1 This is gdb.info, produced by makeinfo version 5.2 from gdb.texinfo.
3 Copyright (C) 1988-2014 Free Software Foundation, Inc.
5 Permission is granted to copy, distribute and/or modify this document
6 under the terms of the GNU Free Documentation License, Version 1.3 or
7 any later version published by the Free Software Foundation; with the
8 Invariant Sections being "Free Software" and "Free Software Needs Free
9 Documentation", with the Front-Cover Texts being "A GNU Manual," and
10 with the Back-Cover Texts as in (a) below.
12 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
13 this GNU Manual. Buying copies from GNU Press supports the FSF in
14 developing GNU and promoting software freedom."
15 INFO-DIR-SECTION Software development
17 * Gdb: (gdb). The GNU debugger.
18 * gdbserver: (gdb) Server. The GNU debugging server.
21 This file documents the GNU debugger GDB.
23 This is the Tenth Edition, of 'Debugging with GDB: the GNU
24 Source-Level Debugger' for GDB (GDB) Version 7.8.1.
26 Copyright (C) 1988-2014 Free Software Foundation, Inc.
28 Permission is granted to copy, distribute and/or modify this document
29 under the terms of the GNU Free Documentation License, Version 1.3 or
30 any later version published by the Free Software Foundation; with the
31 Invariant Sections being "Free Software" and "Free Software Needs Free
32 Documentation", with the Front-Cover Texts being "A GNU Manual," and
33 with the Back-Cover Texts as in (a) below.
35 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
36 this GNU Manual. Buying copies from GNU Press supports the FSF in
37 developing GNU and promoting software freedom."
40 File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol
42 E.3 Stop Reply Packets
43 ======================
45 The 'C', 'c', 'S', 's', 'vCont', 'vAttach', 'vRun', 'vStopped', and '?'
46 packets can receive any of the below as a reply. Except for '?' and
47 'vStopped', that reply is only returned when the target halts. In the
48 below the exact meaning of "signal number" is defined by the header
49 'include/gdb/signals.h' in the GDB source code.
51 As in the description of request packets, we include spaces in the
52 reply templates for clarity; these are not part of the reply packet's
53 syntax. No GDB stop reply packet uses spaces to separate its
57 The program received signal number AA (a two-digit hexadecimal
58 number). This is equivalent to a 'T' response with no N:R pairs.
60 'T AA N1:R1;N2:R2;...'
61 The program received signal number AA (a two-digit hexadecimal
62 number). This is equivalent to an 'S' response, except that the
63 'N:R' pairs can carry values of important registers and other
64 information directly in the stop reply packet, reducing round-trip
65 latency. Single-step and breakpoint traps are reported this way.
66 Each 'N:R' pair is interpreted as follows:
68 * If N is a hexadecimal number, it is a register number, and the
69 corresponding R gives that register's value. The data R is a
70 series of bytes in target byte order, with each byte given by
71 a two-digit hex number.
73 * If N is 'thread', then R is the THREAD-ID of the stopped
74 thread, as specified in *note thread-id syntax::.
76 * If N is 'core', then R is the hexadecimal number of the core
77 on which the stop event was detected.
79 * If N is a recognized "stop reason", it describes a more
80 specific event that stopped the target. The currently defined
81 stop reasons are listed below. The AA should be '05', the
82 trap signal. At most one stop reason should be present.
84 * Otherwise, GDB should ignore this 'N:R' pair and go on to the
85 next; this allows us to extend the protocol in the future.
87 The currently defined stop reasons are:
92 The packet indicates a watchpoint hit, and R is the data
96 The packet indicates that the loaded libraries have changed.
97 GDB should use 'qXfer:libraries:read' to fetch a new list of
98 loaded libraries. The R part is ignored.
101 The packet indicates that the target cannot continue replaying
102 logged execution events, because it has reached the end (or
103 the beginning when executing backward) of the log. The value
104 of R will be either 'begin' or 'end'. *Note Reverse
105 Execution::, for more information.
109 The process exited, and AA is the exit status. This is only
110 applicable to certain targets.
112 The second form of the response, including the process ID of the
113 exited process, can be used only when GDB has reported support for
114 multiprocess protocol extensions; see *note multiprocess
115 extensions::. The PID is formatted as a big-endian hex string.
119 The process terminated with signal AA.
121 The second form of the response, including the process ID of the
122 terminated process, can be used only when GDB has reported support
123 for multiprocess protocol extensions; see *note multiprocess
124 extensions::. The PID is formatted as a big-endian hex string.
127 'XX...' is hex encoding of ASCII data, to be written as the
128 program's console output. This can happen at any time while the
129 program is running and the debugger should continue to wait for
130 'W', 'T', etc. This reply is not permitted in non-stop mode.
132 'F CALL-ID,PARAMETER...'
133 CALL-ID is the identifier which says which host system call should
134 be called. This is just the name of the function. Translation
135 into the correct system call is only applicable as it's defined in
136 GDB. *Note File-I/O Remote Protocol Extension::, for a list of
137 implemented system calls.
139 'PARAMETER...' is a list of parameters as defined for this very
142 The target replies with this packet when it expects GDB to call a
143 host system call on behalf of the target. GDB replies with an
144 appropriate 'F' packet and keeps up waiting for the next reply
145 packet from the target. The latest 'C', 'c', 'S' or 's' action is
146 expected to be continued. *Note File-I/O Remote Protocol
147 Extension::, for more details.
150 File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol
152 E.4 General Query Packets
153 =========================
155 Packets starting with 'q' are "general query packets"; packets starting
156 with 'Q' are "general set packets". General query and set packets are a
157 semi-unified form for retrieving and sending information to and from the
160 The initial letter of a query or set packet is followed by a name
161 indicating what sort of thing the packet applies to. For example, GDB
162 may use a 'qSymbol' packet to exchange symbol definitions with the stub.
163 These packet names follow some conventions:
165 * The name must not contain commas, colons or semicolons.
166 * Most GDB query and set packets have a leading upper case letter.
167 * The names of custom vendor packets should use a company prefix, in
168 lower case, followed by a period. For example, packets designed at
169 the Acme Corporation might begin with 'qacme.foo' (for querying
170 foos) or 'Qacme.bar' (for setting bars).
172 The name of a query or set packet should be separated from any
173 parameters by a ':'; the parameters themselves should be separated by
174 ',' or ';'. Stubs must be careful to match the full packet name, and
175 check for a separator or the end of the packet, in case two packet names
176 share a common prefix. New packets should not begin with 'qC', 'qP', or
179 Like the descriptions of the other packets, each description here has
180 a template showing the packet's overall syntax, followed by an
181 explanation of the packet's meaning. We include spaces in some of the
182 templates for clarity; these are not part of the packet's syntax. No
183 GDB packet uses spaces to separate its components.
185 Here are the currently defined query and set packets:
189 Turn on or off the agent as a helper to perform some debugging
190 operations delegated from GDB (*note Control Agent::).
193 Specify which operations GDB expects to request of the target, as a
194 semicolon-separated list of operation name and value pairs.
195 Possible values for OP include 'WriteReg', 'WriteMem',
196 'InsertBreak', 'InsertTrace', 'InsertFastTrace', and 'Stop'. VAL
197 is either 0, indicating that GDB will not request the operation, or
198 1, indicating that it may. (The target can then use this to set up
199 its own internals optimally, for instance if the debugger never
200 expects to insert breakpoints, it may not need to install its own
204 Return the current thread ID.
208 Where THREAD-ID is a thread ID as documented in *note
211 Any other reply implies the old thread ID.
214 Compute the CRC checksum of a block of memory using CRC-32 defined
215 in IEEE 802.3. The CRC is computed byte at a time, taking the most
216 significant bit of each byte first. The initial pattern code
217 '0xffffffff' is used to ensure leading zeros affect the CRC.
219 _Note:_ This is the same CRC used in validating separate debug
220 files (*note Debugging Information in Separate Files: Separate
221 Debug Files.). However the algorithm is slightly different. When
222 validating separate debug files, the CRC is computed taking the
223 _least_ significant bit of each byte first, and the final result is
224 inverted to detect trailing zeros.
228 An error (such as memory fault)
230 The specified memory region's checksum is CRC32.
232 'QDisableRandomization:VALUE'
233 Some target operating systems will randomize the virtual address
234 space of the inferior process as a security feature, but provide a
235 feature to disable such randomization, e.g. to allow for a more
236 deterministic debugging experience. On such systems, this packet
237 with a VALUE of 1 directs the target to disable address space
238 randomization for processes subsequently started via 'vRun'
239 packets, while a packet with a VALUE of 0 tells the target to
240 enable address space randomization.
242 This packet is only available in extended mode (*note extended
247 The request succeeded.
250 An error occurred. The error number NN is given as hex
254 An empty reply indicates that 'QDisableRandomization' is not
255 supported by the stub.
257 This packet is not probed by default; the remote stub must request
258 it, by supplying an appropriate 'qSupported' response (*note
259 qSupported::). This should only be done on targets that actually
260 support disabling address space randomization.
264 Obtain a list of all active thread IDs from the target (OS). Since
265 there may be too many active threads to fit into one reply packet,
266 this query works iteratively: it may require more than one
267 query/reply sequence to obtain the entire list of threads. The
268 first query of the sequence will be the 'qfThreadInfo' query;
269 subsequent queries in the sequence will be the 'qsThreadInfo'
272 NOTE: This packet replaces the 'qL' query (see below).
277 'm THREAD-ID,THREAD-ID...'
278 a comma-separated list of thread IDs
280 (lower case letter 'L') denotes end of list.
282 In response to each query, the target will reply with a list of one
283 or more thread IDs, separated by commas. GDB will respond to each
284 reply with a request for more thread ids (using the 'qs' form of
285 the query), until the target responds with 'l' (lower-case ell, for
286 "last"). Refer to *note thread-id syntax::, for the format of the
289 _Note: GDB will send the 'qfThreadInfo' query during the initial
290 connection with the remote target, and the very first thread ID
291 mentioned in the reply will be stopped by GDB in a subsequent
292 message. Therefore, the stub should ensure that the first thread
293 ID in the 'qfThreadInfo' reply is suitable for being stopped by
296 'qGetTLSAddr:THREAD-ID,OFFSET,LM'
297 Fetch the address associated with thread local storage specified by
298 THREAD-ID, OFFSET, and LM.
300 THREAD-ID is the thread ID associated with the thread for which to
301 fetch the TLS address. *Note thread-id syntax::.
303 OFFSET is the (big endian, hex encoded) offset associated with the
304 thread local variable. (This offset is obtained from the debug
305 information associated with the variable.)
307 LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
308 load module associated with the thread local storage. For example,
309 a GNU/Linux system will pass the link map address of the shared
310 object associated with the thread local storage under
311 consideration. Other operating environments may choose to
312 represent the load module differently, so the precise meaning of
313 this parameter will vary.
317 Hex encoded (big endian) bytes representing the address of the
318 thread local storage requested.
321 An error occurred. The error number NN is given as hex
325 An empty reply indicates that 'qGetTLSAddr' is not supported
328 'qGetTIBAddr:THREAD-ID'
329 Fetch address of the Windows OS specific Thread Information Block.
331 THREAD-ID is the thread ID associated with the thread.
335 Hex encoded (big endian) bytes representing the linear address
336 of the thread information block.
339 An error occured. This means that either the thread was not
340 found, or the address could not be retrieved.
343 An empty reply indicates that 'qGetTIBAddr' is not supported
346 'qL STARTFLAG THREADCOUNT NEXTTHREAD'
347 Obtain thread information from RTOS. Where: STARTFLAG (one hex
348 digit) is one to indicate the first query and zero to indicate a
349 subsequent query; THREADCOUNT (two hex digits) is the maximum
350 number of threads the response packet can contain; and NEXTTHREAD
351 (eight hex digits), for subsequent queries (STARTFLAG is zero), is
352 returned in the response as ARGTHREAD.
354 Don't use this packet; use the 'qfThreadInfo' query instead (see
358 'qM COUNT DONE ARGTHREAD THREAD...'
359 Where: COUNT (two hex digits) is the number of threads being
360 returned; DONE (one hex digit) is zero to indicate more
361 threads and one indicates no further threads; ARGTHREADID
362 (eight hex digits) is NEXTTHREAD from the request packet;
363 THREAD... is a sequence of thread IDs, THREADID (eight hex
364 digits), from the target. See
365 'remote.c:parse_threadlist_response()'.
368 Get section offsets that the target used when relocating the
372 'Text=XXX;Data=YYY[;Bss=ZZZ]'
373 Relocate the 'Text' section by XXX from its original address.
374 Relocate the 'Data' section by YYY from its original address.
375 If the object file format provides segment information (e.g.
376 ELF 'PT_LOAD' program headers), GDB will relocate entire
377 segments by the supplied offsets.
379 _Note: while a 'Bss' offset may be included in the response,
380 GDB ignores this and instead applies the 'Data' offset to the
383 'TextSeg=XXX[;DataSeg=YYY]'
384 Relocate the first segment of the object file, which
385 conventionally contains program code, to a starting address of
386 XXX. If 'DataSeg' is specified, relocate the second segment,
387 which conventionally contains modifiable data, to a starting
388 address of YYY. GDB will report an error if the object file
389 does not contain segment information, or does not contain at
390 least as many segments as mentioned in the reply. Extra
391 segments are kept at fixed offsets relative to the last
395 Returns information on THREAD-ID. Where: MODE is a hex encoded 32
396 bit mode; THREAD-ID is a thread ID (*note thread-id syntax::).
398 Don't use this packet; use the 'qThreadExtraInfo' query instead
401 Reply: see 'remote.c:remote_unpack_thread_info_response()'.
405 Enter non-stop ('QNonStop:1') or all-stop ('QNonStop:0') mode.
406 *Note Remote Non-Stop::, for more information.
410 The request succeeded.
413 An error occurred. The error number NN is given as hex
417 An empty reply indicates that 'QNonStop' is not supported by
420 This packet is not probed by default; the remote stub must request
421 it, by supplying an appropriate 'qSupported' response (*note
422 qSupported::). Use of this packet is controlled by the 'set
423 non-stop' command; *note Non-Stop Mode::.
425 'QPassSignals: SIGNAL [;SIGNAL]...'
426 Each listed SIGNAL should be passed directly to the inferior
427 process. Signals are numbered identically to continue packets and
428 stop replies (*note Stop Reply Packets::). Each SIGNAL list item
429 should be strictly greater than the previous item. These signals
430 do not need to stop the inferior, or be reported to GDB. All other
431 signals should be reported to GDB. Multiple 'QPassSignals' packets
432 do not combine; any earlier 'QPassSignals' list is completely
433 replaced by the new list. This packet improves performance when
434 using 'handle SIGNAL nostop noprint pass'.
438 The request succeeded.
441 An error occurred. The error number NN is given as hex
445 An empty reply indicates that 'QPassSignals' is not supported
448 Use of this packet is controlled by the 'set remote pass-signals'
449 command (*note set remote pass-signals: Remote Configuration.).
450 This packet is not probed by default; the remote stub must request
451 it, by supplying an appropriate 'qSupported' response (*note
454 'QProgramSignals: SIGNAL [;SIGNAL]...'
455 Each listed SIGNAL may be delivered to the inferior process.
456 Others should be silently discarded.
458 In some cases, the remote stub may need to decide whether to
459 deliver a signal to the program or not without GDB involvement.
460 One example of that is while detaching -- the program's threads may
461 have stopped for signals that haven't yet had a chance of being
462 reported to GDB, and so the remote stub can use the signal list
463 specified by this packet to know whether to deliver or ignore those
466 This does not influence whether to deliver a signal as requested by
467 a resumption packet (*note vCont packet::).
469 Signals are numbered identically to continue packets and stop
470 replies (*note Stop Reply Packets::). Each SIGNAL list item should
471 be strictly greater than the previous item. Multiple
472 'QProgramSignals' packets do not combine; any earlier
473 'QProgramSignals' list is completely replaced by the new list.
477 The request succeeded.
480 An error occurred. The error number NN is given as hex
484 An empty reply indicates that 'QProgramSignals' is not
485 supported by the stub.
487 Use of this packet is controlled by the 'set remote
488 program-signals' command (*note set remote program-signals: Remote
489 Configuration.). This packet is not probed by default; the remote
490 stub must request it, by supplying an appropriate 'qSupported'
491 response (*note qSupported::).
494 COMMAND (hex encoded) is passed to the local interpreter for
495 execution. Invalid commands should be reported using the output
496 string. Before the final result packet, the target may also
497 respond with a number of intermediate 'OOUTPUT' console output
498 packets. _Implementors should note that providing access to a
499 stubs's interpreter may have security implications_.
503 A command response with no output.
505 A command response with the hex encoded output string OUTPUT.
507 Indicate a badly formed request.
509 An empty reply indicates that 'qRcmd' is not recognized.
511 (Note that the 'qRcmd' packet's name is separated from the command
512 by a ',', not a ':', contrary to the naming conventions above.
513 Please don't use this packet as a model for new packets.)
515 'qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN'
516 Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. Both ADDRESS
517 and LENGTH are encoded in hex; SEARCH-PATTERN is a sequence of
518 bytes, also hex encoded.
522 The pattern was not found.
524 The pattern was found at ADDRESS.
526 A badly formed request or an error was encountered while
529 An empty reply indicates that 'qSearch:memory' is not
533 Request that the remote stub disable the normal '+'/'-' protocol
534 acknowledgments (*note Packet Acknowledgment::).
538 The stub has switched to no-acknowledgment mode. GDB
539 acknowledges this reponse, but neither the stub nor GDB shall
540 send or expect further '+'/'-' acknowledgments in the current
543 An empty reply indicates that the stub does not support
544 no-acknowledgment mode.
546 'qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
547 Tell the remote stub about features supported by GDB, and query the
548 stub for features it supports. This packet allows GDB and the
549 remote stub to take advantage of each others' features.
550 'qSupported' also consolidates multiple feature probes at startup,
551 to improve GDB performance--a single larger packet performs better
552 than multiple smaller probe packets on high-latency links. Some
553 features may enable behavior which must not be on by default, e.g.
554 because it would confuse older clients or stubs. Other features
555 may describe packets which could be automatically probed for, but
556 are not. These features must be reported before GDB will use them.
557 This "default unsupported" behavior is not appropriate for all
558 packets, but it helps to keep the initial connection time under
559 control with new versions of GDB which support increasing numbers
563 'STUBFEATURE [;STUBFEATURE]...'
564 The stub supports or does not support each returned
565 STUBFEATURE, depending on the form of each STUBFEATURE (see
566 below for the possible forms).
568 An empty reply indicates that 'qSupported' is not recognized,
569 or that no features needed to be reported to GDB.
571 The allowed forms for each feature (either a GDBFEATURE in the
572 'qSupported' packet, or a STUBFEATURE in the response) are:
575 The remote protocol feature NAME is supported, and associated
576 with the specified VALUE. The format of VALUE depends on the
577 feature, but it must not include a semicolon.
579 The remote protocol feature NAME is supported, and does not
580 need an associated value.
582 The remote protocol feature NAME is not supported.
584 The remote protocol feature NAME may be supported, and GDB
585 should auto-detect support in some other way when it is
586 needed. This form will not be used for GDBFEATURE
587 notifications, but may be used for STUBFEATURE responses.
589 Whenever the stub receives a 'qSupported' request, the supplied set
590 of GDB features should override any previous request. This allows
591 GDB to put the stub in a known state, even if the stub had
592 previously been communicating with a different version of GDB.
594 The following values of GDBFEATURE (for the packet sent by GDB) are
598 This feature indicates whether GDB supports multiprocess
599 extensions to the remote protocol. GDB does not use such
600 extensions unless the stub also reports that it supports them
601 by including 'multiprocess+' in its 'qSupported' reply. *Note
602 multiprocess extensions::, for details.
605 This feature indicates that GDB supports the XML target
606 description. If the stub sees 'xmlRegisters=' with target
607 specific strings separated by a comma, it will report register
611 This feature indicates whether GDB supports the 'qRelocInsn'
612 packet (*note Relocate instruction reply packet: Tracepoint
615 Stubs should ignore any unknown values for GDBFEATURE. Any GDB
616 which sends a 'qSupported' packet supports receiving packets of
617 unlimited length (earlier versions of GDB may reject overly long
618 responses). Additional values for GDBFEATURE may be defined in the
619 future to let the stub take advantage of new features in GDB, e.g.
620 incompatible improvements in the remote protocol--the
621 'multiprocess' feature is an example of such a feature. The stub's
622 reply should be independent of the GDBFEATURE entries sent by GDB;
623 first GDB describes all the features it supports, and then the stub
624 replies with all the features it supports.
626 Similarly, GDB will silently ignore unrecognized stub feature
627 responses, as long as each response uses one of the standard forms.
629 Some features are flags. A stub which supports a flag feature
630 should respond with a '+' form response. Other features require
631 values, and the stub should respond with an '=' form response.
633 Each feature has a default value, which GDB will use if
634 'qSupported' is not available or if the feature is not mentioned in
635 the 'qSupported' response. The default values are fixed; a stub is
636 free to omit any feature responses that match the defaults.
638 Not all features can be probed, but for those which can, the
639 probing mechanism is useful: in some cases, a stub's internal
640 architecture may not allow the protocol layer to know some
641 information about the underlying target in advance. This is
642 especially common in stubs which may be configured for multiple
645 These are the currently defined stub features and their properties:
647 Feature Name Value Default Probe
650 'PacketSize' Yes '-' No
652 'qXfer:auxv:read' No '-' Yes
654 'qXfer:btrace:read' No '-' Yes
656 'qXfer:features:read' No '-' Yes
658 'qXfer:libraries:read' No '-' Yes
660 'qXfer:libraries-svr4:read'No '-' Yes
662 'augmented-libraries-svr4-read'No '-' No
664 'qXfer:memory-map:read' No '-' Yes
666 'qXfer:sdata:read' No '-' Yes
668 'qXfer:spu:read' No '-' Yes
670 'qXfer:spu:write' No '-' Yes
672 'qXfer:siginfo:read' No '-' Yes
674 'qXfer:siginfo:write' No '-' Yes
676 'qXfer:threads:read' No '-' Yes
678 'qXfer:traceframe-info:read'No '-' Yes
680 'qXfer:uib:read' No '-' Yes
682 'qXfer:fdpic:read' No '-' Yes
684 'Qbtrace:off' Yes '-' Yes
686 'Qbtrace:bts' Yes '-' Yes
688 'QNonStop' No '-' Yes
690 'QPassSignals' No '-' Yes
692 'QStartNoAckMode' No '-' Yes
694 'multiprocess' No '-' No
696 'ConditionalBreakpoints' No '-' No
698 'ConditionalTracepoints' No '-' No
700 'ReverseContinue' No '-' No
702 'ReverseStep' No '-' No
704 'TracepointSource' No '-' No
710 'QDisableRandomization' No '-' No
712 'EnableDisableTracepoints'No '-' No
714 'QTBuffer:size' No '-' No
718 'BreakpointCommands' No '-' No
721 These are the currently defined stub features, in more detail:
724 The remote stub can accept packets up to at least BYTES in
725 length. GDB will send packets up to this size for bulk
726 transfers, and will never send larger packets. This is a
727 limit on the data characters in the packet, including the
728 frame and checksum. There is no trailing NUL byte in a remote
729 protocol packet; if the stub stores packets in a
730 NUL-terminated format, it should allow an extra byte in its
731 buffer for the NUL. If this stub feature is not supported, GDB
732 guesses based on the size of the 'g' packet response.
735 The remote stub understands the 'qXfer:auxv:read' packet
736 (*note qXfer auxiliary vector read::).
739 The remote stub understands the 'qXfer:btrace:read' packet
740 (*note qXfer btrace read::).
742 'qXfer:features:read'
743 The remote stub understands the 'qXfer:features:read' packet
744 (*note qXfer target description read::).
746 'qXfer:libraries:read'
747 The remote stub understands the 'qXfer:libraries:read' packet
748 (*note qXfer library list read::).
750 'qXfer:libraries-svr4:read'
751 The remote stub understands the 'qXfer:libraries-svr4:read'
752 packet (*note qXfer svr4 library list read::).
754 'augmented-libraries-svr4-read'
755 The remote stub understands the augmented form of the
756 'qXfer:libraries-svr4:read' packet (*note qXfer svr4 library
759 'qXfer:memory-map:read'
760 The remote stub understands the 'qXfer:memory-map:read' packet
761 (*note qXfer memory map read::).
764 The remote stub understands the 'qXfer:sdata:read' packet
765 (*note qXfer sdata read::).
768 The remote stub understands the 'qXfer:spu:read' packet (*note
772 The remote stub understands the 'qXfer:spu:write' packet
773 (*note qXfer spu write::).
776 The remote stub understands the 'qXfer:siginfo:read' packet
777 (*note qXfer siginfo read::).
779 'qXfer:siginfo:write'
780 The remote stub understands the 'qXfer:siginfo:write' packet
781 (*note qXfer siginfo write::).
784 The remote stub understands the 'qXfer:threads:read' packet
785 (*note qXfer threads read::).
787 'qXfer:traceframe-info:read'
788 The remote stub understands the 'qXfer:traceframe-info:read'
789 packet (*note qXfer traceframe info read::).
792 The remote stub understands the 'qXfer:uib:read' packet (*note
793 qXfer unwind info block::).
796 The remote stub understands the 'qXfer:fdpic:read' packet
797 (*note qXfer fdpic loadmap read::).
800 The remote stub understands the 'QNonStop' packet (*note
804 The remote stub understands the 'QPassSignals' packet (*note
808 The remote stub understands the 'QStartNoAckMode' packet and
809 prefers to operate in no-acknowledgment mode. *Note Packet
813 The remote stub understands the multiprocess extensions to the
814 remote protocol syntax. The multiprocess extensions affect
815 the syntax of thread IDs in both packets and replies (*note
816 thread-id syntax::), and add process IDs to the 'D' packet and
817 'W' and 'X' replies. Note that reporting this feature
818 indicates support for the syntactic extensions only, not that
819 the stub necessarily supports debugging of more than one
820 process at a time. The stub must not use multiprocess
821 extensions in packet replies unless GDB has also indicated it
822 supports them in its 'qSupported' request.
825 The remote stub understands the 'qXfer:osdata:read' packet
826 ((*note qXfer osdata read::).
828 'ConditionalBreakpoints'
829 The target accepts and implements evaluation of conditional
830 expressions defined for breakpoints. The target will only
831 report breakpoint triggers when such conditions are true
832 (*note Break Conditions: Conditions.).
834 'ConditionalTracepoints'
835 The remote stub accepts and implements conditional expressions
836 defined for tracepoints (*note Tracepoint Conditions::).
839 The remote stub accepts and implements the reverse continue
843 The remote stub accepts and implements the reverse step packet
847 The remote stub understands the 'QTDPsrc' packet that supplies
848 the source form of tracepoint definitions.
851 The remote stub understands the 'QAgent' packet.
854 The remote stub understands the 'QAllow' packet.
856 'QDisableRandomization'
857 The remote stub understands the 'QDisableRandomization'
861 The remote stub supports static tracepoints.
864 The remote stub supports installing tracepoint in tracing.
866 'EnableDisableTracepoints'
867 The remote stub supports the 'QTEnable' (*note QTEnable::) and
868 'QTDisable' (*note QTDisable::) packets that allow tracepoints
869 to be enabled and disabled while a trace experiment is
873 The remote stub supports the 'QTBuffer:size' (*note
874 QTBuffer-size::) packet that allows to change the size of the
878 The remote stub supports the 'tracenz' bytecode for collecting
879 strings. See *note Bytecode Descriptions:: for details about
883 The remote stub supports running a breakpoint's command list
884 itself, rather than reporting the hit to GDB.
887 The remote stub understands the 'Qbtrace:off' packet.
890 The remote stub understands the 'Qbtrace:bts' packet.
893 Notify the target that GDB is prepared to serve symbol lookup
894 requests. Accept requests from the target for the values of
899 The target does not need to look up any (more) symbols.
901 The target requests the value of symbol SYM_NAME (hex
902 encoded). GDB may provide the value by using the
903 'qSymbol:SYM_VALUE:SYM_NAME' message, described below.
905 'qSymbol:SYM_VALUE:SYM_NAME'
906 Set the value of SYM_NAME to SYM_VALUE.
908 SYM_NAME (hex encoded) is the name of a symbol whose value the
909 target has previously requested.
911 SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot
912 supply a value for SYM_NAME, then this field will be empty.
916 The target does not need to look up any (more) symbols.
918 The target requests the value of a new symbol SYM_NAME (hex
919 encoded). GDB will continue to supply the values of symbols
920 (if available), until the target ceases to request them.
933 *Note Tracepoint Packets::.
935 'qThreadExtraInfo,THREAD-ID'
936 Obtain from the target OS a printable string description of thread
937 attributes for the thread THREAD-ID; see *note thread-id syntax::,
938 for the forms of THREAD-ID. This string may contain anything that
939 the target OS thinks is interesting for GDB to tell the user about
940 the thread. The string is displayed in GDB's 'info threads'
941 display. Some examples of possible thread extra info strings are
942 'Runnable', or 'Blocked on Mutex'.
946 Where 'XX...' is a hex encoding of ASCII data, comprising the
947 printable string containing the extra information about the
950 (Note that the 'qThreadExtraInfo' packet's name is separated from
951 the command by a ',', not a ':', contrary to the naming conventions
952 above. Please don't use this packet as a model for new packets.)
970 *Note Tracepoint Packets::.
972 'qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
973 Read uninterpreted bytes from the target's special data area
974 identified by the keyword OBJECT. Request LENGTH bytes starting at
975 OFFSET bytes into the data. The content and encoding of ANNEX is
976 specific to OBJECT; it can supply additional details about what
979 Here are the specific requests of this form defined so far. All
980 'qXfer:OBJECT:read:...' requests use the same reply formats, listed
983 'qXfer:auxv:read::OFFSET,LENGTH'
984 Access the target's "auxiliary vector". *Note auxiliary
985 vector: OS Information. Note ANNEX must be empty.
987 This packet is not probed by default; the remote stub must
988 request it, by supplying an appropriate 'qSupported' response
989 (*note qSupported::).
991 'qXfer:btrace:read:ANNEX:OFFSET,LENGTH'
993 Return a description of the current branch trace. *Note
994 Branch Trace Format::. The annex part of the generic 'qXfer'
995 packet may have one of the following values:
998 Returns all available branch trace.
1001 Returns all available branch trace if the branch trace
1002 changed since the last read request.
1005 Returns the new branch trace since the last read request.
1006 Adds a new block to the end of the trace that begins at
1007 zero and ends at the source location of the first branch
1008 in the trace buffer. This extra block is used to stitch
1011 If the trace buffer overflowed, returns an error
1012 indicating the overflow.
1014 This packet is not probed by default; the remote stub must
1015 request it by supplying an appropriate 'qSupported' response
1016 (*note qSupported::).
1018 'qXfer:features:read:ANNEX:OFFSET,LENGTH'
1019 Access the "target description". *Note Target Descriptions::.
1020 The annex specifies which XML document to access. The main
1021 description is always loaded from the 'target.xml' annex.
1023 This packet is not probed by default; the remote stub must
1024 request it, by supplying an appropriate 'qSupported' response
1025 (*note qSupported::).
1027 'qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
1028 Access the target's list of loaded libraries. *Note Library
1029 List Format::. The annex part of the generic 'qXfer' packet
1030 must be empty (*note qXfer read::).
1032 Targets which maintain a list of libraries in the program's
1033 memory do not need to implement this packet; it is designed
1034 for platforms where the operating system manages the list of
1037 This packet is not probed by default; the remote stub must
1038 request it, by supplying an appropriate 'qSupported' response
1039 (*note qSupported::).
1041 'qXfer:libraries-svr4:read:ANNEX:OFFSET,LENGTH'
1042 Access the target's list of loaded libraries when the target
1043 is an SVR4 platform. *Note Library List Format for SVR4
1044 Targets::. The annex part of the generic 'qXfer' packet must
1045 be empty unless the remote stub indicated it supports the
1046 augmented form of this packet by supplying an appropriate
1047 'qSupported' response (*note qXfer read::, *note
1050 This packet is optional for better performance on SVR4
1051 targets. GDB uses memory read packets to read the SVR4
1052 library list otherwise.
1054 This packet is not probed by default; the remote stub must
1055 request it, by supplying an appropriate 'qSupported' response
1056 (*note qSupported::).
1058 If the remote stub indicates it supports the augmented form of
1059 this packet then the annex part of the generic 'qXfer' packet
1060 may contain a semicolon-separated list of 'NAME=VALUE'
1061 arguments. The currently supported arguments are:
1064 A hexadecimal number specifying the address of the
1065 'struct link_map' to start reading the library list from.
1066 If unset or zero then the first 'struct link_map' in the
1067 library list will be chosen as the starting point.
1070 A hexadecimal number specifying the address of the
1071 'struct link_map' immediately preceding the 'struct
1072 link_map' specified by the 'start' argument. If unset or
1073 zero then the remote stub will expect that no 'struct
1074 link_map' exists prior to the starting point.
1076 Arguments that are not understood by the remote stub will be
1079 'qXfer:memory-map:read::OFFSET,LENGTH'
1080 Access the target's "memory-map". *Note Memory Map Format::.
1081 The annex part of the generic 'qXfer' packet must be empty
1082 (*note qXfer read::).
1084 This packet is not probed by default; the remote stub must
1085 request it, by supplying an appropriate 'qSupported' response
1086 (*note qSupported::).
1088 'qXfer:sdata:read::OFFSET,LENGTH'
1090 Read contents of the extra collected static tracepoint marker
1091 information. The annex part of the generic 'qXfer' packet
1092 must be empty (*note qXfer read::). *Note Tracepoint Action
1093 Lists: Tracepoint Actions.
1095 This packet is not probed by default; the remote stub must
1096 request it, by supplying an appropriate 'qSupported' response
1097 (*note qSupported::).
1099 'qXfer:siginfo:read::OFFSET,LENGTH'
1100 Read contents of the extra signal information on the target
1101 system. The annex part of the generic 'qXfer' packet must be
1102 empty (*note qXfer read::).
1104 This packet is not probed by default; the remote stub must
1105 request it, by supplying an appropriate 'qSupported' response
1106 (*note qSupported::).
1108 'qXfer:spu:read:ANNEX:OFFSET,LENGTH'
1109 Read contents of an 'spufs' file on the target system. The
1110 annex specifies which file to read; it must be of the form
1111 'ID/NAME', where ID specifies an SPU context ID in the target
1112 process, and NAME identifes the 'spufs' file in that context
1115 This packet is not probed by default; the remote stub must
1116 request it, by supplying an appropriate 'qSupported' response
1117 (*note qSupported::).
1119 'qXfer:threads:read::OFFSET,LENGTH'
1120 Access the list of threads on target. *Note Thread List
1121 Format::. The annex part of the generic 'qXfer' packet must
1122 be empty (*note qXfer read::).
1124 This packet is not probed by default; the remote stub must
1125 request it, by supplying an appropriate 'qSupported' response
1126 (*note qSupported::).
1128 'qXfer:traceframe-info:read::OFFSET,LENGTH'
1130 Return a description of the current traceframe's contents.
1131 *Note Traceframe Info Format::. The annex part of the generic
1132 'qXfer' packet must be empty (*note qXfer read::).
1134 This packet is not probed by default; the remote stub must
1135 request it, by supplying an appropriate 'qSupported' response
1136 (*note qSupported::).
1138 'qXfer:uib:read:PC:OFFSET,LENGTH'
1140 Return the unwind information block for PC. This packet is
1141 used on OpenVMS/ia64 to ask the kernel unwind information.
1143 This packet is not probed by default.
1145 'qXfer:fdpic:read:ANNEX:OFFSET,LENGTH'
1146 Read contents of 'loadmap's on the target system. The annex,
1147 either 'exec' or 'interp', specifies which 'loadmap',
1148 executable 'loadmap' or interpreter 'loadmap' to read.
1150 This packet is not probed by default; the remote stub must
1151 request it, by supplying an appropriate 'qSupported' response
1152 (*note qSupported::).
1154 'qXfer:osdata:read::OFFSET,LENGTH'
1155 Access the target's "operating system information". *Note
1156 Operating System Information::.
1160 Data DATA (*note Binary Data::) has been read from the target.
1161 There may be more data at a higher address (although it is
1162 permitted to return 'm' even for the last valid block of data,
1163 as long as at least one byte of data was read). It is
1164 possible for DATA to have fewer bytes than the LENGTH in the
1168 Data DATA (*note Binary Data::) has been read from the target.
1169 There is no more data to be read. It is possible for DATA to
1170 have fewer bytes than the LENGTH in the request.
1173 The OFFSET in the request is at the end of the data. There is
1174 no more data to be read.
1177 The request was malformed, or ANNEX was invalid.
1180 The offset was invalid, or there was an error encountered
1181 reading the data. The NN part is a hex-encoded 'errno' value.
1184 An empty reply indicates the OBJECT string was not recognized
1185 by the stub, or that the object does not support reading.
1187 'qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
1188 Write uninterpreted bytes into the target's special data area
1189 identified by the keyword OBJECT, starting at OFFSET bytes into the
1190 data. The binary-encoded data (*note Binary Data::) to be written
1191 is given by DATA.... The content and encoding of ANNEX is specific
1192 to OBJECT; it can supply additional details about what data to
1195 Here are the specific requests of this form defined so far. All
1196 'qXfer:OBJECT:write:...' requests use the same reply formats,
1199 'qXfer:siginfo:write::OFFSET:DATA...'
1200 Write DATA to the extra signal information on the target
1201 system. The annex part of the generic 'qXfer' packet must be
1202 empty (*note qXfer write::).
1204 This packet is not probed by default; the remote stub must
1205 request it, by supplying an appropriate 'qSupported' response
1206 (*note qSupported::).
1208 'qXfer:spu:write:ANNEX:OFFSET:DATA...'
1209 Write DATA to an 'spufs' file on the target system. The annex
1210 specifies which file to write; it must be of the form
1211 'ID/NAME', where ID specifies an SPU context ID in the target
1212 process, and NAME identifes the 'spufs' file in that context
1215 This packet is not probed by default; the remote stub must
1216 request it, by supplying an appropriate 'qSupported' response
1217 (*note qSupported::).
1221 NN (hex encoded) is the number of bytes written. This may be
1222 fewer bytes than supplied in the request.
1225 The request was malformed, or ANNEX was invalid.
1228 The offset was invalid, or there was an error encountered
1229 writing the data. The NN part is a hex-encoded 'errno' value.
1232 An empty reply indicates the OBJECT string was not recognized
1233 by the stub, or that the object does not support writing.
1235 'qXfer:OBJECT:OPERATION:...'
1236 Requests of this form may be added in the future. When a stub does
1237 not recognize the OBJECT keyword, or its support for OBJECT does
1238 not recognize the OPERATION keyword, the stub must respond with an
1242 Return an indication of whether the remote server attached to an
1243 existing process or created a new process. When the multiprocess
1244 protocol extensions are supported (*note multiprocess
1245 extensions::), PID is an integer in hexadecimal format identifying
1246 the target process. Otherwise, GDB will omit the PID field and the
1247 query packet will be simplified as 'qAttached'.
1249 This query is used, for example, to know whether the remote process
1250 should be detached or killed when a GDB session is ended with the
1255 The remote server attached to an existing process.
1257 The remote server created a new process.
1259 A badly formed request or an error was encountered.
1262 Enable branch tracing for the current thread using bts tracing.
1266 Branch tracing has been enabled.
1268 A badly formed request or an error was encountered.
1271 Disable branch tracing for the current thread.
1275 Branch tracing has been disabled.
1277 A badly formed request or an error was encountered.
1279 ---------- Footnotes ----------
1281 (1) The 'qP' and 'qL' packets predate these conventions, and have
1282 arguments without any terminator for the packet name; we suspect they
1283 are in widespread use in places that are difficult to upgrade. The 'qC'
1284 packet has no arguments, but some existing stubs (e.g. RedBoot) are
1285 known to not check for the end of the packet.
1288 File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol
1290 E.5 Architecture-Specific Protocol Details
1291 ==========================================
1293 This section describes how the remote protocol is applied to specific
1294 target architectures. Also see *note Standard Target Features::, for
1295 details of XML target descriptions for each architecture.
1299 * ARM-Specific Protocol Details::
1300 * MIPS-Specific Protocol Details::
1303 File: gdb.info, Node: ARM-Specific Protocol Details, Next: MIPS-Specific Protocol Details, Up: Architecture-Specific Protocol Details
1305 E.5.1 ARM-specific Protocol Details
1306 -----------------------------------
1310 * ARM Breakpoint Kinds::
1313 File: gdb.info, Node: ARM Breakpoint Kinds, Up: ARM-Specific Protocol Details
1315 E.5.1.1 ARM Breakpoint Kinds
1316 ............................
1318 These breakpoint kinds are defined for the 'Z0' and 'Z1' packets.
1321 16-bit Thumb mode breakpoint.
1324 32-bit Thumb mode (Thumb-2) breakpoint.
1327 32-bit ARM mode breakpoint.
1330 File: gdb.info, Node: MIPS-Specific Protocol Details, Prev: ARM-Specific Protocol Details, Up: Architecture-Specific Protocol Details
1332 E.5.2 MIPS-specific Protocol Details
1333 ------------------------------------
1337 * MIPS Register packet Format::
1338 * MIPS Breakpoint Kinds::
1341 File: gdb.info, Node: MIPS Register packet Format, Next: MIPS Breakpoint Kinds, Up: MIPS-Specific Protocol Details
1343 E.5.2.1 MIPS Register Packet Format
1344 ...................................
1346 The following 'g'/'G' packets have previously been defined. In the
1347 below, some thirty-two bit registers are transferred as sixty-four bits.
1348 Those registers should be zero/sign extended (which?) to fill the space
1349 allocated. Register bytes are transferred in target byte order. The
1350 two nibbles within a register byte are transferred most-significant -
1354 All registers are transferred as thirty-two bit quantities in the
1355 order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
1356 floating-point registers; fsr; fir; fp.
1359 All registers are transferred as sixty-four bit quantities
1360 (including thirty-two bit registers such as 'sr'). The ordering is
1361 the same as 'MIPS32'.
1364 File: gdb.info, Node: MIPS Breakpoint Kinds, Prev: MIPS Register packet Format, Up: MIPS-Specific Protocol Details
1366 E.5.2.2 MIPS Breakpoint Kinds
1367 .............................
1369 These breakpoint kinds are defined for the 'Z0' and 'Z1' packets.
1372 16-bit MIPS16 mode breakpoint.
1375 16-bit microMIPS mode breakpoint.
1378 32-bit standard MIPS mode breakpoint.
1381 32-bit microMIPS mode breakpoint.
1384 File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol
1386 E.6 Tracepoint Packets
1387 ======================
1389 Here we describe the packets GDB uses to implement tracepoints (*note
1392 'QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]'
1393 Create a new tracepoint, number N, at ADDR. If ENA is 'E', then
1394 the tracepoint is enabled; if it is 'D', then the tracepoint is
1395 disabled. The STEP gives the tracepoint's step count, and PASS
1396 gives its pass count. If an 'F' is present, then the tracepoint is
1397 to be a fast tracepoint, and the FLEN is the number of bytes that
1398 the target should copy elsewhere to make room for the tracepoint.
1399 If an 'X' is present, it introduces a tracepoint condition, which
1400 consists of a hexadecimal length, followed by a comma and
1401 hex-encoded bytes, in a manner similar to action encodings as
1402 described below. If the trailing '-' is present, further 'QTDP'
1403 packets will follow to specify this tracepoint's actions.
1407 The packet was understood and carried out.
1409 *Note Relocate instruction reply packet: Tracepoint Packets.
1411 The packet was not recognized.
1413 'QTDP:-N:ADDR:[S]ACTION...[-]'
1414 Define actions to be taken when a tracepoint is hit. The N and
1415 ADDR must be the same as in the initial 'QTDP' packet for this
1416 tracepoint. This packet may only be sent immediately after another
1417 'QTDP' packet that ended with a '-'. If the trailing '-' is
1418 present, further 'QTDP' packets will follow, specifying more
1419 actions for this tracepoint.
1421 In the series of action packets for a given tracepoint, at most one
1422 can have an 'S' before its first ACTION. If such a packet is sent,
1423 it and the following packets define "while-stepping" actions. Any
1424 prior packets define ordinary actions -- that is, those taken when
1425 the tracepoint is first hit. If no action packet has an 'S', then
1426 all the packets in the series specify ordinary tracepoint actions.
1428 The 'ACTION...' portion of the packet is a series of actions,
1429 concatenated without separators. Each action has one of the
1433 Collect the registers whose bits are set in MASK, a
1434 hexadecimal number whose I'th bit is set if register number I
1435 should be collected. (The least significant bit is numbered
1436 zero.) Note that MASK may be any number of digits long; it
1437 may not fit in a 32-bit word.
1439 'M BASEREG,OFFSET,LEN'
1440 Collect LEN bytes of memory starting at the address in
1441 register number BASEREG, plus OFFSET. If BASEREG is '-1',
1442 then the range has a fixed address: OFFSET is the address of
1443 the lowest byte to collect. The BASEREG, OFFSET, and LEN
1444 parameters are all unsigned hexadecimal values (the '-1' value
1445 for BASEREG is a special case).
1448 Evaluate EXPR, whose length is LEN, and collect memory as it
1449 directs. The agent expression EXPR is as described in *note
1450 Agent Expressions::. Each byte of the expression is encoded
1451 as a two-digit hex number in the packet; LEN is the number of
1452 bytes in the expression (and thus one-half the number of hex
1453 digits in the packet).
1455 Any number of actions may be packed together in a single 'QTDP'
1456 packet, as long as the packet does not exceed the maximum packet
1457 length (400 bytes, for many stubs). There may be only one 'R'
1458 action per tracepoint, and it must precede any 'M' or 'X' actions.
1459 Any registers referred to by 'M' and 'X' actions must be collected
1460 by a preceding 'R' action. (The "while-stepping" actions are
1461 treated as if they were attached to a separate tracepoint, as far
1462 as these restrictions are concerned.)
1466 The packet was understood and carried out.
1468 *Note Relocate instruction reply packet: Tracepoint Packets.
1470 The packet was not recognized.
1472 'QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES'
1473 Specify a source string of tracepoint N at address ADDR. This is
1474 useful to get accurate reproduction of the tracepoints originally
1475 downloaded at the beginning of the trace run. The TYPE is the name
1476 of the tracepoint part, such as 'cond' for the tracepoint's
1477 conditional expression (see below for a list of types), while BYTES
1478 is the string, encoded in hexadecimal.
1480 START is the offset of the BYTES within the overall source string,
1481 while SLEN is the total length of the source string. This is
1482 intended for handling source strings that are longer than will fit
1485 The available string types are 'at' for the location, 'cond' for
1486 the conditional, and 'cmd' for an action command. GDB sends a
1487 separate packet for each command in the action list, in the same
1488 order in which the commands are stored in the list.
1490 The target does not need to do anything with source strings except
1491 report them back as part of the replies to the 'qTfP'/'qTsP' query
1494 Although this packet is optional, and GDB will only send it if the
1495 target replies with 'TracepointSource' *Note General Query
1496 Packets::, it makes both disconnected tracing and trace files much
1497 easier to use. Otherwise the user must be careful that the
1498 tracepoints in effect while looking at trace frames are identical
1499 to the ones in effect during the trace run; even a small
1500 discrepancy could cause 'tdump' not to work, or a particular trace
1504 Create a new trace state variable, number N, with an initial value
1505 of VALUE, which is a 64-bit signed integer. Both N and VALUE are
1506 encoded as hexadecimal values. GDB has the option of not using
1507 this packet for initial values of zero; the target should simply
1508 create the trace state variables as they are mentioned in
1512 Select the N'th tracepoint frame from the buffer, and use the
1513 register and memory contents recorded there to answer subsequent
1514 request packets from GDB.
1516 A successful reply from the stub indicates that the stub has found
1517 the requested frame. The response is a series of parts,
1518 concatenated without separators, describing the frame we selected.
1519 Each part has one of the following forms:
1522 The selected frame is number N in the trace frame buffer; F is
1523 a hexadecimal number. If F is '-1', then there was no frame
1524 matching the criteria in the request packet.
1527 The selected trace frame records a hit of tracepoint number T;
1528 T is a hexadecimal number.
1531 Like 'QTFrame:N', but select the first tracepoint frame after the
1532 currently selected frame whose PC is ADDR; ADDR is a hexadecimal
1536 Like 'QTFrame:N', but select the first tracepoint frame after the
1537 currently selected frame that is a hit of tracepoint T; T is a
1540 'QTFrame:range:START:END'
1541 Like 'QTFrame:N', but select the first tracepoint frame after the
1542 currently selected frame whose PC is between START (inclusive) and
1543 END (inclusive); START and END are hexadecimal numbers.
1545 'QTFrame:outside:START:END'
1546 Like 'QTFrame:range:START:END', but select the first frame
1547 _outside_ the given range of addresses (exclusive).
1550 This packet requests the minimum length of instruction at which a
1551 fast tracepoint (*note Set Tracepoints::) may be placed. For
1552 instance, on the 32-bit x86 architecture, it is possible to use a
1553 4-byte jump, but it depends on the target system being able to
1554 create trampolines in the first 64K of memory, which might or might
1555 not be possible for that system. So the reply to this packet will
1556 be 4 if it is able to arrange for that.
1561 The minimum instruction length is currently unknown.
1563 The minimum instruction length is LENGTH, where LENGTH is a
1564 hexadecimal number greater or equal to 1. A reply of 1 means
1565 that a fast tracepoint may be placed on any instruction
1568 An error has occurred.
1570 An empty reply indicates that the request is not supported by
1574 Begin the tracepoint experiment. Begin collecting data from
1575 tracepoint hits in the trace frame buffer. This packet supports
1576 the 'qRelocInsn' reply (*note Relocate instruction reply packet:
1577 Tracepoint Packets.).
1580 End the tracepoint experiment. Stop collecting trace frames.
1583 Enable tracepoint N at address ADDR in a started tracepoint
1584 experiment. If the tracepoint was previously disabled, then
1585 collection of data from it will resume.
1588 Disable tracepoint N at address ADDR in a started tracepoint
1589 experiment. No more data will be collected from the tracepoint
1590 unless 'QTEnable:N:ADDR' is subsequently issued.
1593 Clear the table of tracepoints, and empty the trace frame buffer.
1595 'QTro:START1,END1:START2,END2:...'
1596 Establish the given ranges of memory as "transparent". The stub
1597 will answer requests for these ranges from memory's current
1598 contents, if they were not collected as part of the tracepoint hit.
1600 GDB uses this to mark read-only regions of memory, like those
1601 containing program code. Since these areas never change, they
1602 should still have the same contents they did when the tracepoint
1603 was hit, so there's no reason for the stub to refuse to provide
1606 'QTDisconnected:VALUE'
1607 Set the choice to what to do with the tracing run when GDB
1608 disconnects from the target. A VALUE of 1 directs the target to
1609 continue the tracing run, while 0 tells the target to stop tracing
1610 if GDB is no longer in the picture.
1613 Ask the stub if there is a trace experiment running right now.
1615 The reply has the form:
1617 'TRUNNING[;FIELD]...'
1618 RUNNING is a single digit '1' if the trace is presently
1619 running, or '0' if not. It is followed by semicolon-separated
1620 optional fields that an agent may use to report additional
1623 If the trace is not running, the agent may report any of several
1624 explanations as one of the optional fields:
1627 No trace has been run yet.
1630 The trace was stopped by a user-originated stop command. The
1631 optional TEXT field is a user-supplied string supplied as part
1632 of the stop command (for instance, an explanation of why the
1633 trace was stopped manually). It is hex-encoded.
1636 The trace stopped because the trace buffer filled up.
1639 The trace stopped because GDB disconnected from the target.
1642 The trace stopped because tracepoint TPNUM exceeded its pass
1646 The trace stopped because tracepoint TPNUM had an error. The
1647 string TEXT is available to describe the nature of the error
1648 (for instance, a divide by zero in the condition expression);
1652 The trace stopped for some other reason.
1654 Additional optional fields supply statistical and other
1655 information. Although not required, they are extremely useful for
1656 users monitoring the progress of a trace run. If a trace has
1657 stopped, and these numbers are reported, they must reflect the
1658 state of the just-stopped trace.
1661 The number of trace frames in the buffer.
1664 The total number of trace frames created during the run. This
1665 may be larger than the trace frame count, if the buffer is
1669 The total size of the trace buffer, in bytes.
1672 The number of bytes still unused in the buffer.
1675 The value of the circular trace buffer flag. '1' means that
1676 the trace buffer is circular and old trace frames will be
1677 discarded if necessary to make room, '0' means that the trace
1678 buffer is linear and may fill up.
1681 The value of the disconnected tracing flag. '1' means that
1682 tracing will continue after GDB disconnects, '0' means that
1683 the trace run will stop.
1686 Ask the stub for the current state of tracepoint number TP at
1691 The tracepoint has been hit HITS times so far during the trace
1692 run, and accounts for USAGE in the trace buffer. Note that
1693 'while-stepping' steps are not counted as separate hits, but
1694 the steps' space consumption is added into the usage number.
1697 Ask the stub for the value of the trace state variable number VAR.
1701 The value of the variable is VALUE. This will be the current
1702 value of the variable if the user is examining a running
1703 target, or a saved value if the variable was collected in the
1704 trace frame that the user is looking at. Note that multiple
1705 requests may result in different reply values, such as when
1706 requesting values while the program is running.
1709 The value of the variable is unknown. This would occur, for
1710 example, if the user is examining a trace frame in which the
1711 requested variable was not collected.
1715 These packets request data about tracepoints that are being used by
1716 the target. GDB sends 'qTfP' to get the first piece of data, and
1717 multiple 'qTsP' to get additional pieces. Replies to these packets
1718 generally take the form of the 'QTDP' packets that define
1719 tracepoints. (FIXME add detailed syntax)
1723 These packets request data about trace state variables that are on
1724 the target. GDB sends 'qTfV' to get the first vari of data, and
1725 multiple 'qTsV' to get additional variables. Replies to these
1726 packets follow the syntax of the 'QTDV' packets that define trace
1731 These packets request data about static tracepoint markers that
1732 exist in the target program. GDB sends 'qTfSTM' to get the first
1733 piece of data, and multiple 'qTsSTM' to get additional pieces.
1734 Replies to these packets take the following form:
1737 'm ADDRESS:ID:EXTRA'
1739 'm ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...'
1740 a comma-separated list of markers
1742 (lower case letter 'L') denotes end of list.
1744 An error occurred. The error number NN is given as hex
1747 An empty reply indicates that the request is not supported by
1750 The ADDRESS is encoded in hex; ID and EXTRA are strings encoded in
1753 In response to each query, the target will reply with a list of one
1754 or more markers, separated by commas. GDB will respond to each
1755 reply with a request for more markers (using the 'qs' form of the
1756 query), until the target responds with 'l' (lower-case ell, for
1760 This packets requests data about static tracepoint markers in the
1761 target program at ADDRESS. Replies to this packet follow the
1762 syntax of the 'qTfSTM' and 'qTsSTM' packets that list static
1766 This packet directs the target to save trace data to the file name
1767 FILENAME in the target's filesystem. The FILENAME is encoded as a
1768 hex string; the interpretation of the file name (relative vs
1769 absolute, wild cards, etc) is up to the target.
1771 'qTBuffer:OFFSET,LEN'
1772 Return up to LEN bytes of the current contents of trace buffer,
1773 starting at OFFSET. The trace buffer is treated as if it were a
1774 contiguous collection of traceframes, as per the trace file format.
1775 The reply consists as many hex-encoded bytes as the target can
1776 deliver in a packet; it is not an error to return fewer than were
1777 asked for. A reply consisting of just 'l' indicates that no bytes
1780 'QTBuffer:circular:VALUE'
1781 This packet directs the target to use a circular trace buffer if
1782 VALUE is 1, or a linear buffer if the value is 0.
1784 'QTBuffer:size:SIZE'
1785 This packet directs the target to make the trace buffer be of size
1786 SIZE if possible. A value of '-1' tells the target to use whatever
1789 'QTNotes:[TYPE:TEXT][;TYPE:TEXT]...'
1790 This packet adds optional textual notes to the trace run.
1791 Allowable types include 'user', 'notes', and 'tstop', the TEXT
1792 fields are arbitrary strings, hex-encoded.
1794 E.6.1 Relocate instruction reply packet
1795 ---------------------------------------
1797 When installing fast tracepoints in memory, the target may need to
1798 relocate the instruction currently at the tracepoint address to a
1799 different address in memory. For most instructions, a simple copy is
1800 enough, but, for example, call instructions that implicitly push the
1801 return address on the stack, and relative branches or other PC-relative
1802 instructions require offset adjustment, so that the effect of executing
1803 the instruction at a different address is the same as if it had executed
1804 in the original location.
1806 In response to several of the tracepoint packets, the target may also
1807 respond with a number of intermediate 'qRelocInsn' request packets
1808 before the final result packet, to have GDB handle this relocation
1809 operation. If a packet supports this mechanism, its documentation will
1810 explicitly say so. See for example the above descriptions for the
1811 'QTStart' and 'QTDP' packets. The format of the request is:
1813 'qRelocInsn:FROM;TO'
1815 This requests GDB to copy instruction at address FROM to address
1816 TO, possibly adjusted so that executing the instruction at TO has
1817 the same effect as executing it at FROM. GDB writes the adjusted
1818 instruction to target memory starting at TO.
1821 'qRelocInsn:ADJUSTED_SIZE'
1822 Informs the stub the relocation is complete. The ADJUSTED_SIZE is
1823 the length in bytes of resulting relocated instruction sequence.
1825 A badly formed request was detected, or an error was encountered
1826 while relocating the instruction.
1829 File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol
1831 E.7 Host I/O Packets
1832 ====================
1834 The "Host I/O" packets allow GDB to perform I/O operations on the far
1835 side of a remote link. For example, Host I/O is used to upload and
1836 download files to a remote target with its own filesystem. Host I/O
1837 uses the same constant values and data structure layout as the
1838 target-initiated File-I/O protocol. However, the Host I/O packets are
1839 structured differently. The target-initiated protocol relies on target
1840 memory to store parameters and buffers. Host I/O requests are initiated
1841 by GDB, and the target's memory is not involved. *Note File-I/O Remote
1842 Protocol Extension::, for more details on the target-initiated protocol.
1844 The Host I/O request packets all encode a single operation along with
1845 its arguments. They have this format:
1847 'vFile:OPERATION: PARAMETER...'
1848 OPERATION is the name of the particular request; the target should
1849 compare the entire packet name up to the second colon when checking
1850 for a supported operation. The format of PARAMETER depends on the
1851 operation. Numbers are always passed in hexadecimal. Negative
1852 numbers have an explicit minus sign (i.e. two's complement is not
1853 used). Strings (e.g. filenames) are encoded as a series of
1854 hexadecimal bytes. The last argument to a system call may be a
1855 buffer of escaped binary data (*note Binary Data::).
1857 The valid responses to Host I/O packets are:
1859 'F RESULT [, ERRNO] [; ATTACHMENT]'
1860 RESULT is the integer value returned by this operation, usually
1861 non-negative for success and -1 for errors. If an error has
1862 occured, ERRNO will be included in the result specifying a value
1863 defined by the File-I/O protocol (*note Errno Values::). For
1864 operations which return data, ATTACHMENT supplies the data as a
1865 binary buffer. Binary buffers in response packets are escaped in
1866 the normal way (*note Binary Data::). See the individual packet
1867 documentation for the interpretation of RESULT and ATTACHMENT.
1870 An empty response indicates that this operation is not recognized.
1872 These are the supported Host I/O operations:
1874 'vFile:open: FILENAME, FLAGS, MODE'
1875 Open a file at FILENAME and return a file descriptor for it, or
1876 return -1 if an error occurs. The FILENAME is a string, FLAGS is
1877 an integer indicating a mask of open flags (*note Open Flags::),
1878 and MODE is an integer indicating a mask of mode bits to use if the
1879 file is created (*note mode_t Values::). *Note open::, for details
1880 of the open flags and mode values.
1883 Close the open file corresponding to FD and return 0, or -1 if an
1886 'vFile:pread: FD, COUNT, OFFSET'
1887 Read data from the open file corresponding to FD. Up to COUNT
1888 bytes will be read from the file, starting at OFFSET relative to
1889 the start of the file. The target may read fewer bytes; common
1890 reasons include packet size limits and an end-of-file condition.
1891 The number of bytes read is returned. Zero should only be returned
1892 for a successful read at the end of the file, or if COUNT was zero.
1894 The data read should be returned as a binary attachment on success.
1895 If zero bytes were read, the response should include an empty
1896 binary attachment (i.e. a trailing semicolon). The return value is
1897 the number of target bytes read; the binary attachment may be
1898 longer if some characters were escaped.
1900 'vFile:pwrite: FD, OFFSET, DATA'
1901 Write DATA (a binary buffer) to the open file corresponding to FD.
1902 Start the write at OFFSET from the start of the file. Unlike many
1903 'write' system calls, there is no separate COUNT argument; the
1904 length of DATA in the packet is used. 'vFile:write' returns the
1905 number of bytes written, which may be shorter than the length of
1906 DATA, or -1 if an error occurred.
1908 'vFile:unlink: FILENAME'
1909 Delete the file at FILENAME on the target. Return 0, or -1 if an
1910 error occurs. The FILENAME is a string.
1912 'vFile:readlink: FILENAME'
1913 Read value of symbolic link FILENAME on the target. Return the
1914 number of bytes read, or -1 if an error occurs.
1916 The data read should be returned as a binary attachment on success.
1917 If zero bytes were read, the response should include an empty
1918 binary attachment (i.e. a trailing semicolon). The return value is
1919 the number of target bytes read; the binary attachment may be
1920 longer if some characters were escaped.
1923 File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol
1928 When a program on the remote target is running, GDB may attempt to
1929 interrupt it by sending a 'Ctrl-C', 'BREAK' or a 'BREAK' followed by
1930 'g', control of which is specified via GDB's 'interrupt-sequence'.
1932 The precise meaning of 'BREAK' is defined by the transport mechanism
1933 and may, in fact, be undefined. GDB does not currently define a 'BREAK'
1934 mechanism for any of the network interfaces except for TCP, in which
1935 case GDB sends the 'telnet' BREAK sequence.
1937 'Ctrl-C', on the other hand, is defined and implemented for all
1938 transport mechanisms. It is represented by sending the single byte
1939 '0x03' without any of the usual packet overhead described in the
1940 Overview section (*note Overview::). When a '0x03' byte is transmitted
1941 as part of a packet, it is considered to be packet data and does _not_
1942 represent an interrupt. E.g., an 'X' packet (*note X packet::), used
1943 for binary downloads, may include an unescaped '0x03' as part of its
1946 'BREAK' followed by 'g' is also known as Magic SysRq g. When Linux
1947 kernel receives this sequence from serial port, it stops execution and
1950 Stubs are not required to recognize these interrupt mechanisms and
1951 the precise meaning associated with receipt of the interrupt is
1952 implementation defined. If the target supports debugging of multiple
1953 threads and/or processes, it should attempt to interrupt all
1954 currently-executing threads and processes. If the stub is successful at
1955 interrupting the running program, it should send one of the stop reply
1956 packets (*note Stop Reply Packets::) to GDB as a result of successfully
1957 stopping the program in all-stop mode, and a stop reply for each stopped
1958 thread in non-stop mode. Interrupts received while the program is
1959 stopped are discarded.
1962 File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol
1964 E.9 Notification Packets
1965 ========================
1967 The GDB remote serial protocol includes "notifications", packets that
1968 require no acknowledgment. Both the GDB and the stub may send
1969 notifications (although the only notifications defined at present are
1970 sent by the stub). Notifications carry information without incurring
1971 the round-trip latency of an acknowledgment, and so are useful for
1972 low-impact communications where occasional packet loss is not a problem.
1974 A notification packet has the form '% DATA # CHECKSUM', where DATA is
1975 the content of the notification, and CHECKSUM is a checksum of DATA,
1976 computed and formatted as for ordinary GDB packets. A notification's
1977 DATA never contains '$', '%' or '#' characters. Upon receiving a
1978 notification, the recipient sends no '+' or '-' to acknowledge the
1979 notification's receipt or to report its corruption.
1981 Every notification's DATA begins with a name, which contains no colon
1982 characters, followed by a colon character.
1984 Recipients should silently ignore corrupted notifications and
1985 notifications they do not understand. Recipients should restart timeout
1986 periods on receipt of a well-formed notification, whether or not they
1989 Senders should only send the notifications described here when this
1990 protocol description specifies that they are permitted. In the future,
1991 we may extend the protocol to permit existing notifications in new
1992 contexts; this rule helps older senders avoid confusing newer
1995 (Older versions of GDB ignore bytes received until they see the '$'
1996 byte that begins an ordinary packet, so new stubs may transmit
1997 notifications without fear of confusing older clients. There are no
1998 notifications defined for GDB to send at the moment, but we assume that
1999 most older stubs would ignore them, as well.)
2001 Each notification is comprised of three parts:
2003 The notification packet is sent by the side that initiates the
2004 exchange (currently, only the stub does that), with EVENT carrying
2005 the specific information about the notification, and NAME
2006 specifying the name of the notification.
2008 The acknowledge sent by the other side, usually GDB, to acknowledge
2009 the exchange and request the event.
2011 The purpose of an asynchronous notification mechanism is to report to
2012 GDB that something interesting happened in the remote stub.
2014 The remote stub may send notification NAME:EVENT at any time, but GDB
2015 acknowledges the notification when appropriate. The notification event
2016 is pending before GDB acknowledges. Only one notification at a time may
2017 be pending; if additional events occur before GDB has acknowledged the
2018 previous notification, they must be queued by the stub for later
2019 synchronous transmission in response to ACK packets from GDB. Because
2020 the notification mechanism is unreliable, the stub is permitted to
2021 resend a notification if it believes GDB may not have received it.
2023 Specifically, notifications may appear when GDB is not otherwise
2024 reading input from the stub, or when GDB is expecting to read a normal
2025 synchronous response or a '+'/'-' acknowledgment to a packet it has
2026 sent. Notification packets are distinct from any other communication
2027 from the stub so there is no ambiguity.
2029 After receiving a notification, GDB shall acknowledge it by sending a
2030 ACK packet as a regular, synchronous request to the stub. Such
2031 acknowledgment is not required to happen immediately, as GDB is
2032 permitted to send other, unrelated packets to the stub first, which the
2033 stub should process normally.
2035 Upon receiving a ACK packet, if the stub has other queued events to
2036 report to GDB, it shall respond by sending a normal EVENT. GDB shall
2037 then send another ACK packet to solicit further responses; again, it is
2038 permitted to send other, unrelated packets as well which the stub should
2041 If the stub receives a ACK packet and there are no additional EVENT
2042 to report, the stub shall return an 'OK' response. At this point, GDB
2043 has finished processing a notification and the stub has completed
2044 sending any queued events. GDB won't accept any new notifications until
2045 the final 'OK' is received . If further notification events occur, the
2046 stub shall send a new notification, GDB shall accept the notification,
2047 and the process shall be repeated.
2049 The process of asynchronous notification can be illustrated by the
2051 <- %%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;
2054 <- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;
2056 <- T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;
2060 The following notifications are defined:
2062 NotificationAck Event Description
2064 Stop vStopped REPLY. The REPLY has the Report an asynchronous
2065 form of a stop reply, as stop event in non-stop
2066 described in *note Stop mode.
2067 Reply Packets::. Refer
2070 information on how these
2072 acknowledged by GDB.
2075 File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol
2077 E.10 Remote Protocol Support for Non-Stop Mode
2078 ==============================================
2080 GDB's remote protocol supports non-stop debugging of multi-threaded
2081 programs, as described in *note Non-Stop Mode::. If the stub supports
2082 non-stop mode, it should report that to GDB by including 'QNonStop+' in
2083 its 'qSupported' response (*note qSupported::).
2085 GDB typically sends a 'QNonStop' packet only when establishing a new
2086 connection with the stub. Entering non-stop mode does not alter the
2087 state of any currently-running threads, but targets must stop all
2088 threads in any already-attached processes when entering all-stop mode.
2089 GDB uses the '?' packet as necessary to probe the target state after a
2092 In non-stop mode, when an attached process encounters an event that
2093 would otherwise be reported with a stop reply, it uses the asynchronous
2094 notification mechanism (*note Notification Packets::) to inform GDB. In
2095 contrast to all-stop mode, where all threads in all processes are
2096 stopped when a stop reply is sent, in non-stop mode only the thread
2097 reporting the stop event is stopped. That is, when reporting a 'S' or
2098 'T' response to indicate completion of a step operation, hitting a
2099 breakpoint, or a fault, only the affected thread is stopped; any other
2100 still-running threads continue to run. When reporting a 'W' or 'X'
2101 response, all running threads belonging to other attached processes
2104 In non-stop mode, the target shall respond to the '?' packet as
2105 follows. First, any incomplete stop reply notification/'vStopped'
2106 sequence in progress is abandoned. The target must begin a new sequence
2107 reporting stop events for all stopped threads, whether or not it has
2108 previously reported those events to GDB. The first stop reply is sent
2109 as a synchronous reply to the '?' packet, and subsequent stop replies
2110 are sent as responses to 'vStopped' packets using the mechanism
2111 described above. The target must not send asynchronous stop reply
2112 notifications until the sequence is complete. If all threads are
2113 running when the target receives the '?' packet, or if the target is not
2114 attached to any process, it shall respond 'OK'.
2117 File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol
2119 E.11 Packet Acknowledgment
2120 ==========================
2122 By default, when either the host or the target machine receives a
2123 packet, the first response expected is an acknowledgment: either '+' (to
2124 indicate the package was received correctly) or '-' (to request
2125 retransmission). This mechanism allows the GDB remote protocol to
2126 operate over unreliable transport mechanisms, such as a serial line.
2128 In cases where the transport mechanism is itself reliable (such as a
2129 pipe or TCP connection), the '+'/'-' acknowledgments are redundant. It
2130 may be desirable to disable them in that case to reduce communication
2131 overhead, or for other reasons. This can be accomplished by means of
2132 the 'QStartNoAckMode' packet; *note QStartNoAckMode::.
2134 When in no-acknowledgment mode, neither the stub nor GDB shall send
2135 or expect '+'/'-' protocol acknowledgments. The packet and response
2136 format still includes the normal checksum, as described in *note
2137 Overview::, but the checksum may be ignored by the receiver.
2139 If the stub supports 'QStartNoAckMode' and prefers to operate in
2140 no-acknowledgment mode, it should report that to GDB by including
2141 'QStartNoAckMode+' in its response to 'qSupported'; *note qSupported::.
2142 If GDB also supports 'QStartNoAckMode' and it has not been disabled via
2143 the 'set remote noack-packet off' command (*note Remote
2144 Configuration::), GDB may then send a 'QStartNoAckMode' packet to the
2145 stub. Only then may the stub actually turn off packet acknowledgments.
2146 GDB sends a final '+' acknowledgment of the stub's 'OK' response, which
2147 can be safely ignored by the stub.
2149 Note that 'set remote noack-packet' command only affects negotiation
2150 between GDB and the stub when subsequent connections are made; it does
2151 not affect the protocol acknowledgment state for any current connection.
2152 Since '+'/'-' acknowledgments are enabled by default when a new
2153 connection is established, there is also no protocol request to
2154 re-enable the acknowledgments for the current connection, once disabled.
2157 File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol
2162 Example sequence of a target being re-started. Notice how the restart
2163 does not get any direct output:
2170 <- T001:1234123412341234
2173 Example sequence of a target being stepped by a single instruction:
2180 <- T001:1234123412341234
2188 File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol
2190 E.13 File-I/O Remote Protocol Extension
2191 =======================================
2195 * File-I/O Overview::
2197 * The F Request Packet::
2198 * The F Reply Packet::
2199 * The Ctrl-C Message::
2201 * List of Supported Calls::
2202 * Protocol-specific Representation of Datatypes::
2204 * File-I/O Examples::
2207 File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension
2209 E.13.1 File-I/O Overview
2210 ------------------------
2212 The "File I/O remote protocol extension" (short: File-I/O) allows the
2213 target to use the host's file system and console I/O to perform various
2214 system calls. System calls on the target system are translated into a
2215 remote protocol packet to the host system, which then performs the
2216 needed actions and returns a response packet to the target system. This
2217 simulates file system operations even on targets that lack file systems.
2219 The protocol is defined to be independent of both the host and target
2220 systems. It uses its own internal representation of datatypes and
2221 values. Both GDB and the target's GDB stub are responsible for
2222 translating the system-dependent value representations into the internal
2223 protocol representations when data is transmitted.
2225 The communication is synchronous. A system call is possible only
2226 when GDB is waiting for a response from the 'C', 'c', 'S' or 's'
2227 packets. While GDB handles the request for a system call, the target is
2228 stopped to allow deterministic access to the target's memory. Therefore
2229 File-I/O is not interruptible by target signals. On the other hand, it
2230 is possible to interrupt File-I/O by a user interrupt ('Ctrl-C') within
2233 The target's request to perform a host system call does not finish
2234 the latest 'C', 'c', 'S' or 's' action. That means, after finishing the
2235 system call, the target returns to continuing the previous activity
2236 (continue, step). No additional continue or step request from GDB is
2240 <- target requests 'system call X'
2241 target is stopped, GDB executes system call
2242 -> GDB returns result
2243 ... target continues, GDB returns to wait for the target
2244 <- target hits breakpoint and sends a Txx packet
2246 The protocol only supports I/O on the console and to regular files on
2247 the host file system. Character or block special devices, pipes, named
2248 pipes, sockets or any other communication method on the host system are
2249 not supported by this protocol.
2251 File I/O is not supported in non-stop mode.
2254 File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension
2256 E.13.2 Protocol Basics
2257 ----------------------
2259 The File-I/O protocol uses the 'F' packet as the request as well as
2260 reply packet. Since a File-I/O system call can only occur when GDB is
2261 waiting for a response from the continuing or stepping target, the
2262 File-I/O request is a reply that GDB has to expect as a result of a
2263 previous 'C', 'c', 'S' or 's' packet. This 'F' packet contains all
2264 information needed to allow GDB to call the appropriate host system
2267 * A unique identifier for the requested system call.
2269 * All parameters to the system call. Pointers are given as addresses
2270 in the target memory address space. Pointers to strings are given
2271 as pointer/length pair. Numerical values are given as they are.
2272 Numerical control flags are given in a protocol-specific
2275 At this point, GDB has to perform the following actions.
2277 * If the parameters include pointer values to data needed as input to
2278 a system call, GDB requests this data from the target with a
2279 standard 'm' packet request. This additional communication has to
2280 be expected by the target implementation and is handled as any
2283 * GDB translates all value from protocol representation to host
2284 representation as needed. Datatypes are coerced into the host
2287 * GDB calls the system call.
2289 * It then coerces datatypes back to protocol representation.
2291 * If the system call is expected to return data in buffer space
2292 specified by pointer parameters to the call, the data is
2293 transmitted to the target using a 'M' or 'X' packet. This packet
2294 has to be expected by the target implementation and is handled as
2295 any other 'M' or 'X' packet.
2297 Eventually GDB replies with another 'F' packet which contains all
2298 necessary information for the target to continue. This at least
2303 * 'errno', if has been changed by the system call.
2307 After having done the needed type and value coercion, the target
2308 continues the latest continue or step action.
2311 File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension
2313 E.13.3 The 'F' Request Packet
2314 -----------------------------
2316 The 'F' request packet has the following format:
2318 'FCALL-ID,PARAMETER...'
2320 CALL-ID is the identifier to indicate the host system call to be
2321 called. This is just the name of the function.
2323 PARAMETER... are the parameters to the system call. Parameters are
2324 hexadecimal integer values, either the actual values in case of
2325 scalar datatypes, pointers to target buffer space in case of
2326 compound datatypes and unspecified memory areas, or pointer/length
2327 pairs in case of string parameters. These are appended to the
2328 CALL-ID as a comma-delimited list. All values are transmitted in
2329 ASCII string representation, pointer/length pairs separated by a
2333 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
2335 E.13.4 The 'F' Reply Packet
2336 ---------------------------
2338 The 'F' reply packet has the following format:
2340 'FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
2342 RETCODE is the return code of the system call as hexadecimal value.
2344 ERRNO is the 'errno' set by the call, in protocol-specific
2345 representation. This parameter can be omitted if the call was
2348 CTRL-C FLAG is only sent if the user requested a break. In this
2349 case, ERRNO must be sent as well, even if the call was successful.
2350 The CTRL-C FLAG itself consists of the character 'C':
2354 or, if the call was interrupted before the host call has been
2359 assuming 4 is the protocol-specific representation of 'EINTR'.
2362 File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension
2364 E.13.5 The 'Ctrl-C' Message
2365 ---------------------------
2367 If the 'Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
2368 Packet::), the target should behave as if it had gotten a break message.
2369 The meaning for the target is "system call interrupted by 'SIGINT'".
2370 Consequentially, the target should actually stop (as with a break
2371 message) and return to GDB with a 'T02' packet.
2373 It's important for the target to know in which state the system call
2374 was interrupted. There are two possible cases:
2376 * The system call hasn't been performed on the host yet.
2378 * The system call on the host has been finished.
2380 These two states can be distinguished by the target by the value of
2381 the returned 'errno'. If it's the protocol representation of 'EINTR',
2382 the system call hasn't been performed. This is equivalent to the
2383 'EINTR' handling on POSIX systems. In any other case, the target may
2384 presume that the system call has been finished -- successfully or not --
2385 and should behave as if the break message arrived right after the system
2388 GDB must behave reliably. If the system call has not been called
2389 yet, GDB may send the 'F' reply immediately, setting 'EINTR' as 'errno'
2390 in the packet. If the system call on the host has been finished before
2391 the user requests a break, the full action must be finished by GDB.
2392 This requires sending 'M' or 'X' packets as necessary. The 'F' packet
2393 may only be sent when either nothing has happened or the full action has
2397 File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension
2402 By default and if not explicitly closed by the target system, the file
2403 descriptors 0, 1 and 2 are connected to the GDB console. Output on the
2404 GDB console is handled as any other file output operation ('write(1,
2405 ...)' or 'write(2, ...)'). Console input is handled by GDB so that
2406 after the target read request from file descriptor 0 all following
2407 typing is buffered until either one of the following conditions is met:
2409 * The user types 'Ctrl-c'. The behaviour is as explained above, and
2410 the 'read' system call is treated as finished.
2412 * The user presses <RET>. This is treated as end of input with a
2415 * The user types 'Ctrl-d'. This is treated as end of input. No
2416 trailing character (neither newline nor 'Ctrl-D') is appended to
2419 If the user has typed more characters than fit in the buffer given to
2420 the 'read' call, the trailing characters are buffered in GDB until
2421 either another 'read(0, ...)' is requested by the target, or debugging
2422 is stopped at the user's request.
2425 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
2427 E.13.7 List of Supported Calls
2428 ------------------------------
2445 File: gdb.info, Node: open, Next: close, Up: List of Supported Calls
2451 int open(const char *pathname, int flags);
2452 int open(const char *pathname, int flags, mode_t mode);
2455 'Fopen,PATHPTR/LEN,FLAGS,MODE'
2457 FLAGS is the bitwise 'OR' of the following values:
2460 If the file does not exist it will be created. The host rules
2461 apply as far as file ownership and time stamps are concerned.
2464 When used with 'O_CREAT', if the file already exists it is an
2465 error and open() fails.
2468 If the file already exists and the open mode allows writing
2469 ('O_RDWR' or 'O_WRONLY' is given) it will be truncated to zero
2473 The file is opened in append mode.
2476 The file is opened for reading only.
2479 The file is opened for writing only.
2482 The file is opened for reading and writing.
2484 Other bits are silently ignored.
2486 MODE is the bitwise 'OR' of the following values:
2489 User has read permission.
2492 User has write permission.
2495 Group has read permission.
2498 Group has write permission.
2501 Others have read permission.
2504 Others have write permission.
2506 Other bits are silently ignored.
2509 'open' returns the new file descriptor or -1 if an error occurred.
2514 PATHNAME already exists and 'O_CREAT' and 'O_EXCL' were used.
2517 PATHNAME refers to a directory.
2520 The requested access is not allowed.
2523 PATHNAME was too long.
2526 A directory component in PATHNAME does not exist.
2529 PATHNAME refers to a device, pipe, named pipe or socket.
2532 PATHNAME refers to a file on a read-only filesystem and write
2533 access was requested.
2536 PATHNAME is an invalid pointer value.
2539 No space on device to create the file.
2542 The process already has the maximum number of files open.
2545 The limit on the total number of files open on the system has
2549 The call was interrupted by the user.
2552 File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls
2564 'close' returns zero on success, or -1 if an error occurred.
2569 FD isn't a valid open file descriptor.
2572 The call was interrupted by the user.
2575 File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls
2581 int read(int fd, void *buf, unsigned int count);
2584 'Fread,FD,BUFPTR,COUNT'
2587 On success, the number of bytes read is returned. Zero indicates
2588 end of file. If count is zero, read returns zero as well. On
2589 error, -1 is returned.
2594 FD is not a valid file descriptor or is not open for reading.
2597 BUFPTR is an invalid pointer value.
2600 The call was interrupted by the user.
2603 File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls
2609 int write(int fd, const void *buf, unsigned int count);
2612 'Fwrite,FD,BUFPTR,COUNT'
2615 On success, the number of bytes written are returned. Zero
2616 indicates nothing was written. On error, -1 is returned.
2621 FD is not a valid file descriptor or is not open for writing.
2624 BUFPTR is an invalid pointer value.
2627 An attempt was made to write a file that exceeds the
2628 host-specific maximum file size allowed.
2631 No space on device to write the data.
2634 The call was interrupted by the user.
2637 File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls
2643 long lseek (int fd, long offset, int flag);
2646 'Flseek,FD,OFFSET,FLAG'
2651 The offset is set to OFFSET bytes.
2654 The offset is set to its current location plus OFFSET bytes.
2657 The offset is set to the size of the file plus OFFSET bytes.
2660 On success, the resulting unsigned offset in bytes from the
2661 beginning of the file is returned. Otherwise, a value of -1 is
2667 FD is not a valid open file descriptor.
2670 FD is associated with the GDB console.
2673 FLAG is not a proper value.
2676 The call was interrupted by the user.
2679 File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls
2685 int rename(const char *oldpath, const char *newpath);
2688 'Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
2691 On success, zero is returned. On error, -1 is returned.
2696 NEWPATH is an existing directory, but OLDPATH is not a
2700 NEWPATH is a non-empty directory.
2703 OLDPATH or NEWPATH is a directory that is in use by some
2707 An attempt was made to make a directory a subdirectory of
2711 A component used as a directory in OLDPATH or new path is not
2712 a directory. Or OLDPATH is a directory and NEWPATH exists but
2716 OLDPATHPTR or NEWPATHPTR are invalid pointer values.
2719 No access to the file or the path of the file.
2723 OLDPATH or NEWPATH was too long.
2726 A directory component in OLDPATH or NEWPATH does not exist.
2729 The file is on a read-only filesystem.
2732 The device containing the file has no room for the new
2736 The call was interrupted by the user.
2739 File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls
2745 int unlink(const char *pathname);
2748 'Funlink,PATHNAMEPTR/LEN'
2751 On success, zero is returned. On error, -1 is returned.
2756 No access to the file or the path of the file.
2759 The system does not allow unlinking of directories.
2762 The file PATHNAME cannot be unlinked because it's being used
2766 PATHNAMEPTR is an invalid pointer value.
2769 PATHNAME was too long.
2772 A directory component in PATHNAME does not exist.
2775 A component of the path is not a directory.
2778 The file is on a read-only filesystem.
2781 The call was interrupted by the user.
2784 File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls
2790 int stat(const char *pathname, struct stat *buf);
2791 int fstat(int fd, struct stat *buf);
2794 'Fstat,PATHNAMEPTR/LEN,BUFPTR'
2798 On success, zero is returned. On error, -1 is returned.
2803 FD is not a valid open file.
2806 A directory component in PATHNAME does not exist or the path
2810 A component of the path is not a directory.
2813 PATHNAMEPTR is an invalid pointer value.
2816 No access to the file or the path of the file.
2819 PATHNAME was too long.
2822 The call was interrupted by the user.
2825 File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls
2831 int gettimeofday(struct timeval *tv, void *tz);
2834 'Fgettimeofday,TVPTR,TZPTR'
2837 On success, 0 is returned, -1 otherwise.
2842 TZ is a non-NULL pointer.
2845 TVPTR and/or TZPTR is an invalid pointer value.
2848 File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls
2860 Returns 1 if FD refers to the GDB console, 0 otherwise.
2865 The call was interrupted by the user.
2867 Note that the 'isatty' call is treated as a special case: it returns
2868 1 to the target if the file descriptor is attached to the GDB console, 0
2869 otherwise. Implementing through system calls would require implementing
2870 'ioctl' and would be more complex than needed.
2873 File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls
2879 int system(const char *command);
2882 'Fsystem,COMMANDPTR/LEN'
2885 If LEN is zero, the return value indicates whether a shell is
2886 available. A zero return value indicates a shell is not available.
2887 For non-zero LEN, the value returned is -1 on error and the return
2888 status of the command otherwise. Only the exit status of the
2889 command is returned, which is extracted from the host's 'system'
2890 return value by calling 'WEXITSTATUS(retval)'. In case '/bin/sh'
2891 could not be executed, 127 is returned.
2896 The call was interrupted by the user.
2898 GDB takes over the full task of calling the necessary host calls to
2899 perform the 'system' call. The return value of 'system' on the host is
2900 simplified before it's returned to the target. Any termination signal
2901 information from the child process is discarded, and the return value
2902 consists entirely of the exit status of the called command.
2904 Due to security concerns, the 'system' call is by default refused by
2905 GDB. The user has to allow this call explicitly with the 'set remote
2906 system-call-allowed 1' command.
2908 'set remote system-call-allowed'
2909 Control whether to allow the 'system' calls in the File I/O
2910 protocol for the remote target. The default is zero (disabled).
2912 'show remote system-call-allowed'
2913 Show whether the 'system' calls are allowed in the File I/O
2917 File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension
2919 E.13.8 Protocol-specific Representation of Datatypes
2920 ----------------------------------------------------
2924 * Integral Datatypes::
2931 File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes
2936 The integral datatypes used in the system calls are 'int', 'unsigned
2937 int', 'long', 'unsigned long', 'mode_t', and 'time_t'.
2939 'int', 'unsigned int', 'mode_t' and 'time_t' are implemented as 32
2940 bit values in this protocol.
2942 'long' and 'unsigned long' are implemented as 64 bit types.
2944 *Note Limits::, for corresponding MIN and MAX values (similar to
2945 those in 'limits.h') to allow range checking on host and target.
2947 'time_t' datatypes are defined as seconds since the Epoch.
2949 All integral datatypes transferred as part of a memory read or write
2950 of a structured datatype e.g. a 'struct stat' have to be given in big
2954 File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes
2959 Pointers to target data are transmitted as they are. An exception is
2960 made for pointers to buffers for which the length isn't transmitted as
2961 part of the function call, namely strings. Strings are transmitted as a
2962 pointer/length pair, both as hex values, e.g.
2966 which is a pointer to data of length 18 bytes at position 0x1aaf. The
2967 length is defined as the full string length in bytes, including the
2968 trailing null byte. For example, the string '"hello world"' at address
2969 0x123456 is transmitted as
2974 File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes
2979 Structured data which is transferred using a memory read or write (for
2980 example, a 'struct stat') is expected to be in a protocol-specific
2981 format with all scalar multibyte datatypes being big endian.
2982 Translation to this representation needs to be done both by the target
2983 before the 'F' packet is sent, and by GDB before it transfers memory to
2984 the target. Transferred pointers to structured data should point to the
2985 already-coerced data at any time.
2988 File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes
2993 The buffer of type 'struct stat' used by the target and GDB is defined
2997 unsigned int st_dev; /* device */
2998 unsigned int st_ino; /* inode */
2999 mode_t st_mode; /* protection */
3000 unsigned int st_nlink; /* number of hard links */
3001 unsigned int st_uid; /* user ID of owner */
3002 unsigned int st_gid; /* group ID of owner */
3003 unsigned int st_rdev; /* device type (if inode device) */
3004 unsigned long st_size; /* total size, in bytes */
3005 unsigned long st_blksize; /* blocksize for filesystem I/O */
3006 unsigned long st_blocks; /* number of blocks allocated */
3007 time_t st_atime; /* time of last access */
3008 time_t st_mtime; /* time of last modification */
3009 time_t st_ctime; /* time of last change */
3012 The integral datatypes conform to the definitions given in the
3013 appropriate section (see *note Integral Datatypes::, for details) so
3014 this structure is of size 64 bytes.
3016 The values of several fields have a restricted meaning and/or range
3020 A value of 0 represents a file, 1 the console.
3023 No valid meaning for the target. Transmitted unchanged.
3026 Valid mode bits are described in *note Constants::. Any other bits
3027 have currently no meaning for the target.
3032 No valid meaning for the target. Transmitted unchanged.
3037 These values have a host and file system dependent accuracy.
3038 Especially on Windows hosts, the file system may not support exact
3041 The target gets a 'struct stat' of the above representation and is
3042 responsible for coercing it to the target representation before
3045 Note that due to size differences between the host, target, and
3046 protocol representations of 'struct stat' members, these members could
3047 eventually get truncated on the target.
3050 File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes
3055 The buffer of type 'struct timeval' used by the File-I/O protocol is
3059 time_t tv_sec; /* second */
3060 long tv_usec; /* microsecond */
3063 The integral datatypes conform to the definitions given in the
3064 appropriate section (see *note Integral Datatypes::, for details) so
3065 this structure is of size 8 bytes.
3068 File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension
3073 The following values are used for the constants inside of the protocol.
3074 GDB and target are responsible for translating these values before and
3075 after the call as needed.
3086 File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants
3091 All values are given in hexadecimal representation.
3102 File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants
3107 All values are given in octal representation.
3122 File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants
3127 All values are given in decimal representation.
3150 'EUNKNOWN' is used as a fallback error value if a host system returns
3151 any error value not in the list of supported error numbers.
3154 File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
3164 File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants
3169 All values are given in decimal representation.
3174 LONG_MIN -9223372036854775808
3175 LONG_MAX 9223372036854775807
3176 ULONG_MAX 18446744073709551615
3179 File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension
3181 E.13.10 File-I/O Examples
3182 -------------------------
3184 Example sequence of a write call, file descriptor 3, buffer is at target
3185 address 0x1234, 6 bytes should be written:
3188 _request memory read from target_
3191 _return "6 bytes written"_
3194 Example sequence of a read call, file descriptor 3, buffer is at
3195 target address 0x1234, 6 bytes should be read:
3198 _request memory write to target_
3200 _return "6 bytes read"_
3203 Example sequence of a read call, call fails on the host due to
3204 invalid file descriptor ('EBADF'):
3209 Example sequence of a read call, user presses 'Ctrl-c' before syscall
3216 Example sequence of a read call, user presses 'Ctrl-c' after syscall
3224 File: gdb.info, Node: Library List Format, Next: Library List Format for SVR4 Targets, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol
3226 E.14 Library List Format
3227 ========================
3229 On some platforms, a dynamic loader (e.g. 'ld.so') runs in the same
3230 process as your application to manage libraries. In this case, GDB can
3231 use the loader's symbol table and normal memory operations to maintain a
3232 list of shared libraries. On other platforms, the operating system
3233 manages loaded libraries. GDB can not retrieve the list of currently
3234 loaded libraries through memory operations, so it uses the
3235 'qXfer:libraries:read' packet (*note qXfer library list read::) instead.
3236 The remote stub queries the target's operating system and reports which
3237 libraries are loaded.
3239 The 'qXfer:libraries:read' packet returns an XML document which lists
3240 loaded libraries and their offsets. Each library has an associated name
3241 and one or more segment or section base addresses, which report where
3242 the library was loaded in memory.
3244 For the common case of libraries that are fully linked binaries, the
3245 library should have a list of segments. If the target supports dynamic
3246 linking of a relocatable object file, its library XML element should
3247 instead include a list of allocated sections. The segment or section
3248 bases are start addresses, not relocation offsets; they do not depend on
3249 the library's link-time base addresses.
3251 GDB must be linked with the Expat library to support XML library
3252 lists. *Note Expat::.
3254 A simple memory map, with one loaded library relocated by a single
3255 offset, looks like this:
3258 <library name="/lib/libc.so.6">
3259 <segment address="0x10000000"/>
3263 Another simple memory map, with one loaded library with three
3264 allocated sections (.text, .data, .bss), looks like this:
3267 <library name="sharedlib.o">
3268 <section address="0x10000000"/>
3269 <section address="0x20000000"/>
3270 <section address="0x30000000"/>
3274 The format of a library list is described by this DTD:
3276 <!-- library-list: Root element with versioning -->
3277 <!ELEMENT library-list (library)*>
3278 <!ATTLIST library-list version CDATA #FIXED "1.0">
3279 <!ELEMENT library (segment*, section*)>
3280 <!ATTLIST library name CDATA #REQUIRED>
3281 <!ELEMENT segment EMPTY>
3282 <!ATTLIST segment address CDATA #REQUIRED>
3283 <!ELEMENT section EMPTY>
3284 <!ATTLIST section address CDATA #REQUIRED>
3286 In addition, segments and section descriptors cannot be mixed within
3287 a single library element, and you must supply at least one segment or
3288 section for each library.
3291 File: gdb.info, Node: Library List Format for SVR4 Targets, Next: Memory Map Format, Prev: Library List Format, Up: Remote Protocol
3293 E.15 Library List Format for SVR4 Targets
3294 =========================================
3296 On SVR4 platforms GDB can use the symbol table of a dynamic loader (e.g.
3297 'ld.so') and normal memory operations to maintain a list of shared
3298 libraries. Still a special library list provided by this packet is more
3299 efficient for the GDB remote protocol.
3301 The 'qXfer:libraries-svr4:read' packet returns an XML document which
3302 lists loaded libraries and their SVR4 linker parameters. For each
3303 library on SVR4 target, the following parameters are reported:
3305 - 'name', the absolute file name from the 'l_name' field of 'struct
3307 - 'lm' with address of 'struct link_map' used for TLS (Thread Local
3309 - 'l_addr', the displacement as read from the field 'l_addr' of
3310 'struct link_map'. For prelinked libraries this is not an absolute
3311 memory address. It is a displacement of absolute memory address
3312 against address the file was prelinked to during the library load.
3313 - 'l_ld', which is memory address of the 'PT_DYNAMIC' segment
3315 Additionally the single 'main-lm' attribute specifies address of
3316 'struct link_map' used for the main executable. This parameter is used
3317 for TLS access and its presence is optional.
3319 GDB must be linked with the Expat library to support XML SVR4 library
3320 lists. *Note Expat::.
3322 A simple memory map, with two loaded libraries (which do not use
3323 prelink), looks like this:
3325 <library-list-svr4 version="1.0" main-lm="0xe4f8f8">
3326 <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
3328 <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
3332 The format of an SVR4 library list is described by this DTD:
3334 <!-- library-list-svr4: Root element with versioning -->
3335 <!ELEMENT library-list-svr4 (library)*>
3336 <!ATTLIST library-list-svr4 version CDATA #FIXED "1.0">
3337 <!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED>
3338 <!ELEMENT library EMPTY>
3339 <!ATTLIST library name CDATA #REQUIRED>
3340 <!ATTLIST library lm CDATA #REQUIRED>
3341 <!ATTLIST library l_addr CDATA #REQUIRED>
3342 <!ATTLIST library l_ld CDATA #REQUIRED>
3345 File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format for SVR4 Targets, Up: Remote Protocol
3347 E.16 Memory Map Format
3348 ======================
3350 To be able to write into flash memory, GDB needs to obtain a memory map
3351 from the target. This section describes the format of the memory map.
3353 The memory map is obtained using the 'qXfer:memory-map:read' (*note
3354 qXfer memory map read::) packet and is an XML document that lists memory
3357 GDB must be linked with the Expat library to support XML memory maps.
3360 The top-level structure of the document is shown below:
3362 <?xml version="1.0"?>
3363 <!DOCTYPE memory-map
3364 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
3365 "http://sourceware.org/gdb/gdb-memory-map.dtd">
3370 Each region can be either:
3372 * A region of RAM starting at ADDR and extending for LENGTH bytes
3375 <memory type="ram" start="ADDR" length="LENGTH"/>
3377 * A region of read-only memory:
3379 <memory type="rom" start="ADDR" length="LENGTH"/>
3381 * A region of flash memory, with erasure blocks BLOCKSIZE bytes in
3384 <memory type="flash" start="ADDR" length="LENGTH">
3385 <property name="blocksize">BLOCKSIZE</property>
3388 Regions must not overlap. GDB assumes that areas of memory not
3389 covered by the memory map are RAM, and uses the ordinary 'M' and 'X'
3390 packets to write to addresses in such ranges.
3392 The formal DTD for memory map format is given below:
3394 <!-- ................................................... -->
3395 <!-- Memory Map XML DTD ................................ -->
3396 <!-- File: memory-map.dtd .............................. -->
3397 <!-- .................................... .............. -->
3398 <!-- memory-map.dtd -->
3399 <!-- memory-map: Root element with versioning -->
3400 <!ELEMENT memory-map (memory | property)>
3401 <!ATTLIST memory-map version CDATA #FIXED "1.0.0">
3402 <!ELEMENT memory (property)>
3403 <!-- memory: Specifies a memory region,
3404 and its type, or device. -->
3405 <!ATTLIST memory type CDATA #REQUIRED
3406 start CDATA #REQUIRED
3407 length CDATA #REQUIRED
3408 device CDATA #IMPLIED>
3409 <!-- property: Generic attribute tag -->
3410 <!ELEMENT property (#PCDATA | property)*>
3411 <!ATTLIST property name CDATA #REQUIRED>
3414 File: gdb.info, Node: Thread List Format, Next: Traceframe Info Format, Prev: Memory Map Format, Up: Remote Protocol
3416 E.17 Thread List Format
3417 =======================
3419 To efficiently update the list of threads and their attributes, GDB
3420 issues the 'qXfer:threads:read' packet (*note qXfer threads read::) and
3421 obtains the XML document with the following structure:
3423 <?xml version="1.0"?>
3425 <thread id="id" core="0">
3430 Each 'thread' element must have the 'id' attribute that identifies
3431 the thread (*note thread-id syntax::). The 'core' attribute, if
3432 present, specifies which processor core the thread was last executing
3433 on. The content of the of 'thread' element is interpreted as
3434 human-readable auxilliary information.
3437 File: gdb.info, Node: Traceframe Info Format, Next: Branch Trace Format, Prev: Thread List Format, Up: Remote Protocol
3439 E.18 Traceframe Info Format
3440 ===========================
3442 To be able to know which objects in the inferior can be examined when
3443 inspecting a tracepoint hit, GDB needs to obtain the list of memory
3444 ranges, registers and trace state variables that have been collected in
3447 This list is obtained using the 'qXfer:traceframe-info:read' (*note
3448 qXfer traceframe info read::) packet and is an XML document.
3450 GDB must be linked with the Expat library to support XML traceframe
3451 info discovery. *Note Expat::.
3453 The top-level structure of the document is shown below:
3455 <?xml version="1.0"?>
3456 <!DOCTYPE traceframe-info
3457 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
3458 "http://sourceware.org/gdb/gdb-traceframe-info.dtd">
3463 Each traceframe block can be either:
3465 * A region of collected memory starting at ADDR and extending for
3466 LENGTH bytes from there:
3468 <memory start="ADDR" length="LENGTH"/>
3470 * A block indicating trace state variable numbered NUMBER has been
3475 The formal DTD for the traceframe info format is given below:
3477 <!ELEMENT traceframe-info (memory | tvar)* >
3478 <!ATTLIST traceframe-info version CDATA #FIXED "1.0">
3480 <!ELEMENT memory EMPTY>
3481 <!ATTLIST memory start CDATA #REQUIRED
3482 length CDATA #REQUIRED>
3484 <!ATTLIST tvar id CDATA #REQUIRED>
3487 File: gdb.info, Node: Branch Trace Format, Prev: Traceframe Info Format, Up: Remote Protocol
3489 E.19 Branch Trace Format
3490 ========================
3492 In order to display the branch trace of an inferior thread, GDB needs to
3493 obtain the list of branches. This list is represented as list of
3494 sequential code blocks that are connected via branches. The code in
3495 each block has been executed sequentially.
3497 This list is obtained using the 'qXfer:btrace:read' (*note qXfer
3498 btrace read::) packet and is an XML document.
3500 GDB must be linked with the Expat library to support XML traceframe
3501 info discovery. *Note Expat::.
3503 The top-level structure of the document is shown below:
3505 <?xml version="1.0"?>
3507 PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"
3508 "http://sourceware.org/gdb/gdb-btrace.dtd">
3513 * A block of sequentially executed instructions starting at BEGIN and
3516 <block begin="BEGIN" end="END"/>
3518 The formal DTD for the branch trace format is given below:
3520 <!ELEMENT btrace (block)* >
3521 <!ATTLIST btrace version CDATA #FIXED "1.0">
3523 <!ELEMENT block EMPTY>
3524 <!ATTLIST block begin CDATA #REQUIRED
3525 end CDATA #REQUIRED>
3528 File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top
3530 Appendix F The GDB Agent Expression Mechanism
3531 *********************************************
3533 In some applications, it is not feasible for the debugger to interrupt
3534 the program's execution long enough for the developer to learn anything
3535 helpful about its behavior. If the program's correctness depends on its
3536 real-time behavior, delays introduced by a debugger might cause the
3537 program to fail, even when the code itself is correct. It is useful to
3538 be able to observe the program's behavior without interrupting it.
3540 Using GDB's 'trace' and 'collect' commands, the user can specify
3541 locations in the program, and arbitrary expressions to evaluate when
3542 those locations are reached. Later, using the 'tfind' command, she can
3543 examine the values those expressions had when the program hit the trace
3544 points. The expressions may also denote objects in memory -- structures
3545 or arrays, for example -- whose values GDB should record; while visiting
3546 a particular tracepoint, the user may inspect those objects as if they
3547 were in memory at that moment. However, because GDB records these
3548 values without interacting with the user, it can do so quickly and
3549 unobtrusively, hopefully not disturbing the program's behavior.
3551 When GDB is debugging a remote target, the GDB "agent" code running
3552 on the target computes the values of the expressions itself. To avoid
3553 having a full symbolic expression evaluator on the agent, GDB translates
3554 expressions in the source language into a simpler bytecode language, and
3555 then sends the bytecode to the agent; the agent then executes the
3556 bytecode, and records the values for GDB to retrieve later.
3558 The bytecode language is simple; there are forty-odd opcodes, the
3559 bulk of which are the usual vocabulary of C operands (addition,
3560 subtraction, shifts, and so on) and various sizes of literals and memory
3561 reference operations. The bytecode interpreter operates strictly on
3562 machine-level values -- various sizes of integers and floating point
3563 numbers -- and requires no information about types or symbols; thus, the
3564 interpreter's internal data structures are simple, and each bytecode
3565 requires only a few native machine instructions to implement it. The
3566 interpreter is small, and strict limits on the memory and time required
3567 to evaluate an expression are easy to determine, making it suitable for
3568 use by the debugging agent in real-time applications.
3572 * General Bytecode Design:: Overview of the interpreter.
3573 * Bytecode Descriptions:: What each one does.
3574 * Using Agent Expressions:: How agent expressions fit into the big picture.
3575 * Varying Target Capabilities:: How to discover what the target can do.
3576 * Rationale:: Why we did it this way.
3579 File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions
3581 F.1 General Bytecode Design
3582 ===========================
3584 The agent represents bytecode expressions as an array of bytes. Each
3585 instruction is one byte long (thus the term "bytecode"). Some
3586 instructions are followed by operand bytes; for example, the 'goto'
3587 instruction is followed by a destination for the jump.
3589 The bytecode interpreter is a stack-based machine; most instructions
3590 pop their operands off the stack, perform some operation, and push the
3591 result back on the stack for the next instruction to consume. Each
3592 element of the stack may contain either a integer or a floating point
3593 value; these values are as many bits wide as the largest integer that
3594 can be directly manipulated in the source language. Stack elements
3595 carry no record of their type; bytecode could push a value as an
3596 integer, then pop it as a floating point value. However, GDB will not
3597 generate code which does this. In C, one might define the type of a
3598 stack element as follows:
3603 where 'LONGEST' and 'DOUBLEST' are 'typedef' names for the largest
3604 integer and floating point types on the machine.
3606 By the time the bytecode interpreter reaches the end of the
3607 expression, the value of the expression should be the only value left on
3608 the stack. For tracing applications, 'trace' bytecodes in the
3609 expression will have recorded the necessary data, and the value on the
3610 stack may be discarded. For other applications, like conditional
3611 breakpoints, the value may be useful.
3613 Separate from the stack, the interpreter has two registers:
3615 The address of the next bytecode to execute.
3618 The address of the start of the bytecode expression, necessary for
3619 interpreting the 'goto' and 'if_goto' instructions.
3621 Neither of these registers is directly visible to the bytecode language
3622 itself, but they are useful for defining the meanings of the bytecode
3625 There are no instructions to perform side effects on the running
3626 program, or call the program's functions; we assume that these
3627 expressions are only used for unobtrusive debugging, not for patching
3630 Most bytecode instructions do not distinguish between the various
3631 sizes of values, and operate on full-width values; the upper bits of the
3632 values are simply ignored, since they do not usually make a difference
3633 to the value computed. The exceptions to this rule are:
3635 memory reference instructions ('ref'N)
3636 There are distinct instructions to fetch different word sizes from
3637 memory. Once on the stack, however, the values are treated as
3638 full-size integers. They may need to be sign-extended; the 'ext'
3639 instruction exists for this purpose.
3641 the sign-extension instruction ('ext' N)
3642 These clearly need to know which portion of their operand is to be
3643 extended to occupy the full length of the word.
3645 If the interpreter is unable to evaluate an expression completely for
3646 some reason (a memory location is inaccessible, or a divisor is zero,
3647 for example), we say that interpretation "terminates with an error".
3648 This means that the problem is reported back to the interpreter's caller
3649 in some helpful way. In general, code using agent expressions should
3650 assume that they may attempt to divide by zero, fetch arbitrary memory
3651 locations, and misbehave in other ways.
3653 Even complicated C expressions compile to a few bytecode
3654 instructions; for example, the expression 'x + y * z' would typically
3655 produce code like the following, assuming that 'x' and 'y' live in
3656 registers, and 'z' is a global variable holding a 32-bit 'int':
3659 const32 address of z
3666 In detail, these mean:
3669 Push the value of register 1 (presumably holding 'x') onto the
3673 Push the value of register 2 (holding 'y').
3675 'const32 address of z'
3676 Push the address of 'z' onto the stack.
3679 Fetch a 32-bit word from the address at the top of the stack;
3680 replace the address on the stack with the value. Thus, we replace
3681 the address of 'z' with 'z''s value.
3684 Sign-extend the value on the top of the stack from 32 bits to full
3685 length. This is necessary because 'z' is a signed integer.
3688 Pop the top two numbers on the stack, multiply them, and push their
3689 product. Now the top of the stack contains the value of the
3693 Pop the top two numbers, add them, and push the sum. Now the top
3694 of the stack contains the value of 'x + y * z'.
3697 Stop executing; the value left on the stack top is the value to be
3701 File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions
3703 F.2 Bytecode Descriptions
3704 =========================
3706 Each bytecode description has the following form:
3708 'add' (0x02): A B => A+B
3710 Pop the top two stack items, A and B, as integers; push their sum,
3713 In this example, 'add' is the name of the bytecode, and '(0x02)' is
3714 the one-byte value used to encode the bytecode, in hexadecimal. The
3715 phrase "A B => A+B" shows the stack before and after the bytecode
3716 executes. Beforehand, the stack must contain at least two values, A and
3717 B; since the top of the stack is to the right, B is on the top of the
3718 stack, and A is underneath it. After execution, the bytecode will have
3719 popped A and B from the stack, and replaced them with a single value,
3720 A+B. There may be other values on the stack below those shown, but the
3721 bytecode affects only those shown.
3723 Here is another example:
3725 'const8' (0x22) N: => N
3726 Push the 8-bit integer constant N on the stack, without sign
3729 In this example, the bytecode 'const8' takes an operand N directly
3730 from the bytecode stream; the operand follows the 'const8' bytecode
3731 itself. We write any such operands immediately after the name of the
3732 bytecode, before the colon, and describe the exact encoding of the
3733 operand in the bytecode stream in the body of the bytecode description.
3735 For the 'const8' bytecode, there are no stack items given before the
3736 =>; this simply means that the bytecode consumes no values from the
3737 stack. If a bytecode consumes no values, or produces no values, the
3738 list on either side of the => may be empty.
3740 If a value is written as A, B, or N, then the bytecode treats it as
3741 an integer. If a value is written is ADDR, then the bytecode treats it
3744 We do not fully describe the floating point operations here; although
3745 this design can be extended in a clean way to handle floating point
3746 values, they are not of immediate interest to the customer, so we avoid
3747 describing them, to save time.
3751 Prefix for floating-point bytecodes. Not implemented yet.
3753 'add' (0x02): A B => A+B
3754 Pop two integers from the stack, and push their sum, as an integer.
3756 'sub' (0x03): A B => A-B
3757 Pop two integers from the stack, subtract the top value from the
3758 next-to-top value, and push the difference.
3760 'mul' (0x04): A B => A*B
3761 Pop two integers from the stack, multiply them, and push the
3762 product on the stack. Note that, when one multiplies two N-bit
3763 numbers yielding another N-bit number, it is irrelevant whether the
3764 numbers are signed or not; the results are the same.
3766 'div_signed' (0x05): A B => A/B
3767 Pop two signed integers from the stack; divide the next-to-top
3768 value by the top value, and push the quotient. If the divisor is
3769 zero, terminate with an error.
3771 'div_unsigned' (0x06): A B => A/B
3772 Pop two unsigned integers from the stack; divide the next-to-top
3773 value by the top value, and push the quotient. If the divisor is
3774 zero, terminate with an error.
3776 'rem_signed' (0x07): A B => A MODULO B
3777 Pop two signed integers from the stack; divide the next-to-top
3778 value by the top value, and push the remainder. If the divisor is
3779 zero, terminate with an error.
3781 'rem_unsigned' (0x08): A B => A MODULO B
3782 Pop two unsigned integers from the stack; divide the next-to-top
3783 value by the top value, and push the remainder. If the divisor is
3784 zero, terminate with an error.
3786 'lsh' (0x09): A B => A<<B
3787 Pop two integers from the stack; let A be the next-to-top value,
3788 and B be the top value. Shift A left by B bits, and push the
3791 'rsh_signed' (0x0a): A B => '(signed)'A>>B
3792 Pop two integers from the stack; let A be the next-to-top value,
3793 and B be the top value. Shift A right by B bits, inserting copies
3794 of the top bit at the high end, and push the result.
3796 'rsh_unsigned' (0x0b): A B => A>>B
3797 Pop two integers from the stack; let A be the next-to-top value,
3798 and B be the top value. Shift A right by B bits, inserting zero
3799 bits at the high end, and push the result.
3801 'log_not' (0x0e): A => !A
3802 Pop an integer from the stack; if it is zero, push the value one;
3803 otherwise, push the value zero.
3805 'bit_and' (0x0f): A B => A&B
3806 Pop two integers from the stack, and push their bitwise 'and'.
3808 'bit_or' (0x10): A B => A|B
3809 Pop two integers from the stack, and push their bitwise 'or'.
3811 'bit_xor' (0x11): A B => A^B
3812 Pop two integers from the stack, and push their bitwise
3815 'bit_not' (0x12): A => ~A
3816 Pop an integer from the stack, and push its bitwise complement.
3818 'equal' (0x13): A B => A=B
3819 Pop two integers from the stack; if they are equal, push the value
3820 one; otherwise, push the value zero.
3822 'less_signed' (0x14): A B => A<B
3823 Pop two signed integers from the stack; if the next-to-top value is
3824 less than the top value, push the value one; otherwise, push the
3827 'less_unsigned' (0x15): A B => A<B
3828 Pop two unsigned integers from the stack; if the next-to-top value
3829 is less than the top value, push the value one; otherwise, push the
3832 'ext' (0x16) N: A => A, sign-extended from N bits
3833 Pop an unsigned value from the stack; treating it as an N-bit
3834 twos-complement value, extend it to full length. This means that
3835 all bits to the left of bit N-1 (where the least significant bit is
3836 bit 0) are set to the value of bit N-1. Note that N may be larger
3837 than or equal to the width of the stack elements of the bytecode
3838 engine; in this case, the bytecode should have no effect.
3840 The number of source bits to preserve, N, is encoded as a single
3841 byte unsigned integer following the 'ext' bytecode.
3843 'zero_ext' (0x2a) N: A => A, zero-extended from N bits
3844 Pop an unsigned value from the stack; zero all but the bottom N
3845 bits. This means that all bits to the left of bit N-1 (where the
3846 least significant bit is bit 0) are set to the value of bit N-1.
3848 The number of source bits to preserve, N, is encoded as a single
3849 byte unsigned integer following the 'zero_ext' bytecode.
3851 'ref8' (0x17): ADDR => A
3852 'ref16' (0x18): ADDR => A
3853 'ref32' (0x19): ADDR => A
3854 'ref64' (0x1a): ADDR => A
3855 Pop an address ADDR from the stack. For bytecode 'ref'N, fetch an
3856 N-bit value from ADDR, using the natural target endianness. Push
3857 the fetched value as an unsigned integer.
3859 Note that ADDR may not be aligned in any particular way; the 'refN'
3860 bytecodes should operate correctly for any address.
3862 If attempting to access memory at ADDR would cause a processor
3863 exception of some sort, terminate with an error.
3865 'ref_float' (0x1b): ADDR => D
3866 'ref_double' (0x1c): ADDR => D
3867 'ref_long_double' (0x1d): ADDR => D
3868 'l_to_d' (0x1e): A => D
3869 'd_to_l' (0x1f): D => A
3870 Not implemented yet.
3872 'dup' (0x28): A => A A
3873 Push another copy of the stack's top element.
3875 'swap' (0x2b): A B => B A
3876 Exchange the top two items on the stack.
3879 Discard the top value on the stack.
3881 'pick' (0x32) N: A ... B => A ... B A
3882 Duplicate an item from the stack and push it on the top of the
3883 stack. N, a single byte, indicates the stack item to copy. If N
3884 is zero, this is the same as 'dup'; if N is one, it copies the item
3885 under the top item, etc. If N exceeds the number of items on the
3886 stack, terminate with an error.
3888 'rot' (0x33): A B C => C B A
3889 Rotate the top three items on the stack.
3891 'if_goto' (0x20) OFFSET: A =>
3892 Pop an integer off the stack; if it is non-zero, branch to the
3893 given offset in the bytecode string. Otherwise, continue to the
3894 next instruction in the bytecode stream. In other words, if A is
3895 non-zero, set the 'pc' register to 'start' + OFFSET. Thus, an
3896 offset of zero denotes the beginning of the expression.
3898 The OFFSET is stored as a sixteen-bit unsigned value, stored
3899 immediately following the 'if_goto' bytecode. It is always stored
3900 most significant byte first, regardless of the target's normal
3901 endianness. The offset is not guaranteed to fall at any particular
3902 alignment within the bytecode stream; thus, on machines where
3903 fetching a 16-bit on an unaligned address raises an exception, you
3904 should fetch the offset one byte at a time.
3906 'goto' (0x21) OFFSET: =>
3907 Branch unconditionally to OFFSET; in other words, set the 'pc'
3908 register to 'start' + OFFSET.
3910 The offset is stored in the same way as for the 'if_goto' bytecode.
3912 'const8' (0x22) N: => N
3913 'const16' (0x23) N: => N
3914 'const32' (0x24) N: => N
3915 'const64' (0x25) N: => N
3916 Push the integer constant N on the stack, without sign extension.
3917 To produce a small negative value, push a small twos-complement
3918 value, and then sign-extend it using the 'ext' bytecode.
3920 The constant N is stored in the appropriate number of bytes
3921 following the 'const'B bytecode. The constant N is always stored
3922 most significant byte first, regardless of the target's normal
3923 endianness. The constant is not guaranteed to fall at any
3924 particular alignment within the bytecode stream; thus, on machines
3925 where fetching a 16-bit on an unaligned address raises an
3926 exception, you should fetch N one byte at a time.
3928 'reg' (0x26) N: => A
3929 Push the value of register number N, without sign extension. The
3930 registers are numbered following GDB's conventions.
3932 The register number N is encoded as a 16-bit unsigned integer
3933 immediately following the 'reg' bytecode. It is always stored most
3934 significant byte first, regardless of the target's normal
3935 endianness. The register number is not guaranteed to fall at any
3936 particular alignment within the bytecode stream; thus, on machines
3937 where fetching a 16-bit on an unaligned address raises an
3938 exception, you should fetch the register number one byte at a time.
3940 'getv' (0x2c) N: => V
3941 Push the value of trace state variable number N, without sign
3944 The variable number N is encoded as a 16-bit unsigned integer
3945 immediately following the 'getv' bytecode. It is always stored
3946 most significant byte first, regardless of the target's normal
3947 endianness. The variable number is not guaranteed to fall at any
3948 particular alignment within the bytecode stream; thus, on machines
3949 where fetching a 16-bit on an unaligned address raises an
3950 exception, you should fetch the register number one byte at a time.
3952 'setv' (0x2d) N: => V
3953 Set trace state variable number N to the value found on the top of
3954 the stack. The stack is unchanged, so that the value is readily
3955 available if the assignment is part of a larger expression. The
3956 handling of N is as described for 'getv'.
3958 'trace' (0x0c): ADDR SIZE =>
3959 Record the contents of the SIZE bytes at ADDR in a trace buffer,
3960 for later retrieval by GDB.
3962 'trace_quick' (0x0d) SIZE: ADDR => ADDR
3963 Record the contents of the SIZE bytes at ADDR in a trace buffer,
3964 for later retrieval by GDB. SIZE is a single byte unsigned integer
3965 following the 'trace' opcode.
3967 This bytecode is equivalent to the sequence 'dup const8 SIZE
3968 trace', but we provide it anyway to save space in bytecode strings.
3970 'trace16' (0x30) SIZE: ADDR => ADDR
3971 Identical to trace_quick, except that SIZE is a 16-bit big-endian
3972 unsigned integer, not a single byte. This should probably have
3973 been named 'trace_quick16', for consistency.
3975 'tracev' (0x2e) N: => A
3976 Record the value of trace state variable number N in the trace
3977 buffer. The handling of N is as described for 'getv'.
3979 'tracenz' (0x2f) ADDR SIZE =>
3980 Record the bytes at ADDR in a trace buffer, for later retrieval by
3981 GDB. Stop at either the first zero byte, or when SIZE bytes have
3982 been recorded, whichever occurs first.
3984 'printf' (0x34) NUMARGS STRING =>
3985 Do a formatted print, in the style of the C function 'printf').
3986 The value of NUMARGS is the number of arguments to expect on the
3987 stack, while STRING is the format string, prefixed with a two-byte
3988 length. The last byte of the string must be zero, and is included
3989 in the length. The format string includes escaped sequences just
3990 as it appears in C source, so for instance the format string
3991 '"\t%d\n"' is six characters long, and the output will consist of a
3992 tab character, a decimal number, and a newline. At the top of the
3993 stack, above the values to be printed, this bytecode will pop a
3994 "function" and "channel". If the function is nonzero, then the
3995 target may treat it as a function and call it, passing the channel
3996 as a first argument, as with the C function 'fprintf'. If the
3997 function is zero, then the target may simply call a standard
3998 formatted print function of its choice. In all, this bytecode pops
3999 2 + NUMARGS stack elements, and pushes nothing.
4002 Stop executing bytecode; the result should be the top element of
4003 the stack. If the purpose of the expression was to compute an
4004 lvalue or a range of memory, then the next-to-top of the stack is
4005 the lvalue's address, and the top of the stack is the lvalue's
4009 File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions
4011 F.3 Using Agent Expressions
4012 ===========================
4014 Agent expressions can be used in several different ways by GDB, and the
4015 debugger can generate different bytecode sequences as appropriate.
4017 One possibility is to do expression evaluation on the target rather
4018 than the host, such as for the conditional of a conditional tracepoint.
4019 In such a case, GDB compiles the source expression into a bytecode
4020 sequence that simply gets values from registers or memory, does
4021 arithmetic, and returns a result.
4023 Another way to use agent expressions is for tracepoint data
4024 collection. GDB generates a different bytecode sequence for collection;
4025 in addition to bytecodes that do the calculation, GDB adds 'trace'
4026 bytecodes to save the pieces of memory that were used.
4028 * The user selects trace points in the program's code at which GDB
4029 should collect data.
4031 * The user specifies expressions to evaluate at each trace point.
4032 These expressions may denote objects in memory, in which case those
4033 objects' contents are recorded as the program runs, or computed
4034 values, in which case the values themselves are recorded.
4036 * GDB transmits the tracepoints and their associated expressions to
4037 the GDB agent, running on the debugging target.
4039 * The agent arranges to be notified when a trace point is hit.
4041 * When execution on the target reaches a trace point, the agent
4042 evaluates the expressions associated with that trace point, and
4043 records the resulting values and memory ranges.
4045 * Later, when the user selects a given trace event and inspects the
4046 objects and expression values recorded, GDB talks to the agent to
4047 retrieve recorded data as necessary to meet the user's requests.
4048 If the user asks to see an object whose contents have not been
4049 recorded, GDB reports an error.
4052 File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions
4054 F.4 Varying Target Capabilities
4055 ===============================
4057 Some targets don't support floating-point, and some would rather not
4058 have to deal with 'long long' operations. Also, different targets will
4059 have different stack sizes, and different bytecode buffer lengths.
4061 Thus, GDB needs a way to ask the target about itself. We haven't
4062 worked out the details yet, but in general, GDB should be able to send
4063 the target a packet asking it to describe itself. The reply should be a
4064 packet whose length is explicit, so we can add new information to the
4065 packet in future revisions of the agent, without confusing old versions
4066 of GDB, and it should contain a version number. It should contain at
4067 least the following information:
4069 * whether floating point is supported
4071 * whether 'long long' is supported
4073 * maximum acceptable size of bytecode stack
4075 * maximum acceptable length of bytecode expressions
4077 * which registers are actually available for collection
4079 * whether the target supports disabled tracepoints
4082 File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions
4087 Some of the design decisions apparent above are arguable.
4089 What about stack overflow/underflow?
4090 GDB should be able to query the target to discover its stack size.
4091 Given that information, GDB can determine at translation time
4092 whether a given expression will overflow the stack. But this spec
4093 isn't about what kinds of error-checking GDB ought to do.
4095 Why are you doing everything in LONGEST?
4097 Speed isn't important, but agent code size is; using LONGEST brings
4098 in a bunch of support code to do things like division, etc. So
4099 this is a serious concern.
4101 First, note that you don't need different bytecodes for different
4102 operand sizes. You can generate code without _knowing_ how big the
4103 stack elements actually are on the target. If the target only
4104 supports 32-bit ints, and you don't send any 64-bit bytecodes,
4105 everything just works. The observation here is that the MIPS and
4106 the Alpha have only fixed-size registers, and you can still get C's
4107 semantics even though most instructions only operate on full-sized
4108 words. You just need to make sure everything is properly
4109 sign-extended at the right times. So there is no need for 32- and
4110 64-bit variants of the bytecodes. Just implement everything using
4111 the largest size you support.
4113 GDB should certainly check to see what sizes the target supports,
4114 so the user can get an error earlier, rather than later. But this
4115 information is not necessary for correctness.
4117 Why don't you have '>' or '<=' operators?
4118 I want to keep the interpreter small, and we don't need them. We
4119 can combine the 'less_' opcodes with 'log_not', and swap the order
4120 of the operands, yielding all four asymmetrical comparison
4121 operators. For example, '(x <= y)' is '! (x > y)', which is '! (y
4124 Why do you have 'log_not'?
4125 Why do you have 'ext'?
4126 Why do you have 'zero_ext'?
4127 These are all easily synthesized from other instructions, but I
4128 expect them to be used frequently, and they're simple, so I include
4129 them to keep bytecode strings short.
4131 'log_not' is equivalent to 'const8 0 equal'; it's used in half the
4132 relational operators.
4134 'ext N' is equivalent to 'const8 S-N lsh const8 S-N rsh_signed',
4135 where S is the size of the stack elements; it follows 'refM' and
4136 REG bytecodes when the value should be signed. See the next
4139 'zero_ext N' is equivalent to 'constM MASK log_and'; it's used
4140 whenever we push the value of a register, because we can't assume
4141 the upper bits of the register aren't garbage.
4143 Why not have sign-extending variants of the 'ref' operators?
4144 Because that would double the number of 'ref' operators, and we
4145 need the 'ext' bytecode anyway for accessing bitfields.
4147 Why not have constant-address variants of the 'ref' operators?
4148 Because that would double the number of 'ref' operators again, and
4149 'const32 ADDRESS ref32' is only one byte longer.
4151 Why do the 'refN' operators have to support unaligned fetches?
4152 GDB will generate bytecode that fetches multi-byte values at
4153 unaligned addresses whenever the executable's debugging information
4154 tells it to. Furthermore, GDB does not know the value the pointer
4155 will have when GDB generates the bytecode, so it cannot determine
4156 whether a particular fetch will be aligned or not.
4158 In particular, structure bitfields may be several bytes long, but
4159 follow no alignment rules; members of packed structures are not
4160 necessarily aligned either.
4162 In general, there are many cases where unaligned references occur
4163 in correct C code, either at the programmer's explicit request, or
4164 at the compiler's discretion. Thus, it is simpler to make the GDB
4165 agent bytecodes work correctly in all circumstances than to make
4166 GDB guess in each case whether the compiler did the usual thing.
4168 Why are there no side-effecting operators?
4169 Because our current client doesn't want them? That's a cheap
4170 answer. I think the real answer is that I'm afraid of implementing
4171 function calls. We should re-visit this issue after the present
4172 contract is delivered.
4174 Why aren't the 'goto' ops PC-relative?
4175 The interpreter has the base address around anyway for PC bounds
4176 checking, and it seemed simpler.
4178 Why is there only one offset size for the 'goto' ops?
4179 Offsets are currently sixteen bits. I'm not happy with this
4182 Suppose we have multiple branch ops with different offset sizes.
4183 As I generate code left-to-right, all my jumps are forward jumps
4184 (there are no loops in expressions), so I never know the target
4185 when I emit the jump opcode. Thus, I have to either always assume
4186 the largest offset size, or do jump relaxation on the code after I
4187 generate it, which seems like a big waste of time.
4189 I can imagine a reasonable expression being longer than 256 bytes.
4190 I can't imagine one being longer than 64k. Thus, we need 16-bit
4191 offsets. This kind of reasoning is so bogus, but relaxation is
4194 The other approach would be to generate code right-to-left. Then
4195 I'd always know my offset size. That might be fun.
4197 Where is the function call bytecode?
4199 When we add side-effects, we should add this.
4201 Why does the 'reg' bytecode take a 16-bit register number?
4203 Intel's IA-64 architecture has 128 general-purpose registers, and
4204 128 floating-point registers, and I'm sure it has some random
4207 Why do we need 'trace' and 'trace_quick'?
4208 Because GDB needs to record all the memory contents and registers
4209 an expression touches. If the user wants to evaluate an expression
4210 'x->y->z', the agent must record the values of 'x' and 'x->y' as
4211 well as the value of 'x->y->z'.
4213 Don't the 'trace' bytecodes make the interpreter less general?
4214 They do mean that the interpreter contains special-purpose code,
4215 but that doesn't mean the interpreter can only be used for that
4216 purpose. If an expression doesn't use the 'trace' bytecodes, they
4217 don't get in its way.
4219 Why doesn't 'trace_quick' consume its arguments the way everything else does?
4220 In general, you do want your operators to consume their arguments;
4221 it's consistent, and generally reduces the amount of stack
4222 rearrangement necessary. However, 'trace_quick' is a kludge to
4223 save space; it only exists so we needn't write 'dup const8 SIZE
4224 trace' before every memory reference. Therefore, it's okay for it
4225 not to consume its arguments; it's meant for a specific context in
4226 which we know exactly what it should do with the stack. If we're
4227 going to have a kludge, it should be an effective kludge.
4229 Why does 'trace16' exist?
4230 That opcode was added by the customer that contracted Cygnus for
4231 the data tracing work. I personally think it is unnecessary;
4232 objects that large will be quite rare, so it is okay to use 'dup
4233 const16 SIZE trace' in those cases.
4235 Whatever we decide to do with 'trace16', we should at least leave
4236 opcode 0x30 reserved, to remain compatible with the customer who
4240 File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top
4242 Appendix G Target Descriptions
4243 ******************************
4245 One of the challenges of using GDB to debug embedded systems is that
4246 there are so many minor variants of each processor architecture in use.
4247 It is common practice for vendors to start with a standard processor
4248 core -- ARM, PowerPC, or MIPS, for example -- and then make changes to
4249 adapt it to a particular market niche. Some architectures have hundreds
4250 of variants, available from dozens of vendors. This leads to a number
4253 * With so many different customized processors, it is difficult for
4254 the GDB maintainers to keep up with the changes.
4255 * Since individual variants may have short lifetimes or limited
4256 audiences, it may not be worthwhile to carry information about
4257 every variant in the GDB source tree.
4258 * When GDB does support the architecture of the embedded system at
4259 hand, the task of finding the correct architecture name to give the
4260 'set architecture' command can be error-prone.
4262 To address these problems, the GDB remote protocol allows a target
4263 system to not only identify itself to GDB, but to actually describe its
4264 own features. This lets GDB support processor variants it has never
4265 seen before -- to the extent that the descriptions are accurate, and
4266 that GDB understands them.
4268 GDB must be linked with the Expat library to support XML target
4269 descriptions. *Note Expat::.
4273 * Retrieving Descriptions:: How descriptions are fetched from a target.
4274 * Target Description Format:: The contents of a target description.
4275 * Predefined Target Types:: Standard types available for target
4277 * Standard Target Features:: Features GDB knows about.
4280 File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions
4282 G.1 Retrieving Descriptions
4283 ===========================
4285 Target descriptions can be read from the target automatically, or
4286 specified by the user manually. The default behavior is to read the
4287 description from the target. GDB retrieves it via the remote protocol
4288 using 'qXfer' requests (*note qXfer: General Query Packets.). The ANNEX
4289 in the 'qXfer' packet will be 'target.xml'. The contents of the
4290 'target.xml' annex are an XML document, of the form described in *note
4291 Target Description Format::.
4293 Alternatively, you can specify a file to read for the target
4294 description. If a file is set, the target will not be queried. The
4295 commands to specify a file are:
4297 'set tdesc filename PATH'
4298 Read the target description from PATH.
4300 'unset tdesc filename'
4301 Do not read the XML target description from a file. GDB will use
4302 the description supplied by the current target.
4304 'show tdesc filename'
4305 Show the filename to read for a target description, if any.
4308 File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions
4310 G.2 Target Description Format
4311 =============================
4313 A target description annex is an XML (http://www.w3.org/XML/) document
4314 which complies with the Document Type Definition provided in the GDB
4315 sources in 'gdb/features/gdb-target.dtd'. This means you can use
4316 generally available tools like 'xmllint' to check that your feature
4317 descriptions are well-formed and valid. However, to help people
4318 unfamiliar with XML write descriptions for their targets, we also
4319 describe the grammar here.
4321 Target descriptions can identify the architecture of the remote
4322 target and (for some architectures) provide information about custom
4323 register sets. They can also identify the OS ABI of the remote target.
4324 GDB can use this information to autoconfigure for your target, or to
4325 warn you if you connect to an unsupported target.
4327 Here is a simple target description:
4329 <target version="1.0">
4330 <architecture>i386:x86-64</architecture>
4333 This minimal description only says that the target uses the x86-64
4336 A target description has the following overall form, with [ ] marking
4337 optional elements and ... marking repeatable elements. The elements are
4338 explained further below.
4340 <?xml version="1.0"?>
4341 <!DOCTYPE target SYSTEM "gdb-target.dtd">
4342 <target version="1.0">
4349 The description is generally insensitive to whitespace and line breaks,
4350 under the usual common-sense rules. The XML version declaration and
4351 document type declaration can generally be omitted (GDB does not require
4352 them), but specifying them may be useful for XML validation tools. The
4353 'version' attribute for '<target>' may also be omitted, but we recommend
4354 including it; if future versions of GDB use an incompatible revision of
4355 'gdb-target.dtd', they will detect and report the version mismatch.
4360 It can sometimes be valuable to split a target description up into
4361 several different annexes, either for organizational purposes, or to
4362 share files between different possible target descriptions. You can
4363 divide a description into multiple files by replacing any element of the
4364 target description with an inclusion directive of the form:
4366 <xi:include href="DOCUMENT"/>
4368 When GDB encounters an element of this form, it will retrieve the named
4369 XML DOCUMENT, and replace the inclusion directive with the contents of
4370 that document. If the current description was read using 'qXfer', then
4371 so will be the included document; DOCUMENT will be interpreted as the
4372 name of an annex. If the current description was read from a file, GDB
4373 will look for DOCUMENT as a file in the same directory where it found
4374 the original description.
4379 An '<architecture>' element has this form:
4381 <architecture>ARCH</architecture>
4383 ARCH is one of the architectures from the set accepted by 'set
4384 architecture' (*note Specifying a Debugging Target: Targets.).
4389 This optional field was introduced in GDB version 7.0. Previous
4390 versions of GDB ignore it.
4392 An '<osabi>' element has this form:
4394 <osabi>ABI-NAME</osabi>
4396 ABI-NAME is an OS ABI name from the same selection accepted by 'set osabi'
4397 (*note Configuring the Current ABI: ABI.).
4399 G.2.4 Compatible Architecture
4400 -----------------------------
4402 This optional field was introduced in GDB version 7.0. Previous
4403 versions of GDB ignore it.
4405 A '<compatible>' element has this form:
4407 <compatible>ARCH</compatible>
4409 ARCH is one of the architectures from the set accepted by 'set
4410 architecture' (*note Specifying a Debugging Target: Targets.).
4412 A '<compatible>' element is used to specify that the target is able
4413 to run binaries in some other than the main target architecture given by
4414 the '<architecture>' element. For example, on the Cell Broadband
4415 Engine, the main architecture is 'powerpc:common' or 'powerpc:common64',
4416 but the system is able to run binaries in the 'spu' architecture as
4417 well. The way to describe this capability with '<compatible>' is as
4420 <architecture>powerpc:common</architecture>
4421 <compatible>spu</compatible>
4426 Each '<feature>' describes some logical portion of the target system.
4427 Features are currently used to describe available CPU registers and the
4428 types of their contents. A '<feature>' element has this form:
4430 <feature name="NAME">
4435 Each feature's name should be unique within the description. The name
4436 of a feature does not matter unless GDB has some special knowledge of
4437 the contents of that feature; if it does, the feature should have its
4438 standard name. *Note Standard Target Features::.
4443 Any register's value is a collection of bits which GDB must interpret.
4444 The default interpretation is a two's complement integer, but other
4445 types can be requested by name in the register description. Some
4446 predefined types are provided by GDB (*note Predefined Target Types::),
4447 and the description can define additional composite types.
4449 Each type element must have an 'id' attribute, which gives a unique
4450 (within the containing '<feature>') name to the type. Types must be
4451 defined before they are used.
4453 Some targets offer vector registers, which can be treated as arrays
4454 of scalar elements. These types are written as '<vector>' elements,
4455 specifying the array element type, TYPE, and the number of elements,
4458 <vector id="ID" type="TYPE" count="COUNT"/>
4460 If a register's value is usefully viewed in multiple ways, define it
4461 with a union type containing the useful representations. The '<union>'
4462 element contains one or more '<field>' elements, each of which has a
4466 <field name="NAME" type="TYPE"/>
4470 If a register's value is composed from several separate values,
4471 define it with a structure type. There are two forms of the '<struct>'
4472 element; a '<struct>' element must either contain only bitfields or
4473 contain no bitfields. If the structure contains only bitfields, its
4474 total size in bytes must be specified, each bitfield must have an
4475 explicit start and end, and bitfields are automatically assigned an
4476 integer type. The field's START should be less than or equal to its
4477 END, and zero represents the least significant bit.
4479 <struct id="ID" size="SIZE">
4480 <field name="NAME" start="START" end="END"/>
4484 If the structure contains no bitfields, then each field has an
4485 explicit type, and no implicit padding is added.
4488 <field name="NAME" type="TYPE"/>
4492 If a register's value is a series of single-bit flags, define it with
4493 a flags type. The '<flags>' element has an explicit SIZE and contains
4494 one or more '<field>' elements. Each field has a NAME, a START, and an
4495 END. Only single-bit flags are supported.
4497 <flags id="ID" size="SIZE">
4498 <field name="NAME" start="START" end="END"/>
4505 Each register is represented as an element with this form:
4510 [save-restore="SAVE-RESTORE"]
4514 The components are as follows:
4517 The register's name; it must be unique within the target
4521 The register's size, in bits.
4524 The register's number. If omitted, a register's number is one
4525 greater than that of the previous register (either in the current
4526 feature or in a preceding feature); the first register in the
4527 target description defaults to zero. This register number is used
4528 to read or write the register; e.g. it is used in the remote 'p'
4529 and 'P' packets, and registers appear in the 'g' and 'G' packets in
4530 order of increasing register number.
4533 Whether the register should be preserved across inferior function
4534 calls; this must be either 'yes' or 'no'. The default is 'yes',
4535 which is appropriate for most registers except for some system
4536 control registers; this is not related to the target's ABI.
4539 The type of the register. It may be a predefined type, a type
4540 defined in the current feature, or one of the special types 'int'
4541 and 'float'. 'int' is an integer type of the correct size for
4542 BITSIZE, and 'float' is a floating point type (in the
4543 architecture's normal floating point format) of the correct size
4544 for BITSIZE. The default is 'int'.
4547 The register group to which this register belongs. It must be
4548 either 'general', 'float', or 'vector'. If no GROUP is specified,
4549 GDB will not display the register in 'info registers'.
4552 File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions
4554 G.3 Predefined Target Types
4555 ===========================
4557 Type definitions in the self-description can build up composite types
4558 from basic building blocks, but can not define fundamental types.
4559 Instead, standard identifiers are provided by GDB for the fundamental
4560 types. The currently supported types are:
4567 Signed integer types holding the specified number of bits.
4574 Unsigned integer types holding the specified number of bits.
4578 Pointers to unspecified code and data. The program counter and any
4579 dedicated return address register may be marked as code pointers;
4580 printing a code pointer converts it into a symbolic address. The
4581 stack pointer and any dedicated address registers may be marked as
4585 Single precision IEEE floating point.
4588 Double precision IEEE floating point.
4591 The 12-byte extended precision format used by ARM FPA registers.
4594 The 10-byte extended precision format used by x87 registers.
4597 32bit EFLAGS register used by x86.
4600 32bit MXCSR register used by x86.
4603 File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions
4605 G.4 Standard Target Features
4606 ============================
4608 A target description must contain either no registers or all the
4609 target's registers. If the description contains no registers, then GDB
4610 will assume a default register layout, selected based on the
4611 architecture. If the description contains any registers, the default
4612 layout will not be used; the standard registers must be described in the
4613 target description, in such a way that GDB can recognize them.
4615 This is accomplished by giving specific names to feature elements
4616 which contain standard registers. GDB will look for features with those
4617 names and verify that they contain the expected registers; if any known
4618 feature is missing required registers, or if any required feature is
4619 missing, GDB will reject the target description. You can add additional
4620 registers to any of the standard features -- GDB will display them just
4621 as if they were added to an unrecognized feature.
4623 This section lists the known features and their expected contents.
4624 Sample XML documents for these features are included in the GDB source
4625 tree, in the directory 'gdb/features'.
4627 Names recognized by GDB should include the name of the company or
4628 organization which selected the name, and the overall architecture to
4629 which the feature applies; so e.g. the feature containing ARM core
4630 registers is named 'org.gnu.gdb.arm.core'.
4632 The names of registers are not case sensitive for the purpose of
4633 recognizing standard features, but GDB will only display registers using
4634 the capitalization used in the description.
4638 * AArch64 Features::
4643 * Nios II Features::
4644 * PowerPC Features::
4645 * S/390 and System z Features::
4649 File: gdb.info, Node: AArch64 Features, Next: ARM Features, Up: Standard Target Features
4651 G.4.1 AArch64 Features
4652 ----------------------
4654 The 'org.gnu.gdb.aarch64.core' feature is required for AArch64 targets.
4655 It should contain registers 'x0' through 'x30', 'sp', 'pc', and 'cpsr'.
4657 The 'org.gnu.gdb.aarch64.fpu' feature is optional. If present, it
4658 should contain registers 'v0' through 'v31', 'fpsr', and 'fpcr'.
4661 File: gdb.info, Node: ARM Features, Next: i386 Features, Prev: AArch64 Features, Up: Standard Target Features
4666 The 'org.gnu.gdb.arm.core' feature is required for non-M-profile ARM
4667 targets. It should contain registers 'r0' through 'r13', 'sp', 'lr',
4670 For M-profile targets (e.g. Cortex-M3), the 'org.gnu.gdb.arm.core'
4671 feature is replaced by 'org.gnu.gdb.arm.m-profile'. It should contain
4672 registers 'r0' through 'r13', 'sp', 'lr', 'pc', and 'xpsr'.
4674 The 'org.gnu.gdb.arm.fpa' feature is optional. If present, it should
4675 contain registers 'f0' through 'f7' and 'fps'.
4677 The 'org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it
4678 should contain at least registers 'wR0' through 'wR15' and 'wCGR0'
4679 through 'wCGR3'. The 'wCID', 'wCon', 'wCSSF', and 'wCASF' registers are
4682 The 'org.gnu.gdb.arm.vfp' feature is optional. If present, it should
4683 contain at least registers 'd0' through 'd15'. If they are present,
4684 'd16' through 'd31' should also be included. GDB will synthesize the
4685 single-precision registers from halves of the double-precision
4688 The 'org.gnu.gdb.arm.neon' feature is optional. It does not need to
4689 contain registers; it instructs GDB to display the VFP double-precision
4690 registers as vectors and to synthesize the quad-precision registers from
4691 pairs of double-precision registers. If this feature is present,
4692 'org.gnu.gdb.arm.vfp' must also be present and include 32
4693 double-precision registers.
4696 File: gdb.info, Node: i386 Features, Next: MIPS Features, Prev: ARM Features, Up: Standard Target Features
4701 The 'org.gnu.gdb.i386.core' feature is required for i386/amd64 targets.
4702 It should describe the following registers:
4704 - 'eax' through 'edi' plus 'eip' for i386
4705 - 'rax' through 'r15' plus 'rip' for amd64
4706 - 'eflags', 'cs', 'ss', 'ds', 'es', 'fs', 'gs'
4707 - 'st0' through 'st7'
4708 - 'fctrl', 'fstat', 'ftag', 'fiseg', 'fioff', 'foseg', 'fooff' and
4711 The register sets may be different, depending on the target.
4713 The 'org.gnu.gdb.i386.sse' feature is optional. It should describe
4716 - 'xmm0' through 'xmm7' for i386
4717 - 'xmm0' through 'xmm15' for amd64
4720 The 'org.gnu.gdb.i386.avx' feature is optional and requires the
4721 'org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits
4724 - 'ymm0h' through 'ymm7h' for i386
4725 - 'ymm0h' through 'ymm15h' for amd64
4727 The 'org.gnu.gdb.i386.mpx' is an optional feature representing
4728 Intel(R) Memory Protection Extension (MPX). It should describe the
4729 following registers:
4731 - 'bnd0raw' through 'bnd3raw' for i386 and amd64.
4732 - 'bndcfgu' and 'bndstatus' for i386 and amd64.
4734 The 'org.gnu.gdb.i386.linux' feature is optional. It should describe
4735 a single register, 'orig_eax'.
4737 The 'org.gnu.gdb.i386.avx512' feature is optional and requires the
4738 'org.gnu.gdb.i386.avx' feature. It should describe additional XMM
4741 - 'xmm16h' through 'xmm31h', only valid for amd64.
4743 It should describe the upper 128 bits of additional YMM registers:
4745 - 'ymm16h' through 'ymm31h', only valid for amd64.
4747 It should describe the upper 256 bits of ZMM registers:
4749 - 'zmm0h' through 'zmm7h' for i386.
4750 - 'zmm0h' through 'zmm15h' for amd64.
4752 It should describe the additional ZMM registers:
4754 - 'zmm16h' through 'zmm31h', only valid for amd64.
4757 File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: i386 Features, Up: Standard Target Features
4762 The 'org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It
4763 should contain registers 'r0' through 'r31', 'lo', 'hi', and 'pc'. They
4764 may be 32-bit or 64-bit depending on the target.
4766 The 'org.gnu.gdb.mips.cp0' feature is also required. It should
4767 contain at least the 'status', 'badvaddr', and 'cause' registers. They
4768 may be 32-bit or 64-bit depending on the target.
4770 The 'org.gnu.gdb.mips.fpu' feature is currently required, though it
4771 may be optional in a future version of GDB. It should contain registers
4772 'f0' through 'f31', 'fcsr', and 'fir'. They may be 32-bit or 64-bit
4773 depending on the target.
4775 The 'org.gnu.gdb.mips.dsp' feature is optional. It should contain
4776 registers 'hi1' through 'hi3', 'lo1' through 'lo3', and 'dspctl'. The
4777 'dspctl' register should be 32-bit and the rest may be 32-bit or 64-bit
4778 depending on the target.
4780 The 'org.gnu.gdb.mips.linux' feature is optional. It should contain
4781 a single register, 'restart', which is used by the Linux kernel to
4782 control restartable syscalls.
4785 File: gdb.info, Node: M68K Features, Next: Nios II Features, Prev: MIPS Features, Up: Standard Target Features
4790 ''org.gnu.gdb.m68k.core''
4791 ''org.gnu.gdb.coldfire.core''
4792 ''org.gnu.gdb.fido.core''
4793 One of those features must be always present. The feature that is
4794 present determines which flavor of m68k is used. The feature that
4795 is present should contain registers 'd0' through 'd7', 'a0' through
4796 'a5', 'fp', 'sp', 'ps' and 'pc'.
4798 ''org.gnu.gdb.coldfire.fp''
4799 This feature is optional. If present, it should contain registers
4800 'fp0' through 'fp7', 'fpcontrol', 'fpstatus' and 'fpiaddr'.
4803 File: gdb.info, Node: Nios II Features, Next: PowerPC Features, Prev: M68K Features, Up: Standard Target Features
4805 G.4.6 Nios II Features
4806 ----------------------
4808 The 'org.gnu.gdb.nios2.cpu' feature is required for Nios II targets. It
4809 should contain the 32 core registers ('zero', 'at', 'r2' through 'r23',
4810 'et' through 'ra'), 'pc', and the 16 control registers ('status' through
4814 File: gdb.info, Node: PowerPC Features, Next: S/390 and System z Features, Prev: Nios II Features, Up: Standard Target Features
4816 G.4.7 PowerPC Features
4817 ----------------------
4819 The 'org.gnu.gdb.power.core' feature is required for PowerPC targets.
4820 It should contain registers 'r0' through 'r31', 'pc', 'msr', 'cr', 'lr',
4821 'ctr', and 'xer'. They may be 32-bit or 64-bit depending on the target.
4823 The 'org.gnu.gdb.power.fpu' feature is optional. It should contain
4824 registers 'f0' through 'f31' and 'fpscr'.
4826 The 'org.gnu.gdb.power.altivec' feature is optional. It should
4827 contain registers 'vr0' through 'vr31', 'vscr', and 'vrsave'.
4829 The 'org.gnu.gdb.power.vsx' feature is optional. It should contain
4830 registers 'vs0h' through 'vs31h'. GDB will combine these registers with
4831 the floating point registers ('f0' through 'f31') and the altivec
4832 registers ('vr0' through 'vr31') to present the 128-bit wide registers
4833 'vs0' through 'vs63', the set of vector registers for POWER7.
4835 The 'org.gnu.gdb.power.spe' feature is optional. It should contain
4836 registers 'ev0h' through 'ev31h', 'acc', and 'spefscr'. SPE targets
4837 should provide 32-bit registers in 'org.gnu.gdb.power.core' and provide
4838 the upper halves in 'ev0h' through 'ev31h'. GDB will combine these to
4839 present registers 'ev0' through 'ev31' to the user.
4842 File: gdb.info, Node: S/390 and System z Features, Next: TIC6x Features, Prev: PowerPC Features, Up: Standard Target Features
4844 G.4.8 S/390 and System z Features
4845 ---------------------------------
4847 The 'org.gnu.gdb.s390.core' feature is required for S/390 and System z
4848 targets. It should contain the PSW and the 16 general registers. In
4849 particular, System z targets should provide the 64-bit registers 'pswm',
4850 'pswa', and 'r0' through 'r15'. S/390 targets should provide the 32-bit
4851 versions of these registers. A System z target that runs in 31-bit
4852 addressing mode should provide 32-bit versions of 'pswm' and 'pswa', as
4853 well as the general register's upper halves 'r0h' through 'r15h', and
4854 their lower halves 'r0l' through 'r15l'.
4856 The 'org.gnu.gdb.s390.fpr' feature is required. It should contain
4857 the 64-bit registers 'f0' through 'f15', and 'fpc'.
4859 The 'org.gnu.gdb.s390.acr' feature is required. It should contain
4860 the 32-bit registers 'acr0' through 'acr15'.
4862 The 'org.gnu.gdb.s390.linux' feature is optional. It should contain
4863 the register 'orig_r2', which is 64-bit wide on System z targets and
4864 32-bit otherwise. In addition, the feature may contain the 'last_break'
4865 register, whose width depends on the addressing mode, as well as the
4866 'system_call' register, which is always 32-bit wide.
4868 The 'org.gnu.gdb.s390.tdb' feature is optional. It should contain
4869 the 64-bit registers 'tdb0', 'tac', 'tct', 'atia', and 'tr0' through
4873 File: gdb.info, Node: TIC6x Features, Prev: S/390 and System z Features, Up: Standard Target Features
4875 G.4.9 TMS320C6x Features
4876 ------------------------
4878 The 'org.gnu.gdb.tic6x.core' feature is required for TMS320C6x targets.
4879 It should contain registers 'A0' through 'A15', registers 'B0' through
4880 'B15', 'CSR' and 'PC'.
4882 The 'org.gnu.gdb.tic6x.gp' feature is optional. It should contain
4883 registers 'A16' through 'A31' and 'B16' through 'B31'.
4885 The 'org.gnu.gdb.tic6x.c6xp' feature is optional. It should contain
4886 registers 'TSR', 'ILC' and 'RILC'.
4889 File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top
4891 Appendix H Operating System Information
4892 ***************************************
4898 Users of GDB often wish to obtain information about the state of the
4899 operating system running on the target--for example the list of
4900 processes, or the list of open files. This section describes the
4901 mechanism that makes it possible. This mechanism is similar to the
4902 target features mechanism (*note Target Descriptions::), but focuses on
4903 a different aspect of target.
4905 Operating system information is retrived from the target via the
4906 remote protocol, using 'qXfer' requests (*note qXfer osdata read::).
4907 The object name in the request should be 'osdata', and the ANNEX
4908 identifies the data to be fetched.
4911 File: gdb.info, Node: Process list, Up: Operating System Information
4916 When requesting the process list, the ANNEX field in the 'qXfer' request
4917 should be 'processes'. The returned data is an XML document. The
4918 formal syntax of this document is defined in 'gdb/features/osdata.dtd'.
4920 An example document is:
4922 <?xml version="1.0"?>
4923 <!DOCTYPE target SYSTEM "osdata.dtd">
4924 <osdata type="processes">
4926 <column name="pid">1</column>
4927 <column name="user">root</column>
4928 <column name="command">/sbin/init</column>
4929 <column name="cores">1,2,3</column>
4933 Each item should include a column whose name is 'pid'. The value of
4934 that column should identify the process on the target. The 'user' and
4935 'command' columns are optional, and will be displayed by GDB. The
4936 'cores' column, if present, should contain a comma-separated list of
4937 cores that this process is running on. Target may provide additional
4938 columns, which GDB currently ignores.
4941 File: gdb.info, Node: Trace File Format, Next: Index Section Format, Prev: Operating System Information, Up: Top
4943 Appendix I Trace File Format
4944 ****************************
4946 The trace file comes in three parts: a header, a textual description
4947 section, and a trace frame section with binary data.
4949 The header has the form '\x7fTRACE0\n'. The first byte is '0x7f' so
4950 as to indicate that the file contains binary data, while the '0' is a
4951 version number that may have different values in the future.
4953 The description section consists of multiple lines of ASCII text
4954 separated by newline characters ('0xa'). The lines may include a
4955 variety of optional descriptive or context-setting information, such as
4956 tracepoint definitions or register set size. GDB will ignore any line
4957 that it does not recognize. An empty line marks the end of this
4960 The trace frame section consists of a number of consecutive frames.
4961 Each frame begins with a two-byte tracepoint number, followed by a
4962 four-byte size giving the amount of data in the frame. The data in the
4963 frame consists of a number of blocks, each introduced by a character
4964 indicating its type (at least register, memory, and trace state
4965 variable). The data in this section is raw binary, not a hexadecimal or
4966 other encoding; its endianness matches the target's endianness.
4969 Register block. The number and ordering of bytes matches that of a
4970 'g' packet in the remote protocol. Note that these are the actual
4971 bytes, in target order and GDB register order, not a hexadecimal
4974 'M ADDRESS LENGTH BYTES...'
4975 Memory block. This is a contiguous block of memory, at the 8-byte
4976 address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH
4980 Trace state variable block. This records the 8-byte signed value
4981 VALUE of trace state variable numbered NUMBER.
4983 Future enhancements of the trace file format may include additional
4987 File: gdb.info, Node: Index Section Format, Next: Man Pages, Prev: Trace File Format, Up: Top
4989 Appendix J '.gdb_index' section format
4990 **************************************
4992 This section documents the index section that is created by 'save
4993 gdb-index' (*note Index Files::). The index section is DWARF-specific;
4994 some knowledge of DWARF is assumed in this description.
4996 The mapped index file format is designed to be directly 'mmap'able on
4997 any architecture. In most cases, a datum is represented using a
4998 little-endian 32-bit integer value, called an 'offset_type'. Big endian
4999 machines must byte-swap the values before using them. Exceptions to
5000 this rule are noted. The data is laid out such that alignment is always
5003 A mapped index consists of several areas, laid out in order.
5005 1. The file header. This is a sequence of values, of 'offset_type'
5006 unless otherwise noted:
5008 1. The version number, currently 8. Versions 1, 2 and 3 are
5009 obsolete. Version 4 uses a different hashing function from
5010 versions 5 and 6. Version 6 includes symbols for inlined
5011 functions, whereas versions 4 and 5 do not. Version 7 adds
5012 attributes to the CU indices in the symbol table. Version 8
5013 specifies that symbols from DWARF type units
5014 ('DW_TAG_type_unit') refer to the type unit's symbol table and
5015 not the compilation unit ('DW_TAG_comp_unit') using the type.
5017 GDB will only read version 4, 5, or 6 indices by specifying
5018 'set use-deprecated-index-sections on'. GDB has a workaround
5019 for potentially broken version 7 indices so it is currently
5020 not flagged as deprecated.
5022 2. The offset, from the start of the file, of the CU list.
5024 3. The offset, from the start of the file, of the types CU list.
5025 Note that this area can be empty, in which case this offset
5026 will be equal to the next offset.
5028 4. The offset, from the start of the file, of the address area.
5030 5. The offset, from the start of the file, of the symbol table.
5032 6. The offset, from the start of the file, of the constant pool.
5034 2. The CU list. This is a sequence of pairs of 64-bit little-endian
5035 values, sorted by the CU offset. The first element in each pair is
5036 the offset of a CU in the '.debug_info' section. The second
5037 element in each pair is the length of that CU. References to a CU
5038 elsewhere in the map are done using a CU index, which is just the
5039 0-based index into this table. Note that if there are type CUs,
5040 then conceptually CUs and type CUs form a single list for the
5041 purposes of CU indices.
5043 3. The types CU list. This is a sequence of triplets of 64-bit
5044 little-endian values. In a triplet, the first value is the CU
5045 offset, the second value is the type offset in the CU, and the
5046 third value is the type signature. The types CU list is not
5049 4. The address area. The address area consists of a sequence of
5050 address entries. Each address entry has three elements:
5052 1. The low address. This is a 64-bit little-endian value.
5054 2. The high address. This is a 64-bit little-endian value. Like
5055 'DW_AT_high_pc', the value is one byte beyond the end.
5057 3. The CU index. This is an 'offset_type' value.
5059 5. The symbol table. This is an open-addressed hash table. The size
5060 of the hash table is always a power of 2.
5062 Each slot in the hash table consists of a pair of 'offset_type'
5063 values. The first value is the offset of the symbol's name in the
5064 constant pool. The second value is the offset of the CU vector in
5067 If both values are 0, then this slot in the hash table is empty.
5068 This is ok because while 0 is a valid constant pool index, it
5069 cannot be a valid index for both a string and a CU vector.
5071 The hash value for a table entry is computed by applying an
5072 iterative hash function to the symbol's name. Starting with an
5073 initial value of 'r = 0', each (unsigned) character 'c' in the
5074 string is incorporated into the hash using the formula depending on
5078 The formula is 'r = r * 67 + c - 113'.
5081 The formula is 'r = r * 67 + tolower (c) - 113'.
5083 The terminating '\0' is not incorporated into the hash.
5085 The step size used in the hash table is computed via '((hash * 17)
5086 & (size - 1)) | 1', where 'hash' is the hash value, and 'size' is
5087 the size of the hash table. The step size is used to find the next
5088 candidate slot when handling a hash collision.
5090 The names of C++ symbols in the hash table are canonicalized. We
5091 don't currently have a simple description of the canonicalization
5092 algorithm; if you intend to create new index sections, you must
5095 6. The constant pool. This is simply a bunch of bytes. It is
5096 organized so that alignment is correct: CU vectors are stored
5097 first, followed by strings.
5099 A CU vector in the constant pool is a sequence of 'offset_type'
5100 values. The first value is the number of CU indices in the vector.
5101 Each subsequent value is the index and symbol attributes of a CU in
5102 the CU list. This element in the hash table is used to indicate
5103 which CUs define the symbol and how the symbol is used. See below
5104 for the format of each CU index+attributes entry.
5106 A string in the constant pool is zero-terminated.
5108 Attributes were added to CU index values in '.gdb_index' version 7.
5109 If a symbol has multiple uses within a CU then there is one CU
5110 index+attributes value for each use.
5112 The format of each CU index+attributes entry is as follows (bit 0 =
5116 This is the index of the CU in the CU list.
5118 These bits are reserved for future purposes and must be zero.
5120 The kind of the symbol in the CU.
5123 This value is reserved and should not be used. By reserving
5124 zero the full 'offset_type' value is backwards compatible with
5125 previous versions of the index.
5127 The symbol is a type.
5129 The symbol is a variable or an enum value.
5131 The symbol is a function.
5133 Any other kind of symbol.
5135 These values are reserved.
5138 This bit is zero if the value is global and one if it is static.
5140 The determination of whether a symbol is global or static is
5141 complicated. The authorative reference is the file 'dwarf2read.c'
5144 This pseudo-code describes the computation of a symbol's kind and
5145 global/static attributes in the index.
5147 is_external = get_attribute (die, DW_AT_external);
5148 language = get_attribute (cu_die, DW_AT_language);
5151 case DW_TAG_typedef:
5152 case DW_TAG_base_type:
5153 case DW_TAG_subrange_type:
5157 case DW_TAG_enumerator:
5159 is_static = (language != CPLUS && language != JAVA);
5161 case DW_TAG_subprogram:
5163 is_static = ! (is_external || language == ADA);
5165 case DW_TAG_constant:
5167 is_static = ! is_external;
5169 case DW_TAG_variable:
5171 is_static = ! is_external;
5173 case DW_TAG_namespace:
5177 case DW_TAG_class_type:
5178 case DW_TAG_interface_type:
5179 case DW_TAG_structure_type:
5180 case DW_TAG_union_type:
5181 case DW_TAG_enumeration_type:
5183 is_static = (language != CPLUS && language != JAVA);
5190 File: gdb.info, Node: Man Pages, Next: Copying, Prev: Index Section Format, Up: Top
5192 Appendix K Manual pages
5193 ***********************
5197 * gdb man:: The GNU Debugger man page
5198 * gdbserver man:: Remote Server for the GNU Debugger man page
5199 * gcore man:: Generate a core file of a running program
5200 * gdbinit man:: gdbinit scripts
5203 File: gdb.info, Node: gdb man, Next: gdbserver man, Up: Man Pages
5208 gdb ['-help'] ['-nh'] ['-nx'] ['-q'] ['-batch'] ['-cd='DIR] ['-f']
5209 ['-b' BPS] ['-tty='DEV] ['-s' SYMFILE] ['-e' PROG] ['-se' PROG]
5210 ['-c' CORE] ['-p' PROCID] ['-x' CMDS] ['-d' DIR] [PROG|PROG PROCID|PROG
5213 The purpose of a debugger such as GDB is to allow you to see what is
5214 going on "inside" another program while it executes - or what another
5215 program was doing at the moment it crashed.
5217 GDB can do four main kinds of things (plus other things in support of
5218 these) to help you catch bugs in the act:
5220 * Start your program, specifying anything that might affect its
5223 * Make your program stop on specified conditions.
5225 * Examine what has happened, when your program has stopped.
5227 * Change things in your program, so you can experiment with
5228 correcting the effects of one bug and go on to learn about another.
5230 You can use GDB to debug programs written in C, C++, Fortran and
5233 GDB is invoked with the shell command 'gdb'. Once started, it reads
5234 commands from the terminal until you tell it to exit with the GDB
5235 command 'quit'. You can get online help from GDB itself by using the
5238 You can run 'gdb' with no arguments or options; but the most usual
5239 way to start GDB is with one argument or two, specifying an executable
5240 program as the argument:
5244 You can also start with both an executable program and a core file
5249 You can, instead, specify a process ID as a second argument, if you
5250 want to debug a running process:
5255 would attach GDB to process '1234' (unless you also have a file named
5256 '1234'; GDB does check for a core file first). With option '-p' you can
5257 omit the PROGRAM filename.
5259 Here are some of the most frequently needed GDB commands:
5261 'break [FILE:]FUNCTIOP'
5262 Set a breakpoint at FUNCTION (in FILE).
5265 Start your program (with ARGLIST, if specified).
5268 Backtrace: display the program stack.
5271 Display the value of an expression.
5274 Continue running your program (after stopping, e.g. at a
5278 Execute next program line (after stopping); step _over_ any
5279 function calls in the line.
5281 'edit [FILE:]FUNCTION'
5282 look at the program line where it is presently stopped.
5284 'list [FILE:]FUNCTION'
5285 type the text of the program in the vicinity of where it is
5289 Execute next program line (after stopping); step _into_ any
5290 function calls in the line.
5293 Show information about GDB command NAME, or general information
5299 Any arguments other than options specify an executable file and core
5300 file (or process ID); that is, the first argument encountered with no
5301 associated option flag is equivalent to a '-se' option, and the second,
5302 if any, is equivalent to a '-c' option if it's the name of a file. Many
5303 options have both long and short forms; both are shown here. The long
5304 forms are also recognized if you truncate them, so long as enough of the
5305 option is present to be unambiguous. (If you prefer, you can flag
5306 option arguments with '+' rather than '-', though we illustrate the more
5309 All the options and command line arguments you give are processed in
5310 sequential order. The order makes a difference when the '-x' option is
5315 List all options, with brief explanations.
5319 Read symbol table from file FILE.
5322 Enable writing into executable and core files.
5326 Use file FILE as the executable file to execute when appropriate,
5327 and for examining pure data in conjunction with a core dump.
5330 Read symbol table from file FILE and use it as the executable file.
5334 Use file FILE as a core dump to examine.
5338 Execute GDB commands from file FILE.
5341 Execute given GDB COMMAND.
5343 '-directory=DIRECTORY'
5345 Add DIRECTORY to the path to search for source files.
5348 Do not execute commands from '~/.gdbinit'.
5352 Do not execute commands from any '.gdbinit' initialization files.
5356 "Quiet". Do not print the introductory and copyright messages.
5357 These messages are also suppressed in batch mode.
5360 Run in batch mode. Exit with status '0' after processing all the
5361 command files specified with '-x' (and '.gdbinit', if not
5362 inhibited). Exit with nonzero status if an error occurs in
5363 executing the GDB commands in the command files.
5365 Batch mode may be useful for running GDB as a filter, for example
5366 to download and run a program on another computer; in order to make
5367 this more useful, the message
5369 Program exited normally.
5371 (which is ordinarily issued whenever a program running under GDB
5372 control terminates) is not issued when running in batch mode.
5375 Run GDB using DIRECTORY as its working directory, instead of the
5380 Emacs sets this option when it runs GDB as a subprocess. It tells
5381 GDB to output the full file name and line number in a standard,
5382 recognizable fashion each time a stack frame is displayed (which
5383 includes each time the program stops). This recognizable format
5384 looks like two '\032' characters, followed by the file name, line
5385 number and character position separated by colons, and a newline.
5386 The Emacs-to-GDB interface program uses the two '\032' characters
5387 as a signal to display the source code for the frame.
5390 Set the line speed (baud rate or bits per second) of any serial
5391 interface used by GDB for remote debugging.
5394 Run using DEVICE for your program's standard input and output.
5397 File: gdb.info, Node: gdbserver man, Next: gcore man, Prev: gdb man, Up: Man Pages
5402 gdbserver COMM PROG [ARGS...]
5404 gdbserver -attach COMM PID
5406 gdbserver -multi COMM
5408 'gdbserver' is a program that allows you to run GDB on a different
5409 machine than the one which is running the program being debugged.
5411 Usage (server (target) side)
5412 ----------------------------
5414 First, you need to have a copy of the program you want to debug put onto
5415 the target system. The program can be stripped to save space if needed,
5416 as 'gdbserver' doesn't care about symbols. All symbol handling is taken
5417 care of by the GDB running on the host system.
5419 To use the server, you log on to the target system, and run the
5420 'gdbserver' program. You must tell it (a) how to communicate with GDB,
5421 (b) the name of your program, and (c) its arguments. The general syntax
5424 target> gdbserver COMM PROGRAM [ARGS ...]
5426 For example, using a serial port, you might say:
5428 target> gdbserver /dev/com1 emacs foo.txt
5430 This tells 'gdbserver' to debug emacs with an argument of foo.txt,
5431 and to communicate with GDB via '/dev/com1'. 'gdbserver' now waits
5432 patiently for the host GDB to communicate with it.
5434 To use a TCP connection, you could say:
5436 target> gdbserver host:2345 emacs foo.txt
5438 This says pretty much the same thing as the last example, except that
5439 we are going to communicate with the 'host' GDB via TCP. The 'host:2345'
5440 argument means that we are expecting to see a TCP connection from 'host'
5441 to local TCP port 2345. (Currently, the 'host' part is ignored.) You
5442 can choose any number you want for the port number as long as it does
5443 not conflict with any existing TCP ports on the target system. This
5444 same port number must be used in the host GDBs 'target remote' command,
5445 which will be described shortly. Note that if you chose a port number
5446 that conflicts with another service, 'gdbserver' will print an error
5449 'gdbserver' can also attach to running programs. This is
5450 accomplished via the '--attach' argument. The syntax is:
5452 target> gdbserver --attach COMM PID
5454 PID is the process ID of a currently running process. It isn't
5455 necessary to point 'gdbserver' at a binary for the running process.
5457 To start 'gdbserver' without supplying an initial command to run or
5458 process ID to attach, use the '--multi' command line option. In such
5459 case you should connect using 'target extended-remote' to start the
5460 program you want to debug.
5462 target> gdbserver --multi COMM
5467 You need an unstripped copy of the target program on your host system,
5468 since GDB needs to examine it's symbol tables and such. Start up GDB as
5469 you normally would, with the target program as the first argument. (You
5470 may need to use the '--baud' option if the serial line is running at
5471 anything except 9600 baud.) That is 'gdb TARGET-PROG', or 'gdb --baud
5472 BAUD TARGET-PROG'. After that, the only new command you need to know
5473 about is 'target remote' (or 'target extended-remote'). Its argument is
5474 either a device name (usually a serial device, like '/dev/ttyb'), or a
5475 'HOST:PORT' descriptor. For example:
5477 (gdb) target remote /dev/ttyb
5479 communicates with the server via serial line '/dev/ttyb', and:
5481 (gdb) target remote the-target:2345
5483 communicates via a TCP connection to port 2345 on host 'the-target',
5484 where you previously started up 'gdbserver' with the same port number.
5485 Note that for TCP connections, you must start up 'gdbserver' prior to
5486 using the 'target remote' command, otherwise you may get an error that
5487 looks something like 'Connection refused'.
5489 'gdbserver' can also debug multiple inferiors at once, described in
5490 *note Inferiors and Programs::. In such case use the 'extended-remote'
5491 GDB command variant:
5493 (gdb) target extended-remote the-target:2345
5495 The 'gdbserver' option '--multi' may or may not be used in such case.
5497 There are three different modes for invoking 'gdbserver':
5499 * Debug a specific program specified by its program name:
5501 gdbserver COMM PROG [ARGS...]
5503 The COMM parameter specifies how should the server communicate with
5504 GDB; it is either a device name (to use a serial line), a TCP port
5505 number (':1234'), or '-' or 'stdio' to use stdin/stdout of
5506 'gdbserver'. Specify the name of the program to debug in PROG.
5507 Any remaining arguments will be passed to the program verbatim.
5508 When the program exits, GDB will close the connection, and
5509 'gdbserver' will exit.
5511 * Debug a specific program by specifying the process ID of a running
5514 gdbserver --attach COMM PID
5516 The COMM parameter is as described above. Supply the process ID of
5517 a running program in PID; GDB will do everything else. Like with
5518 the previous mode, when the process PID exits, GDB will close the
5519 connection, and 'gdbserver' will exit.
5521 * Multi-process mode - debug more than one program/process:
5523 gdbserver --multi COMM
5525 In this mode, GDB can instruct 'gdbserver' which command(s) to run.
5526 Unlike the other 2 modes, GDB will not close the connection when a
5527 process being debugged exits, so you can debug several processes in
5530 In each of the modes you may specify these options:
5533 List all options, with brief explanations.
5536 This option causes 'gdbserver' to print its version number and
5540 'gdbserver' will attach to a running program. The syntax is:
5542 target> gdbserver --attach COMM PID
5544 PID is the process ID of a currently running process. It isn't
5545 necessary to point 'gdbserver' at a binary for the running process.
5548 To start 'gdbserver' without supplying an initial command to run or
5549 process ID to attach, use this command line option. Then you can
5550 connect using 'target extended-remote' and start the program you
5551 want to debug. The syntax is:
5553 target> gdbserver --multi COMM
5556 Instruct 'gdbserver' to display extra status information about the
5557 debugging process. This option is intended for 'gdbserver'
5558 development and for bug reports to the developers.
5561 Instruct 'gdbserver' to display remote protocol debug output. This
5562 option is intended for 'gdbserver' development and for bug reports
5565 '--debug-format=option1[,option2,...]'
5566 Instruct 'gdbserver' to include extra information in each line of
5567 debugging output. *Note Other Command-Line Arguments for
5571 Specify a wrapper to launch programs for debugging. The option
5572 should be followed by the name of the wrapper, then any
5573 command-line arguments to pass to the wrapper, then '--' indicating
5574 the end of the wrapper arguments.
5577 By default, 'gdbserver' keeps the listening TCP port open, so that
5578 additional connections are possible. However, if you start
5579 'gdbserver' with the '--once' option, it will stop listening for
5580 any further connection attempts after connecting to the first GDB
5584 File: gdb.info, Node: gcore man, Next: gdbinit man, Prev: gdbserver man, Up: Man Pages
5589 gcore [-o FILENAME] PID
5591 Generate a core dump of a running program with process ID PID.
5592 Produced file is equivalent to a kernel produced core file as if the
5593 process crashed (and if 'ulimit -c' were used to set up an appropriate
5594 core dump limit). Unlike after a crash, after 'gcore' the program
5595 remains running without any change.
5598 The optional argument FILENAME specifies the file name where to put
5599 the core dump. If not specified, the file name defaults to
5600 'core.PID', where PID is the running program process ID.
5603 File: gdb.info, Node: gdbinit man, Prev: gcore man, Up: Man Pages
5613 These files contain GDB commands to automatically execute during GDB
5614 startup. The lines of contents are canned sequences of commands,
5615 described in *note Sequences::.
5617 Please read more in *note Startup::.
5619 '(not enabled with --with-system-gdbinit during compilation)'
5620 System-wide initialization file. It is executed unless user
5621 specified GDB option '-nx' or '-n'. See more in *note System-wide
5625 User initialization file. It is executed unless user specified GDB
5626 options '-nx', '-n' or '-nh'.
5629 Initialization file for current directory. It may need to be
5630 enabled with GDB security command 'set auto-load local-gdbinit'.
5631 See more in *note Init File in the Current Directory::.
5634 File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Man Pages, Up: Top
5636 Appendix L GNU GENERAL PUBLIC LICENSE
5637 *************************************
5639 Version 3, 29 June 2007
5641 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
5643 Everyone is permitted to copy and distribute verbatim copies of this
5644 license document, but changing it is not allowed.
5649 The GNU General Public License is a free, copyleft license for software
5650 and other kinds of works.
5652 The licenses for most software and other practical works are designed
5653 to take away your freedom to share and change the works. By contrast,
5654 the GNU General Public License is intended to guarantee your freedom to
5655 share and change all versions of a program--to make sure it remains free
5656 software for all its users. We, the Free Software Foundation, use the
5657 GNU General Public License for most of our software; it applies also to
5658 any other work released this way by its authors. You can apply it to
5661 When we speak of free software, we are referring to freedom, not
5662 price. Our General Public Licenses are designed to make sure that you
5663 have the freedom to distribute copies of free software (and charge for
5664 them if you wish), that you receive source code or can get it if you
5665 want it, that you can change the software or use pieces of it in new
5666 free programs, and that you know you can do these things.
5668 To protect your rights, we need to prevent others from denying you
5669 these rights or asking you to surrender the rights. Therefore, you have
5670 certain responsibilities if you distribute copies of the software, or if
5671 you modify it: responsibilities to respect the freedom of others.
5673 For example, if you distribute copies of such a program, whether
5674 gratis or for a fee, you must pass on to the recipients the same
5675 freedoms that you received. You must make sure that they, too, receive
5676 or can get the source code. And you must show them these terms so they
5679 Developers that use the GNU GPL protect your rights with two steps:
5680 (1) assert copyright on the software, and (2) offer you this License
5681 giving you legal permission to copy, distribute and/or modify it.
5683 For the developers' and authors' protection, the GPL clearly explains
5684 that there is no warranty for this free software. For both users' and
5685 authors' sake, the GPL requires that modified versions be marked as
5686 changed, so that their problems will not be attributed erroneously to
5687 authors of previous versions.
5689 Some devices are designed to deny users access to install or run
5690 modified versions of the software inside them, although the manufacturer
5691 can do so. This is fundamentally incompatible with the aim of
5692 protecting users' freedom to change the software. The systematic
5693 pattern of such abuse occurs in the area of products for individuals to
5694 use, which is precisely where it is most unacceptable. Therefore, we
5695 have designed this version of the GPL to prohibit the practice for those
5696 products. If such problems arise substantially in other domains, we
5697 stand ready to extend this provision to those domains in future versions
5698 of the GPL, as needed to protect the freedom of users.
5700 Finally, every program is threatened constantly by software patents.
5701 States should not allow patents to restrict development and use of
5702 software on general-purpose computers, but in those that do, we wish to
5703 avoid the special danger that patents applied to a free program could
5704 make it effectively proprietary. To prevent this, the GPL assures that
5705 patents cannot be used to render the program non-free.
5707 The precise terms and conditions for copying, distribution and
5708 modification follow.
5710 TERMS AND CONDITIONS
5711 ====================
5715 "This License" refers to version 3 of the GNU General Public
5718 "Copyright" also means copyright-like laws that apply to other
5719 kinds of works, such as semiconductor masks.
5721 "The Program" refers to any copyrightable work licensed under this
5722 License. Each licensee is addressed as "you". "Licensees" and
5723 "recipients" may be individuals or organizations.
5725 To "modify" a work means to copy from or adapt all or part of the
5726 work in a fashion requiring copyright permission, other than the
5727 making of an exact copy. The resulting work is called a "modified
5728 version" of the earlier work or a work "based on" the earlier work.
5730 A "covered work" means either the unmodified Program or a work
5731 based on the Program.
5733 To "propagate" a work means to do anything with it that, without
5734 permission, would make you directly or secondarily liable for
5735 infringement under applicable copyright law, except executing it on
5736 a computer or modifying a private copy. Propagation includes
5737 copying, distribution (with or without modification), making
5738 available to the public, and in some countries other activities as
5741 To "convey" a work means any kind of propagation that enables other
5742 parties to make or receive copies. Mere interaction with a user
5743 through a computer network, with no transfer of a copy, is not
5746 An interactive user interface displays "Appropriate Legal Notices"
5747 to the extent that it includes a convenient and prominently visible
5748 feature that (1) displays an appropriate copyright notice, and (2)
5749 tells the user that there is no warranty for the work (except to
5750 the extent that warranties are provided), that licensees may convey
5751 the work under this License, and how to view a copy of this
5752 License. If the interface presents a list of user commands or
5753 options, such as a menu, a prominent item in the list meets this
5758 The "source code" for a work means the preferred form of the work
5759 for making modifications to it. "Object code" means any non-source
5762 A "Standard Interface" means an interface that either is an
5763 official standard defined by a recognized standards body, or, in
5764 the case of interfaces specified for a particular programming
5765 language, one that is widely used among developers working in that
5768 The "System Libraries" of an executable work include anything,
5769 other than the work as a whole, that (a) is included in the normal
5770 form of packaging a Major Component, but which is not part of that
5771 Major Component, and (b) serves only to enable use of the work with
5772 that Major Component, or to implement a Standard Interface for
5773 which an implementation is available to the public in source code
5774 form. A "Major Component", in this context, means a major
5775 essential component (kernel, window system, and so on) of the
5776 specific operating system (if any) on which the executable work
5777 runs, or a compiler used to produce the work, or an object code
5778 interpreter used to run it.
5780 The "Corresponding Source" for a work in object code form means all
5781 the source code needed to generate, install, and (for an executable
5782 work) run the object code and to modify the work, including scripts
5783 to control those activities. However, it does not include the
5784 work's System Libraries, or general-purpose tools or generally
5785 available free programs which are used unmodified in performing
5786 those activities but which are not part of the work. For example,
5787 Corresponding Source includes interface definition files associated
5788 with source files for the work, and the source code for shared
5789 libraries and dynamically linked subprograms that the work is
5790 specifically designed to require, such as by intimate data
5791 communication or control flow between those subprograms and other
5794 The Corresponding Source need not include anything that users can
5795 regenerate automatically from other parts of the Corresponding
5798 The Corresponding Source for a work in source code form is that
5801 2. Basic Permissions.
5803 All rights granted under this License are granted for the term of
5804 copyright on the Program, and are irrevocable provided the stated
5805 conditions are met. This License explicitly affirms your unlimited
5806 permission to run the unmodified Program. The output from running
5807 a covered work is covered by this License only if the output, given
5808 its content, constitutes a covered work. This License acknowledges
5809 your rights of fair use or other equivalent, as provided by
5812 You may make, run and propagate covered works that you do not
5813 convey, without conditions so long as your license otherwise
5814 remains in force. You may convey covered works to others for the
5815 sole purpose of having them make modifications exclusively for you,
5816 or provide you with facilities for running those works, provided
5817 that you comply with the terms of this License in conveying all
5818 material for which you do not control copyright. Those thus making
5819 or running the covered works for you must do so exclusively on your
5820 behalf, under your direction and control, on terms that prohibit
5821 them from making any copies of your copyrighted material outside
5822 their relationship with you.
5824 Conveying under any other circumstances is permitted solely under
5825 the conditions stated below. Sublicensing is not allowed; section
5826 10 makes it unnecessary.
5828 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
5830 No covered work shall be deemed part of an effective technological
5831 measure under any applicable law fulfilling obligations under
5832 article 11 of the WIPO copyright treaty adopted on 20 December
5833 1996, or similar laws prohibiting or restricting circumvention of
5836 When you convey a covered work, you waive any legal power to forbid
5837 circumvention of technological measures to the extent such
5838 circumvention is effected by exercising rights under this License
5839 with respect to the covered work, and you disclaim any intention to
5840 limit operation or modification of the work as a means of
5841 enforcing, against the work's users, your or third parties' legal
5842 rights to forbid circumvention of technological measures.
5844 4. Conveying Verbatim Copies.
5846 You may convey verbatim copies of the Program's source code as you
5847 receive it, in any medium, provided that you conspicuously and
5848 appropriately publish on each copy an appropriate copyright notice;
5849 keep intact all notices stating that this License and any
5850 non-permissive terms added in accord with section 7 apply to the
5851 code; keep intact all notices of the absence of any warranty; and
5852 give all recipients a copy of this License along with the Program.
5854 You may charge any price or no price for each copy that you convey,
5855 and you may offer support or warranty protection for a fee.
5857 5. Conveying Modified Source Versions.
5859 You may convey a work based on the Program, or the modifications to
5860 produce it from the Program, in the form of source code under the
5861 terms of section 4, provided that you also meet all of these
5864 a. The work must carry prominent notices stating that you
5865 modified it, and giving a relevant date.
5867 b. The work must carry prominent notices stating that it is
5868 released under this License and any conditions added under
5869 section 7. This requirement modifies the requirement in
5870 section 4 to "keep intact all notices".
5872 c. You must license the entire work, as a whole, under this
5873 License to anyone who comes into possession of a copy. This
5874 License will therefore apply, along with any applicable
5875 section 7 additional terms, to the whole of the work, and all
5876 its parts, regardless of how they are packaged. This License
5877 gives no permission to license the work in any other way, but
5878 it does not invalidate such permission if you have separately
5881 d. If the work has interactive user interfaces, each must display
5882 Appropriate Legal Notices; however, if the Program has
5883 interactive interfaces that do not display Appropriate Legal
5884 Notices, your work need not make them do so.
5886 A compilation of a covered work with other separate and independent
5887 works, which are not by their nature extensions of the covered
5888 work, and which are not combined with it such as to form a larger
5889 program, in or on a volume of a storage or distribution medium, is
5890 called an "aggregate" if the compilation and its resulting
5891 copyright are not used to limit the access or legal rights of the
5892 compilation's users beyond what the individual works permit.
5893 Inclusion of a covered work in an aggregate does not cause this
5894 License to apply to the other parts of the aggregate.
5896 6. Conveying Non-Source Forms.
5898 You may convey a covered work in object code form under the terms
5899 of sections 4 and 5, provided that you also convey the
5900 machine-readable Corresponding Source under the terms of this
5901 License, in one of these ways:
5903 a. Convey the object code in, or embodied in, a physical product
5904 (including a physical distribution medium), accompanied by the
5905 Corresponding Source fixed on a durable physical medium
5906 customarily used for software interchange.
5908 b. Convey the object code in, or embodied in, a physical product
5909 (including a physical distribution medium), accompanied by a
5910 written offer, valid for at least three years and valid for as
5911 long as you offer spare parts or customer support for that
5912 product model, to give anyone who possesses the object code
5913 either (1) a copy of the Corresponding Source for all the
5914 software in the product that is covered by this License, on a
5915 durable physical medium customarily used for software
5916 interchange, for a price no more than your reasonable cost of
5917 physically performing this conveying of source, or (2) access
5918 to copy the Corresponding Source from a network server at no
5921 c. Convey individual copies of the object code with a copy of the
5922 written offer to provide the Corresponding Source. This
5923 alternative is allowed only occasionally and noncommercially,
5924 and only if you received the object code with such an offer,
5925 in accord with subsection 6b.
5927 d. Convey the object code by offering access from a designated
5928 place (gratis or for a charge), and offer equivalent access to
5929 the Corresponding Source in the same way through the same
5930 place at no further charge. You need not require recipients
5931 to copy the Corresponding Source along with the object code.
5932 If the place to copy the object code is a network server, the
5933 Corresponding Source may be on a different server (operated by
5934 you or a third party) that supports equivalent copying
5935 facilities, provided you maintain clear directions next to the
5936 object code saying where to find the Corresponding Source.
5937 Regardless of what server hosts the Corresponding Source, you
5938 remain obligated to ensure that it is available for as long as
5939 needed to satisfy these requirements.
5941 e. Convey the object code using peer-to-peer transmission,
5942 provided you inform other peers where the object code and
5943 Corresponding Source of the work are being offered to the
5944 general public at no charge under subsection 6d.
5946 A separable portion of the object code, whose source code is
5947 excluded from the Corresponding Source as a System Library, need
5948 not be included in conveying the object code work.
5950 A "User Product" is either (1) a "consumer product", which means
5951 any tangible personal property which is normally used for personal,
5952 family, or household purposes, or (2) anything designed or sold for
5953 incorporation into a dwelling. In determining whether a product is
5954 a consumer product, doubtful cases shall be resolved in favor of
5955 coverage. For a particular product received by a particular user,
5956 "normally used" refers to a typical or common use of that class of
5957 product, regardless of the status of the particular user or of the
5958 way in which the particular user actually uses, or expects or is
5959 expected to use, the product. A product is a consumer product
5960 regardless of whether the product has substantial commercial,
5961 industrial or non-consumer uses, unless such uses represent the
5962 only significant mode of use of the product.
5964 "Installation Information" for a User Product means any methods,
5965 procedures, authorization keys, or other information required to
5966 install and execute modified versions of a covered work in that
5967 User Product from a modified version of its Corresponding Source.
5968 The information must suffice to ensure that the continued
5969 functioning of the modified object code is in no case prevented or
5970 interfered with solely because modification has been made.
5972 If you convey an object code work under this section in, or with,
5973 or specifically for use in, a User Product, and the conveying
5974 occurs as part of a transaction in which the right of possession
5975 and use of the User Product is transferred to the recipient in
5976 perpetuity or for a fixed term (regardless of how the transaction
5977 is characterized), the Corresponding Source conveyed under this
5978 section must be accompanied by the Installation Information. But
5979 this requirement does not apply if neither you nor any third party
5980 retains the ability to install modified object code on the User
5981 Product (for example, the work has been installed in ROM).
5983 The requirement to provide Installation Information does not
5984 include a requirement to continue to provide support service,
5985 warranty, or updates for a work that has been modified or installed
5986 by the recipient, or for the User Product in which it has been
5987 modified or installed. Access to a network may be denied when the
5988 modification itself materially and adversely affects the operation
5989 of the network or violates the rules and protocols for
5990 communication across the network.
5992 Corresponding Source conveyed, and Installation Information
5993 provided, in accord with this section must be in a format that is
5994 publicly documented (and with an implementation available to the
5995 public in source code form), and must require no special password
5996 or key for unpacking, reading or copying.
5998 7. Additional Terms.
6000 "Additional permissions" are terms that supplement the terms of
6001 this License by making exceptions from one or more of its
6002 conditions. Additional permissions that are applicable to the
6003 entire Program shall be treated as though they were included in
6004 this License, to the extent that they are valid under applicable
6005 law. If additional permissions apply only to part of the Program,
6006 that part may be used separately under those permissions, but the
6007 entire Program remains governed by this License without regard to
6008 the additional permissions.
6010 When you convey a copy of a covered work, you may at your option
6011 remove any additional permissions from that copy, or from any part
6012 of it. (Additional permissions may be written to require their own
6013 removal in certain cases when you modify the work.) You may place
6014 additional permissions on material, added by you to a covered work,
6015 for which you have or can give appropriate copyright permission.
6017 Notwithstanding any other provision of this License, for material
6018 you add to a covered work, you may (if authorized by the copyright
6019 holders of that material) supplement the terms of this License with
6022 a. Disclaiming warranty or limiting liability differently from
6023 the terms of sections 15 and 16 of this License; or
6025 b. Requiring preservation of specified reasonable legal notices
6026 or author attributions in that material or in the Appropriate
6027 Legal Notices displayed by works containing it; or
6029 c. Prohibiting misrepresentation of the origin of that material,
6030 or requiring that modified versions of such material be marked
6031 in reasonable ways as different from the original version; or
6033 d. Limiting the use for publicity purposes of names of licensors
6034 or authors of the material; or
6036 e. Declining to grant rights under trademark law for use of some
6037 trade names, trademarks, or service marks; or
6039 f. Requiring indemnification of licensors and authors of that
6040 material by anyone who conveys the material (or modified
6041 versions of it) with contractual assumptions of liability to
6042 the recipient, for any liability that these contractual
6043 assumptions directly impose on those licensors and authors.
6045 All other non-permissive additional terms are considered "further
6046 restrictions" within the meaning of section 10. If the Program as
6047 you received it, or any part of it, contains a notice stating that
6048 it is governed by this License along with a term that is a further
6049 restriction, you may remove that term. If a license document
6050 contains a further restriction but permits relicensing or conveying
6051 under this License, you may add to a covered work material governed
6052 by the terms of that license document, provided that the further
6053 restriction does not survive such relicensing or conveying.
6055 If you add terms to a covered work in accord with this section, you
6056 must place, in the relevant source files, a statement of the
6057 additional terms that apply to those files, or a notice indicating
6058 where to find the applicable terms.
6060 Additional terms, permissive or non-permissive, may be stated in
6061 the form of a separately written license, or stated as exceptions;
6062 the above requirements apply either way.
6066 You may not propagate or modify a covered work except as expressly
6067 provided under this License. Any attempt otherwise to propagate or
6068 modify it is void, and will automatically terminate your rights
6069 under this License (including any patent licenses granted under the
6070 third paragraph of section 11).
6072 However, if you cease all violation of this License, then your
6073 license from a particular copyright holder is reinstated (a)
6074 provisionally, unless and until the copyright holder explicitly and
6075 finally terminates your license, and (b) permanently, if the
6076 copyright holder fails to notify you of the violation by some
6077 reasonable means prior to 60 days after the cessation.
6079 Moreover, your license from a particular copyright holder is
6080 reinstated permanently if the copyright holder notifies you of the
6081 violation by some reasonable means, this is the first time you have
6082 received notice of violation of this License (for any work) from
6083 that copyright holder, and you cure the violation prior to 30 days
6084 after your receipt of the notice.
6086 Termination of your rights under this section does not terminate
6087 the licenses of parties who have received copies or rights from you
6088 under this License. If your rights have been terminated and not
6089 permanently reinstated, you do not qualify to receive new licenses
6090 for the same material under section 10.
6092 9. Acceptance Not Required for Having Copies.
6094 You are not required to accept this License in order to receive or
6095 run a copy of the Program. Ancillary propagation of a covered work
6096 occurring solely as a consequence of using peer-to-peer
6097 transmission to receive a copy likewise does not require
6098 acceptance. However, nothing other than this License grants you
6099 permission to propagate or modify any covered work. These actions
6100 infringe copyright if you do not accept this License. Therefore,
6101 by modifying or propagating a covered work, you indicate your
6102 acceptance of this License to do so.
6104 10. Automatic Licensing of Downstream Recipients.
6106 Each time you convey a covered work, the recipient automatically
6107 receives a license from the original licensors, to run, modify and
6108 propagate that work, subject to this License. You are not
6109 responsible for enforcing compliance by third parties with this
6112 An "entity transaction" is a transaction transferring control of an
6113 organization, or substantially all assets of one, or subdividing an
6114 organization, or merging organizations. If propagation of a
6115 covered work results from an entity transaction, each party to that
6116 transaction who receives a copy of the work also receives whatever
6117 licenses to the work the party's predecessor in interest had or
6118 could give under the previous paragraph, plus a right to possession
6119 of the Corresponding Source of the work from the predecessor in
6120 interest, if the predecessor has it or can get it with reasonable
6123 You may not impose any further restrictions on the exercise of the
6124 rights granted or affirmed under this License. For example, you
6125 may not impose a license fee, royalty, or other charge for exercise
6126 of rights granted under this License, and you may not initiate
6127 litigation (including a cross-claim or counterclaim in a lawsuit)
6128 alleging that any patent claim is infringed by making, using,
6129 selling, offering for sale, or importing the Program or any portion
6134 A "contributor" is a copyright holder who authorizes use under this
6135 License of the Program or a work on which the Program is based.
6136 The work thus licensed is called the contributor's "contributor
6139 A contributor's "essential patent claims" are all patent claims
6140 owned or controlled by the contributor, whether already acquired or
6141 hereafter acquired, that would be infringed by some manner,
6142 permitted by this License, of making, using, or selling its
6143 contributor version, but do not include claims that would be
6144 infringed only as a consequence of further modification of the
6145 contributor version. For purposes of this definition, "control"
6146 includes the right to grant patent sublicenses in a manner
6147 consistent with the requirements of this License.
6149 Each contributor grants you a non-exclusive, worldwide,
6150 royalty-free patent license under the contributor's essential
6151 patent claims, to make, use, sell, offer for sale, import and
6152 otherwise run, modify and propagate the contents of its contributor
6155 In the following three paragraphs, a "patent license" is any
6156 express agreement or commitment, however denominated, not to
6157 enforce a patent (such as an express permission to practice a
6158 patent or covenant not to sue for patent infringement). To "grant"
6159 such a patent license to a party means to make such an agreement or
6160 commitment not to enforce a patent against the party.
6162 If you convey a covered work, knowingly relying on a patent
6163 license, and the Corresponding Source of the work is not available
6164 for anyone to copy, free of charge and under the terms of this
6165 License, through a publicly available network server or other
6166 readily accessible means, then you must either (1) cause the
6167 Corresponding Source to be so available, or (2) arrange to deprive
6168 yourself of the benefit of the patent license for this particular
6169 work, or (3) arrange, in a manner consistent with the requirements
6170 of this License, to extend the patent license to downstream
6171 recipients. "Knowingly relying" means you have actual knowledge
6172 that, but for the patent license, your conveying the covered work
6173 in a country, or your recipient's use of the covered work in a
6174 country, would infringe one or more identifiable patents in that
6175 country that you have reason to believe are valid.
6177 If, pursuant to or in connection with a single transaction or
6178 arrangement, you convey, or propagate by procuring conveyance of, a
6179 covered work, and grant a patent license to some of the parties
6180 receiving the covered work authorizing them to use, propagate,
6181 modify or convey a specific copy of the covered work, then the
6182 patent license you grant is automatically extended to all
6183 recipients of the covered work and works based on it.
6185 A patent license is "discriminatory" if it does not include within
6186 the scope of its coverage, prohibits the exercise of, or is
6187 conditioned on the non-exercise of one or more of the rights that
6188 are specifically granted under this License. You may not convey a
6189 covered work if you are a party to an arrangement with a third
6190 party that is in the business of distributing software, under which
6191 you make payment to the third party based on the extent of your
6192 activity of conveying the work, and under which the third party
6193 grants, to any of the parties who would receive the covered work
6194 from you, a discriminatory patent license (a) in connection with
6195 copies of the covered work conveyed by you (or copies made from
6196 those copies), or (b) primarily for and in connection with specific
6197 products or compilations that contain the covered work, unless you
6198 entered into that arrangement, or that patent license was granted,
6199 prior to 28 March 2007.
6201 Nothing in this License shall be construed as excluding or limiting
6202 any implied license or other defenses to infringement that may
6203 otherwise be available to you under applicable patent law.
6205 12. No Surrender of Others' Freedom.
6207 If conditions are imposed on you (whether by court order, agreement
6208 or otherwise) that contradict the conditions of this License, they
6209 do not excuse you from the conditions of this License. If you
6210 cannot convey a covered work so as to satisfy simultaneously your
6211 obligations under this License and any other pertinent obligations,
6212 then as a consequence you may not convey it at all. For example,
6213 if you agree to terms that obligate you to collect a royalty for
6214 further conveying from those to whom you convey the Program, the
6215 only way you could satisfy both those terms and this License would
6216 be to refrain entirely from conveying the Program.
6218 13. Use with the GNU Affero General Public License.
6220 Notwithstanding any other provision of this License, you have
6221 permission to link or combine any covered work with a work licensed
6222 under version 3 of the GNU Affero General Public License into a
6223 single combined work, and to convey the resulting work. The terms
6224 of this License will continue to apply to the part which is the
6225 covered work, but the special requirements of the GNU Affero
6226 General Public License, section 13, concerning interaction through
6227 a network will apply to the combination as such.
6229 14. Revised Versions of this License.
6231 The Free Software Foundation may publish revised and/or new
6232 versions of the GNU General Public License from time to time. Such
6233 new versions will be similar in spirit to the present version, but
6234 may differ in detail to address new problems or concerns.
6236 Each version is given a distinguishing version number. If the
6237 Program specifies that a certain numbered version of the GNU
6238 General Public License "or any later version" applies to it, you
6239 have the option of following the terms and conditions either of
6240 that numbered version or of any later version published by the Free
6241 Software Foundation. If the Program does not specify a version
6242 number of the GNU General Public License, you may choose any
6243 version ever published by the Free Software Foundation.
6245 If the Program specifies that a proxy can decide which future
6246 versions of the GNU General Public License can be used, that
6247 proxy's public statement of acceptance of a version permanently
6248 authorizes you to choose that version for the Program.
6250 Later license versions may give you additional or different
6251 permissions. However, no additional obligations are imposed on any
6252 author or copyright holder as a result of your choosing to follow a
6255 15. Disclaimer of Warranty.
6257 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
6258 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
6259 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
6260 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
6261 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
6262 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
6263 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
6264 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
6265 NECESSARY SERVICING, REPAIR OR CORRECTION.
6267 16. Limitation of Liability.
6269 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
6270 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
6271 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
6272 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
6273 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
6274 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
6275 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
6276 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
6277 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
6278 THE POSSIBILITY OF SUCH DAMAGES.
6280 17. Interpretation of Sections 15 and 16.
6282 If the disclaimer of warranty and limitation of liability provided
6283 above cannot be given local legal effect according to their terms,
6284 reviewing courts shall apply local law that most closely
6285 approximates an absolute waiver of all civil liability in
6286 connection with the Program, unless a warranty or assumption of
6287 liability accompanies a copy of the Program in return for a fee.
6289 END OF TERMS AND CONDITIONS
6290 ===========================
6292 How to Apply These Terms to Your New Programs
6293 =============================================
6295 If you develop a new program, and you want it to be of the greatest
6296 possible use to the public, the best way to achieve this is to make it
6297 free software which everyone can redistribute and change under these
6300 To do so, attach the following notices to the program. It is safest
6301 to attach them to the start of each source file to most effectively
6302 state the exclusion of warranty; and each file should have at least the
6303 "copyright" line and a pointer to where the full notice is found.
6305 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
6306 Copyright (C) YEAR NAME OF AUTHOR
6308 This program is free software: you can redistribute it and/or modify
6309 it under the terms of the GNU General Public License as published by
6310 the Free Software Foundation, either version 3 of the License, or (at
6311 your option) any later version.
6313 This program is distributed in the hope that it will be useful, but
6314 WITHOUT ANY WARRANTY; without even the implied warranty of
6315 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6316 General Public License for more details.
6318 You should have received a copy of the GNU General Public License
6319 along with this program. If not, see <http://www.gnu.org/licenses/>.
6321 Also add information on how to contact you by electronic and paper
6324 If the program does terminal interaction, make it output a short
6325 notice like this when it starts in an interactive mode:
6327 PROGRAM Copyright (C) YEAR NAME OF AUTHOR
6328 This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
6329 This is free software, and you are welcome to redistribute it
6330 under certain conditions; type 'show c' for details.
6332 The hypothetical commands 'show w' and 'show c' should show the
6333 appropriate parts of the General Public License. Of course, your
6334 program's commands might be different; for a GUI interface, you would
6337 You should also get your employer (if you work as a programmer) or
6338 school, if any, to sign a "copyright disclaimer" for the program, if
6339 necessary. For more information on this, and how to apply and follow
6340 the GNU GPL, see <http://www.gnu.org/licenses/>.
6342 The GNU General Public License does not permit incorporating your
6343 program into proprietary programs. If your program is a subroutine
6344 library, you may consider it more useful to permit linking proprietary
6345 applications with the library. If this is what you want to do, use the
6346 GNU Lesser General Public License instead of this License. But first,
6347 please read <http://www.gnu.org/philosophy/why-not-lgpl.html>.
6350 File: gdb.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Copying, Up: Top
6352 Appendix M GNU Free Documentation License
6353 *****************************************
6355 Version 1.3, 3 November 2008
6357 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
6360 Everyone is permitted to copy and distribute verbatim copies
6361 of this license document, but changing it is not allowed.
6365 The purpose of this License is to make a manual, textbook, or other
6366 functional and useful document "free" in the sense of freedom: to
6367 assure everyone the effective freedom to copy and redistribute it,
6368 with or without modifying it, either commercially or
6369 noncommercially. Secondarily, this License preserves for the
6370 author and publisher a way to get credit for their work, while not
6371 being considered responsible for modifications made by others.
6373 This License is a kind of "copyleft", which means that derivative
6374 works of the document must themselves be free in the same sense.
6375 It complements the GNU General Public License, which is a copyleft
6376 license designed for free software.
6378 We have designed this License in order to use it for manuals for
6379 free software, because free software needs free documentation: a
6380 free program should come with manuals providing the same freedoms
6381 that the software does. But this License is not limited to
6382 software manuals; it can be used for any textual work, regardless
6383 of subject matter or whether it is published as a printed book. We
6384 recommend this License principally for works whose purpose is
6385 instruction or reference.
6387 1. APPLICABILITY AND DEFINITIONS
6389 This License applies to any manual or other work, in any medium,
6390 that contains a notice placed by the copyright holder saying it can
6391 be distributed under the terms of this License. Such a notice
6392 grants a world-wide, royalty-free license, unlimited in duration,
6393 to use that work under the conditions stated herein. The
6394 "Document", below, refers to any such manual or work. Any member
6395 of the public is a licensee, and is addressed as "you". You accept
6396 the license if you copy, modify or distribute the work in a way
6397 requiring permission under copyright law.
6399 A "Modified Version" of the Document means any work containing the
6400 Document or a portion of it, either copied verbatim, or with
6401 modifications and/or translated into another language.
6403 A "Secondary Section" is a named appendix or a front-matter section
6404 of the Document that deals exclusively with the relationship of the
6405 publishers or authors of the Document to the Document's overall
6406 subject (or to related matters) and contains nothing that could
6407 fall directly within that overall subject. (Thus, if the Document
6408 is in part a textbook of mathematics, a Secondary Section may not
6409 explain any mathematics.) The relationship could be a matter of
6410 historical connection with the subject or with related matters, or
6411 of legal, commercial, philosophical, ethical or political position
6414 The "Invariant Sections" are certain Secondary Sections whose
6415 titles are designated, as being those of Invariant Sections, in the
6416 notice that says that the Document is released under this License.
6417 If a section does not fit the above definition of Secondary then it
6418 is not allowed to be designated as Invariant. The Document may
6419 contain zero Invariant Sections. If the Document does not identify
6420 any Invariant Sections then there are none.
6422 The "Cover Texts" are certain short passages of text that are
6423 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
6424 that says that the Document is released under this License. A
6425 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
6426 be at most 25 words.
6428 A "Transparent" copy of the Document means a machine-readable copy,
6429 represented in a format whose specification is available to the
6430 general public, that is suitable for revising the document
6431 straightforwardly with generic text editors or (for images composed
6432 of pixels) generic paint programs or (for drawings) some widely
6433 available drawing editor, and that is suitable for input to text
6434 formatters or for automatic translation to a variety of formats
6435 suitable for input to text formatters. A copy made in an otherwise
6436 Transparent file format whose markup, or absence of markup, has
6437 been arranged to thwart or discourage subsequent modification by
6438 readers is not Transparent. An image format is not Transparent if
6439 used for any substantial amount of text. A copy that is not
6440 "Transparent" is called "Opaque".
6442 Examples of suitable formats for Transparent copies include plain
6443 ASCII without markup, Texinfo input format, LaTeX input format,
6444 SGML or XML using a publicly available DTD, and standard-conforming
6445 simple HTML, PostScript or PDF designed for human modification.
6446 Examples of transparent image formats include PNG, XCF and JPG.
6447 Opaque formats include proprietary formats that can be read and
6448 edited only by proprietary word processors, SGML or XML for which
6449 the DTD and/or processing tools are not generally available, and
6450 the machine-generated HTML, PostScript or PDF produced by some word
6451 processors for output purposes only.
6453 The "Title Page" means, for a printed book, the title page itself,
6454 plus such following pages as are needed to hold, legibly, the
6455 material this License requires to appear in the title page. For
6456 works in formats which do not have any title page as such, "Title
6457 Page" means the text near the most prominent appearance of the
6458 work's title, preceding the beginning of the body of the text.
6460 The "publisher" means any person or entity that distributes copies
6461 of the Document to the public.
6463 A section "Entitled XYZ" means a named subunit of the Document
6464 whose title either is precisely XYZ or contains XYZ in parentheses
6465 following text that translates XYZ in another language. (Here XYZ
6466 stands for a specific section name mentioned below, such as
6467 "Acknowledgements", "Dedications", "Endorsements", or "History".)
6468 To "Preserve the Title" of such a section when you modify the
6469 Document means that it remains a section "Entitled XYZ" according
6472 The Document may include Warranty Disclaimers next to the notice
6473 which states that this License applies to the Document. These
6474 Warranty Disclaimers are considered to be included by reference in
6475 this License, but only as regards disclaiming warranties: any other
6476 implication that these Warranty Disclaimers may have is void and
6477 has no effect on the meaning of this License.
6481 You may copy and distribute the Document in any medium, either
6482 commercially or noncommercially, provided that this License, the
6483 copyright notices, and the license notice saying this License
6484 applies to the Document are reproduced in all copies, and that you
6485 add no other conditions whatsoever to those of this License. You
6486 may not use technical measures to obstruct or control the reading
6487 or further copying of the copies you make or distribute. However,
6488 you may accept compensation in exchange for copies. If you
6489 distribute a large enough number of copies you must also follow the
6490 conditions in section 3.
6492 You may also lend copies, under the same conditions stated above,
6493 and you may publicly display copies.
6495 3. COPYING IN QUANTITY
6497 If you publish printed copies (or copies in media that commonly
6498 have printed covers) of the Document, numbering more than 100, and
6499 the Document's license notice requires Cover Texts, you must
6500 enclose the copies in covers that carry, clearly and legibly, all
6501 these Cover Texts: Front-Cover Texts on the front cover, and
6502 Back-Cover Texts on the back cover. Both covers must also clearly
6503 and legibly identify you as the publisher of these copies. The
6504 front cover must present the full title with all words of the title
6505 equally prominent and visible. You may add other material on the
6506 covers in addition. Copying with changes limited to the covers, as
6507 long as they preserve the title of the Document and satisfy these
6508 conditions, can be treated as verbatim copying in other respects.
6510 If the required texts for either cover are too voluminous to fit
6511 legibly, you should put the first ones listed (as many as fit
6512 reasonably) on the actual cover, and continue the rest onto
6515 If you publish or distribute Opaque copies of the Document
6516 numbering more than 100, you must either include a machine-readable
6517 Transparent copy along with each Opaque copy, or state in or with
6518 each Opaque copy a computer-network location from which the general
6519 network-using public has access to download using public-standard
6520 network protocols a complete Transparent copy of the Document, free
6521 of added material. If you use the latter option, you must take
6522 reasonably prudent steps, when you begin distribution of Opaque
6523 copies in quantity, to ensure that this Transparent copy will
6524 remain thus accessible at the stated location until at least one
6525 year after the last time you distribute an Opaque copy (directly or
6526 through your agents or retailers) of that edition to the public.
6528 It is requested, but not required, that you contact the authors of
6529 the Document well before redistributing any large number of copies,
6530 to give them a chance to provide you with an updated version of the
6535 You may copy and distribute a Modified Version of the Document
6536 under the conditions of sections 2 and 3 above, provided that you
6537 release the Modified Version under precisely this License, with the
6538 Modified Version filling the role of the Document, thus licensing
6539 distribution and modification of the Modified Version to whoever
6540 possesses a copy of it. In addition, you must do these things in
6541 the Modified Version:
6543 A. Use in the Title Page (and on the covers, if any) a title
6544 distinct from that of the Document, and from those of previous
6545 versions (which should, if there were any, be listed in the
6546 History section of the Document). You may use the same title
6547 as a previous version if the original publisher of that
6548 version gives permission.
6550 B. List on the Title Page, as authors, one or more persons or
6551 entities responsible for authorship of the modifications in
6552 the Modified Version, together with at least five of the
6553 principal authors of the Document (all of its principal
6554 authors, if it has fewer than five), unless they release you
6555 from this requirement.
6557 C. State on the Title page the name of the publisher of the
6558 Modified Version, as the publisher.
6560 D. Preserve all the copyright notices of the Document.
6562 E. Add an appropriate copyright notice for your modifications
6563 adjacent to the other copyright notices.
6565 F. Include, immediately after the copyright notices, a license
6566 notice giving the public permission to use the Modified
6567 Version under the terms of this License, in the form shown in
6570 G. Preserve in that license notice the full lists of Invariant
6571 Sections and required Cover Texts given in the Document's
6574 H. Include an unaltered copy of this License.
6576 I. Preserve the section Entitled "History", Preserve its Title,
6577 and add to it an item stating at least the title, year, new
6578 authors, and publisher of the Modified Version as given on the
6579 Title Page. If there is no section Entitled "History" in the
6580 Document, create one stating the title, year, authors, and
6581 publisher of the Document as given on its Title Page, then add
6582 an item describing the Modified Version as stated in the
6585 J. Preserve the network location, if any, given in the Document
6586 for public access to a Transparent copy of the Document, and
6587 likewise the network locations given in the Document for
6588 previous versions it was based on. These may be placed in the
6589 "History" section. You may omit a network location for a work
6590 that was published at least four years before the Document
6591 itself, or if the original publisher of the version it refers
6592 to gives permission.
6594 K. For any section Entitled "Acknowledgements" or "Dedications",
6595 Preserve the Title of the section, and preserve in the section
6596 all the substance and tone of each of the contributor
6597 acknowledgements and/or dedications given therein.
6599 L. Preserve all the Invariant Sections of the Document, unaltered
6600 in their text and in their titles. Section numbers or the
6601 equivalent are not considered part of the section titles.
6603 M. Delete any section Entitled "Endorsements". Such a section
6604 may not be included in the Modified Version.
6606 N. Do not retitle any existing section to be Entitled
6607 "Endorsements" or to conflict in title with any Invariant
6610 O. Preserve any Warranty Disclaimers.
6612 If the Modified Version includes new front-matter sections or
6613 appendices that qualify as Secondary Sections and contain no
6614 material copied from the Document, you may at your option designate
6615 some or all of these sections as invariant. To do this, add their
6616 titles to the list of Invariant Sections in the Modified Version's
6617 license notice. These titles must be distinct from any other
6620 You may add a section Entitled "Endorsements", provided it contains
6621 nothing but endorsements of your Modified Version by various
6622 parties--for example, statements of peer review or that the text
6623 has been approved by an organization as the authoritative
6624 definition of a standard.
6626 You may add a passage of up to five words as a Front-Cover Text,
6627 and a passage of up to 25 words as a Back-Cover Text, to the end of
6628 the list of Cover Texts in the Modified Version. Only one passage
6629 of Front-Cover Text and one of Back-Cover Text may be added by (or
6630 through arrangements made by) any one entity. If the Document
6631 already includes a cover text for the same cover, previously added
6632 by you or by arrangement made by the same entity you are acting on
6633 behalf of, you may not add another; but you may replace the old
6634 one, on explicit permission from the previous publisher that added
6637 The author(s) and publisher(s) of the Document do not by this
6638 License give permission to use their names for publicity for or to
6639 assert or imply endorsement of any Modified Version.
6641 5. COMBINING DOCUMENTS
6643 You may combine the Document with other documents released under
6644 this License, under the terms defined in section 4 above for
6645 modified versions, provided that you include in the combination all
6646 of the Invariant Sections of all of the original documents,
6647 unmodified, and list them all as Invariant Sections of your
6648 combined work in its license notice, and that you preserve all
6649 their Warranty Disclaimers.
6651 The combined work need only contain one copy of this License, and
6652 multiple identical Invariant Sections may be replaced with a single
6653 copy. If there are multiple Invariant Sections with the same name
6654 but different contents, make the title of each such section unique
6655 by adding at the end of it, in parentheses, the name of the
6656 original author or publisher of that section if known, or else a
6657 unique number. Make the same adjustment to the section titles in
6658 the list of Invariant Sections in the license notice of the
6661 In the combination, you must combine any sections Entitled
6662 "History" in the various original documents, forming one section
6663 Entitled "History"; likewise combine any sections Entitled
6664 "Acknowledgements", and any sections Entitled "Dedications". You
6665 must delete all sections Entitled "Endorsements."
6667 6. COLLECTIONS OF DOCUMENTS
6669 You may make a collection consisting of the Document and other
6670 documents released under this License, and replace the individual
6671 copies of this License in the various documents with a single copy
6672 that is included in the collection, provided that you follow the
6673 rules of this License for verbatim copying of each of the documents
6674 in all other respects.
6676 You may extract a single document from such a collection, and
6677 distribute it individually under this License, provided you insert
6678 a copy of this License into the extracted document, and follow this
6679 License in all other respects regarding verbatim copying of that
6682 7. AGGREGATION WITH INDEPENDENT WORKS
6684 A compilation of the Document or its derivatives with other
6685 separate and independent documents or works, in or on a volume of a
6686 storage or distribution medium, is called an "aggregate" if the
6687 copyright resulting from the compilation is not used to limit the
6688 legal rights of the compilation's users beyond what the individual
6689 works permit. When the Document is included in an aggregate, this
6690 License does not apply to the other works in the aggregate which
6691 are not themselves derivative works of the Document.
6693 If the Cover Text requirement of section 3 is applicable to these
6694 copies of the Document, then if the Document is less than one half
6695 of the entire aggregate, the Document's Cover Texts may be placed
6696 on covers that bracket the Document within the aggregate, or the
6697 electronic equivalent of covers if the Document is in electronic
6698 form. Otherwise they must appear on printed covers that bracket
6699 the whole aggregate.
6703 Translation is considered a kind of modification, so you may
6704 distribute translations of the Document under the terms of section
6705 4. Replacing Invariant Sections with translations requires special
6706 permission from their copyright holders, but you may include
6707 translations of some or all Invariant Sections in addition to the
6708 original versions of these Invariant Sections. You may include a
6709 translation of this License, and all the license notices in the
6710 Document, and any Warranty Disclaimers, provided that you also
6711 include the original English version of this License and the
6712 original versions of those notices and disclaimers. In case of a
6713 disagreement between the translation and the original version of
6714 this License or a notice or disclaimer, the original version will
6717 If a section in the Document is Entitled "Acknowledgements",
6718 "Dedications", or "History", the requirement (section 4) to
6719 Preserve its Title (section 1) will typically require changing the
6724 You may not copy, modify, sublicense, or distribute the Document
6725 except as expressly provided under this License. Any attempt
6726 otherwise to copy, modify, sublicense, or distribute it is void,
6727 and will automatically terminate your rights under this License.
6729 However, if you cease all violation of this License, then your
6730 license from a particular copyright holder is reinstated (a)
6731 provisionally, unless and until the copyright holder explicitly and
6732 finally terminates your license, and (b) permanently, if the
6733 copyright holder fails to notify you of the violation by some
6734 reasonable means prior to 60 days after the cessation.
6736 Moreover, your license from a particular copyright holder is
6737 reinstated permanently if the copyright holder notifies you of the
6738 violation by some reasonable means, this is the first time you have
6739 received notice of violation of this License (for any work) from
6740 that copyright holder, and you cure the violation prior to 30 days
6741 after your receipt of the notice.
6743 Termination of your rights under this section does not terminate
6744 the licenses of parties who have received copies or rights from you
6745 under this License. If your rights have been terminated and not
6746 permanently reinstated, receipt of a copy of some or all of the
6747 same material does not give you any rights to use it.
6749 10. FUTURE REVISIONS OF THIS LICENSE
6751 The Free Software Foundation may publish new, revised versions of
6752 the GNU Free Documentation License from time to time. Such new
6753 versions will be similar in spirit to the present version, but may
6754 differ in detail to address new problems or concerns. See
6755 <http://www.gnu.org/copyleft/>.
6757 Each version of the License is given a distinguishing version
6758 number. If the Document specifies that a particular numbered
6759 version of this License "or any later version" applies to it, you
6760 have the option of following the terms and conditions either of
6761 that specified version or of any later version that has been
6762 published (not as a draft) by the Free Software Foundation. If the
6763 Document does not specify a version number of this License, you may
6764 choose any version ever published (not as a draft) by the Free
6765 Software Foundation. If the Document specifies that a proxy can
6766 decide which future versions of this License can be used, that
6767 proxy's public statement of acceptance of a version permanently
6768 authorizes you to choose that version for the Document.
6772 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
6773 World Wide Web server that publishes copyrightable works and also
6774 provides prominent facilities for anybody to edit those works. A
6775 public wiki that anybody can edit is an example of such a server.
6776 A "Massive Multiauthor Collaboration" (or "MMC") contained in the
6777 site means any set of copyrightable works thus published on the MMC
6780 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
6781 license published by Creative Commons Corporation, a not-for-profit
6782 corporation with a principal place of business in San Francisco,
6783 California, as well as future copyleft versions of that license
6784 published by that same organization.
6786 "Incorporate" means to publish or republish a Document, in whole or
6787 in part, as part of another Document.
6789 An MMC is "eligible for relicensing" if it is licensed under this
6790 License, and if all works that were first published under this
6791 License somewhere other than this MMC, and subsequently
6792 incorporated in whole or in part into the MMC, (1) had no cover
6793 texts or invariant sections, and (2) were thus incorporated prior
6794 to November 1, 2008.
6796 The operator of an MMC Site may republish an MMC contained in the
6797 site under CC-BY-SA on the same site at any time before August 1,
6798 2009, provided the MMC is eligible for relicensing.
6800 ADDENDUM: How to use this License for your documents
6801 ====================================================
6803 To use this License in a document you have written, include a copy of
6804 the License in the document and put the following copyright and license
6805 notices just after the title page:
6807 Copyright (C) YEAR YOUR NAME.
6808 Permission is granted to copy, distribute and/or modify this document
6809 under the terms of the GNU Free Documentation License, Version 1.3
6810 or any later version published by the Free Software Foundation;
6811 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
6812 Texts. A copy of the license is included in the section entitled ``GNU
6813 Free Documentation License''.
6815 If you have Invariant Sections, Front-Cover Texts and Back-Cover
6816 Texts, replace the "with...Texts." line with this:
6818 with the Invariant Sections being LIST THEIR TITLES, with
6819 the Front-Cover Texts being LIST, and with the Back-Cover Texts
6822 If you have Invariant Sections without Cover Texts, or some other
6823 combination of the three, merge those two alternatives to suit the
6826 If your document contains nontrivial examples of program code, we
6827 recommend releasing these examples in parallel under your choice of free
6828 software license, such as the GNU General Public License, to permit
6829 their use in free software.
projects / platform / upstream / gdb.git / blob