Debug (command)

{{Short description|Line-oriented debug utility in DOS}} {{Use dmy dates|date=January 2020|cs1-dates=y}} {{Use list-defined references|date=January 2022}} {{Infobox software | name = DEBUG.COM (MS-DOS <= 2.0), DEBUG.EXE (MS-DOS >= 3.x) | screenshot = File:Dosbox 001.png | author = Tim Paterson | developer = Microsoft, IBM, Digital Research, Novell, Caldera | programming language = MS-DOS: x86 assembly language | operating system = DOS, OS/2, Windows | genre = Debugger | license = MS-DOS v2.0, FreeDOS: MIT<br />OS/2, Windows: Proprietary software | website = {{URL|https://technet.microsoft.com/en-us/library/bb491040.aspx|Debug}} }} The line-oriented debugger '''<code>DEBUG.EXE</code>''' is an external command in operating systems such as DOS, OS/2 and Windows (only in 16-bit/32-bit versions<ref name="MASM for x64"/>).

DEBUG can act as an assembler, disassembler, or hex dump program allowing users to interactively examine memory contents (in assembly language, hexadecimal or ASCII), make changes, and selectively execute COM, EXE and other file types. It also has several subcommands which are used to access specific disk sectors, I/O ports and memory addresses.

==Overview== [[File:IBM PC DOS 1.0 screenshot.png|thumb|300px|<code>DEBUG.COM</code> (among other commands) in IBM PC DOS 1.0.]] [[File:Microsoft Windows 95 Version 4.00.1111 debug command 492x259.png|thumb|300px|The Microsoft Windows 95 <code>DEBUG.EXE</code> command]] Traditionally, all computers and operating systems have included a maintenance function, used to determine whether a program is working correctly.{{Citation needed|date=June 2007}} DEBUG was originally written by Tim Paterson to serve this purpose in 86-DOS. When Paterson began working for Microsoft in the early 1980s he brought the program with him. DEBUG was part of {{nowrap|DOS 1.00}} and has been included in MS-DOS/PC DOS and certain versions of Microsoft Windows. Originally named <code>DEBUG.COM</code>, the executable was renamed into <code>DEBUG.EXE</code> with MS-DOS 3.2.<ref name="Sedory"/>

Windows XP and later versions included <code>DEBUG</code> for the MS-DOS subsystem to maintain MS-DOS compatibility. The 16-bit DOS commands are not available on 64-bit editions of Windows.<ref name="MS_subsystem"/>

The MS-DOS/PC DOS DEBUG has several limitations:

* In assembly/disassembly modes it only supports 8086 opcodes. * It can only access 16-bit registers and not 32-bit extended registers. * When the "N" subcommand for naming files is used, the filename is stored from offset DS:5D to DS:67 (the Program Segment Prefix File Control Block area), meaning that the program can only save files in FAT 8.3 filename format.

Enhanced DEBUG packages include the DEBUG command in Novell DOS 7, OpenDOS 7.01 and DR-DOS 7.02 and higher, a reimplementation of Digital Research's former Symbolic Instruction Debugger SID/SID86,<ref name="DR_1982_SID86"/> which came with former versions of DR DOS.<ref name="Born_1993_DOS6"/><ref name="Paul_1997_DRDOSTIP"/><ref name="Paul_2002_SID86"/> It is fully compatible with the DEBUG command line syntax of MS-DOS/PC DOS, but offers many enhancements, including supporting 16-bit and 32-bit opcodes up to the Pentium, an extended mode (/X) with dozens of additional commands and sub-modes, a much enhanced command line syntax with user-definable macros and symbolic debugging facilities with named registers, loaded symbol tables, mathematical operations and base conversions, as well as a commenting disassembler.<ref name="Paul_1997_NWDOSTIP"/><ref name="Paul_2002_SID86"/> Some versions also utilized DPMS to function as a "stealth mode" protected-mode debugger.<ref name="Paul_2001_NWDOSTIP"/>

The FreeDOS version of DEBUG was developed by Paul Vojta and is licensed under the MIT License.<ref name="FreeDOS"/>

A 32-bit clone "DEBUGX" version supporting 32-bit DPMI programs exists as well.<ref name="Vojta"/> Andreas "Japheth" Grech, the author of the HX DOS extender, developed enhanced DEBUG versions 0.98 to 1.25, and former PC DOS developer Vernon C. Brooks added versions 1.26 to 1.32.<ref name="Brooks_2014"/>

==Syntax== <pre>DEBUG [[drive:][path] filename [parameters]]</pre>

When DEBUG is started without any parameters the DEBUG prompt, a "-" appears. The user can then enter one of several one or two-letter subcommands, including "A" to enter the assembler mode, "D" to perform a hexadecimal dump, "T" to trace and "U" to unassemble (disassemble) a program in memory.<ref name="TechNet"/> DEBUG can also be used as a "DEBUG script" interpreter using the following syntax.

DEBUG < filename

A script file may contain DEBUG subcommands and assembly language instructions.<ref name="Using_Debug"/> This method can be used to create or edit binary files from batch files.<ref name="Sedory"/>

== Debugging Subcommands == The following is a list of the DEBUG commands available from DEBUG.EXE in MS-DOS 6.22 via the '''<code>?</code>''' command. assemble A [address] compare C range address dump D [range] enter E address [list] fill F range list go G [=address] [addresses] hex H value1 value2 input I port load L [address] [drive] [firstsector] [number] move M range address name N [pathname] [arglist] output O port byte proceed P [=address] [number] quit Q register R [register] search S range list trace T [=address] [value] unassemble U [range] write W [address] [drive] [firstsector] [number] allocate expanded memory XA [#pages] deallocate expanded memory XD [handle] map expanded memory pages XM [Lpage] [Ppage] [handle] display expanded memory status XS The R command displays the current register status and values AX=0000 BX=0000 CX=0000 DX=0000 SP=FFEE BP=0000 SI=0000 DI=0000 DS=2A63 ES=2A63 SS=2A63 CS=2A63 IP=0100 NV UP EI PL NZ NA PO NC 2A63:0100 0F DB 0F While D dumps the current memory displaying both hexadecimal and ASCII values 2A63:0100 0F 00 B9 8A FF F3 AE 47-61 03 1F 8B C3 48 12 B1 .......Ga....H.. 2A63:0110 04 8B C6 F7 0A 0A D0 D3-48 DA 2B D0 34 00 52 2A ........H.+.4.R\* 2A63:0120 00 DB D2 D3 E0 03 F0 8E-DA 8B C7 16 C2 B6 01 16 ................ 2A63:0130 C0 16 F8 8E C2 AC 8A D0-00 00 4E AD 8B C8 46 8A ..........N...F. 2A63:0140 C2 24 FE 3C B0 75 05 AC-F3 AA A0 0A EB 06 3C B2 .$.<.u........<. 2A63:0150 75 6D 6D 13 A8 01 50 14-74 B1 BE 32 01 8D 8B 1E umm...P.t..2.... 2A63:0160 8E FC 12 A8 33 D2 29 E3-13 8B C2 03 C3 69 02 00 ....3.)......i.. 2A63:0170 0B F8 83 FF FF 74 11 26-01 1D E2 F3 81 00 94 FA .....t.&........ And '''U'''''nassemble'' displays the attempted disassembly of the same memory 2A63:0100 0F DB 0F 2A63:0101 00B98AFF ADD [BX+DI+FF8A],BH 2A63:0105 F3 REPZ 2A63:0106 AE SCASB 2A63:0107 47 INC DI 2A63:0108 61 DB 61 2A63:0109 031F ADD BX,[BX] 2A63:010B 8BC3 MOV AX,BX 2A63:010D 48 DEC AX 2A63:010E 12B1048B ADC DH,[BX+DI+8B04] 2A63:0112 C6F70A MOV BH,0A 2A63:0115 0AD0 OR DL,AL 2A63:0117 D348DA ROR WORD PTR [BX+SI-26],CL 2A63:011A 2BD0 SUB DX,AX 2A63:011C 3400 XOR AL,00 2A63:011E 52 PUSH DX 2A63:011F 2A00 SUB AL,[BX+SI]

==Using for non-debugging purposes== The DEBUG utility is useful for editing binary files in an environment where only DOS is installed without anything else. It can also be used to edit disk sectors, which is one method of removing boot-sector viruses.

==Availability== Although technical documentation for the DEBUG command was removed with the release of MS-DOS 3.3, the command was retained in the standard distribution, unlike what was done with EXE2BIN.<ref name="Dror_1988"/>

==Other operating systems== The operating systems Intel ISIS-II<ref name="ISIS"/> and iRMX 86,<ref name="iRMX"/> DEC TOPS-10<ref name="TOPS-10"/> and TOPS-20,<ref name="CMDref"/> THEOS/OASIS,<ref name="OASIS"/> Zilog Z80-RIO,<ref name="Z80-RIO"/> Stratus OpenVOS,<ref name="VOS"/> PC-MOS,<ref name="PC-MOS"/> and AROS<ref name="AROS"/> also provide a <code>DEBUG</code> command.

==See also== * List of DOS commands * DDT (CP/M command) (Dynamic Debugging Technique) * SID (Symbolic Instruction Debugger) * SYMDEB * CodeView * Turbo Debugger * SoftICE * DEBUG (tag)

==References== {{Reflist|refs= <ref name="Sedory">{{cite web |author-first=Daniel B. |author-last=Sedory |title=A Guide to DEBUG |access-date=2014-11-29 |url=http://thestarman.pcministry.com/asm/debug/debug.htm}}</ref> <ref name="MASM for x64">According to [http://msdn.microsoft.com/en-us/library/hb5z4sxd.aspx Microsoft Macro Assembler Reference], inline assembly is not supported for x64.</ref> <ref name="MS_subsystem">[https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-xp/bb490895(v%3dtechnet.10) MS-DOS subsystem commands]</ref> <ref name="TechNet">{{cite web |title=Microsoft TechNet Debug article |url=https://technet.microsoft.com/en-us/library/bb491040.aspx |access-date=2008-04-23}}</ref> <ref name="Born_1993_DOS6">{{cite book |author-first=Günter |author-last=Born |author-link=:de:Günter Born |title=DOS 6 Tuning |language=de |publisher=Markt & Technik |date=1993 |edition=1 |isbn=3-87791-495-0}} (NB. Has several pages on MS-DOS DEBUG.EXE as well as on the Symbolic Instruction Debugger SID.EXE in DR DOS 5.0/6.0.)</ref> <ref name="Paul_1997_DRDOSTIP">{{cite book |title=DRDOSTIP.TXT — Tips und Tricks für DR DOS 3.41 - 5.0 |work=MPDOSTIP |author-first=Matthias R. |author-last=Paul |date=1997-05-24 |orig-date=1991 |edition=47 |language=de |url=http://www.antonis.de/dos/dos-tuts/mpdostip/html/drdostip.htm |access-date=2016-11-07 |url-status=live |archive-url=https://web.archive.org/web/20161107125452/http://www.antonis.de/dos/dos-tuts/mpdostip/html/drdostip.htm |archive-date=2016-11-07}} (NB. Has some information on Symbolic Instruction Debugger (SID86.EXE in DR DOS 3.41 and SID.EXE in DR DOS 5.0/6.0), the predecessor of the DR-DOS DEBUG.EXE.)</ref> <ref name="Paul_1997_NWDOSTIP">{{cite book |title=NWDOS-TIPs — Tips & Tricks rund um Novell DOS 7, mit Blick auf undokumentierte Details, Bugs und Workarounds |chapter=Kapitel II.5. Allgemeines: Undokumentierte Möglichkeiten von DEBUG |trans-chapter=Undocumented features of DEBUG |work=MPDOSTIP |author-first=Matthias R. |author-last=Paul |date=1997-07-30 |edition=3 |version=Release 157 |language=de |url=http://www.antonis.de/dos/dos-tuts/mpdostip/html/nwdostip.htm |access-date=2014-09-06 |url-status=live |archive-url=https://web.archive.org/web/20170910194752/http://www.antonis.de/dos/dos-tuts/mpdostip/html/nwdostip.htm |archive-date=2017-09-10}} (NB. NWDOSTIP.TXT is a comprehensive work on Novell DOS 7 and OpenDOS 7.01, including the description of many undocumented features and internals. It is part of the author's yet larger MPDOSTIP.ZIP collection maintained up to 2001 and distributed on many sites at the time. The provided link points to a HTML-converted older version of the NWDOSTIP.TXT file.)</ref> <ref name="Paul_2001_NWDOSTIP">{{cite book |title=NWDOS-TIPs — Tips & Tricks rund um Novell DOS 7, mit Blick auf undokumentierte Details, Bugs und Workarounds |work=MPDOSTIP |author-first=Matthias R. |author-last=Paul |date=2001-04-09 |edition=3 |version=Release 183 |language=de}}</ref> <ref name="Paul_2002_SID86">{{cite newsgroup |title=SID86 |author-first=Matthias R. |author-last=Paul |date=2002-01-09 |newsgroup=comp.os.cpm |url=https://groups.google.com/d/msg/comp.os.cpm/KG4R7ZNvHK8/U5LAkmjcxYgJ |access-date=2018-04-08 |quote=[…] Since the DR-DOS 7.03 DEBUG is still based on the old SID86.EXE, I suggest to run DEBUG 1.51 and enter the extended help system with ?? from the debug prompt. This will give you eight screens full of syntax and feature help. Some of these features were also supported by older issues. […]}}</ref> <ref name="Vojta">{{cite web |url=http://japheth.de/Debug/README.TXT |title=DEBUG README |access-date=2007-06-25 |author-first=Paul |author-last=Vojta |url-status=dead |archive-url=https://web.archive.org/web/20070824025835/http://www.japheth.de/Debug/README.TXT |archive-date=2007-08-24}}</ref> <ref name="FreeDOS">{{cite web|url=http://www.ibiblio.org/pub/micro/pc-stuff/freedos/files/distributions/1.2/repos/pkg-html/debug.html |title=FreeDOS 1.2 Updates Package - debug (FreeDOS Base) |publisher=Ibiblio.org |date=2021-02-16 |accessdate=2022-09-08}}</ref> <ref name="Brooks_2014">{{cite web |author-first=Vernon C. |author-last=Brooks |title=Enhanced DEBUG for PC DOS and MS-DOS |url=https://pcdosretro.github.io/enhdebug.htm |work=PC DOS Retro |date=2014-04-08 |access-date=2014-05-08 |url-status=live |archive-url=https://web.archive.org/web/20200221141005/https://sites.google.com/site/pcdosretro/enhdebug |archive-date=2020-02-21}}</ref> <ref name="Using_Debug">{{cite book |title=Assembly language for Intel-based computers|url=http://kipirvine.com/asm/debug/Debug_Tutorial.pdf |date=2010 |author-first=Kip R. |author-last=Irvine |isbn=978-0-13602212-1 |edition=6th |publisher=Prentice Hall |section=Using Debug |access-date=2014-03-18}}</ref> <ref name="ISIS">[http://bitsavers.org/pdf/intel/ISIS_II/9800306-06_ISIS-II_Users_Guide_May81.pdf ISIS II Users Guide]</ref> <ref name="iRMX">[https://archive.org/details/bitsavers_inteliRMX1_19819263 iRMX 86 Introduction And Operator's Reference Manual For Release 6]</ref> <ref name="TOPS-10">{{Cite book |title=TOPS-10 Operating System Commands Manual |date=August 1980 |publisher=Digital Equipment Corporation |url=http://scandocs.trailing-edge.com/tops10-aa-0916d-tb.pdf |access-date=2019-02-17 |archive-date=2020-08-09 |archive-url=https://web.archive.org/web/20200809145058/http://scandocs.trailing-edge.com/tops10-aa-0916d-tb.pdf |url-status=dead }}</ref> <ref name="CMDref">{{cite web |url=http://www.textfiles.com/bitsavers/pdf/dec/pdp10/TOPS20/V6.1/AA-FP65A-TM_tops20CmdsRef.pdf |title=TOPS-20 Command manual |access-date=2018-07-18 |archive-date=2020-08-09 |archive-url=https://web.archive.org/web/20200809103116/http://www.textfiles.com/bitsavers/pdf/dec/pdp10/TOPS20/V6.1/AA-FP65A-TM_tops20CmdsRef.pdf |url-status=dead }}</ref> <ref name="OASIS">[http://www.bitsavers.org/pdf/phaseOneSystems/THEOS_OASIS_Users_Handbook_1985.pdf THEOS/OASIS User′s Handbook]</ref> <ref name="Z80-RIO">{{Cite web |url=https://www.z80cpu.eu/mirrors/oldcomputers.dyndns.org/public/pub/rechner/zilog/zds/z80-rio_os_userman.pdf |title=Z80-RIO Operating System User's Manual |access-date=2019-05-04 |archive-date=2022-01-28 |archive-url=https://web.archive.org/web/20220128041146/https://www.z80cpu.eu/mirrors/oldcomputers.dyndns.org/public/pub/rechner/zilog/zds/z80-rio_os_userman.pdf |url-status=dead }}</ref> <ref name="VOS">{{cite web |url=http://stratadoc.stratus.com/vos/19.1.0/r098-19/wwhelp/wwhimpl/common/html/r098-19.pdf |title=OpenVOS Commands Reference Manual}}</ref> <ref name="PC-MOS">[https://github.com/roelandjansen/pcmos386v501/blob/master/DOCS/v4/PCMOSv4UserManual.pdf PC-MOS User Guide]</ref> <ref name="AROS">{{cite web|url=https://aros.sourceforge.net/documentation/users/shell/index.php|title=AROS Research Operating System|access-date=2025-08-09 |archive-date=2019-07-02 |archive-url=https://web.archive.org/web/20190702203042/http://aros.sourceforge.net/documentation/users/shell/index.php|url-status=dead}}</ref> <ref name="DR_1982_SID86">{{cite book |title=SID-86 User's Guide for CP/M-86 |date=August 1982 |orig-date=March 1982 |edition=2 |publisher=Digital Research |id=SID86UG.WS4 |url=http://www.cpm.z80.de/manuals/SID86_User_Guide.txt |access-date=2020-02-06 |url-status=live |archive-url=https://web.archive.org/web/20191020123025/http://www.cpm.z80.de/manuals/SID86_User_Guide.txt |archive-date=2019-10-20}} [https://web.archive.org/web/20200208055456/https://archive.computerhistory.org/resources/access/text/2016/12/102762507-05-01-acc.pdf] (NB. A retyped version of the manual by Emmanuel Roche with Q, SR, and Z commands added. This manual is for the CP/M-86 version, but the DR DOS version is similar.)</ref> <ref name="Dror_1988">{{cite magazine |title=Thank You, IBM |author-first=Asael |author-last=Dror |magazine=PC Magazine |date=1988-01-12 |page=366}}</ref> }}

==External links== {{Wikibooks|Guide to Windows Commands}} * [https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc722863(v=technet.10) Debug | Microsoft Docs] * [https://github.com/microsoft/MS-DOS/blob/master/v2.0/source/DEBUG.ASM Open source DEBUG implementation that comes with MS-DOS v2.0]

Category:Assemblers Category:Debuggers Category:Disassemblers Category:External DOS commands Category:Microsoft free software Category:OS/2 commands