-
-
Notifications
You must be signed in to change notification settings - Fork 564
/
gdb.txt
1525 lines (1506 loc) · 62.9 KB
/
gdb.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
GDB - A GDB commandline like protocol to interact with Xdebug
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Version: 1.0
:Status: draft 1
:Authors: - Derick Rethans <derick@xdebug.org>
.. contents::
1. Description
==============
This document describes a simple GDB-like protocol to interact with
Xdebug with a simple client. The protocol is a text based protocol
for easy implementation and human readability, it is not meant to be
implemented in a GUI debugger.
The protocol provides a means of communication between a debugger engine
(Xdebug) and a debugger client (such as Xdebug 1.3's bundled client).
The structure (and some of the text) in this specification are reused from
the `DBGp specifications <http://xdebug.org/docs-dbgp.php>`_.
2. Terminology
==============
debug client
A client to interact with the debugger engine.
debugger engine
The language engine being debugged.
TRUE
a value defined as TRUE should be a numeric one.
FALSE
a value defined as FALSE should be a numeric zero.
3. Initiating a debugging session
=================================
The debugger engine initiates a debugging session. The debugger engine
will make a connection to a listening debug client, then wait for the debug
client to initiate commands. The debugger engine does not step into the first
line of execution until the IDE issues one of the continuation commands. The
first thing that should happen in a debug session is that the debug client
sets options with the option command, and sets
any additional data, such as breakpoints. Debugger engine implementations
should store and data it receives if it is unable to process them prior to
compiling and/or executing code. Only commands from the "init" section
can be used at this stage.
3.1 Standard GDB port
----------------------
The debug client listens by default on port 17869 for debugger connections, but
this port might be configurable.
.. 5.2 Connection Initialization
.. -----------------------------
..
.. When a debugger engine connects to either a IDE or proxy, it must send an
.. init packet: ::
..
.. <init appid="APPID"
.. idekey="IDE_KEY"
.. session="DBGP_COOKIE"
.. thread="THREAD_ID"
.. parent="PARENT_APPID"
.. language="LANGUAGE_NAME"
.. protocol_version="1.0"
.. fileuri="file://path/to/file">
..
..
.. Attributes in the init element can include:
..
.. =============== ========================================================
.. Attribute Description
.. =============== ========================================================
.. appid defined by the debugger engine
.. idekey defined by the user. The DBGP_IDEKEY environment
.. variable SHOULD be used if it is available,
.. otherwise setting this value is debugger engine
.. implementation specific. This value may be empty.
.. session If the environment variable DBGP_COOKIE exists,
.. then the init packet MUST contain a session
.. attribute with the value of the variable. This
.. allows an IDE to execute a debugger engine, and
.. maintain some state information between the
.. execution and the protocol connection. This value
.. should not be expected to be set in 'remote'
.. debugging situations where the IDE is not in
.. control of the process.
.. thread_id the systems thread id
.. parent_appid the appid of the application that spawned the
.. process. When an application is executed, it
.. should set it's APPID into the environment.
.. If an APPID already exists, it should first
.. read that value and use it as the PARENT_APPID.
.. language_name debugger engine specific, must not contain
.. additional information, such as version, etc.
.. protocol The highest version of this protocol supported
.. fileuri URI of the script file being debugged
.. =============== ========================================================
..
.. The IDE responds by dropping socket connection, or starting with
.. debugger commands.
..
.. The init packet may have child elements for additional vendor specific
.. data. These are entirely optional and must not effect behavior
.. of the debugger interaction. Suggested child elements include: ::
..
.. <engine version="1.abcd">product title</engine>
.. <author>author</author>
.. <company>company</company>
.. <license>licensing info</license>
.. <url>url</url>
.. <copyright>xxx</copyright>
..
.. 5.3 Just in time debugging and debugger proxies
.. -----------------------------------------------
..
.. Proxies are supported to allow multiuser systems work with a defined
.. port for debugging. Each IDE would listen on a unique port and notify the
.. proxy what port it is listening on, along with a key value that is used by
.. the debugger engine to specify which IDE it should be connected with.
..
.. With the exception of the init packet, all communications
.. will be passed through without modifications. A proxy could also implement
.. support for just in time debugging. In this case, a debugger engine would
.. break (perhaps on an error or exception) and connect to the proxy. The proxy
.. would then start the IDE (if it is not already running) and initiate a
.. debugging session with it.
..
.. The method for handling just in time debugging is not defined by the protocol
.. and is implementation specific. One example of how this may work is that the
.. proxy has a configuration file that defines key's for each user, along with
.. the path to the executable that will provide the UI for that user. The debugger
.. engine would have to know this key value in advance and provide it to the proxy
.. in the init packet (see IDE_KEY in section 5.2). The proxy would know if the
.. IDE is running, since the IDE should have communicated with the proxy already,
.. if it has not, the proxy could execute the IDE directly.
..
.. To support proxies and jit deamons, the IDE should be configured with
.. and ip:port pointing to the proxy/jit. The IDE then makes a
.. connection to the proxy when it starts and sends the following command:
..
.. IDE command ::
..
.. proxyinit -a ip:port -k ide_key -m [0|1]
..
.. == ========================================================
.. -p the port that the IDE listens for debugging on. The address
.. is retrieved from the connection information.
.. -k a IDE key, which the debugger engine will also use in it's
.. debugging init command. this allows the proxy to match
.. request to IDE. Typically the user will provide the
.. session key as a configuration item.
.. -m this tells the demon that the IDE supports (or doesn't)
.. multiple debugger sessions. if -m is missing, zero or no
.. support is default.
.. == ========================================================
..
.. IDE command ::
..
.. proxystop -k ide_key
..
.. The IDE sends a proxystop command when it wants the proxy
.. server to stop listening for it.
..
.. The proxy should respond with a simple XML statement alerting the
.. IDE to an error, or the success of the initialization (see section
.. 6.5 for more details on the error element). ::
..
.. <proxyinit success="[0|1]"
.. idekey="{ID}">
.. <error id="app_specific_error_code">
.. <message>UI Usable Message</message>
.. </error>
.. </proxyinit>
..
.. Once the IDE has sent this command, and received a confirmation, it
.. disconnects from the proxy. The IDE will only connect to the proxy
.. when it initially wants to start accepting connections from the proxy,
.. or when it wants to stop accepting connections from the proxy.
..
.. 5.3.1 Init Packet Handling
.. ^^^^^^^^^^^^^^^^^^^^^^^^^^
..
.. If a proxy receives the init packet (see section 5.2), it will use the
.. idekey attribute to pass the request to the correct IDE, or to do some
.. other operation such as which may be required to implement security or
.. initiate just in time debugging. The proxy will add the idekey as a attribute
.. to the init packet when it passes it through to the IDE. The proxy may
.. also add child elements with further information, and must add an
.. attribute to the init element called 'proxied' with the attribute
.. value being the ip address of the debugger engine. This is the only
.. time the proxy should modify data being passed to the IDE.
..
.. 5.3.2 Proxy Errors
.. ^^^^^^^^^^^^^^^^^^
..
.. If the proxy must send error data to the IDE, it may send an XML
.. message with the root element named 'proxyerror'. This message will
.. be in the format of the error packets defined in 6.3 below.
..
.. If the proxy must send error data to the debugger engine, it may
.. send the proxyerror command defined in section 7 below.
..
.. 5.3.3 Proxy Ports
.. ^^^^^^^^^^^^^^^^^
..
.. The proxy listens for IDE connections on port 9001, and for debugger
.. engine connections on port 9000. As with section 5.1, these ports may
.. be configurable in the implementation.
..
.. 5.5 Feature Negotiation
.. -----------------------
..
.. Although the IDE may at any time during the debugging session send
.. feature_get or feature_set commands, the IDE should be designed to
.. negotiate the base set of features up front. Differing languages and
.. debugger engines may operate in many ways, and the IDE should be
.. prepared to handle these differences. Likewise, the IDE may dictate
.. certain features or capabilities be supported by the debugger engine.
.. In any case, the IDE should strive to work with all debugger engines
.. that support this protocol. Therefore, this section describes a
.. minimal set of features the debugger engine must support. These
.. required features are outlined here in the form of discussion,
.. actual implementation of feature arguments are detailed in section 7
.. under the feature_get and feature_set commands.
..
..
.. 6. Message Packets
.. ==================
..
.. The IDE sends simple ASCII commands to the debugger engine. The
.. debugger engine responds with XML data. The XML data is prepended
.. with a stringified integer representing the length of the XML data
.. packet. The length and XML data are separated by a NULL byte. The
.. XML data is ended with a NULL byte. Neither the IDE or debugger engine
.. packets may contain NULL bytes within the packet since it is used as
.. a separator. Binary data must be encoded using base64. ::
..
.. IDE: command [SPACE] [args] -- data [NULL]
.. DEBUGGER: [NUMBER] [NULL] XML(data) [NULL]
..
.. Arguments to the IDE commands are in the same format as common command
.. line arguments, and should be parseable by common code such as getopt,
.. or Pythons Cmd module: ::
..
.. command -a value -b value ...
..
.. All numbers in the protocol are base 10 string representations, unless
.. the number is noted to be debugger engine specific (eg. the address
.. attribute on property elements).
..
.. 6.1 Why not XML both ways?
.. --------------------------
..
.. The primary reason is to avoid the requirement that a debugger
.. engine has an XML parser available. XML is easy to generate, but
.. requires additional libraries for parsing.
..
..
.. 6.2 Packet Communications
.. -------------------------
..
.. The IDE sends a command, then waits for a response from the
.. debugger engine. If the command is not received in a reasonable
.. time (implementation dependent) it may assume the debugger engine
.. has entered a non-responsive state. The exception to this is when
.. the IDE sends a 'continuation' command which may not have an immediate response.
..
.. 'continuation' commands include, but may not be limited to: run, step_into,
.. step_over, step_out and eval. When the debugger engine
.. receives such a command, it is considered to have entered a
.. 'run state'.
..
.. During a 'continuation' command, the IDE should expect to possibly receive
.. stdin and/or stderr packets from the debugger engine prior to
.. receiving a response to the command itself. It may also possibly
.. receive error packets from either the debugger engine, or a proxy
.. if one is in use, either prior to the 'continuation' response, or in response
.. to any other command.
..
.. Stdout and stderr, if requested by the IDE, may only be sent during
.. commands that have put the debugger engine into a 'run' state.
..
.. If the debugger engine supports asynchronous commands, the IDE may also
.. send commands while the debugger engine is in a 'run' state. These
.. commands should be limited to commands such as the 'break' or 'status'
.. commands for performance reasons, but this protocol does not impose
.. such limitations. The debugger engine MUST respond to these commands
.. prior to responding to the original 'run' command.
..
.. An example of communication between IDE and debugger engines. (this
.. is not an example of the actual protocol.) ::
..
.. IDE: feature_get supports_async
.. DBG: yes
.. IDE: stdin redirect
.. DBG: ok
.. IDE: stderr redirect
.. DBG: ok
.. IDE: run
.. DBG: stdin data...
.. DBG: stdin data...
.. DBG: reached breakpoint, done running
.. IDE: give me some variables
.. DBG: ok, here they are
.. IDE: evaluate this expression
.. DBG: stderr data...
.. DBG: ok, done
.. IDE: run
.. IDE: break
.. DBG: ok, breaking
.. DBG: at breakpoint, done running
.. IDE: stop
.. DBG: good bye
..
..
.. 6.3 IDE to debugger engine communications
.. -----------------------------------------
..
.. A debugging IDE (IDE) sends commands to the debugger engine in
.. the form of command line arguments. One argument that is included in
.. all commands is the data length. The data itself is the last part of
.. the command line. The data may be binary data if the encoding argument
.. is 'binary'. ::
..
.. command [SPACE] [arguments] [SPACE] base64(data) [NULL]
..
.. Standard arguments for all commands ::
..
.. -i Transaction ID
.. unique for each command generated by the IDE
..
.. 6.4 debugger engine to IDE communications
.. -----------------------------------------
..
.. The debugger engine always replies or sends XML data. The standard
.. namespace for the root elements returned from the debugger
.. engine MUST be "urn:debugger_protocol_v1". Namespaces have been left
.. out in the examples in this document. The messages sent by the
.. debugger engine must always be NULL terminated. The XML document tag
.. must always be present to provide XML version and encoding information.
..
.. Two base tags are used for the root tags: ::
..
.. data_length
.. <?xml version="1.0" encoding="UTF-8"?>
.. <response command="command_name"
.. transaction_id="transaction_id"/>
..
.. data_length
.. <?xml version="1.0" encoding="UTF-8"?>
.. <stream type="stdout|stderr">...Base64 Data...</stream>
..
.. For simplification, data length and NULL bytes will be left out of the
.. rest of the examples in this document.
..
.. 6.5 debugger engine errors
.. --------------------------
..
.. A debugger engine may need to relay error information back to the IDE in
.. response to any command. The debugger engine may add an error element
.. as a child of the response element. Note that this is not the same
.. as getting language error messages, such as exception data. This is
.. specifically a debugger engine error in response to a IDE
.. command. IDEs and debugger engines may elect to support additional
.. child elements in the error element, but should namespace the elements
.. to avoid conflicts with other implementations. ::
..
.. <response command="command_name"
.. transaction_id="transaction_id">
.. <error code="error_code" apperr="app_specific_error_code">
.. <message>UI Usable Message</message>
.. </error>
.. </response>
..
.. 6.5.1 Error Codes
.. -----------------
..
.. The following are predefined error codes for the response to commands:
..
.. 000 Command parsing errors ::
..
.. 0 - no error
.. 1 - parse error in command
.. 2 - duplicate arguments in command
.. 3 - invalid options (ie, missing a required option)
.. 4 - Unimplemented command
.. 5 - Command not available (Is used for async commands. For instance
.. if the engine is in state "run" than only "break" and "status"
.. are available).
..
.. 100 File related errors ::
..
.. 100 - can not open file (as a reply to a "source" command if the
.. requested source file can't be opened)
.. 101 - stream redirect failed
..
.. 200 Breakpoint, or code flow errors ::
..
.. 200 - breakpoint could not be set (for some reason the breakpoint
.. could not be set due to problems registering it)
.. 201 - breakpoint type not supported (for example I don't support
.. 'watch' yet and thus return this error)
.. 202 - invalid breakpoint (the IDE tried to set a breakpoint on a
.. line that does not exist in the file (ie "line 0" or lines
.. past the end of the file)
.. 203 - no code on breakpoint line (the IDE tried to set a breakpoint
.. on a line which does not have any executable code. The
.. debugger engine is NOT required to return this type if it
.. is impossible to determine if there is code on a given
.. location. (For example, in the PHP debugger backend this
.. will only be returned in some special cases where the current
.. scope falls into the scope of the breakpoint to be set)).
.. 204 - Invalid breakpoint state (using an unsupported breakpoint state
.. was attempted)
.. 205 - No such breakpoint (used in breakpoint_get etc. to show that
.. there is no breakpoint with the given ID)
.. 206 - Error evaluating code (use from eval() (or perhaps
.. property_get for a full name get))
.. 207 - Invalid expression (the expression used for a non-eval()
.. was invalid)
..
.. 300 Data errors ::
..
.. 300 - Can not get property (when the requested property to get did
.. not exist, this is NOT used for an existing but uninitialized
.. property, which just gets the type "uninitialised" (See:
.. PreferredTypeNames)).
.. 301 - Stack depth invalid (the -d stack depth parameter did not
.. exist (ie, there were less stack elements than the number
.. requested) or the parameter was < 0)
.. 302 - Context invalid (an non existing context was requested)
..
.. 900 Protocol errors ::
..
.. 900 - Encoding not supported
.. 998 - An internal exception in the debugger occurred
.. 999 - Unknown error
..
..
.. 6.6 file paths
.. --------------
..
.. All file paths passed between the IDE and debugger engine must be in
.. the URI format specified by IETF RFC 1738 and 2396, and must be
.. absolute paths.
..
.. 6.7 Dynamic code and virtual files
.. ----------------------------------
..
.. The protocol reserves the URI scheme 'dbgp' for all virtual
.. files generated and maintained by language engines. Such
.. virtual files are usually managed by a language engine for
.. dynamic code blocks, i.e. code created at runtime, without
.. an association with a regular file. Any IDE seeing an URI
.. with the 'dbgp' scheme has to use the 'source' command (See
.. section 7.14) to obtain the contents of the file from the
.. engine responsible for that URI.
..
.. All URIs in that scheme have the form:
..
.. dbgp:engine-specific-identifier
..
.. The engine-specific-identifier is some string which the debugger engine
.. uses to keep track of the specific virtual file. The IDE must return
.. the URI to the debugger engine unchanged through the source command to
.. retrieve the virtual file.
..
.. 7. Core Commands
.. ================
..
.. Both IDE and debugger engine must support all core commands.
..
..
.. 7.2 Options and Configuration
.. -----------------------------
..
.. The feature commands are used to request feature support from the debugger
.. engine. This includes configuration options, some of which may be changed via
.. feature_set, the ability to discover support for implemented commands, and to
.. discover values for various features, such as the language version or name.
..
.. An example of usage would be to send a feature request with the string 'stdin'
.. to find out if the engine supports redirection of the stdin stream through the
.. debugger socket. The debugger engine must consider all commands as keys for this
.. command, but may also have keys that are for features that do not map directly
.. to commands.
..
.. 7.2.1 Feature Names
.. ^^^^^^^^^^^^^^^^^^^
..
.. The following features strings MUST be available:
..
.. ========================= ======= ==========================================
.. language_supports_threads get [0|1]
.. language_name get {eg. PHP, Python, Perl}
.. language_version get {version string}
.. encoding get current encoding in use by
.. the debugger session
.. protocol_version get {for now, always 1}
.. supports_async get {for commands such as break}
.. data_encoding get optional, allows to turn off
.. the default base64 encoding of data. This
.. should only be used for development and
.. debugging of the debugger engines
.. themselves, and not for general use. If
.. implemented the value 'base64' must be
.. supported to turn back on regular
.. encoding. the value 'none' means no
.. encoding is in use. all elements that use
.. encoding must include an encoding
.. attribute.
.. breakpoint_languages get some engines may support more than one
.. language. This feature returns a string
.. which is a comma separated list of
.. supported languages. **If the engine does
.. not provide this feature, then it is
.. assumed that the engine only supports the
.. language defined in the feature
.. language_name.** One example of this is an
.. XSLT debugger engine which supports XSLT,
.. XML, HTML and XHTML. An IDE may need this
.. information to to know what types of
.. breakpoints an engine will accept.
.. multiple_sessions get|set {0|1}
.. encoding get|set {ISO8859-15, UTF-8, etc.}
.. max_children get|set max number of array or object
.. children to initially retrieve
.. max_data get|set max amount of variable data to
.. get|set initially retrieve.
.. max_depth get|set maximum depth that the debugger
.. engine may return when sending arrays,
.. hashs or object structures to the IDE.
.. data_encoding get|set see feature_get
.. ========================= ======= ==========================================
..
.. The following features strings MAY be available, if they are not, the IDE should
.. assume that the feature is not available:
..
.. ========================= ======= ==========================================
.. supports_postmortem get [0|1] This feature lets an IDE know that
.. there is benefit to continuing interaction
.. during the STOPPING state (sect. 7.1).
.. show_hidden get|set [0|1] This feature can get set by the IDE
.. if it wants to have more detailed internal
.. information on properties (eg. private
.. members of classes, etc.) Zero means that
.. hidden members are not shown to the IDE.
.. notify_ok get|set [0|1] See section 8.5
.. ========================= ======= ==========================================
..
.. Additionally, all protocol commands supported must have a string,
.. such as the following examples: ::
..
.. breakpoint_set
.. break
.. eval
..
.. 7.2.3 feature_set
.. ^^^^^^^^^^^^^^^^^
..
.. The feature set command allows a IDE to tell the debugger engine what additional
.. capabilities it has. One example of this would be telling the debugger engine
.. whether the IDE supports multiple debugger sessions (for threads, etc.). The
.. debugger engine responds with telling the IDE whether it has enabled the feature
.. or not.
..
.. Note: The IDE does not have to listen for additional debugger connections if it
.. does not support debugging multiple sessions. debugger engines must handle
.. connection failures gracefully.
..
.. arguments for feature_set include:
..
.. == ==========================================
.. -n feature_name
.. -v value to be set
.. == ==========================================
..
.. feature_set can be called at any time during a debug session to
.. change values previously set. This allows a IDE to change
.. encodings.
..
.. debug client ::
..
.. feature_set -i transaction_id -n feature-name -v value
..
.. debugger engine ::
..
.. <response command="feature_set"
.. feature="feature_name"
.. success="0|1"
.. transaction_id="transaction_id"/>
..
..
.. 7.5 continuation commands
.. -------------------------
..
.. resume the execution of the application.
..
.. run:
.. starts or resumes the script until a new breakpoint is reached,
.. or the end of the script is reached.
..
.. step_into:
.. steps to the next statement, if there is a function call
.. involved it will break on the first statement in that function
..
.. step_over:
.. steps to the next statement, if there is a function call on the
.. line from which the step_over is issued then the debugger engine
.. will stop at the statement after the function call in the same
.. scope as from where the command was issued
..
.. step_out:
.. steps out of the current scope and breaks on the statement after
.. returning from the current function. (Also called 'finish' in
.. GDB)
..
.. stop:
.. ends execution of the script immediately, the debugger engine may
.. not respond, though if possible should be designed to do so.
.. The script will be terminated right away and be followed by a
.. disconnection of the network connection from the IDE (and debugger
.. engine if required in multi request apache processes).
..
.. detach (optional):
.. stops interaction with the debugger engine. Once this command
.. is executed, the IDE will no longer be able to communicate with
.. the debugger engine. This does not end execution of the script
.. as does the stop command above, but rather detaches from debugging.
.. Support of this continuation command is optional, and the IDE should
.. verify support for it via the feature_get command. If the IDE has
.. created stdin/stdout/stderr pipes for execution of the script
.. (eg. an interactive shell or other console to catch script output),
.. it should keep those open and usable by the process until the process
.. has terminated normally.
..
.. The response to a continue command is a status response (see
.. status above). The debugger engine does not send this response
.. immediately, but rather when it reaches a breakpoint, or ends
.. execution for any other reason.
..
.. debug client ::
..
.. run -i transaction_id
..
.. debugger engine ::
..
.. <response command="run"
.. status="starting"
.. reason="ok"
.. transaction_id="transaction_id"/>
..
.. 7.6 breakpoints
.. ---------------
..
.. Breakpoints are locations or conditions at which a debugger engine
.. pauses execution, responds to the IDE, and waits for further commands
.. from the IDE. A failure in any breakpoint commands results in an
.. error defined in `section 6.5`_.
..
..
.. The following DBGP commands relate to breakpoints:
..
.. ================== =================================================
.. breakpoint_set_ Set a new breakpoint on the session.
.. breakpoint_get_ Get breakpoint info for the given breakpoint id.
.. breakpoint_update_ Update one or more attributes of a breakpoint.
.. breakpoint_remove_ Remove the given breakpoint on the session.
.. breakpoint_list_ Get a list of all of the session's breakpoints.
.. ================== =================================================
..
.. .. _breakpoint_set: `7.6.1 breakpoint_set`_
.. .. _breakpoint_get: `7.6.2 breakpoint_get`_
.. .. _breakpoint_update: `7.6.3 breakpoint_update`_
.. .. _breakpoint_remove: `7.6.4 breakpoint_remove`_
.. .. _breakpoint_list: `7.6.5 breakpoint_list`_
..
..
.. There are six different breakpoints *types*:
..
.. ============== =========== =========================================
.. Type Req'd Attrs Description
.. ============== =========== =========================================
.. line filename, break on the given lineno in the given
.. lineno file
.. call function break on entry into new stack for
.. function name
.. return function break on exit from stack for function
.. name
.. exception exception break on exception of the given name
.. conditional expression break when the given expression is true
.. at the given filename and line number or
.. just in given filename
.. watch expression break on write of the variable or address
.. defined by the expression argument
.. ============== =========== =========================================
..
..
.. A breakpoint has the following attributes. Note that some attributes are only
.. applicable for some breakpoint types.
..
.. ================== ======================================================
.. type breakpoint type (see table above for valid types)
.. filename The file the breakpoint is effective in. This must be
.. a "file://" URI.
.. lineno Line number on which breakpoint is effective. Line
.. numbers are 1-based. If an implementation requires a
.. numeric value to indicate that *lineno* is not set,
.. it is suggested that -1 be used, although this is not
.. enforced.
.. state Current state of the breakpoint. This must be one of
.. *enabled*, *disabled*.
.. function Function name for *call* or *return* type
.. breakpoints.
.. temporary Flag to define if breakpoint is temporary. A
.. temporary breakpoint is one that is deleted after its
.. first use. This is useful for features like "Run to
.. Cursor". Once the debugger engine uses a temporary
.. breakpoint, it should automatically remove the breakpoint
.. from it's list of valid breakpoints.
.. hit_count Number of effective hits for the breakpoint in the
.. current session. This value is maintained by the
.. debugger engine (a.k.a. DBGP client). A
.. breakpoint's hit count should be increment whenever
.. it is considered to break execution (i.e. whenever
.. debugging comes to this line). If the breakpoint is
.. *disabled* then the hit count should NOT be
.. incremented.
.. hit_value A numeric value used together with the
.. *hit_condition* to determine if the breakpoint should
.. pause execution or be skipped.
.. hit_condition A string indicating a condition to use to compare
.. *hit_count* and *hit_value*. The following values are
.. legal:
..
.. `>=`
.. break if hit_count is greater than or equal to
.. hit_value [default]
.. `==`
.. break if hit_count is equal to hit_value
.. `%`
.. break if hit_count is a multiple of hit_value
.. exception Exception name for *exception* type breakpoints.
.. ================== ======================================================
..
.. Breakpoints should be maintained in the debugger engine at an application
.. level, not the thread level. Debugger engines that support thread debugging
.. MUST provide breakpoint id's that are global for the application, and must
.. use all breakpoints for all threads where applicable.
..
.. As for any other commands, if there is error the debugger engine should
.. return an error response as described in `section 6.5`_.
..
.. .. _`section 6.5`: `6.5 debugger engine errors`_
..
..
.. 7.6.1 breakpoint_set
.. ^^^^^^^^^^^^^^^^^^^^
..
.. This command is used by the IDE to set a breakpoint for the session.
..
.. IDE to debugger engine::
..
.. breakpoint_set -i TRANSACTION_ID [<arguments...>] -- base64(expression)
..
.. where the arguments are:
..
.. ================== =====================================================
.. -t TYPE breakpoint *type*, see below for valid values
.. -s STATE breakpoint *state* [optional, defaults to "enabled"]
.. -f FILENAME the *filename* to which the breakpoint belongs
.. -n LINENO the line number (*lineno*) of the breakpoint
.. -m FUNCTION *function* name [required for *call* or *return*
.. breakpoint types]
.. -x EXCEPTION *exception* name [required for *exception* breakpoint
.. types]
.. -h HIT_VALUE hit value (*hit_value*) used with the hit condition
.. to determine if should break; a value of zero
.. indicates hit count processing is disabled for this
.. breakpoint [optional, defaults to zero (i.e.
.. disabled)]
.. -o HIT_CONDITION hit condition string (*hit_condition*); see
.. hit_condition documentation above; BTW 'o' stands for
.. 'operator' [optional, defaults to '>=']
.. -r 0|1 Boolean value indicating if this breakpoint is
.. *temporary*. [optional, defaults to false]
.. -- EXPRESSION code *expression*, in the language of the debugger
.. engine [required for *conditional* breakpoint types]
.. ================== =====================================================
..
.. An example breakpoint_set command for a conditional breakpoint could look
.. like this::
..
.. breakpoint_set -i 1 -f test.pl -l 20 -- base64($x > 3)
..
.. A unique id for this breakpoint for this session is returned by the debugger
.. engine. This *session breakpoint id* is used by the IDE to identify the
.. breakpoint in other breakpoint commands.
..
.. debugger engine to IDE::
..
.. <response command="breakpoint_set"
.. transaction_id="TRANSACTION_ID"
.. state="STATE"
.. id="BREAKPOINT_ID"/>
..
.. where,
..
.. ================== =====================================================
.. BREAKPOINT_ID is an arbitrary string that uniquely identifies this
.. breakpoint in the debugger engine.
.. STATE the initial state of the breakpoint as set by the
.. debugger engine
.. ================== =====================================================
..
..
.. 7.6.2 breakpoint_get
.. ^^^^^^^^^^^^^^^^^^^^
..
.. This command is used by the IDE to get breakpoint information from the
.. debugger engine.
..
.. IDE to debugger engine::
..
.. breakpoint_get -i TRANSACTION_ID -d BREAKPOINT_ID
..
.. where,
..
.. ================== =====================================================
.. BREAKPOINT_ID is the unique *session breakpoint id* returned by
.. *breakpoint_set*.
.. ================== =====================================================
..
.. debugger engine to IDE::
..
.. <response command="breakpoint_get"
.. transaction_id="TRANSACTION_ID">
.. <breakpoint id="BREAKPOINT_ID"
.. type="TYPE"
.. state="STATE"
.. filename="FILENAME"
.. lineno="LINENO"
.. function="FUNCTION"
.. exception="EXCEPTION"
.. hit_value="HIT_VALUE"
.. hit_condition="HIT_CONDITION"
.. hit_count="HIT_COUNT">
.. <expression>EXPRESSION</expression>
.. </breakpoint>
.. </response>
..
.. where each breakpoint attribute is only required if its value is relevant.
.. E.g., the <expression/> child element need only be included if there is an
.. expression defined, the *function* attribute need only be included if this is
.. a *function* breakpoint.
..
..
.. 7.6.3 breakpoint_update
.. ^^^^^^^^^^^^^^^^^^^^^^^
..
.. This command is used by the IDE to update one or more attributes of a
.. breakpoint that was already set on the debugger engine via *breakpoint_set*.
..
.. IDE to debugger engine::
..
.. breakpoint_update -i TRANSACTION_ID -d BREAKPOINT_ID [<arguments...>]
..
.. where the arguments are as follows. All arguments are optional, however
.. at least one argument should be present. See breakpoint_set_ for a description of
.. each argument:
..
.. == ===============
.. -s STATE
.. -n LINENO
.. -h HIT_VALUE
.. -o HIT_CONDITION
.. == ===============
..
.. debugger engine to IDE::
..
.. <response command="breakpoint_update"
.. transaction_id="TRANSACTION_ID"/>
..
..
.. 7.6.4 breakpoint_remove
.. ^^^^^^^^^^^^^^^^^^^^^^^
..
.. This command is used by the IDE to remove the given breakpoint.
..
.. IDE to debugger engine::
..
.. breakpoint_remove -i TRANSACTION_ID -d BREAKPOINT_ID
..
.. debugger engine to IDE::
..
.. <response command="breakpoint_remove"
.. transaction_id="TRANSACTION_ID"/>
..
..
.. 7.6.5 breakpoint_list
.. ^^^^^^^^^^^^^^^^^^^^^
..
.. This command is used by the IDE to get breakpoint information for all
.. breakpoints that the debugger engine has.
..
.. IDE to debugger engine::
..
.. breakpoint_list -i TRANSACTION_ID
..
.. debugger engine to IDE::
..
.. <response command="breakpoint_list"
.. transaction_id="TRANSACTION_ID">
.. <breakpoint id="BREAKPOINT_ID"
.. type="TYPE"
.. state="STATE"
.. filename="FILENAME"
.. lineno="LINENO"
.. function="FUNCTION"
.. exception="EXCEPTION"
.. hit_value="HIT_VALUE"
.. hit_condition="HIT_CONDITION"
.. hit_count="HIT_COUNT">
.. <expression>EXPRESSION</expression>
.. </breakpoint>
.. <breakpoint ...>...</breakpoint>
.. ...
.. </response>
..
..
..
.. 7.7 stack_depth
.. ---------------
..
.. debug client ::
..
.. stack-depth -i transaction_id
..
.. debugger engine ::
..
.. <response command="stack_depth"
.. depth="{NUM}"
.. transaction_id="transaction_id"/>
..
..
.. 7.8 stack_get
.. -------------
..
.. Returns stack information for a given stack depth. For extended
.. debuggers, multiple file/line's may be returned by having
.. child elements of the stack element. This is to allow
.. for debuggers, such as XSLT, that have execution and data files.
.. The filename returned should always be the local file
.. system path translated into a file URI, and should include the
.. system name if the engine is not connecting to an ip on the local
.. box: file://systemname/c|/path. If the stack depth is
.. specified, only one stack element is returned, for the depth
.. requested, though child elements may be returned also. The
.. current context is stack depth of zero, the 'oldest' context
.. (in some languages known as 'main') is the highest numbered
.. context.
..
.. == ==========================================
.. -d stack depth (optional)
.. == ==========================================
..
.. debug client ::
..
.. stack_get -d {NUM} -i transaction_id
..
.. debugger engine ::
..
.. <response command="stack_get"
.. transaction_id="transaction_id">
.. <stack level="{NUM}"
.. type="file|eval|?"
.. filename="..."
.. lineno="{NUM}"
.. where=""
.. cmdbegin="line_number:offset"
.. cmdend="line_number:offset"/>
.. <stack level="{NUM}"
.. type="file|eval|?"
.. filename="..."
.. lineno="{NUM}">
.. <input level="{NUM}"
.. type="file|eval|?"
.. filename="..."
.. lineno="{NUM}"/>
.. </stack>