From: Takuo Yasunaga Date: Mon, 26 May 2014 17:46:56 +0000 (+0900) Subject: modified: env/Eos_env X-Git-Tag: v2.3.65p0294~162^2~9^2~66 X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=a169a952764020491773094f0992fad092a4930a;p=eos%2Fbase.git modified: env/Eos_env modify util/HOSTDIR/bin modified: include/Matrix3D.h modified: include/eosPoint.h modified: include/genUtil.h modified: include/lmrcImageMasking.h modified: src/Objects/General/Matrix3D/inc/Matrix3D.h modified: src/Objects/General/Memory/inc/Memory.h modified: src/Objects/General/Memory/src/memoryAllocate.c modified: src/Objects/General/Memory/src/memoryByteSwap.c new file: src/Objects/General/eosFunc/* Add a new object of eosFunc: Sync/Rect modified: src/Objects/General/eosPoint/* Add eosPoint for maker new file: bin/eosPointRotation new file: src/Tools/rec3d/marker2Dto3DEstimator/* Not yet completed --- diff --git a/bin/X86MAC64/eosPointRotation b/bin/X86MAC64/eosPointRotation new file mode 100755 index 0000000000..a95af816cd Binary files /dev/null and b/bin/X86MAC64/eosPointRotation differ diff --git a/lib/X86MAC64/libAI.a b/lib/X86MAC64/libAI.a index 500de116e7..c82faa0cb8 100644 Binary files a/lib/X86MAC64/libAI.a and b/lib/X86MAC64/libAI.a differ diff --git a/lib/X86MAC64/libArray.a b/lib/X86MAC64/libArray.a index f761b47fb7..429dcef038 100644 Binary files a/lib/X86MAC64/libArray.a and b/lib/X86MAC64/libArray.a differ diff --git a/lib/X86MAC64/libCluster.a b/lib/X86MAC64/libCluster.a index bc19eecdd3..7c46c278ff 100644 Binary files a/lib/X86MAC64/libCluster.a and b/lib/X86MAC64/libCluster.a differ diff --git a/lib/X86MAC64/libContour.a b/lib/X86MAC64/libContour.a index 71563a1679..e869d2a7fa 100644 Binary files a/lib/X86MAC64/libContour.a and b/lib/X86MAC64/libContour.a differ diff --git a/lib/X86MAC64/libCrystal.a b/lib/X86MAC64/libCrystal.a index c28031644e..0c42136663 100644 Binary files a/lib/X86MAC64/libCrystal.a and b/lib/X86MAC64/libCrystal.a differ diff --git a/lib/X86MAC64/libEosObjects.a b/lib/X86MAC64/libEosObjects.a index 5af385ad5b..13febf4fc8 100644 Binary files a/lib/X86MAC64/libEosObjects.a and b/lib/X86MAC64/libEosObjects.a differ diff --git a/lib/X86MAC64/libEosObjects.debug.a b/lib/X86MAC64/libEosObjects.debug.a index 643d60e547..4bb068c5e1 100644 Binary files a/lib/X86MAC64/libEosObjects.debug.a and b/lib/X86MAC64/libEosObjects.debug.a differ diff --git a/lib/X86MAC64/libFile.a b/lib/X86MAC64/libFile.a index dd1df20e33..79e318cdbe 100644 Binary files a/lib/X86MAC64/libFile.a and b/lib/X86MAC64/libFile.a differ diff --git a/lib/X86MAC64/libMATH.a b/lib/X86MAC64/libMATH.a index 4eb3af6665..3e8bbb40de 100644 Binary files a/lib/X86MAC64/libMATH.a and b/lib/X86MAC64/libMATH.a differ diff --git a/lib/X86MAC64/libMap2D.a b/lib/X86MAC64/libMap2D.a index a7f8c88056..ccdf2f3d6b 100644 Binary files a/lib/X86MAC64/libMap2D.a and b/lib/X86MAC64/libMap2D.a differ diff --git a/lib/X86MAC64/libMatrix3D.a b/lib/X86MAC64/libMatrix3D.a index 460e760954..d7ad0a60b5 100644 Binary files a/lib/X86MAC64/libMatrix3D.a and b/lib/X86MAC64/libMatrix3D.a differ diff --git a/lib/X86MAC64/libMatrix3D.debug.a b/lib/X86MAC64/libMatrix3D.debug.a index 05c1d850a1..56ef2258a1 100644 Binary files a/lib/X86MAC64/libMatrix3D.debug.a and b/lib/X86MAC64/libMatrix3D.debug.a differ diff --git a/lib/X86MAC64/libMemory.a b/lib/X86MAC64/libMemory.a index 4535b1c951..411558779a 100644 Binary files a/lib/X86MAC64/libMemory.a and b/lib/X86MAC64/libMemory.a differ diff --git a/lib/X86MAC64/libMemory.so b/lib/X86MAC64/libMemory.so index fa2d667677..b9ef7d8943 100644 Binary files a/lib/X86MAC64/libMemory.so and b/lib/X86MAC64/libMemory.so differ diff --git a/lib/X86MAC64/libPVM.a b/lib/X86MAC64/libPVM.a index 49f24e4942..06fbce5378 100644 Binary files a/lib/X86MAC64/libPVM.a and b/lib/X86MAC64/libPVM.a differ diff --git a/lib/X86MAC64/libRandom.a b/lib/X86MAC64/libRandom.a index 3c177f962c..960abda1e6 100644 Binary files a/lib/X86MAC64/libRandom.a and b/lib/X86MAC64/libRandom.a differ diff --git a/lib/X86MAC64/libSocket.a b/lib/X86MAC64/libSocket.a index 2246791335..8a8746a351 100644 Binary files a/lib/X86MAC64/libSocket.a and b/lib/X86MAC64/libSocket.a differ diff --git a/lib/X86MAC64/libSpecialNumber.a b/lib/X86MAC64/libSpecialNumber.a index cbeca484e0..dc8e715557 100644 Binary files a/lib/X86MAC64/libSpecialNumber.a and b/lib/X86MAC64/libSpecialNumber.a differ diff --git a/lib/X86MAC64/libString.a b/lib/X86MAC64/libString.a index 0239041379..6949616756 100644 Binary files a/lib/X86MAC64/libString.a and b/lib/X86MAC64/libString.a differ diff --git a/lib/X86MAC64/libTclTk.a b/lib/X86MAC64/libTclTk.a index a2e6090a6f..bc0b112813 100644 Binary files a/lib/X86MAC64/libTclTk.a and b/lib/X86MAC64/libTclTk.a differ diff --git a/lib/X86MAC64/libVector.a b/lib/X86MAC64/libVector.a index 1d8a1a104b..411b5fa643 100644 Binary files a/lib/X86MAC64/libVector.a and b/lib/X86MAC64/libVector.a differ diff --git a/lib/X86MAC64/libalsa.a b/lib/X86MAC64/libalsa.a index a6bb8666ee..2c75cb3fa6 100644 Binary files a/lib/X86MAC64/libalsa.a and b/lib/X86MAC64/libalsa.a differ diff --git a/lib/X86MAC64/libavsFile.a b/lib/X86MAC64/libavsFile.a index f405143210..7a738a67a2 100644 Binary files a/lib/X86MAC64/libavsFile.a and b/lib/X86MAC64/libavsFile.a differ diff --git a/lib/X86MAC64/libctfInfo.a b/lib/X86MAC64/libctfInfo.a index c3e1cf860f..27d6d717db 100644 Binary files a/lib/X86MAC64/libctfInfo.a and b/lib/X86MAC64/libctfInfo.a differ diff --git a/lib/X86MAC64/libdsn6File.a b/lib/X86MAC64/libdsn6File.a index d045b61e6e..d6dfe82161 100644 Binary files a/lib/X86MAC64/libdsn6File.a and b/lib/X86MAC64/libdsn6File.a differ diff --git a/lib/X86MAC64/libdummy.a b/lib/X86MAC64/libdummy.a index cd21151d66..fa1d2cf01e 100644 Binary files a/lib/X86MAC64/libdummy.a and b/lib/X86MAC64/libdummy.a differ diff --git a/lib/X86MAC64/libemData.a b/lib/X86MAC64/libemData.a index ca38e60eac..f84ebe9de0 100644 Binary files a/lib/X86MAC64/libemData.a and b/lib/X86MAC64/libemData.a differ diff --git a/lib/X86MAC64/libeosFunc.a b/lib/X86MAC64/libeosFunc.a new file mode 100644 index 0000000000..a58c6e9ffd Binary files /dev/null and b/lib/X86MAC64/libeosFunc.a differ diff --git a/lib/X86MAC64/libeosFunc.so b/lib/X86MAC64/libeosFunc.so new file mode 100644 index 0000000000..3b0c12c391 Binary files /dev/null and b/lib/X86MAC64/libeosFunc.so differ diff --git a/lib/X86MAC64/libeosPThread.a b/lib/X86MAC64/libeosPThread.a index ab02a2efdc..b7450f6110 100644 Binary files a/lib/X86MAC64/libeosPThread.a and b/lib/X86MAC64/libeosPThread.a differ diff --git a/lib/X86MAC64/libeosPoint.a b/lib/X86MAC64/libeosPoint.a index 34f9e72f89..8b0e13475f 100644 Binary files a/lib/X86MAC64/libeosPoint.a and b/lib/X86MAC64/libeosPoint.a differ diff --git a/lib/X86MAC64/libeosPoint.debug.a b/lib/X86MAC64/libeosPoint.debug.a new file mode 100644 index 0000000000..1c5d4556df Binary files /dev/null and b/lib/X86MAC64/libeosPoint.debug.a differ diff --git a/lib/X86MAC64/libgifFile.a b/lib/X86MAC64/libgifFile.a index d99d39e400..3169c69e16 100644 Binary files a/lib/X86MAC64/libgifFile.a and b/lib/X86MAC64/libgifFile.a differ diff --git a/lib/X86MAC64/libhf2000.a b/lib/X86MAC64/libhf2000.a index 51d2fcdcaa..1b4d46630b 100644 Binary files a/lib/X86MAC64/libhf2000.a and b/lib/X86MAC64/libhf2000.a differ diff --git a/lib/X86MAC64/liblargeIP.a b/lib/X86MAC64/liblargeIP.a index ccb0969c09..74d2d8e547 100644 Binary files a/lib/X86MAC64/liblargeIP.a and b/lib/X86MAC64/liblargeIP.a differ diff --git a/lib/X86MAC64/libllData.a b/lib/X86MAC64/libllData.a index fcf1bf8614..cf50d463b4 100644 Binary files a/lib/X86MAC64/libllData.a and b/lib/X86MAC64/libllData.a differ diff --git a/lib/X86MAC64/libltlgData.a b/lib/X86MAC64/libltlgData.a index db323f3af1..40156aad99 100644 Binary files a/lib/X86MAC64/libltlgData.a and b/lib/X86MAC64/libltlgData.a differ diff --git a/lib/X86MAC64/libmrcImage.a b/lib/X86MAC64/libmrcImage.a index 0dafd80222..d9619fe92f 100644 Binary files a/lib/X86MAC64/libmrcImage.a and b/lib/X86MAC64/libmrcImage.a differ diff --git a/lib/X86MAC64/libopenGL.a b/lib/X86MAC64/libopenGL.a index 6d47955c8c..0d5965d221 100644 Binary files a/lib/X86MAC64/libopenGL.a and b/lib/X86MAC64/libopenGL.a differ diff --git a/lib/X86MAC64/libpdbFile.a b/lib/X86MAC64/libpdbFile.a index 345b4dc9aa..24f6f2893b 100644 Binary files a/lib/X86MAC64/libpdbFile.a and b/lib/X86MAC64/libpdbFile.a differ diff --git a/lib/X86MAC64/libpsFile.a b/lib/X86MAC64/libpsFile.a index 6a296b4bce..4696ff3fe8 100644 Binary files a/lib/X86MAC64/libpsFile.a and b/lib/X86MAC64/libpsFile.a differ diff --git a/lib/X86MAC64/libsimulation.a b/lib/X86MAC64/libsimulation.a index 4bcf07cae8..c35a0b180e 100644 Binary files a/lib/X86MAC64/libsimulation.a and b/lib/X86MAC64/libsimulation.a differ diff --git a/lib/X86MAC64/libtgaFile.a b/lib/X86MAC64/libtgaFile.a index d90b0869f7..16077eb6db 100644 Binary files a/lib/X86MAC64/libtgaFile.a and b/lib/X86MAC64/libtgaFile.a differ diff --git a/lib/X86MAC64/libtransform.a b/lib/X86MAC64/libtransform.a index d99e380569..bdf1d61129 100644 Binary files a/lib/X86MAC64/libtransform.a and b/lib/X86MAC64/libtransform.a differ diff --git a/lib/X86MAC64/shared/eosFunc.sharedo b/lib/X86MAC64/shared/eosFunc.sharedo new file mode 100644 index 0000000000..0278a4dde4 Binary files /dev/null and b/lib/X86MAC64/shared/eosFunc.sharedo differ diff --git a/lib/X86MAC64/shared/eosPointCopy.sharedo b/lib/X86MAC64/shared/eosPointCopy.sharedo new file mode 100644 index 0000000000..8fb7a2b4a1 Binary files /dev/null and b/lib/X86MAC64/shared/eosPointCopy.sharedo differ diff --git a/lib/X86MAC64/shared/eosPointRead.sharedo b/lib/X86MAC64/shared/eosPointRead.sharedo index 9f43ce2d80..20945a1b3e 100644 Binary files a/lib/X86MAC64/shared/eosPointRead.sharedo and b/lib/X86MAC64/shared/eosPointRead.sharedo differ diff --git a/lib/X86MAC64/shared/eosPointRotate.sharedo b/lib/X86MAC64/shared/eosPointRotate.sharedo new file mode 100644 index 0000000000..3f815af0fe Binary files /dev/null and b/lib/X86MAC64/shared/eosPointRotate.sharedo differ diff --git a/lib/X86MAC64/shared/eosPointUtil.sharedo b/lib/X86MAC64/shared/eosPointUtil.sharedo new file mode 100644 index 0000000000..134222636f Binary files /dev/null and b/lib/X86MAC64/shared/eosPointUtil.sharedo differ diff --git a/lib/X86MAC64/shared/eosPointWrite.sharedo b/lib/X86MAC64/shared/eosPointWrite.sharedo new file mode 100644 index 0000000000..020defa74d Binary files /dev/null and b/lib/X86MAC64/shared/eosPointWrite.sharedo differ diff --git a/lib/X86MAC64/shared/lmrc2Dto3D.sharedo b/lib/X86MAC64/shared/lmrc2Dto3D.sharedo index 3eb5a8be96..f394b9a266 100644 Binary files a/lib/X86MAC64/shared/lmrc2Dto3D.sharedo and b/lib/X86MAC64/shared/lmrc2Dto3D.sharedo differ diff --git a/lib/X86MAC64/shared/lmrcImageDensity.sharedo b/lib/X86MAC64/shared/lmrcImageDensity.sharedo index 4725bb9218..94e125c9af 100644 Binary files a/lib/X86MAC64/shared/lmrcImageDensity.sharedo and b/lib/X86MAC64/shared/lmrcImageDensity.sharedo differ diff --git a/lib/X86MAC64/shared/lmrcImageRhoFiltering.sharedo b/lib/X86MAC64/shared/lmrcImageRhoFiltering.sharedo index 9f1f678520..002d3a8878 100644 Binary files a/lib/X86MAC64/shared/lmrcImageRhoFiltering.sharedo and b/lib/X86MAC64/shared/lmrcImageRhoFiltering.sharedo differ diff --git a/lib/X86MAC64/shared/memoryAllocate.sharedo b/lib/X86MAC64/shared/memoryAllocate.sharedo index 76e82241f1..00765718ca 100644 Binary files a/lib/X86MAC64/shared/memoryAllocate.sharedo and b/lib/X86MAC64/shared/memoryAllocate.sharedo differ diff --git a/lib/X86MAC64/shared/memoryByteSwap.sharedo b/lib/X86MAC64/shared/memoryByteSwap.sharedo index 3e2fd15b16..cf7a5245b7 100644 Binary files a/lib/X86MAC64/shared/memoryByteSwap.sharedo and b/lib/X86MAC64/shared/memoryByteSwap.sharedo differ diff --git a/src/Objects/DataExpress/Contour/src/X86MAC64/libContour.a b/src/Objects/DataExpress/Contour/src/X86MAC64/libContour.a index 71563a1679..e869d2a7fa 100644 Binary files a/src/Objects/DataExpress/Contour/src/X86MAC64/libContour.a and b/src/Objects/DataExpress/Contour/src/X86MAC64/libContour.a differ diff --git a/src/Objects/DataExpress/Contour/src/X86MAC64/libContour.debug.a b/src/Objects/DataExpress/Contour/src/X86MAC64/libContour.debug.a index bbe18582a1..7f0eb4be8d 100644 Binary files a/src/Objects/DataExpress/Contour/src/X86MAC64/libContour.debug.a and b/src/Objects/DataExpress/Contour/src/X86MAC64/libContour.debug.a differ diff --git a/src/Objects/DataExpress/TclTk/src/X86MAC64/libTclTk.a b/src/Objects/DataExpress/TclTk/src/X86MAC64/libTclTk.a index a2e6090a6f..bc0b112813 100644 Binary files a/src/Objects/DataExpress/TclTk/src/X86MAC64/libTclTk.a and b/src/Objects/DataExpress/TclTk/src/X86MAC64/libTclTk.a differ diff --git a/src/Objects/DataExpress/TclTk/src/X86MAC64/libTclTk.debug.a b/src/Objects/DataExpress/TclTk/src/X86MAC64/libTclTk.debug.a index 2742e7b41f..060b9e5041 100644 Binary files a/src/Objects/DataExpress/TclTk/src/X86MAC64/libTclTk.debug.a and b/src/Objects/DataExpress/TclTk/src/X86MAC64/libTclTk.debug.a differ diff --git a/src/Objects/DataExpress/alsa/src/X86MAC64/libalsa.a b/src/Objects/DataExpress/alsa/src/X86MAC64/libalsa.a index a6bb8666ee..2c75cb3fa6 100644 Binary files a/src/Objects/DataExpress/alsa/src/X86MAC64/libalsa.a and b/src/Objects/DataExpress/alsa/src/X86MAC64/libalsa.a differ diff --git a/src/Objects/DataExpress/alsa/src/X86MAC64/libalsa.debug.a b/src/Objects/DataExpress/alsa/src/X86MAC64/libalsa.debug.a index d742b2992c..87429b9b09 100644 Binary files a/src/Objects/DataExpress/alsa/src/X86MAC64/libalsa.debug.a and b/src/Objects/DataExpress/alsa/src/X86MAC64/libalsa.debug.a differ diff --git a/src/Objects/DataExpress/avsFile/src/X86MAC64/libavsFile.a b/src/Objects/DataExpress/avsFile/src/X86MAC64/libavsFile.a index f405143210..7a738a67a2 100644 Binary files a/src/Objects/DataExpress/avsFile/src/X86MAC64/libavsFile.a and b/src/Objects/DataExpress/avsFile/src/X86MAC64/libavsFile.a differ diff --git a/src/Objects/DataExpress/avsFile/src/X86MAC64/libavsFile.debug.a b/src/Objects/DataExpress/avsFile/src/X86MAC64/libavsFile.debug.a index 3bfea32247..cd495e7815 100644 Binary files a/src/Objects/DataExpress/avsFile/src/X86MAC64/libavsFile.debug.a and b/src/Objects/DataExpress/avsFile/src/X86MAC64/libavsFile.debug.a differ diff --git a/src/Objects/DataExpress/gifFile/src/X86MAC64/libgifFile.a b/src/Objects/DataExpress/gifFile/src/X86MAC64/libgifFile.a index d99d39e400..3169c69e16 100644 Binary files a/src/Objects/DataExpress/gifFile/src/X86MAC64/libgifFile.a and b/src/Objects/DataExpress/gifFile/src/X86MAC64/libgifFile.a differ diff --git a/src/Objects/DataExpress/gifFile/src/X86MAC64/libgifFile.debug.a b/src/Objects/DataExpress/gifFile/src/X86MAC64/libgifFile.debug.a index 38bf81116e..13ada726b5 100644 Binary files a/src/Objects/DataExpress/gifFile/src/X86MAC64/libgifFile.debug.a and b/src/Objects/DataExpress/gifFile/src/X86MAC64/libgifFile.debug.a differ diff --git a/src/Objects/DataExpress/openGL/src/X86MAC64/libopenGL.a b/src/Objects/DataExpress/openGL/src/X86MAC64/libopenGL.a index 6d47955c8c..0d5965d221 100644 Binary files a/src/Objects/DataExpress/openGL/src/X86MAC64/libopenGL.a and b/src/Objects/DataExpress/openGL/src/X86MAC64/libopenGL.a differ diff --git a/src/Objects/DataExpress/openGL/src/X86MAC64/libopenGL.debug.a b/src/Objects/DataExpress/openGL/src/X86MAC64/libopenGL.debug.a index 442f8d2f23..a1aaadace0 100644 Binary files a/src/Objects/DataExpress/openGL/src/X86MAC64/libopenGL.debug.a and b/src/Objects/DataExpress/openGL/src/X86MAC64/libopenGL.debug.a differ diff --git a/src/Objects/DataExpress/psFile/src/X86MAC64/libpsFile.a b/src/Objects/DataExpress/psFile/src/X86MAC64/libpsFile.a index 6a296b4bce..4696ff3fe8 100644 Binary files a/src/Objects/DataExpress/psFile/src/X86MAC64/libpsFile.a and b/src/Objects/DataExpress/psFile/src/X86MAC64/libpsFile.a differ diff --git a/src/Objects/DataExpress/psFile/src/X86MAC64/libpsFile.debug.a b/src/Objects/DataExpress/psFile/src/X86MAC64/libpsFile.debug.a index d5c838f380..533aa645c5 100644 Binary files a/src/Objects/DataExpress/psFile/src/X86MAC64/libpsFile.debug.a and b/src/Objects/DataExpress/psFile/src/X86MAC64/libpsFile.debug.a differ diff --git a/src/Objects/DataManip/MATH/src/X86MAC64/libMATH.a b/src/Objects/DataManip/MATH/src/X86MAC64/libMATH.a index 4eb3af6665..3e8bbb40de 100644 Binary files a/src/Objects/DataManip/MATH/src/X86MAC64/libMATH.a and b/src/Objects/DataManip/MATH/src/X86MAC64/libMATH.a differ diff --git a/src/Objects/DataManip/MATH/src/X86MAC64/libMATH.debug.a b/src/Objects/DataManip/MATH/src/X86MAC64/libMATH.debug.a index 3516a56ea6..2b234aa80e 100644 Binary files a/src/Objects/DataManip/MATH/src/X86MAC64/libMATH.debug.a and b/src/Objects/DataManip/MATH/src/X86MAC64/libMATH.debug.a differ diff --git a/src/Objects/DataManip/ctfInfo/src/X86MAC64/libctfInfo.a b/src/Objects/DataManip/ctfInfo/src/X86MAC64/libctfInfo.a index c3e1cf860f..27d6d717db 100644 Binary files a/src/Objects/DataManip/ctfInfo/src/X86MAC64/libctfInfo.a and b/src/Objects/DataManip/ctfInfo/src/X86MAC64/libctfInfo.a differ diff --git a/src/Objects/DataManip/ctfInfo/src/X86MAC64/libctfInfo.debug.a b/src/Objects/DataManip/ctfInfo/src/X86MAC64/libctfInfo.debug.a index 364e3807ff..2bb6052094 100644 Binary files a/src/Objects/DataManip/ctfInfo/src/X86MAC64/libctfInfo.debug.a and b/src/Objects/DataManip/ctfInfo/src/X86MAC64/libctfInfo.debug.a differ diff --git a/src/Objects/DataManip/dsn6File/src/X86MAC64/libdsn6File.a b/src/Objects/DataManip/dsn6File/src/X86MAC64/libdsn6File.a index d045b61e6e..d6dfe82161 100644 Binary files a/src/Objects/DataManip/dsn6File/src/X86MAC64/libdsn6File.a and b/src/Objects/DataManip/dsn6File/src/X86MAC64/libdsn6File.a differ diff --git a/src/Objects/DataManip/dsn6File/src/X86MAC64/libdsn6File.debug.a b/src/Objects/DataManip/dsn6File/src/X86MAC64/libdsn6File.debug.a index 0ca4769746..5cfc7c4c7a 100644 Binary files a/src/Objects/DataManip/dsn6File/src/X86MAC64/libdsn6File.debug.a and b/src/Objects/DataManip/dsn6File/src/X86MAC64/libdsn6File.debug.a differ diff --git a/src/Objects/DataManip/emData/src/X86MAC64/libemData.a b/src/Objects/DataManip/emData/src/X86MAC64/libemData.a index ca38e60eac..f84ebe9de0 100644 Binary files a/src/Objects/DataManip/emData/src/X86MAC64/libemData.a and b/src/Objects/DataManip/emData/src/X86MAC64/libemData.a differ diff --git a/src/Objects/DataManip/emData/src/X86MAC64/libemData.debug.a b/src/Objects/DataManip/emData/src/X86MAC64/libemData.debug.a index bdfb67bf06..cde923f2a8 100644 Binary files a/src/Objects/DataManip/emData/src/X86MAC64/libemData.debug.a and b/src/Objects/DataManip/emData/src/X86MAC64/libemData.debug.a differ diff --git a/src/Objects/DataManip/largeIP/src/X86MAC64/liblargeIP.a b/src/Objects/DataManip/largeIP/src/X86MAC64/liblargeIP.a index ccb0969c09..74d2d8e547 100644 Binary files a/src/Objects/DataManip/largeIP/src/X86MAC64/liblargeIP.a and b/src/Objects/DataManip/largeIP/src/X86MAC64/liblargeIP.a differ diff --git a/src/Objects/DataManip/largeIP/src/X86MAC64/liblargeIP.debug.a b/src/Objects/DataManip/largeIP/src/X86MAC64/liblargeIP.debug.a index c792391521..eca568069f 100644 Binary files a/src/Objects/DataManip/largeIP/src/X86MAC64/liblargeIP.debug.a and b/src/Objects/DataManip/largeIP/src/X86MAC64/liblargeIP.debug.a differ diff --git a/src/Objects/DataManip/llData/src/X86MAC64/libllData.a b/src/Objects/DataManip/llData/src/X86MAC64/libllData.a index fcf1bf8614..cf50d463b4 100644 Binary files a/src/Objects/DataManip/llData/src/X86MAC64/libllData.a and b/src/Objects/DataManip/llData/src/X86MAC64/libllData.a differ diff --git a/src/Objects/DataManip/llData/src/X86MAC64/libllData.debug.a b/src/Objects/DataManip/llData/src/X86MAC64/libllData.debug.a index 97fe465996..dc6abdb101 100644 Binary files a/src/Objects/DataManip/llData/src/X86MAC64/libllData.debug.a and b/src/Objects/DataManip/llData/src/X86MAC64/libllData.debug.a differ diff --git a/src/Objects/DataManip/ltlgData/src/X86MAC64/libltlgData.a b/src/Objects/DataManip/ltlgData/src/X86MAC64/libltlgData.a index db323f3af1..40156aad99 100644 Binary files a/src/Objects/DataManip/ltlgData/src/X86MAC64/libltlgData.a and b/src/Objects/DataManip/ltlgData/src/X86MAC64/libltlgData.a differ diff --git a/src/Objects/DataManip/ltlgData/src/X86MAC64/libltlgData.debug.a b/src/Objects/DataManip/ltlgData/src/X86MAC64/libltlgData.debug.a index ff2efa6675..dbce4e0b77 100644 Binary files a/src/Objects/DataManip/ltlgData/src/X86MAC64/libltlgData.debug.a and b/src/Objects/DataManip/ltlgData/src/X86MAC64/libltlgData.debug.a differ diff --git a/src/Objects/DataManip/mrcImage/src/X86MAC64/libmrcImage.a b/src/Objects/DataManip/mrcImage/src/X86MAC64/libmrcImage.a index 0dafd80222..d9619fe92f 100644 Binary files a/src/Objects/DataManip/mrcImage/src/X86MAC64/libmrcImage.a and b/src/Objects/DataManip/mrcImage/src/X86MAC64/libmrcImage.a differ diff --git a/src/Objects/DataManip/mrcImage/src/X86MAC64/libmrcImage.debug.a b/src/Objects/DataManip/mrcImage/src/X86MAC64/libmrcImage.debug.a index 479f7605af..812a717a1f 100644 Binary files a/src/Objects/DataManip/mrcImage/src/X86MAC64/libmrcImage.debug.a and b/src/Objects/DataManip/mrcImage/src/X86MAC64/libmrcImage.debug.a differ diff --git a/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageAddValueCuda.cu b/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageAddValueCuda.cu new file mode 120000 index 0000000000..1ea8bf47b8 --- /dev/null +++ b/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageAddValueCuda.cu @@ -0,0 +1 @@ +../lmrcImageAddValueCuda.cu \ No newline at end of file diff --git a/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageClusterAnalysis.cu b/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageClusterAnalysis.cu new file mode 120000 index 0000000000..7a0c013cf7 --- /dev/null +++ b/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageClusterAnalysis.cu @@ -0,0 +1 @@ +../lmrcImageClusterAnalysis.cu \ No newline at end of file diff --git a/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageDensity.sharedo b/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageDensity.sharedo index 4725bb9218..94e125c9af 100644 Binary files a/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageDensity.sharedo and b/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageDensity.sharedo differ diff --git a/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageFFT.sharedo b/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageFFT.sharedo deleted file mode 100644 index db0fd06dc8..0000000000 Binary files a/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageFFT.sharedo and /dev/null differ diff --git a/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageRhoFiltering.sharedo b/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageRhoFiltering.sharedo index 9f1f678520..002d3a8878 100644 Binary files a/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageRhoFiltering.sharedo and b/src/Objects/DataManip/mrcImage/src/X86MAC64/lmrcImageRhoFiltering.sharedo differ diff --git a/src/Objects/DataManip/pdbFile/src/X86MAC64/libpdbFile.a b/src/Objects/DataManip/pdbFile/src/X86MAC64/libpdbFile.a index 345b4dc9aa..24f6f2893b 100644 Binary files a/src/Objects/DataManip/pdbFile/src/X86MAC64/libpdbFile.a and b/src/Objects/DataManip/pdbFile/src/X86MAC64/libpdbFile.a differ diff --git a/src/Objects/DataManip/pdbFile/src/X86MAC64/libpdbFile.debug.a b/src/Objects/DataManip/pdbFile/src/X86MAC64/libpdbFile.debug.a index 7e54c75ca2..43e738f284 100644 Binary files a/src/Objects/DataManip/pdbFile/src/X86MAC64/libpdbFile.debug.a and b/src/Objects/DataManip/pdbFile/src/X86MAC64/libpdbFile.debug.a differ diff --git a/src/Objects/DataManip/pdbFile/src/X86MAC64/pdbTransCuda.cu b/src/Objects/DataManip/pdbFile/src/X86MAC64/pdbTransCuda.cu new file mode 120000 index 0000000000..a2f7509458 --- /dev/null +++ b/src/Objects/DataManip/pdbFile/src/X86MAC64/pdbTransCuda.cu @@ -0,0 +1 @@ +../pdbTransCuda.cu \ No newline at end of file diff --git a/src/Objects/DataManip/simulation/src/X86MAC64/libsimulation.a b/src/Objects/DataManip/simulation/src/X86MAC64/libsimulation.a index 4bcf07cae8..c35a0b180e 100644 Binary files a/src/Objects/DataManip/simulation/src/X86MAC64/libsimulation.a and b/src/Objects/DataManip/simulation/src/X86MAC64/libsimulation.a differ diff --git a/src/Objects/DataManip/simulation/src/X86MAC64/libsimulation.debug.a b/src/Objects/DataManip/simulation/src/X86MAC64/libsimulation.debug.a index efb2bf5556..f03dec02ec 100644 Binary files a/src/Objects/DataManip/simulation/src/X86MAC64/libsimulation.debug.a and b/src/Objects/DataManip/simulation/src/X86MAC64/libsimulation.debug.a differ diff --git a/src/Objects/DataManip/tgaFile/src/X86MAC64/libtgaFile.a b/src/Objects/DataManip/tgaFile/src/X86MAC64/libtgaFile.a index d90b0869f7..16077eb6db 100644 Binary files a/src/Objects/DataManip/tgaFile/src/X86MAC64/libtgaFile.a and b/src/Objects/DataManip/tgaFile/src/X86MAC64/libtgaFile.a differ diff --git a/src/Objects/DataManip/tgaFile/src/X86MAC64/libtgaFile.debug.a b/src/Objects/DataManip/tgaFile/src/X86MAC64/libtgaFile.debug.a index a2351cd467..e17a9a7aca 100644 Binary files a/src/Objects/DataManip/tgaFile/src/X86MAC64/libtgaFile.debug.a and b/src/Objects/DataManip/tgaFile/src/X86MAC64/libtgaFile.debug.a differ diff --git a/src/Objects/DataManip/transform/src/X86MAC64/libtransform.a b/src/Objects/DataManip/transform/src/X86MAC64/libtransform.a index d99e380569..bdf1d61129 100644 Binary files a/src/Objects/DataManip/transform/src/X86MAC64/libtransform.a and b/src/Objects/DataManip/transform/src/X86MAC64/libtransform.a differ diff --git a/src/Objects/DataManip/transform/src/X86MAC64/libtransform.debug.a b/src/Objects/DataManip/transform/src/X86MAC64/libtransform.debug.a index 5215e3de39..deaaee8cfc 100644 Binary files a/src/Objects/DataManip/transform/src/X86MAC64/libtransform.debug.a and b/src/Objects/DataManip/transform/src/X86MAC64/libtransform.debug.a differ diff --git a/src/Objects/DataManip/transform/src/X86MAC64/lmrc2Dto3D.sharedo b/src/Objects/DataManip/transform/src/X86MAC64/lmrc2Dto3D.sharedo index 3eb5a8be96..f394b9a266 100644 Binary files a/src/Objects/DataManip/transform/src/X86MAC64/lmrc2Dto3D.sharedo and b/src/Objects/DataManip/transform/src/X86MAC64/lmrc2Dto3D.sharedo differ diff --git a/src/Objects/General/AI/src/X86MAC64/libAI.a b/src/Objects/General/AI/src/X86MAC64/libAI.a index 500de116e7..c82faa0cb8 100644 Binary files a/src/Objects/General/AI/src/X86MAC64/libAI.a and b/src/Objects/General/AI/src/X86MAC64/libAI.a differ diff --git a/src/Objects/General/AI/src/X86MAC64/libAI.debug.a b/src/Objects/General/AI/src/X86MAC64/libAI.debug.a index e5e0e16544..83ba237d7e 100644 Binary files a/src/Objects/General/AI/src/X86MAC64/libAI.debug.a and b/src/Objects/General/AI/src/X86MAC64/libAI.debug.a differ diff --git a/src/Objects/General/Array/src/X86MAC64/libArray.a b/src/Objects/General/Array/src/X86MAC64/libArray.a index f761b47fb7..429dcef038 100644 Binary files a/src/Objects/General/Array/src/X86MAC64/libArray.a and b/src/Objects/General/Array/src/X86MAC64/libArray.a differ diff --git a/src/Objects/General/Array/src/X86MAC64/libArray.debug.a b/src/Objects/General/Array/src/X86MAC64/libArray.debug.a index e7c47c6828..31e101dc68 100644 Binary files a/src/Objects/General/Array/src/X86MAC64/libArray.debug.a and b/src/Objects/General/Array/src/X86MAC64/libArray.debug.a differ diff --git a/src/Objects/General/Cluster/src/X86MAC64/libCluster.a b/src/Objects/General/Cluster/src/X86MAC64/libCluster.a index bc19eecdd3..7c46c278ff 100644 Binary files a/src/Objects/General/Cluster/src/X86MAC64/libCluster.a and b/src/Objects/General/Cluster/src/X86MAC64/libCluster.a differ diff --git a/src/Objects/General/Cluster/src/X86MAC64/libCluster.debug.a b/src/Objects/General/Cluster/src/X86MAC64/libCluster.debug.a index 2691e22781..2d6afef6e3 100644 Binary files a/src/Objects/General/Cluster/src/X86MAC64/libCluster.debug.a and b/src/Objects/General/Cluster/src/X86MAC64/libCluster.debug.a differ diff --git a/src/Objects/General/Crystal/src/X86MAC64/libCrystal.a b/src/Objects/General/Crystal/src/X86MAC64/libCrystal.a index c28031644e..0c42136663 100644 Binary files a/src/Objects/General/Crystal/src/X86MAC64/libCrystal.a and b/src/Objects/General/Crystal/src/X86MAC64/libCrystal.a differ diff --git a/src/Objects/General/Crystal/src/X86MAC64/libCrystal.debug.a b/src/Objects/General/Crystal/src/X86MAC64/libCrystal.debug.a index a3da29ee19..f68a028887 100644 Binary files a/src/Objects/General/Crystal/src/X86MAC64/libCrystal.debug.a and b/src/Objects/General/Crystal/src/X86MAC64/libCrystal.debug.a differ diff --git a/src/Objects/General/File/src/X86MAC64/libFile.a b/src/Objects/General/File/src/X86MAC64/libFile.a index dd1df20e33..79e318cdbe 100644 Binary files a/src/Objects/General/File/src/X86MAC64/libFile.a and b/src/Objects/General/File/src/X86MAC64/libFile.a differ diff --git a/src/Objects/General/File/src/X86MAC64/libFile.debug.a b/src/Objects/General/File/src/X86MAC64/libFile.debug.a index 01ffa8a5ed..c034b77c4e 100644 Binary files a/src/Objects/General/File/src/X86MAC64/libFile.debug.a and b/src/Objects/General/File/src/X86MAC64/libFile.debug.a differ diff --git a/src/Objects/General/Map2D/src/X86MAC64/libMap2D.a b/src/Objects/General/Map2D/src/X86MAC64/libMap2D.a index a7f8c88056..ccdf2f3d6b 100644 Binary files a/src/Objects/General/Map2D/src/X86MAC64/libMap2D.a and b/src/Objects/General/Map2D/src/X86MAC64/libMap2D.a differ diff --git a/src/Objects/General/Map2D/src/X86MAC64/libMap2D.debug.a b/src/Objects/General/Map2D/src/X86MAC64/libMap2D.debug.a index 6e254007f0..f15e89bf86 100644 Binary files a/src/Objects/General/Map2D/src/X86MAC64/libMap2D.debug.a and b/src/Objects/General/Map2D/src/X86MAC64/libMap2D.debug.a differ diff --git a/src/Objects/General/Matrix3D/src/X86MAC64/libMatrix3D.a b/src/Objects/General/Matrix3D/src/X86MAC64/libMatrix3D.a index 460e760954..d7ad0a60b5 100644 Binary files a/src/Objects/General/Matrix3D/src/X86MAC64/libMatrix3D.a and b/src/Objects/General/Matrix3D/src/X86MAC64/libMatrix3D.a differ diff --git a/src/Objects/General/Matrix3D/src/X86MAC64/libMatrix3D.debug.a b/src/Objects/General/Matrix3D/src/X86MAC64/libMatrix3D.debug.a index cbd0d0d5be..56ef2258a1 100644 Binary files a/src/Objects/General/Matrix3D/src/X86MAC64/libMatrix3D.debug.a and b/src/Objects/General/Matrix3D/src/X86MAC64/libMatrix3D.debug.a differ diff --git a/src/Objects/General/Memory/src/X86MAC64/libMemory.a b/src/Objects/General/Memory/src/X86MAC64/libMemory.a index 4535b1c951..411558779a 100644 Binary files a/src/Objects/General/Memory/src/X86MAC64/libMemory.a and b/src/Objects/General/Memory/src/X86MAC64/libMemory.a differ diff --git a/src/Objects/General/Memory/src/X86MAC64/libMemory.debug.a b/src/Objects/General/Memory/src/X86MAC64/libMemory.debug.a index 6b7d4aad7d..7a9105aaea 100644 Binary files a/src/Objects/General/Memory/src/X86MAC64/libMemory.debug.a and b/src/Objects/General/Memory/src/X86MAC64/libMemory.debug.a differ diff --git a/src/Objects/General/Memory/src/X86MAC64/libMemory.so b/src/Objects/General/Memory/src/X86MAC64/libMemory.so index fa2d667677..b9ef7d8943 100755 Binary files a/src/Objects/General/Memory/src/X86MAC64/libMemory.so and b/src/Objects/General/Memory/src/X86MAC64/libMemory.so differ diff --git a/src/Objects/General/Memory/src/X86MAC64/memoryAllocate.sharedo b/src/Objects/General/Memory/src/X86MAC64/memoryAllocate.sharedo index 76e82241f1..00765718ca 100644 Binary files a/src/Objects/General/Memory/src/X86MAC64/memoryAllocate.sharedo and b/src/Objects/General/Memory/src/X86MAC64/memoryAllocate.sharedo differ diff --git a/src/Objects/General/Memory/src/X86MAC64/memoryByteSwap.sharedo b/src/Objects/General/Memory/src/X86MAC64/memoryByteSwap.sharedo index 3e2fd15b16..cf7a5245b7 100644 Binary files a/src/Objects/General/Memory/src/X86MAC64/memoryByteSwap.sharedo and b/src/Objects/General/Memory/src/X86MAC64/memoryByteSwap.sharedo differ diff --git a/src/Objects/General/PVM/src/X86MAC64/libPVM.a b/src/Objects/General/PVM/src/X86MAC64/libPVM.a index 49f24e4942..06fbce5378 100644 Binary files a/src/Objects/General/PVM/src/X86MAC64/libPVM.a and b/src/Objects/General/PVM/src/X86MAC64/libPVM.a differ diff --git a/src/Objects/General/PVM/src/X86MAC64/libPVM.debug.a b/src/Objects/General/PVM/src/X86MAC64/libPVM.debug.a index f7e97f6bb5..ea90ac89b2 100644 Binary files a/src/Objects/General/PVM/src/X86MAC64/libPVM.debug.a and b/src/Objects/General/PVM/src/X86MAC64/libPVM.debug.a differ diff --git a/src/Objects/General/Random/src/X86MAC64/libRandom.a b/src/Objects/General/Random/src/X86MAC64/libRandom.a index 3c177f962c..960abda1e6 100644 Binary files a/src/Objects/General/Random/src/X86MAC64/libRandom.a and b/src/Objects/General/Random/src/X86MAC64/libRandom.a differ diff --git a/src/Objects/General/Random/src/X86MAC64/libRandom.debug.a b/src/Objects/General/Random/src/X86MAC64/libRandom.debug.a index 71355cd5fa..f65ecdcc3d 100644 Binary files a/src/Objects/General/Random/src/X86MAC64/libRandom.debug.a and b/src/Objects/General/Random/src/X86MAC64/libRandom.debug.a differ diff --git a/src/Objects/General/Socket/src/X86MAC64/libSocket.a b/src/Objects/General/Socket/src/X86MAC64/libSocket.a index 2246791335..8a8746a351 100644 Binary files a/src/Objects/General/Socket/src/X86MAC64/libSocket.a and b/src/Objects/General/Socket/src/X86MAC64/libSocket.a differ diff --git a/src/Objects/General/Socket/src/X86MAC64/libSocket.debug.a b/src/Objects/General/Socket/src/X86MAC64/libSocket.debug.a index 4d56614c0c..d1caea6c04 100644 Binary files a/src/Objects/General/Socket/src/X86MAC64/libSocket.debug.a and b/src/Objects/General/Socket/src/X86MAC64/libSocket.debug.a differ diff --git a/src/Objects/General/SpecialNumber/src/X86MAC64/libSpecialNumber.a b/src/Objects/General/SpecialNumber/src/X86MAC64/libSpecialNumber.a index cbeca484e0..dc8e715557 100644 Binary files a/src/Objects/General/SpecialNumber/src/X86MAC64/libSpecialNumber.a and b/src/Objects/General/SpecialNumber/src/X86MAC64/libSpecialNumber.a differ diff --git a/src/Objects/General/SpecialNumber/src/X86MAC64/libSpecialNumber.debug.a b/src/Objects/General/SpecialNumber/src/X86MAC64/libSpecialNumber.debug.a index 5c61971980..bd95c39d2d 100644 Binary files a/src/Objects/General/SpecialNumber/src/X86MAC64/libSpecialNumber.debug.a and b/src/Objects/General/SpecialNumber/src/X86MAC64/libSpecialNumber.debug.a differ diff --git a/src/Objects/General/String/src/X86MAC64/libString.a b/src/Objects/General/String/src/X86MAC64/libString.a index 0239041379..6949616756 100644 Binary files a/src/Objects/General/String/src/X86MAC64/libString.a and b/src/Objects/General/String/src/X86MAC64/libString.a differ diff --git a/src/Objects/General/String/src/X86MAC64/libString.debug.a b/src/Objects/General/String/src/X86MAC64/libString.debug.a index 4c56daf00a..0488829547 100644 Binary files a/src/Objects/General/String/src/X86MAC64/libString.debug.a and b/src/Objects/General/String/src/X86MAC64/libString.debug.a differ diff --git a/src/Objects/General/Vector/src/X86MAC64/libVector.a b/src/Objects/General/Vector/src/X86MAC64/libVector.a index 1d8a1a104b..411b5fa643 100644 Binary files a/src/Objects/General/Vector/src/X86MAC64/libVector.a and b/src/Objects/General/Vector/src/X86MAC64/libVector.a differ diff --git a/src/Objects/General/Vector/src/X86MAC64/libVector.debug.a b/src/Objects/General/Vector/src/X86MAC64/libVector.debug.a index a6d22a2354..bc3a65074a 100644 Binary files a/src/Objects/General/Vector/src/X86MAC64/libVector.debug.a and b/src/Objects/General/Vector/src/X86MAC64/libVector.debug.a differ diff --git a/src/Objects/General/dummy/src/X86MAC64/libdummy.a b/src/Objects/General/dummy/src/X86MAC64/libdummy.a index cd21151d66..fa1d2cf01e 100644 Binary files a/src/Objects/General/dummy/src/X86MAC64/libdummy.a and b/src/Objects/General/dummy/src/X86MAC64/libdummy.a differ diff --git a/src/Objects/General/dummy/src/X86MAC64/libdummy.debug.a b/src/Objects/General/dummy/src/X86MAC64/libdummy.debug.a index 853824ba5d..772649b558 100644 Binary files a/src/Objects/General/dummy/src/X86MAC64/libdummy.debug.a and b/src/Objects/General/dummy/src/X86MAC64/libdummy.debug.a differ diff --git a/src/Objects/General/eosCuda/src/X86MAC64/libeosCuda.debug.a b/src/Objects/General/eosCuda/src/X86MAC64/libeosCuda.debug.a deleted file mode 100644 index 1ad8d16866..0000000000 Binary files a/src/Objects/General/eosCuda/src/X86MAC64/libeosCuda.debug.a and /dev/null differ diff --git a/src/Objects/General/eosCuda/src/X86MAC64/libeosCuda.so b/src/Objects/General/eosCuda/src/X86MAC64/libeosCuda.so deleted file mode 100755 index 96baafb851..0000000000 Binary files a/src/Objects/General/eosCuda/src/X86MAC64/libeosCuda.so and /dev/null differ diff --git a/src/Objects/General/eosFunc/src/X86MAC64/.Depend b/src/Objects/General/eosFunc/src/X86MAC64/.Depend new file mode 100644 index 0000000000..7b6c633a65 --- /dev/null +++ b/src/Objects/General/eosFunc/src/X86MAC64/.Depend @@ -0,0 +1 @@ +X86MAC64/eosFunc.o:eosFunc.o diff --git a/src/Objects/General/eosFunc/src/X86MAC64/.Source b/src/Objects/General/eosFunc/src/X86MAC64/.Source new file mode 100644 index 0000000000..01f875fed6 --- /dev/null +++ b/src/Objects/General/eosFunc/src/X86MAC64/.Source @@ -0,0 +1,28 @@ +SRC = \ +eosFunc.c \ + +OBJ = \ +eosFunc.o \ + +SHAREDOBJ = \ +eosFunc.sharedo \ + +REALOBJ = \ +X86MAC64/eosFunc.o \ + +REALSHAREDOBJ = \ +X86MAC64/eosFunc.sharedo \ + +OBJDEBUG = \ +eosFunc.debugo \ + +REALOBJDEBUG = \ +X86MAC64/eosFunc.debugo \ + +OBJCUDAGDB = \ +eosFunc.cudagdb.o \ + +REALOBJCUDAGDB = \ +X86MAC64/eosFunc.cudagdb.o \ + + diff --git a/src/Objects/General/eosFunc/src/X86MAC64/Makefile b/src/Objects/General/eosFunc/src/X86MAC64/Makefile new file mode 100755 index 0000000000..a4295539e5 --- /dev/null +++ b/src/Objects/General/eosFunc/src/X86MAC64/Makefile @@ -0,0 +1,36 @@ +SHELL=/bin/ksh +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/$(OBJECTNAME)/Config/Define.inc +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/Config/Define.inc +include $(EOS_HOME)/src/$(WORLDNAME)/Config/Define.inc +include $(EOS_HOME)/src/Config/DefineObject.inc + +include .Source +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/$(OBJECTNAME)/src/.CHeader +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/$(OBJECTNAME)/src/.CCHeader +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/$(OBJECTNAME)/src/.Wish + +LIBNAME=lib$(OBJECTNAME).a +SHAREDLIB=lib$(OBJECTNAME).so +LIBNAMEDEBUG=lib$(OBJECTNAME).debug.a +LIBNAMECUDAGDB=lib$(OBJECTNAME).cudagdb.a + +$(LIBNAME): $(OBJ) + @echo LIBNAME:$(LIBNAME) + $(AR) rs $(LIBNAME) $(OBJ) + +$(SHAREDLIB): $(SHAREDOBJ) + @COMPILEDOBJ=`ls $(SHAREDOBJ)` ; echo "#### Compiled Objects"; echo $${COMPILEDOBJ}; echo "################"; \ + $(SHARED) $(SHAREDLIB) $${COMPILEDOBJ} + +debug: $(LIBNAMEDEBUG) $(LIBNAMECUDAGDB) + +$(LIBNAMEDEBUG): $(OBJDEBUG) + @echo LIBNAME:$(LIBNAMEDEBUG) + $(AR) rs $(LIBNAMEDEBUG) $(OBJDEBUG) + +$(LIBNAMECUDAGDB): $(OBJCUDAGDB) + @echo LIBNAME:$(LIBNAMECUDAGDB) + $(AR) rs $(LIBNAMECUDAGDB) $(OBJCUDAGDB) + +include .Depend + diff --git a/src/Objects/General/eosFunc/src/X86MAC64/X86MAC64 b/src/Objects/General/eosFunc/src/X86MAC64/X86MAC64 new file mode 120000 index 0000000000..c0a8a9858e --- /dev/null +++ b/src/Objects/General/eosFunc/src/X86MAC64/X86MAC64 @@ -0,0 +1 @@ +../../../../../hostdepend/X86MAC64/src/Objects/General/eosFunc/src/X86MAC64 \ No newline at end of file diff --git a/src/Objects/General/eosFunc/src/X86MAC64/eosFunc.sharedo b/src/Objects/General/eosFunc/src/X86MAC64/eosFunc.sharedo new file mode 100644 index 0000000000..0278a4dde4 Binary files /dev/null and b/src/Objects/General/eosFunc/src/X86MAC64/eosFunc.sharedo differ diff --git a/src/Objects/General/eosFunc/src/X86MAC64/libeosFunc.a b/src/Objects/General/eosFunc/src/X86MAC64/libeosFunc.a new file mode 100644 index 0000000000..a58c6e9ffd Binary files /dev/null and b/src/Objects/General/eosFunc/src/X86MAC64/libeosFunc.a differ diff --git a/src/Objects/General/eosFunc/src/X86MAC64/libeosFunc.debug.a b/src/Objects/General/eosFunc/src/X86MAC64/libeosFunc.debug.a new file mode 100644 index 0000000000..08702f0171 Binary files /dev/null and b/src/Objects/General/eosFunc/src/X86MAC64/libeosFunc.debug.a differ diff --git a/src/Objects/General/eosFunc/src/X86MAC64/libeosFunc.so b/src/Objects/General/eosFunc/src/X86MAC64/libeosFunc.so new file mode 100755 index 0000000000..3b0c12c391 Binary files /dev/null and b/src/Objects/General/eosFunc/src/X86MAC64/libeosFunc.so differ diff --git a/src/Objects/General/eosPThread/src/X86MAC64/libeosPThread.a b/src/Objects/General/eosPThread/src/X86MAC64/libeosPThread.a index ab02a2efdc..b7450f6110 100644 Binary files a/src/Objects/General/eosPThread/src/X86MAC64/libeosPThread.a and b/src/Objects/General/eosPThread/src/X86MAC64/libeosPThread.a differ diff --git a/src/Objects/General/eosPThread/src/X86MAC64/libeosPThread.debug.a b/src/Objects/General/eosPThread/src/X86MAC64/libeosPThread.debug.a index 1457054e5c..c4aff89366 100644 Binary files a/src/Objects/General/eosPThread/src/X86MAC64/libeosPThread.debug.a and b/src/Objects/General/eosPThread/src/X86MAC64/libeosPThread.debug.a differ diff --git a/src/Objects/General/eosPoint/src/X86MAC64/.Depend b/src/Objects/General/eosPoint/src/X86MAC64/.Depend index dae6e2dae8..0bd98bf219 100644 --- a/src/Objects/General/eosPoint/src/X86MAC64/.Depend +++ b/src/Objects/General/eosPoint/src/X86MAC64/.Depend @@ -1 +1,5 @@ +X86MAC64/eosPointCopy.o:eosPointCopy.o X86MAC64/eosPointRead.o:eosPointRead.o +X86MAC64/eosPointRotate.o:eosPointRotate.o +X86MAC64/eosPointUtil.o:eosPointUtil.o +X86MAC64/eosPointWrite.o:eosPointWrite.o diff --git a/src/Objects/General/eosPoint/src/X86MAC64/.Source b/src/Objects/General/eosPoint/src/X86MAC64/.Source index 35722eb474..5a7efe11b9 100644 --- a/src/Objects/General/eosPoint/src/X86MAC64/.Source +++ b/src/Objects/General/eosPoint/src/X86MAC64/.Source @@ -1,28 +1,64 @@ SRC = \ +eosPointCopy.c \ eosPointRead.c \ +eosPointRotate.c \ +eosPointUtil.c \ +eosPointWrite.c \ OBJ = \ +eosPointCopy.o \ eosPointRead.o \ +eosPointRotate.o \ +eosPointUtil.o \ +eosPointWrite.o \ SHAREDOBJ = \ +eosPointCopy.sharedo \ eosPointRead.sharedo \ +eosPointRotate.sharedo \ +eosPointUtil.sharedo \ +eosPointWrite.sharedo \ REALOBJ = \ +X86MAC64/eosPointCopy.o \ X86MAC64/eosPointRead.o \ +X86MAC64/eosPointRotate.o \ +X86MAC64/eosPointUtil.o \ +X86MAC64/eosPointWrite.o \ REALSHAREDOBJ = \ +X86MAC64/eosPointCopy.sharedo \ X86MAC64/eosPointRead.sharedo \ +X86MAC64/eosPointRotate.sharedo \ +X86MAC64/eosPointUtil.sharedo \ +X86MAC64/eosPointWrite.sharedo \ OBJDEBUG = \ +eosPointCopy.debugo \ eosPointRead.debugo \ +eosPointRotate.debugo \ +eosPointUtil.debugo \ +eosPointWrite.debugo \ REALOBJDEBUG = \ +X86MAC64/eosPointCopy.debugo \ X86MAC64/eosPointRead.debugo \ +X86MAC64/eosPointRotate.debugo \ +X86MAC64/eosPointUtil.debugo \ +X86MAC64/eosPointWrite.debugo \ OBJCUDAGDB = \ +eosPointCopy.cudagdb.o \ eosPointRead.cudagdb.o \ +eosPointRotate.cudagdb.o \ +eosPointUtil.cudagdb.o \ +eosPointWrite.cudagdb.o \ REALOBJCUDAGDB = \ +X86MAC64/eosPointCopy.cudagdb.o \ X86MAC64/eosPointRead.cudagdb.o \ +X86MAC64/eosPointRotate.cudagdb.o \ +X86MAC64/eosPointUtil.cudagdb.o \ +X86MAC64/eosPointWrite.cudagdb.o \ diff --git a/src/Objects/General/eosPoint/src/X86MAC64/eosPointCopy.sharedo b/src/Objects/General/eosPoint/src/X86MAC64/eosPointCopy.sharedo new file mode 100644 index 0000000000..8fb7a2b4a1 Binary files /dev/null and b/src/Objects/General/eosPoint/src/X86MAC64/eosPointCopy.sharedo differ diff --git a/src/Objects/General/eosPoint/src/X86MAC64/eosPointRead.sharedo b/src/Objects/General/eosPoint/src/X86MAC64/eosPointRead.sharedo index 9f43ce2d80..20945a1b3e 100644 Binary files a/src/Objects/General/eosPoint/src/X86MAC64/eosPointRead.sharedo and b/src/Objects/General/eosPoint/src/X86MAC64/eosPointRead.sharedo differ diff --git a/src/Objects/General/eosPoint/src/X86MAC64/eosPointRotate.c b/src/Objects/General/eosPoint/src/X86MAC64/eosPointRotate.c new file mode 120000 index 0000000000..1a232e2c55 --- /dev/null +++ b/src/Objects/General/eosPoint/src/X86MAC64/eosPointRotate.c @@ -0,0 +1 @@ +../eosPointRotate.c \ No newline at end of file diff --git a/src/Objects/General/eosPoint/src/X86MAC64/eosPointRotate.sharedo b/src/Objects/General/eosPoint/src/X86MAC64/eosPointRotate.sharedo new file mode 100644 index 0000000000..3f815af0fe Binary files /dev/null and b/src/Objects/General/eosPoint/src/X86MAC64/eosPointRotate.sharedo differ diff --git a/src/Objects/General/eosPoint/src/X86MAC64/eosPointUtil.c b/src/Objects/General/eosPoint/src/X86MAC64/eosPointUtil.c new file mode 120000 index 0000000000..5a8f8c67af --- /dev/null +++ b/src/Objects/General/eosPoint/src/X86MAC64/eosPointUtil.c @@ -0,0 +1 @@ +../eosPointUtil.c \ No newline at end of file diff --git a/src/Objects/General/eosPoint/src/X86MAC64/eosPointUtil.sharedo b/src/Objects/General/eosPoint/src/X86MAC64/eosPointUtil.sharedo new file mode 100644 index 0000000000..134222636f Binary files /dev/null and b/src/Objects/General/eosPoint/src/X86MAC64/eosPointUtil.sharedo differ diff --git a/src/Objects/General/eosPoint/src/X86MAC64/eosPointWrite.c b/src/Objects/General/eosPoint/src/X86MAC64/eosPointWrite.c new file mode 120000 index 0000000000..88d2ef967f --- /dev/null +++ b/src/Objects/General/eosPoint/src/X86MAC64/eosPointWrite.c @@ -0,0 +1 @@ +../eosPointWrite.c \ No newline at end of file diff --git a/src/Objects/General/eosPoint/src/X86MAC64/eosPointWrite.sharedo b/src/Objects/General/eosPoint/src/X86MAC64/eosPointWrite.sharedo new file mode 100644 index 0000000000..020defa74d Binary files /dev/null and b/src/Objects/General/eosPoint/src/X86MAC64/eosPointWrite.sharedo differ diff --git a/src/Objects/General/eosPoint/src/X86MAC64/libeosPoint.a b/src/Objects/General/eosPoint/src/X86MAC64/libeosPoint.a index 34f9e72f89..8b0e13475f 100644 Binary files a/src/Objects/General/eosPoint/src/X86MAC64/libeosPoint.a and b/src/Objects/General/eosPoint/src/X86MAC64/libeosPoint.a differ diff --git a/src/Objects/General/eosPoint/src/X86MAC64/libeosPoint.debug.a b/src/Objects/General/eosPoint/src/X86MAC64/libeosPoint.debug.a index 0b06dce0b8..977c0ae7af 100644 Binary files a/src/Objects/General/eosPoint/src/X86MAC64/libeosPoint.debug.a and b/src/Objects/General/eosPoint/src/X86MAC64/libeosPoint.debug.a differ diff --git a/src/Objects/MachineManip/hf2000/src/X86MAC64/libhf2000.a b/src/Objects/MachineManip/hf2000/src/X86MAC64/libhf2000.a index 51d2fcdcaa..1b4d46630b 100644 Binary files a/src/Objects/MachineManip/hf2000/src/X86MAC64/libhf2000.a and b/src/Objects/MachineManip/hf2000/src/X86MAC64/libhf2000.a differ diff --git a/src/Objects/MachineManip/hf2000/src/X86MAC64/libhf2000.debug.a b/src/Objects/MachineManip/hf2000/src/X86MAC64/libhf2000.debug.a index 5aeca37fca..148f75848f 100644 Binary files a/src/Objects/MachineManip/hf2000/src/X86MAC64/libhf2000.debug.a and b/src/Objects/MachineManip/hf2000/src/X86MAC64/libhf2000.debug.a differ diff --git a/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/.Depend b/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/.Depend new file mode 100644 index 0000000000..71c343a8ba --- /dev/null +++ b/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/.Depend @@ -0,0 +1,200 @@ +argCheck.o: argCheck.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + /Users/tacyas/Eos/include/string.h /usr/include/math.h ../inc/config.h \ + ../inc/../inc/eosPointRotation.h /Users/tacyas/Eos/include/genUtil.h \ + /Users/tacyas/Eos/include/File.h /Users/tacyas/Eos/include/Memory.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/limits.h \ + /usr/include/limits.h /usr/include/machine/limits.h \ + /usr/include/i386/limits.h /usr/include/i386/_limits.h \ + /usr/include/sys/syslimits.h +eosPointRotation.o: eosPointRotation.c /usr/include/stdio.h \ + /usr/include/sys/cdefs.h /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + /Users/tacyas/Eos/include/string.h /usr/include/math.h ../inc/config.h \ + ../inc/../inc/eosPointRotation.h /Users/tacyas/Eos/include/genUtil.h \ + /Users/tacyas/Eos/include/Matrix3D.h \ + /Users/tacyas/Eos/include/Vector.h /Users/tacyas/Eos/include/Array.h \ + /Users/tacyas/Eos/include/Memory.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/limits.h \ + /usr/include/limits.h /usr/include/machine/limits.h \ + /usr/include/i386/limits.h /usr/include/i386/_limits.h \ + /usr/include/sys/syslimits.h /Users/tacyas/Eos/include/eosPoint.h +init.o: init.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + /Users/tacyas/Eos/include/string.h /usr/include/math.h ../inc/config.h \ + ../inc/../inc/eosPointRotation.h /Users/tacyas/Eos/include/genUtil.h \ + /Users/tacyas/Eos/include/File.h /Users/tacyas/Eos/include/Memory.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/limits.h \ + /usr/include/limits.h /usr/include/machine/limits.h \ + /usr/include/i386/limits.h /usr/include/i386/_limits.h \ + /usr/include/sys/syslimits.h +usage.o: usage.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + ../inc/config.h ../inc/../inc/eosPointRotation.h +util.o: util.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + ../inc/config.h ../inc/../inc/eosPointRotation.h diff --git a/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/Makefile b/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/Makefile new file mode 100755 index 0000000000..ec6124702f --- /dev/null +++ b/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/Makefile @@ -0,0 +1,114 @@ +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/$(OBJECTNAME)/Config/Define.inc +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/Config/Define.inc +include $(EOS_HOME)/src/$(WORLDNAME)/Config/Define.inc +include $(EOS_HOME)/src/Config/DefineTool.inc + +LIBFILES = \ + $(LIBPREFIX)EosObjects$(LIBSUFFIX) + +LIBFILESDEBUG = \ + $(LIBPREFIX)EosObjects.debug$(LIBSUFFIX) + +SRCC = \ + $(OBJECTNAME).c \ + init.c \ + argCheck.c \ + usage.c \ + util.c + +SRCCXX = \ + $(OBJECTNAME).cc \ + init.cc \ + argCheck.cc \ + usage.cc \ + util.cc + +MODULES = \ + $(OBJECTNAME).o \ + init.o \ + argCheck.o \ + usage.o \ + util.o + +REALMODULES = \ + $(OSTYPE)/$(OBJECTNAME).o \ + $(OSTYPE)/init.o \ + $(OSTYPE)/argCheck.o \ + $(OSTYPE)/usage.o \ + $(OSTYPE)/util.o + +MODULESDEBUG = \ + $(OBJECTNAME).debugo \ + init.debugo \ + argCheck.debugo \ + usage.debugo \ + util.debugo + +MODULESCUDAGDB = \ + $(OBJECTNAME).cudagdb.o \ + init.cudagdb.o \ + argCheck.cudagdb.o \ + usage.cudagdb.o \ + util.cudagdb.o + +REALMODULESDEBUG = \ + $(OSTYPE)/$(OBJECTNAME).debugo \ + $(OSTYPE)/init.debugo \ + $(OSTYPE)/argCheck.debugo \ + $(OSTYPE)/usage.debugo \ + $(OSTYPE)/util.debugo + + +$(OBJECTNAME): $(MODULES) $(LIBFILES) + @if [ -f $(VPATH)/$(OBJECTNAME).c ] ; \ + then \ + echo $(CC) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(CC) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).cc ] ; \ + then \ + echo $(CXX) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(CXX) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).ccm ] ; \ + then \ + echo "MICO"; \ + echo $(MICOLD) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(MICOLD) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).cu ] ; \ + then \ + echo $(NVCC) $(NVCCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) $(CUDALIB) $(CUDAINC) -o $@ ; \ + $(NVCC) $(NVCCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) $(CUDALIB) $(CUDAINC) -o $@ ; \ + fi + + +$(OBJECTNAME).debug: $(MODULESDEBUG) $(LIBFILESDEBUG) + @if [ -f $(VPATH)/$(OBJECTNAME).c ] ; \ + then \ + echo $(CC) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(CC) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).cc ] ; \ + then \ + echo $(CXX) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(CXX) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).ccm ] ; \ + then \ + echo "MICO"; \ + echo $(MICOLD) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(MICOLD) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).cu ] ; \ + then \ + echo $(CC) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(CC) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + +$(OBJECTNAME).cudagdb: $(MODULESCUDAGDB) $(LIBFILESDEBUG) + echo $(NVCC) "$(NVCCOPTSCUDAGDB) $(MODULESCUDAGDB) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@" + $(NVCC) $(NVCCOPTSCUDAGDB) $(MODULESCUDAGDB) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ + +include ./.Depend +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/$(OBJECTNAME)/Config/Target.inc diff --git a/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/X86MAC64 b/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/X86MAC64 new file mode 120000 index 0000000000..cafa115fc7 --- /dev/null +++ b/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/X86MAC64 @@ -0,0 +1 @@ +../../../../../hostdepend/X86MAC64/src/Tools/eosPoint/eosPointRotation/src/X86MAC64 \ No newline at end of file diff --git a/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/eosPointRotation b/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/eosPointRotation new file mode 100755 index 0000000000..a95af816cd Binary files /dev/null and b/src/Tools/eosPoint/eosPointRotation/src/X86MAC64/eosPointRotation differ diff --git a/src/Tools/mrcImage/mrcImageAddValue/src/X86MAC64/mrcImageAddValue b/src/Tools/mrcImage/mrcImageAddValue/src/X86MAC64/mrcImageAddValue deleted file mode 100755 index 6c3f333cf8..0000000000 Binary files a/src/Tools/mrcImage/mrcImageAddValue/src/X86MAC64/mrcImageAddValue and /dev/null differ diff --git a/src/Tools/mrcImage/mrcImageFFT/src/X86MAC64/mrcImageFFT b/src/Tools/mrcImage/mrcImageFFT/src/X86MAC64/mrcImageFFT deleted file mode 100755 index 87de9f4d7c..0000000000 Binary files a/src/Tools/mrcImage/mrcImageFFT/src/X86MAC64/mrcImageFFT and /dev/null differ diff --git a/src/Tools/pdbUtil/pdb2mrc2d/src/X86MAC64/pdb2mrc2d b/src/Tools/pdbUtil/pdb2mrc2d/src/X86MAC64/pdb2mrc2d deleted file mode 100755 index 937ba2cafb..0000000000 Binary files a/src/Tools/pdbUtil/pdb2mrc2d/src/X86MAC64/pdb2mrc2d and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbChargeFit/src/X86MAC64/pdbChargeFit b/src/Tools/pdbUtil/pdbChargeFit/src/X86MAC64/pdbChargeFit deleted file mode 100755 index fb58611171..0000000000 Binary files a/src/Tools/pdbUtil/pdbChargeFit/src/X86MAC64/pdbChargeFit and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbCrystalCreate/src/X86MAC64/pdbCrystalCreate b/src/Tools/pdbUtil/pdbCrystalCreate/src/X86MAC64/pdbCrystalCreate deleted file mode 100755 index 67364a7bd8..0000000000 Binary files a/src/Tools/pdbUtil/pdbCrystalCreate/src/X86MAC64/pdbCrystalCreate and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbHelix/src/X86MAC64/pdbHelix b/src/Tools/pdbUtil/pdbHelix/src/X86MAC64/pdbHelix deleted file mode 100755 index cb81221d50..0000000000 Binary files a/src/Tools/pdbUtil/pdbHelix/src/X86MAC64/pdbHelix and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbMove/src/X86MAC64/pdbMove b/src/Tools/pdbUtil/pdbMove/src/X86MAC64/pdbMove deleted file mode 100755 index d51a795fff..0000000000 Binary files a/src/Tools/pdbUtil/pdbMove/src/X86MAC64/pdbMove and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbPCA/src/X86MAC64/pdbPCA b/src/Tools/pdbUtil/pdbPCA/src/X86MAC64/pdbPCA deleted file mode 100755 index 258503936a..0000000000 Binary files a/src/Tools/pdbUtil/pdbPCA/src/X86MAC64/pdbPCA and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbRhoFit/src/X86MAC64/pdbRhoFit b/src/Tools/pdbUtil/pdbRhoFit/src/X86MAC64/pdbRhoFit deleted file mode 100755 index 2dc7173be0..0000000000 Binary files a/src/Tools/pdbUtil/pdbRhoFit/src/X86MAC64/pdbRhoFit and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbRhoFitTm/src/X86MAC64/pdbRhoFitTm b/src/Tools/pdbUtil/pdbRhoFitTm/src/X86MAC64/pdbRhoFitTm deleted file mode 100755 index c490889a93..0000000000 Binary files a/src/Tools/pdbUtil/pdbRhoFitTm/src/X86MAC64/pdbRhoFitTm and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbRotation/src/X86MAC64/pdbRotation b/src/Tools/pdbUtil/pdbRotation/src/X86MAC64/pdbRotation deleted file mode 100755 index 9f34ae5352..0000000000 Binary files a/src/Tools/pdbUtil/pdbRotation/src/X86MAC64/pdbRotation and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbShapeFit/src/X86MAC64/pdbShapeFit b/src/Tools/pdbUtil/pdbShapeFit/src/X86MAC64/pdbShapeFit deleted file mode 100755 index 257f5476a3..0000000000 Binary files a/src/Tools/pdbUtil/pdbShapeFit/src/X86MAC64/pdbShapeFit and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbTrans/src/X86MAC64/pdbTrans b/src/Tools/pdbUtil/pdbTrans/src/X86MAC64/pdbTrans deleted file mode 100755 index 4b2ded950d..0000000000 Binary files a/src/Tools/pdbUtil/pdbTrans/src/X86MAC64/pdbTrans and /dev/null differ diff --git a/src/Tools/pdbUtil/pdbTwoProteinFit/src/X86MAC64/pdbTwoProteinFit b/src/Tools/pdbUtil/pdbTwoProteinFit/src/X86MAC64/pdbTwoProteinFit deleted file mode 100755 index 745395fc94..0000000000 Binary files a/src/Tools/pdbUtil/pdbTwoProteinFit/src/X86MAC64/pdbTwoProteinFit and /dev/null differ diff --git a/src/Tools/rec3d/CheckCommonLineData/src/X86MAC64/CheckCommonLineData b/src/Tools/rec3d/CheckCommonLineData/src/X86MAC64/CheckCommonLineData index 8adf732e8f..c6a823d2e2 100755 Binary files a/src/Tools/rec3d/CheckCommonLineData/src/X86MAC64/CheckCommonLineData and b/src/Tools/rec3d/CheckCommonLineData/src/X86MAC64/CheckCommonLineData differ diff --git a/src/Tools/rec3d/CheckOfOrientation/src/X86MAC64/CheckOfOrientation b/src/Tools/rec3d/CheckOfOrientation/src/X86MAC64/CheckOfOrientation index c01913812c..c50c62fce1 100755 Binary files a/src/Tools/rec3d/CheckOfOrientation/src/X86MAC64/CheckOfOrientation and b/src/Tools/rec3d/CheckOfOrientation/src/X86MAC64/CheckOfOrientation differ diff --git a/src/Tools/rec3d/CommonLineCalculation/src/X86MAC64/CommonLineCalculation b/src/Tools/rec3d/CommonLineCalculation/src/X86MAC64/CommonLineCalculation index 4ebac7250b..f2ab0bd015 100755 Binary files a/src/Tools/rec3d/CommonLineCalculation/src/X86MAC64/CommonLineCalculation and b/src/Tools/rec3d/CommonLineCalculation/src/X86MAC64/CommonLineCalculation differ diff --git a/src/Tools/rec3d/EvaluateCorrelationMapwithCommonLine/src/X86MAC64/EvaluateCorrelationMapwithCommonLine b/src/Tools/rec3d/EvaluateCorrelationMapwithCommonLine/src/X86MAC64/EvaluateCorrelationMapwithCommonLine index e73380b19b..b53de0a100 100755 Binary files a/src/Tools/rec3d/EvaluateCorrelationMapwithCommonLine/src/X86MAC64/EvaluateCorrelationMapwithCommonLine and b/src/Tools/rec3d/EvaluateCorrelationMapwithCommonLine/src/X86MAC64/EvaluateCorrelationMapwithCommonLine differ diff --git a/src/Tools/rec3d/FETOrientationSearchByAnnealing/src/X86MAC64/FETOrientationSearchByAnnealing b/src/Tools/rec3d/FETOrientationSearchByAnnealing/src/X86MAC64/FETOrientationSearchByAnnealing index 833be5356e..3420af775e 100755 Binary files a/src/Tools/rec3d/FETOrientationSearchByAnnealing/src/X86MAC64/FETOrientationSearchByAnnealing and b/src/Tools/rec3d/FETOrientationSearchByAnnealing/src/X86MAC64/FETOrientationSearchByAnnealing differ diff --git a/src/Tools/rec3d/FETOrientationSearchByFeatureAlignment/src/X86MAC64/FETOrientationSearchByFeatureAlignment b/src/Tools/rec3d/FETOrientationSearchByFeatureAlignment/src/X86MAC64/FETOrientationSearchByFeatureAlignment index 2effe3d1f7..7f0d9758b1 100755 Binary files a/src/Tools/rec3d/FETOrientationSearchByFeatureAlignment/src/X86MAC64/FETOrientationSearchByFeatureAlignment and b/src/Tools/rec3d/FETOrientationSearchByFeatureAlignment/src/X86MAC64/FETOrientationSearchByFeatureAlignment differ diff --git a/src/Tools/rec3d/FETmapOrientationSearchBySimultaneousFitting/src/X86MAC64/FETmapOrientationSearchBySimultaneousFitting b/src/Tools/rec3d/FETmapOrientationSearchBySimultaneousFitting/src/X86MAC64/FETmapOrientationSearchBySimultaneousFitting index cd82ca0040..a8a915e442 100755 Binary files a/src/Tools/rec3d/FETmapOrientationSearchBySimultaneousFitting/src/X86MAC64/FETmapOrientationSearchBySimultaneousFitting and b/src/Tools/rec3d/FETmapOrientationSearchBySimultaneousFitting/src/X86MAC64/FETmapOrientationSearchBySimultaneousFitting differ diff --git a/src/Tools/rec3d/FETsmallMapSetCreate_forSimultaneousMinimization/src/X86MAC64/FETsmallMapSetCreate_forSimultaneousMinimization b/src/Tools/rec3d/FETsmallMapSetCreate_forSimultaneousMinimization/src/X86MAC64/FETsmallMapSetCreate_forSimultaneousMinimization index 632e9e17f8..b0de90485c 100755 Binary files a/src/Tools/rec3d/FETsmallMapSetCreate_forSimultaneousMinimization/src/X86MAC64/FETsmallMapSetCreate_forSimultaneousMinimization and b/src/Tools/rec3d/FETsmallMapSetCreate_forSimultaneousMinimization/src/X86MAC64/FETsmallMapSetCreate_forSimultaneousMinimization differ diff --git a/src/Tools/rec3d/LCalculationForOrientationSearch/src/X86MAC64/LCalculationForOrientationSearch b/src/Tools/rec3d/LCalculationForOrientationSearch/src/X86MAC64/LCalculationForOrientationSearch index c8e19c64d9..84932438c8 100755 Binary files a/src/Tools/rec3d/LCalculationForOrientationSearch/src/X86MAC64/LCalculationForOrientationSearch and b/src/Tools/rec3d/LCalculationForOrientationSearch/src/X86MAC64/LCalculationForOrientationSearch differ diff --git a/src/Tools/rec3d/ProjectionDirectionMapCreate/src/X86MAC64/ProjectionDirectionMapCreate b/src/Tools/rec3d/ProjectionDirectionMapCreate/src/X86MAC64/ProjectionDirectionMapCreate index d399bd92b9..ce0ad4e0b1 100755 Binary files a/src/Tools/rec3d/ProjectionDirectionMapCreate/src/X86MAC64/ProjectionDirectionMapCreate and b/src/Tools/rec3d/ProjectionDirectionMapCreate/src/X86MAC64/ProjectionDirectionMapCreate differ diff --git a/src/Tools/rec3d/WeightCalculationOfCommonLineSearch/src/X86MAC64/WeightCalculationOfCommonLineSearch b/src/Tools/rec3d/WeightCalculationOfCommonLineSearch/src/X86MAC64/WeightCalculationOfCommonLineSearch index 71b344ed0a..eff928cf0a 100755 Binary files a/src/Tools/rec3d/WeightCalculationOfCommonLineSearch/src/X86MAC64/WeightCalculationOfCommonLineSearch and b/src/Tools/rec3d/WeightCalculationOfCommonLineSearch/src/X86MAC64/WeightCalculationOfCommonLineSearch differ diff --git a/src/Tools/rec3d/WeightCalculationOfCommonLineSearchByAllSinogram/src/X86MAC64/WeightCalculationOfCommonLineSearchByAllSinogram b/src/Tools/rec3d/WeightCalculationOfCommonLineSearchByAllSinogram/src/X86MAC64/WeightCalculationOfCommonLineSearchByAllSinogram index f038da7859..564681c166 100755 Binary files a/src/Tools/rec3d/WeightCalculationOfCommonLineSearchByAllSinogram/src/X86MAC64/WeightCalculationOfCommonLineSearchByAllSinogram and b/src/Tools/rec3d/WeightCalculationOfCommonLineSearchByAllSinogram/src/X86MAC64/WeightCalculationOfCommonLineSearchByAllSinogram differ diff --git a/src/Tools/rec3d/ll2ltlg/src/X86MAC64/ll2ltlg b/src/Tools/rec3d/ll2ltlg/src/X86MAC64/ll2ltlg index c2d25ebcc7..a8de3aa315 100755 Binary files a/src/Tools/rec3d/ll2ltlg/src/X86MAC64/ll2ltlg and b/src/Tools/rec3d/ll2ltlg/src/X86MAC64/ll2ltlg differ diff --git a/src/Tools/rec3d/llExtract/src/X86MAC64/llExtract b/src/Tools/rec3d/llExtract/src/X86MAC64/llExtract index 1ac928c7cb..790dc4088e 100755 Binary files a/src/Tools/rec3d/llExtract/src/X86MAC64/llExtract and b/src/Tools/rec3d/llExtract/src/X86MAC64/llExtract differ diff --git a/src/Tools/rec3d/llExtractCtfinfFileCreate/src/X86MAC64/llExtractCtfinfFileCreate b/src/Tools/rec3d/llExtractCtfinfFileCreate/src/X86MAC64/llExtractCtfinfFileCreate index 35c97668f4..a8ebd0721c 100755 Binary files a/src/Tools/rec3d/llExtractCtfinfFileCreate/src/X86MAC64/llExtractCtfinfFileCreate and b/src/Tools/rec3d/llExtractCtfinfFileCreate/src/X86MAC64/llExtractCtfinfFileCreate differ diff --git a/src/Tools/rec3d/llExtractCtrlFileCreate/src/X86MAC64/llExtractCtrlFileCreate b/src/Tools/rec3d/llExtractCtrlFileCreate/src/X86MAC64/llExtractCtrlFileCreate index ceb6daa2e2..c7c178fb00 100755 Binary files a/src/Tools/rec3d/llExtractCtrlFileCreate/src/X86MAC64/llExtractCtrlFileCreate and b/src/Tools/rec3d/llExtractCtrlFileCreate/src/X86MAC64/llExtractCtrlFileCreate differ diff --git a/src/Tools/rec3d/maker2Dto3DEstimator/src/X86MAC64/.Depend b/src/Tools/rec3d/maker2Dto3DEstimator/src/X86MAC64/.Depend new file mode 100644 index 0000000000..e790c21f75 --- /dev/null +++ b/src/Tools/rec3d/maker2Dto3DEstimator/src/X86MAC64/.Depend @@ -0,0 +1,158 @@ +argCheck.o: argCheck.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + /Users/tacyas/Eos/include/string.h /usr/include/math.h ../inc/config.h \ + ../inc/../inc/maker2Dto3DEstimator.h \ + /Users/tacyas/Eos/include/genUtil.h /Users/tacyas/Eos/include/File.h \ + /Users/tacyas/Eos/include/Memory.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/limits.h \ + /usr/include/limits.h /usr/include/machine/limits.h \ + /usr/include/i386/limits.h /usr/include/i386/_limits.h \ + /usr/include/sys/syslimits.h +init.o: init.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + /Users/tacyas/Eos/include/string.h /usr/include/math.h ../inc/config.h \ + ../inc/../inc/maker2Dto3DEstimator.h \ + /Users/tacyas/Eos/include/genUtil.h /Users/tacyas/Eos/include/File.h \ + /Users/tacyas/Eos/include/Memory.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/limits.h \ + /usr/include/limits.h /usr/include/machine/limits.h \ + /usr/include/i386/limits.h /usr/include/i386/_limits.h \ + /usr/include/sys/syslimits.h +usage.o: usage.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + ../inc/config.h ../inc/../inc/maker2Dto3DEstimator.h +util.o: util.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + ../inc/config.h ../inc/../inc/maker2Dto3DEstimator.h diff --git a/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/.Depend b/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/.Depend new file mode 100644 index 0000000000..daeea3fd95 --- /dev/null +++ b/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/.Depend @@ -0,0 +1,199 @@ +argCheck.o: argCheck.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + /Users/tacyas/Eos/include/string.h /usr/include/math.h ../inc/config.h \ + ../inc/../inc/marker2Dto3DEstimator.h \ + /Users/tacyas/Eos/include/genUtil.h /Users/tacyas/Eos/include/File.h \ + /Users/tacyas/Eos/include/Memory.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/limits.h \ + /usr/include/limits.h /usr/include/machine/limits.h \ + /usr/include/i386/limits.h /usr/include/i386/_limits.h \ + /usr/include/sys/syslimits.h +init.o: init.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + /Users/tacyas/Eos/include/string.h /usr/include/math.h ../inc/config.h \ + ../inc/../inc/marker2Dto3DEstimator.h \ + /Users/tacyas/Eos/include/genUtil.h /Users/tacyas/Eos/include/File.h \ + /Users/tacyas/Eos/include/Memory.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/limits.h \ + /usr/include/limits.h /usr/include/machine/limits.h \ + /usr/include/i386/limits.h /usr/include/i386/_limits.h \ + /usr/include/sys/syslimits.h +marker2Dto3DEstimator.o: marker2Dto3DEstimator.c /usr/include/stdio.h \ + /usr/include/sys/cdefs.h /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + /Users/tacyas/Eos/include/string.h /usr/include/math.h ../inc/config.h \ + ../inc/../inc/marker2Dto3DEstimator.h \ + /Users/tacyas/Eos/include/genUtil.h \ + /Users/tacyas/Eos/include/eosPoint.h \ + /Users/tacyas/Eos/include/Matrix3D.h \ + /Users/tacyas/Eos/include/Vector.h /Users/tacyas/Eos/include/Array.h +usage.o: usage.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + ../inc/config.h ../inc/../inc/marker2Dto3DEstimator.h +util.o: util.c /usr/include/stdio.h /usr/include/sys/cdefs.h \ + /usr/include/sys/_symbol_aliasing.h \ + /usr/include/sys/_posix_availability.h /usr/include/Availability.h \ + /usr/include/AvailabilityInternal.h /usr/include/_types.h \ + /usr/include/sys/_types.h /usr/include/machine/_types.h \ + /usr/include/i386/_types.h /usr/include/sys/_types/_va_list.h \ + /usr/include/sys/_types/_size_t.h /usr/include/sys/_types/_null.h \ + /usr/include/sys/_types/_off_t.h /usr/include/sys/_types/_ssize_t.h \ + /usr/include/secure/_stdio.h /usr/include/secure/_common.h \ + /usr/include/stdlib.h /usr/include/sys/wait.h \ + /usr/include/sys/_types/_pid_t.h /usr/include/sys/_types/_id_t.h \ + /usr/include/sys/signal.h /usr/include/sys/appleapiopts.h \ + /usr/include/machine/signal.h /usr/include/i386/signal.h \ + /usr/include/machine/_mcontext.h /usr/include/i386/_mcontext.h \ + /usr/include/mach/i386/_structs.h \ + /usr/include/sys/_types/_sigaltstack.h \ + /usr/include/sys/_types/_ucontext.h \ + /usr/include/sys/_types/_pthread_attr_t.h \ + /usr/include/sys/_types/_sigset_t.h /usr/include/sys/_types/_uid_t.h \ + /usr/include/sys/resource.h \ + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/5.1/include/stdint.h \ + /usr/include/stdint.h /usr/include/sys/_types/_int8_t.h \ + /usr/include/sys/_types/_int16_t.h /usr/include/sys/_types/_int32_t.h \ + /usr/include/sys/_types/_int64_t.h /usr/include/_types/_uint8_t.h \ + /usr/include/_types/_uint16_t.h /usr/include/_types/_uint32_t.h \ + /usr/include/_types/_uint64_t.h /usr/include/sys/_types/_intptr_t.h \ + /usr/include/sys/_types/_uintptr_t.h /usr/include/_types/_intmax_t.h \ + /usr/include/_types/_uintmax_t.h /usr/include/sys/_types/_timeval.h \ + /usr/include/machine/endian.h /usr/include/i386/endian.h \ + /usr/include/sys/_endian.h /usr/include/libkern/_OSByteOrder.h \ + /usr/include/libkern/i386/_OSByteOrder.h /usr/include/alloca.h \ + /usr/include/sys/_types/_ct_rune_t.h /usr/include/sys/_types/_rune_t.h \ + /usr/include/sys/_types/_wchar_t.h /usr/include/machine/types.h \ + /usr/include/i386/types.h /usr/include/sys/_types/___offsetof.h \ + /usr/include/sys/_types/_dev_t.h /usr/include/sys/_types/_mode_t.h \ + ../inc/config.h ../inc/../inc/marker2Dto3DEstimator.h diff --git a/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/Makefile b/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/Makefile new file mode 100755 index 0000000000..ec6124702f --- /dev/null +++ b/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/Makefile @@ -0,0 +1,114 @@ +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/$(OBJECTNAME)/Config/Define.inc +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/Config/Define.inc +include $(EOS_HOME)/src/$(WORLDNAME)/Config/Define.inc +include $(EOS_HOME)/src/Config/DefineTool.inc + +LIBFILES = \ + $(LIBPREFIX)EosObjects$(LIBSUFFIX) + +LIBFILESDEBUG = \ + $(LIBPREFIX)EosObjects.debug$(LIBSUFFIX) + +SRCC = \ + $(OBJECTNAME).c \ + init.c \ + argCheck.c \ + usage.c \ + util.c + +SRCCXX = \ + $(OBJECTNAME).cc \ + init.cc \ + argCheck.cc \ + usage.cc \ + util.cc + +MODULES = \ + $(OBJECTNAME).o \ + init.o \ + argCheck.o \ + usage.o \ + util.o + +REALMODULES = \ + $(OSTYPE)/$(OBJECTNAME).o \ + $(OSTYPE)/init.o \ + $(OSTYPE)/argCheck.o \ + $(OSTYPE)/usage.o \ + $(OSTYPE)/util.o + +MODULESDEBUG = \ + $(OBJECTNAME).debugo \ + init.debugo \ + argCheck.debugo \ + usage.debugo \ + util.debugo + +MODULESCUDAGDB = \ + $(OBJECTNAME).cudagdb.o \ + init.cudagdb.o \ + argCheck.cudagdb.o \ + usage.cudagdb.o \ + util.cudagdb.o + +REALMODULESDEBUG = \ + $(OSTYPE)/$(OBJECTNAME).debugo \ + $(OSTYPE)/init.debugo \ + $(OSTYPE)/argCheck.debugo \ + $(OSTYPE)/usage.debugo \ + $(OSTYPE)/util.debugo + + +$(OBJECTNAME): $(MODULES) $(LIBFILES) + @if [ -f $(VPATH)/$(OBJECTNAME).c ] ; \ + then \ + echo $(CC) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(CC) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).cc ] ; \ + then \ + echo $(CXX) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(CXX) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).ccm ] ; \ + then \ + echo "MICO"; \ + echo $(MICOLD) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(MICOLD) $(CCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).cu ] ; \ + then \ + echo $(NVCC) $(NVCCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) $(CUDALIB) $(CUDAINC) -o $@ ; \ + $(NVCC) $(NVCCOPTS) $(MODULES) $(LIBFILES) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) $(CUDALIB) $(CUDAINC) -o $@ ; \ + fi + + +$(OBJECTNAME).debug: $(MODULESDEBUG) $(LIBFILESDEBUG) + @if [ -f $(VPATH)/$(OBJECTNAME).c ] ; \ + then \ + echo $(CC) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(CC) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).cc ] ; \ + then \ + echo $(CXX) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(CXX) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).ccm ] ; \ + then \ + echo "MICO"; \ + echo $(MICOLD) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(MICOLD) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + @if [ -f $(VPATH)/$(OBJECTNAME).cu ] ; \ + then \ + echo $(CC) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + $(CC) $(CCOPTSDEBUG) $(MODULESDEBUG) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ ; \ + fi + +$(OBJECTNAME).cudagdb: $(MODULESCUDAGDB) $(LIBFILESDEBUG) + echo $(NVCC) "$(NVCCOPTSCUDAGDB) $(MODULESCUDAGDB) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@" + $(NVCC) $(NVCCOPTSCUDAGDB) $(MODULESCUDAGDB) $(LIBFILESDEBUG) $(EXTRA_LIB) $(KHOROS_LIBS) $(LIBPVM) $(STANDARDLIB) $(HOSTDEPENDENTLIB) -o $@ + +include ./.Depend +include $(EOS_HOME)/src/$(WORLDNAME)/$(CLASSNAME)/$(OBJECTNAME)/Config/Target.inc diff --git a/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/X86MAC64 b/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/X86MAC64 new file mode 120000 index 0000000000..d286fdf8b4 --- /dev/null +++ b/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/X86MAC64 @@ -0,0 +1 @@ +../../../../../hostdepend/X86MAC64/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64 \ No newline at end of file diff --git a/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/marker2Dto3DEstimator b/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/marker2Dto3DEstimator new file mode 100755 index 0000000000..736520e2c5 Binary files /dev/null and b/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64/marker2Dto3DEstimator differ diff --git a/util/X86MAC64/bin/gdb b/util/X86MAC64/bin/gdb new file mode 100755 index 0000000000..909f6a3e90 Binary files /dev/null and b/util/X86MAC64/bin/gdb differ diff --git a/util/X86MAC64/include/ansidecl.h b/util/X86MAC64/include/ansidecl.h new file mode 100644 index 0000000000..5cd03a7d76 --- /dev/null +++ b/util/X86MAC64/include/ansidecl.h @@ -0,0 +1,450 @@ +/* ANSI and traditional C compatability macros + Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, + 2002, 2003, 2004, 2005, 2006, 2007, 2009, 2010 + Free Software Foundation, Inc. + This file is part of the GNU C Library. + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA. */ + +/* ANSI and traditional C compatibility macros + + ANSI C is assumed if __STDC__ is #defined. + + Macro ANSI C definition Traditional C definition + ----- ---- - ---------- ----------- - ---------- + ANSI_PROTOTYPES 1 not defined + PTR `void *' `char *' + PTRCONST `void *const' `char *' + LONG_DOUBLE `long double' `double' + const not defined `' + volatile not defined `' + signed not defined `' + VA_START(ap, var) va_start(ap, var) va_start(ap) + + Note that it is safe to write "void foo();" indicating a function + with no return value, in all K+R compilers we have been able to test. + + For declaring functions with prototypes, we also provide these: + + PARAMS ((prototype)) + -- for functions which take a fixed number of arguments. Use this + when declaring the function. When defining the function, write a + K+R style argument list. For example: + + char *strcpy PARAMS ((char *dest, char *source)); + ... + char * + strcpy (dest, source) + char *dest; + char *source; + { ... } + + + VPARAMS ((prototype, ...)) + -- for functions which take a variable number of arguments. Use + PARAMS to declare the function, VPARAMS to define it. For example: + + int printf PARAMS ((const char *format, ...)); + ... + int + printf VPARAMS ((const char *format, ...)) + { + ... + } + + For writing functions which take variable numbers of arguments, we + also provide the VA_OPEN, VA_CLOSE, and VA_FIXEDARG macros. These + hide the differences between K+R and C89 more + thoroughly than the simple VA_START() macro mentioned above. + + VA_OPEN and VA_CLOSE are used *instead of* va_start and va_end. + Immediately after VA_OPEN, put a sequence of VA_FIXEDARG calls + corresponding to the list of fixed arguments. Then use va_arg + normally to get the variable arguments, or pass your va_list object + around. You do not declare the va_list yourself; VA_OPEN does it + for you. + + Here is a complete example: + + int + printf VPARAMS ((const char *format, ...)) + { + int result; + + VA_OPEN (ap, format); + VA_FIXEDARG (ap, const char *, format); + + result = vfprintf (stdout, format, ap); + VA_CLOSE (ap); + + return result; + } + + + You can declare variables either before or after the VA_OPEN, + VA_FIXEDARG sequence. Also, VA_OPEN and VA_CLOSE are the beginning + and end of a block. They must appear at the same nesting level, + and any variables declared after VA_OPEN go out of scope at + VA_CLOSE. Unfortunately, with a K+R compiler, that includes the + argument list. You can have multiple instances of VA_OPEN/VA_CLOSE + pairs in a single function in case you need to traverse the + argument list more than once. + + For ease of writing code which uses GCC extensions but needs to be + portable to other compilers, we provide the GCC_VERSION macro that + simplifies testing __GNUC__ and __GNUC_MINOR__ together, and various + wrappers around __attribute__. Also, __extension__ will be #defined + to nothing if it doesn't work. See below. + + This header also defines a lot of obsolete macros: + CONST, VOLATILE, SIGNED, PROTO, EXFUN, DEFUN, DEFUN_VOID, + AND, DOTS, NOARGS. Don't use them. */ + +#ifndef _ANSIDECL_H +#define _ANSIDECL_H 1 + +#ifdef __cplusplus +extern "C" { +#endif + +/* Every source file includes this file, + so they will all get the switch for lint. */ +/* LINTLIBRARY */ + +/* Using MACRO(x,y) in cpp #if conditionals does not work with some + older preprocessors. Thus we can't define something like this: + +#define HAVE_GCC_VERSION(MAJOR, MINOR) \ + (__GNUC__ > (MAJOR) || (__GNUC__ == (MAJOR) && __GNUC_MINOR__ >= (MINOR))) + +and then test "#if HAVE_GCC_VERSION(2,7)". + +So instead we use the macro below and test it against specific values. */ + +/* This macro simplifies testing whether we are using gcc, and if it + is of a particular minimum version. (Both major & minor numbers are + significant.) This macro will evaluate to 0 if we are not using + gcc at all. */ +#ifndef GCC_VERSION +#define GCC_VERSION (__GNUC__ * 1000 + __GNUC_MINOR__) +#endif /* GCC_VERSION */ + +#if defined (__STDC__) || defined(__cplusplus) || defined (_AIX) || (defined (__mips) && defined (_SYSTYPE_SVR4)) || defined(_WIN32) +/* All known AIX compilers implement these things (but don't always + define __STDC__). The RISC/OS MIPS compiler defines these things + in SVR4 mode, but does not define __STDC__. */ +/* eraxxon@alumni.rice.edu: The Compaq C++ compiler, unlike many other + C++ compilers, does not define __STDC__, though it acts as if this + was so. (Verified versions: 5.7, 6.2, 6.3, 6.5) */ + +#define ANSI_PROTOTYPES 1 +#define PTR void * +#define PTRCONST void *const +#define LONG_DOUBLE long double + +/* PARAMS is often defined elsewhere (e.g. by libintl.h), so wrap it in + a #ifndef. */ +#ifndef PARAMS +#define PARAMS(ARGS) ARGS +#endif + +#define VPARAMS(ARGS) ARGS +#define VA_START(VA_LIST, VAR) va_start(VA_LIST, VAR) + +/* variadic function helper macros */ +/* "struct Qdmy" swallows the semicolon after VA_OPEN/VA_FIXEDARG's + use without inhibiting further decls and without declaring an + actual variable. */ +#define VA_OPEN(AP, VAR) { va_list AP; va_start(AP, VAR); { struct Qdmy +#define VA_CLOSE(AP) } va_end(AP); } +#define VA_FIXEDARG(AP, T, N) struct Qdmy + +#undef const +#undef volatile +#undef signed + +/* inline requires special treatment; it's in C99, and GCC >=2.7 supports + it too, but it's not in C89. */ +#undef inline +#if __STDC_VERSION__ >= 199901L || defined(__cplusplus) || (defined(__SUNPRO_C) && defined(__C99FEATURES__)) +/* it's a keyword */ +#else +# if GCC_VERSION >= 2007 +# define inline __inline__ /* __inline__ prevents -pedantic warnings */ +# else +# define inline /* nothing */ +# endif +#endif + +/* These are obsolete. Do not use. */ +#ifndef IN_GCC +#define CONST const +#define VOLATILE volatile +#define SIGNED signed + +#define PROTO(type, name, arglist) type name arglist +#define EXFUN(name, proto) name proto +#define DEFUN(name, arglist, args) name(args) +#define DEFUN_VOID(name) name(void) +#define AND , +#define DOTS , ... +#define NOARGS void +#endif /* ! IN_GCC */ + +#else /* Not ANSI C. */ + +#undef ANSI_PROTOTYPES +#define PTR char * +#define PTRCONST PTR +#define LONG_DOUBLE double + +#define PARAMS(args) () +#define VPARAMS(args) (va_alist) va_dcl +#define VA_START(va_list, var) va_start(va_list) + +#define VA_OPEN(AP, VAR) { va_list AP; va_start(AP); { struct Qdmy +#define VA_CLOSE(AP) } va_end(AP); } +#define VA_FIXEDARG(AP, TYPE, NAME) TYPE NAME = va_arg(AP, TYPE) + +/* some systems define these in header files for non-ansi mode */ +#undef const +#undef volatile +#undef signed +#undef inline +#define const +#define volatile +#define signed +#define inline + +#ifndef IN_GCC +#define CONST +#define VOLATILE +#define SIGNED + +#define PROTO(type, name, arglist) type name () +#define EXFUN(name, proto) name() +#define DEFUN(name, arglist, args) name arglist args; +#define DEFUN_VOID(name) name() +#define AND ; +#define DOTS +#define NOARGS +#endif /* ! IN_GCC */ + +#endif /* ANSI C. */ + +/* Define macros for some gcc attributes. This permits us to use the + macros freely, and know that they will come into play for the + version of gcc in which they are supported. */ + +#if (GCC_VERSION < 2007) +# define __attribute__(x) +#endif + +/* Attribute __malloc__ on functions was valid as of gcc 2.96. */ +#ifndef ATTRIBUTE_MALLOC +# if (GCC_VERSION >= 2096) +# define ATTRIBUTE_MALLOC __attribute__ ((__malloc__)) +# else +# define ATTRIBUTE_MALLOC +# endif /* GNUC >= 2.96 */ +#endif /* ATTRIBUTE_MALLOC */ + +/* Attributes on labels were valid as of gcc 2.93 and g++ 4.5. For + g++ an attribute on a label must be followed by a semicolon. */ +#ifndef ATTRIBUTE_UNUSED_LABEL +# ifndef __cplusplus +# if GCC_VERSION >= 2093 +# define ATTRIBUTE_UNUSED_LABEL ATTRIBUTE_UNUSED +# else +# define ATTRIBUTE_UNUSED_LABEL +# endif +# else +# if GCC_VERSION >= 4005 +# define ATTRIBUTE_UNUSED_LABEL ATTRIBUTE_UNUSED ; +# else +# define ATTRIBUTE_UNUSED_LABEL +# endif +# endif +#endif + +/* Similarly to ARG_UNUSED below. Prior to GCC 3.4, the C++ frontend + couldn't parse attributes placed after the identifier name, and now + the entire compiler is built with C++. */ +#ifndef ATTRIBUTE_UNUSED +#if GCC_VERSION >= 3004 +# define ATTRIBUTE_UNUSED __attribute__ ((__unused__)) +#else +#define ATTRIBUTE_UNUSED +#endif +#endif /* ATTRIBUTE_UNUSED */ + +/* Before GCC 3.4, the C++ frontend couldn't parse attributes placed after the + identifier name. */ +#if ! defined(__cplusplus) || (GCC_VERSION >= 3004) +# define ARG_UNUSED(NAME) NAME ATTRIBUTE_UNUSED +#else /* !__cplusplus || GNUC >= 3.4 */ +# define ARG_UNUSED(NAME) NAME +#endif /* !__cplusplus || GNUC >= 3.4 */ + +#ifndef ATTRIBUTE_NORETURN +#define ATTRIBUTE_NORETURN __attribute__ ((__noreturn__)) +#endif /* ATTRIBUTE_NORETURN */ + +/* Attribute `nonnull' was valid as of gcc 3.3. */ +#ifndef ATTRIBUTE_NONNULL +# if (GCC_VERSION >= 3003) +# define ATTRIBUTE_NONNULL(m) __attribute__ ((__nonnull__ (m))) +# else +# define ATTRIBUTE_NONNULL(m) +# endif /* GNUC >= 3.3 */ +#endif /* ATTRIBUTE_NONNULL */ + +/* Attribute `returns_nonnull' was valid as of gcc 4.9. */ +#ifndef ATTRIBUTE_RETURNS_NONNULL +# if (GCC_VERSION >= 4009) +# define ATTRIBUTE_RETURNS_NONNULL __attribute__ ((__returns_nonnull__)) +# else +# define ATTRIBUTE_RETURNS_NONNULL +# endif /* GNUC >= 4.9 */ +#endif /* ATTRIBUTE_RETURNS_NONNULL */ + +/* Attribute `pure' was valid as of gcc 3.0. */ +#ifndef ATTRIBUTE_PURE +# if (GCC_VERSION >= 3000) +# define ATTRIBUTE_PURE __attribute__ ((__pure__)) +# else +# define ATTRIBUTE_PURE +# endif /* GNUC >= 3.0 */ +#endif /* ATTRIBUTE_PURE */ + +/* Use ATTRIBUTE_PRINTF when the format specifier must not be NULL. + This was the case for the `printf' format attribute by itself + before GCC 3.3, but as of 3.3 we need to add the `nonnull' + attribute to retain this behavior. */ +#ifndef ATTRIBUTE_PRINTF +#define ATTRIBUTE_PRINTF(m, n) __attribute__ ((__format__ (__printf__, m, n))) ATTRIBUTE_NONNULL(m) +#define ATTRIBUTE_PRINTF_1 ATTRIBUTE_PRINTF(1, 2) +#define ATTRIBUTE_PRINTF_2 ATTRIBUTE_PRINTF(2, 3) +#define ATTRIBUTE_PRINTF_3 ATTRIBUTE_PRINTF(3, 4) +#define ATTRIBUTE_PRINTF_4 ATTRIBUTE_PRINTF(4, 5) +#define ATTRIBUTE_PRINTF_5 ATTRIBUTE_PRINTF(5, 6) +#endif /* ATTRIBUTE_PRINTF */ + +/* Use ATTRIBUTE_FPTR_PRINTF when the format attribute is to be set on + a function pointer. Format attributes were allowed on function + pointers as of gcc 3.1. */ +#ifndef ATTRIBUTE_FPTR_PRINTF +# if (GCC_VERSION >= 3001) +# define ATTRIBUTE_FPTR_PRINTF(m, n) ATTRIBUTE_PRINTF(m, n) +# else +# define ATTRIBUTE_FPTR_PRINTF(m, n) +# endif /* GNUC >= 3.1 */ +# define ATTRIBUTE_FPTR_PRINTF_1 ATTRIBUTE_FPTR_PRINTF(1, 2) +# define ATTRIBUTE_FPTR_PRINTF_2 ATTRIBUTE_FPTR_PRINTF(2, 3) +# define ATTRIBUTE_FPTR_PRINTF_3 ATTRIBUTE_FPTR_PRINTF(3, 4) +# define ATTRIBUTE_FPTR_PRINTF_4 ATTRIBUTE_FPTR_PRINTF(4, 5) +# define ATTRIBUTE_FPTR_PRINTF_5 ATTRIBUTE_FPTR_PRINTF(5, 6) +#endif /* ATTRIBUTE_FPTR_PRINTF */ + +/* Use ATTRIBUTE_NULL_PRINTF when the format specifier may be NULL. A + NULL format specifier was allowed as of gcc 3.3. */ +#ifndef ATTRIBUTE_NULL_PRINTF +# if (GCC_VERSION >= 3003) +# define ATTRIBUTE_NULL_PRINTF(m, n) __attribute__ ((__format__ (__printf__, m, n))) +# else +# define ATTRIBUTE_NULL_PRINTF(m, n) +# endif /* GNUC >= 3.3 */ +# define ATTRIBUTE_NULL_PRINTF_1 ATTRIBUTE_NULL_PRINTF(1, 2) +# define ATTRIBUTE_NULL_PRINTF_2 ATTRIBUTE_NULL_PRINTF(2, 3) +# define ATTRIBUTE_NULL_PRINTF_3 ATTRIBUTE_NULL_PRINTF(3, 4) +# define ATTRIBUTE_NULL_PRINTF_4 ATTRIBUTE_NULL_PRINTF(4, 5) +# define ATTRIBUTE_NULL_PRINTF_5 ATTRIBUTE_NULL_PRINTF(5, 6) +#endif /* ATTRIBUTE_NULL_PRINTF */ + +/* Attribute `sentinel' was valid as of gcc 3.5. */ +#ifndef ATTRIBUTE_SENTINEL +# if (GCC_VERSION >= 3005) +# define ATTRIBUTE_SENTINEL __attribute__ ((__sentinel__)) +# else +# define ATTRIBUTE_SENTINEL +# endif /* GNUC >= 3.5 */ +#endif /* ATTRIBUTE_SENTINEL */ + + +#ifndef ATTRIBUTE_ALIGNED_ALIGNOF +# if (GCC_VERSION >= 3000) +# define ATTRIBUTE_ALIGNED_ALIGNOF(m) __attribute__ ((__aligned__ (__alignof__ (m)))) +# else +# define ATTRIBUTE_ALIGNED_ALIGNOF(m) +# endif /* GNUC >= 3.0 */ +#endif /* ATTRIBUTE_ALIGNED_ALIGNOF */ + +/* Useful for structures whose layout must much some binary specification + regardless of the alignment and padding qualities of the compiler. */ +#ifndef ATTRIBUTE_PACKED +# define ATTRIBUTE_PACKED __attribute__ ((packed)) +#endif + +/* Attribute `hot' and `cold' was valid as of gcc 4.3. */ +#ifndef ATTRIBUTE_COLD +# if (GCC_VERSION >= 4003) +# define ATTRIBUTE_COLD __attribute__ ((__cold__)) +# else +# define ATTRIBUTE_COLD +# endif /* GNUC >= 4.3 */ +#endif /* ATTRIBUTE_COLD */ +#ifndef ATTRIBUTE_HOT +# if (GCC_VERSION >= 4003) +# define ATTRIBUTE_HOT __attribute__ ((__hot__)) +# else +# define ATTRIBUTE_HOT +# endif /* GNUC >= 4.3 */ +#endif /* ATTRIBUTE_HOT */ + +/* We use __extension__ in some places to suppress -pedantic warnings + about GCC extensions. This feature didn't work properly before + gcc 2.8. */ +#if GCC_VERSION < 2008 +#define __extension__ +#endif + +/* This is used to declare a const variable which should be visible + outside of the current compilation unit. Use it as + EXPORTED_CONST int i = 1; + This is because the semantics of const are different in C and C++. + "extern const" is permitted in C but it looks strange, and gcc + warns about it when -Wc++-compat is not used. */ +#ifdef __cplusplus +#define EXPORTED_CONST extern const +#else +#define EXPORTED_CONST const +#endif + +/* Be conservative and only use enum bitfields with C++ or GCC. + FIXME: provide a complete autoconf test for buggy enum bitfields. */ + +#ifdef __cplusplus +#define ENUM_BITFIELD(TYPE) enum TYPE +#elif (GCC_VERSION > 2000) +#define ENUM_BITFIELD(TYPE) __extension__ enum TYPE +#else +#define ENUM_BITFIELD(TYPE) unsigned int +#endif + +#ifdef __cplusplus +} +#endif + +#endif /* ansidecl.h */ diff --git a/util/X86MAC64/include/bfd.h b/util/X86MAC64/include/bfd.h new file mode 100644 index 0000000000..da8897eebf --- /dev/null +++ b/util/X86MAC64/include/bfd.h @@ -0,0 +1,7180 @@ +/* DO NOT EDIT! -*- buffer-read-only: t -*- This file is automatically + generated from "bfd-in.h", "init.c", "opncls.c", "libbfd.c", + "bfdio.c", "bfdwin.c", "section.c", "archures.c", "reloc.c", + "syms.c", "bfd.c", "archive.c", "corefile.c", "targets.c", "format.c", + "linker.c", "simple.c" and "compress.c". + Run "make headers" in your build bfd/ to regenerate. */ + +/* Main header file for the bfd library -- portable access to object files. + + Copyright 1990-2013 Free Software Foundation, Inc. + + Contributed by Cygnus Support. + + This file is part of BFD, the Binary File Descriptor library. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA. */ + +#ifndef __BFD_H_SEEN__ +#define __BFD_H_SEEN__ + +/* PR 14072: Ensure that config.h is included first. */ +#if !defined PACKAGE && !defined PACKAGE_VERSION +#error config.h must be included before this header +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +#include "ansidecl.h" +#include "symcat.h" +#include + +#if defined (__STDC__) || defined (ALMOST_STDC) || defined (HAVE_STRINGIZE) +#ifndef SABER +/* This hack is to avoid a problem with some strict ANSI C preprocessors. + The problem is, "32_" is not a valid preprocessing token, and we don't + want extra underscores (e.g., "nlm_32_"). The XCONCAT2 macro will + cause the inner CONCAT2 macros to be evaluated first, producing + still-valid pp-tokens. Then the final concatenation can be done. */ +#undef CONCAT4 +#define CONCAT4(a,b,c,d) XCONCAT2(CONCAT2(a,b),CONCAT2(c,d)) +#endif +#endif + +/* This is a utility macro to handle the situation where the code + wants to place a constant string into the code, followed by a + comma and then the length of the string. Doing this by hand + is error prone, so using this macro is safer. */ +#define STRING_COMMA_LEN(STR) (STR), (sizeof (STR) - 1) +/* Unfortunately it is not possible to use the STRING_COMMA_LEN macro + to create the arguments to another macro, since the preprocessor + will mis-count the number of arguments to the outer macro (by not + evaluating STRING_COMMA_LEN and so missing the comma). This is a + problem for example when trying to use STRING_COMMA_LEN to build + the arguments to the strncmp() macro. Hence this alternative + definition of strncmp is provided here. + + Note - these macros do NOT work if STR2 is not a constant string. */ +#define CONST_STRNEQ(STR1,STR2) (strncmp ((STR1), (STR2), sizeof (STR2) - 1) == 0) + /* strcpy() can have a similar problem, but since we know we are + copying a constant string, we can use memcpy which will be faster + since there is no need to check for a NUL byte inside STR. We + can also save time if we do not need to copy the terminating NUL. */ +#define LITMEMCPY(DEST,STR2) memcpy ((DEST), (STR2), sizeof (STR2) - 1) +#define LITSTRCPY(DEST,STR2) memcpy ((DEST), (STR2), sizeof (STR2)) + + +#define BFD_SUPPORTS_PLUGINS 0 + +/* The word size used by BFD on the host. This may be 64 with a 32 + bit target if the host is 64 bit, or if other 64 bit targets have + been selected with --enable-targets, or if --enable-64-bit-bfd. */ +#define BFD_ARCH_SIZE 64 + +/* The word size of the default bfd target. */ +#define BFD_DEFAULT_TARGET_SIZE 32 + +#define BFD_HOST_64BIT_LONG 1 +#define BFD_HOST_64BIT_LONG_LONG 0 +#if 1 +#define BFD_HOST_64_BIT long +#define BFD_HOST_U_64_BIT unsigned long +typedef BFD_HOST_64_BIT bfd_int64_t; +typedef BFD_HOST_U_64_BIT bfd_uint64_t; +#endif + +#if BFD_ARCH_SIZE >= 64 +#define BFD64 +#endif + +#ifndef INLINE +#if __GNUC__ >= 2 +#define INLINE __inline__ +#else +#define INLINE +#endif +#endif + +/* Declaring a type wide enough to hold a host long and a host pointer. */ +#define BFD_HOSTPTR_T unsigned long +typedef BFD_HOSTPTR_T bfd_hostptr_t; + +/* Forward declaration. */ +typedef struct bfd bfd; + +/* Boolean type used in bfd. Too many systems define their own + versions of "boolean" for us to safely typedef a "boolean" of + our own. Using an enum for "bfd_boolean" has its own set of + problems, with strange looking casts required to avoid warnings + on some older compilers. Thus we just use an int. + + General rule: Functions which are bfd_boolean return TRUE on + success and FALSE on failure (unless they're a predicate). */ + +typedef int bfd_boolean; +#undef FALSE +#undef TRUE +#define FALSE 0 +#define TRUE 1 + +#ifdef BFD64 + +#ifndef BFD_HOST_64_BIT + #error No 64 bit integer type available +#endif /* ! defined (BFD_HOST_64_BIT) */ + +typedef BFD_HOST_U_64_BIT bfd_vma; +typedef BFD_HOST_64_BIT bfd_signed_vma; +typedef BFD_HOST_U_64_BIT bfd_size_type; +typedef BFD_HOST_U_64_BIT symvalue; + +#if BFD_HOST_64BIT_LONG +#define BFD_VMA_FMT "l" +#elif defined (__MSVCRT__) +#define BFD_VMA_FMT "I64" +#else +#define BFD_VMA_FMT "ll" +#endif + +#ifndef fprintf_vma +#define sprintf_vma(s,x) sprintf (s, "%016" BFD_VMA_FMT "x", x) +#define fprintf_vma(f,x) fprintf (f, "%016" BFD_VMA_FMT "x", x) +#endif + +#else /* not BFD64 */ + +/* Represent a target address. Also used as a generic unsigned type + which is guaranteed to be big enough to hold any arithmetic types + we need to deal with. */ +typedef unsigned long bfd_vma; + +/* A generic signed type which is guaranteed to be big enough to hold any + arithmetic types we need to deal with. Can be assumed to be compatible + with bfd_vma in the same way that signed and unsigned ints are compatible + (as parameters, in assignment, etc). */ +typedef long bfd_signed_vma; + +typedef unsigned long symvalue; +typedef unsigned long bfd_size_type; + +/* Print a bfd_vma x on stream s. */ +#define BFD_VMA_FMT "l" +#define fprintf_vma(s,x) fprintf (s, "%08" BFD_VMA_FMT "x", x) +#define sprintf_vma(s,x) sprintf (s, "%08" BFD_VMA_FMT "x", x) + +#endif /* not BFD64 */ + +#define HALF_BFD_SIZE_TYPE \ + (((bfd_size_type) 1) << (8 * sizeof (bfd_size_type) / 2)) + +#ifndef BFD_HOST_64_BIT +/* Fall back on a 32 bit type. The idea is to make these types always + available for function return types, but in the case that + BFD_HOST_64_BIT is undefined such a function should abort or + otherwise signal an error. */ +typedef bfd_signed_vma bfd_int64_t; +typedef bfd_vma bfd_uint64_t; +#endif + +/* An offset into a file. BFD always uses the largest possible offset + based on the build time availability of fseek, fseeko, or fseeko64. */ +typedef BFD_HOST_64_BIT file_ptr; +typedef unsigned BFD_HOST_64_BIT ufile_ptr; + +extern void bfd_sprintf_vma (bfd *, char *, bfd_vma); +extern void bfd_fprintf_vma (bfd *, void *, bfd_vma); + +#define printf_vma(x) fprintf_vma(stdout,x) +#define bfd_printf_vma(abfd,x) bfd_fprintf_vma (abfd,stdout,x) + +typedef unsigned int flagword; /* 32 bits of flags */ +typedef unsigned char bfd_byte; + +/* File formats. */ + +typedef enum bfd_format +{ + bfd_unknown = 0, /* File format is unknown. */ + bfd_object, /* Linker/assembler/compiler output. */ + bfd_archive, /* Object archive file. */ + bfd_core, /* Core dump. */ + bfd_type_end /* Marks the end; don't use it! */ +} +bfd_format; + +/* Symbols and relocation. */ + +/* A count of carsyms (canonical archive symbols). */ +typedef unsigned long symindex; + +/* How to perform a relocation. */ +typedef const struct reloc_howto_struct reloc_howto_type; + +#define BFD_NO_MORE_SYMBOLS ((symindex) ~0) + +/* General purpose part of a symbol X; + target specific parts are in libcoff.h, libaout.h, etc. */ + +#define bfd_get_section(x) ((x)->section) +#define bfd_get_output_section(x) ((x)->section->output_section) +#define bfd_set_section(x,y) ((x)->section) = (y) +#define bfd_asymbol_base(x) ((x)->section->vma) +#define bfd_asymbol_value(x) (bfd_asymbol_base(x) + (x)->value) +#define bfd_asymbol_name(x) ((x)->name) +/*Perhaps future: #define bfd_asymbol_bfd(x) ((x)->section->owner)*/ +#define bfd_asymbol_bfd(x) ((x)->the_bfd) +#define bfd_asymbol_flavour(x) \ + (((x)->flags & BSF_SYNTHETIC) != 0 \ + ? bfd_target_unknown_flavour \ + : bfd_asymbol_bfd (x)->xvec->flavour) + +/* A canonical archive symbol. */ +/* This is a type pun with struct ranlib on purpose! */ +typedef struct carsym +{ + char *name; + file_ptr file_offset; /* Look here to find the file. */ +} +carsym; /* To make these you call a carsymogen. */ + +/* Used in generating armaps (archive tables of contents). + Perhaps just a forward definition would do? */ +struct orl /* Output ranlib. */ +{ + char **name; /* Symbol name. */ + union + { + file_ptr pos; + bfd *abfd; + } u; /* bfd* or file position. */ + int namidx; /* Index into string table. */ +}; + +/* Linenumber stuff. */ +typedef struct lineno_cache_entry +{ + unsigned int line_number; /* Linenumber from start of function. */ + union + { + struct bfd_symbol *sym; /* Function name. */ + bfd_vma offset; /* Offset into section. */ + } u; +} +alent; + +/* Object and core file sections. */ + +#define align_power(addr, align) \ + (((addr) + ((bfd_vma) 1 << (align)) - 1) & ((bfd_vma) -1 << (align))) + +typedef struct bfd_section *sec_ptr; + +#define bfd_get_section_name(bfd, ptr) ((void) bfd, (ptr)->name) +#define bfd_get_section_vma(bfd, ptr) ((void) bfd, (ptr)->vma) +#define bfd_get_section_lma(bfd, ptr) ((void) bfd, (ptr)->lma) +#define bfd_get_section_alignment(bfd, ptr) ((void) bfd, \ + (ptr)->alignment_power) +#define bfd_section_name(bfd, ptr) ((ptr)->name) +#define bfd_section_size(bfd, ptr) ((ptr)->size) +#define bfd_get_section_size(ptr) ((ptr)->size) +#define bfd_section_vma(bfd, ptr) ((ptr)->vma) +#define bfd_section_lma(bfd, ptr) ((ptr)->lma) +#define bfd_section_alignment(bfd, ptr) ((ptr)->alignment_power) +#define bfd_get_section_flags(bfd, ptr) ((void) bfd, (ptr)->flags) +#define bfd_get_section_userdata(bfd, ptr) ((void) bfd, (ptr)->userdata) + +#define bfd_is_com_section(ptr) (((ptr)->flags & SEC_IS_COMMON) != 0) + +/* Find the address one past the end of SEC. */ +#define bfd_get_section_limit(bfd, sec) \ + (((bfd)->direction != write_direction && (sec)->rawsize != 0 \ + ? (sec)->rawsize : (sec)->size) / bfd_octets_per_byte (bfd)) + +/* Return TRUE if input section SEC has been discarded. */ +#define discarded_section(sec) \ + (!bfd_is_abs_section (sec) \ + && bfd_is_abs_section ((sec)->output_section) \ + && (sec)->sec_info_type != SEC_INFO_TYPE_MERGE \ + && (sec)->sec_info_type != SEC_INFO_TYPE_JUST_SYMS) + +typedef enum bfd_print_symbol +{ + bfd_print_symbol_name, + bfd_print_symbol_more, + bfd_print_symbol_all +} bfd_print_symbol_type; + +/* Information about a symbol that nm needs. */ + +typedef struct _symbol_info +{ + symvalue value; + char type; + const char *name; /* Symbol name. */ + unsigned char stab_type; /* Stab type. */ + char stab_other; /* Stab other. */ + short stab_desc; /* Stab desc. */ + const char *stab_name; /* String for stab type. */ +} symbol_info; + +/* Get the name of a stabs type code. */ + +extern const char *bfd_get_stab_name (int); + +/* Hash table routines. There is no way to free up a hash table. */ + +/* An element in the hash table. Most uses will actually use a larger + structure, and an instance of this will be the first field. */ + +struct bfd_hash_entry +{ + /* Next entry for this hash code. */ + struct bfd_hash_entry *next; + /* String being hashed. */ + const char *string; + /* Hash code. This is the full hash code, not the index into the + table. */ + unsigned long hash; +}; + +/* A hash table. */ + +struct bfd_hash_table +{ + /* The hash array. */ + struct bfd_hash_entry **table; + /* A function used to create new elements in the hash table. The + first entry is itself a pointer to an element. When this + function is first invoked, this pointer will be NULL. However, + having the pointer permits a hierarchy of method functions to be + built each of which calls the function in the superclass. Thus + each function should be written to allocate a new block of memory + only if the argument is NULL. */ + struct bfd_hash_entry *(*newfunc) + (struct bfd_hash_entry *, struct bfd_hash_table *, const char *); + /* An objalloc for this hash table. This is a struct objalloc *, + but we use void * to avoid requiring the inclusion of objalloc.h. */ + void *memory; + /* The number of slots in the hash table. */ + unsigned int size; + /* The number of entries in the hash table. */ + unsigned int count; + /* The size of elements. */ + unsigned int entsize; + /* If non-zero, don't grow the hash table. */ + unsigned int frozen:1; +}; + +/* Initialize a hash table. */ +extern bfd_boolean bfd_hash_table_init + (struct bfd_hash_table *, + struct bfd_hash_entry *(*) (struct bfd_hash_entry *, + struct bfd_hash_table *, + const char *), + unsigned int); + +/* Initialize a hash table specifying a size. */ +extern bfd_boolean bfd_hash_table_init_n + (struct bfd_hash_table *, + struct bfd_hash_entry *(*) (struct bfd_hash_entry *, + struct bfd_hash_table *, + const char *), + unsigned int, unsigned int); + +/* Free up a hash table. */ +extern void bfd_hash_table_free + (struct bfd_hash_table *); + +/* Look up a string in a hash table. If CREATE is TRUE, a new entry + will be created for this string if one does not already exist. The + COPY argument must be TRUE if this routine should copy the string + into newly allocated memory when adding an entry. */ +extern struct bfd_hash_entry *bfd_hash_lookup + (struct bfd_hash_table *, const char *, bfd_boolean create, + bfd_boolean copy); + +/* Insert an entry in a hash table. */ +extern struct bfd_hash_entry *bfd_hash_insert + (struct bfd_hash_table *, const char *, unsigned long); + +/* Rename an entry in a hash table. */ +extern void bfd_hash_rename + (struct bfd_hash_table *, const char *, struct bfd_hash_entry *); + +/* Replace an entry in a hash table. */ +extern void bfd_hash_replace + (struct bfd_hash_table *, struct bfd_hash_entry *old, + struct bfd_hash_entry *nw); + +/* Base method for creating a hash table entry. */ +extern struct bfd_hash_entry *bfd_hash_newfunc + (struct bfd_hash_entry *, struct bfd_hash_table *, const char *); + +/* Grab some space for a hash table entry. */ +extern void *bfd_hash_allocate + (struct bfd_hash_table *, unsigned int); + +/* Traverse a hash table in a random order, calling a function on each + element. If the function returns FALSE, the traversal stops. The + INFO argument is passed to the function. */ +extern void bfd_hash_traverse + (struct bfd_hash_table *, + bfd_boolean (*) (struct bfd_hash_entry *, void *), + void *info); + +/* Allows the default size of a hash table to be configured. New hash + tables allocated using bfd_hash_table_init will be created with + this size. */ +extern unsigned long bfd_hash_set_default_size (unsigned long); + +/* This structure is used to keep track of stabs in sections + information while linking. */ + +struct stab_info +{ + /* A hash table used to hold stabs strings. */ + struct bfd_strtab_hash *strings; + /* The header file hash table. */ + struct bfd_hash_table includes; + /* The first .stabstr section. */ + struct bfd_section *stabstr; +}; + +#define COFF_SWAP_TABLE (void *) &bfd_coff_std_swap_table + +/* User program access to BFD facilities. */ + +/* Direct I/O routines, for programs which know more about the object + file than BFD does. Use higher level routines if possible. */ + +extern bfd_size_type bfd_bread (void *, bfd_size_type, bfd *); +extern bfd_size_type bfd_bwrite (const void *, bfd_size_type, bfd *); +extern int bfd_seek (bfd *, file_ptr, int); +extern file_ptr bfd_tell (bfd *); +extern int bfd_flush (bfd *); +extern int bfd_stat (bfd *, struct stat *); + +/* Deprecated old routines. */ +#if __GNUC__ +#define bfd_read(BUF, ELTSIZE, NITEMS, ABFD) \ + (warn_deprecated ("bfd_read", __FILE__, __LINE__, __FUNCTION__), \ + bfd_bread ((BUF), (ELTSIZE) * (NITEMS), (ABFD))) +#define bfd_write(BUF, ELTSIZE, NITEMS, ABFD) \ + (warn_deprecated ("bfd_write", __FILE__, __LINE__, __FUNCTION__), \ + bfd_bwrite ((BUF), (ELTSIZE) * (NITEMS), (ABFD))) +#else +#define bfd_read(BUF, ELTSIZE, NITEMS, ABFD) \ + (warn_deprecated ("bfd_read", (const char *) 0, 0, (const char *) 0), \ + bfd_bread ((BUF), (ELTSIZE) * (NITEMS), (ABFD))) +#define bfd_write(BUF, ELTSIZE, NITEMS, ABFD) \ + (warn_deprecated ("bfd_write", (const char *) 0, 0, (const char *) 0),\ + bfd_bwrite ((BUF), (ELTSIZE) * (NITEMS), (ABFD))) +#endif +extern void warn_deprecated (const char *, const char *, int, const char *); + +/* Cast from const char * to char * so that caller can assign to + a char * without a warning. */ +#define bfd_get_filename(abfd) ((char *) (abfd)->filename) +#define bfd_get_cacheable(abfd) ((abfd)->cacheable) +#define bfd_get_format(abfd) ((abfd)->format) +#define bfd_get_target(abfd) ((abfd)->xvec->name) +#define bfd_get_flavour(abfd) ((abfd)->xvec->flavour) +#define bfd_family_coff(abfd) \ + (bfd_get_flavour (abfd) == bfd_target_coff_flavour || \ + bfd_get_flavour (abfd) == bfd_target_xcoff_flavour) +#define bfd_big_endian(abfd) ((abfd)->xvec->byteorder == BFD_ENDIAN_BIG) +#define bfd_little_endian(abfd) ((abfd)->xvec->byteorder == BFD_ENDIAN_LITTLE) +#define bfd_header_big_endian(abfd) \ + ((abfd)->xvec->header_byteorder == BFD_ENDIAN_BIG) +#define bfd_header_little_endian(abfd) \ + ((abfd)->xvec->header_byteorder == BFD_ENDIAN_LITTLE) +#define bfd_get_file_flags(abfd) ((abfd)->flags) +#define bfd_applicable_file_flags(abfd) ((abfd)->xvec->object_flags) +#define bfd_applicable_section_flags(abfd) ((abfd)->xvec->section_flags) +#define bfd_my_archive(abfd) ((abfd)->my_archive) +#define bfd_has_map(abfd) ((abfd)->has_armap) +#define bfd_is_thin_archive(abfd) ((abfd)->is_thin_archive) + +#define bfd_valid_reloc_types(abfd) ((abfd)->xvec->valid_reloc_types) +#define bfd_usrdata(abfd) ((abfd)->usrdata) + +#define bfd_get_start_address(abfd) ((abfd)->start_address) +#define bfd_get_symcount(abfd) ((abfd)->symcount) +#define bfd_get_outsymbols(abfd) ((abfd)->outsymbols) +#define bfd_count_sections(abfd) ((abfd)->section_count) + +#define bfd_get_dynamic_symcount(abfd) ((abfd)->dynsymcount) + +#define bfd_get_symbol_leading_char(abfd) ((abfd)->xvec->symbol_leading_char) + +extern bfd_boolean bfd_cache_close + (bfd *abfd); +/* NB: This declaration should match the autogenerated one in libbfd.h. */ + +extern bfd_boolean bfd_cache_close_all (void); + +extern bfd_boolean bfd_record_phdr + (bfd *, unsigned long, bfd_boolean, flagword, bfd_boolean, bfd_vma, + bfd_boolean, bfd_boolean, unsigned int, struct bfd_section **); + +/* Byte swapping routines. */ + +bfd_uint64_t bfd_getb64 (const void *); +bfd_uint64_t bfd_getl64 (const void *); +bfd_int64_t bfd_getb_signed_64 (const void *); +bfd_int64_t bfd_getl_signed_64 (const void *); +bfd_vma bfd_getb32 (const void *); +bfd_vma bfd_getl32 (const void *); +bfd_signed_vma bfd_getb_signed_32 (const void *); +bfd_signed_vma bfd_getl_signed_32 (const void *); +bfd_vma bfd_getb16 (const void *); +bfd_vma bfd_getl16 (const void *); +bfd_signed_vma bfd_getb_signed_16 (const void *); +bfd_signed_vma bfd_getl_signed_16 (const void *); +void bfd_putb64 (bfd_uint64_t, void *); +void bfd_putl64 (bfd_uint64_t, void *); +void bfd_putb32 (bfd_vma, void *); +void bfd_putl32 (bfd_vma, void *); +void bfd_putb16 (bfd_vma, void *); +void bfd_putl16 (bfd_vma, void *); + +/* Byte swapping routines which take size and endiannes as arguments. */ + +bfd_uint64_t bfd_get_bits (const void *, int, bfd_boolean); +void bfd_put_bits (bfd_uint64_t, void *, int, bfd_boolean); + +#if defined(__STDC__) || defined(ALMOST_STDC) +struct ecoff_debug_info; +struct ecoff_debug_swap; +struct ecoff_extr; +struct bfd_symbol; +struct bfd_link_info; +struct bfd_link_hash_entry; +struct bfd_section_already_linked; +struct bfd_elf_version_tree; +#endif + +extern bfd_boolean bfd_section_already_linked_table_init (void); +extern void bfd_section_already_linked_table_free (void); +extern bfd_boolean _bfd_handle_already_linked + (struct bfd_section *, struct bfd_section_already_linked *, + struct bfd_link_info *); + +/* Externally visible ECOFF routines. */ + +extern bfd_vma bfd_ecoff_get_gp_value + (bfd * abfd); +extern bfd_boolean bfd_ecoff_set_gp_value + (bfd *abfd, bfd_vma gp_value); +extern bfd_boolean bfd_ecoff_set_regmasks + (bfd *abfd, unsigned long gprmask, unsigned long fprmask, + unsigned long *cprmask); +extern void *bfd_ecoff_debug_init + (bfd *output_bfd, struct ecoff_debug_info *output_debug, + const struct ecoff_debug_swap *output_swap, struct bfd_link_info *); +extern void bfd_ecoff_debug_free + (void *handle, bfd *output_bfd, struct ecoff_debug_info *output_debug, + const struct ecoff_debug_swap *output_swap, struct bfd_link_info *); +extern bfd_boolean bfd_ecoff_debug_accumulate + (void *handle, bfd *output_bfd, struct ecoff_debug_info *output_debug, + const struct ecoff_debug_swap *output_swap, bfd *input_bfd, + struct ecoff_debug_info *input_debug, + const struct ecoff_debug_swap *input_swap, struct bfd_link_info *); +extern bfd_boolean bfd_ecoff_debug_accumulate_other + (void *handle, bfd *output_bfd, struct ecoff_debug_info *output_debug, + const struct ecoff_debug_swap *output_swap, bfd *input_bfd, + struct bfd_link_info *); +extern bfd_boolean bfd_ecoff_debug_externals + (bfd *abfd, struct ecoff_debug_info *debug, + const struct ecoff_debug_swap *swap, bfd_boolean relocatable, + bfd_boolean (*get_extr) (struct bfd_symbol *, struct ecoff_extr *), + void (*set_index) (struct bfd_symbol *, bfd_size_type)); +extern bfd_boolean bfd_ecoff_debug_one_external + (bfd *abfd, struct ecoff_debug_info *debug, + const struct ecoff_debug_swap *swap, const char *name, + struct ecoff_extr *esym); +extern bfd_size_type bfd_ecoff_debug_size + (bfd *abfd, struct ecoff_debug_info *debug, + const struct ecoff_debug_swap *swap); +extern bfd_boolean bfd_ecoff_write_debug + (bfd *abfd, struct ecoff_debug_info *debug, + const struct ecoff_debug_swap *swap, file_ptr where); +extern bfd_boolean bfd_ecoff_write_accumulated_debug + (void *handle, bfd *abfd, struct ecoff_debug_info *debug, + const struct ecoff_debug_swap *swap, + struct bfd_link_info *info, file_ptr where); + +/* Externally visible ELF routines. */ + +struct bfd_link_needed_list +{ + struct bfd_link_needed_list *next; + bfd *by; + const char *name; +}; + +enum dynamic_lib_link_class { + DYN_NORMAL = 0, + DYN_AS_NEEDED = 1, + DYN_DT_NEEDED = 2, + DYN_NO_ADD_NEEDED = 4, + DYN_NO_NEEDED = 8 +}; + +enum notice_asneeded_action { + notice_as_needed, + notice_not_needed, + notice_needed +}; + +extern bfd_boolean bfd_elf_record_link_assignment + (bfd *, struct bfd_link_info *, const char *, bfd_boolean, + bfd_boolean); +extern struct bfd_link_needed_list *bfd_elf_get_needed_list + (bfd *, struct bfd_link_info *); +extern bfd_boolean bfd_elf_get_bfd_needed_list + (bfd *, struct bfd_link_needed_list **); +extern bfd_boolean bfd_elf_stack_segment_size (bfd *, struct bfd_link_info *, + const char *, bfd_vma); +extern bfd_boolean bfd_elf_size_dynamic_sections + (bfd *, const char *, const char *, const char *, const char *, const char *, + const char * const *, struct bfd_link_info *, struct bfd_section **); +extern bfd_boolean bfd_elf_size_dynsym_hash_dynstr + (bfd *, struct bfd_link_info *); +extern void bfd_elf_set_dt_needed_name + (bfd *, const char *); +extern const char *bfd_elf_get_dt_soname + (bfd *); +extern void bfd_elf_set_dyn_lib_class + (bfd *, enum dynamic_lib_link_class); +extern int bfd_elf_get_dyn_lib_class + (bfd *); +extern struct bfd_link_needed_list *bfd_elf_get_runpath_list + (bfd *, struct bfd_link_info *); +extern bfd_boolean bfd_elf_discard_info + (bfd *, struct bfd_link_info *); +extern unsigned int _bfd_elf_default_action_discarded + (struct bfd_section *); + +/* Return an upper bound on the number of bytes required to store a + copy of ABFD's program header table entries. Return -1 if an error + occurs; bfd_get_error will return an appropriate code. */ +extern long bfd_get_elf_phdr_upper_bound + (bfd *abfd); + +/* Copy ABFD's program header table entries to *PHDRS. The entries + will be stored as an array of Elf_Internal_Phdr structures, as + defined in include/elf/internal.h. To find out how large the + buffer needs to be, call bfd_get_elf_phdr_upper_bound. + + Return the number of program header table entries read, or -1 if an + error occurs; bfd_get_error will return an appropriate code. */ +extern int bfd_get_elf_phdrs + (bfd *abfd, void *phdrs); + +/* Create a new BFD as if by bfd_openr. Rather than opening a file, + reconstruct an ELF file by reading the segments out of remote memory + based on the ELF file header at EHDR_VMA and the ELF program headers it + points to. If not null, *LOADBASEP is filled in with the difference + between the VMAs from which the segments were read, and the VMAs the + file headers (and hence BFD's idea of each section's VMA) put them at. + + The function TARGET_READ_MEMORY is called to copy LEN bytes from the + remote memory at target address VMA into the local buffer at MYADDR; it + should return zero on success or an `errno' code on failure. TEMPL must + be a BFD for an ELF target with the word size and byte order found in + the remote memory. */ +extern bfd *bfd_elf_bfd_from_remote_memory + (bfd *templ, bfd_vma ehdr_vma, bfd_vma *loadbasep, + int (*target_read_memory) (bfd_vma vma, bfd_byte *myaddr, + bfd_size_type len)); + +extern struct bfd_section *_bfd_elf_tls_setup + (bfd *, struct bfd_link_info *); + +extern struct bfd_section * +_bfd_nearby_section (bfd *, struct bfd_section *, bfd_vma); + +extern void _bfd_fix_excluded_sec_syms + (bfd *, struct bfd_link_info *); + +extern unsigned bfd_m68k_mach_to_features (int); + +extern int bfd_m68k_features_to_mach (unsigned); + +extern bfd_boolean bfd_m68k_elf32_create_embedded_relocs + (bfd *, struct bfd_link_info *, struct bfd_section *, struct bfd_section *, + char **); + +extern void bfd_elf_m68k_set_target_options (struct bfd_link_info *, int); + +extern bfd_boolean bfd_bfin_elf32_create_embedded_relocs + (bfd *, struct bfd_link_info *, struct bfd_section *, struct bfd_section *, + char **); + +extern bfd_boolean bfd_cr16_elf32_create_embedded_relocs + (bfd *, struct bfd_link_info *, struct bfd_section *, struct bfd_section *, + char **); + +/* SunOS shared library support routines for the linker. */ + +extern struct bfd_link_needed_list *bfd_sunos_get_needed_list + (bfd *, struct bfd_link_info *); +extern bfd_boolean bfd_sunos_record_link_assignment + (bfd *, struct bfd_link_info *, const char *); +extern bfd_boolean bfd_sunos_size_dynamic_sections + (bfd *, struct bfd_link_info *, struct bfd_section **, + struct bfd_section **, struct bfd_section **); + +/* Linux shared library support routines for the linker. */ + +extern bfd_boolean bfd_i386linux_size_dynamic_sections + (bfd *, struct bfd_link_info *); +extern bfd_boolean bfd_m68klinux_size_dynamic_sections + (bfd *, struct bfd_link_info *); +extern bfd_boolean bfd_sparclinux_size_dynamic_sections + (bfd *, struct bfd_link_info *); + +/* mmap hacks */ + +struct _bfd_window_internal; +typedef struct _bfd_window_internal bfd_window_internal; + +typedef struct _bfd_window +{ + /* What the user asked for. */ + void *data; + bfd_size_type size; + /* The actual window used by BFD. Small user-requested read-only + regions sharing a page may share a single window into the object + file. Read-write versions shouldn't until I've fixed things to + keep track of which portions have been claimed by the + application; don't want to give the same region back when the + application wants two writable copies! */ + struct _bfd_window_internal *i; +} +bfd_window; + +extern void bfd_init_window + (bfd_window *); +extern void bfd_free_window + (bfd_window *); +extern bfd_boolean bfd_get_file_window + (bfd *, file_ptr, bfd_size_type, bfd_window *, bfd_boolean); + +/* XCOFF support routines for the linker. */ + +extern bfd_boolean bfd_xcoff_split_import_path + (bfd *, const char *, const char **, const char **); +extern bfd_boolean bfd_xcoff_set_archive_import_path + (struct bfd_link_info *, bfd *, const char *); +extern bfd_boolean bfd_xcoff_link_record_set + (bfd *, struct bfd_link_info *, struct bfd_link_hash_entry *, bfd_size_type); +extern bfd_boolean bfd_xcoff_import_symbol + (bfd *, struct bfd_link_info *, struct bfd_link_hash_entry *, bfd_vma, + const char *, const char *, const char *, unsigned int); +extern bfd_boolean bfd_xcoff_export_symbol + (bfd *, struct bfd_link_info *, struct bfd_link_hash_entry *); +extern bfd_boolean bfd_xcoff_link_count_reloc + (bfd *, struct bfd_link_info *, const char *); +extern bfd_boolean bfd_xcoff_record_link_assignment + (bfd *, struct bfd_link_info *, const char *); +extern bfd_boolean bfd_xcoff_size_dynamic_sections + (bfd *, struct bfd_link_info *, const char *, const char *, + unsigned long, unsigned long, unsigned long, bfd_boolean, + int, bfd_boolean, unsigned int, struct bfd_section **, bfd_boolean); +extern bfd_boolean bfd_xcoff_link_generate_rtinit + (bfd *, const char *, const char *, bfd_boolean); + +/* XCOFF support routines for ar. */ +extern bfd_boolean bfd_xcoff_ar_archive_set_magic + (bfd *, char *); + +/* Externally visible COFF routines. */ + +#if defined(__STDC__) || defined(ALMOST_STDC) +struct internal_syment; +union internal_auxent; +#endif + +extern bfd_boolean bfd_coff_get_syment + (bfd *, struct bfd_symbol *, struct internal_syment *); + +extern bfd_boolean bfd_coff_get_auxent + (bfd *, struct bfd_symbol *, int, union internal_auxent *); + +extern bfd_boolean bfd_coff_set_symbol_class + (bfd *, struct bfd_symbol *, unsigned int); + +extern bfd_boolean bfd_m68k_coff_create_embedded_relocs + (bfd *, struct bfd_link_info *, struct bfd_section *, struct bfd_section *, char **); + +/* ARM VFP11 erratum workaround support. */ +typedef enum +{ + BFD_ARM_VFP11_FIX_DEFAULT, + BFD_ARM_VFP11_FIX_NONE, + BFD_ARM_VFP11_FIX_SCALAR, + BFD_ARM_VFP11_FIX_VECTOR +} bfd_arm_vfp11_fix; + +extern void bfd_elf32_arm_init_maps + (bfd *); + +extern void bfd_elf32_arm_set_vfp11_fix + (bfd *, struct bfd_link_info *); + +extern void bfd_elf32_arm_set_cortex_a8_fix + (bfd *, struct bfd_link_info *); + +extern bfd_boolean bfd_elf32_arm_vfp11_erratum_scan + (bfd *, struct bfd_link_info *); + +extern void bfd_elf32_arm_vfp11_fix_veneer_locations + (bfd *, struct bfd_link_info *); + +/* ARM Interworking support. Called from linker. */ +extern bfd_boolean bfd_arm_allocate_interworking_sections + (struct bfd_link_info *); + +extern bfd_boolean bfd_arm_process_before_allocation + (bfd *, struct bfd_link_info *, int); + +extern bfd_boolean bfd_arm_get_bfd_for_interworking + (bfd *, struct bfd_link_info *); + +/* PE ARM Interworking support. Called from linker. */ +extern bfd_boolean bfd_arm_pe_allocate_interworking_sections + (struct bfd_link_info *); + +extern bfd_boolean bfd_arm_pe_process_before_allocation + (bfd *, struct bfd_link_info *, int); + +extern bfd_boolean bfd_arm_pe_get_bfd_for_interworking + (bfd *, struct bfd_link_info *); + +/* ELF ARM Interworking support. Called from linker. */ +extern bfd_boolean bfd_elf32_arm_allocate_interworking_sections + (struct bfd_link_info *); + +extern bfd_boolean bfd_elf32_arm_process_before_allocation + (bfd *, struct bfd_link_info *); + +void bfd_elf32_arm_set_target_relocs + (bfd *, struct bfd_link_info *, int, char *, int, int, bfd_arm_vfp11_fix, + int, int, int, int, int); + +extern bfd_boolean bfd_elf32_arm_get_bfd_for_interworking + (bfd *, struct bfd_link_info *); + +extern bfd_boolean bfd_elf32_arm_add_glue_sections_to_bfd + (bfd *, struct bfd_link_info *); + +/* ELF ARM mapping symbol support */ +#define BFD_ARM_SPECIAL_SYM_TYPE_MAP (1 << 0) +#define BFD_ARM_SPECIAL_SYM_TYPE_TAG (1 << 1) +#define BFD_ARM_SPECIAL_SYM_TYPE_OTHER (1 << 2) +#define BFD_ARM_SPECIAL_SYM_TYPE_ANY (~0) +extern bfd_boolean bfd_is_arm_special_symbol_name + (const char * name, int type); + +extern void bfd_elf32_arm_set_byteswap_code (struct bfd_link_info *, int); + +/* ARM Note section processing. */ +extern bfd_boolean bfd_arm_merge_machines + (bfd *, bfd *); + +extern bfd_boolean bfd_arm_update_notes + (bfd *, const char *); + +extern unsigned int bfd_arm_get_mach_from_notes + (bfd *, const char *); + +/* ARM stub generation support. Called from the linker. */ +extern int elf32_arm_setup_section_lists + (bfd *, struct bfd_link_info *); +extern void elf32_arm_next_input_section + (struct bfd_link_info *, struct bfd_section *); +extern bfd_boolean elf32_arm_size_stubs + (bfd *, bfd *, struct bfd_link_info *, bfd_signed_vma, + struct bfd_section * (*) (const char *, struct bfd_section *, unsigned int), + void (*) (void)); +extern bfd_boolean elf32_arm_build_stubs + (struct bfd_link_info *); + +/* ARM unwind section editing support. */ +extern bfd_boolean elf32_arm_fix_exidx_coverage +(struct bfd_section **, unsigned int, struct bfd_link_info *, bfd_boolean); + +/* C6x unwind section editing support. */ +extern bfd_boolean elf32_tic6x_fix_exidx_coverage +(struct bfd_section **, unsigned int, struct bfd_link_info *, bfd_boolean); + +/* PowerPC @tls opcode transform/validate. */ +extern unsigned int _bfd_elf_ppc_at_tls_transform + (unsigned int, unsigned int); +/* PowerPC @tprel opcode transform/validate. */ +extern unsigned int _bfd_elf_ppc_at_tprel_transform + (unsigned int, unsigned int); + +extern void bfd_elf64_aarch64_init_maps + (bfd *); + +extern void bfd_elf32_aarch64_init_maps + (bfd *); + +extern void bfd_elf64_aarch64_set_options + (bfd *, struct bfd_link_info *, int, int, int); + +extern void bfd_elf32_aarch64_set_options + (bfd *, struct bfd_link_info *, int, int, int); + +/* ELF AArch64 mapping symbol support. */ +#define BFD_AARCH64_SPECIAL_SYM_TYPE_MAP (1 << 0) +#define BFD_AARCH64_SPECIAL_SYM_TYPE_TAG (1 << 1) +#define BFD_AARCH64_SPECIAL_SYM_TYPE_OTHER (1 << 2) +#define BFD_AARCH64_SPECIAL_SYM_TYPE_ANY (~0) +extern bfd_boolean bfd_is_aarch64_special_symbol_name + (const char * name, int type); + +/* AArch64 stub generation support for ELF64. Called from the linker. */ +extern int elf64_aarch64_setup_section_lists + (bfd *, struct bfd_link_info *); +extern void elf64_aarch64_next_input_section + (struct bfd_link_info *, struct bfd_section *); +extern bfd_boolean elf64_aarch64_size_stubs + (bfd *, bfd *, struct bfd_link_info *, bfd_signed_vma, + struct bfd_section * (*) (const char *, struct bfd_section *), + void (*) (void)); +extern bfd_boolean elf64_aarch64_build_stubs + (struct bfd_link_info *); +/* AArch64 stub generation support for ELF32. Called from the linker. */ +extern int elf32_aarch64_setup_section_lists + (bfd *, struct bfd_link_info *); +extern void elf32_aarch64_next_input_section + (struct bfd_link_info *, struct bfd_section *); +extern bfd_boolean elf32_aarch64_size_stubs + (bfd *, bfd *, struct bfd_link_info *, bfd_signed_vma, + struct bfd_section * (*) (const char *, struct bfd_section *), + void (*) (void)); +extern bfd_boolean elf32_aarch64_build_stubs + (struct bfd_link_info *); + + +/* TI COFF load page support. */ +extern void bfd_ticoff_set_section_load_page + (struct bfd_section *, int); + +extern int bfd_ticoff_get_section_load_page + (struct bfd_section *); + +/* H8/300 functions. */ +extern bfd_vma bfd_h8300_pad_address + (bfd *, bfd_vma); + +/* IA64 Itanium code generation. Called from linker. */ +extern void bfd_elf32_ia64_after_parse + (int); + +extern void bfd_elf64_ia64_after_parse + (int); + +/* This structure is used for a comdat section, as in PE. A comdat + section is associated with a particular symbol. When the linker + sees a comdat section, it keeps only one of the sections with a + given name and associated with a given symbol. */ + +struct coff_comdat_info +{ + /* The name of the symbol associated with a comdat section. */ + const char *name; + + /* The local symbol table index of the symbol associated with a + comdat section. This is only meaningful to the object file format + specific code; it is not an index into the list returned by + bfd_canonicalize_symtab. */ + long symbol; +}; + +extern struct coff_comdat_info * bfd_coff_get_comdat_section + (bfd *, struct bfd_section *); +/* Extracted from init.c. */ +void bfd_init (void); + +/* Extracted from opncls.c. */ +extern unsigned int bfd_use_reserved_id; +bfd *bfd_fopen (const char *filename, const char *target, + const char *mode, int fd); + +bfd *bfd_openr (const char *filename, const char *target); + +bfd *bfd_fdopenr (const char *filename, const char *target, int fd); + +bfd *bfd_openstreamr (const char * filename, const char * target, void * stream); + +bfd *bfd_openr_iovec (const char *filename, const char *target, + void *(*open_func) (struct bfd *nbfd, + void *open_closure), + void *open_closure, + file_ptr (*pread_func) (struct bfd *nbfd, + void *stream, + void *buf, + file_ptr nbytes, + file_ptr offset), + int (*close_func) (struct bfd *nbfd, + void *stream), + int (*stat_func) (struct bfd *abfd, + void *stream, + struct stat *sb)); + +bfd *bfd_openw (const char *filename, const char *target); + +bfd_boolean bfd_close (bfd *abfd); + +bfd_boolean bfd_close_all_done (bfd *); + +bfd *bfd_create (const char *filename, bfd *templ); + +bfd_boolean bfd_make_writable (bfd *abfd); + +bfd_boolean bfd_make_readable (bfd *abfd); + +void *bfd_alloc (bfd *abfd, bfd_size_type wanted); + +void *bfd_zalloc (bfd *abfd, bfd_size_type wanted); + +unsigned long bfd_calc_gnu_debuglink_crc32 + (unsigned long crc, const unsigned char *buf, bfd_size_type len); + +char *bfd_get_debug_link_info (bfd *abfd, unsigned long *crc32_out); + +char *bfd_get_alt_debug_link_info (bfd * abfd, + bfd_size_type *buildid_len, + bfd_byte **buildid_out); + +char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir); + +char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir); + +struct bfd_section *bfd_create_gnu_debuglink_section + (bfd *abfd, const char *filename); + +bfd_boolean bfd_fill_in_gnu_debuglink_section + (bfd *abfd, struct bfd_section *sect, const char *filename); + +/* Extracted from libbfd.c. */ + +/* Byte swapping macros for user section data. */ + +#define bfd_put_8(abfd, val, ptr) \ + ((void) (*((unsigned char *) (ptr)) = (val) & 0xff)) +#define bfd_put_signed_8 \ + bfd_put_8 +#define bfd_get_8(abfd, ptr) \ + (*(const unsigned char *) (ptr) & 0xff) +#define bfd_get_signed_8(abfd, ptr) \ + (((*(const unsigned char *) (ptr) & 0xff) ^ 0x80) - 0x80) + +#define bfd_put_16(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx16, ((val),(ptr))) +#define bfd_put_signed_16 \ + bfd_put_16 +#define bfd_get_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx16, (ptr)) +#define bfd_get_signed_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_16, (ptr)) + +#define bfd_put_32(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx32, ((val),(ptr))) +#define bfd_put_signed_32 \ + bfd_put_32 +#define bfd_get_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx32, (ptr)) +#define bfd_get_signed_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_32, (ptr)) + +#define bfd_put_64(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx64, ((val), (ptr))) +#define bfd_put_signed_64 \ + bfd_put_64 +#define bfd_get_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx64, (ptr)) +#define bfd_get_signed_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_64, (ptr)) + +#define bfd_get(bits, abfd, ptr) \ + ((bits) == 8 ? (bfd_vma) bfd_get_8 (abfd, ptr) \ + : (bits) == 16 ? bfd_get_16 (abfd, ptr) \ + : (bits) == 32 ? bfd_get_32 (abfd, ptr) \ + : (bits) == 64 ? bfd_get_64 (abfd, ptr) \ + : (abort (), (bfd_vma) - 1)) + +#define bfd_put(bits, abfd, val, ptr) \ + ((bits) == 8 ? bfd_put_8 (abfd, val, ptr) \ + : (bits) == 16 ? bfd_put_16 (abfd, val, ptr) \ + : (bits) == 32 ? bfd_put_32 (abfd, val, ptr) \ + : (bits) == 64 ? bfd_put_64 (abfd, val, ptr) \ + : (abort (), (void) 0)) + + +/* Byte swapping macros for file header data. */ + +#define bfd_h_put_8(abfd, val, ptr) \ + bfd_put_8 (abfd, val, ptr) +#define bfd_h_put_signed_8(abfd, val, ptr) \ + bfd_put_8 (abfd, val, ptr) +#define bfd_h_get_8(abfd, ptr) \ + bfd_get_8 (abfd, ptr) +#define bfd_h_get_signed_8(abfd, ptr) \ + bfd_get_signed_8 (abfd, ptr) + +#define bfd_h_put_16(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx16, (val, ptr)) +#define bfd_h_put_signed_16 \ + bfd_h_put_16 +#define bfd_h_get_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx16, (ptr)) +#define bfd_h_get_signed_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr)) + +#define bfd_h_put_32(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx32, (val, ptr)) +#define bfd_h_put_signed_32 \ + bfd_h_put_32 +#define bfd_h_get_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx32, (ptr)) +#define bfd_h_get_signed_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr)) + +#define bfd_h_put_64(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx64, (val, ptr)) +#define bfd_h_put_signed_64 \ + bfd_h_put_64 +#define bfd_h_get_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx64, (ptr)) +#define bfd_h_get_signed_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr)) + +/* Aliases for the above, which should eventually go away. */ + +#define H_PUT_64 bfd_h_put_64 +#define H_PUT_32 bfd_h_put_32 +#define H_PUT_16 bfd_h_put_16 +#define H_PUT_8 bfd_h_put_8 +#define H_PUT_S64 bfd_h_put_signed_64 +#define H_PUT_S32 bfd_h_put_signed_32 +#define H_PUT_S16 bfd_h_put_signed_16 +#define H_PUT_S8 bfd_h_put_signed_8 +#define H_GET_64 bfd_h_get_64 +#define H_GET_32 bfd_h_get_32 +#define H_GET_16 bfd_h_get_16 +#define H_GET_8 bfd_h_get_8 +#define H_GET_S64 bfd_h_get_signed_64 +#define H_GET_S32 bfd_h_get_signed_32 +#define H_GET_S16 bfd_h_get_signed_16 +#define H_GET_S8 bfd_h_get_signed_8 + + +/* Extracted from bfdio.c. */ +long bfd_get_mtime (bfd *abfd); + +file_ptr bfd_get_size (bfd *abfd); + +void *bfd_mmap (bfd *abfd, void *addr, bfd_size_type len, + int prot, int flags, file_ptr offset, + void **map_addr, bfd_size_type *map_len); + +/* Extracted from bfdwin.c. */ +/* Extracted from section.c. */ +typedef struct bfd_section +{ + /* The name of the section; the name isn't a copy, the pointer is + the same as that passed to bfd_make_section. */ + const char *name; + + /* A unique sequence number. */ + int id; + + /* Which section in the bfd; 0..n-1 as sections are created in a bfd. */ + int index; + + /* The next section in the list belonging to the BFD, or NULL. */ + struct bfd_section *next; + + /* The previous section in the list belonging to the BFD, or NULL. */ + struct bfd_section *prev; + + /* The field flags contains attributes of the section. Some + flags are read in from the object file, and some are + synthesized from other information. */ + flagword flags; + +#define SEC_NO_FLAGS 0x000 + + /* Tells the OS to allocate space for this section when loading. + This is clear for a section containing debug information only. */ +#define SEC_ALLOC 0x001 + + /* Tells the OS to load the section from the file when loading. + This is clear for a .bss section. */ +#define SEC_LOAD 0x002 + + /* The section contains data still to be relocated, so there is + some relocation information too. */ +#define SEC_RELOC 0x004 + + /* A signal to the OS that the section contains read only data. */ +#define SEC_READONLY 0x008 + + /* The section contains code only. */ +#define SEC_CODE 0x010 + + /* The section contains data only. */ +#define SEC_DATA 0x020 + + /* The section will reside in ROM. */ +#define SEC_ROM 0x040 + + /* The section contains constructor information. This section + type is used by the linker to create lists of constructors and + destructors used by <>. When a back end sees a symbol + which should be used in a constructor list, it creates a new + section for the type of name (e.g., <<__CTOR_LIST__>>), attaches + the symbol to it, and builds a relocation. To build the lists + of constructors, all the linker has to do is catenate all the + sections called <<__CTOR_LIST__>> and relocate the data + contained within - exactly the operations it would peform on + standard data. */ +#define SEC_CONSTRUCTOR 0x080 + + /* The section has contents - a data section could be + <> | <>; a debug section could be + <> */ +#define SEC_HAS_CONTENTS 0x100 + + /* An instruction to the linker to not output the section + even if it has information which would normally be written. */ +#define SEC_NEVER_LOAD 0x200 + + /* The section contains thread local data. */ +#define SEC_THREAD_LOCAL 0x400 + + /* The section has GOT references. This flag is only for the + linker, and is currently only used by the elf32-hppa back end. + It will be set if global offset table references were detected + in this section, which indicate to the linker that the section + contains PIC code, and must be handled specially when doing a + static link. */ +#define SEC_HAS_GOT_REF 0x800 + + /* The section contains common symbols (symbols may be defined + multiple times, the value of a symbol is the amount of + space it requires, and the largest symbol value is the one + used). Most targets have exactly one of these (which we + translate to bfd_com_section_ptr), but ECOFF has two. */ +#define SEC_IS_COMMON 0x1000 + + /* The section contains only debugging information. For + example, this is set for ELF .debug and .stab sections. + strip tests this flag to see if a section can be + discarded. */ +#define SEC_DEBUGGING 0x2000 + + /* The contents of this section are held in memory pointed to + by the contents field. This is checked by bfd_get_section_contents, + and the data is retrieved from memory if appropriate. */ +#define SEC_IN_MEMORY 0x4000 + + /* The contents of this section are to be excluded by the + linker for executable and shared objects unless those + objects are to be further relocated. */ +#define SEC_EXCLUDE 0x8000 + + /* The contents of this section are to be sorted based on the sum of + the symbol and addend values specified by the associated relocation + entries. Entries without associated relocation entries will be + appended to the end of the section in an unspecified order. */ +#define SEC_SORT_ENTRIES 0x10000 + + /* When linking, duplicate sections of the same name should be + discarded, rather than being combined into a single section as + is usually done. This is similar to how common symbols are + handled. See SEC_LINK_DUPLICATES below. */ +#define SEC_LINK_ONCE 0x20000 + + /* If SEC_LINK_ONCE is set, this bitfield describes how the linker + should handle duplicate sections. */ +#define SEC_LINK_DUPLICATES 0xc0000 + + /* This value for SEC_LINK_DUPLICATES means that duplicate + sections with the same name should simply be discarded. */ +#define SEC_LINK_DUPLICATES_DISCARD 0x0 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if there are any duplicate sections, although + it should still only link one copy. */ +#define SEC_LINK_DUPLICATES_ONE_ONLY 0x40000 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if any duplicate sections are a different size. */ +#define SEC_LINK_DUPLICATES_SAME_SIZE 0x80000 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if any duplicate sections contain different + contents. */ +#define SEC_LINK_DUPLICATES_SAME_CONTENTS \ + (SEC_LINK_DUPLICATES_ONE_ONLY | SEC_LINK_DUPLICATES_SAME_SIZE) + + /* This section was created by the linker as part of dynamic + relocation or other arcane processing. It is skipped when + going through the first-pass output, trusting that someone + else up the line will take care of it later. */ +#define SEC_LINKER_CREATED 0x100000 + + /* This section should not be subject to garbage collection. + Also set to inform the linker that this section should not be + listed in the link map as discarded. */ +#define SEC_KEEP 0x200000 + + /* This section contains "short" data, and should be placed + "near" the GP. */ +#define SEC_SMALL_DATA 0x400000 + + /* Attempt to merge identical entities in the section. + Entity size is given in the entsize field. */ +#define SEC_MERGE 0x800000 + + /* If given with SEC_MERGE, entities to merge are zero terminated + strings where entsize specifies character size instead of fixed + size entries. */ +#define SEC_STRINGS 0x1000000 + + /* This section contains data about section groups. */ +#define SEC_GROUP 0x2000000 + + /* The section is a COFF shared library section. This flag is + only for the linker. If this type of section appears in + the input file, the linker must copy it to the output file + without changing the vma or size. FIXME: Although this + was originally intended to be general, it really is COFF + specific (and the flag was renamed to indicate this). It + might be cleaner to have some more general mechanism to + allow the back end to control what the linker does with + sections. */ +#define SEC_COFF_SHARED_LIBRARY 0x4000000 + + /* This input section should be copied to output in reverse order + as an array of pointers. This is for ELF linker internal use + only. */ +#define SEC_ELF_REVERSE_COPY 0x4000000 + + /* This section contains data which may be shared with other + executables or shared objects. This is for COFF only. */ +#define SEC_COFF_SHARED 0x8000000 + + /* When a section with this flag is being linked, then if the size of + the input section is less than a page, it should not cross a page + boundary. If the size of the input section is one page or more, + it should be aligned on a page boundary. This is for TI + TMS320C54X only. */ +#define SEC_TIC54X_BLOCK 0x10000000 + + /* Conditionally link this section; do not link if there are no + references found to any symbol in the section. This is for TI + TMS320C54X only. */ +#define SEC_TIC54X_CLINK 0x20000000 + + /* Indicate that section has the no read flag set. This happens + when memory read flag isn't set. */ +#define SEC_COFF_NOREAD 0x40000000 + + /* End of section flags. */ + + /* Some internal packed boolean fields. */ + + /* See the vma field. */ + unsigned int user_set_vma : 1; + + /* A mark flag used by some of the linker backends. */ + unsigned int linker_mark : 1; + + /* Another mark flag used by some of the linker backends. Set for + output sections that have an input section. */ + unsigned int linker_has_input : 1; + + /* Mark flag used by some linker backends for garbage collection. */ + unsigned int gc_mark : 1; + + /* Section compression status. */ + unsigned int compress_status : 2; +#define COMPRESS_SECTION_NONE 0 +#define COMPRESS_SECTION_DONE 1 +#define DECOMPRESS_SECTION_SIZED 2 + + /* The following flags are used by the ELF linker. */ + + /* Mark sections which have been allocated to segments. */ + unsigned int segment_mark : 1; + + /* Type of sec_info information. */ + unsigned int sec_info_type:3; +#define SEC_INFO_TYPE_NONE 0 +#define SEC_INFO_TYPE_STABS 1 +#define SEC_INFO_TYPE_MERGE 2 +#define SEC_INFO_TYPE_EH_FRAME 3 +#define SEC_INFO_TYPE_JUST_SYMS 4 + + /* Nonzero if this section uses RELA relocations, rather than REL. */ + unsigned int use_rela_p:1; + + /* Bits used by various backends. The generic code doesn't touch + these fields. */ + + unsigned int sec_flg0:1; + unsigned int sec_flg1:1; + unsigned int sec_flg2:1; + unsigned int sec_flg3:1; + unsigned int sec_flg4:1; + unsigned int sec_flg5:1; + + /* End of internal packed boolean fields. */ + + /* The virtual memory address of the section - where it will be + at run time. The symbols are relocated against this. The + user_set_vma flag is maintained by bfd; if it's not set, the + backend can assign addresses (for example, in <>, where + the default address for <<.data>> is dependent on the specific + target and various flags). */ + bfd_vma vma; + + /* The load address of the section - where it would be in a + rom image; really only used for writing section header + information. */ + bfd_vma lma; + + /* The size of the section in octets, as it will be output. + Contains a value even if the section has no contents (e.g., the + size of <<.bss>>). */ + bfd_size_type size; + + /* For input sections, the original size on disk of the section, in + octets. This field should be set for any section whose size is + changed by linker relaxation. It is required for sections where + the linker relaxation scheme doesn't cache altered section and + reloc contents (stabs, eh_frame, SEC_MERGE, some coff relaxing + targets), and thus the original size needs to be kept to read the + section multiple times. For output sections, rawsize holds the + section size calculated on a previous linker relaxation pass. */ + bfd_size_type rawsize; + + /* The compressed size of the section in octets. */ + bfd_size_type compressed_size; + + /* Relaxation table. */ + struct relax_table *relax; + + /* Count of used relaxation table entries. */ + int relax_count; + + + /* If this section is going to be output, then this value is the + offset in *bytes* into the output section of the first byte in the + input section (byte ==> smallest addressable unit on the + target). In most cases, if this was going to start at the + 100th octet (8-bit quantity) in the output section, this value + would be 100. However, if the target byte size is 16 bits + (bfd_octets_per_byte is "2"), this value would be 50. */ + bfd_vma output_offset; + + /* The output section through which to map on output. */ + struct bfd_section *output_section; + + /* The alignment requirement of the section, as an exponent of 2 - + e.g., 3 aligns to 2^3 (or 8). */ + unsigned int alignment_power; + + /* If an input section, a pointer to a vector of relocation + records for the data in this section. */ + struct reloc_cache_entry *relocation; + + /* If an output section, a pointer to a vector of pointers to + relocation records for the data in this section. */ + struct reloc_cache_entry **orelocation; + + /* The number of relocation records in one of the above. */ + unsigned reloc_count; + + /* Information below is back end specific - and not always used + or updated. */ + + /* File position of section data. */ + file_ptr filepos; + + /* File position of relocation info. */ + file_ptr rel_filepos; + + /* File position of line data. */ + file_ptr line_filepos; + + /* Pointer to data for applications. */ + void *userdata; + + /* If the SEC_IN_MEMORY flag is set, this points to the actual + contents. */ + unsigned char *contents; + + /* Attached line number information. */ + alent *lineno; + + /* Number of line number records. */ + unsigned int lineno_count; + + /* Entity size for merging purposes. */ + unsigned int entsize; + + /* Points to the kept section if this section is a link-once section, + and is discarded. */ + struct bfd_section *kept_section; + + /* When a section is being output, this value changes as more + linenumbers are written out. */ + file_ptr moving_line_filepos; + + /* What the section number is in the target world. */ + int target_index; + + void *used_by_bfd; + + /* If this is a constructor section then here is a list of the + relocations created to relocate items within it. */ + struct relent_chain *constructor_chain; + + /* The BFD which owns the section. */ + bfd *owner; + + /* A symbol which points at this section only. */ + struct bfd_symbol *symbol; + struct bfd_symbol **symbol_ptr_ptr; + + /* Early in the link process, map_head and map_tail are used to build + a list of input sections attached to an output section. Later, + output sections use these fields for a list of bfd_link_order + structs. */ + union { + struct bfd_link_order *link_order; + struct bfd_section *s; + } map_head, map_tail; +} asection; + +/* Relax table contains information about instructions which can + be removed by relaxation -- replacing a long address with a + short address. */ +struct relax_table { + /* Address where bytes may be deleted. */ + bfd_vma addr; + + /* Number of bytes to be deleted. */ + int size; +}; + +/* Note: the following are provided as inline functions rather than macros + because not all callers use the return value. A macro implementation + would use a comma expression, eg: "((ptr)->foo = val, TRUE)" and some + compilers will complain about comma expressions that have no effect. */ +static inline bfd_boolean +bfd_set_section_userdata (bfd * abfd ATTRIBUTE_UNUSED, asection * ptr, void * val) +{ + ptr->userdata = val; + return TRUE; +} + +static inline bfd_boolean +bfd_set_section_vma (bfd * abfd ATTRIBUTE_UNUSED, asection * ptr, bfd_vma val) +{ + ptr->vma = ptr->lma = val; + ptr->user_set_vma = TRUE; + return TRUE; +} + +static inline bfd_boolean +bfd_set_section_alignment (bfd * abfd ATTRIBUTE_UNUSED, asection * ptr, unsigned int val) +{ + ptr->alignment_power = val; + return TRUE; +} + +/* These sections are global, and are managed by BFD. The application + and target back end are not permitted to change the values in + these sections. */ +extern asection _bfd_std_section[4]; + +#define BFD_ABS_SECTION_NAME "*ABS*" +#define BFD_UND_SECTION_NAME "*UND*" +#define BFD_COM_SECTION_NAME "*COM*" +#define BFD_IND_SECTION_NAME "*IND*" + +/* Pointer to the common section. */ +#define bfd_com_section_ptr (&_bfd_std_section[0]) +/* Pointer to the undefined section. */ +#define bfd_und_section_ptr (&_bfd_std_section[1]) +/* Pointer to the absolute section. */ +#define bfd_abs_section_ptr (&_bfd_std_section[2]) +/* Pointer to the indirect section. */ +#define bfd_ind_section_ptr (&_bfd_std_section[3]) + +#define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr) +#define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr) +#define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr) + +#define bfd_is_const_section(SEC) \ + ( ((SEC) == bfd_abs_section_ptr) \ + || ((SEC) == bfd_und_section_ptr) \ + || ((SEC) == bfd_com_section_ptr) \ + || ((SEC) == bfd_ind_section_ptr)) + +/* Macros to handle insertion and deletion of a bfd's sections. These + only handle the list pointers, ie. do not adjust section_count, + target_index etc. */ +#define bfd_section_list_remove(ABFD, S) \ + do \ + { \ + asection *_s = S; \ + asection *_next = _s->next; \ + asection *_prev = _s->prev; \ + if (_prev) \ + _prev->next = _next; \ + else \ + (ABFD)->sections = _next; \ + if (_next) \ + _next->prev = _prev; \ + else \ + (ABFD)->section_last = _prev; \ + } \ + while (0) +#define bfd_section_list_append(ABFD, S) \ + do \ + { \ + asection *_s = S; \ + bfd *_abfd = ABFD; \ + _s->next = NULL; \ + if (_abfd->section_last) \ + { \ + _s->prev = _abfd->section_last; \ + _abfd->section_last->next = _s; \ + } \ + else \ + { \ + _s->prev = NULL; \ + _abfd->sections = _s; \ + } \ + _abfd->section_last = _s; \ + } \ + while (0) +#define bfd_section_list_prepend(ABFD, S) \ + do \ + { \ + asection *_s = S; \ + bfd *_abfd = ABFD; \ + _s->prev = NULL; \ + if (_abfd->sections) \ + { \ + _s->next = _abfd->sections; \ + _abfd->sections->prev = _s; \ + } \ + else \ + { \ + _s->next = NULL; \ + _abfd->section_last = _s; \ + } \ + _abfd->sections = _s; \ + } \ + while (0) +#define bfd_section_list_insert_after(ABFD, A, S) \ + do \ + { \ + asection *_a = A; \ + asection *_s = S; \ + asection *_next = _a->next; \ + _s->next = _next; \ + _s->prev = _a; \ + _a->next = _s; \ + if (_next) \ + _next->prev = _s; \ + else \ + (ABFD)->section_last = _s; \ + } \ + while (0) +#define bfd_section_list_insert_before(ABFD, B, S) \ + do \ + { \ + asection *_b = B; \ + asection *_s = S; \ + asection *_prev = _b->prev; \ + _s->prev = _prev; \ + _s->next = _b; \ + _b->prev = _s; \ + if (_prev) \ + _prev->next = _s; \ + else \ + (ABFD)->sections = _s; \ + } \ + while (0) +#define bfd_section_removed_from_list(ABFD, S) \ + ((S)->next == NULL ? (ABFD)->section_last != (S) : (S)->next->prev != (S)) + +#define BFD_FAKE_SECTION(SEC, FLAGS, SYM, NAME, IDX) \ + /* name, id, index, next, prev, flags, user_set_vma, */ \ + { NAME, IDX, 0, NULL, NULL, FLAGS, 0, \ + \ + /* linker_mark, linker_has_input, gc_mark, decompress_status, */ \ + 0, 0, 1, 0, \ + \ + /* segment_mark, sec_info_type, use_rela_p, */ \ + 0, 0, 0, \ + \ + /* sec_flg0, sec_flg1, sec_flg2, sec_flg3, sec_flg4, sec_flg5, */ \ + 0, 0, 0, 0, 0, 0, \ + \ + /* vma, lma, size, rawsize, compressed_size, relax, relax_count, */ \ + 0, 0, 0, 0, 0, 0, 0, \ + \ + /* output_offset, output_section, alignment_power, */ \ + 0, &SEC, 0, \ + \ + /* relocation, orelocation, reloc_count, filepos, rel_filepos, */ \ + NULL, NULL, 0, 0, 0, \ + \ + /* line_filepos, userdata, contents, lineno, lineno_count, */ \ + 0, NULL, NULL, NULL, 0, \ + \ + /* entsize, kept_section, moving_line_filepos, */ \ + 0, NULL, 0, \ + \ + /* target_index, used_by_bfd, constructor_chain, owner, */ \ + 0, NULL, NULL, NULL, \ + \ + /* symbol, symbol_ptr_ptr, */ \ + (struct bfd_symbol *) SYM, &SEC.symbol, \ + \ + /* map_head, map_tail */ \ + { NULL }, { NULL } \ + } + +void bfd_section_list_clear (bfd *); + +asection *bfd_get_section_by_name (bfd *abfd, const char *name); + +asection *bfd_get_next_section_by_name (asection *sec); + +asection *bfd_get_linker_section (bfd *abfd, const char *name); + +asection *bfd_get_section_by_name_if + (bfd *abfd, + const char *name, + bfd_boolean (*func) (bfd *abfd, asection *sect, void *obj), + void *obj); + +char *bfd_get_unique_section_name + (bfd *abfd, const char *templat, int *count); + +asection *bfd_make_section_old_way (bfd *abfd, const char *name); + +asection *bfd_make_section_anyway_with_flags + (bfd *abfd, const char *name, flagword flags); + +asection *bfd_make_section_anyway (bfd *abfd, const char *name); + +asection *bfd_make_section_with_flags + (bfd *, const char *name, flagword flags); + +asection *bfd_make_section (bfd *, const char *name); + +bfd_boolean bfd_set_section_flags + (bfd *abfd, asection *sec, flagword flags); + +void bfd_rename_section + (bfd *abfd, asection *sec, const char *newname); + +void bfd_map_over_sections + (bfd *abfd, + void (*func) (bfd *abfd, asection *sect, void *obj), + void *obj); + +asection *bfd_sections_find_if + (bfd *abfd, + bfd_boolean (*operation) (bfd *abfd, asection *sect, void *obj), + void *obj); + +bfd_boolean bfd_set_section_size + (bfd *abfd, asection *sec, bfd_size_type val); + +bfd_boolean bfd_set_section_contents + (bfd *abfd, asection *section, const void *data, + file_ptr offset, bfd_size_type count); + +bfd_boolean bfd_get_section_contents + (bfd *abfd, asection *section, void *location, file_ptr offset, + bfd_size_type count); + +bfd_boolean bfd_malloc_and_get_section + (bfd *abfd, asection *section, bfd_byte **buf); + +bfd_boolean bfd_copy_private_section_data + (bfd *ibfd, asection *isec, bfd *obfd, asection *osec); + +#define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \ + BFD_SEND (obfd, _bfd_copy_private_section_data, \ + (ibfd, isection, obfd, osection)) +bfd_boolean bfd_generic_is_group_section (bfd *, const asection *sec); + +bfd_boolean bfd_generic_discard_group (bfd *abfd, asection *group); + +/* Extracted from archures.c. */ +enum bfd_architecture +{ + bfd_arch_unknown, /* File arch not known. */ + bfd_arch_obscure, /* Arch known, not one of these. */ + bfd_arch_m68k, /* Motorola 68xxx */ +#define bfd_mach_m68000 1 +#define bfd_mach_m68008 2 +#define bfd_mach_m68010 3 +#define bfd_mach_m68020 4 +#define bfd_mach_m68030 5 +#define bfd_mach_m68040 6 +#define bfd_mach_m68060 7 +#define bfd_mach_cpu32 8 +#define bfd_mach_fido 9 +#define bfd_mach_mcf_isa_a_nodiv 10 +#define bfd_mach_mcf_isa_a 11 +#define bfd_mach_mcf_isa_a_mac 12 +#define bfd_mach_mcf_isa_a_emac 13 +#define bfd_mach_mcf_isa_aplus 14 +#define bfd_mach_mcf_isa_aplus_mac 15 +#define bfd_mach_mcf_isa_aplus_emac 16 +#define bfd_mach_mcf_isa_b_nousp 17 +#define bfd_mach_mcf_isa_b_nousp_mac 18 +#define bfd_mach_mcf_isa_b_nousp_emac 19 +#define bfd_mach_mcf_isa_b 20 +#define bfd_mach_mcf_isa_b_mac 21 +#define bfd_mach_mcf_isa_b_emac 22 +#define bfd_mach_mcf_isa_b_float 23 +#define bfd_mach_mcf_isa_b_float_mac 24 +#define bfd_mach_mcf_isa_b_float_emac 25 +#define bfd_mach_mcf_isa_c 26 +#define bfd_mach_mcf_isa_c_mac 27 +#define bfd_mach_mcf_isa_c_emac 28 +#define bfd_mach_mcf_isa_c_nodiv 29 +#define bfd_mach_mcf_isa_c_nodiv_mac 30 +#define bfd_mach_mcf_isa_c_nodiv_emac 31 + bfd_arch_vax, /* DEC Vax */ + bfd_arch_i960, /* Intel 960 */ + /* The order of the following is important. + lower number indicates a machine type that + only accepts a subset of the instructions + available to machines with higher numbers. + The exception is the "ca", which is + incompatible with all other machines except + "core". */ + +#define bfd_mach_i960_core 1 +#define bfd_mach_i960_ka_sa 2 +#define bfd_mach_i960_kb_sb 3 +#define bfd_mach_i960_mc 4 +#define bfd_mach_i960_xa 5 +#define bfd_mach_i960_ca 6 +#define bfd_mach_i960_jx 7 +#define bfd_mach_i960_hx 8 + + bfd_arch_or32, /* OpenRISC 32 */ + + bfd_arch_sparc, /* SPARC */ +#define bfd_mach_sparc 1 +/* The difference between v8plus and v9 is that v9 is a true 64 bit env. */ +#define bfd_mach_sparc_sparclet 2 +#define bfd_mach_sparc_sparclite 3 +#define bfd_mach_sparc_v8plus 4 +#define bfd_mach_sparc_v8plusa 5 /* with ultrasparc add'ns. */ +#define bfd_mach_sparc_sparclite_le 6 +#define bfd_mach_sparc_v9 7 +#define bfd_mach_sparc_v9a 8 /* with ultrasparc add'ns. */ +#define bfd_mach_sparc_v8plusb 9 /* with cheetah add'ns. */ +#define bfd_mach_sparc_v9b 10 /* with cheetah add'ns. */ +/* Nonzero if MACH has the v9 instruction set. */ +#define bfd_mach_sparc_v9_p(mach) \ + ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9b \ + && (mach) != bfd_mach_sparc_sparclite_le) +/* Nonzero if MACH is a 64 bit sparc architecture. */ +#define bfd_mach_sparc_64bit_p(mach) \ + ((mach) >= bfd_mach_sparc_v9 && (mach) != bfd_mach_sparc_v8plusb) + bfd_arch_spu, /* PowerPC SPU */ +#define bfd_mach_spu 256 + bfd_arch_mips, /* MIPS Rxxxx */ +#define bfd_mach_mips3000 3000 +#define bfd_mach_mips3900 3900 +#define bfd_mach_mips4000 4000 +#define bfd_mach_mips4010 4010 +#define bfd_mach_mips4100 4100 +#define bfd_mach_mips4111 4111 +#define bfd_mach_mips4120 4120 +#define bfd_mach_mips4300 4300 +#define bfd_mach_mips4400 4400 +#define bfd_mach_mips4600 4600 +#define bfd_mach_mips4650 4650 +#define bfd_mach_mips5000 5000 +#define bfd_mach_mips5400 5400 +#define bfd_mach_mips5500 5500 +#define bfd_mach_mips5900 5900 +#define bfd_mach_mips6000 6000 +#define bfd_mach_mips7000 7000 +#define bfd_mach_mips8000 8000 +#define bfd_mach_mips9000 9000 +#define bfd_mach_mips10000 10000 +#define bfd_mach_mips12000 12000 +#define bfd_mach_mips14000 14000 +#define bfd_mach_mips16000 16000 +#define bfd_mach_mips16 16 +#define bfd_mach_mips5 5 +#define bfd_mach_mips_loongson_2e 3001 +#define bfd_mach_mips_loongson_2f 3002 +#define bfd_mach_mips_loongson_3a 3003 +#define bfd_mach_mips_sb1 12310201 /* octal 'SB', 01 */ +#define bfd_mach_mips_octeon 6501 +#define bfd_mach_mips_octeonp 6601 +#define bfd_mach_mips_octeon2 6502 +#define bfd_mach_mips_xlr 887682 /* decimal 'XLR' */ +#define bfd_mach_mipsisa32 32 +#define bfd_mach_mipsisa32r2 33 +#define bfd_mach_mipsisa64 64 +#define bfd_mach_mipsisa64r2 65 +#define bfd_mach_mips_micromips 96 + bfd_arch_i386, /* Intel 386 */ +#define bfd_mach_i386_intel_syntax (1 << 0) +#define bfd_mach_i386_i8086 (1 << 1) +#define bfd_mach_i386_i386 (1 << 2) +#define bfd_mach_x86_64 (1 << 3) +#define bfd_mach_x64_32 (1 << 4) +#define bfd_mach_i386_i386_intel_syntax (bfd_mach_i386_i386 | bfd_mach_i386_intel_syntax) +#define bfd_mach_x86_64_intel_syntax (bfd_mach_x86_64 | bfd_mach_i386_intel_syntax) +#define bfd_mach_x64_32_intel_syntax (bfd_mach_x64_32 | bfd_mach_i386_intel_syntax) + bfd_arch_l1om, /* Intel L1OM */ +#define bfd_mach_l1om (1 << 5) +#define bfd_mach_l1om_intel_syntax (bfd_mach_l1om | bfd_mach_i386_intel_syntax) + bfd_arch_k1om, /* Intel K1OM */ +#define bfd_mach_k1om (1 << 6) +#define bfd_mach_k1om_intel_syntax (bfd_mach_k1om | bfd_mach_i386_intel_syntax) +#define bfd_mach_i386_nacl (1 << 7) +#define bfd_mach_i386_i386_nacl (bfd_mach_i386_i386 | bfd_mach_i386_nacl) +#define bfd_mach_x86_64_nacl (bfd_mach_x86_64 | bfd_mach_i386_nacl) +#define bfd_mach_x64_32_nacl (bfd_mach_x64_32 | bfd_mach_i386_nacl) + bfd_arch_we32k, /* AT&T WE32xxx */ + bfd_arch_tahoe, /* CCI/Harris Tahoe */ + bfd_arch_i860, /* Intel 860 */ + bfd_arch_i370, /* IBM 360/370 Mainframes */ + bfd_arch_romp, /* IBM ROMP PC/RT */ + bfd_arch_convex, /* Convex */ + bfd_arch_m88k, /* Motorola 88xxx */ + bfd_arch_m98k, /* Motorola 98xxx */ + bfd_arch_pyramid, /* Pyramid Technology */ + bfd_arch_h8300, /* Renesas H8/300 (formerly Hitachi H8/300) */ +#define bfd_mach_h8300 1 +#define bfd_mach_h8300h 2 +#define bfd_mach_h8300s 3 +#define bfd_mach_h8300hn 4 +#define bfd_mach_h8300sn 5 +#define bfd_mach_h8300sx 6 +#define bfd_mach_h8300sxn 7 + bfd_arch_pdp11, /* DEC PDP-11 */ + bfd_arch_plugin, + bfd_arch_powerpc, /* PowerPC */ +#define bfd_mach_ppc 32 +#define bfd_mach_ppc64 64 +#define bfd_mach_ppc_403 403 +#define bfd_mach_ppc_403gc 4030 +#define bfd_mach_ppc_405 405 +#define bfd_mach_ppc_505 505 +#define bfd_mach_ppc_601 601 +#define bfd_mach_ppc_602 602 +#define bfd_mach_ppc_603 603 +#define bfd_mach_ppc_ec603e 6031 +#define bfd_mach_ppc_604 604 +#define bfd_mach_ppc_620 620 +#define bfd_mach_ppc_630 630 +#define bfd_mach_ppc_750 750 +#define bfd_mach_ppc_860 860 +#define bfd_mach_ppc_a35 35 +#define bfd_mach_ppc_rs64ii 642 +#define bfd_mach_ppc_rs64iii 643 +#define bfd_mach_ppc_7400 7400 +#define bfd_mach_ppc_e500 500 +#define bfd_mach_ppc_e500mc 5001 +#define bfd_mach_ppc_e500mc64 5005 +#define bfd_mach_ppc_e5500 5006 +#define bfd_mach_ppc_e6500 5007 +#define bfd_mach_ppc_titan 83 +#define bfd_mach_ppc_vle 84 + bfd_arch_rs6000, /* IBM RS/6000 */ +#define bfd_mach_rs6k 6000 +#define bfd_mach_rs6k_rs1 6001 +#define bfd_mach_rs6k_rsc 6003 +#define bfd_mach_rs6k_rs2 6002 + bfd_arch_hppa, /* HP PA RISC */ +#define bfd_mach_hppa10 10 +#define bfd_mach_hppa11 11 +#define bfd_mach_hppa20 20 +#define bfd_mach_hppa20w 25 + bfd_arch_d10v, /* Mitsubishi D10V */ +#define bfd_mach_d10v 1 +#define bfd_mach_d10v_ts2 2 +#define bfd_mach_d10v_ts3 3 + bfd_arch_d30v, /* Mitsubishi D30V */ + bfd_arch_dlx, /* DLX */ + bfd_arch_m68hc11, /* Motorola 68HC11 */ + bfd_arch_m68hc12, /* Motorola 68HC12 */ +#define bfd_mach_m6812_default 0 +#define bfd_mach_m6812 1 +#define bfd_mach_m6812s 2 + bfd_arch_m9s12x, /* Freescale S12X */ + bfd_arch_m9s12xg, /* Freescale XGATE */ + bfd_arch_z8k, /* Zilog Z8000 */ +#define bfd_mach_z8001 1 +#define bfd_mach_z8002 2 + bfd_arch_h8500, /* Renesas H8/500 (formerly Hitachi H8/500) */ + bfd_arch_sh, /* Renesas / SuperH SH (formerly Hitachi SH) */ +#define bfd_mach_sh 1 +#define bfd_mach_sh2 0x20 +#define bfd_mach_sh_dsp 0x2d +#define bfd_mach_sh2a 0x2a +#define bfd_mach_sh2a_nofpu 0x2b +#define bfd_mach_sh2a_nofpu_or_sh4_nommu_nofpu 0x2a1 +#define bfd_mach_sh2a_nofpu_or_sh3_nommu 0x2a2 +#define bfd_mach_sh2a_or_sh4 0x2a3 +#define bfd_mach_sh2a_or_sh3e 0x2a4 +#define bfd_mach_sh2e 0x2e +#define bfd_mach_sh3 0x30 +#define bfd_mach_sh3_nommu 0x31 +#define bfd_mach_sh3_dsp 0x3d +#define bfd_mach_sh3e 0x3e +#define bfd_mach_sh4 0x40 +#define bfd_mach_sh4_nofpu 0x41 +#define bfd_mach_sh4_nommu_nofpu 0x42 +#define bfd_mach_sh4a 0x4a +#define bfd_mach_sh4a_nofpu 0x4b +#define bfd_mach_sh4al_dsp 0x4d +#define bfd_mach_sh5 0x50 + bfd_arch_alpha, /* Dec Alpha */ +#define bfd_mach_alpha_ev4 0x10 +#define bfd_mach_alpha_ev5 0x20 +#define bfd_mach_alpha_ev6 0x30 + bfd_arch_arm, /* Advanced Risc Machines ARM. */ +#define bfd_mach_arm_unknown 0 +#define bfd_mach_arm_2 1 +#define bfd_mach_arm_2a 2 +#define bfd_mach_arm_3 3 +#define bfd_mach_arm_3M 4 +#define bfd_mach_arm_4 5 +#define bfd_mach_arm_4T 6 +#define bfd_mach_arm_5 7 +#define bfd_mach_arm_5T 8 +#define bfd_mach_arm_5TE 9 +#define bfd_mach_arm_XScale 10 +#define bfd_mach_arm_ep9312 11 +#define bfd_mach_arm_iWMMXt 12 +#define bfd_mach_arm_iWMMXt2 13 + bfd_arch_nds32, /* Andes NDS32 */ +#define bfd_mach_n1 1 +#define bfd_mach_n1h 2 +#define bfd_mach_n1h_v2 3 +#define bfd_mach_n1h_v3 4 +#define bfd_mach_n1h_v3m 5 + bfd_arch_ns32k, /* National Semiconductors ns32000 */ + bfd_arch_w65, /* WDC 65816 */ + bfd_arch_tic30, /* Texas Instruments TMS320C30 */ + bfd_arch_tic4x, /* Texas Instruments TMS320C3X/4X */ +#define bfd_mach_tic3x 30 +#define bfd_mach_tic4x 40 + bfd_arch_tic54x, /* Texas Instruments TMS320C54X */ + bfd_arch_tic6x, /* Texas Instruments TMS320C6X */ + bfd_arch_tic80, /* TI TMS320c80 (MVP) */ + bfd_arch_v850, /* NEC V850 */ + bfd_arch_v850_rh850,/* NEC V850 (using RH850 ABI) */ +#define bfd_mach_v850 1 +#define bfd_mach_v850e 'E' +#define bfd_mach_v850e1 '1' +#define bfd_mach_v850e2 0x4532 +#define bfd_mach_v850e2v3 0x45325633 +#define bfd_mach_v850e3v5 0x45335635 /* ('E'|'3'|'V'|'5') */ + bfd_arch_arc, /* ARC Cores */ +#define bfd_mach_arc_5 5 +#define bfd_mach_arc_6 6 +#define bfd_mach_arc_7 7 +#define bfd_mach_arc_8 8 + bfd_arch_m32c, /* Renesas M16C/M32C. */ +#define bfd_mach_m16c 0x75 +#define bfd_mach_m32c 0x78 + bfd_arch_m32r, /* Renesas M32R (formerly Mitsubishi M32R/D) */ +#define bfd_mach_m32r 1 /* For backwards compatibility. */ +#define bfd_mach_m32rx 'x' +#define bfd_mach_m32r2 '2' + bfd_arch_mn10200, /* Matsushita MN10200 */ + bfd_arch_mn10300, /* Matsushita MN10300 */ +#define bfd_mach_mn10300 300 +#define bfd_mach_am33 330 +#define bfd_mach_am33_2 332 + bfd_arch_fr30, +#define bfd_mach_fr30 0x46523330 + bfd_arch_frv, +#define bfd_mach_frv 1 +#define bfd_mach_frvsimple 2 +#define bfd_mach_fr300 300 +#define bfd_mach_fr400 400 +#define bfd_mach_fr450 450 +#define bfd_mach_frvtomcat 499 /* fr500 prototype */ +#define bfd_mach_fr500 500 +#define bfd_mach_fr550 550 + bfd_arch_moxie, /* The moxie processor */ +#define bfd_mach_moxie 1 + bfd_arch_mcore, + bfd_arch_mep, +#define bfd_mach_mep 1 +#define bfd_mach_mep_h1 0x6831 +#define bfd_mach_mep_c5 0x6335 + bfd_arch_metag, +#define bfd_mach_metag 1 + bfd_arch_ia64, /* HP/Intel ia64 */ +#define bfd_mach_ia64_elf64 64 +#define bfd_mach_ia64_elf32 32 + bfd_arch_ip2k, /* Ubicom IP2K microcontrollers. */ +#define bfd_mach_ip2022 1 +#define bfd_mach_ip2022ext 2 + bfd_arch_iq2000, /* Vitesse IQ2000. */ +#define bfd_mach_iq2000 1 +#define bfd_mach_iq10 2 + bfd_arch_epiphany, /* Adapteva EPIPHANY */ +#define bfd_mach_epiphany16 1 +#define bfd_mach_epiphany32 2 + bfd_arch_mt, +#define bfd_mach_ms1 1 +#define bfd_mach_mrisc2 2 +#define bfd_mach_ms2 3 + bfd_arch_pj, + bfd_arch_avr, /* Atmel AVR microcontrollers. */ +#define bfd_mach_avr1 1 +#define bfd_mach_avr2 2 +#define bfd_mach_avr25 25 +#define bfd_mach_avr3 3 +#define bfd_mach_avr31 31 +#define bfd_mach_avr35 35 +#define bfd_mach_avr4 4 +#define bfd_mach_avr5 5 +#define bfd_mach_avr51 51 +#define bfd_mach_avr6 6 +#define bfd_mach_avrxmega1 101 +#define bfd_mach_avrxmega2 102 +#define bfd_mach_avrxmega3 103 +#define bfd_mach_avrxmega4 104 +#define bfd_mach_avrxmega5 105 +#define bfd_mach_avrxmega6 106 +#define bfd_mach_avrxmega7 107 + bfd_arch_bfin, /* ADI Blackfin */ +#define bfd_mach_bfin 1 + bfd_arch_cr16, /* National Semiconductor CompactRISC (ie CR16). */ +#define bfd_mach_cr16 1 + bfd_arch_cr16c, /* National Semiconductor CompactRISC. */ +#define bfd_mach_cr16c 1 + bfd_arch_crx, /* National Semiconductor CRX. */ +#define bfd_mach_crx 1 + bfd_arch_cris, /* Axis CRIS */ +#define bfd_mach_cris_v0_v10 255 +#define bfd_mach_cris_v32 32 +#define bfd_mach_cris_v10_v32 1032 + bfd_arch_rl78, +#define bfd_mach_rl78 0x75 + bfd_arch_rx, /* Renesas RX. */ +#define bfd_mach_rx 0x75 + bfd_arch_s390, /* IBM s390 */ +#define bfd_mach_s390_31 31 +#define bfd_mach_s390_64 64 + bfd_arch_score, /* Sunplus score */ +#define bfd_mach_score3 3 +#define bfd_mach_score7 7 + bfd_arch_openrisc, /* OpenRISC */ + bfd_arch_mmix, /* Donald Knuth's educational processor. */ + bfd_arch_xstormy16, +#define bfd_mach_xstormy16 1 + bfd_arch_msp430, /* Texas Instruments MSP430 architecture. */ +#define bfd_mach_msp11 11 +#define bfd_mach_msp110 110 +#define bfd_mach_msp12 12 +#define bfd_mach_msp13 13 +#define bfd_mach_msp14 14 +#define bfd_mach_msp15 15 +#define bfd_mach_msp16 16 +#define bfd_mach_msp20 20 +#define bfd_mach_msp21 21 +#define bfd_mach_msp22 22 +#define bfd_mach_msp23 23 +#define bfd_mach_msp24 24 +#define bfd_mach_msp26 26 +#define bfd_mach_msp31 31 +#define bfd_mach_msp32 32 +#define bfd_mach_msp33 33 +#define bfd_mach_msp41 41 +#define bfd_mach_msp42 42 +#define bfd_mach_msp43 43 +#define bfd_mach_msp44 44 +#define bfd_mach_msp430x 45 +#define bfd_mach_msp46 46 +#define bfd_mach_msp47 47 +#define bfd_mach_msp54 54 + bfd_arch_xc16x, /* Infineon's XC16X Series. */ +#define bfd_mach_xc16x 1 +#define bfd_mach_xc16xl 2 +#define bfd_mach_xc16xs 3 + bfd_arch_xgate, /* Freescale XGATE */ +#define bfd_mach_xgate 1 + bfd_arch_xtensa, /* Tensilica's Xtensa cores. */ +#define bfd_mach_xtensa 1 + bfd_arch_z80, +#define bfd_mach_z80strict 1 /* No undocumented opcodes. */ +#define bfd_mach_z80 3 /* With ixl, ixh, iyl, and iyh. */ +#define bfd_mach_z80full 7 /* All undocumented instructions. */ +#define bfd_mach_r800 11 /* R800: successor with multiplication. */ + bfd_arch_lm32, /* Lattice Mico32 */ +#define bfd_mach_lm32 1 + bfd_arch_microblaze,/* Xilinx MicroBlaze. */ + bfd_arch_tilepro, /* Tilera TILEPro */ + bfd_arch_tilegx, /* Tilera TILE-Gx */ +#define bfd_mach_tilepro 1 +#define bfd_mach_tilegx 1 +#define bfd_mach_tilegx32 2 + bfd_arch_aarch64, /* AArch64 */ +#define bfd_mach_aarch64 0 +#define bfd_mach_aarch64_ilp32 32 + bfd_arch_nios2, +#define bfd_mach_nios2 0 + bfd_arch_last + }; + +typedef struct bfd_arch_info +{ + int bits_per_word; + int bits_per_address; + int bits_per_byte; + enum bfd_architecture arch; + unsigned long mach; + const char *arch_name; + const char *printable_name; + unsigned int section_align_power; + /* TRUE if this is the default machine for the architecture. + The default arch should be the first entry for an arch so that + all the entries for that arch can be accessed via <>. */ + bfd_boolean the_default; + const struct bfd_arch_info * (*compatible) + (const struct bfd_arch_info *a, const struct bfd_arch_info *b); + + bfd_boolean (*scan) (const struct bfd_arch_info *, const char *); + + /* Allocate via bfd_malloc and return a fill buffer of size COUNT. If + IS_BIGENDIAN is TRUE, the order of bytes is big endian. If CODE is + TRUE, the buffer contains code. */ + void *(*fill) (bfd_size_type count, bfd_boolean is_bigendian, + bfd_boolean code); + + const struct bfd_arch_info *next; +} +bfd_arch_info_type; + +const char *bfd_printable_name (bfd *abfd); + +const bfd_arch_info_type *bfd_scan_arch (const char *string); + +const char **bfd_arch_list (void); + +const bfd_arch_info_type *bfd_arch_get_compatible + (const bfd *abfd, const bfd *bbfd, bfd_boolean accept_unknowns); + +void bfd_set_arch_info (bfd *abfd, const bfd_arch_info_type *arg); + +enum bfd_architecture bfd_get_arch (bfd *abfd); + +unsigned long bfd_get_mach (bfd *abfd); + +unsigned int bfd_arch_bits_per_byte (bfd *abfd); + +unsigned int bfd_arch_bits_per_address (bfd *abfd); + +const bfd_arch_info_type *bfd_get_arch_info (bfd *abfd); + +const bfd_arch_info_type *bfd_lookup_arch + (enum bfd_architecture arch, unsigned long machine); + +const char *bfd_printable_arch_mach + (enum bfd_architecture arch, unsigned long machine); + +unsigned int bfd_octets_per_byte (bfd *abfd); + +unsigned int bfd_arch_mach_octets_per_byte + (enum bfd_architecture arch, unsigned long machine); + +/* Extracted from reloc.c. */ +typedef enum bfd_reloc_status +{ + /* No errors detected. */ + bfd_reloc_ok, + + /* The relocation was performed, but there was an overflow. */ + bfd_reloc_overflow, + + /* The address to relocate was not within the section supplied. */ + bfd_reloc_outofrange, + + /* Used by special functions. */ + bfd_reloc_continue, + + /* Unsupported relocation size requested. */ + bfd_reloc_notsupported, + + /* Unused. */ + bfd_reloc_other, + + /* The symbol to relocate against was undefined. */ + bfd_reloc_undefined, + + /* The relocation was performed, but may not be ok - presently + generated only when linking i960 coff files with i960 b.out + symbols. If this type is returned, the error_message argument + to bfd_perform_relocation will be set. */ + bfd_reloc_dangerous + } + bfd_reloc_status_type; + + +typedef struct reloc_cache_entry +{ + /* A pointer into the canonical table of pointers. */ + struct bfd_symbol **sym_ptr_ptr; + + /* offset in section. */ + bfd_size_type address; + + /* addend for relocation value. */ + bfd_vma addend; + + /* Pointer to how to perform the required relocation. */ + reloc_howto_type *howto; + +} +arelent; + +enum complain_overflow +{ + /* Do not complain on overflow. */ + complain_overflow_dont, + + /* Complain if the value overflows when considered as a signed + number one bit larger than the field. ie. A bitfield of N bits + is allowed to represent -2**n to 2**n-1. */ + complain_overflow_bitfield, + + /* Complain if the value overflows when considered as a signed + number. */ + complain_overflow_signed, + + /* Complain if the value overflows when considered as an + unsigned number. */ + complain_overflow_unsigned +}; + +struct reloc_howto_struct +{ + /* The type field has mainly a documentary use - the back end can + do what it wants with it, though normally the back end's + external idea of what a reloc number is stored + in this field. For example, a PC relative word relocation + in a coff environment has the type 023 - because that's + what the outside world calls a R_PCRWORD reloc. */ + unsigned int type; + + /* The value the final relocation is shifted right by. This drops + unwanted data from the relocation. */ + unsigned int rightshift; + + /* The size of the item to be relocated. This is *not* a + power-of-two measure. To get the number of bytes operated + on by a type of relocation, use bfd_get_reloc_size. */ + int size; + + /* The number of bits in the item to be relocated. This is used + when doing overflow checking. */ + unsigned int bitsize; + + /* The relocation is relative to the field being relocated. */ + bfd_boolean pc_relative; + + /* The bit position of the reloc value in the destination. + The relocated value is left shifted by this amount. */ + unsigned int bitpos; + + /* What type of overflow error should be checked for when + relocating. */ + enum complain_overflow complain_on_overflow; + + /* If this field is non null, then the supplied function is + called rather than the normal function. This allows really + strange relocation methods to be accommodated (e.g., i960 callj + instructions). */ + bfd_reloc_status_type (*special_function) + (bfd *, arelent *, struct bfd_symbol *, void *, asection *, + bfd *, char **); + + /* The textual name of the relocation type. */ + char *name; + + /* Some formats record a relocation addend in the section contents + rather than with the relocation. For ELF formats this is the + distinction between USE_REL and USE_RELA (though the code checks + for USE_REL == 1/0). The value of this field is TRUE if the + addend is recorded with the section contents; when performing a + partial link (ld -r) the section contents (the data) will be + modified. The value of this field is FALSE if addends are + recorded with the relocation (in arelent.addend); when performing + a partial link the relocation will be modified. + All relocations for all ELF USE_RELA targets should set this field + to FALSE (values of TRUE should be looked on with suspicion). + However, the converse is not true: not all relocations of all ELF + USE_REL targets set this field to TRUE. Why this is so is peculiar + to each particular target. For relocs that aren't used in partial + links (e.g. GOT stuff) it doesn't matter what this is set to. */ + bfd_boolean partial_inplace; + + /* src_mask selects the part of the instruction (or data) to be used + in the relocation sum. If the target relocations don't have an + addend in the reloc, eg. ELF USE_REL, src_mask will normally equal + dst_mask to extract the addend from the section contents. If + relocations do have an addend in the reloc, eg. ELF USE_RELA, this + field should be zero. Non-zero values for ELF USE_RELA targets are + bogus as in those cases the value in the dst_mask part of the + section contents should be treated as garbage. */ + bfd_vma src_mask; + + /* dst_mask selects which parts of the instruction (or data) are + replaced with a relocated value. */ + bfd_vma dst_mask; + + /* When some formats create PC relative instructions, they leave + the value of the pc of the place being relocated in the offset + slot of the instruction, so that a PC relative relocation can + be made just by adding in an ordinary offset (e.g., sun3 a.out). + Some formats leave the displacement part of an instruction + empty (e.g., m88k bcs); this flag signals the fact. */ + bfd_boolean pcrel_offset; +}; + +#define HOWTO(C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \ + { (unsigned) C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC } +#define NEWHOWTO(FUNCTION, NAME, SIZE, REL, IN) \ + HOWTO (0, 0, SIZE, 0, REL, 0, complain_overflow_dont, FUNCTION, \ + NAME, FALSE, 0, 0, IN) + +#define EMPTY_HOWTO(C) \ + HOWTO ((C), 0, 0, 0, FALSE, 0, complain_overflow_dont, NULL, \ + NULL, FALSE, 0, 0, FALSE) + +#define HOWTO_PREPARE(relocation, symbol) \ + { \ + if (symbol != NULL) \ + { \ + if (bfd_is_com_section (symbol->section)) \ + { \ + relocation = 0; \ + } \ + else \ + { \ + relocation = symbol->value; \ + } \ + } \ + } + +unsigned int bfd_get_reloc_size (reloc_howto_type *); + +typedef struct relent_chain +{ + arelent relent; + struct relent_chain *next; +} +arelent_chain; + +bfd_reloc_status_type bfd_check_overflow + (enum complain_overflow how, + unsigned int bitsize, + unsigned int rightshift, + unsigned int addrsize, + bfd_vma relocation); + +bfd_reloc_status_type bfd_perform_relocation + (bfd *abfd, + arelent *reloc_entry, + void *data, + asection *input_section, + bfd *output_bfd, + char **error_message); + +bfd_reloc_status_type bfd_install_relocation + (bfd *abfd, + arelent *reloc_entry, + void *data, bfd_vma data_start, + asection *input_section, + char **error_message); + +enum bfd_reloc_code_real { + _dummy_first_bfd_reloc_code_real, + + +/* Basic absolute relocations of N bits. */ + BFD_RELOC_64, + BFD_RELOC_32, + BFD_RELOC_26, + BFD_RELOC_24, + BFD_RELOC_16, + BFD_RELOC_14, + BFD_RELOC_8, + +/* PC-relative relocations. Sometimes these are relative to the address +of the relocation itself; sometimes they are relative to the start of +the section containing the relocation. It depends on the specific target. + +The 24-bit relocation is used in some Intel 960 configurations. */ + BFD_RELOC_64_PCREL, + BFD_RELOC_32_PCREL, + BFD_RELOC_24_PCREL, + BFD_RELOC_16_PCREL, + BFD_RELOC_12_PCREL, + BFD_RELOC_8_PCREL, + +/* Section relative relocations. Some targets need this for DWARF2. */ + BFD_RELOC_32_SECREL, + +/* For ELF. */ + BFD_RELOC_32_GOT_PCREL, + BFD_RELOC_16_GOT_PCREL, + BFD_RELOC_8_GOT_PCREL, + BFD_RELOC_32_GOTOFF, + BFD_RELOC_16_GOTOFF, + BFD_RELOC_LO16_GOTOFF, + BFD_RELOC_HI16_GOTOFF, + BFD_RELOC_HI16_S_GOTOFF, + BFD_RELOC_8_GOTOFF, + BFD_RELOC_64_PLT_PCREL, + BFD_RELOC_32_PLT_PCREL, + BFD_RELOC_24_PLT_PCREL, + BFD_RELOC_16_PLT_PCREL, + BFD_RELOC_8_PLT_PCREL, + BFD_RELOC_64_PLTOFF, + BFD_RELOC_32_PLTOFF, + BFD_RELOC_16_PLTOFF, + BFD_RELOC_LO16_PLTOFF, + BFD_RELOC_HI16_PLTOFF, + BFD_RELOC_HI16_S_PLTOFF, + BFD_RELOC_8_PLTOFF, + +/* Size relocations. */ + BFD_RELOC_SIZE32, + BFD_RELOC_SIZE64, + +/* Relocations used by 68K ELF. */ + BFD_RELOC_68K_GLOB_DAT, + BFD_RELOC_68K_JMP_SLOT, + BFD_RELOC_68K_RELATIVE, + BFD_RELOC_68K_TLS_GD32, + BFD_RELOC_68K_TLS_GD16, + BFD_RELOC_68K_TLS_GD8, + BFD_RELOC_68K_TLS_LDM32, + BFD_RELOC_68K_TLS_LDM16, + BFD_RELOC_68K_TLS_LDM8, + BFD_RELOC_68K_TLS_LDO32, + BFD_RELOC_68K_TLS_LDO16, + BFD_RELOC_68K_TLS_LDO8, + BFD_RELOC_68K_TLS_IE32, + BFD_RELOC_68K_TLS_IE16, + BFD_RELOC_68K_TLS_IE8, + BFD_RELOC_68K_TLS_LE32, + BFD_RELOC_68K_TLS_LE16, + BFD_RELOC_68K_TLS_LE8, + +/* Linkage-table relative. */ + BFD_RELOC_32_BASEREL, + BFD_RELOC_16_BASEREL, + BFD_RELOC_LO16_BASEREL, + BFD_RELOC_HI16_BASEREL, + BFD_RELOC_HI16_S_BASEREL, + BFD_RELOC_8_BASEREL, + BFD_RELOC_RVA, + +/* Absolute 8-bit relocation, but used to form an address like 0xFFnn. */ + BFD_RELOC_8_FFnn, + +/* These PC-relative relocations are stored as word displacements -- +i.e., byte displacements shifted right two bits. The 30-bit word +displacement (<<32_PCREL_S2>> -- 32 bits, shifted 2) is used on the +SPARC. (SPARC tools generally refer to this as <>.) The +signed 16-bit displacement is used on the MIPS, and the 23-bit +displacement is used on the Alpha. */ + BFD_RELOC_32_PCREL_S2, + BFD_RELOC_16_PCREL_S2, + BFD_RELOC_23_PCREL_S2, + +/* High 22 bits and low 10 bits of 32-bit value, placed into lower bits of +the target word. These are used on the SPARC. */ + BFD_RELOC_HI22, + BFD_RELOC_LO10, + +/* For systems that allocate a Global Pointer register, these are +displacements off that register. These relocation types are +handled specially, because the value the register will have is +decided relatively late. */ + BFD_RELOC_GPREL16, + BFD_RELOC_GPREL32, + +/* Reloc types used for i960/b.out. */ + BFD_RELOC_I960_CALLJ, + +/* SPARC ELF relocations. There is probably some overlap with other +relocation types already defined. */ + BFD_RELOC_NONE, + BFD_RELOC_SPARC_WDISP22, + BFD_RELOC_SPARC22, + BFD_RELOC_SPARC13, + BFD_RELOC_SPARC_GOT10, + BFD_RELOC_SPARC_GOT13, + BFD_RELOC_SPARC_GOT22, + BFD_RELOC_SPARC_PC10, + BFD_RELOC_SPARC_PC22, + BFD_RELOC_SPARC_WPLT30, + BFD_RELOC_SPARC_COPY, + BFD_RELOC_SPARC_GLOB_DAT, + BFD_RELOC_SPARC_JMP_SLOT, + BFD_RELOC_SPARC_RELATIVE, + BFD_RELOC_SPARC_UA16, + BFD_RELOC_SPARC_UA32, + BFD_RELOC_SPARC_UA64, + BFD_RELOC_SPARC_GOTDATA_HIX22, + BFD_RELOC_SPARC_GOTDATA_LOX10, + BFD_RELOC_SPARC_GOTDATA_OP_HIX22, + BFD_RELOC_SPARC_GOTDATA_OP_LOX10, + BFD_RELOC_SPARC_GOTDATA_OP, + BFD_RELOC_SPARC_JMP_IREL, + BFD_RELOC_SPARC_IRELATIVE, + +/* I think these are specific to SPARC a.out (e.g., Sun 4). */ + BFD_RELOC_SPARC_BASE13, + BFD_RELOC_SPARC_BASE22, + +/* SPARC64 relocations */ +#define BFD_RELOC_SPARC_64 BFD_RELOC_64 + BFD_RELOC_SPARC_10, + BFD_RELOC_SPARC_11, + BFD_RELOC_SPARC_OLO10, + BFD_RELOC_SPARC_HH22, + BFD_RELOC_SPARC_HM10, + BFD_RELOC_SPARC_LM22, + BFD_RELOC_SPARC_PC_HH22, + BFD_RELOC_SPARC_PC_HM10, + BFD_RELOC_SPARC_PC_LM22, + BFD_RELOC_SPARC_WDISP16, + BFD_RELOC_SPARC_WDISP19, + BFD_RELOC_SPARC_7, + BFD_RELOC_SPARC_6, + BFD_RELOC_SPARC_5, +#define BFD_RELOC_SPARC_DISP64 BFD_RELOC_64_PCREL + BFD_RELOC_SPARC_PLT32, + BFD_RELOC_SPARC_PLT64, + BFD_RELOC_SPARC_HIX22, + BFD_RELOC_SPARC_LOX10, + BFD_RELOC_SPARC_H44, + BFD_RELOC_SPARC_M44, + BFD_RELOC_SPARC_L44, + BFD_RELOC_SPARC_REGISTER, + BFD_RELOC_SPARC_H34, + BFD_RELOC_SPARC_SIZE32, + BFD_RELOC_SPARC_SIZE64, + BFD_RELOC_SPARC_WDISP10, + +/* SPARC little endian relocation */ + BFD_RELOC_SPARC_REV32, + +/* SPARC TLS relocations */ + BFD_RELOC_SPARC_TLS_GD_HI22, + BFD_RELOC_SPARC_TLS_GD_LO10, + BFD_RELOC_SPARC_TLS_GD_ADD, + BFD_RELOC_SPARC_TLS_GD_CALL, + BFD_RELOC_SPARC_TLS_LDM_HI22, + BFD_RELOC_SPARC_TLS_LDM_LO10, + BFD_RELOC_SPARC_TLS_LDM_ADD, + BFD_RELOC_SPARC_TLS_LDM_CALL, + BFD_RELOC_SPARC_TLS_LDO_HIX22, + BFD_RELOC_SPARC_TLS_LDO_LOX10, + BFD_RELOC_SPARC_TLS_LDO_ADD, + BFD_RELOC_SPARC_TLS_IE_HI22, + BFD_RELOC_SPARC_TLS_IE_LO10, + BFD_RELOC_SPARC_TLS_IE_LD, + BFD_RELOC_SPARC_TLS_IE_LDX, + BFD_RELOC_SPARC_TLS_IE_ADD, + BFD_RELOC_SPARC_TLS_LE_HIX22, + BFD_RELOC_SPARC_TLS_LE_LOX10, + BFD_RELOC_SPARC_TLS_DTPMOD32, + BFD_RELOC_SPARC_TLS_DTPMOD64, + BFD_RELOC_SPARC_TLS_DTPOFF32, + BFD_RELOC_SPARC_TLS_DTPOFF64, + BFD_RELOC_SPARC_TLS_TPOFF32, + BFD_RELOC_SPARC_TLS_TPOFF64, + +/* SPU Relocations. */ + BFD_RELOC_SPU_IMM7, + BFD_RELOC_SPU_IMM8, + BFD_RELOC_SPU_IMM10, + BFD_RELOC_SPU_IMM10W, + BFD_RELOC_SPU_IMM16, + BFD_RELOC_SPU_IMM16W, + BFD_RELOC_SPU_IMM18, + BFD_RELOC_SPU_PCREL9a, + BFD_RELOC_SPU_PCREL9b, + BFD_RELOC_SPU_PCREL16, + BFD_RELOC_SPU_LO16, + BFD_RELOC_SPU_HI16, + BFD_RELOC_SPU_PPU32, + BFD_RELOC_SPU_PPU64, + BFD_RELOC_SPU_ADD_PIC, + +/* Alpha ECOFF and ELF relocations. Some of these treat the symbol or +"addend" in some special way. +For GPDISP_HI16 ("gpdisp") relocations, the symbol is ignored when +writing; when reading, it will be the absolute section symbol. The +addend is the displacement in bytes of the "lda" instruction from +the "ldah" instruction (which is at the address of this reloc). */ + BFD_RELOC_ALPHA_GPDISP_HI16, + +/* For GPDISP_LO16 ("ignore") relocations, the symbol is handled as +with GPDISP_HI16 relocs. The addend is ignored when writing the +relocations out, and is filled in with the file's GP value on +reading, for convenience. */ + BFD_RELOC_ALPHA_GPDISP_LO16, + +/* The ELF GPDISP relocation is exactly the same as the GPDISP_HI16 +relocation except that there is no accompanying GPDISP_LO16 +relocation. */ + BFD_RELOC_ALPHA_GPDISP, + +/* The Alpha LITERAL/LITUSE relocs are produced by a symbol reference; +the assembler turns it into a LDQ instruction to load the address of +the symbol, and then fills in a register in the real instruction. + +The LITERAL reloc, at the LDQ instruction, refers to the .lita +section symbol. The addend is ignored when writing, but is filled +in with the file's GP value on reading, for convenience, as with the +GPDISP_LO16 reloc. + +The ELF_LITERAL reloc is somewhere between 16_GOTOFF and GPDISP_LO16. +It should refer to the symbol to be referenced, as with 16_GOTOFF, +but it generates output not based on the position within the .got +section, but relative to the GP value chosen for the file during the +final link stage. + +The LITUSE reloc, on the instruction using the loaded address, gives +information to the linker that it might be able to use to optimize +away some literal section references. The symbol is ignored (read +as the absolute section symbol), and the "addend" indicates the type +of instruction using the register: +1 - "memory" fmt insn +2 - byte-manipulation (byte offset reg) +3 - jsr (target of branch) */ + BFD_RELOC_ALPHA_LITERAL, + BFD_RELOC_ALPHA_ELF_LITERAL, + BFD_RELOC_ALPHA_LITUSE, + +/* The HINT relocation indicates a value that should be filled into the +"hint" field of a jmp/jsr/ret instruction, for possible branch- +prediction logic which may be provided on some processors. */ + BFD_RELOC_ALPHA_HINT, + +/* The LINKAGE relocation outputs a linkage pair in the object file, +which is filled by the linker. */ + BFD_RELOC_ALPHA_LINKAGE, + +/* The CODEADDR relocation outputs a STO_CA in the object file, +which is filled by the linker. */ + BFD_RELOC_ALPHA_CODEADDR, + +/* The GPREL_HI/LO relocations together form a 32-bit offset from the +GP register. */ + BFD_RELOC_ALPHA_GPREL_HI16, + BFD_RELOC_ALPHA_GPREL_LO16, + +/* Like BFD_RELOC_23_PCREL_S2, except that the source and target must +share a common GP, and the target address is adjusted for +STO_ALPHA_STD_GPLOAD. */ + BFD_RELOC_ALPHA_BRSGP, + +/* The NOP relocation outputs a NOP if the longword displacement +between two procedure entry points is < 2^21. */ + BFD_RELOC_ALPHA_NOP, + +/* The BSR relocation outputs a BSR if the longword displacement +between two procedure entry points is < 2^21. */ + BFD_RELOC_ALPHA_BSR, + +/* The LDA relocation outputs a LDA if the longword displacement +between two procedure entry points is < 2^16. */ + BFD_RELOC_ALPHA_LDA, + +/* The BOH relocation outputs a BSR if the longword displacement +between two procedure entry points is < 2^21, or else a hint. */ + BFD_RELOC_ALPHA_BOH, + +/* Alpha thread-local storage relocations. */ + BFD_RELOC_ALPHA_TLSGD, + BFD_RELOC_ALPHA_TLSLDM, + BFD_RELOC_ALPHA_DTPMOD64, + BFD_RELOC_ALPHA_GOTDTPREL16, + BFD_RELOC_ALPHA_DTPREL64, + BFD_RELOC_ALPHA_DTPREL_HI16, + BFD_RELOC_ALPHA_DTPREL_LO16, + BFD_RELOC_ALPHA_DTPREL16, + BFD_RELOC_ALPHA_GOTTPREL16, + BFD_RELOC_ALPHA_TPREL64, + BFD_RELOC_ALPHA_TPREL_HI16, + BFD_RELOC_ALPHA_TPREL_LO16, + BFD_RELOC_ALPHA_TPREL16, + +/* The MIPS jump instruction. */ + BFD_RELOC_MIPS_JMP, + BFD_RELOC_MICROMIPS_JMP, + +/* The MIPS16 jump instruction. */ + BFD_RELOC_MIPS16_JMP, + +/* MIPS16 GP relative reloc. */ + BFD_RELOC_MIPS16_GPREL, + +/* High 16 bits of 32-bit value; simple reloc. */ + BFD_RELOC_HI16, + +/* High 16 bits of 32-bit value but the low 16 bits will be sign +extended and added to form the final result. If the low 16 +bits form a negative number, we need to add one to the high value +to compensate for the borrow when the low bits are added. */ + BFD_RELOC_HI16_S, + +/* Low 16 bits. */ + BFD_RELOC_LO16, + +/* High 16 bits of 32-bit pc-relative value */ + BFD_RELOC_HI16_PCREL, + +/* High 16 bits of 32-bit pc-relative value, adjusted */ + BFD_RELOC_HI16_S_PCREL, + +/* Low 16 bits of pc-relative value */ + BFD_RELOC_LO16_PCREL, + +/* Equivalent of BFD_RELOC_MIPS_*, but with the MIPS16 layout of +16-bit immediate fields */ + BFD_RELOC_MIPS16_GOT16, + BFD_RELOC_MIPS16_CALL16, + +/* MIPS16 high 16 bits of 32-bit value. */ + BFD_RELOC_MIPS16_HI16, + +/* MIPS16 high 16 bits of 32-bit value but the low 16 bits will be sign +extended and added to form the final result. If the low 16 +bits form a negative number, we need to add one to the high value +to compensate for the borrow when the low bits are added. */ + BFD_RELOC_MIPS16_HI16_S, + +/* MIPS16 low 16 bits. */ + BFD_RELOC_MIPS16_LO16, + +/* MIPS16 TLS relocations */ + BFD_RELOC_MIPS16_TLS_GD, + BFD_RELOC_MIPS16_TLS_LDM, + BFD_RELOC_MIPS16_TLS_DTPREL_HI16, + BFD_RELOC_MIPS16_TLS_DTPREL_LO16, + BFD_RELOC_MIPS16_TLS_GOTTPREL, + BFD_RELOC_MIPS16_TLS_TPREL_HI16, + BFD_RELOC_MIPS16_TLS_TPREL_LO16, + +/* Relocation against a MIPS literal section. */ + BFD_RELOC_MIPS_LITERAL, + BFD_RELOC_MICROMIPS_LITERAL, + +/* microMIPS PC-relative relocations. */ + BFD_RELOC_MICROMIPS_7_PCREL_S1, + BFD_RELOC_MICROMIPS_10_PCREL_S1, + BFD_RELOC_MICROMIPS_16_PCREL_S1, + +/* microMIPS versions of generic BFD relocs. */ + BFD_RELOC_MICROMIPS_GPREL16, + BFD_RELOC_MICROMIPS_HI16, + BFD_RELOC_MICROMIPS_HI16_S, + BFD_RELOC_MICROMIPS_LO16, + +/* MIPS ELF relocations. */ + BFD_RELOC_MIPS_GOT16, + BFD_RELOC_MICROMIPS_GOT16, + BFD_RELOC_MIPS_CALL16, + BFD_RELOC_MICROMIPS_CALL16, + BFD_RELOC_MIPS_GOT_HI16, + BFD_RELOC_MICROMIPS_GOT_HI16, + BFD_RELOC_MIPS_GOT_LO16, + BFD_RELOC_MICROMIPS_GOT_LO16, + BFD_RELOC_MIPS_CALL_HI16, + BFD_RELOC_MICROMIPS_CALL_HI16, + BFD_RELOC_MIPS_CALL_LO16, + BFD_RELOC_MICROMIPS_CALL_LO16, + BFD_RELOC_MIPS_SUB, + BFD_RELOC_MICROMIPS_SUB, + BFD_RELOC_MIPS_GOT_PAGE, + BFD_RELOC_MICROMIPS_GOT_PAGE, + BFD_RELOC_MIPS_GOT_OFST, + BFD_RELOC_MICROMIPS_GOT_OFST, + BFD_RELOC_MIPS_GOT_DISP, + BFD_RELOC_MICROMIPS_GOT_DISP, + BFD_RELOC_MIPS_SHIFT5, + BFD_RELOC_MIPS_SHIFT6, + BFD_RELOC_MIPS_INSERT_A, + BFD_RELOC_MIPS_INSERT_B, + BFD_RELOC_MIPS_DELETE, + BFD_RELOC_MIPS_HIGHEST, + BFD_RELOC_MICROMIPS_HIGHEST, + BFD_RELOC_MIPS_HIGHER, + BFD_RELOC_MICROMIPS_HIGHER, + BFD_RELOC_MIPS_SCN_DISP, + BFD_RELOC_MICROMIPS_SCN_DISP, + BFD_RELOC_MIPS_REL16, + BFD_RELOC_MIPS_RELGOT, + BFD_RELOC_MIPS_JALR, + BFD_RELOC_MICROMIPS_JALR, + BFD_RELOC_MIPS_TLS_DTPMOD32, + BFD_RELOC_MIPS_TLS_DTPREL32, + BFD_RELOC_MIPS_TLS_DTPMOD64, + BFD_RELOC_MIPS_TLS_DTPREL64, + BFD_RELOC_MIPS_TLS_GD, + BFD_RELOC_MICROMIPS_TLS_GD, + BFD_RELOC_MIPS_TLS_LDM, + BFD_RELOC_MICROMIPS_TLS_LDM, + BFD_RELOC_MIPS_TLS_DTPREL_HI16, + BFD_RELOC_MICROMIPS_TLS_DTPREL_HI16, + BFD_RELOC_MIPS_TLS_DTPREL_LO16, + BFD_RELOC_MICROMIPS_TLS_DTPREL_LO16, + BFD_RELOC_MIPS_TLS_GOTTPREL, + BFD_RELOC_MICROMIPS_TLS_GOTTPREL, + BFD_RELOC_MIPS_TLS_TPREL32, + BFD_RELOC_MIPS_TLS_TPREL64, + BFD_RELOC_MIPS_TLS_TPREL_HI16, + BFD_RELOC_MICROMIPS_TLS_TPREL_HI16, + BFD_RELOC_MIPS_TLS_TPREL_LO16, + BFD_RELOC_MICROMIPS_TLS_TPREL_LO16, + BFD_RELOC_MIPS_EH, + + +/* MIPS ELF relocations (VxWorks and PLT extensions). */ + BFD_RELOC_MIPS_COPY, + BFD_RELOC_MIPS_JUMP_SLOT, + + +/* Moxie ELF relocations. */ + BFD_RELOC_MOXIE_10_PCREL, + + +/* Fujitsu Frv Relocations. */ + BFD_RELOC_FRV_LABEL16, + BFD_RELOC_FRV_LABEL24, + BFD_RELOC_FRV_LO16, + BFD_RELOC_FRV_HI16, + BFD_RELOC_FRV_GPREL12, + BFD_RELOC_FRV_GPRELU12, + BFD_RELOC_FRV_GPREL32, + BFD_RELOC_FRV_GPRELHI, + BFD_RELOC_FRV_GPRELLO, + BFD_RELOC_FRV_GOT12, + BFD_RELOC_FRV_GOTHI, + BFD_RELOC_FRV_GOTLO, + BFD_RELOC_FRV_FUNCDESC, + BFD_RELOC_FRV_FUNCDESC_GOT12, + BFD_RELOC_FRV_FUNCDESC_GOTHI, + BFD_RELOC_FRV_FUNCDESC_GOTLO, + BFD_RELOC_FRV_FUNCDESC_VALUE, + BFD_RELOC_FRV_FUNCDESC_GOTOFF12, + BFD_RELOC_FRV_FUNCDESC_GOTOFFHI, + BFD_RELOC_FRV_FUNCDESC_GOTOFFLO, + BFD_RELOC_FRV_GOTOFF12, + BFD_RELOC_FRV_GOTOFFHI, + BFD_RELOC_FRV_GOTOFFLO, + BFD_RELOC_FRV_GETTLSOFF, + BFD_RELOC_FRV_TLSDESC_VALUE, + BFD_RELOC_FRV_GOTTLSDESC12, + BFD_RELOC_FRV_GOTTLSDESCHI, + BFD_RELOC_FRV_GOTTLSDESCLO, + BFD_RELOC_FRV_TLSMOFF12, + BFD_RELOC_FRV_TLSMOFFHI, + BFD_RELOC_FRV_TLSMOFFLO, + BFD_RELOC_FRV_GOTTLSOFF12, + BFD_RELOC_FRV_GOTTLSOFFHI, + BFD_RELOC_FRV_GOTTLSOFFLO, + BFD_RELOC_FRV_TLSOFF, + BFD_RELOC_FRV_TLSDESC_RELAX, + BFD_RELOC_FRV_GETTLSOFF_RELAX, + BFD_RELOC_FRV_TLSOFF_RELAX, + BFD_RELOC_FRV_TLSMOFF, + + +/* This is a 24bit GOT-relative reloc for the mn10300. */ + BFD_RELOC_MN10300_GOTOFF24, + +/* This is a 32bit GOT-relative reloc for the mn10300, offset by two bytes +in the instruction. */ + BFD_RELOC_MN10300_GOT32, + +/* This is a 24bit GOT-relative reloc for the mn10300, offset by two bytes +in the instruction. */ + BFD_RELOC_MN10300_GOT24, + +/* This is a 16bit GOT-relative reloc for the mn10300, offset by two bytes +in the instruction. */ + BFD_RELOC_MN10300_GOT16, + +/* Copy symbol at runtime. */ + BFD_RELOC_MN10300_COPY, + +/* Create GOT entry. */ + BFD_RELOC_MN10300_GLOB_DAT, + +/* Create PLT entry. */ + BFD_RELOC_MN10300_JMP_SLOT, + +/* Adjust by program base. */ + BFD_RELOC_MN10300_RELATIVE, + +/* Together with another reloc targeted at the same location, +allows for a value that is the difference of two symbols +in the same section. */ + BFD_RELOC_MN10300_SYM_DIFF, + +/* The addend of this reloc is an alignment power that must +be honoured at the offset's location, regardless of linker +relaxation. */ + BFD_RELOC_MN10300_ALIGN, + +/* Various TLS-related relocations. */ + BFD_RELOC_MN10300_TLS_GD, + BFD_RELOC_MN10300_TLS_LD, + BFD_RELOC_MN10300_TLS_LDO, + BFD_RELOC_MN10300_TLS_GOTIE, + BFD_RELOC_MN10300_TLS_IE, + BFD_RELOC_MN10300_TLS_LE, + BFD_RELOC_MN10300_TLS_DTPMOD, + BFD_RELOC_MN10300_TLS_DTPOFF, + BFD_RELOC_MN10300_TLS_TPOFF, + +/* This is a 32bit pcrel reloc for the mn10300, offset by two bytes in the +instruction. */ + BFD_RELOC_MN10300_32_PCREL, + +/* This is a 16bit pcrel reloc for the mn10300, offset by two bytes in the +instruction. */ + BFD_RELOC_MN10300_16_PCREL, + + +/* i386/elf relocations */ + BFD_RELOC_386_GOT32, + BFD_RELOC_386_PLT32, + BFD_RELOC_386_COPY, + BFD_RELOC_386_GLOB_DAT, + BFD_RELOC_386_JUMP_SLOT, + BFD_RELOC_386_RELATIVE, + BFD_RELOC_386_GOTOFF, + BFD_RELOC_386_GOTPC, + BFD_RELOC_386_TLS_TPOFF, + BFD_RELOC_386_TLS_IE, + BFD_RELOC_386_TLS_GOTIE, + BFD_RELOC_386_TLS_LE, + BFD_RELOC_386_TLS_GD, + BFD_RELOC_386_TLS_LDM, + BFD_RELOC_386_TLS_LDO_32, + BFD_RELOC_386_TLS_IE_32, + BFD_RELOC_386_TLS_LE_32, + BFD_RELOC_386_TLS_DTPMOD32, + BFD_RELOC_386_TLS_DTPOFF32, + BFD_RELOC_386_TLS_TPOFF32, + BFD_RELOC_386_TLS_GOTDESC, + BFD_RELOC_386_TLS_DESC_CALL, + BFD_RELOC_386_TLS_DESC, + BFD_RELOC_386_IRELATIVE, + +/* x86-64/elf relocations */ + BFD_RELOC_X86_64_GOT32, + BFD_RELOC_X86_64_PLT32, + BFD_RELOC_X86_64_COPY, + BFD_RELOC_X86_64_GLOB_DAT, + BFD_RELOC_X86_64_JUMP_SLOT, + BFD_RELOC_X86_64_RELATIVE, + BFD_RELOC_X86_64_GOTPCREL, + BFD_RELOC_X86_64_32S, + BFD_RELOC_X86_64_DTPMOD64, + BFD_RELOC_X86_64_DTPOFF64, + BFD_RELOC_X86_64_TPOFF64, + BFD_RELOC_X86_64_TLSGD, + BFD_RELOC_X86_64_TLSLD, + BFD_RELOC_X86_64_DTPOFF32, + BFD_RELOC_X86_64_GOTTPOFF, + BFD_RELOC_X86_64_TPOFF32, + BFD_RELOC_X86_64_GOTOFF64, + BFD_RELOC_X86_64_GOTPC32, + BFD_RELOC_X86_64_GOT64, + BFD_RELOC_X86_64_GOTPCREL64, + BFD_RELOC_X86_64_GOTPC64, + BFD_RELOC_X86_64_GOTPLT64, + BFD_RELOC_X86_64_PLTOFF64, + BFD_RELOC_X86_64_GOTPC32_TLSDESC, + BFD_RELOC_X86_64_TLSDESC_CALL, + BFD_RELOC_X86_64_TLSDESC, + BFD_RELOC_X86_64_IRELATIVE, + BFD_RELOC_X86_64_PC32_BND, + BFD_RELOC_X86_64_PLT32_BND, + +/* ns32k relocations */ + BFD_RELOC_NS32K_IMM_8, + BFD_RELOC_NS32K_IMM_16, + BFD_RELOC_NS32K_IMM_32, + BFD_RELOC_NS32K_IMM_8_PCREL, + BFD_RELOC_NS32K_IMM_16_PCREL, + BFD_RELOC_NS32K_IMM_32_PCREL, + BFD_RELOC_NS32K_DISP_8, + BFD_RELOC_NS32K_DISP_16, + BFD_RELOC_NS32K_DISP_32, + BFD_RELOC_NS32K_DISP_8_PCREL, + BFD_RELOC_NS32K_DISP_16_PCREL, + BFD_RELOC_NS32K_DISP_32_PCREL, + +/* PDP11 relocations */ + BFD_RELOC_PDP11_DISP_8_PCREL, + BFD_RELOC_PDP11_DISP_6_PCREL, + +/* Picojava relocs. Not all of these appear in object files. */ + BFD_RELOC_PJ_CODE_HI16, + BFD_RELOC_PJ_CODE_LO16, + BFD_RELOC_PJ_CODE_DIR16, + BFD_RELOC_PJ_CODE_DIR32, + BFD_RELOC_PJ_CODE_REL16, + BFD_RELOC_PJ_CODE_REL32, + +/* Power(rs6000) and PowerPC relocations. */ + BFD_RELOC_PPC_B26, + BFD_RELOC_PPC_BA26, + BFD_RELOC_PPC_TOC16, + BFD_RELOC_PPC_B16, + BFD_RELOC_PPC_B16_BRTAKEN, + BFD_RELOC_PPC_B16_BRNTAKEN, + BFD_RELOC_PPC_BA16, + BFD_RELOC_PPC_BA16_BRTAKEN, + BFD_RELOC_PPC_BA16_BRNTAKEN, + BFD_RELOC_PPC_COPY, + BFD_RELOC_PPC_GLOB_DAT, + BFD_RELOC_PPC_JMP_SLOT, + BFD_RELOC_PPC_RELATIVE, + BFD_RELOC_PPC_LOCAL24PC, + BFD_RELOC_PPC_EMB_NADDR32, + BFD_RELOC_PPC_EMB_NADDR16, + BFD_RELOC_PPC_EMB_NADDR16_LO, + BFD_RELOC_PPC_EMB_NADDR16_HI, + BFD_RELOC_PPC_EMB_NADDR16_HA, + BFD_RELOC_PPC_EMB_SDAI16, + BFD_RELOC_PPC_EMB_SDA2I16, + BFD_RELOC_PPC_EMB_SDA2REL, + BFD_RELOC_PPC_EMB_SDA21, + BFD_RELOC_PPC_EMB_MRKREF, + BFD_RELOC_PPC_EMB_RELSEC16, + BFD_RELOC_PPC_EMB_RELST_LO, + BFD_RELOC_PPC_EMB_RELST_HI, + BFD_RELOC_PPC_EMB_RELST_HA, + BFD_RELOC_PPC_EMB_BIT_FLD, + BFD_RELOC_PPC_EMB_RELSDA, + BFD_RELOC_PPC_VLE_REL8, + BFD_RELOC_PPC_VLE_REL15, + BFD_RELOC_PPC_VLE_REL24, + BFD_RELOC_PPC_VLE_LO16A, + BFD_RELOC_PPC_VLE_LO16D, + BFD_RELOC_PPC_VLE_HI16A, + BFD_RELOC_PPC_VLE_HI16D, + BFD_RELOC_PPC_VLE_HA16A, + BFD_RELOC_PPC_VLE_HA16D, + BFD_RELOC_PPC_VLE_SDA21, + BFD_RELOC_PPC_VLE_SDA21_LO, + BFD_RELOC_PPC_VLE_SDAREL_LO16A, + BFD_RELOC_PPC_VLE_SDAREL_LO16D, + BFD_RELOC_PPC_VLE_SDAREL_HI16A, + BFD_RELOC_PPC_VLE_SDAREL_HI16D, + BFD_RELOC_PPC_VLE_SDAREL_HA16A, + BFD_RELOC_PPC_VLE_SDAREL_HA16D, + BFD_RELOC_PPC64_HIGHER, + BFD_RELOC_PPC64_HIGHER_S, + BFD_RELOC_PPC64_HIGHEST, + BFD_RELOC_PPC64_HIGHEST_S, + BFD_RELOC_PPC64_TOC16_LO, + BFD_RELOC_PPC64_TOC16_HI, + BFD_RELOC_PPC64_TOC16_HA, + BFD_RELOC_PPC64_TOC, + BFD_RELOC_PPC64_PLTGOT16, + BFD_RELOC_PPC64_PLTGOT16_LO, + BFD_RELOC_PPC64_PLTGOT16_HI, + BFD_RELOC_PPC64_PLTGOT16_HA, + BFD_RELOC_PPC64_ADDR16_DS, + BFD_RELOC_PPC64_ADDR16_LO_DS, + BFD_RELOC_PPC64_GOT16_DS, + BFD_RELOC_PPC64_GOT16_LO_DS, + BFD_RELOC_PPC64_PLT16_LO_DS, + BFD_RELOC_PPC64_SECTOFF_DS, + BFD_RELOC_PPC64_SECTOFF_LO_DS, + BFD_RELOC_PPC64_TOC16_DS, + BFD_RELOC_PPC64_TOC16_LO_DS, + BFD_RELOC_PPC64_PLTGOT16_DS, + BFD_RELOC_PPC64_PLTGOT16_LO_DS, + BFD_RELOC_PPC64_ADDR16_HIGH, + BFD_RELOC_PPC64_ADDR16_HIGHA, + +/* PowerPC and PowerPC64 thread-local storage relocations. */ + BFD_RELOC_PPC_TLS, + BFD_RELOC_PPC_TLSGD, + BFD_RELOC_PPC_TLSLD, + BFD_RELOC_PPC_DTPMOD, + BFD_RELOC_PPC_TPREL16, + BFD_RELOC_PPC_TPREL16_LO, + BFD_RELOC_PPC_TPREL16_HI, + BFD_RELOC_PPC_TPREL16_HA, + BFD_RELOC_PPC_TPREL, + BFD_RELOC_PPC_DTPREL16, + BFD_RELOC_PPC_DTPREL16_LO, + BFD_RELOC_PPC_DTPREL16_HI, + BFD_RELOC_PPC_DTPREL16_HA, + BFD_RELOC_PPC_DTPREL, + BFD_RELOC_PPC_GOT_TLSGD16, + BFD_RELOC_PPC_GOT_TLSGD16_LO, + BFD_RELOC_PPC_GOT_TLSGD16_HI, + BFD_RELOC_PPC_GOT_TLSGD16_HA, + BFD_RELOC_PPC_GOT_TLSLD16, + BFD_RELOC_PPC_GOT_TLSLD16_LO, + BFD_RELOC_PPC_GOT_TLSLD16_HI, + BFD_RELOC_PPC_GOT_TLSLD16_HA, + BFD_RELOC_PPC_GOT_TPREL16, + BFD_RELOC_PPC_GOT_TPREL16_LO, + BFD_RELOC_PPC_GOT_TPREL16_HI, + BFD_RELOC_PPC_GOT_TPREL16_HA, + BFD_RELOC_PPC_GOT_DTPREL16, + BFD_RELOC_PPC_GOT_DTPREL16_LO, + BFD_RELOC_PPC_GOT_DTPREL16_HI, + BFD_RELOC_PPC_GOT_DTPREL16_HA, + BFD_RELOC_PPC64_TPREL16_DS, + BFD_RELOC_PPC64_TPREL16_LO_DS, + BFD_RELOC_PPC64_TPREL16_HIGHER, + BFD_RELOC_PPC64_TPREL16_HIGHERA, + BFD_RELOC_PPC64_TPREL16_HIGHEST, + BFD_RELOC_PPC64_TPREL16_HIGHESTA, + BFD_RELOC_PPC64_DTPREL16_DS, + BFD_RELOC_PPC64_DTPREL16_LO_DS, + BFD_RELOC_PPC64_DTPREL16_HIGHER, + BFD_RELOC_PPC64_DTPREL16_HIGHERA, + BFD_RELOC_PPC64_DTPREL16_HIGHEST, + BFD_RELOC_PPC64_DTPREL16_HIGHESTA, + BFD_RELOC_PPC64_TPREL16_HIGH, + BFD_RELOC_PPC64_TPREL16_HIGHA, + BFD_RELOC_PPC64_DTPREL16_HIGH, + BFD_RELOC_PPC64_DTPREL16_HIGHA, + +/* IBM 370/390 relocations */ + BFD_RELOC_I370_D12, + +/* The type of reloc used to build a constructor table - at the moment +probably a 32 bit wide absolute relocation, but the target can choose. +It generally does map to one of the other relocation types. */ + BFD_RELOC_CTOR, + +/* ARM 26 bit pc-relative branch. The lowest two bits must be zero and are +not stored in the instruction. */ + BFD_RELOC_ARM_PCREL_BRANCH, + +/* ARM 26 bit pc-relative branch. The lowest bit must be zero and is +not stored in the instruction. The 2nd lowest bit comes from a 1 bit +field in the instruction. */ + BFD_RELOC_ARM_PCREL_BLX, + +/* Thumb 22 bit pc-relative branch. The lowest bit must be zero and is +not stored in the instruction. The 2nd lowest bit comes from a 1 bit +field in the instruction. */ + BFD_RELOC_THUMB_PCREL_BLX, + +/* ARM 26-bit pc-relative branch for an unconditional BL or BLX instruction. */ + BFD_RELOC_ARM_PCREL_CALL, + +/* ARM 26-bit pc-relative branch for B or conditional BL instruction. */ + BFD_RELOC_ARM_PCREL_JUMP, + +/* Thumb 7-, 9-, 12-, 20-, 23-, and 25-bit pc-relative branches. +The lowest bit must be zero and is not stored in the instruction. +Note that the corresponding ELF R_ARM_THM_JUMPnn constant has an +"nn" one smaller in all cases. Note further that BRANCH23 +corresponds to R_ARM_THM_CALL. */ + BFD_RELOC_THUMB_PCREL_BRANCH7, + BFD_RELOC_THUMB_PCREL_BRANCH9, + BFD_RELOC_THUMB_PCREL_BRANCH12, + BFD_RELOC_THUMB_PCREL_BRANCH20, + BFD_RELOC_THUMB_PCREL_BRANCH23, + BFD_RELOC_THUMB_PCREL_BRANCH25, + +/* 12-bit immediate offset, used in ARM-format ldr and str instructions. */ + BFD_RELOC_ARM_OFFSET_IMM, + +/* 5-bit immediate offset, used in Thumb-format ldr and str instructions. */ + BFD_RELOC_ARM_THUMB_OFFSET, + +/* Pc-relative or absolute relocation depending on target. Used for +entries in .init_array sections. */ + BFD_RELOC_ARM_TARGET1, + +/* Read-only segment base relative address. */ + BFD_RELOC_ARM_ROSEGREL32, + +/* Data segment base relative address. */ + BFD_RELOC_ARM_SBREL32, + +/* This reloc is used for references to RTTI data from exception handling +tables. The actual definition depends on the target. It may be a +pc-relative or some form of GOT-indirect relocation. */ + BFD_RELOC_ARM_TARGET2, + +/* 31-bit PC relative address. */ + BFD_RELOC_ARM_PREL31, + +/* Low and High halfword relocations for MOVW and MOVT instructions. */ + BFD_RELOC_ARM_MOVW, + BFD_RELOC_ARM_MOVT, + BFD_RELOC_ARM_MOVW_PCREL, + BFD_RELOC_ARM_MOVT_PCREL, + BFD_RELOC_ARM_THUMB_MOVW, + BFD_RELOC_ARM_THUMB_MOVT, + BFD_RELOC_ARM_THUMB_MOVW_PCREL, + BFD_RELOC_ARM_THUMB_MOVT_PCREL, + +/* Relocations for setting up GOTs and PLTs for shared libraries. */ + BFD_RELOC_ARM_JUMP_SLOT, + BFD_RELOC_ARM_GLOB_DAT, + BFD_RELOC_ARM_GOT32, + BFD_RELOC_ARM_PLT32, + BFD_RELOC_ARM_RELATIVE, + BFD_RELOC_ARM_GOTOFF, + BFD_RELOC_ARM_GOTPC, + BFD_RELOC_ARM_GOT_PREL, + +/* ARM thread-local storage relocations. */ + BFD_RELOC_ARM_TLS_GD32, + BFD_RELOC_ARM_TLS_LDO32, + BFD_RELOC_ARM_TLS_LDM32, + BFD_RELOC_ARM_TLS_DTPOFF32, + BFD_RELOC_ARM_TLS_DTPMOD32, + BFD_RELOC_ARM_TLS_TPOFF32, + BFD_RELOC_ARM_TLS_IE32, + BFD_RELOC_ARM_TLS_LE32, + BFD_RELOC_ARM_TLS_GOTDESC, + BFD_RELOC_ARM_TLS_CALL, + BFD_RELOC_ARM_THM_TLS_CALL, + BFD_RELOC_ARM_TLS_DESCSEQ, + BFD_RELOC_ARM_THM_TLS_DESCSEQ, + BFD_RELOC_ARM_TLS_DESC, + +/* ARM group relocations. */ + BFD_RELOC_ARM_ALU_PC_G0_NC, + BFD_RELOC_ARM_ALU_PC_G0, + BFD_RELOC_ARM_ALU_PC_G1_NC, + BFD_RELOC_ARM_ALU_PC_G1, + BFD_RELOC_ARM_ALU_PC_G2, + BFD_RELOC_ARM_LDR_PC_G0, + BFD_RELOC_ARM_LDR_PC_G1, + BFD_RELOC_ARM_LDR_PC_G2, + BFD_RELOC_ARM_LDRS_PC_G0, + BFD_RELOC_ARM_LDRS_PC_G1, + BFD_RELOC_ARM_LDRS_PC_G2, + BFD_RELOC_ARM_LDC_PC_G0, + BFD_RELOC_ARM_LDC_PC_G1, + BFD_RELOC_ARM_LDC_PC_G2, + BFD_RELOC_ARM_ALU_SB_G0_NC, + BFD_RELOC_ARM_ALU_SB_G0, + BFD_RELOC_ARM_ALU_SB_G1_NC, + BFD_RELOC_ARM_ALU_SB_G1, + BFD_RELOC_ARM_ALU_SB_G2, + BFD_RELOC_ARM_LDR_SB_G0, + BFD_RELOC_ARM_LDR_SB_G1, + BFD_RELOC_ARM_LDR_SB_G2, + BFD_RELOC_ARM_LDRS_SB_G0, + BFD_RELOC_ARM_LDRS_SB_G1, + BFD_RELOC_ARM_LDRS_SB_G2, + BFD_RELOC_ARM_LDC_SB_G0, + BFD_RELOC_ARM_LDC_SB_G1, + BFD_RELOC_ARM_LDC_SB_G2, + +/* Annotation of BX instructions. */ + BFD_RELOC_ARM_V4BX, + +/* ARM support for STT_GNU_IFUNC. */ + BFD_RELOC_ARM_IRELATIVE, + +/* These relocs are only used within the ARM assembler. They are not +(at present) written to any object files. */ + BFD_RELOC_ARM_IMMEDIATE, + BFD_RELOC_ARM_ADRL_IMMEDIATE, + BFD_RELOC_ARM_T32_IMMEDIATE, + BFD_RELOC_ARM_T32_ADD_IMM, + BFD_RELOC_ARM_T32_IMM12, + BFD_RELOC_ARM_T32_ADD_PC12, + BFD_RELOC_ARM_SHIFT_IMM, + BFD_RELOC_ARM_SMC, + BFD_RELOC_ARM_HVC, + BFD_RELOC_ARM_SWI, + BFD_RELOC_ARM_MULTI, + BFD_RELOC_ARM_CP_OFF_IMM, + BFD_RELOC_ARM_CP_OFF_IMM_S2, + BFD_RELOC_ARM_T32_CP_OFF_IMM, + BFD_RELOC_ARM_T32_CP_OFF_IMM_S2, + BFD_RELOC_ARM_ADR_IMM, + BFD_RELOC_ARM_LDR_IMM, + BFD_RELOC_ARM_LITERAL, + BFD_RELOC_ARM_IN_POOL, + BFD_RELOC_ARM_OFFSET_IMM8, + BFD_RELOC_ARM_T32_OFFSET_U8, + BFD_RELOC_ARM_T32_OFFSET_IMM, + BFD_RELOC_ARM_HWLITERAL, + BFD_RELOC_ARM_THUMB_ADD, + BFD_RELOC_ARM_THUMB_IMM, + BFD_RELOC_ARM_THUMB_SHIFT, + +/* Renesas / SuperH SH relocs. Not all of these appear in object files. */ + BFD_RELOC_SH_PCDISP8BY2, + BFD_RELOC_SH_PCDISP12BY2, + BFD_RELOC_SH_IMM3, + BFD_RELOC_SH_IMM3U, + BFD_RELOC_SH_DISP12, + BFD_RELOC_SH_DISP12BY2, + BFD_RELOC_SH_DISP12BY4, + BFD_RELOC_SH_DISP12BY8, + BFD_RELOC_SH_DISP20, + BFD_RELOC_SH_DISP20BY8, + BFD_RELOC_SH_IMM4, + BFD_RELOC_SH_IMM4BY2, + BFD_RELOC_SH_IMM4BY4, + BFD_RELOC_SH_IMM8, + BFD_RELOC_SH_IMM8BY2, + BFD_RELOC_SH_IMM8BY4, + BFD_RELOC_SH_PCRELIMM8BY2, + BFD_RELOC_SH_PCRELIMM8BY4, + BFD_RELOC_SH_SWITCH16, + BFD_RELOC_SH_SWITCH32, + BFD_RELOC_SH_USES, + BFD_RELOC_SH_COUNT, + BFD_RELOC_SH_ALIGN, + BFD_RELOC_SH_CODE, + BFD_RELOC_SH_DATA, + BFD_RELOC_SH_LABEL, + BFD_RELOC_SH_LOOP_START, + BFD_RELOC_SH_LOOP_END, + BFD_RELOC_SH_COPY, + BFD_RELOC_SH_GLOB_DAT, + BFD_RELOC_SH_JMP_SLOT, + BFD_RELOC_SH_RELATIVE, + BFD_RELOC_SH_GOTPC, + BFD_RELOC_SH_GOT_LOW16, + BFD_RELOC_SH_GOT_MEDLOW16, + BFD_RELOC_SH_GOT_MEDHI16, + BFD_RELOC_SH_GOT_HI16, + BFD_RELOC_SH_GOTPLT_LOW16, + BFD_RELOC_SH_GOTPLT_MEDLOW16, + BFD_RELOC_SH_GOTPLT_MEDHI16, + BFD_RELOC_SH_GOTPLT_HI16, + BFD_RELOC_SH_PLT_LOW16, + BFD_RELOC_SH_PLT_MEDLOW16, + BFD_RELOC_SH_PLT_MEDHI16, + BFD_RELOC_SH_PLT_HI16, + BFD_RELOC_SH_GOTOFF_LOW16, + BFD_RELOC_SH_GOTOFF_MEDLOW16, + BFD_RELOC_SH_GOTOFF_MEDHI16, + BFD_RELOC_SH_GOTOFF_HI16, + BFD_RELOC_SH_GOTPC_LOW16, + BFD_RELOC_SH_GOTPC_MEDLOW16, + BFD_RELOC_SH_GOTPC_MEDHI16, + BFD_RELOC_SH_GOTPC_HI16, + BFD_RELOC_SH_COPY64, + BFD_RELOC_SH_GLOB_DAT64, + BFD_RELOC_SH_JMP_SLOT64, + BFD_RELOC_SH_RELATIVE64, + BFD_RELOC_SH_GOT10BY4, + BFD_RELOC_SH_GOT10BY8, + BFD_RELOC_SH_GOTPLT10BY4, + BFD_RELOC_SH_GOTPLT10BY8, + BFD_RELOC_SH_GOTPLT32, + BFD_RELOC_SH_SHMEDIA_CODE, + BFD_RELOC_SH_IMMU5, + BFD_RELOC_SH_IMMS6, + BFD_RELOC_SH_IMMS6BY32, + BFD_RELOC_SH_IMMU6, + BFD_RELOC_SH_IMMS10, + BFD_RELOC_SH_IMMS10BY2, + BFD_RELOC_SH_IMMS10BY4, + BFD_RELOC_SH_IMMS10BY8, + BFD_RELOC_SH_IMMS16, + BFD_RELOC_SH_IMMU16, + BFD_RELOC_SH_IMM_LOW16, + BFD_RELOC_SH_IMM_LOW16_PCREL, + BFD_RELOC_SH_IMM_MEDLOW16, + BFD_RELOC_SH_IMM_MEDLOW16_PCREL, + BFD_RELOC_SH_IMM_MEDHI16, + BFD_RELOC_SH_IMM_MEDHI16_PCREL, + BFD_RELOC_SH_IMM_HI16, + BFD_RELOC_SH_IMM_HI16_PCREL, + BFD_RELOC_SH_PT_16, + BFD_RELOC_SH_TLS_GD_32, + BFD_RELOC_SH_TLS_LD_32, + BFD_RELOC_SH_TLS_LDO_32, + BFD_RELOC_SH_TLS_IE_32, + BFD_RELOC_SH_TLS_LE_32, + BFD_RELOC_SH_TLS_DTPMOD32, + BFD_RELOC_SH_TLS_DTPOFF32, + BFD_RELOC_SH_TLS_TPOFF32, + BFD_RELOC_SH_GOT20, + BFD_RELOC_SH_GOTOFF20, + BFD_RELOC_SH_GOTFUNCDESC, + BFD_RELOC_SH_GOTFUNCDESC20, + BFD_RELOC_SH_GOTOFFFUNCDESC, + BFD_RELOC_SH_GOTOFFFUNCDESC20, + BFD_RELOC_SH_FUNCDESC, + +/* ARC Cores relocs. +ARC 22 bit pc-relative branch. The lowest two bits must be zero and are +not stored in the instruction. The high 20 bits are installed in bits 26 +through 7 of the instruction. */ + BFD_RELOC_ARC_B22_PCREL, + +/* ARC 26 bit absolute branch. The lowest two bits must be zero and are not +stored in the instruction. The high 24 bits are installed in bits 23 +through 0. */ + BFD_RELOC_ARC_B26, + +/* ADI Blackfin 16 bit immediate absolute reloc. */ + BFD_RELOC_BFIN_16_IMM, + +/* ADI Blackfin 16 bit immediate absolute reloc higher 16 bits. */ + BFD_RELOC_BFIN_16_HIGH, + +/* ADI Blackfin 'a' part of LSETUP. */ + BFD_RELOC_BFIN_4_PCREL, + +/* ADI Blackfin. */ + BFD_RELOC_BFIN_5_PCREL, + +/* ADI Blackfin 16 bit immediate absolute reloc lower 16 bits. */ + BFD_RELOC_BFIN_16_LOW, + +/* ADI Blackfin. */ + BFD_RELOC_BFIN_10_PCREL, + +/* ADI Blackfin 'b' part of LSETUP. */ + BFD_RELOC_BFIN_11_PCREL, + +/* ADI Blackfin. */ + BFD_RELOC_BFIN_12_PCREL_JUMP, + +/* ADI Blackfin Short jump, pcrel. */ + BFD_RELOC_BFIN_12_PCREL_JUMP_S, + +/* ADI Blackfin Call.x not implemented. */ + BFD_RELOC_BFIN_24_PCREL_CALL_X, + +/* ADI Blackfin Long Jump pcrel. */ + BFD_RELOC_BFIN_24_PCREL_JUMP_L, + +/* ADI Blackfin FD-PIC relocations. */ + BFD_RELOC_BFIN_GOT17M4, + BFD_RELOC_BFIN_GOTHI, + BFD_RELOC_BFIN_GOTLO, + BFD_RELOC_BFIN_FUNCDESC, + BFD_RELOC_BFIN_FUNCDESC_GOT17M4, + BFD_RELOC_BFIN_FUNCDESC_GOTHI, + BFD_RELOC_BFIN_FUNCDESC_GOTLO, + BFD_RELOC_BFIN_FUNCDESC_VALUE, + BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4, + BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI, + BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO, + BFD_RELOC_BFIN_GOTOFF17M4, + BFD_RELOC_BFIN_GOTOFFHI, + BFD_RELOC_BFIN_GOTOFFLO, + +/* ADI Blackfin GOT relocation. */ + BFD_RELOC_BFIN_GOT, + +/* ADI Blackfin PLTPC relocation. */ + BFD_RELOC_BFIN_PLTPC, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_PUSH, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_CONST, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_ADD, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_SUB, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_MULT, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_DIV, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_MOD, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_LSHIFT, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_RSHIFT, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_AND, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_OR, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_XOR, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_LAND, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_LOR, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_LEN, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_NEG, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_COMP, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_PAGE, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_HWPAGE, + +/* ADI Blackfin arithmetic relocation. */ + BFD_ARELOC_BFIN_ADDR, + +/* Mitsubishi D10V relocs. +This is a 10-bit reloc with the right 2 bits +assumed to be 0. */ + BFD_RELOC_D10V_10_PCREL_R, + +/* Mitsubishi D10V relocs. +This is a 10-bit reloc with the right 2 bits +assumed to be 0. This is the same as the previous reloc +except it is in the left container, i.e., +shifted left 15 bits. */ + BFD_RELOC_D10V_10_PCREL_L, + +/* This is an 18-bit reloc with the right 2 bits +assumed to be 0. */ + BFD_RELOC_D10V_18, + +/* This is an 18-bit reloc with the right 2 bits +assumed to be 0. */ + BFD_RELOC_D10V_18_PCREL, + +/* Mitsubishi D30V relocs. +This is a 6-bit absolute reloc. */ + BFD_RELOC_D30V_6, + +/* This is a 6-bit pc-relative reloc with +the right 3 bits assumed to be 0. */ + BFD_RELOC_D30V_9_PCREL, + +/* This is a 6-bit pc-relative reloc with +the right 3 bits assumed to be 0. Same +as the previous reloc but on the right side +of the container. */ + BFD_RELOC_D30V_9_PCREL_R, + +/* This is a 12-bit absolute reloc with the +right 3 bitsassumed to be 0. */ + BFD_RELOC_D30V_15, + +/* This is a 12-bit pc-relative reloc with +the right 3 bits assumed to be 0. */ + BFD_RELOC_D30V_15_PCREL, + +/* This is a 12-bit pc-relative reloc with +the right 3 bits assumed to be 0. Same +as the previous reloc but on the right side +of the container. */ + BFD_RELOC_D30V_15_PCREL_R, + +/* This is an 18-bit absolute reloc with +the right 3 bits assumed to be 0. */ + BFD_RELOC_D30V_21, + +/* This is an 18-bit pc-relative reloc with +the right 3 bits assumed to be 0. */ + BFD_RELOC_D30V_21_PCREL, + +/* This is an 18-bit pc-relative reloc with +the right 3 bits assumed to be 0. Same +as the previous reloc but on the right side +of the container. */ + BFD_RELOC_D30V_21_PCREL_R, + +/* This is a 32-bit absolute reloc. */ + BFD_RELOC_D30V_32, + +/* This is a 32-bit pc-relative reloc. */ + BFD_RELOC_D30V_32_PCREL, + +/* DLX relocs */ + BFD_RELOC_DLX_HI16_S, + +/* DLX relocs */ + BFD_RELOC_DLX_LO16, + +/* DLX relocs */ + BFD_RELOC_DLX_JMP26, + +/* Renesas M16C/M32C Relocations. */ + BFD_RELOC_M32C_HI8, + BFD_RELOC_M32C_RL_JUMP, + BFD_RELOC_M32C_RL_1ADDR, + BFD_RELOC_M32C_RL_2ADDR, + +/* Renesas M32R (formerly Mitsubishi M32R) relocs. +This is a 24 bit absolute address. */ + BFD_RELOC_M32R_24, + +/* This is a 10-bit pc-relative reloc with the right 2 bits assumed to be 0. */ + BFD_RELOC_M32R_10_PCREL, + +/* This is an 18-bit reloc with the right 2 bits assumed to be 0. */ + BFD_RELOC_M32R_18_PCREL, + +/* This is a 26-bit reloc with the right 2 bits assumed to be 0. */ + BFD_RELOC_M32R_26_PCREL, + +/* This is a 16-bit reloc containing the high 16 bits of an address +used when the lower 16 bits are treated as unsigned. */ + BFD_RELOC_M32R_HI16_ULO, + +/* This is a 16-bit reloc containing the high 16 bits of an address +used when the lower 16 bits are treated as signed. */ + BFD_RELOC_M32R_HI16_SLO, + +/* This is a 16-bit reloc containing the lower 16 bits of an address. */ + BFD_RELOC_M32R_LO16, + +/* This is a 16-bit reloc containing the small data area offset for use in +add3, load, and store instructions. */ + BFD_RELOC_M32R_SDA16, + +/* For PIC. */ + BFD_RELOC_M32R_GOT24, + BFD_RELOC_M32R_26_PLTREL, + BFD_RELOC_M32R_COPY, + BFD_RELOC_M32R_GLOB_DAT, + BFD_RELOC_M32R_JMP_SLOT, + BFD_RELOC_M32R_RELATIVE, + BFD_RELOC_M32R_GOTOFF, + BFD_RELOC_M32R_GOTOFF_HI_ULO, + BFD_RELOC_M32R_GOTOFF_HI_SLO, + BFD_RELOC_M32R_GOTOFF_LO, + BFD_RELOC_M32R_GOTPC24, + BFD_RELOC_M32R_GOT16_HI_ULO, + BFD_RELOC_M32R_GOT16_HI_SLO, + BFD_RELOC_M32R_GOT16_LO, + BFD_RELOC_M32R_GOTPC_HI_ULO, + BFD_RELOC_M32R_GOTPC_HI_SLO, + BFD_RELOC_M32R_GOTPC_LO, + +/* NDS32 relocs. +This is a 20 bit absolute address. */ + BFD_RELOC_NDS32_20, + +/* This is a 9-bit pc-relative reloc with the right 1 bit assumed to be 0. */ + BFD_RELOC_NDS32_9_PCREL, + +/* This is a 9-bit pc-relative reloc with the right 1 bit assumed to be 0. */ + BFD_RELOC_NDS32_WORD_9_PCREL, + +/* This is an 15-bit reloc with the right 1 bit assumed to be 0. */ + BFD_RELOC_NDS32_15_PCREL, + +/* This is an 17-bit reloc with the right 1 bit assumed to be 0. */ + BFD_RELOC_NDS32_17_PCREL, + +/* This is a 25-bit reloc with the right 1 bit assumed to be 0. */ + BFD_RELOC_NDS32_25_PCREL, + +/* This is a 20-bit reloc containing the high 20 bits of an address +used with the lower 12 bits */ + BFD_RELOC_NDS32_HI20, + +/* This is a 12-bit reloc containing the lower 12 bits of an address +then shift right by 3. This is used with ldi,sdi... */ + BFD_RELOC_NDS32_LO12S3, + +/* This is a 12-bit reloc containing the lower 12 bits of an address +then shift left by 2. This is used with lwi,swi... */ + BFD_RELOC_NDS32_LO12S2, + +/* This is a 12-bit reloc containing the lower 12 bits of an address +then shift left by 1. This is used with lhi,shi... */ + BFD_RELOC_NDS32_LO12S1, + +/* This is a 12-bit reloc containing the lower 12 bits of an address +then shift left by 0. This is used with lbisbi... */ + BFD_RELOC_NDS32_LO12S0, + +/* This is a 12-bit reloc containing the lower 12 bits of an address +then shift left by 0. This is only used with branch relaxations */ + BFD_RELOC_NDS32_LO12S0_ORI, + +/* This is a 15-bit reloc containing the small data area 18-bit signed offset +and shift left by 3 for use in ldi, sdi... */ + BFD_RELOC_NDS32_SDA15S3, + +/* This is a 15-bit reloc containing the small data area 17-bit signed offset +and shift left by 2 for use in lwi, swi... */ + BFD_RELOC_NDS32_SDA15S2, + +/* This is a 15-bit reloc containing the small data area 16-bit signed offset +and shift left by 1 for use in lhi, shi... */ + BFD_RELOC_NDS32_SDA15S1, + +/* This is a 15-bit reloc containing the small data area 15-bit signed offset +and shift left by 0 for use in lbi, sbi... */ + BFD_RELOC_NDS32_SDA15S0, + +/* This is a 16-bit reloc containing the small data area 16-bit signed offset +and shift left by 3 */ + BFD_RELOC_NDS32_SDA16S3, + +/* This is a 17-bit reloc containing the small data area 17-bit signed offset +and shift left by 2 for use in lwi.gp, swi.gp... */ + BFD_RELOC_NDS32_SDA17S2, + +/* This is a 18-bit reloc containing the small data area 18-bit signed offset +and shift left by 1 for use in lhi.gp, shi.gp... */ + BFD_RELOC_NDS32_SDA18S1, + +/* This is a 19-bit reloc containing the small data area 19-bit signed offset +and shift left by 0 for use in lbi.gp, sbi.gp... */ + BFD_RELOC_NDS32_SDA19S0, + +/* for PIC */ + BFD_RELOC_NDS32_GOT20, + BFD_RELOC_NDS32_9_PLTREL, + BFD_RELOC_NDS32_25_PLTREL, + BFD_RELOC_NDS32_COPY, + BFD_RELOC_NDS32_GLOB_DAT, + BFD_RELOC_NDS32_JMP_SLOT, + BFD_RELOC_NDS32_RELATIVE, + BFD_RELOC_NDS32_GOTOFF, + BFD_RELOC_NDS32_GOTOFF_HI20, + BFD_RELOC_NDS32_GOTOFF_LO12, + BFD_RELOC_NDS32_GOTPC20, + BFD_RELOC_NDS32_GOT_HI20, + BFD_RELOC_NDS32_GOT_LO12, + BFD_RELOC_NDS32_GOTPC_HI20, + BFD_RELOC_NDS32_GOTPC_LO12, + +/* for relax */ + BFD_RELOC_NDS32_INSN16, + BFD_RELOC_NDS32_LABEL, + BFD_RELOC_NDS32_LONGCALL1, + BFD_RELOC_NDS32_LONGCALL2, + BFD_RELOC_NDS32_LONGCALL3, + BFD_RELOC_NDS32_LONGJUMP1, + BFD_RELOC_NDS32_LONGJUMP2, + BFD_RELOC_NDS32_LONGJUMP3, + BFD_RELOC_NDS32_LOADSTORE, + BFD_RELOC_NDS32_9_FIXED, + BFD_RELOC_NDS32_15_FIXED, + BFD_RELOC_NDS32_17_FIXED, + BFD_RELOC_NDS32_25_FIXED, + +/* for PIC */ + BFD_RELOC_NDS32_PLTREL_HI20, + BFD_RELOC_NDS32_PLTREL_LO12, + BFD_RELOC_NDS32_PLT_GOTREL_HI20, + BFD_RELOC_NDS32_PLT_GOTREL_LO12, + +/* for floating point */ + BFD_RELOC_NDS32_SDA12S2_DP, + BFD_RELOC_NDS32_SDA12S2_SP, + BFD_RELOC_NDS32_LO12S2_DP, + BFD_RELOC_NDS32_LO12S2_SP, + +/* for dwarf2 debug_line. */ + BFD_RELOC_NDS32_DWARF2_OP1, + BFD_RELOC_NDS32_DWARF2_OP2, + BFD_RELOC_NDS32_DWARF2_LEB, + +/* for eliminate 16-bit instructions */ + BFD_RELOC_NDS32_UPDATE_TA, + +/* for PIC object relaxation */ + BFD_RELOC_NDS32_PLT_GOTREL_LO20, + BFD_RELOC_NDS32_PLT_GOTREL_LO15, + BFD_RELOC_NDS32_PLT_GOTREL_LO19, + BFD_RELOC_NDS32_GOT_LO15, + BFD_RELOC_NDS32_GOT_LO19, + BFD_RELOC_NDS32_GOTOFF_LO15, + BFD_RELOC_NDS32_GOTOFF_LO19, + BFD_RELOC_NDS32_GOT15S2, + BFD_RELOC_NDS32_GOT17S2, + +/* NDS32 relocs. +This is a 5 bit absolute address. */ + BFD_RELOC_NDS32_5, + +/* This is a 10-bit unsigned pc-relative reloc with the right 1 bit assumed to be 0. */ + BFD_RELOC_NDS32_10_UPCREL, + +/* If fp were omitted, fp can used as another gp. */ + BFD_RELOC_NDS32_SDA_FP7U2_RELA, + +/* relaxation relative relocation types */ + BFD_RELOC_NDS32_RELAX_ENTRY, + BFD_RELOC_NDS32_GOT_SUFF, + BFD_RELOC_NDS32_GOTOFF_SUFF, + BFD_RELOC_NDS32_PLT_GOT_SUFF, + BFD_RELOC_NDS32_MULCALL_SUFF, + BFD_RELOC_NDS32_PTR, + BFD_RELOC_NDS32_PTR_COUNT, + BFD_RELOC_NDS32_PTR_RESOLVED, + BFD_RELOC_NDS32_PLTBLOCK, + BFD_RELOC_NDS32_RELAX_REGION_BEGIN, + BFD_RELOC_NDS32_RELAX_REGION_END, + BFD_RELOC_NDS32_MINUEND, + BFD_RELOC_NDS32_SUBTRAHEND, + BFD_RELOC_NDS32_DIFF8, + BFD_RELOC_NDS32_DIFF16, + BFD_RELOC_NDS32_DIFF32, + BFD_RELOC_NDS32_DIFF_ULEB128, + BFD_RELOC_NDS32_25_ABS, + BFD_RELOC_NDS32_DATA, + BFD_RELOC_NDS32_TRAN, + BFD_RELOC_NDS32_17IFC_PCREL, + BFD_RELOC_NDS32_10IFCU_PCREL, + +/* This is a 9-bit reloc */ + BFD_RELOC_V850_9_PCREL, + +/* This is a 22-bit reloc */ + BFD_RELOC_V850_22_PCREL, + +/* This is a 16 bit offset from the short data area pointer. */ + BFD_RELOC_V850_SDA_16_16_OFFSET, + +/* This is a 16 bit offset (of which only 15 bits are used) from the +short data area pointer. */ + BFD_RELOC_V850_SDA_15_16_OFFSET, + +/* This is a 16 bit offset from the zero data area pointer. */ + BFD_RELOC_V850_ZDA_16_16_OFFSET, + +/* This is a 16 bit offset (of which only 15 bits are used) from the +zero data area pointer. */ + BFD_RELOC_V850_ZDA_15_16_OFFSET, + +/* This is an 8 bit offset (of which only 6 bits are used) from the +tiny data area pointer. */ + BFD_RELOC_V850_TDA_6_8_OFFSET, + +/* This is an 8bit offset (of which only 7 bits are used) from the tiny +data area pointer. */ + BFD_RELOC_V850_TDA_7_8_OFFSET, + +/* This is a 7 bit offset from the tiny data area pointer. */ + BFD_RELOC_V850_TDA_7_7_OFFSET, + +/* This is a 16 bit offset from the tiny data area pointer. */ + BFD_RELOC_V850_TDA_16_16_OFFSET, + +/* This is a 5 bit offset (of which only 4 bits are used) from the tiny +data area pointer. */ + BFD_RELOC_V850_TDA_4_5_OFFSET, + +/* This is a 4 bit offset from the tiny data area pointer. */ + BFD_RELOC_V850_TDA_4_4_OFFSET, + +/* This is a 16 bit offset from the short data area pointer, with the +bits placed non-contiguously in the instruction. */ + BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET, + +/* This is a 16 bit offset from the zero data area pointer, with the +bits placed non-contiguously in the instruction. */ + BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET, + +/* This is a 6 bit offset from the call table base pointer. */ + BFD_RELOC_V850_CALLT_6_7_OFFSET, + +/* This is a 16 bit offset from the call table base pointer. */ + BFD_RELOC_V850_CALLT_16_16_OFFSET, + +/* Used for relaxing indirect function calls. */ + BFD_RELOC_V850_LONGCALL, + +/* Used for relaxing indirect jumps. */ + BFD_RELOC_V850_LONGJUMP, + +/* Used to maintain alignment whilst relaxing. */ + BFD_RELOC_V850_ALIGN, + +/* This is a variation of BFD_RELOC_LO16 that can be used in v850e ld.bu +instructions. */ + BFD_RELOC_V850_LO16_SPLIT_OFFSET, + +/* This is a 16-bit reloc. */ + BFD_RELOC_V850_16_PCREL, + +/* This is a 17-bit reloc. */ + BFD_RELOC_V850_17_PCREL, + +/* This is a 23-bit reloc. */ + BFD_RELOC_V850_23, + +/* This is a 32-bit reloc. */ + BFD_RELOC_V850_32_PCREL, + +/* This is a 32-bit reloc. */ + BFD_RELOC_V850_32_ABS, + +/* This is a 16-bit reloc. */ + BFD_RELOC_V850_16_SPLIT_OFFSET, + +/* This is a 16-bit reloc. */ + BFD_RELOC_V850_16_S1, + +/* Low 16 bits. 16 bit shifted by 1. */ + BFD_RELOC_V850_LO16_S1, + +/* This is a 16 bit offset from the call table base pointer. */ + BFD_RELOC_V850_CALLT_15_16_OFFSET, + +/* DSO relocations. */ + BFD_RELOC_V850_32_GOTPCREL, + +/* DSO relocations. */ + BFD_RELOC_V850_16_GOT, + +/* DSO relocations. */ + BFD_RELOC_V850_32_GOT, + +/* DSO relocations. */ + BFD_RELOC_V850_22_PLT_PCREL, + +/* DSO relocations. */ + BFD_RELOC_V850_32_PLT_PCREL, + +/* DSO relocations. */ + BFD_RELOC_V850_COPY, + +/* DSO relocations. */ + BFD_RELOC_V850_GLOB_DAT, + +/* DSO relocations. */ + BFD_RELOC_V850_JMP_SLOT, + +/* DSO relocations. */ + BFD_RELOC_V850_RELATIVE, + +/* DSO relocations. */ + BFD_RELOC_V850_16_GOTOFF, + +/* DSO relocations. */ + BFD_RELOC_V850_32_GOTOFF, + +/* start code. */ + BFD_RELOC_V850_CODE, + +/* start data in text. */ + BFD_RELOC_V850_DATA, + +/* This is a 8bit DP reloc for the tms320c30, where the most +significant 8 bits of a 24 bit word are placed into the least +significant 8 bits of the opcode. */ + BFD_RELOC_TIC30_LDP, + +/* This is a 7bit reloc for the tms320c54x, where the least +significant 7 bits of a 16 bit word are placed into the least +significant 7 bits of the opcode. */ + BFD_RELOC_TIC54X_PARTLS7, + +/* This is a 9bit DP reloc for the tms320c54x, where the most +significant 9 bits of a 16 bit word are placed into the least +significant 9 bits of the opcode. */ + BFD_RELOC_TIC54X_PARTMS9, + +/* This is an extended address 23-bit reloc for the tms320c54x. */ + BFD_RELOC_TIC54X_23, + +/* This is a 16-bit reloc for the tms320c54x, where the least +significant 16 bits of a 23-bit extended address are placed into +the opcode. */ + BFD_RELOC_TIC54X_16_OF_23, + +/* This is a reloc for the tms320c54x, where the most +significant 7 bits of a 23-bit extended address are placed into +the opcode. */ + BFD_RELOC_TIC54X_MS7_OF_23, + +/* TMS320C6000 relocations. */ + BFD_RELOC_C6000_PCR_S21, + BFD_RELOC_C6000_PCR_S12, + BFD_RELOC_C6000_PCR_S10, + BFD_RELOC_C6000_PCR_S7, + BFD_RELOC_C6000_ABS_S16, + BFD_RELOC_C6000_ABS_L16, + BFD_RELOC_C6000_ABS_H16, + BFD_RELOC_C6000_SBR_U15_B, + BFD_RELOC_C6000_SBR_U15_H, + BFD_RELOC_C6000_SBR_U15_W, + BFD_RELOC_C6000_SBR_S16, + BFD_RELOC_C6000_SBR_L16_B, + BFD_RELOC_C6000_SBR_L16_H, + BFD_RELOC_C6000_SBR_L16_W, + BFD_RELOC_C6000_SBR_H16_B, + BFD_RELOC_C6000_SBR_H16_H, + BFD_RELOC_C6000_SBR_H16_W, + BFD_RELOC_C6000_SBR_GOT_U15_W, + BFD_RELOC_C6000_SBR_GOT_L16_W, + BFD_RELOC_C6000_SBR_GOT_H16_W, + BFD_RELOC_C6000_DSBT_INDEX, + BFD_RELOC_C6000_PREL31, + BFD_RELOC_C6000_COPY, + BFD_RELOC_C6000_JUMP_SLOT, + BFD_RELOC_C6000_EHTYPE, + BFD_RELOC_C6000_PCR_H16, + BFD_RELOC_C6000_PCR_L16, + BFD_RELOC_C6000_ALIGN, + BFD_RELOC_C6000_FPHEAD, + BFD_RELOC_C6000_NOCMP, + +/* This is a 48 bit reloc for the FR30 that stores 32 bits. */ + BFD_RELOC_FR30_48, + +/* This is a 32 bit reloc for the FR30 that stores 20 bits split up into +two sections. */ + BFD_RELOC_FR30_20, + +/* This is a 16 bit reloc for the FR30 that stores a 6 bit word offset in +4 bits. */ + BFD_RELOC_FR30_6_IN_4, + +/* This is a 16 bit reloc for the FR30 that stores an 8 bit byte offset +into 8 bits. */ + BFD_RELOC_FR30_8_IN_8, + +/* This is a 16 bit reloc for the FR30 that stores a 9 bit short offset +into 8 bits. */ + BFD_RELOC_FR30_9_IN_8, + +/* This is a 16 bit reloc for the FR30 that stores a 10 bit word offset +into 8 bits. */ + BFD_RELOC_FR30_10_IN_8, + +/* This is a 16 bit reloc for the FR30 that stores a 9 bit pc relative +short offset into 8 bits. */ + BFD_RELOC_FR30_9_PCREL, + +/* This is a 16 bit reloc for the FR30 that stores a 12 bit pc relative +short offset into 11 bits. */ + BFD_RELOC_FR30_12_PCREL, + +/* Motorola Mcore relocations. */ + BFD_RELOC_MCORE_PCREL_IMM8BY4, + BFD_RELOC_MCORE_PCREL_IMM11BY2, + BFD_RELOC_MCORE_PCREL_IMM4BY2, + BFD_RELOC_MCORE_PCREL_32, + BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2, + BFD_RELOC_MCORE_RVA, + +/* Toshiba Media Processor Relocations. */ + BFD_RELOC_MEP_8, + BFD_RELOC_MEP_16, + BFD_RELOC_MEP_32, + BFD_RELOC_MEP_PCREL8A2, + BFD_RELOC_MEP_PCREL12A2, + BFD_RELOC_MEP_PCREL17A2, + BFD_RELOC_MEP_PCREL24A2, + BFD_RELOC_MEP_PCABS24A2, + BFD_RELOC_MEP_LOW16, + BFD_RELOC_MEP_HI16U, + BFD_RELOC_MEP_HI16S, + BFD_RELOC_MEP_GPREL, + BFD_RELOC_MEP_TPREL, + BFD_RELOC_MEP_TPREL7, + BFD_RELOC_MEP_TPREL7A2, + BFD_RELOC_MEP_TPREL7A4, + BFD_RELOC_MEP_UIMM24, + BFD_RELOC_MEP_ADDR24A4, + BFD_RELOC_MEP_GNU_VTINHERIT, + BFD_RELOC_MEP_GNU_VTENTRY, + + +/* Imagination Technologies Meta relocations. */ + BFD_RELOC_METAG_HIADDR16, + BFD_RELOC_METAG_LOADDR16, + BFD_RELOC_METAG_RELBRANCH, + BFD_RELOC_METAG_GETSETOFF, + BFD_RELOC_METAG_HIOG, + BFD_RELOC_METAG_LOOG, + BFD_RELOC_METAG_REL8, + BFD_RELOC_METAG_REL16, + BFD_RELOC_METAG_HI16_GOTOFF, + BFD_RELOC_METAG_LO16_GOTOFF, + BFD_RELOC_METAG_GETSET_GOTOFF, + BFD_RELOC_METAG_GETSET_GOT, + BFD_RELOC_METAG_HI16_GOTPC, + BFD_RELOC_METAG_LO16_GOTPC, + BFD_RELOC_METAG_HI16_PLT, + BFD_RELOC_METAG_LO16_PLT, + BFD_RELOC_METAG_RELBRANCH_PLT, + BFD_RELOC_METAG_GOTOFF, + BFD_RELOC_METAG_PLT, + BFD_RELOC_METAG_COPY, + BFD_RELOC_METAG_JMP_SLOT, + BFD_RELOC_METAG_RELATIVE, + BFD_RELOC_METAG_GLOB_DAT, + BFD_RELOC_METAG_TLS_GD, + BFD_RELOC_METAG_TLS_LDM, + BFD_RELOC_METAG_TLS_LDO_HI16, + BFD_RELOC_METAG_TLS_LDO_LO16, + BFD_RELOC_METAG_TLS_LDO, + BFD_RELOC_METAG_TLS_IE, + BFD_RELOC_METAG_TLS_IENONPIC, + BFD_RELOC_METAG_TLS_IENONPIC_HI16, + BFD_RELOC_METAG_TLS_IENONPIC_LO16, + BFD_RELOC_METAG_TLS_TPOFF, + BFD_RELOC_METAG_TLS_DTPMOD, + BFD_RELOC_METAG_TLS_DTPOFF, + BFD_RELOC_METAG_TLS_LE, + BFD_RELOC_METAG_TLS_LE_HI16, + BFD_RELOC_METAG_TLS_LE_LO16, + +/* These are relocations for the GETA instruction. */ + BFD_RELOC_MMIX_GETA, + BFD_RELOC_MMIX_GETA_1, + BFD_RELOC_MMIX_GETA_2, + BFD_RELOC_MMIX_GETA_3, + +/* These are relocations for a conditional branch instruction. */ + BFD_RELOC_MMIX_CBRANCH, + BFD_RELOC_MMIX_CBRANCH_J, + BFD_RELOC_MMIX_CBRANCH_1, + BFD_RELOC_MMIX_CBRANCH_2, + BFD_RELOC_MMIX_CBRANCH_3, + +/* These are relocations for the PUSHJ instruction. */ + BFD_RELOC_MMIX_PUSHJ, + BFD_RELOC_MMIX_PUSHJ_1, + BFD_RELOC_MMIX_PUSHJ_2, + BFD_RELOC_MMIX_PUSHJ_3, + BFD_RELOC_MMIX_PUSHJ_STUBBABLE, + +/* These are relocations for the JMP instruction. */ + BFD_RELOC_MMIX_JMP, + BFD_RELOC_MMIX_JMP_1, + BFD_RELOC_MMIX_JMP_2, + BFD_RELOC_MMIX_JMP_3, + +/* This is a relocation for a relative address as in a GETA instruction or +a branch. */ + BFD_RELOC_MMIX_ADDR19, + +/* This is a relocation for a relative address as in a JMP instruction. */ + BFD_RELOC_MMIX_ADDR27, + +/* This is a relocation for an instruction field that may be a general +register or a value 0..255. */ + BFD_RELOC_MMIX_REG_OR_BYTE, + +/* This is a relocation for an instruction field that may be a general +register. */ + BFD_RELOC_MMIX_REG, + +/* This is a relocation for two instruction fields holding a register and +an offset, the equivalent of the relocation. */ + BFD_RELOC_MMIX_BASE_PLUS_OFFSET, + +/* This relocation is an assertion that the expression is not allocated as +a global register. It does not modify contents. */ + BFD_RELOC_MMIX_LOCAL, + +/* This is a 16 bit reloc for the AVR that stores 8 bit pc relative +short offset into 7 bits. */ + BFD_RELOC_AVR_7_PCREL, + +/* This is a 16 bit reloc for the AVR that stores 13 bit pc relative +short offset into 12 bits. */ + BFD_RELOC_AVR_13_PCREL, + +/* This is a 16 bit reloc for the AVR that stores 17 bit value (usually +program memory address) into 16 bits. */ + BFD_RELOC_AVR_16_PM, + +/* This is a 16 bit reloc for the AVR that stores 8 bit value (usually +data memory address) into 8 bit immediate value of LDI insn. */ + BFD_RELOC_AVR_LO8_LDI, + +/* This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit +of data memory address) into 8 bit immediate value of LDI insn. */ + BFD_RELOC_AVR_HI8_LDI, + +/* This is a 16 bit reloc for the AVR that stores 8 bit value (most high 8 bit +of program memory address) into 8 bit immediate value of LDI insn. */ + BFD_RELOC_AVR_HH8_LDI, + +/* This is a 16 bit reloc for the AVR that stores 8 bit value (most high 8 bit +of 32 bit value) into 8 bit immediate value of LDI insn. */ + BFD_RELOC_AVR_MS8_LDI, + +/* This is a 16 bit reloc for the AVR that stores negated 8 bit value +(usually data memory address) into 8 bit immediate value of SUBI insn. */ + BFD_RELOC_AVR_LO8_LDI_NEG, + +/* This is a 16 bit reloc for the AVR that stores negated 8 bit value +(high 8 bit of data memory address) into 8 bit immediate value of +SUBI insn. */ + BFD_RELOC_AVR_HI8_LDI_NEG, + +/* This is a 16 bit reloc for the AVR that stores negated 8 bit value +(most high 8 bit of program memory address) into 8 bit immediate value +of LDI or SUBI insn. */ + BFD_RELOC_AVR_HH8_LDI_NEG, + +/* This is a 16 bit reloc for the AVR that stores negated 8 bit value (msb +of 32 bit value) into 8 bit immediate value of LDI insn. */ + BFD_RELOC_AVR_MS8_LDI_NEG, + +/* This is a 16 bit reloc for the AVR that stores 8 bit value (usually +command address) into 8 bit immediate value of LDI insn. */ + BFD_RELOC_AVR_LO8_LDI_PM, + +/* This is a 16 bit reloc for the AVR that stores 8 bit value +(command address) into 8 bit immediate value of LDI insn. If the address +is beyond the 128k boundary, the linker inserts a jump stub for this reloc +in the lower 128k. */ + BFD_RELOC_AVR_LO8_LDI_GS, + +/* This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit +of command address) into 8 bit immediate value of LDI insn. */ + BFD_RELOC_AVR_HI8_LDI_PM, + +/* This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit +of command address) into 8 bit immediate value of LDI insn. If the address +is beyond the 128k boundary, the linker inserts a jump stub for this reloc +below 128k. */ + BFD_RELOC_AVR_HI8_LDI_GS, + +/* This is a 16 bit reloc for the AVR that stores 8 bit value (most high 8 bit +of command address) into 8 bit immediate value of LDI insn. */ + BFD_RELOC_AVR_HH8_LDI_PM, + +/* This is a 16 bit reloc for the AVR that stores negated 8 bit value +(usually command address) into 8 bit immediate value of SUBI insn. */ + BFD_RELOC_AVR_LO8_LDI_PM_NEG, + +/* This is a 16 bit reloc for the AVR that stores negated 8 bit value +(high 8 bit of 16 bit command address) into 8 bit immediate value +of SUBI insn. */ + BFD_RELOC_AVR_HI8_LDI_PM_NEG, + +/* This is a 16 bit reloc for the AVR that stores negated 8 bit value +(high 6 bit of 22 bit command address) into 8 bit immediate +value of SUBI insn. */ + BFD_RELOC_AVR_HH8_LDI_PM_NEG, + +/* This is a 32 bit reloc for the AVR that stores 23 bit value +into 22 bits. */ + BFD_RELOC_AVR_CALL, + +/* This is a 16 bit reloc for the AVR that stores all needed bits +for absolute addressing with ldi with overflow check to linktime */ + BFD_RELOC_AVR_LDI, + +/* This is a 6 bit reloc for the AVR that stores offset for ldd/std +instructions */ + BFD_RELOC_AVR_6, + +/* This is a 6 bit reloc for the AVR that stores offset for adiw/sbiw +instructions */ + BFD_RELOC_AVR_6_ADIW, + +/* This is a 8 bit reloc for the AVR that stores bits 0..7 of a symbol +in .byte lo8(symbol) */ + BFD_RELOC_AVR_8_LO, + +/* This is a 8 bit reloc for the AVR that stores bits 8..15 of a symbol +in .byte hi8(symbol) */ + BFD_RELOC_AVR_8_HI, + +/* This is a 8 bit reloc for the AVR that stores bits 16..23 of a symbol +in .byte hlo8(symbol) */ + BFD_RELOC_AVR_8_HLO, + +/* Renesas RL78 Relocations. */ + BFD_RELOC_RL78_NEG8, + BFD_RELOC_RL78_NEG16, + BFD_RELOC_RL78_NEG24, + BFD_RELOC_RL78_NEG32, + BFD_RELOC_RL78_16_OP, + BFD_RELOC_RL78_24_OP, + BFD_RELOC_RL78_32_OP, + BFD_RELOC_RL78_8U, + BFD_RELOC_RL78_16U, + BFD_RELOC_RL78_24U, + BFD_RELOC_RL78_DIR3U_PCREL, + BFD_RELOC_RL78_DIFF, + BFD_RELOC_RL78_GPRELB, + BFD_RELOC_RL78_GPRELW, + BFD_RELOC_RL78_GPRELL, + BFD_RELOC_RL78_SYM, + BFD_RELOC_RL78_OP_SUBTRACT, + BFD_RELOC_RL78_OP_NEG, + BFD_RELOC_RL78_OP_AND, + BFD_RELOC_RL78_OP_SHRA, + BFD_RELOC_RL78_ABS8, + BFD_RELOC_RL78_ABS16, + BFD_RELOC_RL78_ABS16_REV, + BFD_RELOC_RL78_ABS32, + BFD_RELOC_RL78_ABS32_REV, + BFD_RELOC_RL78_ABS16U, + BFD_RELOC_RL78_ABS16UW, + BFD_RELOC_RL78_ABS16UL, + BFD_RELOC_RL78_RELAX, + BFD_RELOC_RL78_HI16, + BFD_RELOC_RL78_HI8, + BFD_RELOC_RL78_LO16, + BFD_RELOC_RL78_CODE, + +/* Renesas RX Relocations. */ + BFD_RELOC_RX_NEG8, + BFD_RELOC_RX_NEG16, + BFD_RELOC_RX_NEG24, + BFD_RELOC_RX_NEG32, + BFD_RELOC_RX_16_OP, + BFD_RELOC_RX_24_OP, + BFD_RELOC_RX_32_OP, + BFD_RELOC_RX_8U, + BFD_RELOC_RX_16U, + BFD_RELOC_RX_24U, + BFD_RELOC_RX_DIR3U_PCREL, + BFD_RELOC_RX_DIFF, + BFD_RELOC_RX_GPRELB, + BFD_RELOC_RX_GPRELW, + BFD_RELOC_RX_GPRELL, + BFD_RELOC_RX_SYM, + BFD_RELOC_RX_OP_SUBTRACT, + BFD_RELOC_RX_OP_NEG, + BFD_RELOC_RX_ABS8, + BFD_RELOC_RX_ABS16, + BFD_RELOC_RX_ABS16_REV, + BFD_RELOC_RX_ABS32, + BFD_RELOC_RX_ABS32_REV, + BFD_RELOC_RX_ABS16U, + BFD_RELOC_RX_ABS16UW, + BFD_RELOC_RX_ABS16UL, + BFD_RELOC_RX_RELAX, + +/* Direct 12 bit. */ + BFD_RELOC_390_12, + +/* 12 bit GOT offset. */ + BFD_RELOC_390_GOT12, + +/* 32 bit PC relative PLT address. */ + BFD_RELOC_390_PLT32, + +/* Copy symbol at runtime. */ + BFD_RELOC_390_COPY, + +/* Create GOT entry. */ + BFD_RELOC_390_GLOB_DAT, + +/* Create PLT entry. */ + BFD_RELOC_390_JMP_SLOT, + +/* Adjust by program base. */ + BFD_RELOC_390_RELATIVE, + +/* 32 bit PC relative offset to GOT. */ + BFD_RELOC_390_GOTPC, + +/* 16 bit GOT offset. */ + BFD_RELOC_390_GOT16, + +/* PC relative 12 bit shifted by 1. */ + BFD_RELOC_390_PC12DBL, + +/* 12 bit PC rel. PLT shifted by 1. */ + BFD_RELOC_390_PLT12DBL, + +/* PC relative 16 bit shifted by 1. */ + BFD_RELOC_390_PC16DBL, + +/* 16 bit PC rel. PLT shifted by 1. */ + BFD_RELOC_390_PLT16DBL, + +/* PC relative 24 bit shifted by 1. */ + BFD_RELOC_390_PC24DBL, + +/* 24 bit PC rel. PLT shifted by 1. */ + BFD_RELOC_390_PLT24DBL, + +/* PC relative 32 bit shifted by 1. */ + BFD_RELOC_390_PC32DBL, + +/* 32 bit PC rel. PLT shifted by 1. */ + BFD_RELOC_390_PLT32DBL, + +/* 32 bit PC rel. GOT shifted by 1. */ + BFD_RELOC_390_GOTPCDBL, + +/* 64 bit GOT offset. */ + BFD_RELOC_390_GOT64, + +/* 64 bit PC relative PLT address. */ + BFD_RELOC_390_PLT64, + +/* 32 bit rel. offset to GOT entry. */ + BFD_RELOC_390_GOTENT, + +/* 64 bit offset to GOT. */ + BFD_RELOC_390_GOTOFF64, + +/* 12-bit offset to symbol-entry within GOT, with PLT handling. */ + BFD_RELOC_390_GOTPLT12, + +/* 16-bit offset to symbol-entry within GOT, with PLT handling. */ + BFD_RELOC_390_GOTPLT16, + +/* 32-bit offset to symbol-entry within GOT, with PLT handling. */ + BFD_RELOC_390_GOTPLT32, + +/* 64-bit offset to symbol-entry within GOT, with PLT handling. */ + BFD_RELOC_390_GOTPLT64, + +/* 32-bit rel. offset to symbol-entry within GOT, with PLT handling. */ + BFD_RELOC_390_GOTPLTENT, + +/* 16-bit rel. offset from the GOT to a PLT entry. */ + BFD_RELOC_390_PLTOFF16, + +/* 32-bit rel. offset from the GOT to a PLT entry. */ + BFD_RELOC_390_PLTOFF32, + +/* 64-bit rel. offset from the GOT to a PLT entry. */ + BFD_RELOC_390_PLTOFF64, + +/* s390 tls relocations. */ + BFD_RELOC_390_TLS_LOAD, + BFD_RELOC_390_TLS_GDCALL, + BFD_RELOC_390_TLS_LDCALL, + BFD_RELOC_390_TLS_GD32, + BFD_RELOC_390_TLS_GD64, + BFD_RELOC_390_TLS_GOTIE12, + BFD_RELOC_390_TLS_GOTIE32, + BFD_RELOC_390_TLS_GOTIE64, + BFD_RELOC_390_TLS_LDM32, + BFD_RELOC_390_TLS_LDM64, + BFD_RELOC_390_TLS_IE32, + BFD_RELOC_390_TLS_IE64, + BFD_RELOC_390_TLS_IEENT, + BFD_RELOC_390_TLS_LE32, + BFD_RELOC_390_TLS_LE64, + BFD_RELOC_390_TLS_LDO32, + BFD_RELOC_390_TLS_LDO64, + BFD_RELOC_390_TLS_DTPMOD, + BFD_RELOC_390_TLS_DTPOFF, + BFD_RELOC_390_TLS_TPOFF, + +/* Long displacement extension. */ + BFD_RELOC_390_20, + BFD_RELOC_390_GOT20, + BFD_RELOC_390_GOTPLT20, + BFD_RELOC_390_TLS_GOTIE20, + +/* STT_GNU_IFUNC relocation. */ + BFD_RELOC_390_IRELATIVE, + +/* Score relocations +Low 16 bit for load/store */ + BFD_RELOC_SCORE_GPREL15, + +/* This is a 24-bit reloc with the right 1 bit assumed to be 0 */ + BFD_RELOC_SCORE_DUMMY2, + BFD_RELOC_SCORE_JMP, + +/* This is a 19-bit reloc with the right 1 bit assumed to be 0 */ + BFD_RELOC_SCORE_BRANCH, + +/* This is a 32-bit reloc for 48-bit instructions. */ + BFD_RELOC_SCORE_IMM30, + +/* This is a 32-bit reloc for 48-bit instructions. */ + BFD_RELOC_SCORE_IMM32, + +/* This is a 11-bit reloc with the right 1 bit assumed to be 0 */ + BFD_RELOC_SCORE16_JMP, + +/* This is a 8-bit reloc with the right 1 bit assumed to be 0 */ + BFD_RELOC_SCORE16_BRANCH, + +/* This is a 9-bit reloc with the right 1 bit assumed to be 0 */ + BFD_RELOC_SCORE_BCMP, + +/* Undocumented Score relocs */ + BFD_RELOC_SCORE_GOT15, + BFD_RELOC_SCORE_GOT_LO16, + BFD_RELOC_SCORE_CALL15, + BFD_RELOC_SCORE_DUMMY_HI16, + +/* Scenix IP2K - 9-bit register number / data address */ + BFD_RELOC_IP2K_FR9, + +/* Scenix IP2K - 4-bit register/data bank number */ + BFD_RELOC_IP2K_BANK, + +/* Scenix IP2K - low 13 bits of instruction word address */ + BFD_RELOC_IP2K_ADDR16CJP, + +/* Scenix IP2K - high 3 bits of instruction word address */ + BFD_RELOC_IP2K_PAGE3, + +/* Scenix IP2K - ext/low/high 8 bits of data address */ + BFD_RELOC_IP2K_LO8DATA, + BFD_RELOC_IP2K_HI8DATA, + BFD_RELOC_IP2K_EX8DATA, + +/* Scenix IP2K - low/high 8 bits of instruction word address */ + BFD_RELOC_IP2K_LO8INSN, + BFD_RELOC_IP2K_HI8INSN, + +/* Scenix IP2K - even/odd PC modifier to modify snb pcl.0 */ + BFD_RELOC_IP2K_PC_SKIP, + +/* Scenix IP2K - 16 bit word address in text section. */ + BFD_RELOC_IP2K_TEXT, + +/* Scenix IP2K - 7-bit sp or dp offset */ + BFD_RELOC_IP2K_FR_OFFSET, + +/* Scenix VPE4K coprocessor - data/insn-space addressing */ + BFD_RELOC_VPE4KMATH_DATA, + BFD_RELOC_VPE4KMATH_INSN, + +/* These two relocations are used by the linker to determine which of +the entries in a C++ virtual function table are actually used. When +the --gc-sections option is given, the linker will zero out the entries +that are not used, so that the code for those functions need not be +included in the output. + +VTABLE_INHERIT is a zero-space relocation used to describe to the +linker the inheritance tree of a C++ virtual function table. The +relocation's symbol should be the parent class' vtable, and the +relocation should be located at the child vtable. + +VTABLE_ENTRY is a zero-space relocation that describes the use of a +virtual function table entry. The reloc's symbol should refer to the +table of the class mentioned in the code. Off of that base, an offset +describes the entry that is being used. For Rela hosts, this offset +is stored in the reloc's addend. For Rel hosts, we are forced to put +this offset in the reloc's section offset. */ + BFD_RELOC_VTABLE_INHERIT, + BFD_RELOC_VTABLE_ENTRY, + +/* Intel IA64 Relocations. */ + BFD_RELOC_IA64_IMM14, + BFD_RELOC_IA64_IMM22, + BFD_RELOC_IA64_IMM64, + BFD_RELOC_IA64_DIR32MSB, + BFD_RELOC_IA64_DIR32LSB, + BFD_RELOC_IA64_DIR64MSB, + BFD_RELOC_IA64_DIR64LSB, + BFD_RELOC_IA64_GPREL22, + BFD_RELOC_IA64_GPREL64I, + BFD_RELOC_IA64_GPREL32MSB, + BFD_RELOC_IA64_GPREL32LSB, + BFD_RELOC_IA64_GPREL64MSB, + BFD_RELOC_IA64_GPREL64LSB, + BFD_RELOC_IA64_LTOFF22, + BFD_RELOC_IA64_LTOFF64I, + BFD_RELOC_IA64_PLTOFF22, + BFD_RELOC_IA64_PLTOFF64I, + BFD_RELOC_IA64_PLTOFF64MSB, + BFD_RELOC_IA64_PLTOFF64LSB, + BFD_RELOC_IA64_FPTR64I, + BFD_RELOC_IA64_FPTR32MSB, + BFD_RELOC_IA64_FPTR32LSB, + BFD_RELOC_IA64_FPTR64MSB, + BFD_RELOC_IA64_FPTR64LSB, + BFD_RELOC_IA64_PCREL21B, + BFD_RELOC_IA64_PCREL21BI, + BFD_RELOC_IA64_PCREL21M, + BFD_RELOC_IA64_PCREL21F, + BFD_RELOC_IA64_PCREL22, + BFD_RELOC_IA64_PCREL60B, + BFD_RELOC_IA64_PCREL64I, + BFD_RELOC_IA64_PCREL32MSB, + BFD_RELOC_IA64_PCREL32LSB, + BFD_RELOC_IA64_PCREL64MSB, + BFD_RELOC_IA64_PCREL64LSB, + BFD_RELOC_IA64_LTOFF_FPTR22, + BFD_RELOC_IA64_LTOFF_FPTR64I, + BFD_RELOC_IA64_LTOFF_FPTR32MSB, + BFD_RELOC_IA64_LTOFF_FPTR32LSB, + BFD_RELOC_IA64_LTOFF_FPTR64MSB, + BFD_RELOC_IA64_LTOFF_FPTR64LSB, + BFD_RELOC_IA64_SEGREL32MSB, + BFD_RELOC_IA64_SEGREL32LSB, + BFD_RELOC_IA64_SEGREL64MSB, + BFD_RELOC_IA64_SEGREL64LSB, + BFD_RELOC_IA64_SECREL32MSB, + BFD_RELOC_IA64_SECREL32LSB, + BFD_RELOC_IA64_SECREL64MSB, + BFD_RELOC_IA64_SECREL64LSB, + BFD_RELOC_IA64_REL32MSB, + BFD_RELOC_IA64_REL32LSB, + BFD_RELOC_IA64_REL64MSB, + BFD_RELOC_IA64_REL64LSB, + BFD_RELOC_IA64_LTV32MSB, + BFD_RELOC_IA64_LTV32LSB, + BFD_RELOC_IA64_LTV64MSB, + BFD_RELOC_IA64_LTV64LSB, + BFD_RELOC_IA64_IPLTMSB, + BFD_RELOC_IA64_IPLTLSB, + BFD_RELOC_IA64_COPY, + BFD_RELOC_IA64_LTOFF22X, + BFD_RELOC_IA64_LDXMOV, + BFD_RELOC_IA64_TPREL14, + BFD_RELOC_IA64_TPREL22, + BFD_RELOC_IA64_TPREL64I, + BFD_RELOC_IA64_TPREL64MSB, + BFD_RELOC_IA64_TPREL64LSB, + BFD_RELOC_IA64_LTOFF_TPREL22, + BFD_RELOC_IA64_DTPMOD64MSB, + BFD_RELOC_IA64_DTPMOD64LSB, + BFD_RELOC_IA64_LTOFF_DTPMOD22, + BFD_RELOC_IA64_DTPREL14, + BFD_RELOC_IA64_DTPREL22, + BFD_RELOC_IA64_DTPREL64I, + BFD_RELOC_IA64_DTPREL32MSB, + BFD_RELOC_IA64_DTPREL32LSB, + BFD_RELOC_IA64_DTPREL64MSB, + BFD_RELOC_IA64_DTPREL64LSB, + BFD_RELOC_IA64_LTOFF_DTPREL22, + +/* Motorola 68HC11 reloc. +This is the 8 bit high part of an absolute address. */ + BFD_RELOC_M68HC11_HI8, + +/* Motorola 68HC11 reloc. +This is the 8 bit low part of an absolute address. */ + BFD_RELOC_M68HC11_LO8, + +/* Motorola 68HC11 reloc. +This is the 3 bit of a value. */ + BFD_RELOC_M68HC11_3B, + +/* Motorola 68HC11 reloc. +This reloc marks the beginning of a jump/call instruction. +It is used for linker relaxation to correctly identify beginning +of instruction and change some branches to use PC-relative +addressing mode. */ + BFD_RELOC_M68HC11_RL_JUMP, + +/* Motorola 68HC11 reloc. +This reloc marks a group of several instructions that gcc generates +and for which the linker relaxation pass can modify and/or remove +some of them. */ + BFD_RELOC_M68HC11_RL_GROUP, + +/* Motorola 68HC11 reloc. +This is the 16-bit lower part of an address. It is used for 'call' +instruction to specify the symbol address without any special +transformation (due to memory bank window). */ + BFD_RELOC_M68HC11_LO16, + +/* Motorola 68HC11 reloc. +This is a 8-bit reloc that specifies the page number of an address. +It is used by 'call' instruction to specify the page number of +the symbol. */ + BFD_RELOC_M68HC11_PAGE, + +/* Motorola 68HC11 reloc. +This is a 24-bit reloc that represents the address with a 16-bit +value and a 8-bit page number. The symbol address is transformed +to follow the 16K memory bank of 68HC12 (seen as mapped in the window). */ + BFD_RELOC_M68HC11_24, + +/* Motorola 68HC12 reloc. +This is the 5 bits of a value. */ + BFD_RELOC_M68HC12_5B, + +/* Freescale XGATE reloc. +This reloc marks the beginning of a bra/jal instruction. */ + BFD_RELOC_XGATE_RL_JUMP, + +/* Freescale XGATE reloc. +This reloc marks a group of several instructions that gcc generates +and for which the linker relaxation pass can modify and/or remove +some of them. */ + BFD_RELOC_XGATE_RL_GROUP, + +/* Freescale XGATE reloc. +This is the 16-bit lower part of an address. It is used for the '16-bit' +instructions. */ + BFD_RELOC_XGATE_LO16, + +/* Freescale XGATE reloc. */ + BFD_RELOC_XGATE_GPAGE, + +/* Freescale XGATE reloc. */ + BFD_RELOC_XGATE_24, + +/* Freescale XGATE reloc. +This is a 9-bit pc-relative reloc. */ + BFD_RELOC_XGATE_PCREL_9, + +/* Freescale XGATE reloc. +This is a 10-bit pc-relative reloc. */ + BFD_RELOC_XGATE_PCREL_10, + +/* Freescale XGATE reloc. +This is the 16-bit lower part of an address. It is used for the '16-bit' +instructions. */ + BFD_RELOC_XGATE_IMM8_LO, + +/* Freescale XGATE reloc. +This is the 16-bit higher part of an address. It is used for the '16-bit' +instructions. */ + BFD_RELOC_XGATE_IMM8_HI, + +/* Freescale XGATE reloc. +This is a 3-bit pc-relative reloc. */ + BFD_RELOC_XGATE_IMM3, + +/* Freescale XGATE reloc. +This is a 4-bit pc-relative reloc. */ + BFD_RELOC_XGATE_IMM4, + +/* Freescale XGATE reloc. +This is a 5-bit pc-relative reloc. */ + BFD_RELOC_XGATE_IMM5, + +/* Motorola 68HC12 reloc. +This is the 9 bits of a value. */ + BFD_RELOC_M68HC12_9B, + +/* Motorola 68HC12 reloc. +This is the 16 bits of a value. */ + BFD_RELOC_M68HC12_16B, + +/* Motorola 68HC12/XGATE reloc. +This is a PCREL9 branch. */ + BFD_RELOC_M68HC12_9_PCREL, + +/* Motorola 68HC12/XGATE reloc. +This is a PCREL10 branch. */ + BFD_RELOC_M68HC12_10_PCREL, + +/* Motorola 68HC12/XGATE reloc. +This is the 8 bit low part of an absolute address and immediately precedes +a matching HI8XG part. */ + BFD_RELOC_M68HC12_LO8XG, + +/* Motorola 68HC12/XGATE reloc. +This is the 8 bit high part of an absolute address and immediately follows +a matching LO8XG part. */ + BFD_RELOC_M68HC12_HI8XG, + +/* NS CR16C Relocations. */ + BFD_RELOC_16C_NUM08, + BFD_RELOC_16C_NUM08_C, + BFD_RELOC_16C_NUM16, + BFD_RELOC_16C_NUM16_C, + BFD_RELOC_16C_NUM32, + BFD_RELOC_16C_NUM32_C, + BFD_RELOC_16C_DISP04, + BFD_RELOC_16C_DISP04_C, + BFD_RELOC_16C_DISP08, + BFD_RELOC_16C_DISP08_C, + BFD_RELOC_16C_DISP16, + BFD_RELOC_16C_DISP16_C, + BFD_RELOC_16C_DISP24, + BFD_RELOC_16C_DISP24_C, + BFD_RELOC_16C_DISP24a, + BFD_RELOC_16C_DISP24a_C, + BFD_RELOC_16C_REG04, + BFD_RELOC_16C_REG04_C, + BFD_RELOC_16C_REG04a, + BFD_RELOC_16C_REG04a_C, + BFD_RELOC_16C_REG14, + BFD_RELOC_16C_REG14_C, + BFD_RELOC_16C_REG16, + BFD_RELOC_16C_REG16_C, + BFD_RELOC_16C_REG20, + BFD_RELOC_16C_REG20_C, + BFD_RELOC_16C_ABS20, + BFD_RELOC_16C_ABS20_C, + BFD_RELOC_16C_ABS24, + BFD_RELOC_16C_ABS24_C, + BFD_RELOC_16C_IMM04, + BFD_RELOC_16C_IMM04_C, + BFD_RELOC_16C_IMM16, + BFD_RELOC_16C_IMM16_C, + BFD_RELOC_16C_IMM20, + BFD_RELOC_16C_IMM20_C, + BFD_RELOC_16C_IMM24, + BFD_RELOC_16C_IMM24_C, + BFD_RELOC_16C_IMM32, + BFD_RELOC_16C_IMM32_C, + +/* NS CR16 Relocations. */ + BFD_RELOC_CR16_NUM8, + BFD_RELOC_CR16_NUM16, + BFD_RELOC_CR16_NUM32, + BFD_RELOC_CR16_NUM32a, + BFD_RELOC_CR16_REGREL0, + BFD_RELOC_CR16_REGREL4, + BFD_RELOC_CR16_REGREL4a, + BFD_RELOC_CR16_REGREL14, + BFD_RELOC_CR16_REGREL14a, + BFD_RELOC_CR16_REGREL16, + BFD_RELOC_CR16_REGREL20, + BFD_RELOC_CR16_REGREL20a, + BFD_RELOC_CR16_ABS20, + BFD_RELOC_CR16_ABS24, + BFD_RELOC_CR16_IMM4, + BFD_RELOC_CR16_IMM8, + BFD_RELOC_CR16_IMM16, + BFD_RELOC_CR16_IMM20, + BFD_RELOC_CR16_IMM24, + BFD_RELOC_CR16_IMM32, + BFD_RELOC_CR16_IMM32a, + BFD_RELOC_CR16_DISP4, + BFD_RELOC_CR16_DISP8, + BFD_RELOC_CR16_DISP16, + BFD_RELOC_CR16_DISP20, + BFD_RELOC_CR16_DISP24, + BFD_RELOC_CR16_DISP24a, + BFD_RELOC_CR16_SWITCH8, + BFD_RELOC_CR16_SWITCH16, + BFD_RELOC_CR16_SWITCH32, + BFD_RELOC_CR16_GOT_REGREL20, + BFD_RELOC_CR16_GOTC_REGREL20, + BFD_RELOC_CR16_GLOB_DAT, + +/* NS CRX Relocations. */ + BFD_RELOC_CRX_REL4, + BFD_RELOC_CRX_REL8, + BFD_RELOC_CRX_REL8_CMP, + BFD_RELOC_CRX_REL16, + BFD_RELOC_CRX_REL24, + BFD_RELOC_CRX_REL32, + BFD_RELOC_CRX_REGREL12, + BFD_RELOC_CRX_REGREL22, + BFD_RELOC_CRX_REGREL28, + BFD_RELOC_CRX_REGREL32, + BFD_RELOC_CRX_ABS16, + BFD_RELOC_CRX_ABS32, + BFD_RELOC_CRX_NUM8, + BFD_RELOC_CRX_NUM16, + BFD_RELOC_CRX_NUM32, + BFD_RELOC_CRX_IMM16, + BFD_RELOC_CRX_IMM32, + BFD_RELOC_CRX_SWITCH8, + BFD_RELOC_CRX_SWITCH16, + BFD_RELOC_CRX_SWITCH32, + +/* These relocs are only used within the CRIS assembler. They are not +(at present) written to any object files. */ + BFD_RELOC_CRIS_BDISP8, + BFD_RELOC_CRIS_UNSIGNED_5, + BFD_RELOC_CRIS_SIGNED_6, + BFD_RELOC_CRIS_UNSIGNED_6, + BFD_RELOC_CRIS_SIGNED_8, + BFD_RELOC_CRIS_UNSIGNED_8, + BFD_RELOC_CRIS_SIGNED_16, + BFD_RELOC_CRIS_UNSIGNED_16, + BFD_RELOC_CRIS_LAPCQ_OFFSET, + BFD_RELOC_CRIS_UNSIGNED_4, + +/* Relocs used in ELF shared libraries for CRIS. */ + BFD_RELOC_CRIS_COPY, + BFD_RELOC_CRIS_GLOB_DAT, + BFD_RELOC_CRIS_JUMP_SLOT, + BFD_RELOC_CRIS_RELATIVE, + +/* 32-bit offset to symbol-entry within GOT. */ + BFD_RELOC_CRIS_32_GOT, + +/* 16-bit offset to symbol-entry within GOT. */ + BFD_RELOC_CRIS_16_GOT, + +/* 32-bit offset to symbol-entry within GOT, with PLT handling. */ + BFD_RELOC_CRIS_32_GOTPLT, + +/* 16-bit offset to symbol-entry within GOT, with PLT handling. */ + BFD_RELOC_CRIS_16_GOTPLT, + +/* 32-bit offset to symbol, relative to GOT. */ + BFD_RELOC_CRIS_32_GOTREL, + +/* 32-bit offset to symbol with PLT entry, relative to GOT. */ + BFD_RELOC_CRIS_32_PLT_GOTREL, + +/* 32-bit offset to symbol with PLT entry, relative to this relocation. */ + BFD_RELOC_CRIS_32_PLT_PCREL, + +/* Relocs used in TLS code for CRIS. */ + BFD_RELOC_CRIS_32_GOT_GD, + BFD_RELOC_CRIS_16_GOT_GD, + BFD_RELOC_CRIS_32_GD, + BFD_RELOC_CRIS_DTP, + BFD_RELOC_CRIS_32_DTPREL, + BFD_RELOC_CRIS_16_DTPREL, + BFD_RELOC_CRIS_32_GOT_TPREL, + BFD_RELOC_CRIS_16_GOT_TPREL, + BFD_RELOC_CRIS_32_TPREL, + BFD_RELOC_CRIS_16_TPREL, + BFD_RELOC_CRIS_DTPMOD, + BFD_RELOC_CRIS_32_IE, + +/* Intel i860 Relocations. */ + BFD_RELOC_860_COPY, + BFD_RELOC_860_GLOB_DAT, + BFD_RELOC_860_JUMP_SLOT, + BFD_RELOC_860_RELATIVE, + BFD_RELOC_860_PC26, + BFD_RELOC_860_PLT26, + BFD_RELOC_860_PC16, + BFD_RELOC_860_LOW0, + BFD_RELOC_860_SPLIT0, + BFD_RELOC_860_LOW1, + BFD_RELOC_860_SPLIT1, + BFD_RELOC_860_LOW2, + BFD_RELOC_860_SPLIT2, + BFD_RELOC_860_LOW3, + BFD_RELOC_860_LOGOT0, + BFD_RELOC_860_SPGOT0, + BFD_RELOC_860_LOGOT1, + BFD_RELOC_860_SPGOT1, + BFD_RELOC_860_LOGOTOFF0, + BFD_RELOC_860_SPGOTOFF0, + BFD_RELOC_860_LOGOTOFF1, + BFD_RELOC_860_SPGOTOFF1, + BFD_RELOC_860_LOGOTOFF2, + BFD_RELOC_860_LOGOTOFF3, + BFD_RELOC_860_LOPC, + BFD_RELOC_860_HIGHADJ, + BFD_RELOC_860_HAGOT, + BFD_RELOC_860_HAGOTOFF, + BFD_RELOC_860_HAPC, + BFD_RELOC_860_HIGH, + BFD_RELOC_860_HIGOT, + BFD_RELOC_860_HIGOTOFF, + +/* OpenRISC Relocations. */ + BFD_RELOC_OPENRISC_ABS_26, + BFD_RELOC_OPENRISC_REL_26, + +/* H8 elf Relocations. */ + BFD_RELOC_H8_DIR16A8, + BFD_RELOC_H8_DIR16R8, + BFD_RELOC_H8_DIR24A8, + BFD_RELOC_H8_DIR24R8, + BFD_RELOC_H8_DIR32A16, + BFD_RELOC_H8_DISP32A16, + +/* Sony Xstormy16 Relocations. */ + BFD_RELOC_XSTORMY16_REL_12, + BFD_RELOC_XSTORMY16_12, + BFD_RELOC_XSTORMY16_24, + BFD_RELOC_XSTORMY16_FPTR16, + +/* Self-describing complex relocations. */ + BFD_RELOC_RELC, + + +/* Infineon Relocations. */ + BFD_RELOC_XC16X_PAG, + BFD_RELOC_XC16X_POF, + BFD_RELOC_XC16X_SEG, + BFD_RELOC_XC16X_SOF, + +/* Relocations used by VAX ELF. */ + BFD_RELOC_VAX_GLOB_DAT, + BFD_RELOC_VAX_JMP_SLOT, + BFD_RELOC_VAX_RELATIVE, + +/* Morpho MT - 16 bit immediate relocation. */ + BFD_RELOC_MT_PC16, + +/* Morpho MT - Hi 16 bits of an address. */ + BFD_RELOC_MT_HI16, + +/* Morpho MT - Low 16 bits of an address. */ + BFD_RELOC_MT_LO16, + +/* Morpho MT - Used to tell the linker which vtable entries are used. */ + BFD_RELOC_MT_GNU_VTINHERIT, + +/* Morpho MT - Used to tell the linker which vtable entries are used. */ + BFD_RELOC_MT_GNU_VTENTRY, + +/* Morpho MT - 8 bit immediate relocation. */ + BFD_RELOC_MT_PCINSN8, + +/* msp430 specific relocation codes */ + BFD_RELOC_MSP430_10_PCREL, + BFD_RELOC_MSP430_16_PCREL, + BFD_RELOC_MSP430_16, + BFD_RELOC_MSP430_16_PCREL_BYTE, + BFD_RELOC_MSP430_16_BYTE, + BFD_RELOC_MSP430_2X_PCREL, + BFD_RELOC_MSP430_RL_PCREL, + BFD_RELOC_MSP430_ABS8, + BFD_RELOC_MSP430X_PCR20_EXT_SRC, + BFD_RELOC_MSP430X_PCR20_EXT_DST, + BFD_RELOC_MSP430X_PCR20_EXT_ODST, + BFD_RELOC_MSP430X_ABS20_EXT_SRC, + BFD_RELOC_MSP430X_ABS20_EXT_DST, + BFD_RELOC_MSP430X_ABS20_EXT_ODST, + BFD_RELOC_MSP430X_ABS20_ADR_SRC, + BFD_RELOC_MSP430X_ABS20_ADR_DST, + BFD_RELOC_MSP430X_PCR16, + BFD_RELOC_MSP430X_PCR20_CALL, + BFD_RELOC_MSP430X_ABS16, + BFD_RELOC_MSP430_ABS_HI16, + BFD_RELOC_MSP430_PREL31, + BFD_RELOC_MSP430_SYM_DIFF, + +/* Relocations used by the Altera Nios II core. */ + BFD_RELOC_NIOS2_S16, + BFD_RELOC_NIOS2_U16, + BFD_RELOC_NIOS2_CALL26, + BFD_RELOC_NIOS2_IMM5, + BFD_RELOC_NIOS2_CACHE_OPX, + BFD_RELOC_NIOS2_IMM6, + BFD_RELOC_NIOS2_IMM8, + BFD_RELOC_NIOS2_HI16, + BFD_RELOC_NIOS2_LO16, + BFD_RELOC_NIOS2_HIADJ16, + BFD_RELOC_NIOS2_GPREL, + BFD_RELOC_NIOS2_UJMP, + BFD_RELOC_NIOS2_CJMP, + BFD_RELOC_NIOS2_CALLR, + BFD_RELOC_NIOS2_ALIGN, + BFD_RELOC_NIOS2_GOT16, + BFD_RELOC_NIOS2_CALL16, + BFD_RELOC_NIOS2_GOTOFF_LO, + BFD_RELOC_NIOS2_GOTOFF_HA, + BFD_RELOC_NIOS2_PCREL_LO, + BFD_RELOC_NIOS2_PCREL_HA, + BFD_RELOC_NIOS2_TLS_GD16, + BFD_RELOC_NIOS2_TLS_LDM16, + BFD_RELOC_NIOS2_TLS_LDO16, + BFD_RELOC_NIOS2_TLS_IE16, + BFD_RELOC_NIOS2_TLS_LE16, + BFD_RELOC_NIOS2_TLS_DTPMOD, + BFD_RELOC_NIOS2_TLS_DTPREL, + BFD_RELOC_NIOS2_TLS_TPREL, + BFD_RELOC_NIOS2_COPY, + BFD_RELOC_NIOS2_GLOB_DAT, + BFD_RELOC_NIOS2_JUMP_SLOT, + BFD_RELOC_NIOS2_RELATIVE, + BFD_RELOC_NIOS2_GOTOFF, + +/* IQ2000 Relocations. */ + BFD_RELOC_IQ2000_OFFSET_16, + BFD_RELOC_IQ2000_OFFSET_21, + BFD_RELOC_IQ2000_UHI16, + +/* Special Xtensa relocation used only by PLT entries in ELF shared +objects to indicate that the runtime linker should set the value +to one of its own internal functions or data structures. */ + BFD_RELOC_XTENSA_RTLD, + +/* Xtensa relocations for ELF shared objects. */ + BFD_RELOC_XTENSA_GLOB_DAT, + BFD_RELOC_XTENSA_JMP_SLOT, + BFD_RELOC_XTENSA_RELATIVE, + +/* Xtensa relocation used in ELF object files for symbols that may require +PLT entries. Otherwise, this is just a generic 32-bit relocation. */ + BFD_RELOC_XTENSA_PLT, + +/* Xtensa relocations to mark the difference of two local symbols. +These are only needed to support linker relaxation and can be ignored +when not relaxing. The field is set to the value of the difference +assuming no relaxation. The relocation encodes the position of the +first symbol so the linker can determine whether to adjust the field +value. */ + BFD_RELOC_XTENSA_DIFF8, + BFD_RELOC_XTENSA_DIFF16, + BFD_RELOC_XTENSA_DIFF32, + +/* Generic Xtensa relocations for instruction operands. Only the slot +number is encoded in the relocation. The relocation applies to the +last PC-relative immediate operand, or if there are no PC-relative +immediates, to the last immediate operand. */ + BFD_RELOC_XTENSA_SLOT0_OP, + BFD_RELOC_XTENSA_SLOT1_OP, + BFD_RELOC_XTENSA_SLOT2_OP, + BFD_RELOC_XTENSA_SLOT3_OP, + BFD_RELOC_XTENSA_SLOT4_OP, + BFD_RELOC_XTENSA_SLOT5_OP, + BFD_RELOC_XTENSA_SLOT6_OP, + BFD_RELOC_XTENSA_SLOT7_OP, + BFD_RELOC_XTENSA_SLOT8_OP, + BFD_RELOC_XTENSA_SLOT9_OP, + BFD_RELOC_XTENSA_SLOT10_OP, + BFD_RELOC_XTENSA_SLOT11_OP, + BFD_RELOC_XTENSA_SLOT12_OP, + BFD_RELOC_XTENSA_SLOT13_OP, + BFD_RELOC_XTENSA_SLOT14_OP, + +/* Alternate Xtensa relocations. Only the slot is encoded in the +relocation. The meaning of these relocations is opcode-specific. */ + BFD_RELOC_XTENSA_SLOT0_ALT, + BFD_RELOC_XTENSA_SLOT1_ALT, + BFD_RELOC_XTENSA_SLOT2_ALT, + BFD_RELOC_XTENSA_SLOT3_ALT, + BFD_RELOC_XTENSA_SLOT4_ALT, + BFD_RELOC_XTENSA_SLOT5_ALT, + BFD_RELOC_XTENSA_SLOT6_ALT, + BFD_RELOC_XTENSA_SLOT7_ALT, + BFD_RELOC_XTENSA_SLOT8_ALT, + BFD_RELOC_XTENSA_SLOT9_ALT, + BFD_RELOC_XTENSA_SLOT10_ALT, + BFD_RELOC_XTENSA_SLOT11_ALT, + BFD_RELOC_XTENSA_SLOT12_ALT, + BFD_RELOC_XTENSA_SLOT13_ALT, + BFD_RELOC_XTENSA_SLOT14_ALT, + +/* Xtensa relocations for backward compatibility. These have all been +replaced by BFD_RELOC_XTENSA_SLOT0_OP. */ + BFD_RELOC_XTENSA_OP0, + BFD_RELOC_XTENSA_OP1, + BFD_RELOC_XTENSA_OP2, + +/* Xtensa relocation to mark that the assembler expanded the +instructions from an original target. The expansion size is +encoded in the reloc size. */ + BFD_RELOC_XTENSA_ASM_EXPAND, + +/* Xtensa relocation to mark that the linker should simplify +assembler-expanded instructions. This is commonly used +internally by the linker after analysis of a +BFD_RELOC_XTENSA_ASM_EXPAND. */ + BFD_RELOC_XTENSA_ASM_SIMPLIFY, + +/* Xtensa TLS relocations. */ + BFD_RELOC_XTENSA_TLSDESC_FN, + BFD_RELOC_XTENSA_TLSDESC_ARG, + BFD_RELOC_XTENSA_TLS_DTPOFF, + BFD_RELOC_XTENSA_TLS_TPOFF, + BFD_RELOC_XTENSA_TLS_FUNC, + BFD_RELOC_XTENSA_TLS_ARG, + BFD_RELOC_XTENSA_TLS_CALL, + +/* 8 bit signed offset in (ix+d) or (iy+d). */ + BFD_RELOC_Z80_DISP8, + +/* DJNZ offset. */ + BFD_RELOC_Z8K_DISP7, + +/* CALR offset. */ + BFD_RELOC_Z8K_CALLR, + +/* 4 bit value. */ + BFD_RELOC_Z8K_IMM4L, + +/* Lattice Mico32 relocations. */ + BFD_RELOC_LM32_CALL, + BFD_RELOC_LM32_BRANCH, + BFD_RELOC_LM32_16_GOT, + BFD_RELOC_LM32_GOTOFF_HI16, + BFD_RELOC_LM32_GOTOFF_LO16, + BFD_RELOC_LM32_COPY, + BFD_RELOC_LM32_GLOB_DAT, + BFD_RELOC_LM32_JMP_SLOT, + BFD_RELOC_LM32_RELATIVE, + +/* Difference between two section addreses. Must be followed by a +BFD_RELOC_MACH_O_PAIR. */ + BFD_RELOC_MACH_O_SECTDIFF, + +/* Like BFD_RELOC_MACH_O_SECTDIFF but with a local symbol. */ + BFD_RELOC_MACH_O_LOCAL_SECTDIFF, + +/* Pair of relocation. Contains the first symbol. */ + BFD_RELOC_MACH_O_PAIR, + +/* PCREL relocations. They are marked as branch to create PLT entry if +required. */ + BFD_RELOC_MACH_O_X86_64_BRANCH32, + BFD_RELOC_MACH_O_X86_64_BRANCH8, + +/* Used when referencing a GOT entry. */ + BFD_RELOC_MACH_O_X86_64_GOT, + +/* Used when loading a GOT entry with movq. It is specially marked so that +the linker could optimize the movq to a leaq if possible. */ + BFD_RELOC_MACH_O_X86_64_GOT_LOAD, + +/* Symbol will be substracted. Must be followed by a BFD_RELOC_64. */ + BFD_RELOC_MACH_O_X86_64_SUBTRACTOR32, + +/* Symbol will be substracted. Must be followed by a BFD_RELOC_64. */ + BFD_RELOC_MACH_O_X86_64_SUBTRACTOR64, + +/* Same as BFD_RELOC_32_PCREL but with an implicit -1 addend. */ + BFD_RELOC_MACH_O_X86_64_PCREL32_1, + +/* Same as BFD_RELOC_32_PCREL but with an implicit -2 addend. */ + BFD_RELOC_MACH_O_X86_64_PCREL32_2, + +/* Same as BFD_RELOC_32_PCREL but with an implicit -4 addend. */ + BFD_RELOC_MACH_O_X86_64_PCREL32_4, + +/* This is a 32 bit reloc for the microblaze that stores the +low 16 bits of a value */ + BFD_RELOC_MICROBLAZE_32_LO, + +/* This is a 32 bit pc-relative reloc for the microblaze that +stores the low 16 bits of a value */ + BFD_RELOC_MICROBLAZE_32_LO_PCREL, + +/* This is a 32 bit reloc for the microblaze that stores a +value relative to the read-only small data area anchor */ + BFD_RELOC_MICROBLAZE_32_ROSDA, + +/* This is a 32 bit reloc for the microblaze that stores a +value relative to the read-write small data area anchor */ + BFD_RELOC_MICROBLAZE_32_RWSDA, + +/* This is a 32 bit reloc for the microblaze to handle +expressions of the form "Symbol Op Symbol" */ + BFD_RELOC_MICROBLAZE_32_SYM_OP_SYM, + +/* This is a 64 bit reloc that stores the 32 bit pc relative +value in two words (with an imm instruction). No relocation is +done here - only used for relaxing */ + BFD_RELOC_MICROBLAZE_64_NONE, + +/* This is a 64 bit reloc that stores the 32 bit pc relative +value in two words (with an imm instruction). The relocation is +PC-relative GOT offset */ + BFD_RELOC_MICROBLAZE_64_GOTPC, + +/* This is a 64 bit reloc that stores the 32 bit pc relative +value in two words (with an imm instruction). The relocation is +GOT offset */ + BFD_RELOC_MICROBLAZE_64_GOT, + +/* This is a 64 bit reloc that stores the 32 bit pc relative +value in two words (with an imm instruction). The relocation is +PC-relative offset into PLT */ + BFD_RELOC_MICROBLAZE_64_PLT, + +/* This is a 64 bit reloc that stores the 32 bit GOT relative +value in two words (with an imm instruction). The relocation is +relative offset from _GLOBAL_OFFSET_TABLE_ */ + BFD_RELOC_MICROBLAZE_64_GOTOFF, + +/* This is a 32 bit reloc that stores the 32 bit GOT relative +value in a word. The relocation is relative offset from */ + BFD_RELOC_MICROBLAZE_32_GOTOFF, + +/* This is used to tell the dynamic linker to copy the value out of +the dynamic object into the runtime process image. */ + BFD_RELOC_MICROBLAZE_COPY, + +/* Unused Reloc */ + BFD_RELOC_MICROBLAZE_64_TLS, + +/* This is a 64 bit reloc that stores the 32 bit GOT relative value +of the GOT TLS GD info entry in two words (with an imm instruction). The +relocation is GOT offset. */ + BFD_RELOC_MICROBLAZE_64_TLSGD, + +/* This is a 64 bit reloc that stores the 32 bit GOT relative value +of the GOT TLS LD info entry in two words (with an imm instruction). The +relocation is GOT offset. */ + BFD_RELOC_MICROBLAZE_64_TLSLD, + +/* This is a 32 bit reloc that stores the Module ID to GOT(n). */ + BFD_RELOC_MICROBLAZE_32_TLSDTPMOD, + +/* This is a 32 bit reloc that stores TLS offset to GOT(n+1). */ + BFD_RELOC_MICROBLAZE_32_TLSDTPREL, + +/* This is a 32 bit reloc for storing TLS offset to two words (uses imm +instruction) */ + BFD_RELOC_MICROBLAZE_64_TLSDTPREL, + +/* This is a 64 bit reloc that stores 32-bit thread pointer relative offset +to two words (uses imm instruction). */ + BFD_RELOC_MICROBLAZE_64_TLSGOTTPREL, + +/* This is a 64 bit reloc that stores 32-bit thread pointer relative offset +to two words (uses imm instruction). */ + BFD_RELOC_MICROBLAZE_64_TLSTPREL, + +/* AArch64 pseudo relocation code to mark the start of the AArch64 +relocation enumerators. N.B. the order of the enumerators is +important as several tables in the AArch64 bfd backend are indexed +by these enumerators; make sure they are all synced. */ + BFD_RELOC_AARCH64_RELOC_START, + +/* AArch64 null relocation code. */ + BFD_RELOC_AARCH64_NONE, + +/* Basic absolute relocations of N bits. These are equivalent to +BFD_RELOC_N and they were added to assist the indexing of the howto +table. */ + BFD_RELOC_AARCH64_64, + BFD_RELOC_AARCH64_32, + BFD_RELOC_AARCH64_16, + +/* PC-relative relocations. These are equivalent to BFD_RELOC_N_PCREL +and they were added to assist the indexing of the howto table. */ + BFD_RELOC_AARCH64_64_PCREL, + BFD_RELOC_AARCH64_32_PCREL, + BFD_RELOC_AARCH64_16_PCREL, + +/* AArch64 MOV[NZK] instruction with most significant bits 0 to 15 +of an unsigned address/value. */ + BFD_RELOC_AARCH64_MOVW_G0, + +/* AArch64 MOV[NZK] instruction with less significant bits 0 to 15 of +an address/value. No overflow checking. */ + BFD_RELOC_AARCH64_MOVW_G0_NC, + +/* AArch64 MOV[NZK] instruction with most significant bits 16 to 31 +of an unsigned address/value. */ + BFD_RELOC_AARCH64_MOVW_G1, + +/* AArch64 MOV[NZK] instruction with less significant bits 16 to 31 +of an address/value. No overflow checking. */ + BFD_RELOC_AARCH64_MOVW_G1_NC, + +/* AArch64 MOV[NZK] instruction with most significant bits 32 to 47 +of an unsigned address/value. */ + BFD_RELOC_AARCH64_MOVW_G2, + +/* AArch64 MOV[NZK] instruction with less significant bits 32 to 47 +of an address/value. No overflow checking. */ + BFD_RELOC_AARCH64_MOVW_G2_NC, + +/* AArch64 MOV[NZK] instruction with most signficant bits 48 to 64 +of a signed or unsigned address/value. */ + BFD_RELOC_AARCH64_MOVW_G3, + +/* AArch64 MOV[NZ] instruction with most significant bits 0 to 15 +of a signed value. Changes instruction to MOVZ or MOVN depending on the +value's sign. */ + BFD_RELOC_AARCH64_MOVW_G0_S, + +/* AArch64 MOV[NZ] instruction with most significant bits 16 to 31 +of a signed value. Changes instruction to MOVZ or MOVN depending on the +value's sign. */ + BFD_RELOC_AARCH64_MOVW_G1_S, + +/* AArch64 MOV[NZ] instruction with most significant bits 32 to 47 +of a signed value. Changes instruction to MOVZ or MOVN depending on the +value's sign. */ + BFD_RELOC_AARCH64_MOVW_G2_S, + +/* AArch64 Load Literal instruction, holding a 19 bit pc-relative word +offset. The lowest two bits must be zero and are not stored in the +instruction, giving a 21 bit signed byte offset. */ + BFD_RELOC_AARCH64_LD_LO19_PCREL, + +/* AArch64 ADR instruction, holding a simple 21 bit pc-relative byte offset. */ + BFD_RELOC_AARCH64_ADR_LO21_PCREL, + +/* AArch64 ADRP instruction, with bits 12 to 32 of a pc-relative page +offset, giving a 4KB aligned page base address. */ + BFD_RELOC_AARCH64_ADR_HI21_PCREL, + +/* AArch64 ADRP instruction, with bits 12 to 32 of a pc-relative page +offset, giving a 4KB aligned page base address, but with no overflow +checking. */ + BFD_RELOC_AARCH64_ADR_HI21_NC_PCREL, + +/* AArch64 ADD immediate instruction, holding bits 0 to 11 of the address. +Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. */ + BFD_RELOC_AARCH64_ADD_LO12, + +/* AArch64 8-bit load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. */ + BFD_RELOC_AARCH64_LDST8_LO12, + +/* AArch64 14 bit pc-relative test bit and branch. +The lowest two bits must be zero and are not stored in the instruction, +giving a 16 bit signed byte offset. */ + BFD_RELOC_AARCH64_TSTBR14, + +/* AArch64 19 bit pc-relative conditional branch and compare & branch. +The lowest two bits must be zero and are not stored in the instruction, +giving a 21 bit signed byte offset. */ + BFD_RELOC_AARCH64_BRANCH19, + +/* AArch64 26 bit pc-relative unconditional branch. +The lowest two bits must be zero and are not stored in the instruction, +giving a 28 bit signed byte offset. */ + BFD_RELOC_AARCH64_JUMP26, + +/* AArch64 26 bit pc-relative unconditional branch and link. +The lowest two bits must be zero and are not stored in the instruction, +giving a 28 bit signed byte offset. */ + BFD_RELOC_AARCH64_CALL26, + +/* AArch64 16-bit load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. */ + BFD_RELOC_AARCH64_LDST16_LO12, + +/* AArch64 32-bit load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. */ + BFD_RELOC_AARCH64_LDST32_LO12, + +/* AArch64 64-bit load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. */ + BFD_RELOC_AARCH64_LDST64_LO12, + +/* AArch64 128-bit load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. */ + BFD_RELOC_AARCH64_LDST128_LO12, + +/* AArch64 Load Literal instruction, holding a 19 bit PC relative word +offset of the global offset table entry for a symbol. The lowest two +bits must be zero and are not stored in the instruction, giving a 21 +bit signed byte offset. This relocation type requires signed overflow +checking. */ + BFD_RELOC_AARCH64_GOT_LD_PREL19, + +/* Get to the page base of the global offset table entry for a symbol as +part of an ADRP instruction using a 21 bit PC relative value.Used in +conjunction with BFD_RELOC_AARCH64_LD64_GOT_LO12_NC. */ + BFD_RELOC_AARCH64_ADR_GOT_PAGE, + +/* Unsigned 12 bit byte offset for 64 bit load/store from the page of +the GOT entry for this symbol. Used in conjunction with +BFD_RELOC_AARCH64_ADR_GOTPAGE. Valid in LP64 ABI only. */ + BFD_RELOC_AARCH64_LD64_GOT_LO12_NC, + +/* Unsigned 12 bit byte offset for 32 bit load/store from the page of +the GOT entry for this symbol. Used in conjunction with +BFD_RELOC_AARCH64_ADR_GOTPAGE. Valid in ILP32 ABI only. */ + BFD_RELOC_AARCH64_LD32_GOT_LO12_NC, + +/* Get to the page base of the global offset table entry for a symbols +tls_index structure as part of an adrp instruction using a 21 bit PC +relative value. Used in conjunction with +BFD_RELOC_AARCH64_TLSGD_ADD_LO12_NC. */ + BFD_RELOC_AARCH64_TLSGD_ADR_PAGE21, + +/* Unsigned 12 bit byte offset to global offset table entry for a symbols +tls_index structure. Used in conjunction with +BFD_RELOC_AARCH64_TLSGD_ADR_PAGE21. */ + BFD_RELOC_AARCH64_TLSGD_ADD_LO12_NC, + +/* AArch64 TLS INITIAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G1, + +/* AArch64 TLS INITIAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G0_NC, + +/* AArch64 TLS INITIAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSIE_ADR_GOTTPREL_PAGE21, + +/* AArch64 TLS INITIAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSIE_LD64_GOTTPREL_LO12_NC, + +/* AArch64 TLS INITIAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSIE_LD32_GOTTPREL_LO12_NC, + +/* AArch64 TLS INITIAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_PREL19, + +/* AArch64 TLS LOCAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G2, + +/* AArch64 TLS LOCAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1, + +/* AArch64 TLS LOCAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1_NC, + +/* AArch64 TLS LOCAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0, + +/* AArch64 TLS LOCAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0_NC, + +/* AArch64 TLS LOCAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_HI12, + +/* AArch64 TLS LOCAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12, + +/* AArch64 TLS LOCAL EXEC relocation. */ + BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12_NC, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_LD_PREL19, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_ADR_PREL21, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_ADR_PAGE21, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_LD64_LO12_NC, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_LD32_LO12_NC, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_ADD_LO12_NC, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_OFF_G1, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_OFF_G0_NC, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_LDR, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_ADD, + +/* AArch64 TLS DESC relocation. */ + BFD_RELOC_AARCH64_TLSDESC_CALL, + +/* AArch64 TLS relocation. */ + BFD_RELOC_AARCH64_COPY, + +/* AArch64 TLS relocation. */ + BFD_RELOC_AARCH64_GLOB_DAT, + +/* AArch64 TLS relocation. */ + BFD_RELOC_AARCH64_JUMP_SLOT, + +/* AArch64 TLS relocation. */ + BFD_RELOC_AARCH64_RELATIVE, + +/* AArch64 TLS relocation. */ + BFD_RELOC_AARCH64_TLS_DTPMOD, + +/* AArch64 TLS relocation. */ + BFD_RELOC_AARCH64_TLS_DTPREL, + +/* AArch64 TLS relocation. */ + BFD_RELOC_AARCH64_TLS_TPREL, + +/* AArch64 TLS relocation. */ + BFD_RELOC_AARCH64_TLSDESC, + +/* AArch64 support for STT_GNU_IFUNC. */ + BFD_RELOC_AARCH64_IRELATIVE, + +/* AArch64 pseudo relocation code to mark the end of the AArch64 +relocation enumerators that have direct mapping to ELF reloc codes. +There are a few more enumerators after this one; those are mainly +used by the AArch64 assembler for the internal fixup or to select +one of the above enumerators. */ + BFD_RELOC_AARCH64_RELOC_END, + +/* AArch64 pseudo relocation code to be used internally by the AArch64 +assembler and not (currently) written to any object files. */ + BFD_RELOC_AARCH64_GAS_INTERNAL_FIXUP, + +/* AArch64 unspecified load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. */ + BFD_RELOC_AARCH64_LDST_LO12, + +/* AArch64 pseudo relocation code to be used internally by the AArch64 +assembler and not (currently) written to any object files. */ + BFD_RELOC_AARCH64_LD_GOT_LO12_NC, + +/* AArch64 pseudo relocation code to be used internally by the AArch64 +assembler and not (currently) written to any object files. */ + BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_LO12_NC, + +/* AArch64 pseudo relocation code to be used internally by the AArch64 +assembler and not (currently) written to any object files. */ + BFD_RELOC_AARCH64_TLSDESC_LD_LO12_NC, + +/* Tilera TILEPro Relocations. */ + BFD_RELOC_TILEPRO_COPY, + BFD_RELOC_TILEPRO_GLOB_DAT, + BFD_RELOC_TILEPRO_JMP_SLOT, + BFD_RELOC_TILEPRO_RELATIVE, + BFD_RELOC_TILEPRO_BROFF_X1, + BFD_RELOC_TILEPRO_JOFFLONG_X1, + BFD_RELOC_TILEPRO_JOFFLONG_X1_PLT, + BFD_RELOC_TILEPRO_IMM8_X0, + BFD_RELOC_TILEPRO_IMM8_Y0, + BFD_RELOC_TILEPRO_IMM8_X1, + BFD_RELOC_TILEPRO_IMM8_Y1, + BFD_RELOC_TILEPRO_DEST_IMM8_X1, + BFD_RELOC_TILEPRO_MT_IMM15_X1, + BFD_RELOC_TILEPRO_MF_IMM15_X1, + BFD_RELOC_TILEPRO_IMM16_X0, + BFD_RELOC_TILEPRO_IMM16_X1, + BFD_RELOC_TILEPRO_IMM16_X0_LO, + BFD_RELOC_TILEPRO_IMM16_X1_LO, + BFD_RELOC_TILEPRO_IMM16_X0_HI, + BFD_RELOC_TILEPRO_IMM16_X1_HI, + BFD_RELOC_TILEPRO_IMM16_X0_HA, + BFD_RELOC_TILEPRO_IMM16_X1_HA, + BFD_RELOC_TILEPRO_IMM16_X0_PCREL, + BFD_RELOC_TILEPRO_IMM16_X1_PCREL, + BFD_RELOC_TILEPRO_IMM16_X0_LO_PCREL, + BFD_RELOC_TILEPRO_IMM16_X1_LO_PCREL, + BFD_RELOC_TILEPRO_IMM16_X0_HI_PCREL, + BFD_RELOC_TILEPRO_IMM16_X1_HI_PCREL, + BFD_RELOC_TILEPRO_IMM16_X0_HA_PCREL, + BFD_RELOC_TILEPRO_IMM16_X1_HA_PCREL, + BFD_RELOC_TILEPRO_IMM16_X0_GOT, + BFD_RELOC_TILEPRO_IMM16_X1_GOT, + BFD_RELOC_TILEPRO_IMM16_X0_GOT_LO, + BFD_RELOC_TILEPRO_IMM16_X1_GOT_LO, + BFD_RELOC_TILEPRO_IMM16_X0_GOT_HI, + BFD_RELOC_TILEPRO_IMM16_X1_GOT_HI, + BFD_RELOC_TILEPRO_IMM16_X0_GOT_HA, + BFD_RELOC_TILEPRO_IMM16_X1_GOT_HA, + BFD_RELOC_TILEPRO_MMSTART_X0, + BFD_RELOC_TILEPRO_MMEND_X0, + BFD_RELOC_TILEPRO_MMSTART_X1, + BFD_RELOC_TILEPRO_MMEND_X1, + BFD_RELOC_TILEPRO_SHAMT_X0, + BFD_RELOC_TILEPRO_SHAMT_X1, + BFD_RELOC_TILEPRO_SHAMT_Y0, + BFD_RELOC_TILEPRO_SHAMT_Y1, + BFD_RELOC_TILEPRO_TLS_GD_CALL, + BFD_RELOC_TILEPRO_IMM8_X0_TLS_GD_ADD, + BFD_RELOC_TILEPRO_IMM8_X1_TLS_GD_ADD, + BFD_RELOC_TILEPRO_IMM8_Y0_TLS_GD_ADD, + BFD_RELOC_TILEPRO_IMM8_Y1_TLS_GD_ADD, + BFD_RELOC_TILEPRO_TLS_IE_LOAD, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_LO, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_LO, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HI, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HI, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HA, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HA, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_LO, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_LO, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HI, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HI, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HA, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HA, + BFD_RELOC_TILEPRO_TLS_DTPMOD32, + BFD_RELOC_TILEPRO_TLS_DTPOFF32, + BFD_RELOC_TILEPRO_TLS_TPOFF32, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_LO, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_LO, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HI, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HI, + BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HA, + BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HA, + +/* Tilera TILE-Gx Relocations. */ + BFD_RELOC_TILEGX_HW0, + BFD_RELOC_TILEGX_HW1, + BFD_RELOC_TILEGX_HW2, + BFD_RELOC_TILEGX_HW3, + BFD_RELOC_TILEGX_HW0_LAST, + BFD_RELOC_TILEGX_HW1_LAST, + BFD_RELOC_TILEGX_HW2_LAST, + BFD_RELOC_TILEGX_COPY, + BFD_RELOC_TILEGX_GLOB_DAT, + BFD_RELOC_TILEGX_JMP_SLOT, + BFD_RELOC_TILEGX_RELATIVE, + BFD_RELOC_TILEGX_BROFF_X1, + BFD_RELOC_TILEGX_JUMPOFF_X1, + BFD_RELOC_TILEGX_JUMPOFF_X1_PLT, + BFD_RELOC_TILEGX_IMM8_X0, + BFD_RELOC_TILEGX_IMM8_Y0, + BFD_RELOC_TILEGX_IMM8_X1, + BFD_RELOC_TILEGX_IMM8_Y1, + BFD_RELOC_TILEGX_DEST_IMM8_X1, + BFD_RELOC_TILEGX_MT_IMM14_X1, + BFD_RELOC_TILEGX_MF_IMM14_X1, + BFD_RELOC_TILEGX_MMSTART_X0, + BFD_RELOC_TILEGX_MMEND_X0, + BFD_RELOC_TILEGX_SHAMT_X0, + BFD_RELOC_TILEGX_SHAMT_X1, + BFD_RELOC_TILEGX_SHAMT_Y0, + BFD_RELOC_TILEGX_SHAMT_Y1, + BFD_RELOC_TILEGX_IMM16_X0_HW0, + BFD_RELOC_TILEGX_IMM16_X1_HW0, + BFD_RELOC_TILEGX_IMM16_X0_HW1, + BFD_RELOC_TILEGX_IMM16_X1_HW1, + BFD_RELOC_TILEGX_IMM16_X0_HW2, + BFD_RELOC_TILEGX_IMM16_X1_HW2, + BFD_RELOC_TILEGX_IMM16_X0_HW3, + BFD_RELOC_TILEGX_IMM16_X1_HW3, + BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST, + BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST, + BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST, + BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST, + BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST, + BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST, + BFD_RELOC_TILEGX_IMM16_X0_HW0_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW0_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW1_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW1_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW2_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW2_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW3_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW3_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW0_GOT, + BFD_RELOC_TILEGX_IMM16_X1_HW0_GOT, + BFD_RELOC_TILEGX_IMM16_X0_HW0_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW0_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW1_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW1_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW2_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW2_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_GOT, + BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_GOT, + BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_GOT, + BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_GOT, + BFD_RELOC_TILEGX_IMM16_X0_HW3_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW3_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_GD, + BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_GD, + BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_LE, + BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_LE, + BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_LE, + BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_LE, + BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_LE, + BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_LE, + BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_GD, + BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_GD, + BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_GD, + BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_GD, + BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_IE, + BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_IE, + BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PLT_PCREL, + BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_IE, + BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_IE, + BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_IE, + BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_IE, + BFD_RELOC_TILEGX_TLS_DTPMOD64, + BFD_RELOC_TILEGX_TLS_DTPOFF64, + BFD_RELOC_TILEGX_TLS_TPOFF64, + BFD_RELOC_TILEGX_TLS_DTPMOD32, + BFD_RELOC_TILEGX_TLS_DTPOFF32, + BFD_RELOC_TILEGX_TLS_TPOFF32, + BFD_RELOC_TILEGX_TLS_GD_CALL, + BFD_RELOC_TILEGX_IMM8_X0_TLS_GD_ADD, + BFD_RELOC_TILEGX_IMM8_X1_TLS_GD_ADD, + BFD_RELOC_TILEGX_IMM8_Y0_TLS_GD_ADD, + BFD_RELOC_TILEGX_IMM8_Y1_TLS_GD_ADD, + BFD_RELOC_TILEGX_TLS_IE_LOAD, + BFD_RELOC_TILEGX_IMM8_X0_TLS_ADD, + BFD_RELOC_TILEGX_IMM8_X1_TLS_ADD, + BFD_RELOC_TILEGX_IMM8_Y0_TLS_ADD, + BFD_RELOC_TILEGX_IMM8_Y1_TLS_ADD, + +/* Adapteva EPIPHANY - 8 bit signed pc-relative displacement */ + BFD_RELOC_EPIPHANY_SIMM8, + +/* Adapteva EPIPHANY - 24 bit signed pc-relative displacement */ + BFD_RELOC_EPIPHANY_SIMM24, + +/* Adapteva EPIPHANY - 16 most-significant bits of absolute address */ + BFD_RELOC_EPIPHANY_HIGH, + +/* Adapteva EPIPHANY - 16 least-significant bits of absolute address */ + BFD_RELOC_EPIPHANY_LOW, + +/* Adapteva EPIPHANY - 11 bit signed number - add/sub immediate */ + BFD_RELOC_EPIPHANY_SIMM11, + +/* Adapteva EPIPHANY - 11 bit sign-magnitude number (ld/st displacement) */ + BFD_RELOC_EPIPHANY_IMM11, + +/* Adapteva EPIPHANY - 8 bit immediate for 16 bit mov instruction. */ + BFD_RELOC_EPIPHANY_IMM8, + BFD_RELOC_UNUSED }; +typedef enum bfd_reloc_code_real bfd_reloc_code_real_type; +reloc_howto_type *bfd_reloc_type_lookup + (bfd *abfd, bfd_reloc_code_real_type code); +reloc_howto_type *bfd_reloc_name_lookup + (bfd *abfd, const char *reloc_name); + +const char *bfd_get_reloc_code_name (bfd_reloc_code_real_type code); + +/* Extracted from syms.c. */ + +typedef struct bfd_symbol +{ + /* A pointer to the BFD which owns the symbol. This information + is necessary so that a back end can work out what additional + information (invisible to the application writer) is carried + with the symbol. + + This field is *almost* redundant, since you can use section->owner + instead, except that some symbols point to the global sections + bfd_{abs,com,und}_section. This could be fixed by making + these globals be per-bfd (or per-target-flavor). FIXME. */ + struct bfd *the_bfd; /* Use bfd_asymbol_bfd(sym) to access this field. */ + + /* The text of the symbol. The name is left alone, and not copied; the + application may not alter it. */ + const char *name; + + /* The value of the symbol. This really should be a union of a + numeric value with a pointer, since some flags indicate that + a pointer to another symbol is stored here. */ + symvalue value; + + /* Attributes of a symbol. */ +#define BSF_NO_FLAGS 0x00 + + /* The symbol has local scope; <> in <>. The value + is the offset into the section of the data. */ +#define BSF_LOCAL (1 << 0) + + /* The symbol has global scope; initialized data in <>. The + value is the offset into the section of the data. */ +#define BSF_GLOBAL (1 << 1) + + /* The symbol has global scope and is exported. The value is + the offset into the section of the data. */ +#define BSF_EXPORT BSF_GLOBAL /* No real difference. */ + + /* A normal C symbol would be one of: + <>, <>, <> or + <>. */ + + /* The symbol is a debugging record. The value has an arbitrary + meaning, unless BSF_DEBUGGING_RELOC is also set. */ +#define BSF_DEBUGGING (1 << 2) + + /* The symbol denotes a function entry point. Used in ELF, + perhaps others someday. */ +#define BSF_FUNCTION (1 << 3) + + /* Used by the linker. */ +#define BSF_KEEP (1 << 5) +#define BSF_KEEP_G (1 << 6) + + /* A weak global symbol, overridable without warnings by + a regular global symbol of the same name. */ +#define BSF_WEAK (1 << 7) + + /* This symbol was created to point to a section, e.g. ELF's + STT_SECTION symbols. */ +#define BSF_SECTION_SYM (1 << 8) + + /* The symbol used to be a common symbol, but now it is + allocated. */ +#define BSF_OLD_COMMON (1 << 9) + + /* In some files the type of a symbol sometimes alters its + location in an output file - ie in coff a <> symbol + which is also <> symbol appears where it was + declared and not at the end of a section. This bit is set + by the target BFD part to convey this information. */ +#define BSF_NOT_AT_END (1 << 10) + + /* Signal that the symbol is the label of constructor section. */ +#define BSF_CONSTRUCTOR (1 << 11) + + /* Signal that the symbol is a warning symbol. The name is a + warning. The name of the next symbol is the one to warn about; + if a reference is made to a symbol with the same name as the next + symbol, a warning is issued by the linker. */ +#define BSF_WARNING (1 << 12) + + /* Signal that the symbol is indirect. This symbol is an indirect + pointer to the symbol with the same name as the next symbol. */ +#define BSF_INDIRECT (1 << 13) + + /* BSF_FILE marks symbols that contain a file name. This is used + for ELF STT_FILE symbols. */ +#define BSF_FILE (1 << 14) + + /* Symbol is from dynamic linking information. */ +#define BSF_DYNAMIC (1 << 15) + + /* The symbol denotes a data object. Used in ELF, and perhaps + others someday. */ +#define BSF_OBJECT (1 << 16) + + /* This symbol is a debugging symbol. The value is the offset + into the section of the data. BSF_DEBUGGING should be set + as well. */ +#define BSF_DEBUGGING_RELOC (1 << 17) + + /* This symbol is thread local. Used in ELF. */ +#define BSF_THREAD_LOCAL (1 << 18) + + /* This symbol represents a complex relocation expression, + with the expression tree serialized in the symbol name. */ +#define BSF_RELC (1 << 19) + + /* This symbol represents a signed complex relocation expression, + with the expression tree serialized in the symbol name. */ +#define BSF_SRELC (1 << 20) + + /* This symbol was created by bfd_get_synthetic_symtab. */ +#define BSF_SYNTHETIC (1 << 21) + + /* This symbol is an indirect code object. Unrelated to BSF_INDIRECT. + The dynamic linker will compute the value of this symbol by + calling the function that it points to. BSF_FUNCTION must + also be also set. */ +#define BSF_GNU_INDIRECT_FUNCTION (1 << 22) + /* This symbol is a globally unique data object. The dynamic linker + will make sure that in the entire process there is just one symbol + with this name and type in use. BSF_OBJECT must also be set. */ +#define BSF_GNU_UNIQUE (1 << 23) + + flagword flags; + + /* A pointer to the section to which this symbol is + relative. This will always be non NULL, there are special + sections for undefined and absolute symbols. */ + struct bfd_section *section; + + /* Back end special data. */ + union + { + void *p; + bfd_vma i; + } + udata; +} +asymbol; + +#define bfd_get_symtab_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd)) + +bfd_boolean bfd_is_local_label (bfd *abfd, asymbol *sym); + +bfd_boolean bfd_is_local_label_name (bfd *abfd, const char *name); + +#define bfd_is_local_label_name(abfd, name) \ + BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name)) + +bfd_boolean bfd_is_target_special_symbol (bfd *abfd, asymbol *sym); + +#define bfd_is_target_special_symbol(abfd, sym) \ + BFD_SEND (abfd, _bfd_is_target_special_symbol, (abfd, sym)) + +#define bfd_canonicalize_symtab(abfd, location) \ + BFD_SEND (abfd, _bfd_canonicalize_symtab, (abfd, location)) + +bfd_boolean bfd_set_symtab + (bfd *abfd, asymbol **location, unsigned int count); + +void bfd_print_symbol_vandf (bfd *abfd, void *file, asymbol *symbol); + +#define bfd_make_empty_symbol(abfd) \ + BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd)) + +asymbol *_bfd_generic_make_empty_symbol (bfd *); + +#define bfd_make_debug_symbol(abfd,ptr,size) \ + BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size)) + +int bfd_decode_symclass (asymbol *symbol); + +bfd_boolean bfd_is_undefined_symclass (int symclass); + +void bfd_symbol_info (asymbol *symbol, symbol_info *ret); + +bfd_boolean bfd_copy_private_symbol_data + (bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym); + +#define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \ + BFD_SEND (obfd, _bfd_copy_private_symbol_data, \ + (ibfd, isymbol, obfd, osymbol)) + +/* Extracted from bfd.c. */ +enum bfd_direction + { + no_direction = 0, + read_direction = 1, + write_direction = 2, + both_direction = 3 + }; + +struct bfd +{ + /* A unique identifier of the BFD */ + unsigned int id; + + /* The filename the application opened the BFD with. */ + const char *filename; + + /* A pointer to the target jump table. */ + const struct bfd_target *xvec; + + /* The IOSTREAM, and corresponding IO vector that provide access + to the file backing the BFD. */ + void *iostream; + const struct bfd_iovec *iovec; + + /* The caching routines use these to maintain a + least-recently-used list of BFDs. */ + struct bfd *lru_prev, *lru_next; + + /* When a file is closed by the caching routines, BFD retains + state information on the file here... */ + ufile_ptr where; + + /* File modified time, if mtime_set is TRUE. */ + long mtime; + + /* Reserved for an unimplemented file locking extension. */ + int ifd; + + /* The format which belongs to the BFD. (object, core, etc.) */ + bfd_format format; + + /* The direction with which the BFD was opened. */ + enum bfd_direction direction; + + /* Format_specific flags. */ + flagword flags; + + /* Values that may appear in the flags field of a BFD. These also + appear in the object_flags field of the bfd_target structure, where + they indicate the set of flags used by that backend (not all flags + are meaningful for all object file formats) (FIXME: at the moment, + the object_flags values have mostly just been copied from backend + to another, and are not necessarily correct). */ + +#define BFD_NO_FLAGS 0x00 + + /* BFD contains relocation entries. */ +#define HAS_RELOC 0x01 + + /* BFD is directly executable. */ +#define EXEC_P 0x02 + + /* BFD has line number information (basically used for F_LNNO in a + COFF header). */ +#define HAS_LINENO 0x04 + + /* BFD has debugging information. */ +#define HAS_DEBUG 0x08 + + /* BFD has symbols. */ +#define HAS_SYMS 0x10 + + /* BFD has local symbols (basically used for F_LSYMS in a COFF + header). */ +#define HAS_LOCALS 0x20 + + /* BFD is a dynamic object. */ +#define DYNAMIC 0x40 + + /* Text section is write protected (if D_PAGED is not set, this is + like an a.out NMAGIC file) (the linker sets this by default, but + clears it for -r or -N). */ +#define WP_TEXT 0x80 + + /* BFD is dynamically paged (this is like an a.out ZMAGIC file) (the + linker sets this by default, but clears it for -r or -n or -N). */ +#define D_PAGED 0x100 + + /* BFD is relaxable (this means that bfd_relax_section may be able to + do something) (sometimes bfd_relax_section can do something even if + this is not set). */ +#define BFD_IS_RELAXABLE 0x200 + + /* This may be set before writing out a BFD to request using a + traditional format. For example, this is used to request that when + writing out an a.out object the symbols not be hashed to eliminate + duplicates. */ +#define BFD_TRADITIONAL_FORMAT 0x400 + + /* This flag indicates that the BFD contents are actually cached + in memory. If this is set, iostream points to a bfd_in_memory + struct. */ +#define BFD_IN_MEMORY 0x800 + + /* The sections in this BFD specify a memory page. */ +#define HAS_LOAD_PAGE 0x1000 + + /* This BFD has been created by the linker and doesn't correspond + to any input file. */ +#define BFD_LINKER_CREATED 0x2000 + + /* This may be set before writing out a BFD to request that it + be written using values for UIDs, GIDs, timestamps, etc. that + will be consistent from run to run. */ +#define BFD_DETERMINISTIC_OUTPUT 0x4000 + + /* Compress sections in this BFD. */ +#define BFD_COMPRESS 0x8000 + + /* Decompress sections in this BFD. */ +#define BFD_DECOMPRESS 0x10000 + + /* BFD is a dummy, for plugins. */ +#define BFD_PLUGIN 0x20000 + + /* Flags bits to be saved in bfd_preserve_save. */ +#define BFD_FLAGS_SAVED \ + (BFD_IN_MEMORY | BFD_COMPRESS | BFD_DECOMPRESS | BFD_PLUGIN) + + /* Flags bits which are for BFD use only. */ +#define BFD_FLAGS_FOR_BFD_USE_MASK \ + (BFD_IN_MEMORY | BFD_COMPRESS | BFD_DECOMPRESS | BFD_LINKER_CREATED \ + | BFD_PLUGIN | BFD_TRADITIONAL_FORMAT | BFD_DETERMINISTIC_OUTPUT) + + /* Currently my_archive is tested before adding origin to + anything. I believe that this can become always an add of + origin, with origin set to 0 for non archive files. */ + ufile_ptr origin; + + /* The origin in the archive of the proxy entry. This will + normally be the same as origin, except for thin archives, + when it will contain the current offset of the proxy in the + thin archive rather than the offset of the bfd in its actual + container. */ + ufile_ptr proxy_origin; + + /* A hash table for section names. */ + struct bfd_hash_table section_htab; + + /* Pointer to linked list of sections. */ + struct bfd_section *sections; + + /* The last section on the section list. */ + struct bfd_section *section_last; + + /* The number of sections. */ + unsigned int section_count; + + /* Stuff only useful for object files: + The start address. */ + bfd_vma start_address; + + /* Used for input and output. */ + unsigned int symcount; + + /* Symbol table for output BFD (with symcount entries). + Also used by the linker to cache input BFD symbols. */ + struct bfd_symbol **outsymbols; + + /* Used for slurped dynamic symbol tables. */ + unsigned int dynsymcount; + + /* Pointer to structure which contains architecture information. */ + const struct bfd_arch_info *arch_info; + + /* Stuff only useful for archives. */ + void *arelt_data; + struct bfd *my_archive; /* The containing archive BFD. */ + struct bfd *archive_next; /* The next BFD in the archive. */ + struct bfd *archive_head; /* The first BFD in the archive. */ + struct bfd *nested_archives; /* List of nested archive in a flattened + thin archive. */ + + /* A chain of BFD structures involved in a link. */ + struct bfd *link_next; + + /* A field used by _bfd_generic_link_add_archive_symbols. This will + be used only for archive elements. */ + int archive_pass; + + /* Used by the back end to hold private data. */ + union + { + struct aout_data_struct *aout_data; + struct artdata *aout_ar_data; + struct _oasys_data *oasys_obj_data; + struct _oasys_ar_data *oasys_ar_data; + struct coff_tdata *coff_obj_data; + struct pe_tdata *pe_obj_data; + struct xcoff_tdata *xcoff_obj_data; + struct ecoff_tdata *ecoff_obj_data; + struct ieee_data_struct *ieee_data; + struct ieee_ar_data_struct *ieee_ar_data; + struct srec_data_struct *srec_data; + struct verilog_data_struct *verilog_data; + struct ihex_data_struct *ihex_data; + struct tekhex_data_struct *tekhex_data; + struct elf_obj_tdata *elf_obj_data; + struct nlm_obj_tdata *nlm_obj_data; + struct bout_data_struct *bout_data; + struct mmo_data_struct *mmo_data; + struct sun_core_struct *sun_core_data; + struct sco5_core_struct *sco5_core_data; + struct trad_core_struct *trad_core_data; + struct som_data_struct *som_data; + struct hpux_core_struct *hpux_core_data; + struct hppabsd_core_struct *hppabsd_core_data; + struct sgi_core_struct *sgi_core_data; + struct lynx_core_struct *lynx_core_data; + struct osf_core_struct *osf_core_data; + struct cisco_core_struct *cisco_core_data; + struct versados_data_struct *versados_data; + struct netbsd_core_struct *netbsd_core_data; + struct mach_o_data_struct *mach_o_data; + struct mach_o_fat_data_struct *mach_o_fat_data; + struct plugin_data_struct *plugin_data; + struct bfd_pef_data_struct *pef_data; + struct bfd_pef_xlib_data_struct *pef_xlib_data; + struct bfd_sym_data_struct *sym_data; + void *any; + } + tdata; + + /* Used by the application to hold private data. */ + void *usrdata; + + /* Where all the allocated stuff under this BFD goes. This is a + struct objalloc *, but we use void * to avoid requiring the inclusion + of objalloc.h. */ + void *memory; + + /* Is the file descriptor being cached? That is, can it be closed as + needed, and re-opened when accessed later? */ + unsigned int cacheable : 1; + + /* Marks whether there was a default target specified when the + BFD was opened. This is used to select which matching algorithm + to use to choose the back end. */ + unsigned int target_defaulted : 1; + + /* ... and here: (``once'' means at least once). */ + unsigned int opened_once : 1; + + /* Set if we have a locally maintained mtime value, rather than + getting it from the file each time. */ + unsigned int mtime_set : 1; + + /* Flag set if symbols from this BFD should not be exported. */ + unsigned int no_export : 1; + + /* Remember when output has begun, to stop strange things + from happening. */ + unsigned int output_has_begun : 1; + + /* Have archive map. */ + unsigned int has_armap : 1; + + /* Set if this is a thin archive. */ + unsigned int is_thin_archive : 1; + + /* Set if only required symbols should be added in the link hash table for + this object. Used by VMS linkers. */ + unsigned int selective_search : 1; +}; + +/* See note beside bfd_set_section_userdata. */ +static inline bfd_boolean +bfd_set_cacheable (bfd * abfd, bfd_boolean val) +{ + abfd->cacheable = val; + return TRUE; +} + +typedef enum bfd_error +{ + bfd_error_no_error = 0, + bfd_error_system_call, + bfd_error_invalid_target, + bfd_error_wrong_format, + bfd_error_wrong_object_format, + bfd_error_invalid_operation, + bfd_error_no_memory, + bfd_error_no_symbols, + bfd_error_no_armap, + bfd_error_no_more_archived_files, + bfd_error_malformed_archive, + bfd_error_missing_dso, + bfd_error_file_not_recognized, + bfd_error_file_ambiguously_recognized, + bfd_error_no_contents, + bfd_error_nonrepresentable_section, + bfd_error_no_debug_section, + bfd_error_bad_value, + bfd_error_file_truncated, + bfd_error_file_too_big, + bfd_error_on_input, + bfd_error_invalid_error_code +} +bfd_error_type; + +bfd_error_type bfd_get_error (void); + +void bfd_set_error (bfd_error_type error_tag, ...); + +const char *bfd_errmsg (bfd_error_type error_tag); + +void bfd_perror (const char *message); + +typedef void (*bfd_error_handler_type) (const char *, ...); + +bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type); + +void bfd_set_error_program_name (const char *); + +bfd_error_handler_type bfd_get_error_handler (void); + +typedef void (*bfd_assert_handler_type) (const char *bfd_formatmsg, + const char *bfd_version, + const char *bfd_file, + int bfd_line); + +bfd_assert_handler_type bfd_set_assert_handler (bfd_assert_handler_type); + +bfd_assert_handler_type bfd_get_assert_handler (void); + +long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect); + +long bfd_canonicalize_reloc + (bfd *abfd, asection *sec, arelent **loc, asymbol **syms); + +void bfd_set_reloc + (bfd *abfd, asection *sec, arelent **rel, unsigned int count); + +bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags); + +int bfd_get_arch_size (bfd *abfd); + +int bfd_get_sign_extend_vma (bfd *abfd); + +bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma); + +unsigned int bfd_get_gp_size (bfd *abfd); + +void bfd_set_gp_size (bfd *abfd, unsigned int i); + +bfd_vma bfd_scan_vma (const char *string, const char **end, int base); + +bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd); + +#define bfd_copy_private_header_data(ibfd, obfd) \ + BFD_SEND (obfd, _bfd_copy_private_header_data, \ + (ibfd, obfd)) +bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd); + +#define bfd_copy_private_bfd_data(ibfd, obfd) \ + BFD_SEND (obfd, _bfd_copy_private_bfd_data, \ + (ibfd, obfd)) +bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd); + +#define bfd_merge_private_bfd_data(ibfd, obfd) \ + BFD_SEND (obfd, _bfd_merge_private_bfd_data, \ + (ibfd, obfd)) +bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags); + +#define bfd_set_private_flags(abfd, flags) \ + BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags)) +#define bfd_sizeof_headers(abfd, info) \ + BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info)) + +#define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \ + BFD_SEND (abfd, _bfd_find_nearest_line, \ + (abfd, sec, syms, off, file, func, line)) + +#define bfd_find_nearest_line_discriminator(abfd, sec, syms, off, file, func, \ + line, disc) \ + BFD_SEND (abfd, _bfd_find_nearest_line_discriminator, \ + (abfd, sec, syms, off, file, func, line, disc)) + +#define bfd_find_line(abfd, syms, sym, file, line) \ + BFD_SEND (abfd, _bfd_find_line, \ + (abfd, syms, sym, file, line)) + +#define bfd_find_inliner_info(abfd, file, func, line) \ + BFD_SEND (abfd, _bfd_find_inliner_info, \ + (abfd, file, func, line)) + +#define bfd_debug_info_start(abfd) \ + BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) + +#define bfd_debug_info_end(abfd) \ + BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) + +#define bfd_debug_info_accumulate(abfd, section) \ + BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) + +#define bfd_stat_arch_elt(abfd, stat) \ + BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat)) + +#define bfd_update_armap_timestamp(abfd) \ + BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd)) + +#define bfd_set_arch_mach(abfd, arch, mach)\ + BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) + +#define bfd_relax_section(abfd, section, link_info, again) \ + BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again)) + +#define bfd_gc_sections(abfd, link_info) \ + BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info)) + +#define bfd_lookup_section_flags(link_info, flag_info, section) \ + BFD_SEND (abfd, _bfd_lookup_section_flags, (link_info, flag_info, section)) + +#define bfd_merge_sections(abfd, link_info) \ + BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info)) + +#define bfd_is_group_section(abfd, sec) \ + BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec)) + +#define bfd_discard_group(abfd, sec) \ + BFD_SEND (abfd, _bfd_discard_group, (abfd, sec)) + +#define bfd_link_hash_table_create(abfd) \ + BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd)) + +#define bfd_link_hash_table_free(abfd, hash) \ + BFD_SEND (abfd, _bfd_link_hash_table_free, (hash)) + +#define bfd_link_add_symbols(abfd, info) \ + BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info)) + +#define bfd_link_just_syms(abfd, sec, info) \ + BFD_SEND (abfd, _bfd_link_just_syms, (sec, info)) + +#define bfd_final_link(abfd, info) \ + BFD_SEND (abfd, _bfd_final_link, (abfd, info)) + +#define bfd_free_cached_info(abfd) \ + BFD_SEND (abfd, _bfd_free_cached_info, (abfd)) + +#define bfd_get_dynamic_symtab_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd)) + +#define bfd_print_private_bfd_data(abfd, file)\ + BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file)) + +#define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \ + BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols)) + +#define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \ + BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \ + dyncount, dynsyms, ret)) + +#define bfd_get_dynamic_reloc_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd)) + +#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \ + BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms)) + +extern bfd_byte *bfd_get_relocated_section_contents + (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *, + bfd_boolean, asymbol **); + +bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative); + +bfd_vma bfd_emul_get_maxpagesize (const char *); + +void bfd_emul_set_maxpagesize (const char *, bfd_vma); + +bfd_vma bfd_emul_get_commonpagesize (const char *); + +void bfd_emul_set_commonpagesize (const char *, bfd_vma); + +char *bfd_demangle (bfd *, const char *, int); + +/* Extracted from archive.c. */ +symindex bfd_get_next_mapent + (bfd *abfd, symindex previous, carsym **sym); + +bfd_boolean bfd_set_archive_head (bfd *output, bfd *new_head); + +bfd *bfd_openr_next_archived_file (bfd *archive, bfd *previous); + +/* Extracted from corefile.c. */ +const char *bfd_core_file_failing_command (bfd *abfd); + +int bfd_core_file_failing_signal (bfd *abfd); + +int bfd_core_file_pid (bfd *abfd); + +bfd_boolean core_file_matches_executable_p + (bfd *core_bfd, bfd *exec_bfd); + +bfd_boolean generic_core_file_matches_executable_p + (bfd *core_bfd, bfd *exec_bfd); + +/* Extracted from targets.c. */ +#define BFD_SEND(bfd, message, arglist) \ + ((*((bfd)->xvec->message)) arglist) + +#ifdef DEBUG_BFD_SEND +#undef BFD_SEND +#define BFD_SEND(bfd, message, arglist) \ + (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ + ((*((bfd)->xvec->message)) arglist) : \ + (bfd_assert (__FILE__,__LINE__), NULL)) +#endif +#define BFD_SEND_FMT(bfd, message, arglist) \ + (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) + +#ifdef DEBUG_BFD_SEND +#undef BFD_SEND_FMT +#define BFD_SEND_FMT(bfd, message, arglist) \ + (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ + (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \ + (bfd_assert (__FILE__,__LINE__), NULL)) +#endif + +enum bfd_flavour +{ + bfd_target_unknown_flavour, + bfd_target_aout_flavour, + bfd_target_coff_flavour, + bfd_target_ecoff_flavour, + bfd_target_xcoff_flavour, + bfd_target_elf_flavour, + bfd_target_ieee_flavour, + bfd_target_nlm_flavour, + bfd_target_oasys_flavour, + bfd_target_tekhex_flavour, + bfd_target_srec_flavour, + bfd_target_verilog_flavour, + bfd_target_ihex_flavour, + bfd_target_som_flavour, + bfd_target_os9k_flavour, + bfd_target_versados_flavour, + bfd_target_msdos_flavour, + bfd_target_ovax_flavour, + bfd_target_evax_flavour, + bfd_target_mmo_flavour, + bfd_target_mach_o_flavour, + bfd_target_pef_flavour, + bfd_target_pef_xlib_flavour, + bfd_target_sym_flavour +}; + +enum bfd_endian { BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN }; + +/* Forward declaration. */ +typedef struct bfd_link_info _bfd_link_info; + +/* Forward declaration. */ +typedef struct flag_info flag_info; + +typedef struct bfd_target +{ + /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc. */ + char *name; + + /* The "flavour" of a back end is a general indication about + the contents of a file. */ + enum bfd_flavour flavour; + + /* The order of bytes within the data area of a file. */ + enum bfd_endian byteorder; + + /* The order of bytes within the header parts of a file. */ + enum bfd_endian header_byteorder; + + /* A mask of all the flags which an executable may have set - + from the set <>, <>, ...<>. */ + flagword object_flags; + + /* A mask of all the flags which a section may have set - from + the set <>, <>, ...<>. */ + flagword section_flags; + + /* The character normally found at the front of a symbol. + (if any), perhaps `_'. */ + char symbol_leading_char; + + /* The pad character for file names within an archive header. */ + char ar_pad_char; + + /* The maximum number of characters in an archive header. */ + unsigned char ar_max_namelen; + + /* How well this target matches, used to select between various + possible targets when more than one target matches. */ + unsigned char match_priority; + + /* Entries for byte swapping for data. These are different from the + other entry points, since they don't take a BFD as the first argument. + Certain other handlers could do the same. */ + bfd_uint64_t (*bfd_getx64) (const void *); + bfd_int64_t (*bfd_getx_signed_64) (const void *); + void (*bfd_putx64) (bfd_uint64_t, void *); + bfd_vma (*bfd_getx32) (const void *); + bfd_signed_vma (*bfd_getx_signed_32) (const void *); + void (*bfd_putx32) (bfd_vma, void *); + bfd_vma (*bfd_getx16) (const void *); + bfd_signed_vma (*bfd_getx_signed_16) (const void *); + void (*bfd_putx16) (bfd_vma, void *); + + /* Byte swapping for the headers. */ + bfd_uint64_t (*bfd_h_getx64) (const void *); + bfd_int64_t (*bfd_h_getx_signed_64) (const void *); + void (*bfd_h_putx64) (bfd_uint64_t, void *); + bfd_vma (*bfd_h_getx32) (const void *); + bfd_signed_vma (*bfd_h_getx_signed_32) (const void *); + void (*bfd_h_putx32) (bfd_vma, void *); + bfd_vma (*bfd_h_getx16) (const void *); + bfd_signed_vma (*bfd_h_getx_signed_16) (const void *); + void (*bfd_h_putx16) (bfd_vma, void *); + + /* Format dependent routines: these are vectors of entry points + within the target vector structure, one for each format to check. */ + + /* Check the format of a file being read. Return a <> or zero. */ + const struct bfd_target *(*_bfd_check_format[bfd_type_end]) (bfd *); + + /* Set the format of a file being written. */ + bfd_boolean (*_bfd_set_format[bfd_type_end]) (bfd *); + + /* Write cached information into a file being written, at <>. */ + bfd_boolean (*_bfd_write_contents[bfd_type_end]) (bfd *); + + + /* Generic entry points. */ +#define BFD_JUMP_TABLE_GENERIC(NAME) \ + NAME##_close_and_cleanup, \ + NAME##_bfd_free_cached_info, \ + NAME##_new_section_hook, \ + NAME##_get_section_contents, \ + NAME##_get_section_contents_in_window + + /* Called when the BFD is being closed to do any necessary cleanup. */ + bfd_boolean (*_close_and_cleanup) (bfd *); + /* Ask the BFD to free all cached information. */ + bfd_boolean (*_bfd_free_cached_info) (bfd *); + /* Called when a new section is created. */ + bfd_boolean (*_new_section_hook) (bfd *, sec_ptr); + /* Read the contents of a section. */ + bfd_boolean (*_bfd_get_section_contents) + (bfd *, sec_ptr, void *, file_ptr, bfd_size_type); + bfd_boolean (*_bfd_get_section_contents_in_window) + (bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type); + + /* Entry points to copy private data. */ +#define BFD_JUMP_TABLE_COPY(NAME) \ + NAME##_bfd_copy_private_bfd_data, \ + NAME##_bfd_merge_private_bfd_data, \ + _bfd_generic_init_private_section_data, \ + NAME##_bfd_copy_private_section_data, \ + NAME##_bfd_copy_private_symbol_data, \ + NAME##_bfd_copy_private_header_data, \ + NAME##_bfd_set_private_flags, \ + NAME##_bfd_print_private_bfd_data + + /* Called to copy BFD general private data from one object file + to another. */ + bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *); + /* Called to merge BFD general private data from one object file + to a common output file when linking. */ + bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *); + /* Called to initialize BFD private section data from one object file + to another. */ +#define bfd_init_private_section_data(ibfd, isec, obfd, osec, link_info) \ + BFD_SEND (obfd, _bfd_init_private_section_data, (ibfd, isec, obfd, osec, link_info)) + bfd_boolean (*_bfd_init_private_section_data) + (bfd *, sec_ptr, bfd *, sec_ptr, struct bfd_link_info *); + /* Called to copy BFD private section data from one object file + to another. */ + bfd_boolean (*_bfd_copy_private_section_data) + (bfd *, sec_ptr, bfd *, sec_ptr); + /* Called to copy BFD private symbol data from one symbol + to another. */ + bfd_boolean (*_bfd_copy_private_symbol_data) + (bfd *, asymbol *, bfd *, asymbol *); + /* Called to copy BFD private header data from one object file + to another. */ + bfd_boolean (*_bfd_copy_private_header_data) + (bfd *, bfd *); + /* Called to set private backend flags. */ + bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword); + + /* Called to print private BFD data. */ + bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *); + + /* Core file entry points. */ +#define BFD_JUMP_TABLE_CORE(NAME) \ + NAME##_core_file_failing_command, \ + NAME##_core_file_failing_signal, \ + NAME##_core_file_matches_executable_p, \ + NAME##_core_file_pid + + char * (*_core_file_failing_command) (bfd *); + int (*_core_file_failing_signal) (bfd *); + bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *); + int (*_core_file_pid) (bfd *); + + /* Archive entry points. */ +#define BFD_JUMP_TABLE_ARCHIVE(NAME) \ + NAME##_slurp_armap, \ + NAME##_slurp_extended_name_table, \ + NAME##_construct_extended_name_table, \ + NAME##_truncate_arname, \ + NAME##_write_armap, \ + NAME##_read_ar_hdr, \ + NAME##_write_ar_hdr, \ + NAME##_openr_next_archived_file, \ + NAME##_get_elt_at_index, \ + NAME##_generic_stat_arch_elt, \ + NAME##_update_armap_timestamp + + bfd_boolean (*_bfd_slurp_armap) (bfd *); + bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *); + bfd_boolean (*_bfd_construct_extended_name_table) + (bfd *, char **, bfd_size_type *, const char **); + void (*_bfd_truncate_arname) (bfd *, const char *, char *); + bfd_boolean (*write_armap) + (bfd *, unsigned int, struct orl *, unsigned int, int); + void * (*_bfd_read_ar_hdr_fn) (bfd *); + bfd_boolean (*_bfd_write_ar_hdr_fn) (bfd *, bfd *); + bfd * (*openr_next_archived_file) (bfd *, bfd *); +#define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i)) + bfd * (*_bfd_get_elt_at_index) (bfd *, symindex); + int (*_bfd_stat_arch_elt) (bfd *, struct stat *); + bfd_boolean (*_bfd_update_armap_timestamp) (bfd *); + + /* Entry points used for symbols. */ +#define BFD_JUMP_TABLE_SYMBOLS(NAME) \ + NAME##_get_symtab_upper_bound, \ + NAME##_canonicalize_symtab, \ + NAME##_make_empty_symbol, \ + NAME##_print_symbol, \ + NAME##_get_symbol_info, \ + NAME##_bfd_is_local_label_name, \ + NAME##_bfd_is_target_special_symbol, \ + NAME##_get_lineno, \ + NAME##_find_nearest_line, \ + _bfd_generic_find_nearest_line_discriminator, \ + _bfd_generic_find_line, \ + NAME##_find_inliner_info, \ + NAME##_bfd_make_debug_symbol, \ + NAME##_read_minisymbols, \ + NAME##_minisymbol_to_symbol + + long (*_bfd_get_symtab_upper_bound) (bfd *); + long (*_bfd_canonicalize_symtab) + (bfd *, struct bfd_symbol **); + struct bfd_symbol * + (*_bfd_make_empty_symbol) (bfd *); + void (*_bfd_print_symbol) + (bfd *, void *, struct bfd_symbol *, bfd_print_symbol_type); +#define bfd_print_symbol(b,p,s,e) BFD_SEND (b, _bfd_print_symbol, (b,p,s,e)) + void (*_bfd_get_symbol_info) + (bfd *, struct bfd_symbol *, symbol_info *); +#define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e)) + bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *); + bfd_boolean (*_bfd_is_target_special_symbol) (bfd *, asymbol *); + alent * (*_get_lineno) (bfd *, struct bfd_symbol *); + bfd_boolean (*_bfd_find_nearest_line) + (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma, + const char **, const char **, unsigned int *); + bfd_boolean (*_bfd_find_nearest_line_discriminator) + (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma, + const char **, const char **, unsigned int *, unsigned int *); + bfd_boolean (*_bfd_find_line) + (bfd *, struct bfd_symbol **, struct bfd_symbol *, + const char **, unsigned int *); + bfd_boolean (*_bfd_find_inliner_info) + (bfd *, const char **, const char **, unsigned int *); + /* Back-door to allow format-aware applications to create debug symbols + while using BFD for everything else. Currently used by the assembler + when creating COFF files. */ + asymbol * (*_bfd_make_debug_symbol) + (bfd *, void *, unsigned long size); +#define bfd_read_minisymbols(b, d, m, s) \ + BFD_SEND (b, _read_minisymbols, (b, d, m, s)) + long (*_read_minisymbols) + (bfd *, bfd_boolean, void **, unsigned int *); +#define bfd_minisymbol_to_symbol(b, d, m, f) \ + BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f)) + asymbol * (*_minisymbol_to_symbol) + (bfd *, bfd_boolean, const void *, asymbol *); + + /* Routines for relocs. */ +#define BFD_JUMP_TABLE_RELOCS(NAME) \ + NAME##_get_reloc_upper_bound, \ + NAME##_canonicalize_reloc, \ + NAME##_bfd_reloc_type_lookup, \ + NAME##_bfd_reloc_name_lookup + + long (*_get_reloc_upper_bound) (bfd *, sec_ptr); + long (*_bfd_canonicalize_reloc) + (bfd *, sec_ptr, arelent **, struct bfd_symbol **); + /* See documentation on reloc types. */ + reloc_howto_type * + (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type); + reloc_howto_type * + (*reloc_name_lookup) (bfd *, const char *); + + + /* Routines used when writing an object file. */ +#define BFD_JUMP_TABLE_WRITE(NAME) \ + NAME##_set_arch_mach, \ + NAME##_set_section_contents + + bfd_boolean (*_bfd_set_arch_mach) + (bfd *, enum bfd_architecture, unsigned long); + bfd_boolean (*_bfd_set_section_contents) + (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type); + + /* Routines used by the linker. */ +#define BFD_JUMP_TABLE_LINK(NAME) \ + NAME##_sizeof_headers, \ + NAME##_bfd_get_relocated_section_contents, \ + NAME##_bfd_relax_section, \ + NAME##_bfd_link_hash_table_create, \ + NAME##_bfd_link_hash_table_free, \ + NAME##_bfd_link_add_symbols, \ + NAME##_bfd_link_just_syms, \ + NAME##_bfd_copy_link_hash_symbol_type, \ + NAME##_bfd_final_link, \ + NAME##_bfd_link_split_section, \ + NAME##_bfd_gc_sections, \ + NAME##_bfd_lookup_section_flags, \ + NAME##_bfd_merge_sections, \ + NAME##_bfd_is_group_section, \ + NAME##_bfd_discard_group, \ + NAME##_section_already_linked, \ + NAME##_bfd_define_common_symbol + + int (*_bfd_sizeof_headers) (bfd *, struct bfd_link_info *); + bfd_byte * (*_bfd_get_relocated_section_contents) + (bfd *, struct bfd_link_info *, struct bfd_link_order *, + bfd_byte *, bfd_boolean, struct bfd_symbol **); + + bfd_boolean (*_bfd_relax_section) + (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *); + + /* Create a hash table for the linker. Different backends store + different information in this table. */ + struct bfd_link_hash_table * + (*_bfd_link_hash_table_create) (bfd *); + + /* Release the memory associated with the linker hash table. */ + void (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *); + + /* Add symbols from this object file into the hash table. */ + bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *); + + /* Indicate that we are only retrieving symbol values from this section. */ + void (*_bfd_link_just_syms) (asection *, struct bfd_link_info *); + + /* Copy the symbol type of a linker hash table entry. */ +#define bfd_copy_link_hash_symbol_type(b, t, f) \ + BFD_SEND (b, _bfd_copy_link_hash_symbol_type, (b, t, f)) + void (*_bfd_copy_link_hash_symbol_type) + (bfd *, struct bfd_link_hash_entry *, struct bfd_link_hash_entry *); + + /* Do a link based on the link_order structures attached to each + section of the BFD. */ + bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *); + + /* Should this section be split up into smaller pieces during linking. */ + bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *); + + /* Remove sections that are not referenced from the output. */ + bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *); + + /* Sets the bitmask of allowed and disallowed section flags. */ + bfd_boolean (*_bfd_lookup_section_flags) (struct bfd_link_info *, + struct flag_info *, + asection *); + + /* Attempt to merge SEC_MERGE sections. */ + bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *); + + /* Is this section a member of a group? */ + bfd_boolean (*_bfd_is_group_section) (bfd *, const struct bfd_section *); + + /* Discard members of a group. */ + bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *); + + /* Check if SEC has been already linked during a reloceatable or + final link. */ + bfd_boolean (*_section_already_linked) (bfd *, asection *, + struct bfd_link_info *); + + /* Define a common symbol. */ + bfd_boolean (*_bfd_define_common_symbol) (bfd *, struct bfd_link_info *, + struct bfd_link_hash_entry *); + + /* Routines to handle dynamic symbols and relocs. */ +#define BFD_JUMP_TABLE_DYNAMIC(NAME) \ + NAME##_get_dynamic_symtab_upper_bound, \ + NAME##_canonicalize_dynamic_symtab, \ + NAME##_get_synthetic_symtab, \ + NAME##_get_dynamic_reloc_upper_bound, \ + NAME##_canonicalize_dynamic_reloc + + /* Get the amount of memory required to hold the dynamic symbols. */ + long (*_bfd_get_dynamic_symtab_upper_bound) (bfd *); + /* Read in the dynamic symbols. */ + long (*_bfd_canonicalize_dynamic_symtab) + (bfd *, struct bfd_symbol **); + /* Create synthetized symbols. */ + long (*_bfd_get_synthetic_symtab) + (bfd *, long, struct bfd_symbol **, long, struct bfd_symbol **, + struct bfd_symbol **); + /* Get the amount of memory required to hold the dynamic relocs. */ + long (*_bfd_get_dynamic_reloc_upper_bound) (bfd *); + /* Read in the dynamic relocs. */ + long (*_bfd_canonicalize_dynamic_reloc) + (bfd *, arelent **, struct bfd_symbol **); + + /* Opposite endian version of this target. */ + const struct bfd_target * alternative_target; + + /* Data for use by back-end routines, which isn't + generic enough to belong in this structure. */ + const void *backend_data; + +} bfd_target; + +bfd_boolean bfd_set_default_target (const char *name); + +const bfd_target *bfd_find_target (const char *target_name, bfd *abfd); + +const bfd_target *bfd_get_target_info (const char *target_name, + bfd *abfd, + bfd_boolean *is_bigendian, + int *underscoring, + const char **def_target_arch); +const char ** bfd_target_list (void); + +const bfd_target *bfd_search_for_target + (int (*search_func) (const bfd_target *, void *), + void *); + +/* Extracted from format.c. */ +bfd_boolean bfd_check_format (bfd *abfd, bfd_format format); + +bfd_boolean bfd_check_format_matches + (bfd *abfd, bfd_format format, char ***matching); + +bfd_boolean bfd_set_format (bfd *abfd, bfd_format format); + +const char *bfd_format_string (bfd_format format); + +/* Extracted from linker.c. */ +bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec); + +#define bfd_link_split_section(abfd, sec) \ + BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) + +bfd_boolean bfd_section_already_linked (bfd *abfd, + asection *sec, + struct bfd_link_info *info); + +#define bfd_section_already_linked(abfd, sec, info) \ + BFD_SEND (abfd, _section_already_linked, (abfd, sec, info)) + +bfd_boolean bfd_generic_define_common_symbol + (bfd *output_bfd, struct bfd_link_info *info, + struct bfd_link_hash_entry *h); + +#define bfd_define_common_symbol(output_bfd, info, h) \ + BFD_SEND (output_bfd, _bfd_define_common_symbol, (output_bfd, info, h)) + +struct bfd_elf_version_tree * bfd_find_version_for_sym + (struct bfd_elf_version_tree *verdefs, + const char *sym_name, bfd_boolean *hide); + +bfd_boolean bfd_hide_sym_by_version + (struct bfd_elf_version_tree *verdefs, const char *sym_name); + +/* Extracted from simple.c. */ +bfd_byte *bfd_simple_get_relocated_section_contents + (bfd *abfd, asection *sec, bfd_byte *outbuf, asymbol **symbol_table); + +/* Extracted from compress.c. */ +bfd_boolean bfd_compress_section_contents + (bfd *abfd, asection *section, bfd_byte *uncompressed_buffer, + bfd_size_type uncompressed_size); + +bfd_boolean bfd_get_full_section_contents + (bfd *abfd, asection *section, bfd_byte **ptr); + +void bfd_cache_section_contents + (asection *sec, void *contents); + +bfd_boolean bfd_is_section_compressed + (bfd *abfd, asection *section); + +bfd_boolean bfd_init_section_decompress_status + (bfd *abfd, asection *section); + +bfd_boolean bfd_init_section_compress_status + (bfd *abfd, asection *section); + +#ifdef __cplusplus +} +#endif +#endif diff --git a/util/X86MAC64/include/bfdlink.h b/util/X86MAC64/include/bfdlink.h new file mode 100644 index 0000000000..1ac0738230 --- /dev/null +++ b/util/X86MAC64/include/bfdlink.h @@ -0,0 +1,842 @@ +/* bfdlink.h -- header file for BFD link routines + Copyright 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, + 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 + Free Software Foundation, Inc. + Written by Steve Chamberlain and Ian Lance Taylor, Cygnus Support. + + This file is part of BFD, the Binary File Descriptor library. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, + MA 02110-1301, USA. */ + +#ifndef BFDLINK_H +#define BFDLINK_H + +/* Which symbols to strip during a link. */ +enum bfd_link_strip +{ + strip_none, /* Don't strip any symbols. */ + strip_debugger, /* Strip debugging symbols. */ + strip_some, /* keep_hash is the list of symbols to keep. */ + strip_all /* Strip all symbols. */ +}; + +/* Which local symbols to discard during a link. This is irrelevant + if strip_all is used. */ +enum bfd_link_discard +{ + discard_sec_merge, /* Discard local temporary symbols in SEC_MERGE + sections. */ + discard_none, /* Don't discard any locals. */ + discard_l, /* Discard local temporary symbols. */ + discard_all /* Discard all locals. */ +}; + +/* Describes the type of hash table entry structure being used. + Different hash table structure have different fields and so + support different linking features. */ +enum bfd_link_hash_table_type + { + bfd_link_generic_hash_table, + bfd_link_elf_hash_table + }; + +/* These are the possible types of an entry in the BFD link hash + table. */ + +enum bfd_link_hash_type +{ + bfd_link_hash_new, /* Symbol is new. */ + bfd_link_hash_undefined, /* Symbol seen before, but undefined. */ + bfd_link_hash_undefweak, /* Symbol is weak and undefined. */ + bfd_link_hash_defined, /* Symbol is defined. */ + bfd_link_hash_defweak, /* Symbol is weak and defined. */ + bfd_link_hash_common, /* Symbol is common. */ + bfd_link_hash_indirect, /* Symbol is an indirect link. */ + bfd_link_hash_warning /* Like indirect, but warn if referenced. */ +}; + +enum bfd_link_common_skip_ar_symbols +{ + bfd_link_common_skip_none, + bfd_link_common_skip_text, + bfd_link_common_skip_data, + bfd_link_common_skip_all +}; + +struct bfd_link_hash_common_entry + { + unsigned int alignment_power; /* Alignment. */ + asection *section; /* Symbol section. */ + }; + +/* The linking routines use a hash table which uses this structure for + its elements. */ + +struct bfd_link_hash_entry +{ + /* Base hash table entry structure. */ + struct bfd_hash_entry root; + + /* Type of this entry. */ + ENUM_BITFIELD (bfd_link_hash_type) type : 8; + + unsigned int non_ir_ref : 1; + + /* A union of information depending upon the type. */ + union + { + /* Nothing is kept for bfd_hash_new. */ + /* bfd_link_hash_undefined, bfd_link_hash_undefweak. */ + struct + { + /* Undefined and common symbols are kept in a linked list through + this field. This field is present in all of the union element + so that we don't need to remove entries from the list when we + change their type. Removing entries would either require the + list to be doubly linked, which would waste more memory, or + require a traversal. When an undefined or common symbol is + created, it should be added to this list, the head of which is in + the link hash table itself. As symbols are defined, they need + not be removed from the list; anything which reads the list must + doublecheck the symbol type. + + Weak symbols are not kept on this list. + + Defined and defweak symbols use this field as a reference marker. + If the field is not NULL, or this structure is the tail of the + undefined symbol list, the symbol has been referenced. If the + symbol is undefined and becomes defined, this field will + automatically be non-NULL since the symbol will have been on the + undefined symbol list. */ + struct bfd_link_hash_entry *next; + bfd *abfd; /* BFD symbol was found in. */ + } undef; + /* bfd_link_hash_defined, bfd_link_hash_defweak. */ + struct + { + struct bfd_link_hash_entry *next; + asection *section; /* Symbol section. */ + bfd_vma value; /* Symbol value. */ + } def; + /* bfd_link_hash_indirect, bfd_link_hash_warning. */ + struct + { + struct bfd_link_hash_entry *next; + struct bfd_link_hash_entry *link; /* Real symbol. */ + const char *warning; /* Warning (bfd_link_hash_warning only). */ + } i; + /* bfd_link_hash_common. */ + struct + { + struct bfd_link_hash_entry *next; + /* The linker needs to know three things about common + symbols: the size, the alignment, and the section in + which the symbol should be placed. We store the size + here, and we allocate a small structure to hold the + section and the alignment. The alignment is stored as a + power of two. We don't store all the information + directly because we don't want to increase the size of + the union; this structure is a major space user in the + linker. */ + struct bfd_link_hash_common_entry *p; + bfd_size_type size; /* Common symbol size. */ + } c; + } u; +}; + +/* This is the link hash table. It is a derived class of + bfd_hash_table. */ + +struct bfd_link_hash_table +{ + /* The hash table itself. */ + struct bfd_hash_table table; + /* A linked list of undefined and common symbols, linked through the + next field in the bfd_link_hash_entry structure. */ + struct bfd_link_hash_entry *undefs; + /* Entries are added to the tail of the undefs list. */ + struct bfd_link_hash_entry *undefs_tail; + /* The type of the link hash table. */ + enum bfd_link_hash_table_type type; +}; + +/* Look up an entry in a link hash table. If FOLLOW is TRUE, this + follows bfd_link_hash_indirect and bfd_link_hash_warning links to + the real symbol. */ +extern struct bfd_link_hash_entry *bfd_link_hash_lookup + (struct bfd_link_hash_table *, const char *, bfd_boolean create, + bfd_boolean copy, bfd_boolean follow); + +/* Look up an entry in the main linker hash table if the symbol might + be wrapped. This should only be used for references to an + undefined symbol, not for definitions of a symbol. */ + +extern struct bfd_link_hash_entry *bfd_wrapped_link_hash_lookup + (bfd *, struct bfd_link_info *, const char *, bfd_boolean, + bfd_boolean, bfd_boolean); + +/* Traverse a link hash table. */ +extern void bfd_link_hash_traverse + (struct bfd_link_hash_table *, + bfd_boolean (*) (struct bfd_link_hash_entry *, void *), + void *); + +/* Add an entry to the undefs list. */ +extern void bfd_link_add_undef + (struct bfd_link_hash_table *, struct bfd_link_hash_entry *); + +/* Remove symbols from the undefs list that don't belong there. */ +extern void bfd_link_repair_undef_list + (struct bfd_link_hash_table *table); + +/* Read symbols and cache symbol pointer array in outsymbols. */ +extern bfd_boolean bfd_generic_link_read_symbols (bfd *); + +struct bfd_sym_chain +{ + struct bfd_sym_chain *next; + const char *name; +}; + +/* How to handle unresolved symbols. + There are four possibilities which are enumerated below: */ +enum report_method +{ + /* This is the initial value when then link_info structure is created. + It allows the various stages of the linker to determine whether they + allowed to set the value. */ + RM_NOT_YET_SET = 0, + RM_IGNORE, + RM_GENERATE_WARNING, + RM_GENERATE_ERROR +}; + +typedef enum {with_flags, without_flags} flag_type; + +/* A section flag list. */ +struct flag_info_list +{ + flag_type with; + const char *name; + bfd_boolean valid; + struct flag_info_list *next; +}; + +/* Section flag info. */ +struct flag_info +{ + flagword only_with_flags; + flagword not_with_flags; + struct flag_info_list *flag_list; + bfd_boolean flags_initialized; +}; + +struct bfd_elf_dynamic_list; +struct bfd_elf_version_tree; + +/* This structure holds all the information needed to communicate + between BFD and the linker when doing a link. */ + +struct bfd_link_info +{ + /* TRUE if BFD should generate a shared object (or a pie). */ + unsigned int shared: 1; + + /* TRUE if generating an executable, position independent or not. */ + unsigned int executable : 1; + + /* TRUE if generating a position independent executable. */ + unsigned int pie: 1; + + /* TRUE if BFD should generate a relocatable object file. */ + unsigned int relocatable: 1; + + /* TRUE if BFD should pre-bind symbols in a shared object. */ + unsigned int symbolic: 1; + + /* TRUE if executable should not contain copy relocs. + Setting this true may result in a non-sharable text segment. */ + unsigned int nocopyreloc: 1; + + /* TRUE if BFD should export all symbols in the dynamic symbol table + of an executable, rather than only those used. */ + unsigned int export_dynamic: 1; + + /* TRUE if a default symbol version should be created and used for + exported symbols. */ + unsigned int create_default_symver: 1; + + /* TRUE if unreferenced sections should be removed. */ + unsigned int gc_sections: 1; + + /* TRUE if every symbol should be reported back via the notice + callback. */ + unsigned int notice_all: 1; + + /* TRUE if we are loading LTO outputs. */ + unsigned int loading_lto_outputs: 1; + + /* TRUE if global symbols in discarded sections should be stripped. */ + unsigned int strip_discarded: 1; + + /* TRUE if all data symbols should be dynamic. */ + unsigned int dynamic_data: 1; + + /* Which symbols to strip. */ + ENUM_BITFIELD (bfd_link_strip) strip : 2; + + /* Which local symbols to discard. */ + ENUM_BITFIELD (bfd_link_discard) discard : 2; + + /* Criteria for skipping symbols when determining + whether to include an object from an archive. */ + ENUM_BITFIELD (bfd_link_common_skip_ar_symbols) common_skip_ar_symbols : 2; + + /* What to do with unresolved symbols in an object file. + When producing executables the default is GENERATE_ERROR. + When producing shared libraries the default is IGNORE. The + assumption with shared libraries is that the reference will be + resolved at load/execution time. */ + ENUM_BITFIELD (report_method) unresolved_syms_in_objects : 2; + + /* What to do with unresolved symbols in a shared library. + The same defaults apply. */ + ENUM_BITFIELD (report_method) unresolved_syms_in_shared_libs : 2; + + /* TRUE if shared objects should be linked directly, not shared. */ + unsigned int static_link: 1; + + /* TRUE if symbols should be retained in memory, FALSE if they + should be freed and reread. */ + unsigned int keep_memory: 1; + + /* TRUE if BFD should generate relocation information in the final + executable. */ + unsigned int emitrelocations: 1; + + /* TRUE if PT_GNU_RELRO segment should be created. */ + unsigned int relro: 1; + + /* TRUE if .eh_frame_hdr section and PT_GNU_EH_FRAME ELF segment + should be created. */ + unsigned int eh_frame_hdr: 1; + + /* TRUE if we should warn when adding a DT_TEXTREL to a shared object. */ + unsigned int warn_shared_textrel: 1; + + /* TRUE if we should error when adding a DT_TEXTREL. */ + unsigned int error_textrel: 1; + + /* TRUE if .hash section should be created. */ + unsigned int emit_hash: 1; + + /* TRUE if .gnu.hash section should be created. */ + unsigned int emit_gnu_hash: 1; + + /* If TRUE reduce memory overheads, at the expense of speed. This will + cause map file generation to use an O(N^2) algorithm and disable + caching ELF symbol buffer. */ + unsigned int reduce_memory_overheads: 1; + + /* TRUE if the output file should be in a traditional format. This + is equivalent to the setting of the BFD_TRADITIONAL_FORMAT flag + on the output file, but may be checked when reading the input + files. */ + unsigned int traditional_format: 1; + + /* TRUE if non-PLT relocs should be merged into one reloc section + and sorted so that relocs against the same symbol come together. */ + unsigned int combreloc: 1; + + /* TRUE if a default symbol version should be created and used for + imported symbols. */ + unsigned int default_imported_symver: 1; + + /* TRUE if the new ELF dynamic tags are enabled. */ + unsigned int new_dtags: 1; + + /* FALSE if .eh_frame unwind info should be generated for PLT and other + linker created sections, TRUE if it should be omitted. */ + unsigned int no_ld_generated_unwind_info: 1; + + /* TRUE if BFD should generate a "task linked" object file, + similar to relocatable but also with globals converted to + statics. */ + unsigned int task_link: 1; + + /* TRUE if ok to have multiple definition. */ + unsigned int allow_multiple_definition: 1; + + /* TRUE if ok to have version with no definition. */ + unsigned int allow_undefined_version: 1; + + /* TRUE if some symbols have to be dynamic, controlled by + --dynamic-list command line options. */ + unsigned int dynamic: 1; + + /* TRUE if PT_GNU_STACK segment should be created with PF_R|PF_W|PF_X + flags. */ + unsigned int execstack: 1; + + /* TRUE if PT_GNU_STACK segment should be created with PF_R|PF_W + flags. */ + unsigned int noexecstack: 1; + + /* TRUE if we want to produced optimized output files. This might + need much more time and therefore must be explicitly selected. */ + unsigned int optimize: 1; + + /* TRUE if user should be informed of removed unreferenced sections. */ + unsigned int print_gc_sections: 1; + + /* TRUE if we should warn alternate ELF machine code. */ + unsigned int warn_alternate_em: 1; + + /* TRUE if the linker script contained an explicit PHDRS command. */ + unsigned int user_phdrs: 1; + + /* Char that may appear as the first char of a symbol, but should be + skipped (like symbol_leading_char) when looking up symbols in + wrap_hash. Used by PowerPC Linux for 'dot' symbols. */ + char wrap_char; + + /* Separator between archive and filename in linker script filespecs. */ + char path_separator; + + /* Default stack size. Zero means default (often zero itself), -1 + means explicitly zero-sized. */ + bfd_signed_vma stacksize; + + /* Enable or disable target specific optimizations. + + Not all targets have optimizations to enable. + + Normally these optimizations are disabled by default but some targets + prefer to enable them by default. So this field is a tri-state variable. + The values are: + + zero: Enable the optimizations (either from --relax being specified on + the command line or the backend's before_allocation emulation function. + + positive: The user has requested that these optimizations be disabled. + (Via the --no-relax command line option). + + negative: The optimizations are disabled. (Set when initializing the + args_type structure in ldmain.c:main. */ + signed int disable_target_specific_optimizations; + + /* Function callbacks. */ + const struct bfd_link_callbacks *callbacks; + + /* Hash table handled by BFD. */ + struct bfd_link_hash_table *hash; + + /* Hash table of symbols to keep. This is NULL unless strip is + strip_some. */ + struct bfd_hash_table *keep_hash; + + /* Hash table of symbols to report back via the notice callback. If + this is NULL, and notice_all is FALSE, then no symbols are + reported back. */ + struct bfd_hash_table *notice_hash; + + /* Hash table of symbols which are being wrapped (the --wrap linker + option). If this is NULL, no symbols are being wrapped. */ + struct bfd_hash_table *wrap_hash; + + /* Hash table of symbols which may be left unresolved during + a link. If this is NULL, no symbols can be left unresolved. */ + struct bfd_hash_table *ignore_hash; + + /* The output BFD. */ + bfd *output_bfd; + + /* The list of input BFD's involved in the link. These are chained + together via the link_next field. */ + bfd *input_bfds; + bfd **input_bfds_tail; + + /* If a symbol should be created for each input BFD, this is section + where those symbols should be placed. It must be a section in + the output BFD. It may be NULL, in which case no such symbols + will be created. This is to support CREATE_OBJECT_SYMBOLS in the + linker command language. */ + asection *create_object_symbols_section; + + /* List of global symbol names that are starting points for marking + sections against garbage collection. */ + struct bfd_sym_chain *gc_sym_list; + + /* If a base output file is wanted, then this points to it */ + void *base_file; + + /* The function to call when the executable or shared object is + loaded. */ + const char *init_function; + + /* The function to call when the executable or shared object is + unloaded. */ + const char *fini_function; + + /* Number of relaxation passes. Usually only one relaxation pass + is needed. But a backend can have as many relaxation passes as + necessary. During bfd_relax_section call, it is set to the + current pass, starting from 0. */ + int relax_pass; + + /* Number of relaxation trips. This number is incremented every + time the relaxation pass is restarted due to a previous + relaxation returning true in *AGAIN. */ + int relax_trip; + + /* Non-zero if auto-import thunks for DATA items in pei386 DLLs + should be generated/linked against. Set to 1 if this feature + is explicitly requested by the user, -1 if enabled by default. */ + int pei386_auto_import; + + /* Non-zero if runtime relocs for DATA items with non-zero addends + in pei386 DLLs should be generated. Set to 1 if this feature + is explicitly requested by the user, -1 if enabled by default. */ + int pei386_runtime_pseudo_reloc; + + /* How many spare .dynamic DT_NULL entries should be added? */ + unsigned int spare_dynamic_tags; + + /* May be used to set DT_FLAGS for ELF. */ + bfd_vma flags; + + /* May be used to set DT_FLAGS_1 for ELF. */ + bfd_vma flags_1; + + /* Start and end of RELRO region. */ + bfd_vma relro_start, relro_end; + + /* List of symbols should be dynamic. */ + struct bfd_elf_dynamic_list *dynamic_list; + + /* The version information. */ + struct bfd_elf_version_tree *version_info; +}; + +/* This structures holds a set of callback functions. These are called + by the BFD linker routines. Except for the info functions, the first + argument to each callback function is the bfd_link_info structure + being used and each function returns a boolean value. If the + function returns FALSE, then the BFD function which called it should + return with a failure indication. */ + +struct bfd_link_callbacks +{ + /* A function which is called when an object is added from an + archive. ABFD is the archive element being added. NAME is the + name of the symbol which caused the archive element to be pulled + in. This function may set *SUBSBFD to point to an alternative + BFD from which symbols should in fact be added in place of the + original BFD's symbols. */ + bfd_boolean (*add_archive_element) + (struct bfd_link_info *, bfd *abfd, const char *name, bfd **subsbfd); + /* A function which is called when a symbol is found with multiple + definitions. H is the symbol which is defined multiple times. + NBFD is the new BFD, NSEC is the new section, and NVAL is the new + value. NSEC may be bfd_com_section or bfd_ind_section. */ + bfd_boolean (*multiple_definition) + (struct bfd_link_info *, struct bfd_link_hash_entry *h, + bfd *nbfd, asection *nsec, bfd_vma nval); + /* A function which is called when a common symbol is defined + multiple times. H is the symbol appearing multiple times. + NBFD is the BFD of the new symbol. NTYPE is the type of the new + symbol, one of bfd_link_hash_defined, bfd_link_hash_common, or + bfd_link_hash_indirect. If NTYPE is bfd_link_hash_common, NSIZE + is the size of the new symbol. */ + bfd_boolean (*multiple_common) + (struct bfd_link_info *, struct bfd_link_hash_entry *h, + bfd *nbfd, enum bfd_link_hash_type ntype, bfd_vma nsize); + /* A function which is called to add a symbol to a set. ENTRY is + the link hash table entry for the set itself (e.g., + __CTOR_LIST__). RELOC is the relocation to use for an entry in + the set when generating a relocatable file, and is also used to + get the size of the entry when generating an executable file. + ABFD, SEC and VALUE identify the value to add to the set. */ + bfd_boolean (*add_to_set) + (struct bfd_link_info *, struct bfd_link_hash_entry *entry, + bfd_reloc_code_real_type reloc, bfd *abfd, asection *sec, bfd_vma value); + /* A function which is called when the name of a g++ constructor or + destructor is found. This is only called by some object file + formats. CONSTRUCTOR is TRUE for a constructor, FALSE for a + destructor. This will use BFD_RELOC_CTOR when generating a + relocatable file. NAME is the name of the symbol found. ABFD, + SECTION and VALUE are the value of the symbol. */ + bfd_boolean (*constructor) + (struct bfd_link_info *, bfd_boolean constructor, const char *name, + bfd *abfd, asection *sec, bfd_vma value); + /* A function which is called to issue a linker warning. For + example, this is called when there is a reference to a warning + symbol. WARNING is the warning to be issued. SYMBOL is the name + of the symbol which triggered the warning; it may be NULL if + there is none. ABFD, SECTION and ADDRESS identify the location + which trigerred the warning; either ABFD or SECTION or both may + be NULL if the location is not known. */ + bfd_boolean (*warning) + (struct bfd_link_info *, const char *warning, const char *symbol, + bfd *abfd, asection *section, bfd_vma address); + /* A function which is called when a relocation is attempted against + an undefined symbol. NAME is the symbol which is undefined. + ABFD, SECTION and ADDRESS identify the location from which the + reference is made. IS_FATAL indicates whether an undefined symbol is + a fatal error or not. In some cases SECTION may be NULL. */ + bfd_boolean (*undefined_symbol) + (struct bfd_link_info *, const char *name, bfd *abfd, + asection *section, bfd_vma address, bfd_boolean is_fatal); + /* A function which is called when a reloc overflow occurs. ENTRY is + the link hash table entry for the symbol the reloc is against. + NAME is the name of the local symbol or section the reloc is + against, RELOC_NAME is the name of the relocation, and ADDEND is + any addend that is used. ABFD, SECTION and ADDRESS identify the + location at which the overflow occurs; if this is the result of a + bfd_section_reloc_link_order or bfd_symbol_reloc_link_order, then + ABFD will be NULL. */ + bfd_boolean (*reloc_overflow) + (struct bfd_link_info *, struct bfd_link_hash_entry *entry, + const char *name, const char *reloc_name, bfd_vma addend, + bfd *abfd, asection *section, bfd_vma address); + /* A function which is called when a dangerous reloc is performed. + MESSAGE is an appropriate message. + ABFD, SECTION and ADDRESS identify the location at which the + problem occurred; if this is the result of a + bfd_section_reloc_link_order or bfd_symbol_reloc_link_order, then + ABFD will be NULL. */ + bfd_boolean (*reloc_dangerous) + (struct bfd_link_info *, const char *message, + bfd *abfd, asection *section, bfd_vma address); + /* A function which is called when a reloc is found to be attached + to a symbol which is not being written out. NAME is the name of + the symbol. ABFD, SECTION and ADDRESS identify the location of + the reloc; if this is the result of a + bfd_section_reloc_link_order or bfd_symbol_reloc_link_order, then + ABFD will be NULL. */ + bfd_boolean (*unattached_reloc) + (struct bfd_link_info *, const char *name, + bfd *abfd, asection *section, bfd_vma address); + /* A function which is called when a symbol in notice_hash is + defined or referenced. H is the symbol. ABFD, SECTION and + ADDRESS are the (new) value of the symbol. If SECTION is + bfd_und_section, this is a reference. FLAGS are the symbol + BSF_* flags. STRING is the name of the symbol to indirect to if + the sym is indirect, or the warning string if a warning sym. */ + bfd_boolean (*notice) + (struct bfd_link_info *, struct bfd_link_hash_entry *h, + bfd *abfd, asection *section, bfd_vma address, flagword flags, + const char *string); + /* Error or warning link info message. */ + void (*einfo) + (const char *fmt, ...); + /* General link info message. */ + void (*info) + (const char *fmt, ...); + /* Message to be printed in linker map file. */ + void (*minfo) + (const char *fmt, ...); + /* This callback provides a chance for users of the BFD library to + override its decision about whether to place two adjacent sections + into the same segment. */ + bfd_boolean (*override_segment_assignment) + (struct bfd_link_info *, bfd * abfd, + asection * current_section, asection * previous_section, + bfd_boolean new_segment); +}; + +/* The linker builds link_order structures which tell the code how to + include input data in the output file. */ + +/* These are the types of link_order structures. */ + +enum bfd_link_order_type +{ + bfd_undefined_link_order, /* Undefined. */ + bfd_indirect_link_order, /* Built from a section. */ + bfd_data_link_order, /* Set to explicit data. */ + bfd_section_reloc_link_order, /* Relocate against a section. */ + bfd_symbol_reloc_link_order /* Relocate against a symbol. */ +}; + +/* This is the link_order structure itself. These form a chain + attached to the output section whose contents they are describing. */ + +struct bfd_link_order +{ + /* Next link_order in chain. */ + struct bfd_link_order *next; + /* Type of link_order. */ + enum bfd_link_order_type type; + /* Offset within output section. */ + bfd_vma offset; + /* Size within output section. */ + bfd_size_type size; + /* Type specific information. */ + union + { + struct + { + /* Section to include. If this is used, then + section->output_section must be the section the + link_order is attached to, section->output_offset must + equal the link_order offset field, and section->size + must equal the link_order size field. Maybe these + restrictions should be relaxed someday. */ + asection *section; + } indirect; + struct + { + /* Size of contents, or zero when contents should be filled by + the architecture-dependent fill function. + A non-zero value allows filling of the output section + with an arbitrary repeated pattern. */ + unsigned int size; + /* Data to put into file. */ + bfd_byte *contents; + } data; + struct + { + /* Description of reloc to generate. Used for + bfd_section_reloc_link_order and + bfd_symbol_reloc_link_order. */ + struct bfd_link_order_reloc *p; + } reloc; + } u; +}; + +/* A linker order of type bfd_section_reloc_link_order or + bfd_symbol_reloc_link_order means to create a reloc against a + section or symbol, respectively. This is used to implement -Ur to + generate relocs for the constructor tables. The + bfd_link_order_reloc structure describes the reloc that BFD should + create. It is similar to a arelent, but I didn't use arelent + because the linker does not know anything about most symbols, and + any asymbol structure it creates will be partially meaningless. + This information could logically be in the bfd_link_order struct, + but I didn't want to waste the space since these types of relocs + are relatively rare. */ + +struct bfd_link_order_reloc +{ + /* Reloc type. */ + bfd_reloc_code_real_type reloc; + + union + { + /* For type bfd_section_reloc_link_order, this is the section + the reloc should be against. This must be a section in the + output BFD, not any of the input BFDs. */ + asection *section; + /* For type bfd_symbol_reloc_link_order, this is the name of the + symbol the reloc should be against. */ + const char *name; + } u; + + /* Addend to use. The object file should contain zero. The BFD + backend is responsible for filling in the contents of the object + file correctly. For some object file formats (e.g., COFF) the + addend must be stored into in the object file, and for some + (e.g., SPARC a.out) it is kept in the reloc. */ + bfd_vma addend; +}; + +/* Allocate a new link_order for a section. */ +extern struct bfd_link_order *bfd_new_link_order (bfd *, asection *); + +/* These structures are used to describe version information for the + ELF linker. These structures could be manipulated entirely inside + BFD, but it would be a pain. Instead, the regular linker sets up + these structures, and then passes them into BFD. */ + +/* Glob pattern for a version. */ + +struct bfd_elf_version_expr +{ + /* Next glob pattern for this version. */ + struct bfd_elf_version_expr *next; + /* Glob pattern. */ + const char *pattern; + /* Set if pattern is not a glob. */ + unsigned int literal : 1; + /* Defined by ".symver". */ + unsigned int symver : 1; + /* Defined by version script. */ + unsigned int script : 1; + /* Pattern type. */ +#define BFD_ELF_VERSION_C_TYPE 1 +#define BFD_ELF_VERSION_CXX_TYPE 2 +#define BFD_ELF_VERSION_JAVA_TYPE 4 + unsigned int mask : 3; +}; + +struct bfd_elf_version_expr_head +{ + /* List of all patterns, both wildcards and non-wildcards. */ + struct bfd_elf_version_expr *list; + /* Hash table for non-wildcards. */ + void *htab; + /* Remaining patterns. */ + struct bfd_elf_version_expr *remaining; + /* What kind of pattern types are present in list (bitmask). */ + unsigned int mask; +}; + +/* Version dependencies. */ + +struct bfd_elf_version_deps +{ + /* Next dependency for this version. */ + struct bfd_elf_version_deps *next; + /* The version which this version depends upon. */ + struct bfd_elf_version_tree *version_needed; +}; + +/* A node in the version tree. */ + +struct bfd_elf_version_tree +{ + /* Next version. */ + struct bfd_elf_version_tree *next; + /* Name of this version. */ + const char *name; + /* Version number. */ + unsigned int vernum; + /* Regular expressions for global symbols in this version. */ + struct bfd_elf_version_expr_head globals; + /* Regular expressions for local symbols in this version. */ + struct bfd_elf_version_expr_head locals; + /* List of versions which this version depends upon. */ + struct bfd_elf_version_deps *deps; + /* Index of the version name. This is used within BFD. */ + unsigned int name_indx; + /* Whether this version tree was used. This is used within BFD. */ + int used; + /* Matching hook. */ + struct bfd_elf_version_expr *(*match) + (struct bfd_elf_version_expr_head *head, + struct bfd_elf_version_expr *prev, const char *sym); +}; + +struct bfd_elf_dynamic_list +{ + struct bfd_elf_version_expr_head head; + struct bfd_elf_version_expr *(*match) + (struct bfd_elf_version_expr_head *head, + struct bfd_elf_version_expr *prev, const char *sym); +}; + +#endif diff --git a/util/X86MAC64/include/dis-asm.h b/util/X86MAC64/include/dis-asm.h new file mode 100644 index 0000000000..4afdc2a226 --- /dev/null +++ b/util/X86MAC64/include/dis-asm.h @@ -0,0 +1,382 @@ +/* Interface between the opcode library and its callers. + + Copyright 1999-2013 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street - Fifth Floor, + Boston, MA 02110-1301, USA. + + Written by Cygnus Support, 1993. + + The opcode library (libopcodes.a) provides instruction decoders for + a large variety of instruction sets, callable with an identical + interface, for making instruction-processing programs more independent + of the instruction set being processed. */ + +#ifndef DIS_ASM_H +#define DIS_ASM_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include "bfd.h" + + typedef int (*fprintf_ftype) (void *, const char*, ...) ATTRIBUTE_FPTR_PRINTF_2; + +enum dis_insn_type +{ + dis_noninsn, /* Not a valid instruction. */ + dis_nonbranch, /* Not a branch instruction. */ + dis_branch, /* Unconditional branch. */ + dis_condbranch, /* Conditional branch. */ + dis_jsr, /* Jump to subroutine. */ + dis_condjsr, /* Conditional jump to subroutine. */ + dis_dref, /* Data reference instruction. */ + dis_dref2 /* Two data references in instruction. */ +}; + +/* This struct is passed into the instruction decoding routine, + and is passed back out into each callback. The various fields are used + for conveying information from your main routine into your callbacks, + for passing information into the instruction decoders (such as the + addresses of the callback functions), or for passing information + back from the instruction decoders to their callers. + + It must be initialized before it is first passed; this can be done + by hand, or using one of the initialization macros below. */ + +typedef struct disassemble_info +{ + fprintf_ftype fprintf_func; + void *stream; + void *application_data; + + /* Target description. We could replace this with a pointer to the bfd, + but that would require one. There currently isn't any such requirement + so to avoid introducing one we record these explicitly. */ + /* The bfd_flavour. This can be bfd_target_unknown_flavour. */ + enum bfd_flavour flavour; + /* The bfd_arch value. */ + enum bfd_architecture arch; + /* The bfd_mach value. */ + unsigned long mach; + /* Endianness (for bi-endian cpus). Mono-endian cpus can ignore this. */ + enum bfd_endian endian; + /* Endianness of code, for mixed-endian situations such as ARM BE8. */ + enum bfd_endian endian_code; + /* An arch/mach-specific bitmask of selected instruction subsets, mainly + for processors with run-time-switchable instruction sets. The default, + zero, means that there is no constraint. CGEN-based opcodes ports + may use ISA_foo masks. */ + void *insn_sets; + + /* Some targets need information about the current section to accurately + display insns. If this is NULL, the target disassembler function + will have to make its best guess. */ + asection *section; + + /* An array of pointers to symbols either at the location being disassembled + or at the start of the function being disassembled. The array is sorted + so that the first symbol is intended to be the one used. The others are + present for any misc. purposes. This is not set reliably, but if it is + not NULL, it is correct. */ + asymbol **symbols; + /* Number of symbols in array. */ + int num_symbols; + + /* Symbol table provided for targets that want to look at it. This is + used on Arm to find mapping symbols and determine Arm/Thumb code. */ + asymbol **symtab; + int symtab_pos; + int symtab_size; + + /* For use by the disassembler. + The top 16 bits are reserved for public use (and are documented here). + The bottom 16 bits are for the internal use of the disassembler. */ + unsigned long flags; + /* Set if the disassembler has determined that there are one or more + relocations associated with the instruction being disassembled. */ +#define INSN_HAS_RELOC (1 << 31) + /* Set if the user has requested the disassembly of data as well as code. */ +#define DISASSEMBLE_DATA (1 << 30) + /* Set if the user has specifically set the machine type encoded in the + mach field of this structure. */ +#define USER_SPECIFIED_MACHINE_TYPE (1 << 29) + + /* Use internally by the target specific disassembly code. */ + void *private_data; + + /* Function used to get bytes to disassemble. MEMADDR is the + address of the stuff to be disassembled, MYADDR is the address to + put the bytes in, and LENGTH is the number of bytes to read. + INFO is a pointer to this struct. + Returns an errno value or 0 for success. */ + int (*read_memory_func) + (bfd_vma memaddr, bfd_byte *myaddr, unsigned int length, + struct disassemble_info *dinfo); + + /* Function which should be called if we get an error that we can't + recover from. STATUS is the errno value from read_memory_func and + MEMADDR is the address that we were trying to read. INFO is a + pointer to this struct. */ + void (*memory_error_func) + (int status, bfd_vma memaddr, struct disassemble_info *dinfo); + + /* Function called to print ADDR. */ + void (*print_address_func) + (bfd_vma addr, struct disassemble_info *dinfo); + + /* Function called to determine if there is a symbol at the given ADDR. + If there is, the function returns 1, otherwise it returns 0. + This is used by ports which support an overlay manager where + the overlay number is held in the top part of an address. In + some circumstances we want to include the overlay number in the + address, (normally because there is a symbol associated with + that address), but sometimes we want to mask out the overlay bits. */ + int (* symbol_at_address_func) + (bfd_vma addr, struct disassemble_info *dinfo); + + /* Function called to check if a SYMBOL is can be displayed to the user. + This is used by some ports that want to hide special symbols when + displaying debugging outout. */ + bfd_boolean (* symbol_is_valid) + (asymbol *, struct disassemble_info *dinfo); + + /* These are for buffer_read_memory. */ + bfd_byte *buffer; + bfd_vma buffer_vma; + unsigned int buffer_length; + + /* This variable may be set by the instruction decoder. It suggests + the number of bytes objdump should display on a single line. If + the instruction decoder sets this, it should always set it to + the same value in order to get reasonable looking output. */ + int bytes_per_line; + + /* The next two variables control the way objdump displays the raw data. */ + /* For example, if bytes_per_line is 8 and bytes_per_chunk is 4, the */ + /* output will look like this: + 00: 00000000 00000000 + with the chunks displayed according to "display_endian". */ + int bytes_per_chunk; + enum bfd_endian display_endian; + + /* Number of octets per incremented target address + Normally one, but some DSPs have byte sizes of 16 or 32 bits. */ + unsigned int octets_per_byte; + + /* The number of zeroes we want to see at the end of a section before we + start skipping them. */ + unsigned int skip_zeroes; + + /* The number of zeroes to skip at the end of a section. If the number + of zeroes at the end is between SKIP_ZEROES_AT_END and SKIP_ZEROES, + they will be disassembled. If there are fewer than + SKIP_ZEROES_AT_END, they will be skipped. This is a heuristic + attempt to avoid disassembling zeroes inserted by section + alignment. */ + unsigned int skip_zeroes_at_end; + + /* Whether the disassembler always needs the relocations. */ + bfd_boolean disassembler_needs_relocs; + + /* Results from instruction decoders. Not all decoders yet support + this information. This info is set each time an instruction is + decoded, and is only valid for the last such instruction. + + To determine whether this decoder supports this information, set + insn_info_valid to 0, decode an instruction, then check it. */ + + char insn_info_valid; /* Branch info has been set. */ + char branch_delay_insns; /* How many sequential insn's will run before + a branch takes effect. (0 = normal) */ + char data_size; /* Size of data reference in insn, in bytes */ + enum dis_insn_type insn_type; /* Type of instruction */ + bfd_vma target; /* Target address of branch or dref, if known; + zero if unknown. */ + bfd_vma target2; /* Second target address for dref2 */ + + /* Command line options specific to the target disassembler. */ + char * disassembler_options; + +} disassemble_info; + + +/* Standard disassemblers. Disassemble one instruction at the given + target address. Return number of octets processed. */ +typedef int (*disassembler_ftype) (bfd_vma, disassemble_info *); + +extern int print_insn_aarch64 (bfd_vma, disassemble_info *); +extern int print_insn_alpha (bfd_vma, disassemble_info *); +extern int print_insn_avr (bfd_vma, disassemble_info *); +extern int print_insn_bfin (bfd_vma, disassemble_info *); +extern int print_insn_big_arm (bfd_vma, disassemble_info *); +extern int print_insn_big_mips (bfd_vma, disassemble_info *); +extern int print_insn_big_nios2 (bfd_vma, disassemble_info *); +extern int print_insn_big_or32 (bfd_vma, disassemble_info *); +extern int print_insn_big_powerpc (bfd_vma, disassemble_info *); +extern int print_insn_big_score (bfd_vma, disassemble_info *); +extern int print_insn_cr16 (bfd_vma, disassemble_info *); +extern int print_insn_crx (bfd_vma, disassemble_info *); +extern int print_insn_d10v (bfd_vma, disassemble_info *); +extern int print_insn_d30v (bfd_vma, disassemble_info *); +extern int print_insn_dlx (bfd_vma, disassemble_info *); +extern int print_insn_epiphany (bfd_vma, disassemble_info *); +extern int print_insn_fr30 (bfd_vma, disassemble_info *); +extern int print_insn_frv (bfd_vma, disassemble_info *); +extern int print_insn_h8300 (bfd_vma, disassemble_info *); +extern int print_insn_h8300h (bfd_vma, disassemble_info *); +extern int print_insn_h8300s (bfd_vma, disassemble_info *); +extern int print_insn_h8500 (bfd_vma, disassemble_info *); +extern int print_insn_hppa (bfd_vma, disassemble_info *); +extern int print_insn_i370 (bfd_vma, disassemble_info *); +extern int print_insn_i386 (bfd_vma, disassemble_info *); +extern int print_insn_i386_att (bfd_vma, disassemble_info *); +extern int print_insn_i386_intel (bfd_vma, disassemble_info *); +extern int print_insn_i860 (bfd_vma, disassemble_info *); +extern int print_insn_i960 (bfd_vma, disassemble_info *); +extern int print_insn_ia64 (bfd_vma, disassemble_info *); +extern int print_insn_ip2k (bfd_vma, disassemble_info *); +extern int print_insn_iq2000 (bfd_vma, disassemble_info *); +extern int print_insn_little_arm (bfd_vma, disassemble_info *); +extern int print_insn_little_mips (bfd_vma, disassemble_info *); +extern int print_insn_little_nios2 (bfd_vma, disassemble_info *); +extern int print_insn_little_or32 (bfd_vma, disassemble_info *); +extern int print_insn_little_powerpc (bfd_vma, disassemble_info *); +extern int print_insn_little_score (bfd_vma, disassemble_info *); +extern int print_insn_lm32 (bfd_vma, disassemble_info *); +extern int print_insn_m32c (bfd_vma, disassemble_info *); +extern int print_insn_m32r (bfd_vma, disassemble_info *); +extern int print_insn_m68hc11 (bfd_vma, disassemble_info *); +extern int print_insn_m68hc12 (bfd_vma, disassemble_info *); +extern int print_insn_m9s12x (bfd_vma, disassemble_info *); +extern int print_insn_m9s12xg (bfd_vma, disassemble_info *); +extern int print_insn_m68k (bfd_vma, disassemble_info *); +extern int print_insn_m88k (bfd_vma, disassemble_info *); +extern int print_insn_mcore (bfd_vma, disassemble_info *); +extern int print_insn_mep (bfd_vma, disassemble_info *); +extern int print_insn_metag (bfd_vma, disassemble_info *); +extern int print_insn_microblaze (bfd_vma, disassemble_info *); +extern int print_insn_mmix (bfd_vma, disassemble_info *); +extern int print_insn_mn10200 (bfd_vma, disassemble_info *); +extern int print_insn_mn10300 (bfd_vma, disassemble_info *); +extern int print_insn_moxie (bfd_vma, disassemble_info *); +extern int print_insn_msp430 (bfd_vma, disassemble_info *); +extern int print_insn_mt (bfd_vma, disassemble_info *); +extern int print_insn_nds32 (bfd_vma, disassemble_info *); +extern int print_insn_ns32k (bfd_vma, disassemble_info *); +extern int print_insn_openrisc (bfd_vma, disassemble_info *); +extern int print_insn_pdp11 (bfd_vma, disassemble_info *); +extern int print_insn_pj (bfd_vma, disassemble_info *); +extern int print_insn_rs6000 (bfd_vma, disassemble_info *); +extern int print_insn_s390 (bfd_vma, disassemble_info *); +extern int print_insn_sh (bfd_vma, disassemble_info *); +extern int print_insn_sh64 (bfd_vma, disassemble_info *); +extern int print_insn_sh64x_media (bfd_vma, disassemble_info *); +extern int print_insn_sparc (bfd_vma, disassemble_info *); +extern int print_insn_spu (bfd_vma, disassemble_info *); +extern int print_insn_tic30 (bfd_vma, disassemble_info *); +extern int print_insn_tic4x (bfd_vma, disassemble_info *); +extern int print_insn_tic54x (bfd_vma, disassemble_info *); +extern int print_insn_tic6x (bfd_vma, disassemble_info *); +extern int print_insn_tic80 (bfd_vma, disassemble_info *); +extern int print_insn_tilegx (bfd_vma, disassemble_info *); +extern int print_insn_tilepro (bfd_vma, disassemble_info *); +extern int print_insn_v850 (bfd_vma, disassemble_info *); +extern int print_insn_vax (bfd_vma, disassemble_info *); +extern int print_insn_w65 (bfd_vma, disassemble_info *); +extern int print_insn_xc16x (bfd_vma, disassemble_info *); +extern int print_insn_xgate (bfd_vma, disassemble_info *); +extern int print_insn_xstormy16 (bfd_vma, disassemble_info *); +extern int print_insn_xtensa (bfd_vma, disassemble_info *); +extern int print_insn_z80 (bfd_vma, disassemble_info *); +extern int print_insn_z8001 (bfd_vma, disassemble_info *); +extern int print_insn_z8002 (bfd_vma, disassemble_info *); +extern int print_insn_rx (bfd_vma, disassemble_info *); +extern int print_insn_rl78 (bfd_vma, disassemble_info *); + +extern disassembler_ftype arc_get_disassembler (void *); +extern disassembler_ftype cris_get_disassembler (bfd *); + +extern void print_aarch64_disassembler_options (FILE *); +extern void print_i386_disassembler_options (FILE *); +extern void print_mips_disassembler_options (FILE *); +extern void print_ppc_disassembler_options (FILE *); +extern void print_arm_disassembler_options (FILE *); +extern void parse_arm_disassembler_option (char *); +extern void print_s390_disassembler_options (FILE *); +extern int get_arm_regname_num_options (void); +extern int set_arm_regname_option (int); +extern int get_arm_regnames (int, const char **, const char **, const char *const **); +extern bfd_boolean aarch64_symbol_is_valid (asymbol *, struct disassemble_info *); +extern bfd_boolean arm_symbol_is_valid (asymbol *, struct disassemble_info *); +extern void disassemble_init_powerpc (struct disassemble_info *); + +/* Fetch the disassembler for a given BFD, if that support is available. */ +extern disassembler_ftype disassembler (bfd *); + +/* Amend the disassemble_info structure as necessary for the target architecture. + Should only be called after initialising the info->arch field. */ +extern void disassemble_init_for_target (struct disassemble_info * dinfo); + +/* Document any target specific options available from the disassembler. */ +extern void disassembler_usage (FILE *); + + +/* This block of definitions is for particular callers who read instructions + into a buffer before calling the instruction decoder. */ + +/* Here is a function which callers may wish to use for read_memory_func. + It gets bytes from a buffer. */ +extern int buffer_read_memory + (bfd_vma, bfd_byte *, unsigned int, struct disassemble_info *); + +/* This function goes with buffer_read_memory. + It prints a message using info->fprintf_func and info->stream. */ +extern void perror_memory (int, bfd_vma, struct disassemble_info *); + + +/* Just print the address in hex. This is included for completeness even + though both GDB and objdump provide their own (to print symbolic + addresses). */ +extern void generic_print_address + (bfd_vma, struct disassemble_info *); + +/* Always true. */ +extern int generic_symbol_at_address + (bfd_vma, struct disassemble_info *); + +/* Also always true. */ +extern bfd_boolean generic_symbol_is_valid + (asymbol *, struct disassemble_info *); + +/* Method to initialize a disassemble_info struct. This should be + called by all applications creating such a struct. */ +extern void init_disassemble_info (struct disassemble_info *dinfo, void *stream, + fprintf_ftype fprintf_func); + +/* For compatibility with existing code. */ +#define INIT_DISASSEMBLE_INFO(INFO, STREAM, FPRINTF_FUNC) \ + init_disassemble_info (&(INFO), (STREAM), (fprintf_ftype) (FPRINTF_FUNC)) +#define INIT_DISASSEMBLE_INFO_NO_ARCH(INFO, STREAM, FPRINTF_FUNC) \ + init_disassemble_info (&(INFO), (STREAM), (fprintf_ftype) (FPRINTF_FUNC)) + + +#ifdef __cplusplus +} +#endif + +#endif /* ! defined (DIS_ASM_H) */ diff --git a/util/X86MAC64/include/gdb/jit-reader.h b/util/X86MAC64/include/gdb/jit-reader.h new file mode 100644 index 0000000000..e9599a2b8d --- /dev/null +++ b/util/X86MAC64/include/gdb/jit-reader.h @@ -0,0 +1,346 @@ +/* JIT declarations for GDB, the GNU Debugger. + + Copyright (C) 2011-2014 Free Software Foundation, Inc. + + This file is part of GDB. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . */ + +#ifndef GDB_JIT_READER_H +#define GDB_JIT_READER_H + +#ifdef __cplusplus +extern "C" { +#endif + +/* Versioning information. See gdb_reader_funcs. */ + +#define GDB_READER_INTERFACE_VERSION 1 + +/* Readers must be released under a GPL compatible license. To + declare that the reader is indeed released under a GPL compatible + license, invoke the macro GDB_DECLARE_GPL_COMPATIBLE in a source + file. */ + +#ifdef __cplusplus +#define GDB_DECLARE_GPL_COMPATIBLE_READER \ + extern "C" { \ + extern int plugin_is_GPL_compatible (void); \ + extern int plugin_is_GPL_compatible (void) \ + { \ + return 0; \ + } \ + } + +#else + +#define GDB_DECLARE_GPL_COMPATIBLE_READER \ + extern int plugin_is_GPL_compatible (void); \ + extern int plugin_is_GPL_compatible (void) \ + { \ + return 0; \ + } + +#endif + +/* Represents an address on the target system. */ + +typedef unsigned long GDB_CORE_ADDR; + +/* Return status codes. */ + +enum gdb_status { + GDB_FAIL = 0, + GDB_SUCCESS = 1 +}; + +struct gdb_object; +struct gdb_symtab; +struct gdb_block; +struct gdb_symbol_callbacks; + +/* An array of these are used to represent a map from code addresses to line + numbers in the source file. */ + +struct gdb_line_mapping +{ + int line; + GDB_CORE_ADDR pc; +}; + +/* Create a new GDB code object. Each code object can have one or + more symbol tables, each representing a compiled source file. */ + +typedef struct gdb_object *(gdb_object_open) (struct gdb_symbol_callbacks *cb); + +/* The callback used to create new symbol table. CB is the + gdb_symbol_callbacks which the structure is part of. FILE_NAME is + an (optionally NULL) file name to associate with this new symbol + table. + + Returns a new instance to gdb_symtab that can later be passed to + gdb_block_new, gdb_symtab_add_line_mapping and gdb_symtab_close. */ + +typedef struct gdb_symtab *(gdb_symtab_open) (struct gdb_symbol_callbacks *cb, + struct gdb_object *obj, + const char *file_name); + +/* Creates a new block in a given symbol table. A symbol table is a + forest of blocks, each block representing an code address range and + a corresponding (optionally NULL) NAME. In case the block + corresponds to a function, the NAME passed should be the name of + the function. + + If the new block to be created is a child of (i.e. is nested in) + another block, the parent block can be passed in PARENT. SYMTAB is + the symbol table the new block is to belong in. BEGIN, END is the + code address range the block corresponds to. + + Returns a new instance of gdb_block, which, as of now, has no use. + Note that the gdb_block returned must not be freed by the + caller. */ + +typedef struct gdb_block *(gdb_block_open) (struct gdb_symbol_callbacks *cb, + struct gdb_symtab *symtab, + struct gdb_block *parent, + GDB_CORE_ADDR begin, + GDB_CORE_ADDR end, + const char *name); + +/* Adds a PC to line number mapping for the symbol table SYMTAB. + NLINES is the number of elements in LINES, each element + corresponding to one (PC, line) pair. */ + +typedef void (gdb_symtab_add_line_mapping) (struct gdb_symbol_callbacks *cb, + struct gdb_symtab *symtab, + int nlines, + struct gdb_line_mapping *lines); + +/* Close the symtab SYMTAB. This signals to GDB that no more blocks + will be opened on this symtab. */ + +typedef void (gdb_symtab_close) (struct gdb_symbol_callbacks *cb, + struct gdb_symtab *symtab); + + +/* Closes the gdb_object OBJ and adds the emitted information into + GDB's internal structures. Once this is done, the debug + information will be picked up and used; this will usually be the + last operation in gdb_read_debug_info. */ + +typedef void (gdb_object_close) (struct gdb_symbol_callbacks *cb, + struct gdb_object *obj); + +/* Reads LEN bytes from TARGET_MEM in the target's virtual address + space into GDB_BUF. + + Returns GDB_FAIL on failure, and GDB_SUCCESS on success. */ + +typedef enum gdb_status (gdb_target_read) (GDB_CORE_ADDR target_mem, + void *gdb_buf, int len); + +/* The list of callbacks that are passed to read. These callbacks are + to be used to construct the symbol table. The functions have been + described above. */ + +struct gdb_symbol_callbacks +{ + gdb_object_open *object_open; + gdb_symtab_open *symtab_open; + gdb_block_open *block_open; + gdb_symtab_close *symtab_close; + gdb_object_close *object_close; + + gdb_symtab_add_line_mapping *line_mapping_add; + gdb_target_read *target_read; + + /* For internal use by GDB. */ + void *priv_data; +}; + +/* Forward declaration. */ + +struct gdb_reg_value; + +/* A function of this type is used to free a gdb_reg_value. See the + comment on `free' in struct gdb_reg_value. */ + +typedef void (gdb_reg_value_free) (struct gdb_reg_value *); + +/* Denotes the value of a register. */ + +struct gdb_reg_value +{ + /* The size of the register in bytes. The reader need not set this + field. This will be set for (defined) register values being read + from GDB using reg_get. */ + int size; + + /* Set to non-zero if the value for the register is known. The + registers for which the reader does not call reg_set are also + assumed to be undefined */ + int defined; + + /* Since gdb_reg_value is a variable sized structure, it will + usually be allocated on the heap. This function is expected to + contain the corresponding "free" function. + + When a pointer to gdb_reg_value is being sent from GDB to the + reader (via gdb_unwind_reg_get), the reader is expected to call + this function (with the same gdb_reg_value as argument) once it + is done with the value. + + When the function sends the a gdb_reg_value to GDB (via + gdb_unwind_reg_set), it is expected to set this field to point to + an appropriate cleanup routine (or to NULL if no cleanup is + required). */ + gdb_reg_value_free *free; + + /* The value of the register. */ + unsigned char value[1]; +}; + +/* get_frame_id in gdb_reader_funcs is to return a gdb_frame_id + corresponding to the current frame. The registers corresponding to + the current frame can be read using reg_get. Calling get_frame_id + on a particular frame should return the same gdb_frame_id + throughout its lifetime (i.e. till before it gets unwound). One + way to do this is by having the CODE_ADDRESS point to the + function's first instruction and STACK_ADDRESS point to the value + of the stack pointer when entering the function. */ + +struct gdb_frame_id +{ + GDB_CORE_ADDR code_address; + GDB_CORE_ADDR stack_address; +}; + +/* Forward declaration. */ + +struct gdb_unwind_callbacks; + +/* Returns the value of a particular register in the current frame. + The current frame is the frame that needs to be unwound into the + outer (earlier) frame. + + CB is the struct gdb_unwind_callbacks * the callback belongs to. + REGNUM is the DWARF register number of the register that needs to + be unwound. + + Returns the gdb_reg_value corresponding to the register requested. + In case the value of the register has been optimized away or + otherwise unavailable, the defined flag in the returned + gdb_reg_value will be zero. */ + +typedef struct gdb_reg_value *(gdb_unwind_reg_get) + (struct gdb_unwind_callbacks *cb, int regnum); + +/* Sets the previous value of a particular register. REGNUM is the + (DWARF) register number whose value is to be set. VAL is the value + the register is to be set to. + + VAL is *not* copied, so the memory allocated to it cannot be + reused. Once GDB no longer needs the value, it is deallocated + using the FREE function (see gdb_reg_value). + + A register can also be "set" to an undefined value by setting the + defined in VAL to zero. */ + +typedef void (gdb_unwind_reg_set) (struct gdb_unwind_callbacks *cb, int regnum, + struct gdb_reg_value *val); + +/* This struct is passed to unwind in gdb_reader_funcs, and is to be + used to unwind the current frame (current being the frame whose + registers can be read using reg_get) into the earlier frame. The + functions have been described above. */ + +struct gdb_unwind_callbacks +{ + gdb_unwind_reg_get *reg_get; + gdb_unwind_reg_set *reg_set; + gdb_target_read *target_read; + + /* For internal use by GDB. */ + void *priv_data; +}; + +/* Forward declaration. */ + +struct gdb_reader_funcs; + +/* Parse the debug info off a block of memory, pointed to by MEMORY + (already copied to GDB's address space) and MEMORY_SZ bytes long. + The implementation has to use the functions in CB to actually emit + the parsed data into GDB. SELF is the same structure returned by + gdb_init_reader. + + Return GDB_FAIL on failure and GDB_SUCCESS on success. */ + +typedef enum gdb_status (gdb_read_debug_info) (struct gdb_reader_funcs *self, + struct gdb_symbol_callbacks *cb, + void *memory, long memory_sz); + +/* Unwind the current frame, CB is the set of unwind callbacks that + are to be used to do this. + + Return GDB_FAIL on failure and GDB_SUCCESS on success. */ + +typedef enum gdb_status (gdb_unwind_frame) (struct gdb_reader_funcs *self, + struct gdb_unwind_callbacks *cb); + +/* Return the frame ID corresponding to the current frame, using C to + read the current register values. See the comment on struct + gdb_frame_id. */ + +typedef struct gdb_frame_id (gdb_get_frame_id) (struct gdb_reader_funcs *self, + struct gdb_unwind_callbacks *c); + +/* Called when a reader is being unloaded. This function should also + free SELF, if required. */ + +typedef void (gdb_destroy_reader) (struct gdb_reader_funcs *self); + +/* Called when the reader is loaded. Must either return a properly + populated gdb_reader_funcs or NULL. The memory allocated for the + gdb_reader_funcs is to be managed by the reader itself (i.e. if it + is allocated from the heap, it must also be freed in + gdb_destroy_reader). */ + +extern struct gdb_reader_funcs *gdb_init_reader (void); + +/* Pointer to the functions which implement the reader's + functionality. The individual functions have been documented + above. + + None of the fields are optional. */ + +struct gdb_reader_funcs +{ + /* Must be set to GDB_READER_INTERFACE_VERSION. */ + int reader_version; + + /* For use by the reader. */ + void *priv_data; + + gdb_read_debug_info *read; + gdb_unwind_frame *unwind; + gdb_get_frame_id *get_frame_id; + gdb_destroy_reader *destroy; +}; + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif diff --git a/util/X86MAC64/include/symcat.h b/util/X86MAC64/include/symcat.h new file mode 100644 index 0000000000..b46128796b --- /dev/null +++ b/util/X86MAC64/include/symcat.h @@ -0,0 +1,55 @@ +/* Symbol concatenation utilities. + + Copyright (C) 1998, 2000, 2010 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA. */ + +#ifndef SYM_CAT_H +#define SYM_CAT_H + +#if defined (__STDC__) || defined (ALMOST_STDC) || defined (HAVE_STRINGIZE) +#define CONCAT2(a,b) a##b +#define CONCAT3(a,b,c) a##b##c +#define CONCAT4(a,b,c,d) a##b##c##d +#define CONCAT5(a,b,c,d,e) a##b##c##d##e +#define CONCAT6(a,b,c,d,e,f) a##b##c##d##e##f +#define STRINGX(s) #s +#else +/* Note one should never pass extra whitespace to the CONCATn macros, + e.g. CONCAT2(foo, bar) because traditonal C will keep the space between + the two labels instead of concatenating them. Instead, make sure to + write CONCAT2(foo,bar). */ +#define CONCAT2(a,b) a/**/b +#define CONCAT3(a,b,c) a/**/b/**/c +#define CONCAT4(a,b,c,d) a/**/b/**/c/**/d +#define CONCAT5(a,b,c,d,e) a/**/b/**/c/**/d/**/e +#define CONCAT6(a,b,c,d,e,f) a/**/b/**/c/**/d/**/e/**/f +#define STRINGX(s) "s" +#endif + +#define XCONCAT2(a,b) CONCAT2(a,b) +#define XCONCAT3(a,b,c) CONCAT3(a,b,c) +#define XCONCAT4(a,b,c,d) CONCAT4(a,b,c,d) +#define XCONCAT5(a,b,c,d,e) CONCAT5(a,b,c,d,e) +#define XCONCAT6(a,b,c,d,e,f) CONCAT6(a,b,c,d,e,f) + +/* Note the layer of indirection here is typically used to allow + stringification of the expansion of macros. I.e. "#define foo + bar", "XSTRING(foo)", to yield "bar". Be aware that this only + works for __STDC__, not for traditional C which will still resolve + to "foo". */ +#define XSTRING(s) STRINGX(s) + +#endif /* SYM_CAT_H */ diff --git a/util/X86MAC64/lib/libbfd.a b/util/X86MAC64/lib/libbfd.a new file mode 100644 index 0000000000..b8ec29739b Binary files /dev/null and b/util/X86MAC64/lib/libbfd.a differ diff --git a/util/X86MAC64/lib/libbfd.la b/util/X86MAC64/lib/libbfd.la new file mode 100755 index 0000000000..8119b15a3a --- /dev/null +++ b/util/X86MAC64/lib/libbfd.la @@ -0,0 +1,41 @@ +# libbfd.la - a libtool library file +# Generated by libtool (GNU libtool 1.3134 2009-11-29) 2.2.7a +# +# Please DO NOT delete this file! +# It is necessary for linking the library. + +# The name that we can dlopen(3). +dlname='' + +# Names of this library. +library_names='' + +# The name of the static archive. +old_library='libbfd.a' + +# Linker flags that can not go in dependency_libs. +inherited_linker_flags=' ' + +# Libraries that this one depends upon. +dependency_libs=' -lz' + +# Names of additional weak libraries provided by this library +weak_library_names='' + +# Version information for libbfd. +current=0 +age=0 +revision=0 + +# Is this an already installed library? +installed=yes + +# Should we warn about portability when linking against -modules? +shouldnotlink=no + +# Files to dlopen/dlpreopen +dlopen='' +dlpreopen='' + +# Directory that this library needs to be installed in: +libdir='/Users/tacyas/Eos/util/X86MAC64/lib' diff --git a/util/X86MAC64/lib/libopcodes.a b/util/X86MAC64/lib/libopcodes.a new file mode 100644 index 0000000000..2f97dbe20c Binary files /dev/null and b/util/X86MAC64/lib/libopcodes.a differ diff --git a/util/X86MAC64/lib/libopcodes.la b/util/X86MAC64/lib/libopcodes.la new file mode 100755 index 0000000000..0fb321a7d0 --- /dev/null +++ b/util/X86MAC64/lib/libopcodes.la @@ -0,0 +1,41 @@ +# libopcodes.la - a libtool library file +# Generated by libtool (GNU libtool 1.3134 2009-11-29) 2.2.7a +# +# Please DO NOT delete this file! +# It is necessary for linking the library. + +# The name that we can dlopen(3). +dlname='' + +# Names of this library. +library_names='' + +# The name of the static archive. +old_library='libopcodes.a' + +# Linker flags that can not go in dependency_libs. +inherited_linker_flags=' ' + +# Libraries that this one depends upon. +dependency_libs='' + +# Names of additional weak libraries provided by this library +weak_library_names='' + +# Version information for libopcodes. +current=0 +age=0 +revision=0 + +# Is this an already installed library? +installed=yes + +# Should we warn about portability when linking against -modules? +shouldnotlink=no + +# Files to dlopen/dlpreopen +dlopen='' +dlpreopen='' + +# Directory that this library needs to be installed in: +libdir='/Users/tacyas/Eos/util/X86MAC64/lib' diff --git a/util/X86MAC64/share/gdb/python/gdb/FrameDecorator.py b/util/X86MAC64/share/gdb/python/gdb/FrameDecorator.py new file mode 100644 index 0000000000..1bbc5ab1ce --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/FrameDecorator.py @@ -0,0 +1,302 @@ +# Copyright (C) 2013-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +import gdb + +# This small code snippet deals with problem of strings in Python 2.x +# and Python 3.x. Python 2.x has str and unicode classes which are +# sub-classes of basestring. In Python 3.x all strings are encoded +# and basestring has been removed. +try: + basestring +except NameError: + basestring = str + +class FrameDecorator(object): + """Basic implementation of a Frame Decorator""" + + """ This base frame decorator decorates a frame or another frame + decorator, and provides convenience methods. If this object is + wrapping a frame decorator, defer to that wrapped object's method + if it has one. This allows for frame decorators that have + sub-classed FrameDecorator object, but also wrap other frame + decorators on the same frame to correctly execute. + + E.g + + If the result of frame filters running means we have one gdb.Frame + wrapped by multiple frame decorators, all sub-classed from + FrameDecorator, the resulting hierarchy will be: + + Decorator1 + -- (wraps) Decorator2 + -- (wraps) FrameDecorator + -- (wraps) gdb.Frame + + In this case we have two frame decorators, both of which are + sub-classed from FrameDecorator. If Decorator1 just overrides the + 'function' method, then all of the other methods are carried out + by the super-class FrameDecorator. But Decorator2 may have + overriden other methods, so FrameDecorator will look at the + 'base' parameter and defer to that class's methods. And so on, + down the chain.""" + + # 'base' can refer to a gdb.Frame or another frame decorator. In + # the latter case, the child class will have called the super + # method and _base will be an object conforming to the Frame Filter + # class. + def __init__(self, base): + self._base = base + + @staticmethod + def _is_limited_frame(frame): + """Internal utility to determine if the frame is special or + limited.""" + sal = frame.find_sal() + + if (not sal.symtab or not sal.symtab.filename + or frame.type() == gdb.DUMMY_FRAME + or frame.type() == gdb.SIGTRAMP_FRAME): + + return True + + return False + + def elided(self): + """Return any elided frames that this class might be + wrapping, or None.""" + if hasattr(self._base, "elided"): + return self._base.elided() + + return None + + def function(self): + """ Return the name of the frame's function or an address of + the function of the frame. First determine if this is a + special frame. If not, try to determine filename from GDB's + frame internal function API. Finally, if a name cannot be + determined return the address. If this function returns an + address, GDB will attempt to determine the function name from + its internal minimal symbols store (for example, for inferiors + without debug-info).""" + + # Both gdb.Frame, and FrameDecorator have a method called + # "function", so determine which object this is. + if not isinstance(self._base, gdb.Frame): + if hasattr(self._base, "function"): + # If it is not a gdb.Frame, and there is already a + # "function" method, use that. + return self._base.function() + + frame = self.inferior_frame() + + if frame.type() == gdb.DUMMY_FRAME: + return "" + elif frame.type() == gdb.SIGTRAMP_FRAME: + return "" + + func = frame.function() + + # If we cannot determine the function name, return the + # address. If GDB detects an integer value from this function + # it will attempt to find the function name from minimal + # symbols via its own internal functions. + if func == None: + pc = frame.pc() + return pc + + return str(func) + + def address(self): + """ Return the address of the frame's pc""" + + if hasattr(self._base, "address"): + return self._base.address() + + frame = self.inferior_frame() + return frame.pc() + + def filename(self): + """ Return the filename associated with this frame, detecting + and returning the appropriate library name is this is a shared + library.""" + + if hasattr(self._base, "filename"): + return self._base.filename() + + frame = self.inferior_frame() + sal = frame.find_sal() + if not sal.symtab or not sal.symtab.filename: + pc = frame.pc() + return gdb.solib_name(pc) + else: + return sal.symtab.filename + + def frame_args(self): + """ Return an iterable of frame arguments for this frame, if + any. The iterable object contains objects conforming with the + Symbol/Value interface. If there are no frame arguments, or + if this frame is deemed to be a special case, return None.""" + + if hasattr(self._base, "frame_args"): + return self._base.frame_args() + + frame = self.inferior_frame() + if self._is_limited_frame(frame): + return None + + args = FrameVars(frame) + return args.fetch_frame_args() + + def frame_locals(self): + """ Return an iterable of local variables for this frame, if + any. The iterable object contains objects conforming with the + Symbol/Value interface. If there are no frame locals, or if + this frame is deemed to be a special case, return None.""" + + if hasattr(self._base, "frame_locals"): + return self._base.frame_locals() + + frame = self.inferior_frame() + if self._is_limited_frame(frame): + return None + + args = FrameVars(frame) + return args.fetch_frame_locals() + + def line(self): + """ Return line number information associated with the frame's + pc. If symbol table/line information does not exist, or if + this frame is deemed to be a special case, return None""" + + if hasattr(self._base, "line"): + return self._base.line() + + frame = self.inferior_frame() + if self._is_limited_frame(frame): + return None + + sal = frame.find_sal() + if (sal): + return sal.line + else: + return None + + def inferior_frame(self): + """ Return the gdb.Frame underpinning this frame decorator.""" + + # If 'base' is a frame decorator, we want to call its inferior + # frame method. If '_base' is a gdb.Frame, just return that. + if hasattr(self._base, "inferior_frame"): + return self._base.inferior_frame() + return self._base + +class SymValueWrapper(object): + """A container class conforming to the Symbol/Value interface + which holds frame locals or frame arguments.""" + def __init__(self, symbol, value): + self.sym = symbol + self.val = value + + def value(self): + """ Return the value associated with this symbol, or None""" + return self.val + + def symbol(self): + """ Return the symbol, or Python text, associated with this + symbol, or None""" + return self.sym + +class FrameVars(object): + + """Utility class to fetch and store frame local variables, or + frame arguments.""" + + def __init__(self, frame): + self.frame = frame + self.symbol_class = { + gdb.SYMBOL_LOC_STATIC: True, + gdb.SYMBOL_LOC_REGISTER: True, + gdb.SYMBOL_LOC_ARG: True, + gdb.SYMBOL_LOC_REF_ARG: True, + gdb.SYMBOL_LOC_LOCAL: True, + gdb.SYMBOL_LOC_REGPARM_ADDR: True, + gdb.SYMBOL_LOC_COMPUTED: True + } + + def fetch_b(self, sym): + """ Local utility method to determine if according to Symbol + type whether it should be included in the iterator. Not all + symbols are fetched, and only symbols that return + True from this method should be fetched.""" + + # SYM may be a string instead of a symbol in the case of + # synthetic local arguments or locals. If that is the case, + # always fetch. + if isinstance(sym, basestring): + return True + + sym_type = sym.addr_class + + return self.symbol_class.get(sym_type, False) + + def fetch_frame_locals(self): + """Public utility method to fetch frame local variables for + the stored frame. Frame arguments are not fetched. If there + are no frame local variables, return an empty list.""" + lvars = [] + + try: + block = self.frame.block() + except RuntimeError: + block = None + + while block != None: + if block.is_global or block.is_static: + break + for sym in block: + if sym.is_argument: + continue; + if self.fetch_b(sym): + lvars.append(SymValueWrapper(sym, None)) + + block = block.superblock + + return lvars + + def fetch_frame_args(self): + """Public utility method to fetch frame arguments for the + stored frame. Frame arguments are the only type fetched. If + there are no frame argument variables, return an empty list.""" + + args = [] + + try: + block = self.frame.block() + except RuntimeError: + block = None + + while block != None: + if block.function != None: + break + block = block.superblock + + if block != None: + for sym in block: + if not sym.is_argument: + continue; + args.append(SymValueWrapper(sym, None)) + + return args diff --git a/util/X86MAC64/share/gdb/python/gdb/FrameDecorator.pyc b/util/X86MAC64/share/gdb/python/gdb/FrameDecorator.pyc new file mode 100644 index 0000000000..217ea835cf Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/FrameDecorator.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/FrameIterator.py b/util/X86MAC64/share/gdb/python/gdb/FrameIterator.py new file mode 100644 index 0000000000..c99a91e556 --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/FrameIterator.py @@ -0,0 +1,51 @@ +# Copyright (C) 2013-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +import gdb +import itertools + +class FrameIterator(object): + """A gdb.Frame iterator. Iterates over gdb.Frames or objects that + conform to that interface.""" + + def __init__(self, frame_obj): + """Initialize a FrameIterator. + + Arguments: + frame_obj the starting frame.""" + + super(FrameIterator, self).__init__() + self.frame = frame_obj + + def __iter__(self): + return self + + def next(self): + """next implementation. + + Returns: + The next oldest frame.""" + + result = self.frame + if result is None: + raise StopIteration + self.frame = result.older() + return result + + # Python 3.x requires __next__(self) while Python 2.x requires + # next(self). Define next(self), and for Python 3.x create this + # wrapper. + def __next__(self): + return self.next() diff --git a/util/X86MAC64/share/gdb/python/gdb/FrameIterator.pyc b/util/X86MAC64/share/gdb/python/gdb/FrameIterator.pyc new file mode 100644 index 0000000000..846b1df9f4 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/FrameIterator.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/__init__.py b/util/X86MAC64/share/gdb/python/gdb/__init__.py new file mode 100644 index 0000000000..95a76c25df --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/__init__.py @@ -0,0 +1,126 @@ +# Copyright (C) 2010-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +import traceback +import os +import sys +import _gdb + +if sys.version_info[0] > 2: + # Python 3 moved "reload" + from imp import reload + +from _gdb import * + +class _GdbFile (object): + # These two are needed in Python 3 + encoding = "UTF-8" + errors = "strict" + + def close(self): + # Do nothing. + return None + + def isatty(self): + return False + + def writelines(self, iterable): + for line in iterable: + self.write(line) + + def flush(self): + flush() + +class GdbOutputFile (_GdbFile): + def write(self, s): + write(s, stream=STDOUT) + +sys.stdout = GdbOutputFile() + +class GdbOutputErrorFile (_GdbFile): + def write(self, s): + write(s, stream=STDERR) + +sys.stderr = GdbOutputErrorFile() + +# Default prompt hook does nothing. +prompt_hook = None + +# Ensure that sys.argv is set to something. +# We do not use PySys_SetArgvEx because it did not appear until 2.6.6. +sys.argv = [''] + +# Initial pretty printers. +pretty_printers = [] + +# Initial type printers. +type_printers = [] +# Initial frame filters. +frame_filters = {} + +# Convenience variable to GDB's python directory +PYTHONDIR = os.path.dirname(os.path.dirname(__file__)) + +# Auto-load all functions/commands. + +# Packages to auto-load. + +packages = [ + 'function', + 'command' +] + +# pkgutil.iter_modules is not available prior to Python 2.6. Instead, +# manually iterate the list, collating the Python files in each module +# path. Construct the module name, and import. + +def auto_load_packages(): + for package in packages: + location = os.path.join(os.path.dirname(__file__), package) + if os.path.exists(location): + py_files = filter(lambda x: x.endswith('.py') + and x != '__init__.py', + os.listdir(location)) + + for py_file in py_files: + # Construct from foo.py, gdb.module.foo + modname = "%s.%s.%s" % ( __name__, package, py_file[:-3] ) + try: + if modname in sys.modules: + # reload modules with duplicate names + reload(__import__(modname)) + else: + __import__(modname) + except: + sys.stderr.write (traceback.format_exc() + "\n") + +auto_load_packages() + +def GdbSetPythonDirectory(dir): + """Update sys.path, reload gdb and auto-load packages.""" + global PYTHONDIR + + try: + sys.path.remove(PYTHONDIR) + except ValueError: + pass + sys.path.insert(0, dir) + + PYTHONDIR = dir + + # note that reload overwrites the gdb module without deleting existing + # attributes + reload(__import__(__name__)) + auto_load_packages() diff --git a/util/X86MAC64/share/gdb/python/gdb/__init__.pyc b/util/X86MAC64/share/gdb/python/gdb/__init__.pyc new file mode 100644 index 0000000000..089359d71a Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/__init__.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/command/__init__.py b/util/X86MAC64/share/gdb/python/gdb/command/__init__.py new file mode 100644 index 0000000000..ca768c892d --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/command/__init__.py @@ -0,0 +1,16 @@ +# Copyright (C) 2010-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + + diff --git a/util/X86MAC64/share/gdb/python/gdb/command/__init__.pyc b/util/X86MAC64/share/gdb/python/gdb/command/__init__.pyc new file mode 100644 index 0000000000..8374fc9651 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/command/__init__.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/command/bound_registers.py b/util/X86MAC64/share/gdb/python/gdb/command/bound_registers.py new file mode 100644 index 0000000000..24d4c45a17 --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/command/bound_registers.py @@ -0,0 +1,45 @@ +# Pretty-printer utilities. +# Copyright (C) 2013-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +import gdb.printing + +class BoundPrinter: + """Adds size field to a _rawbound128 type.""" + + def __init__ (self, val): + self.val = val + + def to_string (self): + upper = self.val["ubound"] + lower = self.val["lbound"] + size = (long) ((upper) - (lower)) + if size > -1: + size = size + 1 + result = '{lbound = %s, ubound = %s} : size %s' % (lower, upper, size) + return result + +# There are two pattern matching used: first one is related to a library +# second is related to the type. Since we are displaying a register all +# libraries are accepted. Type to be processed is the same present +# in the xml file. + +def build_pretty_printer (): + pp = gdb.printing.RegexpCollectionPrettyPrinter (".*") + pp.add_printer ('bound', '^__gdb_builtin_type_bound128', BoundPrinter) + return pp + +gdb.printing.register_pretty_printer (gdb.current_objfile (), + build_pretty_printer ()) diff --git a/util/X86MAC64/share/gdb/python/gdb/command/bound_registers.pyc b/util/X86MAC64/share/gdb/python/gdb/command/bound_registers.pyc new file mode 100644 index 0000000000..cfd1f72657 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/command/bound_registers.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/command/explore.py b/util/X86MAC64/share/gdb/python/gdb/command/explore.py new file mode 100644 index 0000000000..fd79de3a0d --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/command/explore.py @@ -0,0 +1,760 @@ +# GDB 'explore' command. +# Copyright (C) 2012-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +"""Implementation of the GDB 'explore' command using the GDB Python API.""" + +import gdb +import sys + +if sys.version_info[0] > 2: + # Python 3 renamed raw_input to input + raw_input = input + +class Explorer(object): + """Internal class which invokes other explorers.""" + + # This map is filled by the Explorer.init_env() function + type_code_to_explorer_map = { } + + _SCALAR_TYPE_LIST = ( + gdb.TYPE_CODE_CHAR, + gdb.TYPE_CODE_INT, + gdb.TYPE_CODE_BOOL, + gdb.TYPE_CODE_FLT, + gdb.TYPE_CODE_VOID, + gdb.TYPE_CODE_ENUM, + ) + + @staticmethod + def guard_expr(expr): + length = len(expr) + guard = False + + if expr[0] == '(' and expr[length-1] == ')': + pass + else: + i = 0 + while i < length: + c = expr[i] + if (c == '_' or ('a' <= c and c <= 'z') or + ('A' <= c and c <= 'Z') or ('0' <= c and c <= '9')): + pass + else: + guard = True + break + i += 1 + + if guard: + return "(" + expr + ")" + else: + return expr + + @staticmethod + def explore_expr(expr, value, is_child): + """Main function to explore an expression value. + + Arguments: + expr: The expression string that is being explored. + value: The gdb.Value value of the expression. + is_child: Boolean value to indicate if the expression is a child. + An expression is a child if it is derived from the main + expression entered by the user. For example, if the user + entered an expression which evaluates to a struct, then + when exploring the fields of the struct, is_child is set + to True internally. + + Returns: + No return value. + """ + type_code = value.type.code + if type_code in Explorer.type_code_to_explorer_map: + explorer_class = Explorer.type_code_to_explorer_map[type_code] + while explorer_class.explore_expr(expr, value, is_child): + pass + else: + print ("Explorer for type '%s' not yet available.\n" % + str(value.type)) + + @staticmethod + def explore_type(name, datatype, is_child): + """Main function to explore a data type. + + Arguments: + name: The string representing the path to the data type being + explored. + datatype: The gdb.Type value of the data type being explored. + is_child: Boolean value to indicate if the name is a child. + A name is a child if it is derived from the main name + entered by the user. For example, if the user entered + the name of struct type, then when exploring the fields + of the struct, is_child is set to True internally. + + Returns: + No return value. + """ + type_code = datatype.code + if type_code in Explorer.type_code_to_explorer_map: + explorer_class = Explorer.type_code_to_explorer_map[type_code] + while explorer_class.explore_type(name, datatype, is_child): + pass + else: + print ("Explorer for type '%s' not yet available.\n" % + str(datatype)) + + @staticmethod + def init_env(): + """Initializes the Explorer environment. + This function should be invoked before starting any exploration. If + invoked before an exploration, it need not be invoked for subsequent + explorations. + """ + Explorer.type_code_to_explorer_map = { + gdb.TYPE_CODE_CHAR : ScalarExplorer, + gdb.TYPE_CODE_INT : ScalarExplorer, + gdb.TYPE_CODE_BOOL : ScalarExplorer, + gdb.TYPE_CODE_FLT : ScalarExplorer, + gdb.TYPE_CODE_VOID : ScalarExplorer, + gdb.TYPE_CODE_ENUM : ScalarExplorer, + gdb.TYPE_CODE_STRUCT : CompoundExplorer, + gdb.TYPE_CODE_UNION : CompoundExplorer, + gdb.TYPE_CODE_PTR : PointerExplorer, + gdb.TYPE_CODE_REF : ReferenceExplorer, + gdb.TYPE_CODE_TYPEDEF : TypedefExplorer, + gdb.TYPE_CODE_ARRAY : ArrayExplorer + } + + @staticmethod + def is_scalar_type(type): + """Checks whether a type is a scalar type. + A type is a scalar type of its type is + gdb.TYPE_CODE_CHAR or + gdb.TYPE_CODE_INT or + gdb.TYPE_CODE_BOOL or + gdb.TYPE_CODE_FLT or + gdb.TYPE_CODE_VOID or + gdb.TYPE_CODE_ENUM. + + Arguments: + type: The type to be checked. + + Returns: + 'True' if 'type' is a scalar type. 'False' otherwise. + """ + return type.code in Explorer._SCALAR_TYPE_LIST + + @staticmethod + def return_to_parent_value(): + """A utility function which prints that the current exploration session + is returning to the parent value. Useful when exploring values. + """ + print ("\nReturning to parent value...\n") + + @staticmethod + def return_to_parent_value_prompt(): + """A utility function which prompts the user to press the 'enter' key + so that the exploration session can shift back to the parent value. + Useful when exploring values. + """ + raw_input("\nPress enter to return to parent value: ") + + @staticmethod + def return_to_enclosing_type(): + """A utility function which prints that the current exploration session + is returning to the enclosing type. Useful when exploring types. + """ + print ("\nReturning to enclosing type...\n") + + @staticmethod + def return_to_enclosing_type_prompt(): + """A utility function which prompts the user to press the 'enter' key + so that the exploration session can shift back to the enclosing type. + Useful when exploring types. + """ + raw_input("\nPress enter to return to enclosing type: ") + + +class ScalarExplorer(object): + """Internal class used to explore scalar values.""" + + @staticmethod + def explore_expr(expr, value, is_child): + """Function to explore scalar values. + See Explorer.explore_expr and Explorer.is_scalar_type for more + information. + """ + print ("'%s' is a scalar value of type '%s'." % + (expr, value.type)) + print ("%s = %s" % (expr, str(value))) + + if is_child: + Explorer.return_to_parent_value_prompt() + Explorer.return_to_parent_value() + + return False + + @staticmethod + def explore_type(name, datatype, is_child): + """Function to explore scalar types. + See Explorer.explore_type and Explorer.is_scalar_type for more + information. + """ + if datatype.code == gdb.TYPE_CODE_ENUM: + if is_child: + print ("%s is of an enumerated type '%s'." % + (name, str(datatype))) + else: + print ("'%s' is an enumerated type." % name) + else: + if is_child: + print ("%s is of a scalar type '%s'." % + (name, str(datatype))) + else: + print ("'%s' is a scalar type." % name) + + if is_child: + Explorer.return_to_enclosing_type_prompt() + Explorer.return_to_enclosing_type() + + return False + + +class PointerExplorer(object): + """Internal class used to explore pointer values.""" + + @staticmethod + def explore_expr(expr, value, is_child): + """Function to explore pointer values. + See Explorer.explore_expr for more information. + """ + print ("'%s' is a pointer to a value of type '%s'" % + (expr, str(value.type.target()))) + option = raw_input("Continue exploring it as a pointer to a single " + "value [y/n]: ") + if option == "y": + deref_value = None + try: + deref_value = value.dereference() + str(deref_value) + except gdb.MemoryError: + print ("'%s' a pointer pointing to an invalid memory " + "location." % expr) + if is_child: + Explorer.return_to_parent_value_prompt() + return False + Explorer.explore_expr("*%s" % Explorer.guard_expr(expr), + deref_value, is_child) + return False + + option = raw_input("Continue exploring it as a pointer to an " + "array [y/n]: ") + if option == "y": + while True: + index = 0 + try: + index = int(raw_input("Enter the index of the element you " + "want to explore in '%s': " % expr)) + except ValueError: + break + element_expr = "%s[%d]" % (Explorer.guard_expr(expr), index) + element = value[index] + try: + str(element) + except gdb.MemoryError: + print ("Cannot read value at index %d." % index) + continue + Explorer.explore_expr(element_expr, element, True) + return False + + if is_child: + Explorer.return_to_parent_value() + return False + + @staticmethod + def explore_type(name, datatype, is_child): + """Function to explore pointer types. + See Explorer.explore_type for more information. + """ + target_type = datatype.target() + print ("\n%s is a pointer to a value of type '%s'." % + (name, str(target_type))) + + Explorer.explore_type("the pointee type of %s" % name, + target_type, + is_child) + return False + + +class ReferenceExplorer(object): + """Internal class used to explore reference (TYPE_CODE_REF) values.""" + + @staticmethod + def explore_expr(expr, value, is_child): + """Function to explore array values. + See Explorer.explore_expr for more information. + """ + referenced_value = value.referenced_value() + Explorer.explore_expr(expr, referenced_value, is_child) + return False + + @staticmethod + def explore_type(name, datatype, is_child): + """Function to explore pointer types. + See Explorer.explore_type for more information. + """ + target_type = datatype.target() + Explorer.explore_type(name, target_type, is_child) + return False + + +class ArrayExplorer(object): + """Internal class used to explore arrays.""" + + @staticmethod + def explore_expr(expr, value, is_child): + """Function to explore array values. + See Explorer.explore_expr for more information. + """ + target_type = value.type.target() + print ("'%s' is an array of '%s'." % (expr, str(target_type))) + index = 0 + try: + index = int(raw_input("Enter the index of the element you want to " + "explore in '%s': " % expr)) + except ValueError: + if is_child: + Explorer.return_to_parent_value() + return False + + element = None + try: + element = value[index] + str(element) + except gdb.MemoryError: + print ("Cannot read value at index %d." % index) + raw_input("Press enter to continue... ") + return True + + Explorer.explore_expr("%s[%d]" % (Explorer.guard_expr(expr), index), + element, True) + return True + + @staticmethod + def explore_type(name, datatype, is_child): + """Function to explore array types. + See Explorer.explore_type for more information. + """ + target_type = datatype.target() + print ("%s is an array of '%s'." % (name, str(target_type))) + + Explorer.explore_type("the array element of %s" % name, target_type, + is_child) + return False + + +class CompoundExplorer(object): + """Internal class used to explore struct, classes and unions.""" + + @staticmethod + def _print_fields(print_list): + """Internal function which prints the fields of a struct/class/union. + """ + max_field_name_length = 0 + for pair in print_list: + if max_field_name_length < len(pair[0]): + max_field_name_length = len(pair[0]) + + for pair in print_list: + print (" %*s = %s" % (max_field_name_length, pair[0], pair[1])) + + @staticmethod + def _get_real_field_count(fields): + real_field_count = 0; + for field in fields: + if not field.artificial: + real_field_count = real_field_count + 1 + + return real_field_count + + @staticmethod + def explore_expr(expr, value, is_child): + """Function to explore structs/classes and union values. + See Explorer.explore_expr for more information. + """ + datatype = value.type + type_code = datatype.code + fields = datatype.fields() + + if type_code == gdb.TYPE_CODE_STRUCT: + type_desc = "struct/class" + else: + type_desc = "union" + + if CompoundExplorer._get_real_field_count(fields) == 0: + print ("The value of '%s' is a %s of type '%s' with no fields." % + (expr, type_desc, str(value.type))) + if is_child: + Explorer.return_to_parent_value_prompt() + return False + + print ("The value of '%s' is a %s of type '%s' with the following " + "fields:\n" % (expr, type_desc, str(value.type))) + + has_explorable_fields = False + choice_to_compound_field_map = { } + current_choice = 0 + print_list = [ ] + for field in fields: + if field.artificial: + continue + field_full_name = Explorer.guard_expr(expr) + "." + field.name + if field.is_base_class: + field_value = value.cast(field.type) + else: + field_value = value[field.name] + literal_value = "" + if type_code == gdb.TYPE_CODE_UNION: + literal_value = ("" % (current_choice, str(field.type))) + has_explorable_fields = True + else: + if Explorer.is_scalar_type(field.type): + literal_value = ("%s .. (Value of type '%s')" % + (str(field_value), str(field.type))) + else: + if field.is_base_class: + field_desc = "base class" + else: + field_desc = "field" + literal_value = ("" % + (current_choice, field_desc, + str(field.type))) + has_explorable_fields = True + + choice_to_compound_field_map[str(current_choice)] = ( + field_full_name, field_value) + current_choice = current_choice + 1 + + print_list.append((field.name, literal_value)) + + CompoundExplorer._print_fields(print_list) + print ("") + + if has_explorable_fields: + choice = raw_input("Enter the field number of choice: ") + if choice in choice_to_compound_field_map: + Explorer.explore_expr(choice_to_compound_field_map[choice][0], + choice_to_compound_field_map[choice][1], + True) + return True + else: + if is_child: + Explorer.return_to_parent_value() + else: + if is_child: + Explorer.return_to_parent_value_prompt() + + return False + + @staticmethod + def explore_type(name, datatype, is_child): + """Function to explore struct/class and union types. + See Explorer.explore_type for more information. + """ + type_code = datatype.code + type_desc = "" + if type_code == gdb.TYPE_CODE_STRUCT: + type_desc = "struct/class" + else: + type_desc = "union" + + fields = datatype.fields() + if CompoundExplorer._get_real_field_count(fields) == 0: + if is_child: + print ("%s is a %s of type '%s' with no fields." % + (name, type_desc, str(datatype))) + Explorer.return_to_enclosing_type_prompt() + else: + print ("'%s' is a %s with no fields." % (name, type_desc)) + return False + + if is_child: + print ("%s is a %s of type '%s' " + "with the following fields:\n" % + (name, type_desc, str(datatype))) + else: + print ("'%s' is a %s with the following " + "fields:\n" % + (name, type_desc)) + + has_explorable_fields = False + current_choice = 0 + choice_to_compound_field_map = { } + print_list = [ ] + for field in fields: + if field.artificial: + continue + if field.is_base_class: + field_desc = "base class" + else: + field_desc = "field" + rhs = ("" % + (current_choice, field_desc, str(field.type))) + print_list.append((field.name, rhs)) + choice_to_compound_field_map[str(current_choice)] = ( + field.name, field.type, field_desc) + current_choice = current_choice + 1 + + CompoundExplorer._print_fields(print_list) + print ("") + + if len(choice_to_compound_field_map) > 0: + choice = raw_input("Enter the field number of choice: ") + if choice in choice_to_compound_field_map: + if is_child: + new_name = ("%s '%s' of %s" % + (choice_to_compound_field_map[choice][2], + choice_to_compound_field_map[choice][0], + name)) + else: + new_name = ("%s '%s' of '%s'" % + (choice_to_compound_field_map[choice][2], + choice_to_compound_field_map[choice][0], + name)) + Explorer.explore_type(new_name, + choice_to_compound_field_map[choice][1], True) + return True + else: + if is_child: + Explorer.return_to_enclosing_type() + else: + if is_child: + Explorer.return_to_enclosing_type_prompt() + + return False + + +class TypedefExplorer(object): + """Internal class used to explore values whose type is a typedef.""" + + @staticmethod + def explore_expr(expr, value, is_child): + """Function to explore typedef values. + See Explorer.explore_expr for more information. + """ + actual_type = value.type.strip_typedefs() + print ("The value of '%s' is of type '%s' " + "which is a typedef of type '%s'" % + (expr, str(value.type), str(actual_type))) + + Explorer.explore_expr(expr, value.cast(actual_type), is_child) + return False + + @staticmethod + def explore_type(name, datatype, is_child): + """Function to explore typedef types. + See Explorer.explore_type for more information. + """ + actual_type = datatype.strip_typedefs() + if is_child: + print ("The type of %s is a typedef of type '%s'." % + (name, str(actual_type))) + else: + print ("The type '%s' is a typedef of type '%s'." % + (name, str(actual_type))) + + Explorer.explore_type(name, actual_type, is_child) + return False + + +class ExploreUtils(object): + """Internal class which provides utilities for the main command classes.""" + + @staticmethod + def check_args(name, arg_str): + """Utility to check if adequate number of arguments are passed to an + explore command. + + Arguments: + name: The name of the explore command. + arg_str: The argument string passed to the explore command. + + Returns: + True if adequate arguments are passed, false otherwise. + + Raises: + gdb.GdbError if adequate arguments are not passed. + """ + if len(arg_str) < 1: + raise gdb.GdbError("ERROR: '%s' requires an argument." + % name) + return False + else: + return True + + @staticmethod + def get_type_from_str(type_str): + """A utility function to deduce the gdb.Type value from a string + representing the type. + + Arguments: + type_str: The type string from which the gdb.Type value should be + deduced. + + Returns: + The deduced gdb.Type value if possible, None otherwise. + """ + try: + # Assume the current language to be C/C++ and make a try. + return gdb.parse_and_eval("(%s *)0" % type_str).type.target() + except RuntimeError: + # If assumption of current language to be C/C++ was wrong, then + # lookup the type using the API. + try: + return gdb.lookup_type(type_str) + except RuntimeError: + return None + + @staticmethod + def get_value_from_str(value_str): + """A utility function to deduce the gdb.Value value from a string + representing the value. + + Arguments: + value_str: The value string from which the gdb.Value value should + be deduced. + + Returns: + The deduced gdb.Value value if possible, None otherwise. + """ + try: + return gdb.parse_and_eval(value_str) + except RuntimeError: + return None + + +class ExploreCommand(gdb.Command): + """Explore a value or a type valid in the current context. + + Usage: + + explore ARG + + - ARG is either a valid expression or a type name. + - At any stage of exploration, hit the return key (instead of a + choice, if any) to return to the enclosing type or value. + """ + + def __init__(self): + super(ExploreCommand, self).__init__(name = "explore", + command_class = gdb.COMMAND_DATA, + prefix = True) + + def invoke(self, arg_str, from_tty): + if ExploreUtils.check_args("explore", arg_str) == False: + return + + # Check if it is a value + value = ExploreUtils.get_value_from_str(arg_str) + if value is not None: + Explorer.explore_expr(arg_str, value, False) + return + + # If it is not a value, check if it is a type + datatype = ExploreUtils.get_type_from_str(arg_str) + if datatype is not None: + Explorer.explore_type(arg_str, datatype, False) + return + + # If it is neither a value nor a type, raise an error. + raise gdb.GdbError( + ("'%s' neither evaluates to a value nor is a type " + "in the current context." % + arg_str)) + + +class ExploreValueCommand(gdb.Command): + """Explore value of an expression valid in the current context. + + Usage: + + explore value ARG + + - ARG is a valid expression. + - At any stage of exploration, hit the return key (instead of a + choice, if any) to return to the enclosing value. + """ + + def __init__(self): + super(ExploreValueCommand, self).__init__( + name = "explore value", command_class = gdb.COMMAND_DATA) + + def invoke(self, arg_str, from_tty): + if ExploreUtils.check_args("explore value", arg_str) == False: + return + + value = ExploreUtils.get_value_from_str(arg_str) + if value is None: + raise gdb.GdbError( + (" '%s' does not evaluate to a value in the current " + "context." % + arg_str)) + return + + Explorer.explore_expr(arg_str, value, False) + + +class ExploreTypeCommand(gdb.Command): + """Explore a type or the type of an expression valid in the current + context. + + Usage: + + explore type ARG + + - ARG is a valid expression or a type name. + - At any stage of exploration, hit the return key (instead of a + choice, if any) to return to the enclosing type. + """ + + def __init__(self): + super(ExploreTypeCommand, self).__init__( + name = "explore type", command_class = gdb.COMMAND_DATA) + + def invoke(self, arg_str, from_tty): + if ExploreUtils.check_args("explore type", arg_str) == False: + return + + datatype = ExploreUtils.get_type_from_str(arg_str) + if datatype is not None: + Explorer.explore_type(arg_str, datatype, False) + return + + value = ExploreUtils.get_value_from_str(arg_str) + if value is not None: + print ("'%s' is of type '%s'." % (arg_str, str(value.type))) + Explorer.explore_type(str(value.type), value.type, False) + return + + raise gdb.GdbError(("'%s' is not a type or value in the current " + "context." % arg_str)) + + +Explorer.init_env() + +ExploreCommand() +ExploreValueCommand() +ExploreTypeCommand() diff --git a/util/X86MAC64/share/gdb/python/gdb/command/explore.pyc b/util/X86MAC64/share/gdb/python/gdb/command/explore.pyc new file mode 100644 index 0000000000..84d7e71057 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/command/explore.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/command/frame_filters.py b/util/X86MAC64/share/gdb/python/gdb/command/frame_filters.py new file mode 100644 index 0000000000..450c5bf6d5 --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/command/frame_filters.py @@ -0,0 +1,467 @@ +# Frame-filter commands. +# Copyright (C) 2013-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +"""GDB commands for working with frame-filters.""" + +import sys +import gdb +import copy +from gdb.FrameIterator import FrameIterator +from gdb.FrameDecorator import FrameDecorator +import gdb.frames +import itertools + +# GDB Commands. +class SetFilterPrefixCmd(gdb.Command): + """Prefix command for 'set' frame-filter related operations.""" + + def __init__(self): + super(SetFilterPrefixCmd, self).__init__("set frame-filter", + gdb.COMMAND_OBSCURE, + gdb.COMPLETE_NONE, True) + +class ShowFilterPrefixCmd(gdb.Command): + """Prefix command for 'show' frame-filter related operations.""" + def __init__(self): + super(ShowFilterPrefixCmd, self).__init__("show frame-filter", + gdb.COMMAND_OBSCURE, + gdb.COMPLETE_NONE, True) +class InfoFrameFilter(gdb.Command): + """List all registered Python frame-filters. + + Usage: info frame-filters + """ + + def __init__(self): + super(InfoFrameFilter, self).__init__("info frame-filter", + gdb.COMMAND_DATA) + @staticmethod + def enabled_string(state): + """Return "Yes" if filter is enabled, otherwise "No".""" + if state: + return "Yes" + else: + return "No" + + def list_frame_filters(self, frame_filters): + """ Internal worker function to list and print frame filters + in a dictionary. + + Arguments: + frame_filters: The name of the dictionary, as + specified by GDB user commands. + """ + + sorted_frame_filters = sorted(frame_filters.items(), + key=lambda i: gdb.frames.get_priority(i[1]), + reverse=True) + + if len(sorted_frame_filters) == 0: + print(" No frame filters registered.") + else: + print(" Priority Enabled Name") + for frame_filter in sorted_frame_filters: + name = frame_filter[0] + try: + priority = '{:<8}'.format( + str(gdb.frames.get_priority(frame_filter[1]))) + enabled = '{:<7}'.format( + self.enabled_string(gdb.frames.get_enabled(frame_filter[1]))) + except Exception: + e = sys.exc_info()[1] + print(" Error printing filter '"+name+"': "+str(e)) + else: + print(" %s %s %s" % (priority, enabled, name)) + + def print_list(self, title, filter_list, blank_line): + print(title) + self.list_frame_filters(filter_list) + if blank_line: + print("") + + def invoke(self, arg, from_tty): + self.print_list("global frame-filters:", gdb.frame_filters, True) + + cp = gdb.current_progspace() + self.print_list("progspace %s frame-filters:" % cp.filename, + cp.frame_filters, True) + + for objfile in gdb.objfiles(): + self.print_list("objfile %s frame-filters:" % objfile.filename, + objfile.frame_filters, False) + +# Internal enable/disable functions. + +def _enable_parse_arg(cmd_name, arg): + """ Internal worker function to take an argument from + enable/disable and return a tuple of arguments. + + Arguments: + cmd_name: Name of the command invoking this function. + args: The argument as a string. + + Returns: + A tuple containing the dictionary, and the argument, or just + the dictionary in the case of "all". + """ + + argv = gdb.string_to_argv(arg); + argc = len(argv) + if argv[0] == "all" and argc > 1: + raise gdb.GdbError(cmd_name + ": with 'all' " \ + "you may not specify a filter.") + else: + if argv[0] != "all" and argc != 2: + raise gdb.GdbError(cmd_name + " takes exactly two arguments.") + + return argv + +def _do_enable_frame_filter(command_tuple, flag): + """Worker for enabling/disabling frame_filters. + + Arguments: + command_type: A tuple with the first element being the + frame filter dictionary, and the second being + the frame filter name. + flag: True for Enable, False for Disable. + """ + + list_op = command_tuple[0] + op_list = gdb.frames.return_list(list_op) + + if list_op == "all": + for item in op_list: + gdb.frames.set_enabled(item, flag) + else: + frame_filter = command_tuple[1] + try: + ff = op_list[frame_filter] + except KeyError: + msg = "frame-filter '" + str(name) + "' not found." + raise gdb.GdbError(msg) + + gdb.frames.set_enabled(ff, flag) + +def _complete_frame_filter_list(text, word, all_flag): + """Worker for frame filter dictionary name completion. + + Arguments: + text: The full text of the command line. + word: The most recent word of the command line. + all_flag: Whether to include the word "all" in completion. + + Returns: + A list of suggested frame filter dictionary name completions + from text/word analysis. This list can be empty when there + are no suggestions for completion. + """ + if all_flag == True: + filter_locations = ["all", "global", "progspace"] + else: + filter_locations = ["global", "progspace"] + for objfile in gdb.objfiles(): + filter_locations.append(objfile.filename) + + # If the user just asked for completions with no completion + # hints, just return all the frame filter dictionaries we know + # about. + if (text == ""): + return filter_locations + + # Otherwise filter on what we know. + flist = filter(lambda x,y=text:x.startswith(y), filter_locations) + + # If we only have one completion, complete it and return it. + if len(flist) == 1: + flist[0] = flist[0][len(text)-len(word):] + + # Otherwise, return an empty list, or a list of frame filter + # dictionaries that the previous filter operation returned. + return flist + +def _complete_frame_filter_name(word, printer_dict): + """Worker for frame filter name completion. + + Arguments: + + word: The most recent word of the command line. + + printer_dict: The frame filter dictionary to search for frame + filter name completions. + + Returns: A list of suggested frame filter name completions + from word analysis of the frame filter dictionary. This list + can be empty when there are no suggestions for completion. + """ + + printer_keys = printer_dict.keys() + if (word == ""): + return printer_keys + + flist = filter(lambda x,y=word:x.startswith(y), printer_keys) + return flist + +class EnableFrameFilter(gdb.Command): + """GDB command to disable the specified frame-filter. + + Usage: enable frame-filter enable DICTIONARY [NAME] + + DICTIONARY is the name of the frame filter dictionary on which to + operate. If dictionary is set to "all", perform operations on all + dictionaries. Named dictionaries are: "global" for the global + frame filter dictionary, "progspace" for the program space's frame + filter dictionary. If either all, or the two named dictionaries + are not specified, the dictionary name is assumed to be the name + of the object-file name. + + NAME matches the name of the frame-filter to operate on. If + DICTIONARY is "all", NAME is ignored. + """ + def __init__(self): + super(EnableFrameFilter, self).__init__("enable frame-filter", + gdb.COMMAND_DATA) + def complete(self, text, word): + """Completion function for both frame filter dictionary, and + frame filter name.""" + if text.count(" ") == 0: + return _complete_frame_filter_list(text, word, True) + else: + printer_list = gdb.frames.return_list(text.split()[0].rstrip()) + return _complete_frame_filter_name(word, printer_list) + + def invoke(self, arg, from_tty): + command_tuple = _enable_parse_arg("enable frame-filter", arg) + _do_enable_frame_filter(command_tuple, True) + + +class DisableFrameFilter(gdb.Command): + """GDB command to disable the specified frame-filter. + + Usage: disable frame-filter disable DICTIONARY [NAME] + + DICTIONARY is the name of the frame filter dictionary on which to + operate. If dictionary is set to "all", perform operations on all + dictionaries. Named dictionaries are: "global" for the global + frame filter dictionary, "progspace" for the program space's frame + filter dictionary. If either all, or the two named dictionaries + are not specified, the dictionary name is assumed to be the name + of the object-file name. + + NAME matches the name of the frame-filter to operate on. If + DICTIONARY is "all", NAME is ignored. + """ + def __init__(self): + super(DisableFrameFilter, self).__init__("disable frame-filter", + gdb.COMMAND_DATA) + + def complete(self, text, word): + """Completion function for both frame filter dictionary, and + frame filter name.""" + if text.count(" ") == 0: + return _complete_frame_filter_list(text, word, True) + else: + printer_list = gdb.frames.return_list(text.split()[0].rstrip()) + return _complete_frame_filter_name(word, printer_list) + + def invoke(self, arg, from_tty): + command_tuple = _enable_parse_arg("disable frame-filter", arg) + _do_enable_frame_filter(command_tuple, False) + +class SetFrameFilterPriority(gdb.Command): + """GDB command to set the priority of the specified frame-filter. + + Usage: set frame-filter priority DICTIONARY NAME PRIORITY + + DICTIONARY is the name of the frame filter dictionary on which to + operate. Named dictionaries are: "global" for the global frame + filter dictionary, "progspace" for the program space's framefilter + dictionary. If either of these two are not specified, the + dictionary name is assumed to be the name of the object-file name. + + NAME matches the name of the frame filter to operate on. + + PRIORITY is the an integer to assign the new priority to the frame + filter. + """ + + def __init__(self): + super(SetFrameFilterPriority, self).__init__("set frame-filter " \ + "priority", + gdb.COMMAND_DATA) + + def _parse_pri_arg(self, arg): + """Internal worker to parse a priority from a tuple. + + Arguments: + arg: Tuple which contains the arguments from the command. + + Returns: + A tuple containing the dictionary, name and priority from + the arguments. + + Raises: + gdb.GdbError: An error parsing the arguments. + """ + + argv = gdb.string_to_argv(arg); + argc = len(argv) + if argc != 3: + print("set frame-filter priority " \ + "takes exactly three arguments.") + return None + + return argv + + def _set_filter_priority(self, command_tuple): + """Internal worker for setting priority of frame-filters, by + parsing a tuple and calling _set_priority with the parsed + tuple. + + Arguments: + command_tuple: Tuple which contains the arguments from the + command. + """ + + list_op = command_tuple[0] + frame_filter = command_tuple[1] + + # GDB returns arguments as a string, so convert priority to + # a number. + priority = int(command_tuple[2]) + + op_list = gdb.frames.return_list(list_op) + + try: + ff = op_list[frame_filter] + except KeyError: + msg = "frame-filter '" + str(name) + "' not found." + raise gdb.GdbError(msg) + + gdb.frames.set_priority(ff, priority) + + def complete(self, text, word): + """Completion function for both frame filter dictionary, and + frame filter name.""" + if text.count(" ") == 0: + return _complete_frame_filter_list(text, word, False) + else: + printer_list = gdb.frames.return_list(text.split()[0].rstrip()) + return _complete_frame_filter_name(word, printer_list) + + def invoke(self, arg, from_tty): + command_tuple = self._parse_pri_arg(arg) + if command_tuple != None: + self._set_filter_priority(command_tuple) + +class ShowFrameFilterPriority(gdb.Command): + """GDB command to show the priority of the specified frame-filter. + + Usage: show frame-filter priority DICTIONARY NAME + + DICTIONARY is the name of the frame filter dictionary on which to + operate. Named dictionaries are: "global" for the global frame + filter dictionary, "progspace" for the program space's framefilter + dictionary. If either of these two are not specified, the + dictionary name is assumed to be the name of the object-file name. + + NAME matches the name of the frame-filter to operate on. + """ + + def __init__(self): + super(ShowFrameFilterPriority, self).__init__("show frame-filter " \ + "priority", + gdb.COMMAND_DATA) + + def _parse_pri_arg(self, arg): + """Internal worker to parse a dictionary and name from a + tuple. + + Arguments: + arg: Tuple which contains the arguments from the command. + + Returns: + A tuple containing the dictionary, and frame filter name. + + Raises: + gdb.GdbError: An error parsing the arguments. + """ + + argv = gdb.string_to_argv(arg); + argc = len(argv) + if argc != 2: + print("show frame-filter priority " \ + "takes exactly two arguments.") + return None + + return argv + + def get_filter_priority(self, frame_filters, name): + """Worker for retrieving the priority of frame_filters. + + Arguments: + frame_filters: Name of frame filter dictionary. + name: object to select printers. + + Returns: + The priority of the frame filter. + + Raises: + gdb.GdbError: A frame filter cannot be found. + """ + + op_list = gdb.frames.return_list(frame_filters) + + try: + ff = op_list[name] + except KeyError: + msg = "frame-filter '" + str(name) + "' not found." + raise gdb.GdbError(msg) + + return gdb.frames.get_priority(ff) + + def complete(self, text, word): + """Completion function for both frame filter dictionary, and + frame filter name.""" + + if text.count(" ") == 0: + return _complete_frame_filter_list(text, word, False) + else: + printer_list = frame._return_list(text.split()[0].rstrip()) + return _complete_frame_filter_name(word, printer_list) + + def invoke(self, arg, from_tty): + command_tuple = self._parse_pri_arg(arg) + if command_tuple == None: + return + filter_name = command_tuple[1] + list_name = command_tuple[0] + try: + priority = self.get_filter_priority(list_name, filter_name); + except Exception: + e = sys.exc_info()[1] + print("Error printing filter priority for '"+name+"':"+str(e)) + else: + print("Priority of filter '" + filter_name + "' in list '" \ + + list_name + "' is: " + str(priority)) + +# Register commands +SetFilterPrefixCmd() +ShowFilterPrefixCmd() +InfoFrameFilter() +EnableFrameFilter() +DisableFrameFilter() +SetFrameFilterPriority() +ShowFrameFilterPriority() diff --git a/util/X86MAC64/share/gdb/python/gdb/command/frame_filters.pyc b/util/X86MAC64/share/gdb/python/gdb/command/frame_filters.pyc new file mode 100644 index 0000000000..423a0d7414 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/command/frame_filters.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/command/pretty_printers.py b/util/X86MAC64/share/gdb/python/gdb/command/pretty_printers.py new file mode 100644 index 0000000000..a9027b3504 --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/command/pretty_printers.py @@ -0,0 +1,368 @@ +# Pretty-printer commands. +# Copyright (C) 2010-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +"""GDB commands for working with pretty-printers.""" + +import copy +import gdb +import re + + +def parse_printer_regexps(arg): + """Internal utility to parse a pretty-printer command argv. + + Arguments: + arg: The arguments to the command. The format is: + [object-regexp [name-regexp]]. + Individual printers in a collection are named as + printer-name;subprinter-name. + + Returns: + The result is a 3-tuple of compiled regular expressions, except that + the resulting compiled subprinter regexp is None if not provided. + + Raises: + SyntaxError: an error processing ARG + """ + + argv = gdb.string_to_argv(arg); + argc = len(argv) + object_regexp = "" # match everything + name_regexp = "" # match everything + subname_regexp = None + if argc > 3: + raise SyntaxError("too many arguments") + if argc >= 1: + object_regexp = argv[0] + if argc >= 2: + name_subname = argv[1].split(";", 1) + name_regexp = name_subname[0] + if len(name_subname) == 2: + subname_regexp = name_subname[1] + # That re.compile raises SyntaxError was determined empirically. + # We catch it and reraise it to provide a slightly more useful + # error message for the user. + try: + object_re = re.compile(object_regexp) + except SyntaxError: + raise SyntaxError("invalid object regexp: %s" % object_regexp) + try: + name_re = re.compile (name_regexp) + except SyntaxError: + raise SyntaxError("invalid name regexp: %s" % name_regexp) + if subname_regexp is not None: + try: + subname_re = re.compile(subname_regexp) + except SyntaxError: + raise SyntaxError("invalid subname regexp: %s" % subname_regexp) + else: + subname_re = None + return(object_re, name_re, subname_re) + + +def printer_enabled_p(printer): + """Internal utility to see if printer (or subprinter) is enabled.""" + if hasattr(printer, "enabled"): + return printer.enabled + else: + return True + + +class InfoPrettyPrinter(gdb.Command): + """GDB command to list all registered pretty-printers. + + Usage: info pretty-printer [object-regexp [name-regexp]] + + OBJECT-REGEXP is a regular expression matching the objects to list. + Objects are "global", the program space's file, and the objfiles within + that program space. + + NAME-REGEXP matches the name of the pretty-printer. + Individual printers in a collection are named as + printer-name;subprinter-name. + """ + + def __init__ (self): + super(InfoPrettyPrinter, self).__init__("info pretty-printer", + gdb.COMMAND_DATA) + + @staticmethod + def enabled_string(printer): + """Return "" if PRINTER is enabled, otherwise " [disabled]".""" + if printer_enabled_p(printer): + return "" + else: + return " [disabled]" + + @staticmethod + def printer_name(printer): + """Return the printer's name.""" + if hasattr(printer, "name"): + return printer.name + if hasattr(printer, "__name__"): + return printer.__name__ + # This "shouldn't happen", but the public API allows for + # direct additions to the pretty-printer list, and we shouldn't + # crash because someone added a bogus printer. + # Plus we want to give the user a way to list unknown printers. + return "unknown" + + def list_pretty_printers(self, pretty_printers, name_re, subname_re): + """Print a list of pretty-printers.""" + # A potential enhancement is to provide an option to list printers in + # "lookup order" (i.e. unsorted). + sorted_pretty_printers = sorted (copy.copy(pretty_printers), + key = self.printer_name) + for printer in sorted_pretty_printers: + name = self.printer_name(printer) + enabled = self.enabled_string(printer) + if name_re.match(name): + print (" %s%s" % (name, enabled)) + if (hasattr(printer, "subprinters") and + printer.subprinters is not None): + sorted_subprinters = sorted (copy.copy(printer.subprinters), + key = self.printer_name) + for subprinter in sorted_subprinters: + if (not subname_re or + subname_re.match(subprinter.name)): + print (" %s%s" % + (subprinter.name, + self.enabled_string(subprinter))) + + def invoke1(self, title, printer_list, + obj_name_to_match, object_re, name_re, subname_re): + """Subroutine of invoke to simplify it.""" + if printer_list and object_re.match(obj_name_to_match): + print (title) + self.list_pretty_printers(printer_list, name_re, subname_re) + + def invoke(self, arg, from_tty): + """GDB calls this to perform the command.""" + (object_re, name_re, subname_re) = parse_printer_regexps(arg) + self.invoke1("global pretty-printers:", gdb.pretty_printers, + "global", object_re, name_re, subname_re) + cp = gdb.current_progspace() + self.invoke1("progspace %s pretty-printers:" % cp.filename, + cp.pretty_printers, "progspace", + object_re, name_re, subname_re) + for objfile in gdb.objfiles(): + self.invoke1(" objfile %s pretty-printers:" % objfile.filename, + objfile.pretty_printers, objfile.filename, + object_re, name_re, subname_re) + + +def count_enabled_printers(pretty_printers): + """Return a 2-tuple of number of enabled and total printers.""" + enabled = 0 + total = 0 + for printer in pretty_printers: + if (hasattr(printer, "subprinters") + and printer.subprinters is not None): + if printer_enabled_p(printer): + for subprinter in printer.subprinters: + if printer_enabled_p(subprinter): + enabled += 1 + total += len(printer.subprinters) + else: + if printer_enabled_p(printer): + enabled += 1 + total += 1 + return (enabled, total) + + +def count_all_enabled_printers(): + """Return a 2-tuble of the enabled state and total number of all printers. + This includes subprinters. + """ + enabled_count = 0 + total_count = 0 + (t_enabled, t_total) = count_enabled_printers(gdb.pretty_printers) + enabled_count += t_enabled + total_count += t_total + (t_enabled, t_total) = count_enabled_printers(gdb.current_progspace().pretty_printers) + enabled_count += t_enabled + total_count += t_total + for objfile in gdb.objfiles(): + (t_enabled, t_total) = count_enabled_printers(objfile.pretty_printers) + enabled_count += t_enabled + total_count += t_total + return (enabled_count, total_count) + + +def pluralize(text, n, suffix="s"): + """Return TEXT pluralized if N != 1.""" + if n != 1: + return "%s%s" % (text, suffix) + else: + return text + + +def show_pretty_printer_enabled_summary(): + """Print the number of printers enabled/disabled. + We count subprinters individually. + """ + (enabled_count, total_count) = count_all_enabled_printers() + print ("%d of %d printers enabled" % (enabled_count, total_count)) + + +def do_enable_pretty_printer_1 (pretty_printers, name_re, subname_re, flag): + """Worker for enabling/disabling pretty-printers. + + Arguments: + pretty_printers: list of pretty-printers + name_re: regular-expression object to select printers + subname_re: regular expression object to select subprinters or None + if all are affected + flag: True for Enable, False for Disable + + Returns: + The number of printers affected. + This is just for informational purposes for the user. + """ + total = 0 + for printer in pretty_printers: + if (hasattr(printer, "name") and name_re.match(printer.name) or + hasattr(printer, "__name__") and name_re.match(printer.__name__)): + if (hasattr(printer, "subprinters") and + printer.subprinters is not None): + if not subname_re: + # Only record printers that change state. + if printer_enabled_p(printer) != flag: + for subprinter in printer.subprinters: + if printer_enabled_p(subprinter): + total += 1 + # NOTE: We preserve individual subprinter settings. + printer.enabled = flag + else: + # NOTE: Whether this actually disables the subprinter + # depends on whether the printer's lookup function supports + # the "enable" API. We can only assume it does. + for subprinter in printer.subprinters: + if subname_re.match(subprinter.name): + # Only record printers that change state. + if (printer_enabled_p(printer) and + printer_enabled_p(subprinter) != flag): + total += 1 + subprinter.enabled = flag + else: + # This printer has no subprinters. + # If the user does "disable pretty-printer .* .* foo" + # should we disable printers that don't have subprinters? + # How do we apply "foo" in this context? Since there is no + # "foo" subprinter it feels like we should skip this printer. + # There's still the issue of how to handle + # "disable pretty-printer .* .* .*", and every other variation + # that can match everything. For now punt and only support + # "disable pretty-printer .* .*" (i.e. subname is elided) + # to disable everything. + if not subname_re: + # Only record printers that change state. + if printer_enabled_p(printer) != flag: + total += 1 + printer.enabled = flag + return total + + +def do_enable_pretty_printer (arg, flag): + """Internal worker for enabling/disabling pretty-printers.""" + (object_re, name_re, subname_re) = parse_printer_regexps(arg) + + total = 0 + if object_re.match("global"): + total += do_enable_pretty_printer_1(gdb.pretty_printers, + name_re, subname_re, flag) + cp = gdb.current_progspace() + if object_re.match("progspace"): + total += do_enable_pretty_printer_1(cp.pretty_printers, + name_re, subname_re, flag) + for objfile in gdb.objfiles(): + if object_re.match(objfile.filename): + total += do_enable_pretty_printer_1(objfile.pretty_printers, + name_re, subname_re, flag) + + if flag: + state = "enabled" + else: + state = "disabled" + print ("%d %s %s" % (total, pluralize("printer", total), state)) + + # Print the total list of printers currently enabled/disabled. + # This is to further assist the user in determining whether the result + # is expected. Since we use regexps to select it's useful. + show_pretty_printer_enabled_summary() + + +# Enable/Disable one or more pretty-printers. +# +# This is intended for use when a broken pretty-printer is shipped/installed +# and the user wants to disable that printer without disabling all the other +# printers. +# +# A useful addition would be -v (verbose) to show each printer affected. + +class EnablePrettyPrinter (gdb.Command): + """GDB command to enable the specified pretty-printer. + + Usage: enable pretty-printer [object-regexp [name-regexp]] + + OBJECT-REGEXP is a regular expression matching the objects to examine. + Objects are "global", the program space's file, and the objfiles within + that program space. + + NAME-REGEXP matches the name of the pretty-printer. + Individual printers in a collection are named as + printer-name;subprinter-name. + """ + + def __init__(self): + super(EnablePrettyPrinter, self).__init__("enable pretty-printer", + gdb.COMMAND_DATA) + + def invoke(self, arg, from_tty): + """GDB calls this to perform the command.""" + do_enable_pretty_printer(arg, True) + + +class DisablePrettyPrinter (gdb.Command): + """GDB command to disable the specified pretty-printer. + + Usage: disable pretty-printer [object-regexp [name-regexp]] + + OBJECT-REGEXP is a regular expression matching the objects to examine. + Objects are "global", the program space's file, and the objfiles within + that program space. + + NAME-REGEXP matches the name of the pretty-printer. + Individual printers in a collection are named as + printer-name;subprinter-name. + """ + + def __init__(self): + super(DisablePrettyPrinter, self).__init__("disable pretty-printer", + gdb.COMMAND_DATA) + + def invoke(self, arg, from_tty): + """GDB calls this to perform the command.""" + do_enable_pretty_printer(arg, False) + + +def register_pretty_printer_commands(): + """Call from a top level script to install the pretty-printer commands.""" + InfoPrettyPrinter() + EnablePrettyPrinter() + DisablePrettyPrinter() + +register_pretty_printer_commands() diff --git a/util/X86MAC64/share/gdb/python/gdb/command/pretty_printers.pyc b/util/X86MAC64/share/gdb/python/gdb/command/pretty_printers.pyc new file mode 100644 index 0000000000..f7289f590c Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/command/pretty_printers.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/command/prompt.py b/util/X86MAC64/share/gdb/python/gdb/command/prompt.py new file mode 100644 index 0000000000..e7dc3daa24 --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/command/prompt.py @@ -0,0 +1,66 @@ +# Extended prompt. +# Copyright (C) 2011-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +"""GDB command for working with extended prompts.""" + +import gdb +import gdb.prompt + +class _ExtendedPrompt(gdb.Parameter): + + """Set the extended prompt. + +Usage: set extended-prompt VALUE + +Substitutions are applied to VALUE to compute the real prompt. + +The currently defined substitutions are: + +""" + # Add the prompt library's dynamically generated help to the + # __doc__ string. + __doc__ = __doc__ + gdb.prompt.prompt_help() + + set_doc = "Set the extended prompt." + show_doc = "Show the extended prompt." + + def __init__(self): + super(_ExtendedPrompt, self).__init__("extended-prompt", + gdb.COMMAND_SUPPORT, + gdb.PARAM_STRING_NOESCAPE) + self.value = '' + self.hook_set = False + + def get_show_string (self, pvalue): + if self.value is not '': + return "The extended prompt is: " + self.value + else: + return "The extended prompt is not set." + + def get_set_string (self): + if self.hook_set == False: + gdb.prompt_hook = self.before_prompt_hook + self.hook_set = True + return "" + + def before_prompt_hook(self, current): + if self.value is not '': + newprompt = gdb.prompt.substitute_prompt(self.value) + return newprompt.replace('\\', '\\\\') + else: + return None + +_ExtendedPrompt() diff --git a/util/X86MAC64/share/gdb/python/gdb/command/prompt.pyc b/util/X86MAC64/share/gdb/python/gdb/command/prompt.pyc new file mode 100644 index 0000000000..52880c0863 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/command/prompt.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/command/type_printers.py b/util/X86MAC64/share/gdb/python/gdb/command/type_printers.py new file mode 100644 index 0000000000..9376be84ba --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/command/type_printers.py @@ -0,0 +1,125 @@ +# Type printer commands. +# Copyright (C) 2010-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +import copy +import gdb + +"""GDB commands for working with type-printers.""" + +class InfoTypePrinter(gdb.Command): + """GDB command to list all registered type-printers. + + Usage: info type-printers + """ + + def __init__ (self): + super(InfoTypePrinter, self).__init__("info type-printers", + gdb.COMMAND_DATA) + + def list_type_printers(self, type_printers): + """Print a list of type printers.""" + # A potential enhancement is to provide an option to list printers in + # "lookup order" (i.e. unsorted). + sorted_type_printers = sorted (copy.copy(type_printers), + key = lambda x: x.name) + for printer in sorted_type_printers: + if printer.enabled: + enabled = '' + else: + enabled = " [disabled]" + print (" %s%s" % (printer.name, enabled)) + + def invoke(self, arg, from_tty): + """GDB calls this to perform the command.""" + sep = '' + for objfile in gdb.objfiles(): + if objfile.type_printers: + print ("%sType printers for %s:" % (sep, objfile.name)) + self.list_type_printers(objfile.type_printers) + sep = '\n' + if gdb.current_progspace().type_printers: + print ("%sType printers for program space:" % sep) + self.list_type_printers(gdb.current_progspace().type_printers) + sep = '\n' + if gdb.type_printers: + print ("%sGlobal type printers:" % sep) + self.list_type_printers(gdb.type_printers) + +class _EnableOrDisableCommand(gdb.Command): + def __init__(self, setting, name): + super(_EnableOrDisableCommand, self).__init__(name, gdb.COMMAND_DATA) + self.setting = setting + + def set_some(self, name, printers): + result = False + for p in printers: + if name == p.name: + p.enabled = self.setting + result = True + return result + + def invoke(self, arg, from_tty): + """GDB calls this to perform the command.""" + for name in arg.split(): + ok = False + for objfile in gdb.objfiles(): + if self.set_some(name, objfile.type_printers): + ok = True + if self.set_some(name, gdb.current_progspace().type_printers): + ok = True + if self.set_some(name, gdb.type_printers): + ok = True + if not ok: + print ("No type printer named '%s'" % name) + + def add_some(self, result, word, printers): + for p in printers: + if p.name.startswith(word): + result.append(p.name) + + def complete(self, text, word): + result = [] + for objfile in gdb.objfiles(): + self.add_some(result, word, objfile.type_printers) + self.add_some(result, word, gdb.current_progspace().type_printers) + self.add_some(result, word, gdb.type_printers) + return result + +class EnableTypePrinter(_EnableOrDisableCommand): + """GDB command to enable the specified type printer. + + Usage: enable type-printer NAME + + NAME is the name of the type-printer. + """ + + def __init__(self): + super(EnableTypePrinter, self).__init__(True, "enable type-printer") + +class DisableTypePrinter(_EnableOrDisableCommand): + """GDB command to disable the specified type-printer. + + Usage: disable type-printer NAME + + NAME is the name of the type-printer. + """ + + def __init__(self): + super(DisableTypePrinter, self).__init__(False, "disable type-printer") + +InfoTypePrinter() +EnableTypePrinter() +DisableTypePrinter() diff --git a/util/X86MAC64/share/gdb/python/gdb/command/type_printers.pyc b/util/X86MAC64/share/gdb/python/gdb/command/type_printers.pyc new file mode 100644 index 0000000000..663489a051 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/command/type_printers.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/frames.py b/util/X86MAC64/share/gdb/python/gdb/frames.py new file mode 100644 index 0000000000..19172e7a69 --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/frames.py @@ -0,0 +1,228 @@ +# Frame-filter commands. +# Copyright (C) 2013-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +"""Internal functions for working with frame-filters.""" + +import gdb +from gdb.FrameIterator import FrameIterator +from gdb.FrameDecorator import FrameDecorator +import itertools +import collections + +def get_priority(filter_item): + """ Internal worker function to return the frame-filter's priority + from a frame filter object. This is a fail free function as it is + used in sorting and filtering. If a badly implemented frame + filter does not implement the priority attribute, return zero + (otherwise sorting/filtering will fail and prevent other frame + filters from executing). + + Arguments: + filter_item: An object conforming to the frame filter + interface. + + Returns: + The priority of the frame filter from the "priority" + attribute, or zero. + """ + # Do not fail here, as the sort will fail. If a filter has not + # (incorrectly) set a priority, set it to zero. + return getattr(filter_item, "priority", 0) + +def set_priority(filter_item, priority): + """ Internal worker function to set the frame-filter's priority. + + Arguments: + filter_item: An object conforming to the frame filter + interface. + priority: The priority to assign as an integer. + """ + + filter_item.priority = priority + +def get_enabled(filter_item): + """ Internal worker function to return a filter's enabled state + from a frame filter object. This is a fail free function as it is + used in sorting and filtering. If a badly implemented frame + filter does not implement the enabled attribute, return False + (otherwise sorting/filtering will fail and prevent other frame + filters from executing). + + Arguments: + filter_item: An object conforming to the frame filter + interface. + + Returns: + The enabled state of the frame filter from the "enabled" + attribute, or False. + """ + + # If the filter class is badly implemented when called from the + # Python filter command, do not cease filter operations, just set + # enabled to False. + return getattr(filter_item, "enabled", False) + +def set_enabled(filter_item, state): + """ Internal Worker function to set the frame-filter's enabled + state. + + Arguments: + filter_item: An object conforming to the frame filter + interface. + state: True or False, depending on desired state. + """ + + filter_item.enabled = state + +def return_list(name): + """ Internal Worker function to return the frame filter + dictionary, depending on the name supplied as an argument. If the + name is not "all", "global" or "progspace", it is assumed to name + an object-file. + + Arguments: + name: The name of the list, as specified by GDB user commands. + + Returns: + A dictionary object for a single specified dictionary, or a + list containing all the items for "all" + + Raises: + gdb.GdbError: A dictionary of that name cannot be found. + """ + + # If all dictionaries are wanted in the case of "all" we + # cannot return a combined dictionary as keys() may clash in + # between different dictionaries. As we just want all the frame + # filters to enable/disable them all, just return the combined + # items() as a chained iterator of dictionary values. + if name == "all": + glob = gdb.frame_filters.values() + prog = gdb.current_progspace().frame_filters.values() + return_iter = itertools.chain(glob, prog) + for objfile in gdb.objfiles(): + return_iter = itertools.chain(return_iter, objfile.frame_filters.values()) + + return return_iter + + if name == "global": + return gdb.frame_filters + else: + if name == "progspace": + cp = gdb.current_progspace() + return cp.frame_filters + else: + for objfile in gdb.objfiles(): + if name == objfile.filename: + return objfile.frame_filters + + msg = "Cannot find frame-filter dictionary for '" + name + "'" + raise gdb.GdbError(msg) + +def _sort_list(): + """ Internal Worker function to merge all known frame-filter + lists, prune any filters with the state set to "disabled", and + sort the list on the frame-filter's "priority" attribute. + + Returns: + sorted_list: A sorted, pruned list of frame filters to + execute. + """ + + all_filters = return_list("all") + sorted_frame_filters = sorted(all_filters, key = get_priority, + reverse = True) + + sorted_frame_filters = filter(get_enabled, + sorted_frame_filters) + + return sorted_frame_filters + +def execute_frame_filters(frame, frame_low, frame_high): + """ Internal function called from GDB that will execute the chain + of frame filters. Each filter is executed in priority order. + After the execution completes, slice the iterator to frame_low - + frame_high range. + + Arguments: + frame: The initial frame. + + frame_low: The low range of the slice. If this is a negative + integer then it indicates a backward slice (ie bt -4) which + counts backward from the last frame in the backtrace. + + frame_high: The high range of the slice. If this is -1 then + it indicates all frames until the end of the stack from + frame_low. + + Returns: + frame_iterator: The sliced iterator after all frame + filters have had a change to execute, or None if no frame + filters are registered. + """ + + # Get a sorted list of frame filters. + sorted_list = list(_sort_list()) + + # Check to see if there are any frame-filters. If not, just + # return None and let default backtrace printing occur. + if len(sorted_list) == 0: + return None + + frame_iterator = FrameIterator(frame) + + # Apply a basic frame decorator to all gdb.Frames. This unifies + # the interface. Python 3.x moved the itertools.imap + # functionality to map(), so check if it is available. + if hasattr(itertools,"imap"): + frame_iterator = itertools.imap(FrameDecorator, frame_iterator) + else: + frame_iterator = map(FrameDecorator, frame_iterator) + + for ff in sorted_list: + frame_iterator = ff.filter(frame_iterator) + + # Slicing + + # Is this a slice from the end of the backtrace, ie bt -2? + if frame_low < 0: + count = 0 + slice_length = abs(frame_low) + # We cannot use MAXLEN argument for deque as it is 2.6 onwards + # and some GDB versions might be < 2.6. + sliced = collections.deque() + + for frame_item in frame_iterator: + if count >= slice_length: + sliced.popleft(); + count = count + 1 + sliced.append(frame_item) + + return iter(sliced) + + # -1 for frame_high means until the end of the backtrace. Set to + # None if that is the case, to indicate to itertools.islice to + # slice to the end of the iterator. + if frame_high == -1: + frame_high = None + else: + # As frames start from 0, add one to frame_high so islice + # correctly finds the end + frame_high = frame_high + 1; + + sliced = itertools.islice(frame_iterator, frame_low, frame_high) + + return sliced diff --git a/util/X86MAC64/share/gdb/python/gdb/frames.pyc b/util/X86MAC64/share/gdb/python/gdb/frames.pyc new file mode 100644 index 0000000000..68b9bacc75 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/frames.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/function/__init__.py b/util/X86MAC64/share/gdb/python/gdb/function/__init__.py new file mode 100644 index 0000000000..bcfadc3bac --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/function/__init__.py @@ -0,0 +1,14 @@ +# Copyright (C) 2012-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . diff --git a/util/X86MAC64/share/gdb/python/gdb/function/__init__.pyc b/util/X86MAC64/share/gdb/python/gdb/function/__init__.pyc new file mode 100644 index 0000000000..5fdec8e54a Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/function/__init__.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/function/strfns.py b/util/X86MAC64/share/gdb/python/gdb/function/strfns.py new file mode 100644 index 0000000000..9e2ed79a44 --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/function/strfns.py @@ -0,0 +1,108 @@ +# Useful gdb string convenience functions. +# Copyright (C) 2012-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +"""$_memeq, $_strlen, $_streq, $_regex""" + +import gdb +import re + + +class _MemEq(gdb.Function): + """$_memeq - compare bytes of memory + +Usage: + $_memeq(a, b, len) + +Returns: + True if len bytes at a and b compare equally. +""" + def __init__(self): + super(_MemEq, self).__init__("_memeq") + + def invoke(self, a, b, length): + if length < 0: + raise ValueError("length must be non-negative") + if length == 0: + return True + # The argument(s) to vector are [low_bound,]high_bound. + byte_vector = gdb.lookup_type("char").vector(length - 1) + ptr_byte_vector = byte_vector.pointer() + a_ptr = a.reinterpret_cast(ptr_byte_vector) + b_ptr = b.reinterpret_cast(ptr_byte_vector) + return a_ptr.dereference() == b_ptr.dereference() + + +class _StrLen(gdb.Function): + """$_strlen - compute string length + +Usage: + $_strlen(a) + +Returns: + Length of string a, assumed to be a string in the current language. +""" + def __init__(self): + super(_StrLen, self).__init__("_strlen") + + def invoke(self, a): + s = a.string() + return len(s) + + +class _StrEq(gdb.Function): + """$_streq - check string equality + +Usage: + $_streq(a, b) + +Returns: + True if a and b are identical strings in the current language. + +Example (amd64-linux): + catch syscall open + cond $bpnum $_streq((char*) $rdi, "foo") +""" + def __init__(self): + super(_StrEq, self).__init__("_streq") + + def invoke(self, a, b): + return a.string() == b.string() + + +class _RegEx(gdb.Function): + """$_regex - check if a string matches a regular expression + +Usage: + $_regex(string, regex) + +Returns: + True if string str (in the current language) matches the + regular expression regex. +""" + def __init__(self): + super(_RegEx, self).__init__("_regex") + + def invoke(self, string, regex): + s = string.string() + r = re.compile(regex.string()) + return bool(r.match(s)) + + +# GDB will import us automagically via gdb/__init__.py. +_MemEq() +_StrLen() +_StrEq() +_RegEx() diff --git a/util/X86MAC64/share/gdb/python/gdb/function/strfns.pyc b/util/X86MAC64/share/gdb/python/gdb/function/strfns.pyc new file mode 100644 index 0000000000..26e87b322b Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/function/strfns.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/printing.py b/util/X86MAC64/share/gdb/python/gdb/printing.py new file mode 100644 index 0000000000..80227c8ccc --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/printing.py @@ -0,0 +1,263 @@ +# Pretty-printer utilities. +# Copyright (C) 2010-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +"""Utilities for working with pretty-printers.""" + +import gdb +import gdb.types +import re +import sys + +if sys.version_info[0] > 2: + # Python 3 removed basestring and long + basestring = str + long = int + +class PrettyPrinter(object): + """A basic pretty-printer. + + Attributes: + name: A unique string among all printers for the context in which + it is defined (objfile, progspace, or global(gdb)), and should + meaningfully describe what can be pretty-printed. + E.g., "StringPiece" or "protobufs". + subprinters: An iterable object with each element having a `name' + attribute, and, potentially, "enabled" attribute. + Or this is None if there are no subprinters. + enabled: A boolean indicating if the printer is enabled. + + Subprinters are for situations where "one" pretty-printer is actually a + collection of several printers. E.g., The libstdc++ pretty-printer has + a pretty-printer for each of several different types, based on regexps. + """ + + # While one might want to push subprinters into the subclass, it's + # present here to formalize such support to simplify + # commands/pretty_printers.py. + + def __init__(self, name, subprinters=None): + self.name = name + self.subprinters = subprinters + self.enabled = True + + def __call__(self, val): + # The subclass must define this. + raise NotImplementedError("PrettyPrinter __call__") + + +class SubPrettyPrinter(object): + """Baseclass for sub-pretty-printers. + + Sub-pretty-printers needn't use this, but it formalizes what's needed. + + Attributes: + name: The name of the subprinter. + enabled: A boolean indicating if the subprinter is enabled. + """ + + def __init__(self, name): + self.name = name + self.enabled = True + + +def register_pretty_printer(obj, printer, replace=False): + """Register pretty-printer PRINTER with OBJ. + + The printer is added to the front of the search list, thus one can override + an existing printer if one needs to. Use a different name when overriding + an existing printer, otherwise an exception will be raised; multiple + printers with the same name are disallowed. + + Arguments: + obj: Either an objfile, progspace, or None (in which case the printer + is registered globally). + printer: Either a function of one argument (old way) or any object + which has attributes: name, enabled, __call__. + replace: If True replace any existing copy of the printer. + Otherwise if the printer already exists raise an exception. + + Returns: + Nothing. + + Raises: + TypeError: A problem with the type of the printer. + ValueError: The printer's name contains a semicolon ";". + RuntimeError: A printer with the same name is already registered. + + If the caller wants the printer to be listable and disableable, it must + follow the PrettyPrinter API. This applies to the old way (functions) too. + If printer is an object, __call__ is a method of two arguments: + self, and the value to be pretty-printed. See PrettyPrinter. + """ + + # Watch for both __name__ and name. + # Functions get the former for free, but we don't want to use an + # attribute named __foo__ for pretty-printers-as-objects. + # If printer has both, we use `name'. + if not hasattr(printer, "__name__") and not hasattr(printer, "name"): + raise TypeError("printer missing attribute: name") + if hasattr(printer, "name") and not hasattr(printer, "enabled"): + raise TypeError("printer missing attribute: enabled") + if not hasattr(printer, "__call__"): + raise TypeError("printer missing attribute: __call__") + + if obj is None: + if gdb.parameter("verbose"): + gdb.write("Registering global %s pretty-printer ...\n" % name) + obj = gdb + else: + if gdb.parameter("verbose"): + gdb.write("Registering %s pretty-printer for %s ...\n" % + (printer.name, obj.filename)) + + if hasattr(printer, "name"): + if not isinstance(printer.name, basestring): + raise TypeError("printer name is not a string") + # If printer provides a name, make sure it doesn't contain ";". + # Semicolon is used by the info/enable/disable pretty-printer commands + # to delimit subprinters. + if printer.name.find(";") >= 0: + raise ValueError("semicolon ';' in printer name") + # Also make sure the name is unique. + # Alas, we can't do the same for functions and __name__, they could + # all have a canonical name like "lookup_function". + # PERF: gdb records printers in a list, making this inefficient. + i = 0 + for p in obj.pretty_printers: + if hasattr(p, "name") and p.name == printer.name: + if replace: + del obj.pretty_printers[i] + break + else: + raise RuntimeError("pretty-printer already registered: %s" % + printer.name) + i = i + 1 + + obj.pretty_printers.insert(0, printer) + + +class RegexpCollectionPrettyPrinter(PrettyPrinter): + """Class for implementing a collection of regular-expression based pretty-printers. + + Intended usage: + + pretty_printer = RegexpCollectionPrettyPrinter("my_library") + pretty_printer.add_printer("myclass1", "^myclass1$", MyClass1Printer) + ... + pretty_printer.add_printer("myclassN", "^myclassN$", MyClassNPrinter) + register_pretty_printer(obj, pretty_printer) + """ + + class RegexpSubprinter(SubPrettyPrinter): + def __init__(self, name, regexp, gen_printer): + super(RegexpCollectionPrettyPrinter.RegexpSubprinter, self).__init__(name) + self.regexp = regexp + self.gen_printer = gen_printer + self.compiled_re = re.compile(regexp) + + def __init__(self, name): + super(RegexpCollectionPrettyPrinter, self).__init__(name, []) + + def add_printer(self, name, regexp, gen_printer): + """Add a printer to the list. + + The printer is added to the end of the list. + + Arguments: + name: The name of the subprinter. + regexp: The regular expression, as a string. + gen_printer: A function/method that given a value returns an + object to pretty-print it. + + Returns: + Nothing. + """ + + # NOTE: A previous version made the name of each printer the regexp. + # That makes it awkward to pass to the enable/disable commands (it's + # cumbersome to make a regexp of a regexp). So now the name is a + # separate parameter. + + self.subprinters.append(self.RegexpSubprinter(name, regexp, + gen_printer)) + + def __call__(self, val): + """Lookup the pretty-printer for the provided value.""" + + # Get the type name. + typename = gdb.types.get_basic_type(val.type).tag + if not typename: + return None + + # Iterate over table of type regexps to determine + # if a printer is registered for that type. + # Return an instantiation of the printer if found. + for printer in self.subprinters: + if printer.enabled and printer.compiled_re.search(typename): + return printer.gen_printer(val) + + # Cannot find a pretty printer. Return None. + return None + +# A helper class for printing enum types. This class is instantiated +# with a list of enumerators to print a particular Value. +class _EnumInstance: + def __init__(self, enumerators, val): + self.enumerators = enumerators + self.val = val + + def to_string(self): + flag_list = [] + v = long(self.val) + any_found = False + for (e_name, e_value) in self.enumerators: + if v & e_value != 0: + flag_list.append(e_name) + v = v & ~e_value + any_found = True + if not any_found or v != 0: + # Leftover value. + flag_list.append('' % v) + return "0x%x [%s]" % (self.val, " | ".join(flag_list)) + +class FlagEnumerationPrinter(PrettyPrinter): + """A pretty-printer which can be used to print a flag-style enumeration. + A flag-style enumeration is one where the enumerators are or'd + together to create values. The new printer will print these + symbolically using '|' notation. The printer must be registered + manually. This printer is most useful when an enum is flag-like, + but has some overlap. GDB's built-in printing will not handle + this case, but this printer will attempt to.""" + + def __init__(self, enum_type): + super(FlagEnumerationPrinter, self).__init__(enum_type) + self.initialized = False + + def __call__(self, val): + if not self.initialized: + self.initialized = True + flags = gdb.lookup_type(self.name) + self.enumerators = [] + for field in flags.fields(): + self.enumerators.append((field.name, field.enumval)) + # Sorting the enumerators by value usually does the right + # thing. + self.enumerators.sort(key = lambda x: x.enumval) + + if self.enabled: + return _EnumInstance(self.enumerators, val) + else: + return None diff --git a/util/X86MAC64/share/gdb/python/gdb/printing.pyc b/util/X86MAC64/share/gdb/python/gdb/printing.pyc new file mode 100644 index 0000000000..a4e7695e57 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/printing.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/prompt.py b/util/X86MAC64/share/gdb/python/gdb/prompt.py new file mode 100644 index 0000000000..d99f2ead7f --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/prompt.py @@ -0,0 +1,148 @@ +# Extended prompt utilities. +# Copyright (C) 2011-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +""" Extended prompt library functions.""" + +import gdb +import os + +def _prompt_pwd(ignore): + "The current working directory." + return os.getcwdu() + +def _prompt_object_attr(func, what, attr, nattr): + """Internal worker for fetching GDB attributes.""" + if attr is None: + attr = nattr + try: + obj = func() + except gdb.error: + return '' % what + if hasattr(obj, attr): + result = getattr(obj, attr) + if callable(result): + result = result() + return result + else: + return '' % (attr, what) + +def _prompt_frame(attr): + "The selected frame; an argument names a frame parameter." + return _prompt_object_attr(gdb.selected_frame, 'frame', attr, 'name') + +def _prompt_thread(attr): + "The selected thread; an argument names a thread parameter." + return _prompt_object_attr(gdb.selected_thread, 'thread', attr, 'num') + +def _prompt_version(attr): + "The version of GDB." + return gdb.VERSION + +def _prompt_esc(attr): + "The ESC character." + return '\033' + +def _prompt_bs(attr): + "A backslash." + return '\\' + +def _prompt_n(attr): + "A newline." + return '\n' + +def _prompt_r(attr): + "A carriage return." + return '\r' + +def _prompt_param(attr): + "A parameter's value; the argument names the parameter." + return gdb.parameter(attr) + +def _prompt_noprint_begin(attr): + "Begins a sequence of non-printing characters." + return '\001' + +def _prompt_noprint_end(attr): + "Ends a sequence of non-printing characters." + return '\002' + +prompt_substitutions = { + 'e': _prompt_esc, + '\\': _prompt_bs, + 'n': _prompt_n, + 'r': _prompt_r, + 'v': _prompt_version, + 'w': _prompt_pwd, + 'f': _prompt_frame, + 't': _prompt_thread, + 'p': _prompt_param, + '[': _prompt_noprint_begin, + ']': _prompt_noprint_end +} + +def prompt_help(): + """Generate help dynamically from the __doc__ strings of attribute + functions.""" + + result = '' + keys = sorted (prompt_substitutions.keys()) + for key in keys: + result += ' \\%s\t%s\n' % (key, prompt_substitutions[key].__doc__) + result += """ +A substitution can be used in a simple form, like "\\f". +An argument can also be passed to it, like "\\f{name}". +The meaning of the argument depends on the particular substitution.""" + return result + +def substitute_prompt(prompt): + "Perform substitutions on PROMPT." + + result = '' + plen = len(prompt) + i = 0 + while i < plen: + if prompt[i] == '\\': + i = i + 1 + if i >= plen: + break + cmdch = prompt[i] + + if cmdch in prompt_substitutions: + cmd = prompt_substitutions[cmdch] + + if i + 1 < plen and prompt[i + 1] == '{': + j = i + 1 + while j < plen and prompt[j] != '}': + j = j + 1 + # Just ignore formatting errors. + if j >= plen or prompt[j] != '}': + arg = None + else: + arg = prompt[i + 2 : j] + i = j + else: + arg = None + result += str(cmd(arg)) + else: + # Unrecognized escapes are turned into the escaped + # character itself. + result += prompt[i] + else: + result += prompt[i] + + i = i + 1 + + return result diff --git a/util/X86MAC64/share/gdb/python/gdb/prompt.pyc b/util/X86MAC64/share/gdb/python/gdb/prompt.pyc new file mode 100644 index 0000000000..29090ff974 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/prompt.pyc differ diff --git a/util/X86MAC64/share/gdb/python/gdb/types.py b/util/X86MAC64/share/gdb/python/gdb/types.py new file mode 100644 index 0000000000..5fa4eab4ff --- /dev/null +++ b/util/X86MAC64/share/gdb/python/gdb/types.py @@ -0,0 +1,176 @@ +# Type utilities. +# Copyright (C) 2010-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +"""Utilities for working with gdb.Types.""" + +import gdb + + +def get_basic_type(type_): + """Return the "basic" type of a type. + + Arguments: + type_: The type to reduce to its basic type. + + Returns: + type_ with const/volatile is stripped away, + and typedefs/references converted to the underlying type. + """ + + while (type_.code == gdb.TYPE_CODE_REF or + type_.code == gdb.TYPE_CODE_TYPEDEF): + if type_.code == gdb.TYPE_CODE_REF: + type_ = type_.target() + else: + type_ = type_.strip_typedefs() + return type_.unqualified() + + +def has_field(type_, field): + """Return True if a type has the specified field. + + Arguments: + type_: The type to examine. + It must be one of gdb.TYPE_CODE_STRUCT, gdb.TYPE_CODE_UNION. + field: The name of the field to look up. + + Returns: + True if the field is present either in type_ or any baseclass. + + Raises: + TypeError: The type is not a struct or union. + """ + + type_ = get_basic_type(type_) + if (type_.code != gdb.TYPE_CODE_STRUCT and + type_.code != gdb.TYPE_CODE_UNION): + raise TypeError("not a struct or union") + for f in type_.fields(): + if f.is_base_class: + if has_field(f.type, field): + return True + else: + # NOTE: f.name could be None + if f.name == field: + return True + return False + + +def make_enum_dict(enum_type): + """Return a dictionary from a program's enum type. + + Arguments: + enum_type: The enum to compute the dictionary for. + + Returns: + The dictionary of the enum. + + Raises: + TypeError: The type is not an enum. + """ + + if enum_type.code != gdb.TYPE_CODE_ENUM: + raise TypeError("not an enum type") + enum_dict = {} + for field in enum_type.fields(): + # The enum's value is stored in "enumval". + enum_dict[field.name] = field.enumval + return enum_dict + + +def deep_items (type_): + """Return an iterator that recursively traverses anonymous fields. + + Arguments: + type_: The type to traverse. It should be one of + gdb.TYPE_CODE_STRUCT or gdb.TYPE_CODE_UNION. + + Returns: + an iterator similar to gdb.Type.iteritems(), i.e., it returns + pairs of key, value, but for any anonymous struct or union + field that field is traversed recursively, depth-first. + """ + for k, v in type_.iteritems (): + if k: + yield k, v + else: + for i in deep_items (v.type): + yield i + +class TypePrinter(object): + """The base class for type printers. + + Instances of this type can be used to substitute type names during + 'ptype'. + + A type printer must have at least 'name' and 'enabled' attributes, + and supply an 'instantiate' method. + + The 'instantiate' method must either return None, or return an + object which has a 'recognize' method. This method must accept a + gdb.Type argument and either return None, meaning that the type + was not recognized, or a string naming the type. + """ + + def __init__(self, name): + self.name = name + self.enabled = True + + def instantiate(self): + return None + +# Helper function for computing the list of type recognizers. +def _get_some_type_recognizers(result, plist): + for printer in plist: + if printer.enabled: + inst = printer.instantiate() + if inst is not None: + result.append(inst) + return None + +def get_type_recognizers(): + "Return a list of the enabled type recognizers for the current context." + result = [] + + # First try the objfiles. + for objfile in gdb.objfiles(): + _get_some_type_recognizers(result, objfile.type_printers) + # Now try the program space. + _get_some_type_recognizers(result, gdb.current_progspace().type_printers) + # Finally, globals. + _get_some_type_recognizers(result, gdb.type_printers) + + return result + +def apply_type_recognizers(recognizers, type_obj): + """Apply the given list of type recognizers to the type TYPE_OBJ. + If any recognizer in the list recognizes TYPE_OBJ, returns the name + given by the recognizer. Otherwise, this returns None.""" + for r in recognizers: + result = r.recognize(type_obj) + if result is not None: + return result + return None + +def register_type_printer(locus, printer): + """Register a type printer. + PRINTER is the type printer instance. + LOCUS is either an objfile, a program space, or None, indicating + global registration.""" + + if locus is None: + locus = gdb + locus.type_printers.insert(0, printer) diff --git a/util/X86MAC64/share/gdb/python/gdb/types.pyc b/util/X86MAC64/share/gdb/python/gdb/types.pyc new file mode 100644 index 0000000000..3673103159 Binary files /dev/null and b/util/X86MAC64/share/gdb/python/gdb/types.pyc differ diff --git a/util/X86MAC64/share/gdb/syscalls/amd64-linux.xml b/util/X86MAC64/share/gdb/syscalls/amd64-linux.xml new file mode 100644 index 0000000000..6a04218527 --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/amd64-linux.xml @@ -0,0 +1,314 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/X86MAC64/share/gdb/syscalls/arm-linux.xml b/util/X86MAC64/share/gdb/syscalls/arm-linux.xml new file mode 100644 index 0000000000..9d989bd8b1 --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/arm-linux.xml @@ -0,0 +1,398 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/X86MAC64/share/gdb/syscalls/gdb-syscalls.dtd b/util/X86MAC64/share/gdb/syscalls/gdb-syscalls.dtd new file mode 100644 index 0000000000..3ad3625e34 --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/gdb-syscalls.dtd @@ -0,0 +1,14 @@ + + + + + + + + diff --git a/util/X86MAC64/share/gdb/syscalls/i386-linux.xml b/util/X86MAC64/share/gdb/syscalls/i386-linux.xml new file mode 100644 index 0000000000..3d890bddce --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/i386-linux.xml @@ -0,0 +1,340 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/X86MAC64/share/gdb/syscalls/mips-n32-linux.xml b/util/X86MAC64/share/gdb/syscalls/mips-n32-linux.xml new file mode 100644 index 0000000000..5c7a95de7e --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/mips-n32-linux.xml @@ -0,0 +1,319 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/X86MAC64/share/gdb/syscalls/mips-n64-linux.xml b/util/X86MAC64/share/gdb/syscalls/mips-n64-linux.xml new file mode 100644 index 0000000000..0a81573d4c --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/mips-n64-linux.xml @@ -0,0 +1,312 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/X86MAC64/share/gdb/syscalls/mips-o32-linux.xml b/util/X86MAC64/share/gdb/syscalls/mips-o32-linux.xml new file mode 100644 index 0000000000..97641b63ef --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/mips-o32-linux.xml @@ -0,0 +1,347 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/X86MAC64/share/gdb/syscalls/ppc-linux.xml b/util/X86MAC64/share/gdb/syscalls/ppc-linux.xml new file mode 100644 index 0000000000..b25d08c3c4 --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/ppc-linux.xml @@ -0,0 +1,310 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/X86MAC64/share/gdb/syscalls/ppc64-linux.xml b/util/X86MAC64/share/gdb/syscalls/ppc64-linux.xml new file mode 100644 index 0000000000..c31415a2af --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/ppc64-linux.xml @@ -0,0 +1,295 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/X86MAC64/share/gdb/syscalls/sparc-linux.xml b/util/X86MAC64/share/gdb/syscalls/sparc-linux.xml new file mode 100644 index 0000000000..24d8612d13 --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/sparc-linux.xml @@ -0,0 +1,344 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/X86MAC64/share/gdb/syscalls/sparc64-linux.xml b/util/X86MAC64/share/gdb/syscalls/sparc64-linux.xml new file mode 100644 index 0000000000..13c0cb7ab5 --- /dev/null +++ b/util/X86MAC64/share/gdb/syscalls/sparc64-linux.xml @@ -0,0 +1,326 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/X86MAC64/share/gdb/system-gdbinit/elinos.py b/util/X86MAC64/share/gdb/system-gdbinit/elinos.py new file mode 100644 index 0000000000..cd35aed16f --- /dev/null +++ b/util/X86MAC64/share/gdb/system-gdbinit/elinos.py @@ -0,0 +1,91 @@ +# Copyright (C) 2011-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +"""Configure GDB using the ELinOS environment.""" + +import os +import glob +import gdb + + +def warn(msg): + print "warning: %s" % msg + + +def get_elinos_environment(): + """Return the ELinOS environment. + + If the ELinOS environment is properly set up, return a dictionary + which contains: + * The path to the ELinOS project at key 'project'; + * The path to the ELinOS CDK at key 'cdk'; + * The ELinOS target name at key 'target' (Eg. 'i486-linux'); + * A list of Xenomai install prefixes (which could be empty, if + the ELinOS project does not include Xenomai) at key 'xenomai'. + + If one of these cannot be found, print a warning; the corresponding + value in the returned dictionary will be None. + """ + result = {} + for key in ("project", "cdk", "target"): + var = "ELINOS_" + key.upper() + if var in os.environ: + result[key] = os.environ[var] + else: + warn("%s not set" % var) + result[key] = None + + if result["project"] is not None: + result["xenomai"] = glob.glob(result["project"] + "/xenomai-[0-9.]*") + else: + result["xenomai"] = [] + + return result + + +def elinos_init(): + """Initialize debugger environment for ELinOS. + + Let the debugger know where to find the ELinOS libraries on host. This + assumes that an ELinOS environment is properly set up. If some environment + variables are missing, warn about which library may be missing. + """ + elinos_env = get_elinos_environment() + + solib_dirs = [] + + # System libraries + if None in (elinos_env[key] for key in ("cdk", "target")): + warn("ELinOS system libraries will not be loaded") + else: + solib_prefix = "%s/%s" % (elinos_env["cdk"], elinos_env["target"]) + solib_dirs += ["%s/%s" % (solib_prefix, "lib")] + gdb.execute("set solib-absolute-prefix %s" % solib_prefix) + + # Xenomai libraries. Those are optional, so have a lighter warning + # if they cannot be located. + if elinos_env["project"] is None: + warn("Xenomai libraries may not be loaded") + else: + for dir in elinos_env['xenomai']: + solib_dirs += ["%s/%s" + % (dir, "xenomai-build/usr/realtime/lib")] + + if len(solib_dirs) != 0: + gdb.execute("set solib-search-path %s" % ":".join(solib_dirs)) + + +if __name__ == "__main__": + elinos_init() diff --git a/util/X86MAC64/share/gdb/system-gdbinit/wrs-linux.py b/util/X86MAC64/share/gdb/system-gdbinit/wrs-linux.py new file mode 100644 index 0000000000..54ec9ece79 --- /dev/null +++ b/util/X86MAC64/share/gdb/system-gdbinit/wrs-linux.py @@ -0,0 +1,25 @@ +# Copyright (C) 2011-2014 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +"""Configure GDB using the WRS/Linux environment.""" + +import os + +if 'ENV_PREFIX' in os.environ: + gdb.execute('set sysroot %s' % os.environ['ENV_PREFIX']) + +else: + print "warning: ENV_PREFIX environment variable missing." + print "The debugger will probably be unable to find the correct system libraries" diff --git a/util/X86MAC64/share/info/annotate.info b/util/X86MAC64/share/info/annotate.info new file mode 100644 index 0000000000..617a795072 --- /dev/null +++ b/util/X86MAC64/share/info/annotate.info @@ -0,0 +1,1187 @@ +This is annotate.info, produced by makeinfo version 5.1 from +annotate.texinfo. + +Copyright (C) 1994-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Annotate: (annotate). The obsolete annotation interface. +END-INFO-DIR-ENTRY + + This file documents GDB's obsolete annotations. + + Copyright (C) 1994-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". + + +File: annotate.info, Node: Top, Next: Annotations Overview, Up: (dir) + +GDB Annotations +*************** + +This document describes the obsolete level two annotation interface +implemented in older GDB versions. + +* Menu: + +* Annotations Overview:: What annotations are; the general syntax. +* Limitations:: Limitations of the annotation interface. +* Migrating to GDB/MI:: Migrating to GDB/MI +* Server Prefix:: Issuing a command without affecting user state. +* Value Annotations:: Values are marked as such. +* Frame Annotations:: Stack frames are annotated. +* Displays:: GDB can be told to display something periodically. +* Prompting:: Annotations marking GDB's need for input. +* Errors:: Annotations for error messages. +* Breakpoint Info:: Information on breakpoints. +* Invalidation:: Some annotations describe things now invalid. +* Annotations for Running:: + Whether the program is running, how it stopped, etc. +* Source Annotations:: Annotations describing source code. +* Multi-threaded Apps:: An annotation that reports multi-threadedness. + +* GNU Free Documentation License:: + + +File: annotate.info, Node: Annotations Overview, Next: Limitations, Prev: Top, Up: Top + +1 What is an Annotation? +************************ + +To produce obsolete level two annotations, start GDB with the +'--annotate=2' option. + + Annotations start with a newline character, two 'control-z' +characters, and the name of the annotation. If there is no additional +information associated with this annotation, the name of the annotation +is followed immediately by a newline. If there is additional +information, the name of the annotation is followed by a space, the +additional information, and a newline. The additional information +cannot contain newline characters. + + Any output not beginning with a newline and two 'control-z' +characters denotes literal output from GDB. Currently there is no need +for GDB to output a newline followed by two 'control-z' characters, but +if there was such a need, the annotations could be extended with an +'escape' annotation which means those three characters as output. + + A simple example of starting up GDB with annotations is: + + $ gdb --annotate=2 + GNU GDB 5.0 + Copyright 2000 Free Software Foundation, Inc. + GDB is free software, covered by the GNU General Public License, + and you are welcome to change it and/or distribute copies of it + under certain conditions. + Type "show copying" to see the conditions. + There is absolutely no warranty for GDB. Type "show warranty" + for details. + This GDB was configured as "sparc-sun-sunos4.1.3" + + ^Z^Zpre-prompt + (gdb) + ^Z^Zprompt + quit + + ^Z^Zpost-prompt + $ + + Here 'quit' is input to GDB; the rest is output from GDB. The three +lines beginning '^Z^Z' (where '^Z' denotes a 'control-z' character) are +annotations; the rest is output from GDB. + + +File: annotate.info, Node: Limitations, Next: Migrating to GDB/MI, Prev: Annotations Overview, Up: Top + +2 Limitations of the Annotation Interface +***************************************** + +The level two annotations mechanism is known to have a number of +technical and architectural limitations. As a consequence, in 2001, +with the release of GDB 5.1 and the addition of GDB/MI, the annotation +interface was marked as deprecated. + + This chapter discusses the known problems. + +2.1 Dependant on CLI output +=========================== + +The annotation interface works by interspersing markups with GDB normal +command-line interpreter output. Unfortunately, this makes the +annotation client dependant on not just the annotations, but also the +CLI output. This is because the client is forced to assume that +specific GDB commands provide specific information. Any change to GDB's +CLI output modifies or removes that information and, consequently, +likely breaks the client. + + Since the GDB/MI output is independent of the CLI, it does not have +this problem. + +2.2 Scalability +=============== + +The annotation interface relies on value annotations (*note Value +Annotations::) and the display mechanism as a way of obtaining +up-to-date value information. These mechanisms are not scalable. + + In a graphical environment, where many values can be displayed +simultaneously, a serious performance problem occurs when the client +tries to first extract from GDB, and then re-display, all those values. +The client should instead only request and update the values that +changed. + + The GDB/MI Variable Objects provide just that mechanism. + +2.3 Correctness +=============== + +The annotation interface assumes that a variable's value can only be +changed when the target is running. This assumption is not correct. A +single assignment to a single variable can result in the entire target, +and all displayed values, needing an update. + + The GDB/MI Variable Objects include a mechanism for efficiently +reporting such changes. + +2.4 Reliability +=============== + +The GDB/MI interface includes a dedicated test directory ('gdb/gdb.mi'), +and any addition or fix to GDB/MI must include testsuite changes. + +2.5 Maintainability +=================== + +The annotation mechanism was implemented by interspersing CLI print +statements with various annotations. As a consequence, any CLI output +change can alter the annotation output. + + Since the GDB/MI output is independent of the CLI, and the GDB/MI is +increasingly implemented independent of the CLI code, its long term +maintenance is much easier. + + +File: annotate.info, Node: Migrating to GDB/MI, Next: Server Prefix, Prev: Limitations, Up: Top + +3 Migrating to GDB/MI +********************* + +By using the 'interp mi' command, it is possible for annotation clients +to invoke GDB/MI commands, and hence access the GDB/MI. By doing this, +existing annotation clients have a migration path from this obsolete +interface to GDB/MI. + + +File: annotate.info, Node: Server Prefix, Next: Value Annotations, Prev: Migrating to GDB/MI, Up: Top + +4 The Server Prefix +******************* + +To issue a command to GDB without affecting certain aspects of the state +which is seen by users, prefix it with 'server '. This means that this +command will not affect the command history, nor will it affect GDB's +notion of which command to repeat if is pressed on a line by +itself. + + The server prefix does not affect the recording of values into the +value history; to print a value without recording it into the value +history, use the 'output' command instead of the 'print' command. + + +File: annotate.info, Node: Value Annotations, Next: Frame Annotations, Prev: Server Prefix, Up: Top + +5 Values +******** + +_Value Annotations have been removed. GDB/MI instead provides Variable +Objects._ + + When a value is printed in various contexts, GDB uses annotations to +delimit the value from the surrounding text. + + If a value is printed using 'print' and added to the value history, +the annotation looks like + + ^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS + HISTORY-STRING + ^Z^Zvalue-history-value + THE-VALUE + ^Z^Zvalue-history-end + +where HISTORY-NUMBER is the number it is getting in the value history, +HISTORY-STRING is a string, such as '$5 = ', which introduces the value +to the user, THE-VALUE is the output corresponding to the value itself, +and VALUE-FLAGS is '*' for a value which can be dereferenced and '-' for +a value which cannot. + + If the value is not added to the value history (it is an invalid +float or it is printed with the 'output' command), the annotation is +similar: + + ^Z^Zvalue-begin VALUE-FLAGS + THE-VALUE + ^Z^Zvalue-end + + When GDB prints an argument to a function (for example, in the output +from the 'backtrace' command), it annotates it as follows: + + ^Z^Zarg-begin + ARGUMENT-NAME + ^Z^Zarg-name-end + SEPARATOR-STRING + ^Z^Zarg-value VALUE-FLAGS + THE-VALUE + ^Z^Zarg-end + +where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is +text which separates the name from the value for the user's benefit +(such as '='), and VALUE-FLAGS and THE-VALUE have the same meanings as +in a 'value-history-begin' annotation. + + When printing a structure, GDB annotates it as follows: + + ^Z^Zfield-begin VALUE-FLAGS + FIELD-NAME + ^Z^Zfield-name-end + SEPARATOR-STRING + ^Z^Zfield-value + THE-VALUE + ^Z^Zfield-end + +where FIELD-NAME is the name of the field, SEPARATOR-STRING is text +which separates the name from the value for the user's benefit (such as +'='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a +'value-history-begin' annotation. + + When printing an array, GDB annotates it as follows: + + ^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS + +where ARRAY-INDEX is the index of the first element being annotated and +VALUE-FLAGS has the same meaning as in a 'value-history-begin' +annotation. This is followed by any number of elements, where is +element can be either a single element: + + ',' WHITESPACE ; omitted for the first element + THE-VALUE + ^Z^Zelt + + or a repeated element + + ',' WHITESPACE ; omitted for the first element + THE-VALUE + ^Z^Zelt-rep NUMBER-OF-REPETITIONS + REPETITION-STRING + ^Z^Zelt-rep-end + + In both cases, THE-VALUE is the output for the value of the element +and WHITESPACE can contain spaces, tabs, and newlines. In the repeated +case, NUMBER-OF-REPETITIONS is the number of consecutive array elements +which contain that value, and REPETITION-STRING is a string which is +designed to convey to the user that repetition is being depicted. + + Once all the array elements have been output, the array annotation is +ended with + + ^Z^Zarray-section-end + + +File: annotate.info, Node: Frame Annotations, Next: Displays, Prev: Value Annotations, Up: Top + +6 Frames +******** + +_Value Annotations have been removed. GDB/MI instead provides a number +of frame commands._ + + _Frame annotations are no longer available. The GDB/MI provides +'-stack-list-arguments', '-stack-list-locals', and '-stack-list-frames' +commands._ + + Whenever GDB prints a frame, it annotates it. For example, this +applies to frames printed when GDB stops, output from commands such as +'backtrace' or 'up', etc. + + The frame annotation begins with + + ^Z^Zframe-begin LEVEL ADDRESS + LEVEL-STRING + +where LEVEL is the number of the frame (0 is the innermost frame, and +other frames have positive numbers), ADDRESS is the address of the code +executing in that frame, and LEVEL-STRING is a string designed to convey +the level to the user. ADDRESS is in the form '0x' followed by one or +more lowercase hex digits (note that this does not depend on the +language). The frame ends with + + ^Z^Zframe-end + + Between these annotations is the main body of the frame, which can +consist of + + * ^Z^Zfunction-call + FUNCTION-CALL-STRING + + where FUNCTION-CALL-STRING is text designed to convey to the user + that this frame is associated with a function call made by GDB to a + function in the program being debugged. + + * ^Z^Zsignal-handler-caller + SIGNAL-HANDLER-CALLER-STRING + + where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to + the user that this frame is associated with whatever mechanism is + used by this operating system to call a signal handler (it is the + frame which calls the signal handler, not the frame for the signal + handler itself). + + * A normal frame. + + This can optionally (depending on whether this is thought of as + interesting information for the user to see) begin with + + ^Z^Zframe-address + ADDRESS + ^Z^Zframe-address-end + SEPARATOR-STRING + + where ADDRESS is the address executing in the frame (the same + address as in the 'frame-begin' annotation, but printed in a form + which is intended for user consumption--in particular, the syntax + varies depending on the language), and SEPARATOR-STRING is a string + intended to separate this address from what follows for the user's + benefit. + + Then comes + + ^Z^Zframe-function-name + FUNCTION-NAME + ^Z^Zframe-args + ARGUMENTS + + where FUNCTION-NAME is the name of the function executing in the + frame, or '??' if not known, and ARGUMENTS are the arguments to the + frame, with parentheses around them (each argument is annotated + individually as well, *note Value Annotations::). + + If source information is available, a reference to it is then + printed: + + ^Z^Zframe-source-begin + SOURCE-INTRO-STRING + ^Z^Zframe-source-file + FILENAME + ^Z^Zframe-source-file-end + : + ^Z^Zframe-source-line + LINE-NUMBER + ^Z^Zframe-source-end + + where SOURCE-INTRO-STRING separates for the user's benefit the + reference from the text which precedes it, FILENAME is the name of + the source file, and LINE-NUMBER is the line number within that + file (the first line is line 1). + + If GDB prints some information about where the frame is from (which + library, which load segment, etc.; currently only done on the + RS/6000), it is annotated with + + ^Z^Zframe-where + INFORMATION + + Then, if source is to actually be displayed for this frame (for + example, this is not true for output from the 'backtrace' command), + then a 'source' annotation (*note Source Annotations::) is + displayed. Unlike most annotations, this is output instead of the + normal text which would be output, not in addition. + + +File: annotate.info, Node: Displays, Next: Prompting, Prev: Frame Annotations, Up: Top + +7 Displays +********** + +_Display Annotations have been removed. GDB/MI instead provides +Variable Objects._ + + When GDB is told to display something using the 'display' command, +the results of the display are annotated: + + ^Z^Zdisplay-begin + NUMBER + ^Z^Zdisplay-number-end + NUMBER-SEPARATOR + ^Z^Zdisplay-format + FORMAT + ^Z^Zdisplay-expression + EXPRESSION + ^Z^Zdisplay-expression-end + EXPRESSION-SEPARATOR + ^Z^Zdisplay-value + VALUE + ^Z^Zdisplay-end + +where NUMBER is the number of the display, NUMBER-SEPARATOR is intended +to separate the number from what follows for the user, FORMAT includes +information such as the size, format, or other information about how the +value is being displayed, EXPRESSION is the expression being displayed, +EXPRESSION-SEPARATOR is intended to separate the expression from the +text that follows for the user, and VALUE is the actual value being +displayed. + + +File: annotate.info, Node: Prompting, Next: Errors, Prev: Displays, Up: Top + +8 Annotation for GDB Input +************************** + +When GDB prompts for input, it annotates this fact so it is possible to +know when to send output, when the output from a given command is over, +etc. + + Different kinds of input each have a different "input type". Each +input type has three annotations: a 'pre-' annotation, which denotes the +beginning of any prompt which is being output, a plain annotation, which +denotes the end of the prompt, and then a 'post-' annotation which +denotes the end of any echo which may (or may not) be associated with +the input. For example, the 'prompt' input type features the following +annotations: + + ^Z^Zpre-prompt + ^Z^Zprompt + ^Z^Zpost-prompt + + The input types are + +'prompt' + When GDB is prompting for a command (the main GDB prompt). + +'commands' + When GDB prompts for a set of commands, like in the 'commands' + command. The annotations are repeated for each command which is + input. + +'overload-choice' + When GDB wants the user to select between various overloaded + functions. + +'query' + When GDB wants the user to confirm a potentially dangerous + operation. + +'prompt-for-continue' + When GDB is asking the user to press return to continue. Note: + Don't expect this to work well; instead use 'set height 0' to + disable prompting. This is because the counting of lines is buggy + in the presence of annotations. + + +File: annotate.info, Node: Errors, Next: Breakpoint Info, Prev: Prompting, Up: Top + +9 Errors +******** + + ^Z^Zquit + + This annotation occurs right before GDB responds to an interrupt. + + ^Z^Zerror + + This annotation occurs right before GDB responds to an error. + + Quit and error annotations indicate that any annotations which GDB +was in the middle of may end abruptly. For example, if a +'value-history-begin' annotation is followed by a 'error', one cannot +expect to receive the matching 'value-history-end'. One cannot expect +not to receive it either, however; an error annotation does not +necessarily mean that GDB is immediately returning all the way to the +top level. + + A quit or error annotation may be preceded by + + ^Z^Zerror-begin + + Any output between that and the quit or error annotation is the error +message. + + Warning messages are not yet annotated. + + +File: annotate.info, Node: Breakpoint Info, Next: Invalidation, Prev: Errors, Up: Top + +10 Information on Breakpoints +***************************** + +_Breakpoint Annotations have been removed. GDB/MI instead provides +breakpoint commands._ + + The output from the 'info breakpoints' command is annotated as +follows: + + ^Z^Zbreakpoints-headers + HEADER-ENTRY + ^Z^Zbreakpoints-table + +where HEADER-ENTRY has the same syntax as an entry (see below) but +instead of containing data, it contains strings which are intended to +convey the meaning of each field to the user. This is followed by any +number of entries. If a field does not apply for this entry, it is +omitted. Fields may contain trailing whitespace. Each entry consists +of: + + ^Z^Zrecord + ^Z^Zfield 0 + NUMBER + ^Z^Zfield 1 + TYPE + ^Z^Zfield 2 + DISPOSITION + ^Z^Zfield 3 + ENABLE + ^Z^Zfield 4 + ADDRESS + ^Z^Zfield 5 + WHAT + ^Z^Zfield 6 + FRAME + ^Z^Zfield 7 + CONDITION + ^Z^Zfield 8 + IGNORE-COUNT + ^Z^Zfield 9 + COMMANDS + + Note that ADDRESS is intended for user consumption--the syntax varies +depending on the language. + + The output ends with + + ^Z^Zbreakpoints-table-end + + +File: annotate.info, Node: Invalidation, Next: Annotations for Running, Prev: Breakpoint Info, Up: Top + +11 Invalidation Notices +*********************** + +The following annotations say that certain pieces of state may have +changed. + +'^Z^Zframes-invalid' + + The frames (for example, output from the 'backtrace' command) may + have changed. + +'^Z^Zbreakpoints-invalid' + + The breakpoints may have changed. For example, the user just added + or deleted a breakpoint. + + +File: annotate.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Top + +12 Running the Program +********************** + +When the program starts executing due to a GDB command such as 'step' or +'continue', + + ^Z^Zstarting + + is output. When the program stops, + + ^Z^Zstopped + + is output. Before the 'stopped' annotation, a variety of annotations +describe how the program stopped. + +'^Z^Zexited EXIT-STATUS' + The program exited, and EXIT-STATUS is the exit status (zero for + successful exit, otherwise nonzero). + +'^Z^Zsignalled' + The program exited with a signal. After the '^Z^Zsignalled', the + annotation continues: + + INTRO-TEXT + ^Z^Zsignal-name + NAME + ^Z^Zsignal-name-end + MIDDLE-TEXT + ^Z^Zsignal-string + STRING + ^Z^Zsignal-string-end + END-TEXT + + where NAME is the name of the signal, such as 'SIGILL' or + 'SIGSEGV', and STRING is the explanation of the signal, such as + 'Illegal Instruction' or 'Segmentation fault'. INTRO-TEXT, + MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no + particular format. + +'^Z^Zsignal' + The syntax of this annotation is just like 'signalled', but GDB is + just saying that the program received the signal, not that it was + terminated with it. + +'^Z^Zbreakpoint NUMBER' + The program hit breakpoint number NUMBER. + +'^Z^Zwatchpoint NUMBER' + The program hit watchpoint number NUMBER. + + +File: annotate.info, Node: Source Annotations, Next: Multi-threaded Apps, Prev: Annotations for Running, Up: Top + +13 Displaying Source +******************** + +The following annotation is used instead of displaying source code: + + ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR + + where FILENAME is an absolute file name indicating which source file, +LINE is the line number within that file (where 1 is the first line in +the file), CHARACTER is the character position within the file (where 0 +is the first character in the file) (for most debug formats this will +necessarily point to the beginning of a line), MIDDLE is 'middle' if +ADDR is in the middle of the line, or 'beg' if ADDR is at the beginning +of the line, and ADDR is the address in the target program associated +with the source which is being displayed. ADDR is in the form '0x' +followed by one or more lowercase hex digits (note that this does not +depend on the language). + + +File: annotate.info, Node: Multi-threaded Apps, Next: GNU Free Documentation License, Prev: Source Annotations, Up: Top + +14 Multi-threaded Applications +****************************** + +The following annotations report thread related changes of state. + +'^Z^Znew-thread' + + This annotation is issued once for each thread that is created + apart from the main thread, which is not reported. + +'^Z^Zthread-changed' + + The selected thread has changed. This may occur at the request of + the user with the 'thread' command, or as a result of execution, + e.g., another thread hits a breakpoint. + + +File: annotate.info, Node: GNU Free Documentation License, Prev: Multi-threaded Apps, Up: Top + +Appendix A GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + + +Tag Table: +Node: Top1166 +Node: Annotations Overview2336 +Node: Limitations4135 +Node: Migrating to GDB/MI6720 +Node: Server Prefix7103 +Node: Value Annotations7749 +Node: Frame Annotations10919 +Node: Displays14818 +Node: Prompting15849 +Node: Errors17352 +Node: Breakpoint Info18242 +Node: Invalidation19467 +Node: Annotations for Running19948 +Node: Source Annotations21461 +Node: Multi-threaded Apps22407 +Node: GNU Free Documentation License23017 + +End Tag Table diff --git a/util/X86MAC64/share/info/bfd.info b/util/X86MAC64/share/info/bfd.info new file mode 100644 index 0000000000..7d7cb154b7 --- /dev/null +++ b/util/X86MAC64/share/info/bfd.info @@ -0,0 +1,13028 @@ +This is bfd.info, produced by makeinfo version 5.1 from bfd.texinfo. + +This file documents the BFD library. + + Copyright (C) 1991 - 2013 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "GNU General Public License" and "Funding Free +Software", the Front-Cover texts being (a) (see below), and with the +Back-Cover Texts being (b) (see below). A copy of the license is +included in the section entitled "GNU Free Documentation License". + + (a) The FSF's Front-Cover Text is: + + A GNU Manual + + (b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU +software. Copies published by the Free Software Foundation raise funds +for GNU development. +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Bfd: (bfd). The Binary File Descriptor library. +END-INFO-DIR-ENTRY + + +File: bfd.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) + +This file documents the binary file descriptor library libbfd. + +* Menu: + +* Overview:: Overview of BFD +* BFD front end:: BFD front end +* BFD back ends:: BFD back ends +* GNU Free Documentation License:: GNU Free Documentation License +* BFD Index:: BFD Index + + +File: bfd.info, Node: Overview, Next: BFD front end, Prev: Top, Up: Top + +1 Introduction +************** + +BFD is a package which allows applications to use the same routines to +operate on object files whatever the object file format. A new object +file format can be supported simply by creating a new BFD back end and +adding it to the library. + + BFD is split into two parts: the front end, and the back ends (one +for each object file format). + * The front end of BFD provides the interface to the user. It + manages memory and various canonical data structures. The front + end also decides which back end to use and when to call back end + routines. + * The back ends provide BFD its view of the real world. Each back + end provides a set of calls which the BFD front end can use to + maintain its canonical form. The back ends also may keep around + information for their own use, for greater efficiency. +* Menu: + +* History:: History +* How It Works:: How It Works +* What BFD Version 2 Can Do:: What BFD Version 2 Can Do + + +File: bfd.info, Node: History, Next: How It Works, Prev: Overview, Up: Overview + +1.1 History +=========== + +One spur behind BFD was the desire, on the part of the GNU 960 team at +Intel Oregon, for interoperability of applications on their COFF and +b.out file formats. Cygnus was providing GNU support for the team, and +was contracted to provide the required functionality. + + The name came from a conversation David Wallace was having with +Richard Stallman about the library: RMS said that it would be quite +hard--David said "BFD". Stallman was right, but the name stuck. + + At the same time, Ready Systems wanted much the same thing, but for +different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k +coff. + + BFD was first implemented by members of Cygnus Support; Steve +Chamberlain ('sac@cygnus.com'), John Gilmore ('gnu@cygnus.com'), K. +Richard Pixley ('rich@cygnus.com') and David Henkel-Wallace +('gumby@cygnus.com'). + + +File: bfd.info, Node: How It Works, Next: What BFD Version 2 Can Do, Prev: History, Up: Overview + +1.2 How To Use BFD +================== + +To use the library, include 'bfd.h' and link with 'libbfd.a'. + + BFD provides a common interface to the parts of an object file for a +calling application. + + When an application successfully opens a target file (object, +archive, or whatever), a pointer to an internal structure is returned. +This pointer points to a structure called 'bfd', described in 'bfd.h'. +Our convention is to call this pointer a BFD, and instances of it within +code 'abfd'. All operations on the target object file are applied as +methods to the BFD. The mapping is defined within 'bfd.h' in a set of +macros, all beginning with 'bfd_' to reduce namespace pollution. + + For example, this sequence does what you would probably expect: +return the number of sections in an object file attached to a BFD +'abfd'. + + #include "bfd.h" + + unsigned int number_of_sections (abfd) + bfd *abfd; + { + return bfd_count_sections (abfd); + } + + The abstraction used within BFD is that an object file has: + + * a header, + * a number of sections containing raw data (*note Sections::), + * a set of relocations (*note Relocations::), and + * some symbol information (*note Symbols::). +Also, BFDs opened for archives have the additional attribute of an index +and contain subordinate BFDs. This approach is fine for a.out and coff, +but loses efficiency when applied to formats such as S-records and +IEEE-695. + + +File: bfd.info, Node: What BFD Version 2 Can Do, Prev: How It Works, Up: Overview + +1.3 What BFD Version 2 Can Do +============================= + +When an object file is opened, BFD subroutines automatically determine +the format of the input object file. They then build a descriptor in +memory with pointers to routines that will be used to access elements of +the object file's data structures. + + As different information from the object files is required, BFD reads +from different sections of the file and processes them. For example, a +very common operation for the linker is processing symbol tables. Each +BFD back end provides a routine for converting between the object file's +representation of symbols and an internal canonical format. When the +linker asks for the symbol table of an object file, it calls through a +memory pointer to the routine from the relevant BFD back end which reads +and converts the table into a canonical form. The linker then operates +upon the canonical form. When the link is finished and the linker +writes the output file's symbol table, another BFD back end routine is +called to take the newly created symbol table and convert it into the +chosen output format. + +* Menu: + +* BFD information loss:: Information Loss +* Canonical format:: The BFD canonical object-file format + + +File: bfd.info, Node: BFD information loss, Next: Canonical format, Up: What BFD Version 2 Can Do + +1.3.1 Information Loss +---------------------- + +_Information can be lost during output._ The output formats supported +by BFD do not provide identical facilities, and information which can be +described in one form has nowhere to go in another format. One example +of this is alignment information in 'b.out'. There is nowhere in an +'a.out' format file to store alignment information on the contained +data, so when a file is linked from 'b.out' and an 'a.out' image is +produced, alignment information will not propagate to the output file. +(The linker will still use the alignment information internally, so the +link is performed correctly). + + Another example is COFF section names. COFF files may contain an +unlimited number of sections, each one with a textual section name. If +the target of the link is a format which does not have many sections +(e.g., 'a.out') or has sections without names (e.g., the Oasys format), +the link cannot be done simply. You can circumvent this problem by +describing the desired input-to-output section mapping with the linker +command language. + + _Information can be lost during canonicalization._ The BFD internal +canonical form of the external formats is not exhaustive; there are +structures in input formats for which there is no direct representation +internally. This means that the BFD back ends cannot maintain all +possible data richness through the transformation between external to +internal and back to external formats. + + This limitation is only a problem when an application reads one +format and writes another. Each BFD back end is responsible for +maintaining as much data as possible, and the internal BFD canonical +form has structures which are opaque to the BFD core, and exported only +to the back ends. When a file is read in one format, the canonical form +is generated for BFD and the application. At the same time, the back +end saves away any information which may otherwise be lost. If the data +is then written back in the same format, the back end routine will be +able to use the canonical form provided by the BFD core as well as the +information it prepared earlier. Since there is a great deal of +commonality between back ends, there is no information lost when linking +or copying big endian COFF to little endian COFF, or 'a.out' to 'b.out'. +When a mixture of formats is linked, the information is only lost from +the files whose format differs from the destination. + + +File: bfd.info, Node: Canonical format, Prev: BFD information loss, Up: What BFD Version 2 Can Do + +1.3.2 The BFD canonical object-file format +------------------------------------------ + +The greatest potential for loss of information occurs when there is the +least overlap between the information provided by the source format, +that stored by the canonical format, and that needed by the destination +format. A brief description of the canonical form may help you +understand which kinds of data you can count on preserving across +conversions. + +_files_ + Information stored on a per-file basis includes target machine + architecture, particular implementation format type, a demand + pageable bit, and a write protected bit. Information like Unix + magic numbers is not stored here--only the magic numbers' meaning, + so a 'ZMAGIC' file would have both the demand pageable bit and the + write protected text bit set. The byte order of the target is + stored on a per-file basis, so that big- and little-endian object + files may be used with one another. + +_sections_ + Each section in the input file contains the name of the section, + the section's original address in the object file, size and + alignment information, various flags, and pointers into other BFD + data structures. + +_symbols_ + Each symbol contains a pointer to the information for the object + file which originally defined it, its name, its value, and various + flag bits. When a BFD back end reads in a symbol table, it + relocates all symbols to make them relative to the base of the + section where they were defined. Doing this ensures that each + symbol points to its containing section. Each symbol also has a + varying amount of hidden private data for the BFD back end. Since + the symbol points to the original file, the private data format for + that symbol is accessible. 'ld' can operate on a collection of + symbols of wildly different formats without problems. + + Normal global and simple local symbols are maintained on output, so + an output file (no matter its format) will retain symbols pointing + to functions and to global, static, and common variables. Some + symbol information is not worth retaining; in 'a.out', type + information is stored in the symbol table as long symbol names. + This information would be useless to most COFF debuggers; the + linker has command line switches to allow users to throw it away. + + There is one word of type information within the symbol, so if the + format supports symbol type information within symbols (for + example, COFF, IEEE, Oasys) and the type is simple enough to fit + within one word (nearly everything but aggregates), the information + will be preserved. + +_relocation level_ + Each canonical BFD relocation record contains a pointer to the + symbol to relocate to, the offset of the data to relocate, the + section the data is in, and a pointer to a relocation type + descriptor. Relocation is performed by passing messages through + the relocation type descriptor and the symbol pointer. Therefore, + relocations can be performed on output data using a relocation + method that is only available in one of the input formats. For + instance, Oasys provides a byte relocation format. A relocation + record requesting this relocation type would point indirectly to a + routine to perform this, so the relocation may be performed on a + byte being written to a 68k COFF file, even though 68k COFF has no + such relocation type. + +_line numbers_ + Object formats can contain, for debugging purposes, some form of + mapping between symbols, source line numbers, and addresses in the + output file. These addresses have to be relocated along with the + symbol information. Each symbol with an associated list of line + number records points to the first record of the list. The head of + a line number list consists of a pointer to the symbol, which + allows finding out the address of the function whose line number is + being described. The rest of the list is made up of pairs: offsets + into the section and line numbers. Any format which can simply + derive this information can pass it successfully between formats + (COFF, IEEE and Oasys). + + +File: bfd.info, Node: BFD front end, Next: BFD back ends, Prev: Overview, Up: Top + +2 BFD Front End +*************** + +* Menu: + +* typedef bfd:: +* Error reporting:: +* Miscellaneous:: +* Memory Usage:: +* Initialization:: +* Sections:: +* Symbols:: +* Archives:: +* Formats:: +* Relocations:: +* Core Files:: +* Targets:: +* Architectures:: +* Opening and Closing:: +* Internal:: +* File Caching:: +* Linker Functions:: +* Hash Tables:: + + +File: bfd.info, Node: typedef bfd, Next: Error reporting, Prev: BFD front end, Up: BFD front end + +2.1 'typedef bfd' +================= + +A BFD has type 'bfd'; objects of this type are the cornerstone of any +application using BFD. Using BFD consists of making references though +the BFD and to data in the BFD. + + Here is the structure that defines the type 'bfd'. It contains the +major data about the file and pointers to the rest of the data. + + + enum bfd_direction + { + no_direction = 0, + read_direction = 1, + write_direction = 2, + both_direction = 3 + }; + + struct bfd + { + /* A unique identifier of the BFD */ + unsigned int id; + + /* The filename the application opened the BFD with. */ + const char *filename; + + /* A pointer to the target jump table. */ + const struct bfd_target *xvec; + + /* The IOSTREAM, and corresponding IO vector that provide access + to the file backing the BFD. */ + void *iostream; + const struct bfd_iovec *iovec; + + /* The caching routines use these to maintain a + least-recently-used list of BFDs. */ + struct bfd *lru_prev, *lru_next; + + /* When a file is closed by the caching routines, BFD retains + state information on the file here... */ + ufile_ptr where; + + /* File modified time, if mtime_set is TRUE. */ + long mtime; + + /* Reserved for an unimplemented file locking extension. */ + int ifd; + + /* The format which belongs to the BFD. (object, core, etc.) */ + bfd_format format; + + /* The direction with which the BFD was opened. */ + enum bfd_direction direction; + + /* Format_specific flags. */ + flagword flags; + + /* Values that may appear in the flags field of a BFD. These also + appear in the object_flags field of the bfd_target structure, where + they indicate the set of flags used by that backend (not all flags + are meaningful for all object file formats) (FIXME: at the moment, + the object_flags values have mostly just been copied from backend + to another, and are not necessarily correct). */ + + #define BFD_NO_FLAGS 0x00 + + /* BFD contains relocation entries. */ + #define HAS_RELOC 0x01 + + /* BFD is directly executable. */ + #define EXEC_P 0x02 + + /* BFD has line number information (basically used for F_LNNO in a + COFF header). */ + #define HAS_LINENO 0x04 + + /* BFD has debugging information. */ + #define HAS_DEBUG 0x08 + + /* BFD has symbols. */ + #define HAS_SYMS 0x10 + + /* BFD has local symbols (basically used for F_LSYMS in a COFF + header). */ + #define HAS_LOCALS 0x20 + + /* BFD is a dynamic object. */ + #define DYNAMIC 0x40 + + /* Text section is write protected (if D_PAGED is not set, this is + like an a.out NMAGIC file) (the linker sets this by default, but + clears it for -r or -N). */ + #define WP_TEXT 0x80 + + /* BFD is dynamically paged (this is like an a.out ZMAGIC file) (the + linker sets this by default, but clears it for -r or -n or -N). */ + #define D_PAGED 0x100 + + /* BFD is relaxable (this means that bfd_relax_section may be able to + do something) (sometimes bfd_relax_section can do something even if + this is not set). */ + #define BFD_IS_RELAXABLE 0x200 + + /* This may be set before writing out a BFD to request using a + traditional format. For example, this is used to request that when + writing out an a.out object the symbols not be hashed to eliminate + duplicates. */ + #define BFD_TRADITIONAL_FORMAT 0x400 + + /* This flag indicates that the BFD contents are actually cached + in memory. If this is set, iostream points to a bfd_in_memory + struct. */ + #define BFD_IN_MEMORY 0x800 + + /* The sections in this BFD specify a memory page. */ + #define HAS_LOAD_PAGE 0x1000 + + /* This BFD has been created by the linker and doesn't correspond + to any input file. */ + #define BFD_LINKER_CREATED 0x2000 + + /* This may be set before writing out a BFD to request that it + be written using values for UIDs, GIDs, timestamps, etc. that + will be consistent from run to run. */ + #define BFD_DETERMINISTIC_OUTPUT 0x4000 + + /* Compress sections in this BFD. */ + #define BFD_COMPRESS 0x8000 + + /* Decompress sections in this BFD. */ + #define BFD_DECOMPRESS 0x10000 + + /* BFD is a dummy, for plugins. */ + #define BFD_PLUGIN 0x20000 + + /* Flags bits to be saved in bfd_preserve_save. */ + #define BFD_FLAGS_SAVED \ + (BFD_IN_MEMORY | BFD_COMPRESS | BFD_DECOMPRESS | BFD_PLUGIN) + + /* Flags bits which are for BFD use only. */ + #define BFD_FLAGS_FOR_BFD_USE_MASK \ + (BFD_IN_MEMORY | BFD_COMPRESS | BFD_DECOMPRESS | BFD_LINKER_CREATED \ + | BFD_PLUGIN | BFD_TRADITIONAL_FORMAT | BFD_DETERMINISTIC_OUTPUT) + + /* Currently my_archive is tested before adding origin to + anything. I believe that this can become always an add of + origin, with origin set to 0 for non archive files. */ + ufile_ptr origin; + + /* The origin in the archive of the proxy entry. This will + normally be the same as origin, except for thin archives, + when it will contain the current offset of the proxy in the + thin archive rather than the offset of the bfd in its actual + container. */ + ufile_ptr proxy_origin; + + /* A hash table for section names. */ + struct bfd_hash_table section_htab; + + /* Pointer to linked list of sections. */ + struct bfd_section *sections; + + /* The last section on the section list. */ + struct bfd_section *section_last; + + /* The number of sections. */ + unsigned int section_count; + + /* Stuff only useful for object files: + The start address. */ + bfd_vma start_address; + + /* Used for input and output. */ + unsigned int symcount; + + /* Symbol table for output BFD (with symcount entries). + Also used by the linker to cache input BFD symbols. */ + struct bfd_symbol **outsymbols; + + /* Used for slurped dynamic symbol tables. */ + unsigned int dynsymcount; + + /* Pointer to structure which contains architecture information. */ + const struct bfd_arch_info *arch_info; + + /* Stuff only useful for archives. */ + void *arelt_data; + struct bfd *my_archive; /* The containing archive BFD. */ + struct bfd *archive_next; /* The next BFD in the archive. */ + struct bfd *archive_head; /* The first BFD in the archive. */ + struct bfd *nested_archives; /* List of nested archive in a flattened + thin archive. */ + + /* A chain of BFD structures involved in a link. */ + struct bfd *link_next; + + /* A field used by _bfd_generic_link_add_archive_symbols. This will + be used only for archive elements. */ + int archive_pass; + + /* Used by the back end to hold private data. */ + union + { + struct aout_data_struct *aout_data; + struct artdata *aout_ar_data; + struct _oasys_data *oasys_obj_data; + struct _oasys_ar_data *oasys_ar_data; + struct coff_tdata *coff_obj_data; + struct pe_tdata *pe_obj_data; + struct xcoff_tdata *xcoff_obj_data; + struct ecoff_tdata *ecoff_obj_data; + struct ieee_data_struct *ieee_data; + struct ieee_ar_data_struct *ieee_ar_data; + struct srec_data_struct *srec_data; + struct verilog_data_struct *verilog_data; + struct ihex_data_struct *ihex_data; + struct tekhex_data_struct *tekhex_data; + struct elf_obj_tdata *elf_obj_data; + struct nlm_obj_tdata *nlm_obj_data; + struct bout_data_struct *bout_data; + struct mmo_data_struct *mmo_data; + struct sun_core_struct *sun_core_data; + struct sco5_core_struct *sco5_core_data; + struct trad_core_struct *trad_core_data; + struct som_data_struct *som_data; + struct hpux_core_struct *hpux_core_data; + struct hppabsd_core_struct *hppabsd_core_data; + struct sgi_core_struct *sgi_core_data; + struct lynx_core_struct *lynx_core_data; + struct osf_core_struct *osf_core_data; + struct cisco_core_struct *cisco_core_data; + struct versados_data_struct *versados_data; + struct netbsd_core_struct *netbsd_core_data; + struct mach_o_data_struct *mach_o_data; + struct mach_o_fat_data_struct *mach_o_fat_data; + struct plugin_data_struct *plugin_data; + struct bfd_pef_data_struct *pef_data; + struct bfd_pef_xlib_data_struct *pef_xlib_data; + struct bfd_sym_data_struct *sym_data; + void *any; + } + tdata; + + /* Used by the application to hold private data. */ + void *usrdata; + + /* Where all the allocated stuff under this BFD goes. This is a + struct objalloc *, but we use void * to avoid requiring the inclusion + of objalloc.h. */ + void *memory; + + /* Is the file descriptor being cached? That is, can it be closed as + needed, and re-opened when accessed later? */ + unsigned int cacheable : 1; + + /* Marks whether there was a default target specified when the + BFD was opened. This is used to select which matching algorithm + to use to choose the back end. */ + unsigned int target_defaulted : 1; + + /* ... and here: (``once'' means at least once). */ + unsigned int opened_once : 1; + + /* Set if we have a locally maintained mtime value, rather than + getting it from the file each time. */ + unsigned int mtime_set : 1; + + /* Flag set if symbols from this BFD should not be exported. */ + unsigned int no_export : 1; + + /* Remember when output has begun, to stop strange things + from happening. */ + unsigned int output_has_begun : 1; + + /* Have archive map. */ + unsigned int has_armap : 1; + + /* Set if this is a thin archive. */ + unsigned int is_thin_archive : 1; + + /* Set if only required symbols should be added in the link hash table for + this object. Used by VMS linkers. */ + unsigned int selective_search : 1; + }; + + /* See note beside bfd_set_section_userdata. */ + static inline bfd_boolean + bfd_set_cacheable (bfd * abfd, bfd_boolean val) + { + abfd->cacheable = val; + return TRUE; + } + + +File: bfd.info, Node: Error reporting, Next: Miscellaneous, Prev: typedef bfd, Up: BFD front end + +2.2 Error reporting +=================== + +Most BFD functions return nonzero on success (check their individual +documentation for precise semantics). On an error, they call +'bfd_set_error' to set an error condition that callers can check by +calling 'bfd_get_error'. If that returns 'bfd_error_system_call', then +check 'errno'. + + The easiest way to report a BFD error to the user is to use +'bfd_perror'. + +2.2.1 Type 'bfd_error_type' +--------------------------- + +The values returned by 'bfd_get_error' are defined by the enumerated +type 'bfd_error_type'. + + + typedef enum bfd_error + { + bfd_error_no_error = 0, + bfd_error_system_call, + bfd_error_invalid_target, + bfd_error_wrong_format, + bfd_error_wrong_object_format, + bfd_error_invalid_operation, + bfd_error_no_memory, + bfd_error_no_symbols, + bfd_error_no_armap, + bfd_error_no_more_archived_files, + bfd_error_malformed_archive, + bfd_error_missing_dso, + bfd_error_file_not_recognized, + bfd_error_file_ambiguously_recognized, + bfd_error_no_contents, + bfd_error_nonrepresentable_section, + bfd_error_no_debug_section, + bfd_error_bad_value, + bfd_error_file_truncated, + bfd_error_file_too_big, + bfd_error_on_input, + bfd_error_invalid_error_code + } + bfd_error_type; + +2.2.1.1 'bfd_get_error' +....................... + +*Synopsis* + bfd_error_type bfd_get_error (void); + *Description* +Return the current BFD error condition. + +2.2.1.2 'bfd_set_error' +....................... + +*Synopsis* + void bfd_set_error (bfd_error_type error_tag, ...); + *Description* +Set the BFD error condition to be ERROR_TAG. If ERROR_TAG is +bfd_error_on_input, then this function takes two more parameters, the +input bfd where the error occurred, and the bfd_error_type error. + +2.2.1.3 'bfd_errmsg' +.................... + +*Synopsis* + const char *bfd_errmsg (bfd_error_type error_tag); + *Description* +Return a string describing the error ERROR_TAG, or the system error if +ERROR_TAG is 'bfd_error_system_call'. + +2.2.1.4 'bfd_perror' +.................... + +*Synopsis* + void bfd_perror (const char *message); + *Description* +Print to the standard error stream a string describing the last BFD +error that occurred, or the last system error if the last BFD error was +a system call failure. If MESSAGE is non-NULL and non-empty, the error +string printed is preceded by MESSAGE, a colon, and a space. It is +followed by a newline. + +2.2.2 BFD error handler +----------------------- + +Some BFD functions want to print messages describing the problem. They +call a BFD error handler function. This function may be overridden by +the program. + + The BFD error handler acts like printf. + + + typedef void (*bfd_error_handler_type) (const char *, ...); + +2.2.2.1 'bfd_set_error_handler' +............................... + +*Synopsis* + bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type); + *Description* +Set the BFD error handler function. Returns the previous function. + +2.2.2.2 'bfd_set_error_program_name' +.................................... + +*Synopsis* + void bfd_set_error_program_name (const char *); + *Description* +Set the program name to use when printing a BFD error. This is printed +before the error message followed by a colon and space. The string must +not be changed after it is passed to this function. + +2.2.2.3 'bfd_get_error_handler' +............................... + +*Synopsis* + bfd_error_handler_type bfd_get_error_handler (void); + *Description* +Return the BFD error handler function. + +2.2.3 BFD assert handler +------------------------ + +If BFD finds an internal inconsistency, the bfd assert handler is called +with information on the BFD version, BFD source file and line. If this +happens, most programs linked against BFD are expected to want to exit +with an error, or mark the current BFD operation as failed, so it is +recommended to override the default handler, which just calls +_bfd_error_handler and continues. + + + typedef void (*bfd_assert_handler_type) (const char *bfd_formatmsg, + const char *bfd_version, + const char *bfd_file, + int bfd_line); + +2.2.3.1 'bfd_set_assert_handler' +................................ + +*Synopsis* + bfd_assert_handler_type bfd_set_assert_handler (bfd_assert_handler_type); + *Description* +Set the BFD assert handler function. Returns the previous function. + +2.2.3.2 'bfd_get_assert_handler' +................................ + +*Synopsis* + bfd_assert_handler_type bfd_get_assert_handler (void); + *Description* +Return the BFD assert handler function. + + +File: bfd.info, Node: Miscellaneous, Next: Memory Usage, Prev: Error reporting, Up: BFD front end + +2.3 Miscellaneous +================= + +2.3.1 Miscellaneous functions +----------------------------- + +2.3.1.1 'bfd_get_reloc_upper_bound' +................................... + +*Synopsis* + long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect); + *Description* +Return the number of bytes required to store the relocation information +associated with section SECT attached to bfd ABFD. If an error occurs, +return -1. + +2.3.1.2 'bfd_canonicalize_reloc' +................................ + +*Synopsis* + long bfd_canonicalize_reloc + (bfd *abfd, asection *sec, arelent **loc, asymbol **syms); + *Description* +Call the back end associated with the open BFD ABFD and translate the +external form of the relocation information attached to SEC into the +internal canonical form. Place the table into memory at LOC, which has +been preallocated, usually by a call to 'bfd_get_reloc_upper_bound'. +Returns the number of relocs, or -1 on error. + + The SYMS table is also needed for horrible internal magic reasons. + +2.3.1.3 'bfd_set_reloc' +....................... + +*Synopsis* + void bfd_set_reloc + (bfd *abfd, asection *sec, arelent **rel, unsigned int count); + *Description* +Set the relocation pointer and count within section SEC to the values +REL and COUNT. The argument ABFD is ignored. + +2.3.1.4 'bfd_set_file_flags' +............................ + +*Synopsis* + bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags); + *Description* +Set the flag word in the BFD ABFD to the value FLAGS. + + Possible errors are: + + * 'bfd_error_wrong_format' - The target bfd was not of object format. + * 'bfd_error_invalid_operation' - The target bfd was open for + reading. + * 'bfd_error_invalid_operation' - The flag word contained a bit which + was not applicable to the type of file. E.g., an attempt was made + to set the 'D_PAGED' bit on a BFD format which does not support + demand paging. + +2.3.1.5 'bfd_get_arch_size' +........................... + +*Synopsis* + int bfd_get_arch_size (bfd *abfd); + *Description* +Returns the architecture address size, in bits, as determined by the +object file's format. For ELF, this information is included in the +header. + + *Returns* +Returns the arch size in bits if known, '-1' otherwise. + +2.3.1.6 'bfd_get_sign_extend_vma' +................................. + +*Synopsis* + int bfd_get_sign_extend_vma (bfd *abfd); + *Description* +Indicates if the target architecture "naturally" sign extends an +address. Some architectures implicitly sign extend address values when +they are converted to types larger than the size of an address. For +instance, bfd_get_start_address() will return an address sign extended +to fill a bfd_vma when this is the case. + + *Returns* +Returns '1' if the target architecture is known to sign extend +addresses, '0' if the target architecture is known to not sign extend +addresses, and '-1' otherwise. + +2.3.1.7 'bfd_set_start_address' +............................... + +*Synopsis* + bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma); + *Description* +Make VMA the entry point of output BFD ABFD. + + *Returns* +Returns 'TRUE' on success, 'FALSE' otherwise. + +2.3.1.8 'bfd_get_gp_size' +......................... + +*Synopsis* + unsigned int bfd_get_gp_size (bfd *abfd); + *Description* +Return the maximum size of objects to be optimized using the GP register +under MIPS ECOFF. This is typically set by the '-G' argument to the +compiler, assembler or linker. + +2.3.1.9 'bfd_set_gp_size' +......................... + +*Synopsis* + void bfd_set_gp_size (bfd *abfd, unsigned int i); + *Description* +Set the maximum size of objects to be optimized using the GP register +under ECOFF or MIPS ELF. This is typically set by the '-G' argument to +the compiler, assembler or linker. + +2.3.1.10 'bfd_scan_vma' +....................... + +*Synopsis* + bfd_vma bfd_scan_vma (const char *string, const char **end, int base); + *Description* +Convert, like 'strtoul', a numerical expression STRING into a 'bfd_vma' +integer, and return that integer. (Though without as many bells and +whistles as 'strtoul'.) The expression is assumed to be unsigned (i.e., +positive). If given a BASE, it is used as the base for conversion. A +base of 0 causes the function to interpret the string in hex if a +leading "0x" or "0X" is found, otherwise in octal if a leading zero is +found, otherwise in decimal. + + If the value would overflow, the maximum 'bfd_vma' value is returned. + +2.3.1.11 'bfd_copy_private_header_data' +....................................... + +*Synopsis* + bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd); + *Description* +Copy private BFD header information from the BFD IBFD to the the BFD +OBFD. This copies information that may require sections to exist, but +does not require symbol tables. Return 'true' on success, 'false' on +error. Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create private + data for OBFD. + #define bfd_copy_private_header_data(ibfd, obfd) \ + BFD_SEND (obfd, _bfd_copy_private_header_data, \ + (ibfd, obfd)) + +2.3.1.12 'bfd_copy_private_bfd_data' +.................................... + +*Synopsis* + bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd); + *Description* +Copy private BFD information from the BFD IBFD to the the BFD OBFD. +Return 'TRUE' on success, 'FALSE' on error. Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create private + data for OBFD. + #define bfd_copy_private_bfd_data(ibfd, obfd) \ + BFD_SEND (obfd, _bfd_copy_private_bfd_data, \ + (ibfd, obfd)) + +2.3.1.13 'bfd_merge_private_bfd_data' +..................................... + +*Synopsis* + bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd); + *Description* +Merge private BFD information from the BFD IBFD to the the output file +BFD OBFD when linking. Return 'TRUE' on success, 'FALSE' on error. +Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create private + data for OBFD. + #define bfd_merge_private_bfd_data(ibfd, obfd) \ + BFD_SEND (obfd, _bfd_merge_private_bfd_data, \ + (ibfd, obfd)) + +2.3.1.14 'bfd_set_private_flags' +................................ + +*Synopsis* + bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags); + *Description* +Set private BFD flag information in the BFD ABFD. Return 'TRUE' on +success, 'FALSE' on error. Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create private + data for OBFD. + #define bfd_set_private_flags(abfd, flags) \ + BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags)) + +2.3.1.15 'Other functions' +.......................... + +*Description* +The following functions exist but have not yet been documented. + #define bfd_sizeof_headers(abfd, info) \ + BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info)) + + #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \ + BFD_SEND (abfd, _bfd_find_nearest_line, \ + (abfd, sec, syms, off, file, func, line)) + + #define bfd_find_nearest_line_discriminator(abfd, sec, syms, off, file, func, \ + line, disc) \ + BFD_SEND (abfd, _bfd_find_nearest_line_discriminator, \ + (abfd, sec, syms, off, file, func, line, disc)) + + #define bfd_find_line(abfd, syms, sym, file, line) \ + BFD_SEND (abfd, _bfd_find_line, \ + (abfd, syms, sym, file, line)) + + #define bfd_find_inliner_info(abfd, file, func, line) \ + BFD_SEND (abfd, _bfd_find_inliner_info, \ + (abfd, file, func, line)) + + #define bfd_debug_info_start(abfd) \ + BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) + + #define bfd_debug_info_end(abfd) \ + BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) + + #define bfd_debug_info_accumulate(abfd, section) \ + BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) + + #define bfd_stat_arch_elt(abfd, stat) \ + BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat)) + + #define bfd_update_armap_timestamp(abfd) \ + BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd)) + + #define bfd_set_arch_mach(abfd, arch, mach)\ + BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) + + #define bfd_relax_section(abfd, section, link_info, again) \ + BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again)) + + #define bfd_gc_sections(abfd, link_info) \ + BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info)) + + #define bfd_lookup_section_flags(link_info, flag_info, section) \ + BFD_SEND (abfd, _bfd_lookup_section_flags, (link_info, flag_info, section)) + + #define bfd_merge_sections(abfd, link_info) \ + BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info)) + + #define bfd_is_group_section(abfd, sec) \ + BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec)) + + #define bfd_discard_group(abfd, sec) \ + BFD_SEND (abfd, _bfd_discard_group, (abfd, sec)) + + #define bfd_link_hash_table_create(abfd) \ + BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd)) + + #define bfd_link_hash_table_free(abfd, hash) \ + BFD_SEND (abfd, _bfd_link_hash_table_free, (hash)) + + #define bfd_link_add_symbols(abfd, info) \ + BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info)) + + #define bfd_link_just_syms(abfd, sec, info) \ + BFD_SEND (abfd, _bfd_link_just_syms, (sec, info)) + + #define bfd_final_link(abfd, info) \ + BFD_SEND (abfd, _bfd_final_link, (abfd, info)) + + #define bfd_free_cached_info(abfd) \ + BFD_SEND (abfd, _bfd_free_cached_info, (abfd)) + + #define bfd_get_dynamic_symtab_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd)) + + #define bfd_print_private_bfd_data(abfd, file)\ + BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file)) + + #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \ + BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols)) + + #define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \ + BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \ + dyncount, dynsyms, ret)) + + #define bfd_get_dynamic_reloc_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd)) + + #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \ + BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms)) + + extern bfd_byte *bfd_get_relocated_section_contents + (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *, + bfd_boolean, asymbol **); + +2.3.1.16 'bfd_alt_mach_code' +............................ + +*Synopsis* + bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative); + *Description* +When more than one machine code number is available for the same machine +type, this function can be used to switch between the preferred one +(alternative == 0) and any others. Currently, only ELF supports this +feature, with up to two alternate machine codes. + +2.3.1.17 'bfd_emul_get_maxpagesize' +................................... + +*Synopsis* + bfd_vma bfd_emul_get_maxpagesize (const char *); + *Description* +Returns the maximum page size, in bytes, as determined by emulation. + + *Returns* +Returns the maximum page size in bytes for ELF, 0 otherwise. + +2.3.1.18 'bfd_emul_set_maxpagesize' +................................... + +*Synopsis* + void bfd_emul_set_maxpagesize (const char *, bfd_vma); + *Description* +For ELF, set the maximum page size for the emulation. It is a no-op for +other formats. + +2.3.1.19 'bfd_emul_get_commonpagesize' +...................................... + +*Synopsis* + bfd_vma bfd_emul_get_commonpagesize (const char *); + *Description* +Returns the common page size, in bytes, as determined by emulation. + + *Returns* +Returns the common page size in bytes for ELF, 0 otherwise. + +2.3.1.20 'bfd_emul_set_commonpagesize' +...................................... + +*Synopsis* + void bfd_emul_set_commonpagesize (const char *, bfd_vma); + *Description* +For ELF, set the common page size for the emulation. It is a no-op for +other formats. + +2.3.1.21 'bfd_demangle' +....................... + +*Synopsis* + char *bfd_demangle (bfd *, const char *, int); + *Description* +Wrapper around cplus_demangle. Strips leading underscores and other +such chars that would otherwise confuse the demangler. If passed a g++ +v3 ABI mangled name, returns a buffer allocated with malloc holding the +demangled name. Returns NULL otherwise and on memory alloc failure. + +2.3.1.22 'struct bfd_iovec' +........................... + +*Description* +The 'struct bfd_iovec' contains the internal file I/O class. Each 'BFD' +has an instance of this class and all file I/O is routed through it (it +is assumed that the instance implements all methods listed below). + struct bfd_iovec + { + /* To avoid problems with macros, a "b" rather than "f" + prefix is prepended to each method name. */ + /* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching + bytes starting at PTR. Return the number of bytes actually + transfered (a read past end-of-file returns less than NBYTES), + or -1 (setting bfd_error) if an error occurs. */ + file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes); + file_ptr (*bwrite) (struct bfd *abfd, const void *ptr, + file_ptr nbytes); + /* Return the current IOSTREAM file offset, or -1 (setting bfd_error + if an error occurs. */ + file_ptr (*btell) (struct bfd *abfd); + /* For the following, on successful completion a value of 0 is returned. + Otherwise, a value of -1 is returned (and bfd_error is set). */ + int (*bseek) (struct bfd *abfd, file_ptr offset, int whence); + int (*bclose) (struct bfd *abfd); + int (*bflush) (struct bfd *abfd); + int (*bstat) (struct bfd *abfd, struct stat *sb); + /* Mmap a part of the files. ADDR, LEN, PROT, FLAGS and OFFSET are the usual + mmap parameter, except that LEN and OFFSET do not need to be page + aligned. Returns (void *)-1 on failure, mmapped address on success. + Also write in MAP_ADDR the address of the page aligned buffer and in + MAP_LEN the size mapped (a page multiple). Use unmap with MAP_ADDR and + MAP_LEN to unmap. */ + void *(*bmmap) (struct bfd *abfd, void *addr, bfd_size_type len, + int prot, int flags, file_ptr offset, + void **map_addr, bfd_size_type *map_len); + }; + extern const struct bfd_iovec _bfd_memory_iovec; + +2.3.1.23 'bfd_get_mtime' +........................ + +*Synopsis* + long bfd_get_mtime (bfd *abfd); + *Description* +Return the file modification time (as read from the file system, or from +the archive header for archive members). + +2.3.1.24 'bfd_get_size' +....................... + +*Synopsis* + file_ptr bfd_get_size (bfd *abfd); + *Description* +Return the file size (as read from file system) for the file associated +with BFD ABFD. + + The initial motivation for, and use of, this routine is not so we can +get the exact size of the object the BFD applies to, since that might +not be generally possible (archive members for example). It would be +ideal if someone could eventually modify it so that such results were +guaranteed. + + Instead, we want to ask questions like "is this NNN byte sized object +I'm about to try read from file offset YYY reasonable?" As as example +of where we might do this, some object formats use string tables for +which the first 'sizeof (long)' bytes of the table contain the size of +the table itself, including the size bytes. If an application tries to +read what it thinks is one of these string tables, without some way to +validate the size, and for some reason the size is wrong (byte swapping +error, wrong location for the string table, etc.), the only clue is +likely to be a read error when it tries to read the table, or a "virtual +memory exhausted" error when it tries to allocate 15 bazillon bytes of +space for the 15 bazillon byte table it is about to read. This function +at least allows us to answer the question, "is the size reasonable?". + +2.3.1.25 'bfd_mmap' +................... + +*Synopsis* + void *bfd_mmap (bfd *abfd, void *addr, bfd_size_type len, + int prot, int flags, file_ptr offset, + void **map_addr, bfd_size_type *map_len); + *Description* +Return mmap()ed region of the file, if possible and implemented. LEN +and OFFSET do not need to be page aligned. The page aligned address and +length are written to MAP_ADDR and MAP_LEN. + + +File: bfd.info, Node: Memory Usage, Next: Initialization, Prev: Miscellaneous, Up: BFD front end + +2.4 Memory Usage +================ + +BFD keeps all of its internal structures in obstacks. There is one +obstack per open BFD file, into which the current state is stored. When +a BFD is closed, the obstack is deleted, and so everything which has +been allocated by BFD for the closing file is thrown away. + + BFD does not free anything created by an application, but pointers +into 'bfd' structures become invalid on a 'bfd_close'; for example, +after a 'bfd_close' the vector passed to 'bfd_canonicalize_symtab' is +still around, since it has been allocated by the application, but the +data that it pointed to are lost. + + The general rule is to not close a BFD until all operations dependent +upon data from the BFD have been completed, or all the data from within +the file has been copied. To help with the management of memory, there +is a function ('bfd_alloc_size') which returns the number of bytes in +obstacks associated with the supplied BFD. This could be used to select +the greediest open BFD, close it to reclaim the memory, perform some +operation and reopen the BFD again, to get a fresh copy of the data +structures. + + +File: bfd.info, Node: Initialization, Next: Sections, Prev: Memory Usage, Up: BFD front end + +2.5 Initialization +================== + +2.5.1 Initialization functions +------------------------------ + +These are the functions that handle initializing a BFD. + +2.5.1.1 'bfd_init' +.................. + +*Synopsis* + void bfd_init (void); + *Description* +This routine must be called before any other BFD function to initialize +magical internal data structures. + + +File: bfd.info, Node: Sections, Next: Symbols, Prev: Initialization, Up: BFD front end + +2.6 Sections +============ + +The raw data contained within a BFD is maintained through the section +abstraction. A single BFD may have any number of sections. It keeps +hold of them by pointing to the first; each one points to the next in +the list. + + Sections are supported in BFD in 'section.c'. + +* Menu: + +* Section Input:: +* Section Output:: +* typedef asection:: +* section prototypes:: + + +File: bfd.info, Node: Section Input, Next: Section Output, Prev: Sections, Up: Sections + +2.6.1 Section input +------------------- + +When a BFD is opened for reading, the section structures are created and +attached to the BFD. + + Each section has a name which describes the section in the outside +world--for example, 'a.out' would contain at least three sections, +called '.text', '.data' and '.bss'. + + Names need not be unique; for example a COFF file may have several +sections named '.data'. + + Sometimes a BFD will contain more than the "natural" number of +sections. A back end may attach other sections containing constructor +data, or an application may add a section (using 'bfd_make_section') to +the sections attached to an already open BFD. For example, the linker +creates an extra section 'COMMON' for each input file's BFD to hold +information about common storage. + + The raw data is not necessarily read in when the section descriptor +is created. Some targets may leave the data in place until a +'bfd_get_section_contents' call is made. Other back ends may read in +all the data at once. For example, an S-record file has to be read once +to determine the size of the data. An IEEE-695 file doesn't contain raw +data in sections, but data and relocation expressions intermixed, so the +data area has to be parsed to get out the data and relocations. + + +File: bfd.info, Node: Section Output, Next: typedef asection, Prev: Section Input, Up: Sections + +2.6.2 Section output +-------------------- + +To write a new object style BFD, the various sections to be written have +to be created. They are attached to the BFD in the same way as input +sections; data is written to the sections using +'bfd_set_section_contents'. + + Any program that creates or combines sections (e.g., the assembler +and linker) must use the 'asection' fields 'output_section' and +'output_offset' to indicate the file sections to which each section must +be written. (If the section is being created from scratch, +'output_section' should probably point to the section itself and +'output_offset' should probably be zero.) + + The data to be written comes from input sections attached (via +'output_section' pointers) to the output sections. The output section +structure can be considered a filter for the input section: the output +section determines the vma of the output data and the name, but the +input section determines the offset into the output section of the data +to be written. + + E.g., to create a section "O", starting at 0x100, 0x123 long, +containing two subsections, "A" at offset 0x0 (i.e., at vma 0x100) and +"B" at offset 0x20 (i.e., at vma 0x120) the 'asection' structures would +look like: + + section name "A" + output_offset 0x00 + size 0x20 + output_section -----------> section name "O" + | vma 0x100 + section name "B" | size 0x123 + output_offset 0x20 | + size 0x103 | + output_section --------| + +2.6.3 Link orders +----------------- + +The data within a section is stored in a "link_order". These are much +like the fixups in 'gas'. The link_order abstraction allows a section +to grow and shrink within itself. + + A link_order knows how big it is, and which is the next link_order +and where the raw data for it is; it also points to a list of +relocations which apply to it. + + The link_order is used by the linker to perform relaxing on final +code. The compiler creates code which is as big as necessary to make it +work without relaxing, and the user can select whether to relax. +Sometimes relaxing takes a lot of time. The linker runs around the +relocations to see if any are attached to data which can be shrunk, if +so it does it on a link_order by link_order basis. + + +File: bfd.info, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections + +2.6.4 typedef asection +---------------------- + +Here is the section structure: + + + typedef struct bfd_section + { + /* The name of the section; the name isn't a copy, the pointer is + the same as that passed to bfd_make_section. */ + const char *name; + + /* A unique sequence number. */ + int id; + + /* Which section in the bfd; 0..n-1 as sections are created in a bfd. */ + int index; + + /* The next section in the list belonging to the BFD, or NULL. */ + struct bfd_section *next; + + /* The previous section in the list belonging to the BFD, or NULL. */ + struct bfd_section *prev; + + /* The field flags contains attributes of the section. Some + flags are read in from the object file, and some are + synthesized from other information. */ + flagword flags; + + #define SEC_NO_FLAGS 0x000 + + /* Tells the OS to allocate space for this section when loading. + This is clear for a section containing debug information only. */ + #define SEC_ALLOC 0x001 + + /* Tells the OS to load the section from the file when loading. + This is clear for a .bss section. */ + #define SEC_LOAD 0x002 + + /* The section contains data still to be relocated, so there is + some relocation information too. */ + #define SEC_RELOC 0x004 + + /* A signal to the OS that the section contains read only data. */ + #define SEC_READONLY 0x008 + + /* The section contains code only. */ + #define SEC_CODE 0x010 + + /* The section contains data only. */ + #define SEC_DATA 0x020 + + /* The section will reside in ROM. */ + #define SEC_ROM 0x040 + + /* The section contains constructor information. This section + type is used by the linker to create lists of constructors and + destructors used by g++. When a back end sees a symbol + which should be used in a constructor list, it creates a new + section for the type of name (e.g., __CTOR_LIST__), attaches + the symbol to it, and builds a relocation. To build the lists + of constructors, all the linker has to do is catenate all the + sections called __CTOR_LIST__ and relocate the data + contained within - exactly the operations it would peform on + standard data. */ + #define SEC_CONSTRUCTOR 0x080 + + /* The section has contents - a data section could be + SEC_ALLOC | SEC_HAS_CONTENTS; a debug section could be + SEC_HAS_CONTENTS */ + #define SEC_HAS_CONTENTS 0x100 + + /* An instruction to the linker to not output the section + even if it has information which would normally be written. */ + #define SEC_NEVER_LOAD 0x200 + + /* The section contains thread local data. */ + #define SEC_THREAD_LOCAL 0x400 + + /* The section has GOT references. This flag is only for the + linker, and is currently only used by the elf32-hppa back end. + It will be set if global offset table references were detected + in this section, which indicate to the linker that the section + contains PIC code, and must be handled specially when doing a + static link. */ + #define SEC_HAS_GOT_REF 0x800 + + /* The section contains common symbols (symbols may be defined + multiple times, the value of a symbol is the amount of + space it requires, and the largest symbol value is the one + used). Most targets have exactly one of these (which we + translate to bfd_com_section_ptr), but ECOFF has two. */ + #define SEC_IS_COMMON 0x1000 + + /* The section contains only debugging information. For + example, this is set for ELF .debug and .stab sections. + strip tests this flag to see if a section can be + discarded. */ + #define SEC_DEBUGGING 0x2000 + + /* The contents of this section are held in memory pointed to + by the contents field. This is checked by bfd_get_section_contents, + and the data is retrieved from memory if appropriate. */ + #define SEC_IN_MEMORY 0x4000 + + /* The contents of this section are to be excluded by the + linker for executable and shared objects unless those + objects are to be further relocated. */ + #define SEC_EXCLUDE 0x8000 + + /* The contents of this section are to be sorted based on the sum of + the symbol and addend values specified by the associated relocation + entries. Entries without associated relocation entries will be + appended to the end of the section in an unspecified order. */ + #define SEC_SORT_ENTRIES 0x10000 + + /* When linking, duplicate sections of the same name should be + discarded, rather than being combined into a single section as + is usually done. This is similar to how common symbols are + handled. See SEC_LINK_DUPLICATES below. */ + #define SEC_LINK_ONCE 0x20000 + + /* If SEC_LINK_ONCE is set, this bitfield describes how the linker + should handle duplicate sections. */ + #define SEC_LINK_DUPLICATES 0xc0000 + + /* This value for SEC_LINK_DUPLICATES means that duplicate + sections with the same name should simply be discarded. */ + #define SEC_LINK_DUPLICATES_DISCARD 0x0 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if there are any duplicate sections, although + it should still only link one copy. */ + #define SEC_LINK_DUPLICATES_ONE_ONLY 0x40000 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if any duplicate sections are a different size. */ + #define SEC_LINK_DUPLICATES_SAME_SIZE 0x80000 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if any duplicate sections contain different + contents. */ + #define SEC_LINK_DUPLICATES_SAME_CONTENTS \ + (SEC_LINK_DUPLICATES_ONE_ONLY | SEC_LINK_DUPLICATES_SAME_SIZE) + + /* This section was created by the linker as part of dynamic + relocation or other arcane processing. It is skipped when + going through the first-pass output, trusting that someone + else up the line will take care of it later. */ + #define SEC_LINKER_CREATED 0x100000 + + /* This section should not be subject to garbage collection. + Also set to inform the linker that this section should not be + listed in the link map as discarded. */ + #define SEC_KEEP 0x200000 + + /* This section contains "short" data, and should be placed + "near" the GP. */ + #define SEC_SMALL_DATA 0x400000 + + /* Attempt to merge identical entities in the section. + Entity size is given in the entsize field. */ + #define SEC_MERGE 0x800000 + + /* If given with SEC_MERGE, entities to merge are zero terminated + strings where entsize specifies character size instead of fixed + size entries. */ + #define SEC_STRINGS 0x1000000 + + /* This section contains data about section groups. */ + #define SEC_GROUP 0x2000000 + + /* The section is a COFF shared library section. This flag is + only for the linker. If this type of section appears in + the input file, the linker must copy it to the output file + without changing the vma or size. FIXME: Although this + was originally intended to be general, it really is COFF + specific (and the flag was renamed to indicate this). It + might be cleaner to have some more general mechanism to + allow the back end to control what the linker does with + sections. */ + #define SEC_COFF_SHARED_LIBRARY 0x4000000 + + /* This input section should be copied to output in reverse order + as an array of pointers. This is for ELF linker internal use + only. */ + #define SEC_ELF_REVERSE_COPY 0x4000000 + + /* This section contains data which may be shared with other + executables or shared objects. This is for COFF only. */ + #define SEC_COFF_SHARED 0x8000000 + + /* When a section with this flag is being linked, then if the size of + the input section is less than a page, it should not cross a page + boundary. If the size of the input section is one page or more, + it should be aligned on a page boundary. This is for TI + TMS320C54X only. */ + #define SEC_TIC54X_BLOCK 0x10000000 + + /* Conditionally link this section; do not link if there are no + references found to any symbol in the section. This is for TI + TMS320C54X only. */ + #define SEC_TIC54X_CLINK 0x20000000 + + /* Indicate that section has the no read flag set. This happens + when memory read flag isn't set. */ + #define SEC_COFF_NOREAD 0x40000000 + + /* End of section flags. */ + + /* Some internal packed boolean fields. */ + + /* See the vma field. */ + unsigned int user_set_vma : 1; + + /* A mark flag used by some of the linker backends. */ + unsigned int linker_mark : 1; + + /* Another mark flag used by some of the linker backends. Set for + output sections that have an input section. */ + unsigned int linker_has_input : 1; + + /* Mark flag used by some linker backends for garbage collection. */ + unsigned int gc_mark : 1; + + /* Section compression status. */ + unsigned int compress_status : 2; + #define COMPRESS_SECTION_NONE 0 + #define COMPRESS_SECTION_DONE 1 + #define DECOMPRESS_SECTION_SIZED 2 + + /* The following flags are used by the ELF linker. */ + + /* Mark sections which have been allocated to segments. */ + unsigned int segment_mark : 1; + + /* Type of sec_info information. */ + unsigned int sec_info_type:3; + #define SEC_INFO_TYPE_NONE 0 + #define SEC_INFO_TYPE_STABS 1 + #define SEC_INFO_TYPE_MERGE 2 + #define SEC_INFO_TYPE_EH_FRAME 3 + #define SEC_INFO_TYPE_JUST_SYMS 4 + + /* Nonzero if this section uses RELA relocations, rather than REL. */ + unsigned int use_rela_p:1; + + /* Bits used by various backends. The generic code doesn't touch + these fields. */ + + unsigned int sec_flg0:1; + unsigned int sec_flg1:1; + unsigned int sec_flg2:1; + unsigned int sec_flg3:1; + unsigned int sec_flg4:1; + unsigned int sec_flg5:1; + + /* End of internal packed boolean fields. */ + + /* The virtual memory address of the section - where it will be + at run time. The symbols are relocated against this. The + user_set_vma flag is maintained by bfd; if it's not set, the + backend can assign addresses (for example, in a.out, where + the default address for .data is dependent on the specific + target and various flags). */ + bfd_vma vma; + + /* The load address of the section - where it would be in a + rom image; really only used for writing section header + information. */ + bfd_vma lma; + + /* The size of the section in octets, as it will be output. + Contains a value even if the section has no contents (e.g., the + size of .bss). */ + bfd_size_type size; + + /* For input sections, the original size on disk of the section, in + octets. This field should be set for any section whose size is + changed by linker relaxation. It is required for sections where + the linker relaxation scheme doesn't cache altered section and + reloc contents (stabs, eh_frame, SEC_MERGE, some coff relaxing + targets), and thus the original size needs to be kept to read the + section multiple times. For output sections, rawsize holds the + section size calculated on a previous linker relaxation pass. */ + bfd_size_type rawsize; + + /* The compressed size of the section in octets. */ + bfd_size_type compressed_size; + + /* Relaxation table. */ + struct relax_table *relax; + + /* Count of used relaxation table entries. */ + int relax_count; + + + /* If this section is going to be output, then this value is the + offset in *bytes* into the output section of the first byte in the + input section (byte ==> smallest addressable unit on the + target). In most cases, if this was going to start at the + 100th octet (8-bit quantity) in the output section, this value + would be 100. However, if the target byte size is 16 bits + (bfd_octets_per_byte is "2"), this value would be 50. */ + bfd_vma output_offset; + + /* The output section through which to map on output. */ + struct bfd_section *output_section; + + /* The alignment requirement of the section, as an exponent of 2 - + e.g., 3 aligns to 2^3 (or 8). */ + unsigned int alignment_power; + + /* If an input section, a pointer to a vector of relocation + records for the data in this section. */ + struct reloc_cache_entry *relocation; + + /* If an output section, a pointer to a vector of pointers to + relocation records for the data in this section. */ + struct reloc_cache_entry **orelocation; + + /* The number of relocation records in one of the above. */ + unsigned reloc_count; + + /* Information below is back end specific - and not always used + or updated. */ + + /* File position of section data. */ + file_ptr filepos; + + /* File position of relocation info. */ + file_ptr rel_filepos; + + /* File position of line data. */ + file_ptr line_filepos; + + /* Pointer to data for applications. */ + void *userdata; + + /* If the SEC_IN_MEMORY flag is set, this points to the actual + contents. */ + unsigned char *contents; + + /* Attached line number information. */ + alent *lineno; + + /* Number of line number records. */ + unsigned int lineno_count; + + /* Entity size for merging purposes. */ + unsigned int entsize; + + /* Points to the kept section if this section is a link-once section, + and is discarded. */ + struct bfd_section *kept_section; + + /* When a section is being output, this value changes as more + linenumbers are written out. */ + file_ptr moving_line_filepos; + + /* What the section number is in the target world. */ + int target_index; + + void *used_by_bfd; + + /* If this is a constructor section then here is a list of the + relocations created to relocate items within it. */ + struct relent_chain *constructor_chain; + + /* The BFD which owns the section. */ + bfd *owner; + + /* A symbol which points at this section only. */ + struct bfd_symbol *symbol; + struct bfd_symbol **symbol_ptr_ptr; + + /* Early in the link process, map_head and map_tail are used to build + a list of input sections attached to an output section. Later, + output sections use these fields for a list of bfd_link_order + structs. */ + union { + struct bfd_link_order *link_order; + struct bfd_section *s; + } map_head, map_tail; + } asection; + + /* Relax table contains information about instructions which can + be removed by relaxation -- replacing a long address with a + short address. */ + struct relax_table { + /* Address where bytes may be deleted. */ + bfd_vma addr; + + /* Number of bytes to be deleted. */ + int size; + }; + + /* Note: the following are provided as inline functions rather than macros + because not all callers use the return value. A macro implementation + would use a comma expression, eg: "((ptr)->foo = val, TRUE)" and some + compilers will complain about comma expressions that have no effect. */ + static inline bfd_boolean + bfd_set_section_userdata (bfd * abfd ATTRIBUTE_UNUSED, asection * ptr, void * val) + { + ptr->userdata = val; + return TRUE; + } + + static inline bfd_boolean + bfd_set_section_vma (bfd * abfd ATTRIBUTE_UNUSED, asection * ptr, bfd_vma val) + { + ptr->vma = ptr->lma = val; + ptr->user_set_vma = TRUE; + return TRUE; + } + + static inline bfd_boolean + bfd_set_section_alignment (bfd * abfd ATTRIBUTE_UNUSED, asection * ptr, unsigned int val) + { + ptr->alignment_power = val; + return TRUE; + } + + /* These sections are global, and are managed by BFD. The application + and target back end are not permitted to change the values in + these sections. */ + extern asection _bfd_std_section[4]; + + #define BFD_ABS_SECTION_NAME "*ABS*" + #define BFD_UND_SECTION_NAME "*UND*" + #define BFD_COM_SECTION_NAME "*COM*" + #define BFD_IND_SECTION_NAME "*IND*" + + /* Pointer to the common section. */ + #define bfd_com_section_ptr (&_bfd_std_section[0]) + /* Pointer to the undefined section. */ + #define bfd_und_section_ptr (&_bfd_std_section[1]) + /* Pointer to the absolute section. */ + #define bfd_abs_section_ptr (&_bfd_std_section[2]) + /* Pointer to the indirect section. */ + #define bfd_ind_section_ptr (&_bfd_std_section[3]) + + #define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr) + #define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr) + #define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr) + + #define bfd_is_const_section(SEC) \ + ( ((SEC) == bfd_abs_section_ptr) \ + || ((SEC) == bfd_und_section_ptr) \ + || ((SEC) == bfd_com_section_ptr) \ + || ((SEC) == bfd_ind_section_ptr)) + + /* Macros to handle insertion and deletion of a bfd's sections. These + only handle the list pointers, ie. do not adjust section_count, + target_index etc. */ + #define bfd_section_list_remove(ABFD, S) \ + do \ + { \ + asection *_s = S; \ + asection *_next = _s->next; \ + asection *_prev = _s->prev; \ + if (_prev) \ + _prev->next = _next; \ + else \ + (ABFD)->sections = _next; \ + if (_next) \ + _next->prev = _prev; \ + else \ + (ABFD)->section_last = _prev; \ + } \ + while (0) + #define bfd_section_list_append(ABFD, S) \ + do \ + { \ + asection *_s = S; \ + bfd *_abfd = ABFD; \ + _s->next = NULL; \ + if (_abfd->section_last) \ + { \ + _s->prev = _abfd->section_last; \ + _abfd->section_last->next = _s; \ + } \ + else \ + { \ + _s->prev = NULL; \ + _abfd->sections = _s; \ + } \ + _abfd->section_last = _s; \ + } \ + while (0) + #define bfd_section_list_prepend(ABFD, S) \ + do \ + { \ + asection *_s = S; \ + bfd *_abfd = ABFD; \ + _s->prev = NULL; \ + if (_abfd->sections) \ + { \ + _s->next = _abfd->sections; \ + _abfd->sections->prev = _s; \ + } \ + else \ + { \ + _s->next = NULL; \ + _abfd->section_last = _s; \ + } \ + _abfd->sections = _s; \ + } \ + while (0) + #define bfd_section_list_insert_after(ABFD, A, S) \ + do \ + { \ + asection *_a = A; \ + asection *_s = S; \ + asection *_next = _a->next; \ + _s->next = _next; \ + _s->prev = _a; \ + _a->next = _s; \ + if (_next) \ + _next->prev = _s; \ + else \ + (ABFD)->section_last = _s; \ + } \ + while (0) + #define bfd_section_list_insert_before(ABFD, B, S) \ + do \ + { \ + asection *_b = B; \ + asection *_s = S; \ + asection *_prev = _b->prev; \ + _s->prev = _prev; \ + _s->next = _b; \ + _b->prev = _s; \ + if (_prev) \ + _prev->next = _s; \ + else \ + (ABFD)->sections = _s; \ + } \ + while (0) + #define bfd_section_removed_from_list(ABFD, S) \ + ((S)->next == NULL ? (ABFD)->section_last != (S) : (S)->next->prev != (S)) + + #define BFD_FAKE_SECTION(SEC, FLAGS, SYM, NAME, IDX) \ + /* name, id, index, next, prev, flags, user_set_vma, */ \ + { NAME, IDX, 0, NULL, NULL, FLAGS, 0, \ + \ + /* linker_mark, linker_has_input, gc_mark, decompress_status, */ \ + 0, 0, 1, 0, \ + \ + /* segment_mark, sec_info_type, use_rela_p, */ \ + 0, 0, 0, \ + \ + /* sec_flg0, sec_flg1, sec_flg2, sec_flg3, sec_flg4, sec_flg5, */ \ + 0, 0, 0, 0, 0, 0, \ + \ + /* vma, lma, size, rawsize, compressed_size, relax, relax_count, */ \ + 0, 0, 0, 0, 0, 0, 0, \ + \ + /* output_offset, output_section, alignment_power, */ \ + 0, &SEC, 0, \ + \ + /* relocation, orelocation, reloc_count, filepos, rel_filepos, */ \ + NULL, NULL, 0, 0, 0, \ + \ + /* line_filepos, userdata, contents, lineno, lineno_count, */ \ + 0, NULL, NULL, NULL, 0, \ + \ + /* entsize, kept_section, moving_line_filepos, */ \ + 0, NULL, 0, \ + \ + /* target_index, used_by_bfd, constructor_chain, owner, */ \ + 0, NULL, NULL, NULL, \ + \ + /* symbol, symbol_ptr_ptr, */ \ + (struct bfd_symbol *) SYM, &SEC.symbol, \ + \ + /* map_head, map_tail */ \ + { NULL }, { NULL } \ + } + + +File: bfd.info, Node: section prototypes, Prev: typedef asection, Up: Sections + +2.6.5 Section prototypes +------------------------ + +These are the functions exported by the section handling part of BFD. + +2.6.5.1 'bfd_section_list_clear' +................................ + +*Synopsis* + void bfd_section_list_clear (bfd *); + *Description* +Clears the section list, and also resets the section count and hash +table entries. + +2.6.5.2 'bfd_get_section_by_name' +................................. + +*Synopsis* + asection *bfd_get_section_by_name (bfd *abfd, const char *name); + *Description* +Return the most recently created section attached to ABFD named NAME. +Return NULL if no such section exists. + +2.6.5.3 'bfd_get_next_section_by_name' +...................................... + +*Synopsis* + asection *bfd_get_next_section_by_name (asection *sec); + *Description* +Given SEC is a section returned by 'bfd_get_section_by_name', return the +next most recently created section attached to the same BFD with the +same name. Return NULL if no such section exists. + +2.6.5.4 'bfd_get_linker_section' +................................ + +*Synopsis* + asection *bfd_get_linker_section (bfd *abfd, const char *name); + *Description* +Return the linker created section attached to ABFD named NAME. Return +NULL if no such section exists. + +2.6.5.5 'bfd_get_section_by_name_if' +.................................... + +*Synopsis* + asection *bfd_get_section_by_name_if + (bfd *abfd, + const char *name, + bfd_boolean (*func) (bfd *abfd, asection *sect, void *obj), + void *obj); + *Description* +Call the provided function FUNC for each section attached to the BFD +ABFD whose name matches NAME, passing OBJ as an argument. The function +will be called as if by + + func (abfd, the_section, obj); + + It returns the first section for which FUNC returns true, otherwise +'NULL'. + +2.6.5.6 'bfd_get_unique_section_name' +..................................... + +*Synopsis* + char *bfd_get_unique_section_name + (bfd *abfd, const char *templat, int *count); + *Description* +Invent a section name that is unique in ABFD by tacking a dot and a +digit suffix onto the original TEMPLAT. If COUNT is non-NULL, then it +specifies the first number tried as a suffix to generate a unique name. +The value pointed to by COUNT will be incremented in this case. + +2.6.5.7 'bfd_make_section_old_way' +.................................. + +*Synopsis* + asection *bfd_make_section_old_way (bfd *abfd, const char *name); + *Description* +Create a new empty section called NAME and attach it to the end of the +chain of sections for the BFD ABFD. An attempt to create a section with +a name which is already in use returns its pointer without changing the +section chain. + + It has the funny name since this is the way it used to be before it +was rewritten.... + + Possible errors are: + + * 'bfd_error_invalid_operation' - If output has already started for + this BFD. + * 'bfd_error_no_memory' - If memory allocation fails. + +2.6.5.8 'bfd_make_section_anyway_with_flags' +............................................ + +*Synopsis* + asection *bfd_make_section_anyway_with_flags + (bfd *abfd, const char *name, flagword flags); + *Description* +Create a new empty section called NAME and attach it to the end of the +chain of sections for ABFD. Create a new section even if there is +already a section with that name. Also set the attributes of the new +section to the value FLAGS. + + Return 'NULL' and set 'bfd_error' on error; possible errors are: + + * 'bfd_error_invalid_operation' - If output has already started for + ABFD. + * 'bfd_error_no_memory' - If memory allocation fails. + +2.6.5.9 'bfd_make_section_anyway' +................................. + +*Synopsis* + asection *bfd_make_section_anyway (bfd *abfd, const char *name); + *Description* +Create a new empty section called NAME and attach it to the end of the +chain of sections for ABFD. Create a new section even if there is +already a section with that name. + + Return 'NULL' and set 'bfd_error' on error; possible errors are: + + * 'bfd_error_invalid_operation' - If output has already started for + ABFD. + * 'bfd_error_no_memory' - If memory allocation fails. + +2.6.5.10 'bfd_make_section_with_flags' +...................................... + +*Synopsis* + asection *bfd_make_section_with_flags + (bfd *, const char *name, flagword flags); + *Description* +Like 'bfd_make_section_anyway', but return 'NULL' (without calling +bfd_set_error ()) without changing the section chain if there is already +a section named NAME. Also set the attributes of the new section to the +value FLAGS. If there is an error, return 'NULL' and set 'bfd_error'. + +2.6.5.11 'bfd_make_section' +........................... + +*Synopsis* + asection *bfd_make_section (bfd *, const char *name); + *Description* +Like 'bfd_make_section_anyway', but return 'NULL' (without calling +bfd_set_error ()) without changing the section chain if there is already +a section named NAME. If there is an error, return 'NULL' and set +'bfd_error'. + +2.6.5.12 'bfd_set_section_flags' +................................ + +*Synopsis* + bfd_boolean bfd_set_section_flags + (bfd *abfd, asection *sec, flagword flags); + *Description* +Set the attributes of the section SEC in the BFD ABFD to the value +FLAGS. Return 'TRUE' on success, 'FALSE' on error. Possible error +returns are: + + * 'bfd_error_invalid_operation' - The section cannot have one or more + of the attributes requested. For example, a .bss section in + 'a.out' may not have the 'SEC_HAS_CONTENTS' field set. + +2.6.5.13 'bfd_rename_section' +............................. + +*Synopsis* + void bfd_rename_section + (bfd *abfd, asection *sec, const char *newname); + *Description* +Rename section SEC in ABFD to NEWNAME. + +2.6.5.14 'bfd_map_over_sections' +................................ + +*Synopsis* + void bfd_map_over_sections + (bfd *abfd, + void (*func) (bfd *abfd, asection *sect, void *obj), + void *obj); + *Description* +Call the provided function FUNC for each section attached to the BFD +ABFD, passing OBJ as an argument. The function will be called as if by + + func (abfd, the_section, obj); + + This is the preferred method for iterating over sections; an +alternative would be to use a loop: + + asection *p; + for (p = abfd->sections; p != NULL; p = p->next) + func (abfd, p, ...) + +2.6.5.15 'bfd_sections_find_if' +............................... + +*Synopsis* + asection *bfd_sections_find_if + (bfd *abfd, + bfd_boolean (*operation) (bfd *abfd, asection *sect, void *obj), + void *obj); + *Description* +Call the provided function OPERATION for each section attached to the +BFD ABFD, passing OBJ as an argument. The function will be called as if +by + + operation (abfd, the_section, obj); + + It returns the first section for which OPERATION returns true. + +2.6.5.16 'bfd_set_section_size' +............................... + +*Synopsis* + bfd_boolean bfd_set_section_size + (bfd *abfd, asection *sec, bfd_size_type val); + *Description* +Set SEC to the size VAL. If the operation is ok, then 'TRUE' is +returned, else 'FALSE'. + + Possible error returns: + + * 'bfd_error_invalid_operation' - Writing has started to the BFD, so + setting the size is invalid. + +2.6.5.17 'bfd_set_section_contents' +................................... + +*Synopsis* + bfd_boolean bfd_set_section_contents + (bfd *abfd, asection *section, const void *data, + file_ptr offset, bfd_size_type count); + *Description* +Sets the contents of the section SECTION in BFD ABFD to the data +starting in memory at DATA. The data is written to the output section +starting at offset OFFSET for COUNT octets. + + Normally 'TRUE' is returned, else 'FALSE'. Possible error returns +are: + + * 'bfd_error_no_contents' - The output section does not have the + 'SEC_HAS_CONTENTS' attribute, so nothing can be written to it. + * and some more too + This routine is front end to the back end function +'_bfd_set_section_contents'. + +2.6.5.18 'bfd_get_section_contents' +................................... + +*Synopsis* + bfd_boolean bfd_get_section_contents + (bfd *abfd, asection *section, void *location, file_ptr offset, + bfd_size_type count); + *Description* +Read data from SECTION in BFD ABFD into memory starting at LOCATION. +The data is read at an offset of OFFSET from the start of the input +section, and is read for COUNT bytes. + + If the contents of a constructor with the 'SEC_CONSTRUCTOR' flag set +are requested or if the section does not have the 'SEC_HAS_CONTENTS' +flag set, then the LOCATION is filled with zeroes. If no errors occur, +'TRUE' is returned, else 'FALSE'. + +2.6.5.19 'bfd_malloc_and_get_section' +..................................... + +*Synopsis* + bfd_boolean bfd_malloc_and_get_section + (bfd *abfd, asection *section, bfd_byte **buf); + *Description* +Read all data from SECTION in BFD ABFD into a buffer, *BUF, malloc'd by +this function. + +2.6.5.20 'bfd_copy_private_section_data' +........................................ + +*Synopsis* + bfd_boolean bfd_copy_private_section_data + (bfd *ibfd, asection *isec, bfd *obfd, asection *osec); + *Description* +Copy private section information from ISEC in the BFD IBFD to the +section OSEC in the BFD OBFD. Return 'TRUE' on success, 'FALSE' on +error. Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create private + data for OSEC. + #define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \ + BFD_SEND (obfd, _bfd_copy_private_section_data, \ + (ibfd, isection, obfd, osection)) + +2.6.5.21 'bfd_generic_is_group_section' +....................................... + +*Synopsis* + bfd_boolean bfd_generic_is_group_section (bfd *, const asection *sec); + *Description* +Returns TRUE if SEC is a member of a group. + +2.6.5.22 'bfd_generic_discard_group' +.................................... + +*Synopsis* + bfd_boolean bfd_generic_discard_group (bfd *abfd, asection *group); + *Description* +Remove all members of GROUP from the output. + + +File: bfd.info, Node: Symbols, Next: Archives, Prev: Sections, Up: BFD front end + +2.7 Symbols +=========== + +BFD tries to maintain as much symbol information as it can when it moves +information from file to file. BFD passes information to applications +though the 'asymbol' structure. When the application requests the +symbol table, BFD reads the table in the native form and translates +parts of it into the internal format. To maintain more than the +information passed to applications, some targets keep some information +"behind the scenes" in a structure only the particular back end knows +about. For example, the coff back end keeps the original symbol table +structure as well as the canonical structure when a BFD is read in. On +output, the coff back end can reconstruct the output symbol table so +that no information is lost, even information unique to coff which BFD +doesn't know or understand. If a coff symbol table were read, but were +written through an a.out back end, all the coff specific information +would be lost. The symbol table of a BFD is not necessarily read in +until a canonicalize request is made. Then the BFD back end fills in a +table provided by the application with pointers to the canonical +information. To output symbols, the application provides BFD with a +table of pointers to pointers to 'asymbol's. This allows applications +like the linker to output a symbol as it was read, since the "behind the +scenes" information will be still available. +* Menu: + +* Reading Symbols:: +* Writing Symbols:: +* Mini Symbols:: +* typedef asymbol:: +* symbol handling functions:: + + +File: bfd.info, Node: Reading Symbols, Next: Writing Symbols, Prev: Symbols, Up: Symbols + +2.7.1 Reading symbols +--------------------- + +There are two stages to reading a symbol table from a BFD: allocating +storage, and the actual reading process. This is an excerpt from an +application which reads the symbol table: + + long storage_needed; + asymbol **symbol_table; + long number_of_symbols; + long i; + + storage_needed = bfd_get_symtab_upper_bound (abfd); + + if (storage_needed < 0) + FAIL + + if (storage_needed == 0) + return; + + symbol_table = xmalloc (storage_needed); + ... + number_of_symbols = + bfd_canonicalize_symtab (abfd, symbol_table); + + if (number_of_symbols < 0) + FAIL + + for (i = 0; i < number_of_symbols; i++) + process_symbol (symbol_table[i]); + + All storage for the symbols themselves is in an objalloc connected to +the BFD; it is freed when the BFD is closed. + + +File: bfd.info, Node: Writing Symbols, Next: Mini Symbols, Prev: Reading Symbols, Up: Symbols + +2.7.2 Writing symbols +--------------------- + +Writing of a symbol table is automatic when a BFD open for writing is +closed. The application attaches a vector of pointers to pointers to +symbols to the BFD being written, and fills in the symbol count. The +close and cleanup code reads through the table provided and performs all +the necessary operations. The BFD output code must always be provided +with an "owned" symbol: one which has come from another BFD, or one +which has been created using 'bfd_make_empty_symbol'. Here is an +example showing the creation of a symbol table with only one element: + + #include "sysdep.h" + #include "bfd.h" + int main (void) + { + bfd *abfd; + asymbol *ptrs[2]; + asymbol *new; + + abfd = bfd_openw ("foo","a.out-sunos-big"); + bfd_set_format (abfd, bfd_object); + new = bfd_make_empty_symbol (abfd); + new->name = "dummy_symbol"; + new->section = bfd_make_section_old_way (abfd, ".text"); + new->flags = BSF_GLOBAL; + new->value = 0x12345; + + ptrs[0] = new; + ptrs[1] = 0; + + bfd_set_symtab (abfd, ptrs, 1); + bfd_close (abfd); + return 0; + } + + ./makesym + nm foo + 00012345 A dummy_symbol + + Many formats cannot represent arbitrary symbol information; for +instance, the 'a.out' object format does not allow an arbitrary number +of sections. A symbol pointing to a section which is not one of +'.text', '.data' or '.bss' cannot be described. + + +File: bfd.info, Node: Mini Symbols, Next: typedef asymbol, Prev: Writing Symbols, Up: Symbols + +2.7.3 Mini Symbols +------------------ + +Mini symbols provide read-only access to the symbol table. They use +less memory space, but require more time to access. They can be useful +for tools like nm or objdump, which may have to handle symbol tables of +extremely large executables. + + The 'bfd_read_minisymbols' function will read the symbols into memory +in an internal form. It will return a 'void *' pointer to a block of +memory, a symbol count, and the size of each symbol. The pointer is +allocated using 'malloc', and should be freed by the caller when it is +no longer needed. + + The function 'bfd_minisymbol_to_symbol' will take a pointer to a +minisymbol, and a pointer to a structure returned by +'bfd_make_empty_symbol', and return a 'asymbol' structure. The return +value may or may not be the same as the value from +'bfd_make_empty_symbol' which was passed in. + + +File: bfd.info, Node: typedef asymbol, Next: symbol handling functions, Prev: Mini Symbols, Up: Symbols + +2.7.4 typedef asymbol +--------------------- + +An 'asymbol' has the form: + + + typedef struct bfd_symbol + { + /* A pointer to the BFD which owns the symbol. This information + is necessary so that a back end can work out what additional + information (invisible to the application writer) is carried + with the symbol. + + This field is *almost* redundant, since you can use section->owner + instead, except that some symbols point to the global sections + bfd_{abs,com,und}_section. This could be fixed by making + these globals be per-bfd (or per-target-flavor). FIXME. */ + struct bfd *the_bfd; /* Use bfd_asymbol_bfd(sym) to access this field. */ + + /* The text of the symbol. The name is left alone, and not copied; the + application may not alter it. */ + const char *name; + + /* The value of the symbol. This really should be a union of a + numeric value with a pointer, since some flags indicate that + a pointer to another symbol is stored here. */ + symvalue value; + + /* Attributes of a symbol. */ + #define BSF_NO_FLAGS 0x00 + + /* The symbol has local scope; static in C. The value + is the offset into the section of the data. */ + #define BSF_LOCAL (1 << 0) + + /* The symbol has global scope; initialized data in C. The + value is the offset into the section of the data. */ + #define BSF_GLOBAL (1 << 1) + + /* The symbol has global scope and is exported. The value is + the offset into the section of the data. */ + #define BSF_EXPORT BSF_GLOBAL /* No real difference. */ + + /* A normal C symbol would be one of: + BSF_LOCAL, BSF_COMMON, BSF_UNDEFINED or + BSF_GLOBAL. */ + + /* The symbol is a debugging record. The value has an arbitrary + meaning, unless BSF_DEBUGGING_RELOC is also set. */ + #define BSF_DEBUGGING (1 << 2) + + /* The symbol denotes a function entry point. Used in ELF, + perhaps others someday. */ + #define BSF_FUNCTION (1 << 3) + + /* Used by the linker. */ + #define BSF_KEEP (1 << 5) + #define BSF_KEEP_G (1 << 6) + + /* A weak global symbol, overridable without warnings by + a regular global symbol of the same name. */ + #define BSF_WEAK (1 << 7) + + /* This symbol was created to point to a section, e.g. ELF's + STT_SECTION symbols. */ + #define BSF_SECTION_SYM (1 << 8) + + /* The symbol used to be a common symbol, but now it is + allocated. */ + #define BSF_OLD_COMMON (1 << 9) + + /* In some files the type of a symbol sometimes alters its + location in an output file - ie in coff a ISFCN symbol + which is also C_EXT symbol appears where it was + declared and not at the end of a section. This bit is set + by the target BFD part to convey this information. */ + #define BSF_NOT_AT_END (1 << 10) + + /* Signal that the symbol is the label of constructor section. */ + #define BSF_CONSTRUCTOR (1 << 11) + + /* Signal that the symbol is a warning symbol. The name is a + warning. The name of the next symbol is the one to warn about; + if a reference is made to a symbol with the same name as the next + symbol, a warning is issued by the linker. */ + #define BSF_WARNING (1 << 12) + + /* Signal that the symbol is indirect. This symbol is an indirect + pointer to the symbol with the same name as the next symbol. */ + #define BSF_INDIRECT (1 << 13) + + /* BSF_FILE marks symbols that contain a file name. This is used + for ELF STT_FILE symbols. */ + #define BSF_FILE (1 << 14) + + /* Symbol is from dynamic linking information. */ + #define BSF_DYNAMIC (1 << 15) + + /* The symbol denotes a data object. Used in ELF, and perhaps + others someday. */ + #define BSF_OBJECT (1 << 16) + + /* This symbol is a debugging symbol. The value is the offset + into the section of the data. BSF_DEBUGGING should be set + as well. */ + #define BSF_DEBUGGING_RELOC (1 << 17) + + /* This symbol is thread local. Used in ELF. */ + #define BSF_THREAD_LOCAL (1 << 18) + + /* This symbol represents a complex relocation expression, + with the expression tree serialized in the symbol name. */ + #define BSF_RELC (1 << 19) + + /* This symbol represents a signed complex relocation expression, + with the expression tree serialized in the symbol name. */ + #define BSF_SRELC (1 << 20) + + /* This symbol was created by bfd_get_synthetic_symtab. */ + #define BSF_SYNTHETIC (1 << 21) + + /* This symbol is an indirect code object. Unrelated to BSF_INDIRECT. + The dynamic linker will compute the value of this symbol by + calling the function that it points to. BSF_FUNCTION must + also be also set. */ + #define BSF_GNU_INDIRECT_FUNCTION (1 << 22) + /* This symbol is a globally unique data object. The dynamic linker + will make sure that in the entire process there is just one symbol + with this name and type in use. BSF_OBJECT must also be set. */ + #define BSF_GNU_UNIQUE (1 << 23) + + flagword flags; + + /* A pointer to the section to which this symbol is + relative. This will always be non NULL, there are special + sections for undefined and absolute symbols. */ + struct bfd_section *section; + + /* Back end special data. */ + union + { + void *p; + bfd_vma i; + } + udata; + } + asymbol; + + +File: bfd.info, Node: symbol handling functions, Prev: typedef asymbol, Up: Symbols + +2.7.5 Symbol handling functions +------------------------------- + +2.7.5.1 'bfd_get_symtab_upper_bound' +.................................... + +*Description* +Return the number of bytes required to store a vector of pointers to +'asymbols' for all the symbols in the BFD ABFD, including a terminal +NULL pointer. If there are no symbols in the BFD, then return 0. If an +error occurs, return -1. + #define bfd_get_symtab_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd)) + +2.7.5.2 'bfd_is_local_label' +............................ + +*Synopsis* + bfd_boolean bfd_is_local_label (bfd *abfd, asymbol *sym); + *Description* +Return TRUE if the given symbol SYM in the BFD ABFD is a compiler +generated local label, else return FALSE. + +2.7.5.3 'bfd_is_local_label_name' +................................. + +*Synopsis* + bfd_boolean bfd_is_local_label_name (bfd *abfd, const char *name); + *Description* +Return TRUE if a symbol with the name NAME in the BFD ABFD is a compiler +generated local label, else return FALSE. This just checks whether the +name has the form of a local label. + #define bfd_is_local_label_name(abfd, name) \ + BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name)) + +2.7.5.4 'bfd_is_target_special_symbol' +...................................... + +*Synopsis* + bfd_boolean bfd_is_target_special_symbol (bfd *abfd, asymbol *sym); + *Description* +Return TRUE iff a symbol SYM in the BFD ABFD is something special to the +particular target represented by the BFD. Such symbols should normally +not be mentioned to the user. + #define bfd_is_target_special_symbol(abfd, sym) \ + BFD_SEND (abfd, _bfd_is_target_special_symbol, (abfd, sym)) + +2.7.5.5 'bfd_canonicalize_symtab' +................................. + +*Description* +Read the symbols from the BFD ABFD, and fills in the vector LOCATION +with pointers to the symbols and a trailing NULL. Return the actual +number of symbol pointers, not including the NULL. + #define bfd_canonicalize_symtab(abfd, location) \ + BFD_SEND (abfd, _bfd_canonicalize_symtab, (abfd, location)) + +2.7.5.6 'bfd_set_symtab' +........................ + +*Synopsis* + bfd_boolean bfd_set_symtab + (bfd *abfd, asymbol **location, unsigned int count); + *Description* +Arrange that when the output BFD ABFD is closed, the table LOCATION of +COUNT pointers to symbols will be written. + +2.7.5.7 'bfd_print_symbol_vandf' +................................ + +*Synopsis* + void bfd_print_symbol_vandf (bfd *abfd, void *file, asymbol *symbol); + *Description* +Print the value and flags of the SYMBOL supplied to the stream FILE. + +2.7.5.8 'bfd_make_empty_symbol' +............................... + +*Description* +Create a new 'asymbol' structure for the BFD ABFD and return a pointer +to it. + + This routine is necessary because each back end has private +information surrounding the 'asymbol'. Building your own 'asymbol' and +pointing to it will not create the private information, and will cause +problems later on. + #define bfd_make_empty_symbol(abfd) \ + BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd)) + +2.7.5.9 '_bfd_generic_make_empty_symbol' +........................................ + +*Synopsis* + asymbol *_bfd_generic_make_empty_symbol (bfd *); + *Description* +Create a new 'asymbol' structure for the BFD ABFD and return a pointer +to it. Used by core file routines, binary back-end and anywhere else +where no private info is needed. + +2.7.5.10 'bfd_make_debug_symbol' +................................ + +*Description* +Create a new 'asymbol' structure for the BFD ABFD, to be used as a +debugging symbol. Further details of its use have yet to be worked out. + #define bfd_make_debug_symbol(abfd,ptr,size) \ + BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size)) + +2.7.5.11 'bfd_decode_symclass' +.............................. + +*Description* +Return a character corresponding to the symbol class of SYMBOL, or '?' +for an unknown class. + + *Synopsis* + int bfd_decode_symclass (asymbol *symbol); + +2.7.5.12 'bfd_is_undefined_symclass' +.................................... + +*Description* +Returns non-zero if the class symbol returned by bfd_decode_symclass +represents an undefined symbol. Returns zero otherwise. + + *Synopsis* + bfd_boolean bfd_is_undefined_symclass (int symclass); + +2.7.5.13 'bfd_symbol_info' +.......................... + +*Description* +Fill in the basic info about symbol that nm needs. Additional info may +be added by the back-ends after calling this function. + + *Synopsis* + void bfd_symbol_info (asymbol *symbol, symbol_info *ret); + +2.7.5.14 'bfd_copy_private_symbol_data' +....................................... + +*Synopsis* + bfd_boolean bfd_copy_private_symbol_data + (bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym); + *Description* +Copy private symbol information from ISYM in the BFD IBFD to the symbol +OSYM in the BFD OBFD. Return 'TRUE' on success, 'FALSE' on error. +Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create private + data for OSEC. + #define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \ + BFD_SEND (obfd, _bfd_copy_private_symbol_data, \ + (ibfd, isymbol, obfd, osymbol)) + + +File: bfd.info, Node: Archives, Next: Formats, Prev: Symbols, Up: BFD front end + +2.8 Archives +============ + +*Description* +An archive (or library) is just another BFD. It has a symbol table, +although there's not much a user program will do with it. + + The big difference between an archive BFD and an ordinary BFD is that +the archive doesn't have sections. Instead it has a chain of BFDs that +are considered its contents. These BFDs can be manipulated like any +other. The BFDs contained in an archive opened for reading will all be +opened for reading. You may put either input or output BFDs into an +archive opened for output; they will be handled correctly when the +archive is closed. + + Use 'bfd_openr_next_archived_file' to step through the contents of an +archive opened for input. You don't have to read the entire archive if +you don't want to! Read it until you find what you want. + + A BFD returned by 'bfd_openr_next_archived_file' can be closed +manually with 'bfd_close'. If you do not close it, then a second +iteration through the members of an archive may return the same BFD. If +you close the archive BFD, then all the member BFDs will automatically +be closed as well. + + Archive contents of output BFDs are chained through the +'archive_next' pointer in a BFD. The first one is findable through the +'archive_head' slot of the archive. Set it with 'bfd_set_archive_head' +(q.v.). A given BFD may be in only one open output archive at a time. + + As expected, the BFD archive code is more general than the archive +code of any given environment. BFD archives may contain files of +different formats (e.g., a.out and coff) and even different +architectures. You may even place archives recursively into archives! + + This can cause unexpected confusion, since some archive formats are +more expressive than others. For instance, Intel COFF archives can +preserve long filenames; SunOS a.out archives cannot. If you move a +file from the first to the second format and back again, the filename +may be truncated. Likewise, different a.out environments have different +conventions as to how they truncate filenames, whether they preserve +directory names in filenames, etc. When interoperating with native +tools, be sure your files are homogeneous. + + Beware: most of these formats do not react well to the presence of +spaces in filenames. We do the best we can, but can't always handle +this case due to restrictions in the format of archives. Many Unix +utilities are braindead in regards to spaces and such in filenames +anyway, so this shouldn't be much of a restriction. + + Archives are supported in BFD in 'archive.c'. + +2.8.1 Archive functions +----------------------- + +2.8.1.1 'bfd_get_next_mapent' +............................. + +*Synopsis* + symindex bfd_get_next_mapent + (bfd *abfd, symindex previous, carsym **sym); + *Description* +Step through archive ABFD's symbol table (if it has one). Successively +update SYM with the next symbol's information, returning that symbol's +(internal) index into the symbol table. + + Supply 'BFD_NO_MORE_SYMBOLS' as the PREVIOUS entry to get the first +one; returns 'BFD_NO_MORE_SYMBOLS' when you've already got the last one. + + A 'carsym' is a canonical archive symbol. The only user-visible +element is its name, a null-terminated string. + +2.8.1.2 'bfd_set_archive_head' +.............................. + +*Synopsis* + bfd_boolean bfd_set_archive_head (bfd *output, bfd *new_head); + *Description* +Set the head of the chain of BFDs contained in the archive OUTPUT to +NEW_HEAD. + +2.8.1.3 'bfd_openr_next_archived_file' +...................................... + +*Synopsis* + bfd *bfd_openr_next_archived_file (bfd *archive, bfd *previous); + *Description* +Provided a BFD, ARCHIVE, containing an archive and NULL, open an input +BFD on the first contained element and returns that. Subsequent calls +should pass the archive and the previous return value to return a +created BFD to the next contained element. NULL is returned when there +are no more. + + +File: bfd.info, Node: Formats, Next: Relocations, Prev: Archives, Up: BFD front end + +2.9 File formats +================ + +A format is a BFD concept of high level file contents type. The formats +supported by BFD are: + + * 'bfd_object' + The BFD may contain data, symbols, relocations and debug info. + + * 'bfd_archive' + The BFD contains other BFDs and an optional index. + + * 'bfd_core' + The BFD contains the result of an executable core dump. + +2.9.1 File format functions +--------------------------- + +2.9.1.1 'bfd_check_format' +.......................... + +*Synopsis* + bfd_boolean bfd_check_format (bfd *abfd, bfd_format format); + *Description* +Verify if the file attached to the BFD ABFD is compatible with the +format FORMAT (i.e., one of 'bfd_object', 'bfd_archive' or 'bfd_core'). + + If the BFD has been set to a specific target before the call, only +the named target and format combination is checked. If the target has +not been set, or has been set to 'default', then all the known target +backends is interrogated to determine a match. If the default target +matches, it is used. If not, exactly one target must recognize the +file, or an error results. + + The function returns 'TRUE' on success, otherwise 'FALSE' with one of +the following error codes: + + * 'bfd_error_invalid_operation' - if 'format' is not one of + 'bfd_object', 'bfd_archive' or 'bfd_core'. + + * 'bfd_error_system_call' - if an error occured during a read - even + some file mismatches can cause bfd_error_system_calls. + + * 'file_not_recognised' - none of the backends recognised the file + format. + + * 'bfd_error_file_ambiguously_recognized' - more than one backend + recognised the file format. + +2.9.1.2 'bfd_check_format_matches' +.................................. + +*Synopsis* + bfd_boolean bfd_check_format_matches + (bfd *abfd, bfd_format format, char ***matching); + *Description* +Like 'bfd_check_format', except when it returns FALSE with 'bfd_errno' +set to 'bfd_error_file_ambiguously_recognized'. In that case, if +MATCHING is not NULL, it will be filled in with a NULL-terminated list +of the names of the formats that matched, allocated with 'malloc'. Then +the user may choose a format and try again. + + When done with the list that MATCHING points to, the caller should +free it. + +2.9.1.3 'bfd_set_format' +........................ + +*Synopsis* + bfd_boolean bfd_set_format (bfd *abfd, bfd_format format); + *Description* +This function sets the file format of the BFD ABFD to the format FORMAT. +If the target set in the BFD does not support the format requested, the +format is invalid, or the BFD is not open for writing, then an error +occurs. + +2.9.1.4 'bfd_format_string' +........................... + +*Synopsis* + const char *bfd_format_string (bfd_format format); + *Description* +Return a pointer to a const string 'invalid', 'object', 'archive', +'core', or 'unknown', depending upon the value of FORMAT. + + +File: bfd.info, Node: Relocations, Next: Core Files, Prev: Formats, Up: BFD front end + +2.10 Relocations +================ + +BFD maintains relocations in much the same way it maintains symbols: +they are left alone until required, then read in en-masse and translated +into an internal form. A common routine 'bfd_perform_relocation' acts +upon the canonical form to do the fixup. + + Relocations are maintained on a per section basis, while symbols are +maintained on a per BFD basis. + + All that a back end has to do to fit the BFD interface is to create a +'struct reloc_cache_entry' for each relocation in a particular section, +and fill in the right bits of the structures. + +* Menu: + +* typedef arelent:: +* howto manager:: + + +File: bfd.info, Node: typedef arelent, Next: howto manager, Prev: Relocations, Up: Relocations + +2.10.1 typedef arelent +---------------------- + +This is the structure of a relocation entry: + + + typedef enum bfd_reloc_status + { + /* No errors detected. */ + bfd_reloc_ok, + + /* The relocation was performed, but there was an overflow. */ + bfd_reloc_overflow, + + /* The address to relocate was not within the section supplied. */ + bfd_reloc_outofrange, + + /* Used by special functions. */ + bfd_reloc_continue, + + /* Unsupported relocation size requested. */ + bfd_reloc_notsupported, + + /* Unused. */ + bfd_reloc_other, + + /* The symbol to relocate against was undefined. */ + bfd_reloc_undefined, + + /* The relocation was performed, but may not be ok - presently + generated only when linking i960 coff files with i960 b.out + symbols. If this type is returned, the error_message argument + to bfd_perform_relocation will be set. */ + bfd_reloc_dangerous + } + bfd_reloc_status_type; + + + typedef struct reloc_cache_entry + { + /* A pointer into the canonical table of pointers. */ + struct bfd_symbol **sym_ptr_ptr; + + /* offset in section. */ + bfd_size_type address; + + /* addend for relocation value. */ + bfd_vma addend; + + /* Pointer to how to perform the required relocation. */ + reloc_howto_type *howto; + + } + arelent; + + *Description* +Here is a description of each of the fields within an 'arelent': + + * 'sym_ptr_ptr' + The symbol table pointer points to a pointer to the symbol associated +with the relocation request. It is the pointer into the table returned +by the back end's 'canonicalize_symtab' action. *Note Symbols::. The +symbol is referenced through a pointer to a pointer so that tools like +the linker can fix up all the symbols of the same name by modifying only +one pointer. The relocation routine looks in the symbol and uses the +base of the section the symbol is attached to and the value of the +symbol as the initial relocation offset. If the symbol pointer is zero, +then the section provided is looked up. + + * 'address' + The 'address' field gives the offset in bytes from the base of the +section data which owns the relocation record to the first byte of +relocatable information. The actual data relocated will be relative to +this point; for example, a relocation type which modifies the bottom two +bytes of a four byte word would not touch the first byte pointed to in a +big endian world. + + * 'addend' + The 'addend' is a value provided by the back end to be added (!) to +the relocation offset. Its interpretation is dependent upon the howto. +For example, on the 68k the code: + + char foo[]; + main() + { + return foo[0x12345678]; + } + + Could be compiled into: + + linkw fp,#-4 + moveb @#12345678,d0 + extbl d0 + unlk fp + rts + + This could create a reloc pointing to 'foo', but leave the offset in +the data, something like: + + RELOCATION RECORDS FOR [.text]: + offset type value + 00000006 32 _foo + + 00000000 4e56 fffc ; linkw fp,#-4 + 00000004 1039 1234 5678 ; moveb @#12345678,d0 + 0000000a 49c0 ; extbl d0 + 0000000c 4e5e ; unlk fp + 0000000e 4e75 ; rts + + Using coff and an 88k, some instructions don't have enough space in +them to represent the full address range, and pointers have to be loaded +in two parts. So you'd get something like: + + or.u r13,r0,hi16(_foo+0x12345678) + ld.b r2,r13,lo16(_foo+0x12345678) + jmp r1 + + This should create two relocs, both pointing to '_foo', and with +0x12340000 in their addend field. The data would consist of: + + RELOCATION RECORDS FOR [.text]: + offset type value + 00000002 HVRT16 _foo+0x12340000 + 00000006 LVRT16 _foo+0x12340000 + + 00000000 5da05678 ; or.u r13,r0,0x5678 + 00000004 1c4d5678 ; ld.b r2,r13,0x5678 + 00000008 f400c001 ; jmp r1 + + The relocation routine digs out the value from the data, adds it to +the addend to get the original offset, and then adds the value of +'_foo'. Note that all 32 bits have to be kept around somewhere, to cope +with carry from bit 15 to bit 16. + + One further example is the sparc and the a.out format. The sparc has +a similar problem to the 88k, in that some instructions don't have room +for an entire offset, but on the sparc the parts are created in odd +sized lumps. The designers of the a.out format chose to not use the +data within the section for storing part of the offset; all the offset +is kept within the reloc. Anything in the data should be ignored. + + save %sp,-112,%sp + sethi %hi(_foo+0x12345678),%g2 + ldsb [%g2+%lo(_foo+0x12345678)],%i0 + ret + restore + + Both relocs contain a pointer to 'foo', and the offsets contain junk. + + RELOCATION RECORDS FOR [.text]: + offset type value + 00000004 HI22 _foo+0x12345678 + 00000008 LO10 _foo+0x12345678 + + 00000000 9de3bf90 ; save %sp,-112,%sp + 00000004 05000000 ; sethi %hi(_foo+0),%g2 + 00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0 + 0000000c 81c7e008 ; ret + 00000010 81e80000 ; restore + + * 'howto' + The 'howto' field can be imagined as a relocation instruction. It is +a pointer to a structure which contains information on what to do with +all of the other information in the reloc record and data section. A +back end would normally have a relocation instruction set and turn +relocations into pointers to the correct structure on input - but it +would be possible to create each howto field on demand. + +2.10.1.1 'enum complain_overflow' +................................. + +Indicates what sort of overflow checking should be done when performing +a relocation. + + + enum complain_overflow + { + /* Do not complain on overflow. */ + complain_overflow_dont, + + /* Complain if the value overflows when considered as a signed + number one bit larger than the field. ie. A bitfield of N bits + is allowed to represent -2**n to 2**n-1. */ + complain_overflow_bitfield, + + /* Complain if the value overflows when considered as a signed + number. */ + complain_overflow_signed, + + /* Complain if the value overflows when considered as an + unsigned number. */ + complain_overflow_unsigned + }; + +2.10.1.2 'reloc_howto_type' +........................... + +The 'reloc_howto_type' is a structure which contains all the information +that libbfd needs to know to tie up a back end's data. + + struct bfd_symbol; /* Forward declaration. */ + + struct reloc_howto_struct + { + /* The type field has mainly a documentary use - the back end can + do what it wants with it, though normally the back end's + external idea of what a reloc number is stored + in this field. For example, a PC relative word relocation + in a coff environment has the type 023 - because that's + what the outside world calls a R_PCRWORD reloc. */ + unsigned int type; + + /* The value the final relocation is shifted right by. This drops + unwanted data from the relocation. */ + unsigned int rightshift; + + /* The size of the item to be relocated. This is *not* a + power-of-two measure. To get the number of bytes operated + on by a type of relocation, use bfd_get_reloc_size. */ + int size; + + /* The number of bits in the item to be relocated. This is used + when doing overflow checking. */ + unsigned int bitsize; + + /* The relocation is relative to the field being relocated. */ + bfd_boolean pc_relative; + + /* The bit position of the reloc value in the destination. + The relocated value is left shifted by this amount. */ + unsigned int bitpos; + + /* What type of overflow error should be checked for when + relocating. */ + enum complain_overflow complain_on_overflow; + + /* If this field is non null, then the supplied function is + called rather than the normal function. This allows really + strange relocation methods to be accommodated (e.g., i960 callj + instructions). */ + bfd_reloc_status_type (*special_function) + (bfd *, arelent *, struct bfd_symbol *, void *, asection *, + bfd *, char **); + + /* The textual name of the relocation type. */ + char *name; + + /* Some formats record a relocation addend in the section contents + rather than with the relocation. For ELF formats this is the + distinction between USE_REL and USE_RELA (though the code checks + for USE_REL == 1/0). The value of this field is TRUE if the + addend is recorded with the section contents; when performing a + partial link (ld -r) the section contents (the data) will be + modified. The value of this field is FALSE if addends are + recorded with the relocation (in arelent.addend); when performing + a partial link the relocation will be modified. + All relocations for all ELF USE_RELA targets should set this field + to FALSE (values of TRUE should be looked on with suspicion). + However, the converse is not true: not all relocations of all ELF + USE_REL targets set this field to TRUE. Why this is so is peculiar + to each particular target. For relocs that aren't used in partial + links (e.g. GOT stuff) it doesn't matter what this is set to. */ + bfd_boolean partial_inplace; + + /* src_mask selects the part of the instruction (or data) to be used + in the relocation sum. If the target relocations don't have an + addend in the reloc, eg. ELF USE_REL, src_mask will normally equal + dst_mask to extract the addend from the section contents. If + relocations do have an addend in the reloc, eg. ELF USE_RELA, this + field should be zero. Non-zero values for ELF USE_RELA targets are + bogus as in those cases the value in the dst_mask part of the + section contents should be treated as garbage. */ + bfd_vma src_mask; + + /* dst_mask selects which parts of the instruction (or data) are + replaced with a relocated value. */ + bfd_vma dst_mask; + + /* When some formats create PC relative instructions, they leave + the value of the pc of the place being relocated in the offset + slot of the instruction, so that a PC relative relocation can + be made just by adding in an ordinary offset (e.g., sun3 a.out). + Some formats leave the displacement part of an instruction + empty (e.g., m88k bcs); this flag signals the fact. */ + bfd_boolean pcrel_offset; + }; + +2.10.1.3 'The HOWTO Macro' +.......................... + +*Description* +The HOWTO define is horrible and will go away. + #define HOWTO(C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \ + { (unsigned) C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC } + + *Description* +And will be replaced with the totally magic way. But for the moment, we +are compatible, so do it this way. + #define NEWHOWTO(FUNCTION, NAME, SIZE, REL, IN) \ + HOWTO (0, 0, SIZE, 0, REL, 0, complain_overflow_dont, FUNCTION, \ + NAME, FALSE, 0, 0, IN) + + *Description* +This is used to fill in an empty howto entry in an array. + #define EMPTY_HOWTO(C) \ + HOWTO ((C), 0, 0, 0, FALSE, 0, complain_overflow_dont, NULL, \ + NULL, FALSE, 0, 0, FALSE) + + *Description* +Helper routine to turn a symbol into a relocation value. + #define HOWTO_PREPARE(relocation, symbol) \ + { \ + if (symbol != NULL) \ + { \ + if (bfd_is_com_section (symbol->section)) \ + { \ + relocation = 0; \ + } \ + else \ + { \ + relocation = symbol->value; \ + } \ + } \ + } + +2.10.1.4 'bfd_get_reloc_size' +............................. + +*Synopsis* + unsigned int bfd_get_reloc_size (reloc_howto_type *); + *Description* +For a reloc_howto_type that operates on a fixed number of bytes, this +returns the number of bytes operated on. + +2.10.1.5 'arelent_chain' +........................ + +*Description* +How relocs are tied together in an 'asection': + typedef struct relent_chain + { + arelent relent; + struct relent_chain *next; + } + arelent_chain; + +2.10.1.6 'bfd_check_overflow' +............................. + +*Synopsis* + bfd_reloc_status_type bfd_check_overflow + (enum complain_overflow how, + unsigned int bitsize, + unsigned int rightshift, + unsigned int addrsize, + bfd_vma relocation); + *Description* +Perform overflow checking on RELOCATION which has BITSIZE significant +bits and will be shifted right by RIGHTSHIFT bits, on a machine with +addresses containing ADDRSIZE significant bits. The result is either of +'bfd_reloc_ok' or 'bfd_reloc_overflow'. + +2.10.1.7 'bfd_perform_relocation' +................................. + +*Synopsis* + bfd_reloc_status_type bfd_perform_relocation + (bfd *abfd, + arelent *reloc_entry, + void *data, + asection *input_section, + bfd *output_bfd, + char **error_message); + *Description* +If OUTPUT_BFD is supplied to this function, the generated image will be +relocatable; the relocations are copied to the output file after they +have been changed to reflect the new state of the world. There are two +ways of reflecting the results of partial linkage in an output file: by +modifying the output data in place, and by modifying the relocation +record. Some native formats (e.g., basic a.out and basic coff) have no +way of specifying an addend in the relocation type, so the addend has to +go in the output data. This is no big deal since in these formats the +output data slot will always be big enough for the addend. Complex +reloc types with addends were invented to solve just this problem. The +ERROR_MESSAGE argument is set to an error message if this return +'bfd_reloc_dangerous'. + +2.10.1.8 'bfd_install_relocation' +................................. + +*Synopsis* + bfd_reloc_status_type bfd_install_relocation + (bfd *abfd, + arelent *reloc_entry, + void *data, bfd_vma data_start, + asection *input_section, + char **error_message); + *Description* +This looks remarkably like 'bfd_perform_relocation', except it does not +expect that the section contents have been filled in. I.e., it's +suitable for use when creating, rather than applying a relocation. + + For now, this function should be considered reserved for the +assembler. + + +File: bfd.info, Node: howto manager, Prev: typedef arelent, Up: Relocations + +2.10.2 The howto manager +------------------------ + +When an application wants to create a relocation, but doesn't know what +the target machine might call it, it can find out by using this bit of +code. + +2.10.2.1 'bfd_reloc_code_type' +.............................. + +*Description* +The insides of a reloc code. The idea is that, eventually, there will +be one enumerator for every type of relocation we ever do. Pass one of +these values to 'bfd_reloc_type_lookup', and it'll return a howto +pointer. + + This does mean that the application must determine the correct +enumerator value; you can't get a howto pointer from a random set of +attributes. + + Here are the possible values for 'enum bfd_reloc_code_real': + + -- : BFD_RELOC_64 + -- : BFD_RELOC_32 + -- : BFD_RELOC_26 + -- : BFD_RELOC_24 + -- : BFD_RELOC_16 + -- : BFD_RELOC_14 + -- : BFD_RELOC_8 + Basic absolute relocations of N bits. + -- : BFD_RELOC_64_PCREL + -- : BFD_RELOC_32_PCREL + -- : BFD_RELOC_24_PCREL + -- : BFD_RELOC_16_PCREL + -- : BFD_RELOC_12_PCREL + -- : BFD_RELOC_8_PCREL + PC-relative relocations. Sometimes these are relative to the + address of the relocation itself; sometimes they are relative to + the start of the section containing the relocation. It depends on + the specific target. + + The 24-bit relocation is used in some Intel 960 configurations. + -- : BFD_RELOC_32_SECREL + Section relative relocations. Some targets need this for DWARF2. + -- : BFD_RELOC_32_GOT_PCREL + -- : BFD_RELOC_16_GOT_PCREL + -- : BFD_RELOC_8_GOT_PCREL + -- : BFD_RELOC_32_GOTOFF + -- : BFD_RELOC_16_GOTOFF + -- : BFD_RELOC_LO16_GOTOFF + -- : BFD_RELOC_HI16_GOTOFF + -- : BFD_RELOC_HI16_S_GOTOFF + -- : BFD_RELOC_8_GOTOFF + -- : BFD_RELOC_64_PLT_PCREL + -- : BFD_RELOC_32_PLT_PCREL + -- : BFD_RELOC_24_PLT_PCREL + -- : BFD_RELOC_16_PLT_PCREL + -- : BFD_RELOC_8_PLT_PCREL + -- : BFD_RELOC_64_PLTOFF + -- : BFD_RELOC_32_PLTOFF + -- : BFD_RELOC_16_PLTOFF + -- : BFD_RELOC_LO16_PLTOFF + -- : BFD_RELOC_HI16_PLTOFF + -- : BFD_RELOC_HI16_S_PLTOFF + -- : BFD_RELOC_8_PLTOFF + For ELF. + -- : BFD_RELOC_SIZE32 + -- : BFD_RELOC_SIZE64 + Size relocations. + -- : BFD_RELOC_68K_GLOB_DAT + -- : BFD_RELOC_68K_JMP_SLOT + -- : BFD_RELOC_68K_RELATIVE + -- : BFD_RELOC_68K_TLS_GD32 + -- : BFD_RELOC_68K_TLS_GD16 + -- : BFD_RELOC_68K_TLS_GD8 + -- : BFD_RELOC_68K_TLS_LDM32 + -- : BFD_RELOC_68K_TLS_LDM16 + -- : BFD_RELOC_68K_TLS_LDM8 + -- : BFD_RELOC_68K_TLS_LDO32 + -- : BFD_RELOC_68K_TLS_LDO16 + -- : BFD_RELOC_68K_TLS_LDO8 + -- : BFD_RELOC_68K_TLS_IE32 + -- : BFD_RELOC_68K_TLS_IE16 + -- : BFD_RELOC_68K_TLS_IE8 + -- : BFD_RELOC_68K_TLS_LE32 + -- : BFD_RELOC_68K_TLS_LE16 + -- : BFD_RELOC_68K_TLS_LE8 + Relocations used by 68K ELF. + -- : BFD_RELOC_32_BASEREL + -- : BFD_RELOC_16_BASEREL + -- : BFD_RELOC_LO16_BASEREL + -- : BFD_RELOC_HI16_BASEREL + -- : BFD_RELOC_HI16_S_BASEREL + -- : BFD_RELOC_8_BASEREL + -- : BFD_RELOC_RVA + Linkage-table relative. + -- : BFD_RELOC_8_FFnn + Absolute 8-bit relocation, but used to form an address like 0xFFnn. + -- : BFD_RELOC_32_PCREL_S2 + -- : BFD_RELOC_16_PCREL_S2 + -- : BFD_RELOC_23_PCREL_S2 + These PC-relative relocations are stored as word displacements - + i.e., byte displacements shifted right two bits. The 30-bit word + displacement (<<32_PCREL_S2>> - 32 bits, shifted 2) is used on the + SPARC. (SPARC tools generally refer to this as <>.) The + signed 16-bit displacement is used on the MIPS, and the 23-bit + displacement is used on the Alpha. + -- : BFD_RELOC_HI22 + -- : BFD_RELOC_LO10 + High 22 bits and low 10 bits of 32-bit value, placed into lower + bits of the target word. These are used on the SPARC. + -- : BFD_RELOC_GPREL16 + -- : BFD_RELOC_GPREL32 + For systems that allocate a Global Pointer register, these are + displacements off that register. These relocation types are + handled specially, because the value the register will have is + decided relatively late. + -- : BFD_RELOC_I960_CALLJ + Reloc types used for i960/b.out. + -- : BFD_RELOC_NONE + -- : BFD_RELOC_SPARC_WDISP22 + -- : BFD_RELOC_SPARC22 + -- : BFD_RELOC_SPARC13 + -- : BFD_RELOC_SPARC_GOT10 + -- : BFD_RELOC_SPARC_GOT13 + -- : BFD_RELOC_SPARC_GOT22 + -- : BFD_RELOC_SPARC_PC10 + -- : BFD_RELOC_SPARC_PC22 + -- : BFD_RELOC_SPARC_WPLT30 + -- : BFD_RELOC_SPARC_COPY + -- : BFD_RELOC_SPARC_GLOB_DAT + -- : BFD_RELOC_SPARC_JMP_SLOT + -- : BFD_RELOC_SPARC_RELATIVE + -- : BFD_RELOC_SPARC_UA16 + -- : BFD_RELOC_SPARC_UA32 + -- : BFD_RELOC_SPARC_UA64 + -- : BFD_RELOC_SPARC_GOTDATA_HIX22 + -- : BFD_RELOC_SPARC_GOTDATA_LOX10 + -- : BFD_RELOC_SPARC_GOTDATA_OP_HIX22 + -- : BFD_RELOC_SPARC_GOTDATA_OP_LOX10 + -- : BFD_RELOC_SPARC_GOTDATA_OP + -- : BFD_RELOC_SPARC_JMP_IREL + -- : BFD_RELOC_SPARC_IRELATIVE + SPARC ELF relocations. There is probably some overlap with other + relocation types already defined. + -- : BFD_RELOC_SPARC_BASE13 + -- : BFD_RELOC_SPARC_BASE22 + I think these are specific to SPARC a.out (e.g., Sun 4). + -- : BFD_RELOC_SPARC_64 + -- : BFD_RELOC_SPARC_10 + -- : BFD_RELOC_SPARC_11 + -- : BFD_RELOC_SPARC_OLO10 + -- : BFD_RELOC_SPARC_HH22 + -- : BFD_RELOC_SPARC_HM10 + -- : BFD_RELOC_SPARC_LM22 + -- : BFD_RELOC_SPARC_PC_HH22 + -- : BFD_RELOC_SPARC_PC_HM10 + -- : BFD_RELOC_SPARC_PC_LM22 + -- : BFD_RELOC_SPARC_WDISP16 + -- : BFD_RELOC_SPARC_WDISP19 + -- : BFD_RELOC_SPARC_7 + -- : BFD_RELOC_SPARC_6 + -- : BFD_RELOC_SPARC_5 + -- : BFD_RELOC_SPARC_DISP64 + -- : BFD_RELOC_SPARC_PLT32 + -- : BFD_RELOC_SPARC_PLT64 + -- : BFD_RELOC_SPARC_HIX22 + -- : BFD_RELOC_SPARC_LOX10 + -- : BFD_RELOC_SPARC_H44 + -- : BFD_RELOC_SPARC_M44 + -- : BFD_RELOC_SPARC_L44 + -- : BFD_RELOC_SPARC_REGISTER + -- : BFD_RELOC_SPARC_H34 + -- : BFD_RELOC_SPARC_SIZE32 + -- : BFD_RELOC_SPARC_SIZE64 + -- : BFD_RELOC_SPARC_WDISP10 + SPARC64 relocations + -- : BFD_RELOC_SPARC_REV32 + SPARC little endian relocation + -- : BFD_RELOC_SPARC_TLS_GD_HI22 + -- : BFD_RELOC_SPARC_TLS_GD_LO10 + -- : BFD_RELOC_SPARC_TLS_GD_ADD + -- : BFD_RELOC_SPARC_TLS_GD_CALL + -- : BFD_RELOC_SPARC_TLS_LDM_HI22 + -- : BFD_RELOC_SPARC_TLS_LDM_LO10 + -- : BFD_RELOC_SPARC_TLS_LDM_ADD + -- : BFD_RELOC_SPARC_TLS_LDM_CALL + -- : BFD_RELOC_SPARC_TLS_LDO_HIX22 + -- : BFD_RELOC_SPARC_TLS_LDO_LOX10 + -- : BFD_RELOC_SPARC_TLS_LDO_ADD + -- : BFD_RELOC_SPARC_TLS_IE_HI22 + -- : BFD_RELOC_SPARC_TLS_IE_LO10 + -- : BFD_RELOC_SPARC_TLS_IE_LD + -- : BFD_RELOC_SPARC_TLS_IE_LDX + -- : BFD_RELOC_SPARC_TLS_IE_ADD + -- : BFD_RELOC_SPARC_TLS_LE_HIX22 + -- : BFD_RELOC_SPARC_TLS_LE_LOX10 + -- : BFD_RELOC_SPARC_TLS_DTPMOD32 + -- : BFD_RELOC_SPARC_TLS_DTPMOD64 + -- : BFD_RELOC_SPARC_TLS_DTPOFF32 + -- : BFD_RELOC_SPARC_TLS_DTPOFF64 + -- : BFD_RELOC_SPARC_TLS_TPOFF32 + -- : BFD_RELOC_SPARC_TLS_TPOFF64 + SPARC TLS relocations + -- : BFD_RELOC_SPU_IMM7 + -- : BFD_RELOC_SPU_IMM8 + -- : BFD_RELOC_SPU_IMM10 + -- : BFD_RELOC_SPU_IMM10W + -- : BFD_RELOC_SPU_IMM16 + -- : BFD_RELOC_SPU_IMM16W + -- : BFD_RELOC_SPU_IMM18 + -- : BFD_RELOC_SPU_PCREL9a + -- : BFD_RELOC_SPU_PCREL9b + -- : BFD_RELOC_SPU_PCREL16 + -- : BFD_RELOC_SPU_LO16 + -- : BFD_RELOC_SPU_HI16 + -- : BFD_RELOC_SPU_PPU32 + -- : BFD_RELOC_SPU_PPU64 + -- : BFD_RELOC_SPU_ADD_PIC + SPU Relocations. + -- : BFD_RELOC_ALPHA_GPDISP_HI16 + Alpha ECOFF and ELF relocations. Some of these treat the symbol or + "addend" in some special way. For GPDISP_HI16 ("gpdisp") + relocations, the symbol is ignored when writing; when reading, it + will be the absolute section symbol. The addend is the + displacement in bytes of the "lda" instruction from the "ldah" + instruction (which is at the address of this reloc). + -- : BFD_RELOC_ALPHA_GPDISP_LO16 + For GPDISP_LO16 ("ignore") relocations, the symbol is handled as + with GPDISP_HI16 relocs. The addend is ignored when writing the + relocations out, and is filled in with the file's GP value on + reading, for convenience. + -- : BFD_RELOC_ALPHA_GPDISP + The ELF GPDISP relocation is exactly the same as the GPDISP_HI16 + relocation except that there is no accompanying GPDISP_LO16 + relocation. + -- : BFD_RELOC_ALPHA_LITERAL + -- : BFD_RELOC_ALPHA_ELF_LITERAL + -- : BFD_RELOC_ALPHA_LITUSE + The Alpha LITERAL/LITUSE relocs are produced by a symbol reference; + the assembler turns it into a LDQ instruction to load the address + of the symbol, and then fills in a register in the real + instruction. + + The LITERAL reloc, at the LDQ instruction, refers to the .lita + section symbol. The addend is ignored when writing, but is filled + in with the file's GP value on reading, for convenience, as with + the GPDISP_LO16 reloc. + + The ELF_LITERAL reloc is somewhere between 16_GOTOFF and + GPDISP_LO16. It should refer to the symbol to be referenced, as + with 16_GOTOFF, but it generates output not based on the position + within the .got section, but relative to the GP value chosen for + the file during the final link stage. + + The LITUSE reloc, on the instruction using the loaded address, + gives information to the linker that it might be able to use to + optimize away some literal section references. The symbol is + ignored (read as the absolute section symbol), and the "addend" + indicates the type of instruction using the register: 1 - "memory" + fmt insn 2 - byte-manipulation (byte offset reg) 3 - jsr (target of + branch) + -- : BFD_RELOC_ALPHA_HINT + The HINT relocation indicates a value that should be filled into + the "hint" field of a jmp/jsr/ret instruction, for possible branch- + prediction logic which may be provided on some processors. + -- : BFD_RELOC_ALPHA_LINKAGE + The LINKAGE relocation outputs a linkage pair in the object file, + which is filled by the linker. + -- : BFD_RELOC_ALPHA_CODEADDR + The CODEADDR relocation outputs a STO_CA in the object file, which + is filled by the linker. + -- : BFD_RELOC_ALPHA_GPREL_HI16 + -- : BFD_RELOC_ALPHA_GPREL_LO16 + The GPREL_HI/LO relocations together form a 32-bit offset from the + GP register. + -- : BFD_RELOC_ALPHA_BRSGP + Like BFD_RELOC_23_PCREL_S2, except that the source and target must + share a common GP, and the target address is adjusted for + STO_ALPHA_STD_GPLOAD. + -- : BFD_RELOC_ALPHA_NOP + The NOP relocation outputs a NOP if the longword displacement + between two procedure entry points is < 2^21. + -- : BFD_RELOC_ALPHA_BSR + The BSR relocation outputs a BSR if the longword displacement + between two procedure entry points is < 2^21. + -- : BFD_RELOC_ALPHA_LDA + The LDA relocation outputs a LDA if the longword displacement + between two procedure entry points is < 2^16. + -- : BFD_RELOC_ALPHA_BOH + The BOH relocation outputs a BSR if the longword displacement + between two procedure entry points is < 2^21, or else a hint. + -- : BFD_RELOC_ALPHA_TLSGD + -- : BFD_RELOC_ALPHA_TLSLDM + -- : BFD_RELOC_ALPHA_DTPMOD64 + -- : BFD_RELOC_ALPHA_GOTDTPREL16 + -- : BFD_RELOC_ALPHA_DTPREL64 + -- : BFD_RELOC_ALPHA_DTPREL_HI16 + -- : BFD_RELOC_ALPHA_DTPREL_LO16 + -- : BFD_RELOC_ALPHA_DTPREL16 + -- : BFD_RELOC_ALPHA_GOTTPREL16 + -- : BFD_RELOC_ALPHA_TPREL64 + -- : BFD_RELOC_ALPHA_TPREL_HI16 + -- : BFD_RELOC_ALPHA_TPREL_LO16 + -- : BFD_RELOC_ALPHA_TPREL16 + Alpha thread-local storage relocations. + -- : BFD_RELOC_MIPS_JMP + -- : BFD_RELOC_MICROMIPS_JMP + The MIPS jump instruction. + -- : BFD_RELOC_MIPS16_JMP + The MIPS16 jump instruction. + -- : BFD_RELOC_MIPS16_GPREL + MIPS16 GP relative reloc. + -- : BFD_RELOC_HI16 + High 16 bits of 32-bit value; simple reloc. + -- : BFD_RELOC_HI16_S + High 16 bits of 32-bit value but the low 16 bits will be sign + extended and added to form the final result. If the low 16 bits + form a negative number, we need to add one to the high value to + compensate for the borrow when the low bits are added. + -- : BFD_RELOC_LO16 + Low 16 bits. + -- : BFD_RELOC_HI16_PCREL + High 16 bits of 32-bit pc-relative value + -- : BFD_RELOC_HI16_S_PCREL + High 16 bits of 32-bit pc-relative value, adjusted + -- : BFD_RELOC_LO16_PCREL + Low 16 bits of pc-relative value + -- : BFD_RELOC_MIPS16_GOT16 + -- : BFD_RELOC_MIPS16_CALL16 + Equivalent of BFD_RELOC_MIPS_*, but with the MIPS16 layout of + 16-bit immediate fields + -- : BFD_RELOC_MIPS16_HI16 + MIPS16 high 16 bits of 32-bit value. + -- : BFD_RELOC_MIPS16_HI16_S + MIPS16 high 16 bits of 32-bit value but the low 16 bits will be + sign extended and added to form the final result. If the low 16 + bits form a negative number, we need to add one to the high value + to compensate for the borrow when the low bits are added. + -- : BFD_RELOC_MIPS16_LO16 + MIPS16 low 16 bits. + -- : BFD_RELOC_MIPS16_TLS_GD + -- : BFD_RELOC_MIPS16_TLS_LDM + -- : BFD_RELOC_MIPS16_TLS_DTPREL_HI16 + -- : BFD_RELOC_MIPS16_TLS_DTPREL_LO16 + -- : BFD_RELOC_MIPS16_TLS_GOTTPREL + -- : BFD_RELOC_MIPS16_TLS_TPREL_HI16 + -- : BFD_RELOC_MIPS16_TLS_TPREL_LO16 + MIPS16 TLS relocations + -- : BFD_RELOC_MIPS_LITERAL + -- : BFD_RELOC_MICROMIPS_LITERAL + Relocation against a MIPS literal section. + -- : BFD_RELOC_MICROMIPS_7_PCREL_S1 + -- : BFD_RELOC_MICROMIPS_10_PCREL_S1 + -- : BFD_RELOC_MICROMIPS_16_PCREL_S1 + microMIPS PC-relative relocations. + -- : BFD_RELOC_MICROMIPS_GPREL16 + -- : BFD_RELOC_MICROMIPS_HI16 + -- : BFD_RELOC_MICROMIPS_HI16_S + -- : BFD_RELOC_MICROMIPS_LO16 + microMIPS versions of generic BFD relocs. + -- : BFD_RELOC_MIPS_GOT16 + -- : BFD_RELOC_MICROMIPS_GOT16 + -- : BFD_RELOC_MIPS_CALL16 + -- : BFD_RELOC_MICROMIPS_CALL16 + -- : BFD_RELOC_MIPS_GOT_HI16 + -- : BFD_RELOC_MICROMIPS_GOT_HI16 + -- : BFD_RELOC_MIPS_GOT_LO16 + -- : BFD_RELOC_MICROMIPS_GOT_LO16 + -- : BFD_RELOC_MIPS_CALL_HI16 + -- : BFD_RELOC_MICROMIPS_CALL_HI16 + -- : BFD_RELOC_MIPS_CALL_LO16 + -- : BFD_RELOC_MICROMIPS_CALL_LO16 + -- : BFD_RELOC_MIPS_SUB + -- : BFD_RELOC_MICROMIPS_SUB + -- : BFD_RELOC_MIPS_GOT_PAGE + -- : BFD_RELOC_MICROMIPS_GOT_PAGE + -- : BFD_RELOC_MIPS_GOT_OFST + -- : BFD_RELOC_MICROMIPS_GOT_OFST + -- : BFD_RELOC_MIPS_GOT_DISP + -- : BFD_RELOC_MICROMIPS_GOT_DISP + -- : BFD_RELOC_MIPS_SHIFT5 + -- : BFD_RELOC_MIPS_SHIFT6 + -- : BFD_RELOC_MIPS_INSERT_A + -- : BFD_RELOC_MIPS_INSERT_B + -- : BFD_RELOC_MIPS_DELETE + -- : BFD_RELOC_MIPS_HIGHEST + -- : BFD_RELOC_MICROMIPS_HIGHEST + -- : BFD_RELOC_MIPS_HIGHER + -- : BFD_RELOC_MICROMIPS_HIGHER + -- : BFD_RELOC_MIPS_SCN_DISP + -- : BFD_RELOC_MICROMIPS_SCN_DISP + -- : BFD_RELOC_MIPS_REL16 + -- : BFD_RELOC_MIPS_RELGOT + -- : BFD_RELOC_MIPS_JALR + -- : BFD_RELOC_MICROMIPS_JALR + -- : BFD_RELOC_MIPS_TLS_DTPMOD32 + -- : BFD_RELOC_MIPS_TLS_DTPREL32 + -- : BFD_RELOC_MIPS_TLS_DTPMOD64 + -- : BFD_RELOC_MIPS_TLS_DTPREL64 + -- : BFD_RELOC_MIPS_TLS_GD + -- : BFD_RELOC_MICROMIPS_TLS_GD + -- : BFD_RELOC_MIPS_TLS_LDM + -- : BFD_RELOC_MICROMIPS_TLS_LDM + -- : BFD_RELOC_MIPS_TLS_DTPREL_HI16 + -- : BFD_RELOC_MICROMIPS_TLS_DTPREL_HI16 + -- : BFD_RELOC_MIPS_TLS_DTPREL_LO16 + -- : BFD_RELOC_MICROMIPS_TLS_DTPREL_LO16 + -- : BFD_RELOC_MIPS_TLS_GOTTPREL + -- : BFD_RELOC_MICROMIPS_TLS_GOTTPREL + -- : BFD_RELOC_MIPS_TLS_TPREL32 + -- : BFD_RELOC_MIPS_TLS_TPREL64 + -- : BFD_RELOC_MIPS_TLS_TPREL_HI16 + -- : BFD_RELOC_MICROMIPS_TLS_TPREL_HI16 + -- : BFD_RELOC_MIPS_TLS_TPREL_LO16 + -- : BFD_RELOC_MICROMIPS_TLS_TPREL_LO16 + -- : BFD_RELOC_MIPS_EH + MIPS ELF relocations. + -- : BFD_RELOC_MIPS_COPY + -- : BFD_RELOC_MIPS_JUMP_SLOT + MIPS ELF relocations (VxWorks and PLT extensions). + -- : BFD_RELOC_MOXIE_10_PCREL + Moxie ELF relocations. + -- : BFD_RELOC_FRV_LABEL16 + -- : BFD_RELOC_FRV_LABEL24 + -- : BFD_RELOC_FRV_LO16 + -- : BFD_RELOC_FRV_HI16 + -- : BFD_RELOC_FRV_GPREL12 + -- : BFD_RELOC_FRV_GPRELU12 + -- : BFD_RELOC_FRV_GPREL32 + -- : BFD_RELOC_FRV_GPRELHI + -- : BFD_RELOC_FRV_GPRELLO + -- : BFD_RELOC_FRV_GOT12 + -- : BFD_RELOC_FRV_GOTHI + -- : BFD_RELOC_FRV_GOTLO + -- : BFD_RELOC_FRV_FUNCDESC + -- : BFD_RELOC_FRV_FUNCDESC_GOT12 + -- : BFD_RELOC_FRV_FUNCDESC_GOTHI + -- : BFD_RELOC_FRV_FUNCDESC_GOTLO + -- : BFD_RELOC_FRV_FUNCDESC_VALUE + -- : BFD_RELOC_FRV_FUNCDESC_GOTOFF12 + -- : BFD_RELOC_FRV_FUNCDESC_GOTOFFHI + -- : BFD_RELOC_FRV_FUNCDESC_GOTOFFLO + -- : BFD_RELOC_FRV_GOTOFF12 + -- : BFD_RELOC_FRV_GOTOFFHI + -- : BFD_RELOC_FRV_GOTOFFLO + -- : BFD_RELOC_FRV_GETTLSOFF + -- : BFD_RELOC_FRV_TLSDESC_VALUE + -- : BFD_RELOC_FRV_GOTTLSDESC12 + -- : BFD_RELOC_FRV_GOTTLSDESCHI + -- : BFD_RELOC_FRV_GOTTLSDESCLO + -- : BFD_RELOC_FRV_TLSMOFF12 + -- : BFD_RELOC_FRV_TLSMOFFHI + -- : BFD_RELOC_FRV_TLSMOFFLO + -- : BFD_RELOC_FRV_GOTTLSOFF12 + -- : BFD_RELOC_FRV_GOTTLSOFFHI + -- : BFD_RELOC_FRV_GOTTLSOFFLO + -- : BFD_RELOC_FRV_TLSOFF + -- : BFD_RELOC_FRV_TLSDESC_RELAX + -- : BFD_RELOC_FRV_GETTLSOFF_RELAX + -- : BFD_RELOC_FRV_TLSOFF_RELAX + -- : BFD_RELOC_FRV_TLSMOFF + Fujitsu Frv Relocations. + -- : BFD_RELOC_MN10300_GOTOFF24 + This is a 24bit GOT-relative reloc for the mn10300. + -- : BFD_RELOC_MN10300_GOT32 + This is a 32bit GOT-relative reloc for the mn10300, offset by two + bytes in the instruction. + -- : BFD_RELOC_MN10300_GOT24 + This is a 24bit GOT-relative reloc for the mn10300, offset by two + bytes in the instruction. + -- : BFD_RELOC_MN10300_GOT16 + This is a 16bit GOT-relative reloc for the mn10300, offset by two + bytes in the instruction. + -- : BFD_RELOC_MN10300_COPY + Copy symbol at runtime. + -- : BFD_RELOC_MN10300_GLOB_DAT + Create GOT entry. + -- : BFD_RELOC_MN10300_JMP_SLOT + Create PLT entry. + -- : BFD_RELOC_MN10300_RELATIVE + Adjust by program base. + -- : BFD_RELOC_MN10300_SYM_DIFF + Together with another reloc targeted at the same location, allows + for a value that is the difference of two symbols in the same + section. + -- : BFD_RELOC_MN10300_ALIGN + The addend of this reloc is an alignment power that must be + honoured at the offset's location, regardless of linker relaxation. + -- : BFD_RELOC_MN10300_TLS_GD + -- : BFD_RELOC_MN10300_TLS_LD + -- : BFD_RELOC_MN10300_TLS_LDO + -- : BFD_RELOC_MN10300_TLS_GOTIE + -- : BFD_RELOC_MN10300_TLS_IE + -- : BFD_RELOC_MN10300_TLS_LE + -- : BFD_RELOC_MN10300_TLS_DTPMOD + -- : BFD_RELOC_MN10300_TLS_DTPOFF + -- : BFD_RELOC_MN10300_TLS_TPOFF + Various TLS-related relocations. + -- : BFD_RELOC_MN10300_32_PCREL + This is a 32bit pcrel reloc for the mn10300, offset by two bytes in + the instruction. + -- : BFD_RELOC_MN10300_16_PCREL + This is a 16bit pcrel reloc for the mn10300, offset by two bytes in + the instruction. + -- : BFD_RELOC_386_GOT32 + -- : BFD_RELOC_386_PLT32 + -- : BFD_RELOC_386_COPY + -- : BFD_RELOC_386_GLOB_DAT + -- : BFD_RELOC_386_JUMP_SLOT + -- : BFD_RELOC_386_RELATIVE + -- : BFD_RELOC_386_GOTOFF + -- : BFD_RELOC_386_GOTPC + -- : BFD_RELOC_386_TLS_TPOFF + -- : BFD_RELOC_386_TLS_IE + -- : BFD_RELOC_386_TLS_GOTIE + -- : BFD_RELOC_386_TLS_LE + -- : BFD_RELOC_386_TLS_GD + -- : BFD_RELOC_386_TLS_LDM + -- : BFD_RELOC_386_TLS_LDO_32 + -- : BFD_RELOC_386_TLS_IE_32 + -- : BFD_RELOC_386_TLS_LE_32 + -- : BFD_RELOC_386_TLS_DTPMOD32 + -- : BFD_RELOC_386_TLS_DTPOFF32 + -- : BFD_RELOC_386_TLS_TPOFF32 + -- : BFD_RELOC_386_TLS_GOTDESC + -- : BFD_RELOC_386_TLS_DESC_CALL + -- : BFD_RELOC_386_TLS_DESC + -- : BFD_RELOC_386_IRELATIVE + i386/elf relocations + -- : BFD_RELOC_X86_64_GOT32 + -- : BFD_RELOC_X86_64_PLT32 + -- : BFD_RELOC_X86_64_COPY + -- : BFD_RELOC_X86_64_GLOB_DAT + -- : BFD_RELOC_X86_64_JUMP_SLOT + -- : BFD_RELOC_X86_64_RELATIVE + -- : BFD_RELOC_X86_64_GOTPCREL + -- : BFD_RELOC_X86_64_32S + -- : BFD_RELOC_X86_64_DTPMOD64 + -- : BFD_RELOC_X86_64_DTPOFF64 + -- : BFD_RELOC_X86_64_TPOFF64 + -- : BFD_RELOC_X86_64_TLSGD + -- : BFD_RELOC_X86_64_TLSLD + -- : BFD_RELOC_X86_64_DTPOFF32 + -- : BFD_RELOC_X86_64_GOTTPOFF + -- : BFD_RELOC_X86_64_TPOFF32 + -- : BFD_RELOC_X86_64_GOTOFF64 + -- : BFD_RELOC_X86_64_GOTPC32 + -- : BFD_RELOC_X86_64_GOT64 + -- : BFD_RELOC_X86_64_GOTPCREL64 + -- : BFD_RELOC_X86_64_GOTPC64 + -- : BFD_RELOC_X86_64_GOTPLT64 + -- : BFD_RELOC_X86_64_PLTOFF64 + -- : BFD_RELOC_X86_64_GOTPC32_TLSDESC + -- : BFD_RELOC_X86_64_TLSDESC_CALL + -- : BFD_RELOC_X86_64_TLSDESC + -- : BFD_RELOC_X86_64_IRELATIVE + -- : BFD_RELOC_X86_64_PC32_BND + -- : BFD_RELOC_X86_64_PLT32_BND + x86-64/elf relocations + -- : BFD_RELOC_NS32K_IMM_8 + -- : BFD_RELOC_NS32K_IMM_16 + -- : BFD_RELOC_NS32K_IMM_32 + -- : BFD_RELOC_NS32K_IMM_8_PCREL + -- : BFD_RELOC_NS32K_IMM_16_PCREL + -- : BFD_RELOC_NS32K_IMM_32_PCREL + -- : BFD_RELOC_NS32K_DISP_8 + -- : BFD_RELOC_NS32K_DISP_16 + -- : BFD_RELOC_NS32K_DISP_32 + -- : BFD_RELOC_NS32K_DISP_8_PCREL + -- : BFD_RELOC_NS32K_DISP_16_PCREL + -- : BFD_RELOC_NS32K_DISP_32_PCREL + ns32k relocations + -- : BFD_RELOC_PDP11_DISP_8_PCREL + -- : BFD_RELOC_PDP11_DISP_6_PCREL + PDP11 relocations + -- : BFD_RELOC_PJ_CODE_HI16 + -- : BFD_RELOC_PJ_CODE_LO16 + -- : BFD_RELOC_PJ_CODE_DIR16 + -- : BFD_RELOC_PJ_CODE_DIR32 + -- : BFD_RELOC_PJ_CODE_REL16 + -- : BFD_RELOC_PJ_CODE_REL32 + Picojava relocs. Not all of these appear in object files. + -- : BFD_RELOC_PPC_B26 + -- : BFD_RELOC_PPC_BA26 + -- : BFD_RELOC_PPC_TOC16 + -- : BFD_RELOC_PPC_B16 + -- : BFD_RELOC_PPC_B16_BRTAKEN + -- : BFD_RELOC_PPC_B16_BRNTAKEN + -- : BFD_RELOC_PPC_BA16 + -- : BFD_RELOC_PPC_BA16_BRTAKEN + -- : BFD_RELOC_PPC_BA16_BRNTAKEN + -- : BFD_RELOC_PPC_COPY + -- : BFD_RELOC_PPC_GLOB_DAT + -- : BFD_RELOC_PPC_JMP_SLOT + -- : BFD_RELOC_PPC_RELATIVE + -- : BFD_RELOC_PPC_LOCAL24PC + -- : BFD_RELOC_PPC_EMB_NADDR32 + -- : BFD_RELOC_PPC_EMB_NADDR16 + -- : BFD_RELOC_PPC_EMB_NADDR16_LO + -- : BFD_RELOC_PPC_EMB_NADDR16_HI + -- : BFD_RELOC_PPC_EMB_NADDR16_HA + -- : BFD_RELOC_PPC_EMB_SDAI16 + -- : BFD_RELOC_PPC_EMB_SDA2I16 + -- : BFD_RELOC_PPC_EMB_SDA2REL + -- : BFD_RELOC_PPC_EMB_SDA21 + -- : BFD_RELOC_PPC_EMB_MRKREF + -- : BFD_RELOC_PPC_EMB_RELSEC16 + -- : BFD_RELOC_PPC_EMB_RELST_LO + -- : BFD_RELOC_PPC_EMB_RELST_HI + -- : BFD_RELOC_PPC_EMB_RELST_HA + -- : BFD_RELOC_PPC_EMB_BIT_FLD + -- : BFD_RELOC_PPC_EMB_RELSDA + -- : BFD_RELOC_PPC_VLE_REL8 + -- : BFD_RELOC_PPC_VLE_REL15 + -- : BFD_RELOC_PPC_VLE_REL24 + -- : BFD_RELOC_PPC_VLE_LO16A + -- : BFD_RELOC_PPC_VLE_LO16D + -- : BFD_RELOC_PPC_VLE_HI16A + -- : BFD_RELOC_PPC_VLE_HI16D + -- : BFD_RELOC_PPC_VLE_HA16A + -- : BFD_RELOC_PPC_VLE_HA16D + -- : BFD_RELOC_PPC_VLE_SDA21 + -- : BFD_RELOC_PPC_VLE_SDA21_LO + -- : BFD_RELOC_PPC_VLE_SDAREL_LO16A + -- : BFD_RELOC_PPC_VLE_SDAREL_LO16D + -- : BFD_RELOC_PPC_VLE_SDAREL_HI16A + -- : BFD_RELOC_PPC_VLE_SDAREL_HI16D + -- : BFD_RELOC_PPC_VLE_SDAREL_HA16A + -- : BFD_RELOC_PPC_VLE_SDAREL_HA16D + -- : BFD_RELOC_PPC64_HIGHER + -- : BFD_RELOC_PPC64_HIGHER_S + -- : BFD_RELOC_PPC64_HIGHEST + -- : BFD_RELOC_PPC64_HIGHEST_S + -- : BFD_RELOC_PPC64_TOC16_LO + -- : BFD_RELOC_PPC64_TOC16_HI + -- : BFD_RELOC_PPC64_TOC16_HA + -- : BFD_RELOC_PPC64_TOC + -- : BFD_RELOC_PPC64_PLTGOT16 + -- : BFD_RELOC_PPC64_PLTGOT16_LO + -- : BFD_RELOC_PPC64_PLTGOT16_HI + -- : BFD_RELOC_PPC64_PLTGOT16_HA + -- : BFD_RELOC_PPC64_ADDR16_DS + -- : BFD_RELOC_PPC64_ADDR16_LO_DS + -- : BFD_RELOC_PPC64_GOT16_DS + -- : BFD_RELOC_PPC64_GOT16_LO_DS + -- : BFD_RELOC_PPC64_PLT16_LO_DS + -- : BFD_RELOC_PPC64_SECTOFF_DS + -- : BFD_RELOC_PPC64_SECTOFF_LO_DS + -- : BFD_RELOC_PPC64_TOC16_DS + -- : BFD_RELOC_PPC64_TOC16_LO_DS + -- : BFD_RELOC_PPC64_PLTGOT16_DS + -- : BFD_RELOC_PPC64_PLTGOT16_LO_DS + -- : BFD_RELOC_PPC64_ADDR16_HIGH + -- : BFD_RELOC_PPC64_ADDR16_HIGHA + Power(rs6000) and PowerPC relocations. + -- : BFD_RELOC_PPC_TLS + -- : BFD_RELOC_PPC_TLSGD + -- : BFD_RELOC_PPC_TLSLD + -- : BFD_RELOC_PPC_DTPMOD + -- : BFD_RELOC_PPC_TPREL16 + -- : BFD_RELOC_PPC_TPREL16_LO + -- : BFD_RELOC_PPC_TPREL16_HI + -- : BFD_RELOC_PPC_TPREL16_HA + -- : BFD_RELOC_PPC_TPREL + -- : BFD_RELOC_PPC_DTPREL16 + -- : BFD_RELOC_PPC_DTPREL16_LO + -- : BFD_RELOC_PPC_DTPREL16_HI + -- : BFD_RELOC_PPC_DTPREL16_HA + -- : BFD_RELOC_PPC_DTPREL + -- : BFD_RELOC_PPC_GOT_TLSGD16 + -- : BFD_RELOC_PPC_GOT_TLSGD16_LO + -- : BFD_RELOC_PPC_GOT_TLSGD16_HI + -- : BFD_RELOC_PPC_GOT_TLSGD16_HA + -- : BFD_RELOC_PPC_GOT_TLSLD16 + -- : BFD_RELOC_PPC_GOT_TLSLD16_LO + -- : BFD_RELOC_PPC_GOT_TLSLD16_HI + -- : BFD_RELOC_PPC_GOT_TLSLD16_HA + -- : BFD_RELOC_PPC_GOT_TPREL16 + -- : BFD_RELOC_PPC_GOT_TPREL16_LO + -- : BFD_RELOC_PPC_GOT_TPREL16_HI + -- : BFD_RELOC_PPC_GOT_TPREL16_HA + -- : BFD_RELOC_PPC_GOT_DTPREL16 + -- : BFD_RELOC_PPC_GOT_DTPREL16_LO + -- : BFD_RELOC_PPC_GOT_DTPREL16_HI + -- : BFD_RELOC_PPC_GOT_DTPREL16_HA + -- : BFD_RELOC_PPC64_TPREL16_DS + -- : BFD_RELOC_PPC64_TPREL16_LO_DS + -- : BFD_RELOC_PPC64_TPREL16_HIGHER + -- : BFD_RELOC_PPC64_TPREL16_HIGHERA + -- : BFD_RELOC_PPC64_TPREL16_HIGHEST + -- : BFD_RELOC_PPC64_TPREL16_HIGHESTA + -- : BFD_RELOC_PPC64_DTPREL16_DS + -- : BFD_RELOC_PPC64_DTPREL16_LO_DS + -- : BFD_RELOC_PPC64_DTPREL16_HIGHER + -- : BFD_RELOC_PPC64_DTPREL16_HIGHERA + -- : BFD_RELOC_PPC64_DTPREL16_HIGHEST + -- : BFD_RELOC_PPC64_DTPREL16_HIGHESTA + -- : BFD_RELOC_PPC64_TPREL16_HIGH + -- : BFD_RELOC_PPC64_TPREL16_HIGHA + -- : BFD_RELOC_PPC64_DTPREL16_HIGH + -- : BFD_RELOC_PPC64_DTPREL16_HIGHA + PowerPC and PowerPC64 thread-local storage relocations. + -- : BFD_RELOC_I370_D12 + IBM 370/390 relocations + -- : BFD_RELOC_CTOR + The type of reloc used to build a constructor table - at the moment + probably a 32 bit wide absolute relocation, but the target can + choose. It generally does map to one of the other relocation + types. + -- : BFD_RELOC_ARM_PCREL_BRANCH + ARM 26 bit pc-relative branch. The lowest two bits must be zero + and are not stored in the instruction. + -- : BFD_RELOC_ARM_PCREL_BLX + ARM 26 bit pc-relative branch. The lowest bit must be zero and is + not stored in the instruction. The 2nd lowest bit comes from a 1 + bit field in the instruction. + -- : BFD_RELOC_THUMB_PCREL_BLX + Thumb 22 bit pc-relative branch. The lowest bit must be zero and + is not stored in the instruction. The 2nd lowest bit comes from a + 1 bit field in the instruction. + -- : BFD_RELOC_ARM_PCREL_CALL + ARM 26-bit pc-relative branch for an unconditional BL or BLX + instruction. + -- : BFD_RELOC_ARM_PCREL_JUMP + ARM 26-bit pc-relative branch for B or conditional BL instruction. + -- : BFD_RELOC_THUMB_PCREL_BRANCH7 + -- : BFD_RELOC_THUMB_PCREL_BRANCH9 + -- : BFD_RELOC_THUMB_PCREL_BRANCH12 + -- : BFD_RELOC_THUMB_PCREL_BRANCH20 + -- : BFD_RELOC_THUMB_PCREL_BRANCH23 + -- : BFD_RELOC_THUMB_PCREL_BRANCH25 + Thumb 7-, 9-, 12-, 20-, 23-, and 25-bit pc-relative branches. The + lowest bit must be zero and is not stored in the instruction. Note + that the corresponding ELF R_ARM_THM_JUMPnn constant has an "nn" + one smaller in all cases. Note further that BRANCH23 corresponds + to R_ARM_THM_CALL. + -- : BFD_RELOC_ARM_OFFSET_IMM + 12-bit immediate offset, used in ARM-format ldr and str + instructions. + -- : BFD_RELOC_ARM_THUMB_OFFSET + 5-bit immediate offset, used in Thumb-format ldr and str + instructions. + -- : BFD_RELOC_ARM_TARGET1 + Pc-relative or absolute relocation depending on target. Used for + entries in .init_array sections. + -- : BFD_RELOC_ARM_ROSEGREL32 + Read-only segment base relative address. + -- : BFD_RELOC_ARM_SBREL32 + Data segment base relative address. + -- : BFD_RELOC_ARM_TARGET2 + This reloc is used for references to RTTI data from exception + handling tables. The actual definition depends on the target. It + may be a pc-relative or some form of GOT-indirect relocation. + -- : BFD_RELOC_ARM_PREL31 + 31-bit PC relative address. + -- : BFD_RELOC_ARM_MOVW + -- : BFD_RELOC_ARM_MOVT + -- : BFD_RELOC_ARM_MOVW_PCREL + -- : BFD_RELOC_ARM_MOVT_PCREL + -- : BFD_RELOC_ARM_THUMB_MOVW + -- : BFD_RELOC_ARM_THUMB_MOVT + -- : BFD_RELOC_ARM_THUMB_MOVW_PCREL + -- : BFD_RELOC_ARM_THUMB_MOVT_PCREL + Low and High halfword relocations for MOVW and MOVT instructions. + -- : BFD_RELOC_ARM_JUMP_SLOT + -- : BFD_RELOC_ARM_GLOB_DAT + -- : BFD_RELOC_ARM_GOT32 + -- : BFD_RELOC_ARM_PLT32 + -- : BFD_RELOC_ARM_RELATIVE + -- : BFD_RELOC_ARM_GOTOFF + -- : BFD_RELOC_ARM_GOTPC + -- : BFD_RELOC_ARM_GOT_PREL + Relocations for setting up GOTs and PLTs for shared libraries. + -- : BFD_RELOC_ARM_TLS_GD32 + -- : BFD_RELOC_ARM_TLS_LDO32 + -- : BFD_RELOC_ARM_TLS_LDM32 + -- : BFD_RELOC_ARM_TLS_DTPOFF32 + -- : BFD_RELOC_ARM_TLS_DTPMOD32 + -- : BFD_RELOC_ARM_TLS_TPOFF32 + -- : BFD_RELOC_ARM_TLS_IE32 + -- : BFD_RELOC_ARM_TLS_LE32 + -- : BFD_RELOC_ARM_TLS_GOTDESC + -- : BFD_RELOC_ARM_TLS_CALL + -- : BFD_RELOC_ARM_THM_TLS_CALL + -- : BFD_RELOC_ARM_TLS_DESCSEQ + -- : BFD_RELOC_ARM_THM_TLS_DESCSEQ + -- : BFD_RELOC_ARM_TLS_DESC + ARM thread-local storage relocations. + -- : BFD_RELOC_ARM_ALU_PC_G0_NC + -- : BFD_RELOC_ARM_ALU_PC_G0 + -- : BFD_RELOC_ARM_ALU_PC_G1_NC + -- : BFD_RELOC_ARM_ALU_PC_G1 + -- : BFD_RELOC_ARM_ALU_PC_G2 + -- : BFD_RELOC_ARM_LDR_PC_G0 + -- : BFD_RELOC_ARM_LDR_PC_G1 + -- : BFD_RELOC_ARM_LDR_PC_G2 + -- : BFD_RELOC_ARM_LDRS_PC_G0 + -- : BFD_RELOC_ARM_LDRS_PC_G1 + -- : BFD_RELOC_ARM_LDRS_PC_G2 + -- : BFD_RELOC_ARM_LDC_PC_G0 + -- : BFD_RELOC_ARM_LDC_PC_G1 + -- : BFD_RELOC_ARM_LDC_PC_G2 + -- : BFD_RELOC_ARM_ALU_SB_G0_NC + -- : BFD_RELOC_ARM_ALU_SB_G0 + -- : BFD_RELOC_ARM_ALU_SB_G1_NC + -- : BFD_RELOC_ARM_ALU_SB_G1 + -- : BFD_RELOC_ARM_ALU_SB_G2 + -- : BFD_RELOC_ARM_LDR_SB_G0 + -- : BFD_RELOC_ARM_LDR_SB_G1 + -- : BFD_RELOC_ARM_LDR_SB_G2 + -- : BFD_RELOC_ARM_LDRS_SB_G0 + -- : BFD_RELOC_ARM_LDRS_SB_G1 + -- : BFD_RELOC_ARM_LDRS_SB_G2 + -- : BFD_RELOC_ARM_LDC_SB_G0 + -- : BFD_RELOC_ARM_LDC_SB_G1 + -- : BFD_RELOC_ARM_LDC_SB_G2 + ARM group relocations. + -- : BFD_RELOC_ARM_V4BX + Annotation of BX instructions. + -- : BFD_RELOC_ARM_IRELATIVE + ARM support for STT_GNU_IFUNC. + -- : BFD_RELOC_ARM_IMMEDIATE + -- : BFD_RELOC_ARM_ADRL_IMMEDIATE + -- : BFD_RELOC_ARM_T32_IMMEDIATE + -- : BFD_RELOC_ARM_T32_ADD_IMM + -- : BFD_RELOC_ARM_T32_IMM12 + -- : BFD_RELOC_ARM_T32_ADD_PC12 + -- : BFD_RELOC_ARM_SHIFT_IMM + -- : BFD_RELOC_ARM_SMC + -- : BFD_RELOC_ARM_HVC + -- : BFD_RELOC_ARM_SWI + -- : BFD_RELOC_ARM_MULTI + -- : BFD_RELOC_ARM_CP_OFF_IMM + -- : BFD_RELOC_ARM_CP_OFF_IMM_S2 + -- : BFD_RELOC_ARM_T32_CP_OFF_IMM + -- : BFD_RELOC_ARM_T32_CP_OFF_IMM_S2 + -- : BFD_RELOC_ARM_ADR_IMM + -- : BFD_RELOC_ARM_LDR_IMM + -- : BFD_RELOC_ARM_LITERAL + -- : BFD_RELOC_ARM_IN_POOL + -- : BFD_RELOC_ARM_OFFSET_IMM8 + -- : BFD_RELOC_ARM_T32_OFFSET_U8 + -- : BFD_RELOC_ARM_T32_OFFSET_IMM + -- : BFD_RELOC_ARM_HWLITERAL + -- : BFD_RELOC_ARM_THUMB_ADD + -- : BFD_RELOC_ARM_THUMB_IMM + -- : BFD_RELOC_ARM_THUMB_SHIFT + These relocs are only used within the ARM assembler. They are not + (at present) written to any object files. + -- : BFD_RELOC_SH_PCDISP8BY2 + -- : BFD_RELOC_SH_PCDISP12BY2 + -- : BFD_RELOC_SH_IMM3 + -- : BFD_RELOC_SH_IMM3U + -- : BFD_RELOC_SH_DISP12 + -- : BFD_RELOC_SH_DISP12BY2 + -- : BFD_RELOC_SH_DISP12BY4 + -- : BFD_RELOC_SH_DISP12BY8 + -- : BFD_RELOC_SH_DISP20 + -- : BFD_RELOC_SH_DISP20BY8 + -- : BFD_RELOC_SH_IMM4 + -- : BFD_RELOC_SH_IMM4BY2 + -- : BFD_RELOC_SH_IMM4BY4 + -- : BFD_RELOC_SH_IMM8 + -- : BFD_RELOC_SH_IMM8BY2 + -- : BFD_RELOC_SH_IMM8BY4 + -- : BFD_RELOC_SH_PCRELIMM8BY2 + -- : BFD_RELOC_SH_PCRELIMM8BY4 + -- : BFD_RELOC_SH_SWITCH16 + -- : BFD_RELOC_SH_SWITCH32 + -- : BFD_RELOC_SH_USES + -- : BFD_RELOC_SH_COUNT + -- : BFD_RELOC_SH_ALIGN + -- : BFD_RELOC_SH_CODE + -- : BFD_RELOC_SH_DATA + -- : BFD_RELOC_SH_LABEL + -- : BFD_RELOC_SH_LOOP_START + -- : BFD_RELOC_SH_LOOP_END + -- : BFD_RELOC_SH_COPY + -- : BFD_RELOC_SH_GLOB_DAT + -- : BFD_RELOC_SH_JMP_SLOT + -- : BFD_RELOC_SH_RELATIVE + -- : BFD_RELOC_SH_GOTPC + -- : BFD_RELOC_SH_GOT_LOW16 + -- : BFD_RELOC_SH_GOT_MEDLOW16 + -- : BFD_RELOC_SH_GOT_MEDHI16 + -- : BFD_RELOC_SH_GOT_HI16 + -- : BFD_RELOC_SH_GOTPLT_LOW16 + -- : BFD_RELOC_SH_GOTPLT_MEDLOW16 + -- : BFD_RELOC_SH_GOTPLT_MEDHI16 + -- : BFD_RELOC_SH_GOTPLT_HI16 + -- : BFD_RELOC_SH_PLT_LOW16 + -- : BFD_RELOC_SH_PLT_MEDLOW16 + -- : BFD_RELOC_SH_PLT_MEDHI16 + -- : BFD_RELOC_SH_PLT_HI16 + -- : BFD_RELOC_SH_GOTOFF_LOW16 + -- : BFD_RELOC_SH_GOTOFF_MEDLOW16 + -- : BFD_RELOC_SH_GOTOFF_MEDHI16 + -- : BFD_RELOC_SH_GOTOFF_HI16 + -- : BFD_RELOC_SH_GOTPC_LOW16 + -- : BFD_RELOC_SH_GOTPC_MEDLOW16 + -- : BFD_RELOC_SH_GOTPC_MEDHI16 + -- : BFD_RELOC_SH_GOTPC_HI16 + -- : BFD_RELOC_SH_COPY64 + -- : BFD_RELOC_SH_GLOB_DAT64 + -- : BFD_RELOC_SH_JMP_SLOT64 + -- : BFD_RELOC_SH_RELATIVE64 + -- : BFD_RELOC_SH_GOT10BY4 + -- : BFD_RELOC_SH_GOT10BY8 + -- : BFD_RELOC_SH_GOTPLT10BY4 + -- : BFD_RELOC_SH_GOTPLT10BY8 + -- : BFD_RELOC_SH_GOTPLT32 + -- : BFD_RELOC_SH_SHMEDIA_CODE + -- : BFD_RELOC_SH_IMMU5 + -- : BFD_RELOC_SH_IMMS6 + -- : BFD_RELOC_SH_IMMS6BY32 + -- : BFD_RELOC_SH_IMMU6 + -- : BFD_RELOC_SH_IMMS10 + -- : BFD_RELOC_SH_IMMS10BY2 + -- : BFD_RELOC_SH_IMMS10BY4 + -- : BFD_RELOC_SH_IMMS10BY8 + -- : BFD_RELOC_SH_IMMS16 + -- : BFD_RELOC_SH_IMMU16 + -- : BFD_RELOC_SH_IMM_LOW16 + -- : BFD_RELOC_SH_IMM_LOW16_PCREL + -- : BFD_RELOC_SH_IMM_MEDLOW16 + -- : BFD_RELOC_SH_IMM_MEDLOW16_PCREL + -- : BFD_RELOC_SH_IMM_MEDHI16 + -- : BFD_RELOC_SH_IMM_MEDHI16_PCREL + -- : BFD_RELOC_SH_IMM_HI16 + -- : BFD_RELOC_SH_IMM_HI16_PCREL + -- : BFD_RELOC_SH_PT_16 + -- : BFD_RELOC_SH_TLS_GD_32 + -- : BFD_RELOC_SH_TLS_LD_32 + -- : BFD_RELOC_SH_TLS_LDO_32 + -- : BFD_RELOC_SH_TLS_IE_32 + -- : BFD_RELOC_SH_TLS_LE_32 + -- : BFD_RELOC_SH_TLS_DTPMOD32 + -- : BFD_RELOC_SH_TLS_DTPOFF32 + -- : BFD_RELOC_SH_TLS_TPOFF32 + -- : BFD_RELOC_SH_GOT20 + -- : BFD_RELOC_SH_GOTOFF20 + -- : BFD_RELOC_SH_GOTFUNCDESC + -- : BFD_RELOC_SH_GOTFUNCDESC20 + -- : BFD_RELOC_SH_GOTOFFFUNCDESC + -- : BFD_RELOC_SH_GOTOFFFUNCDESC20 + -- : BFD_RELOC_SH_FUNCDESC + Renesas / SuperH SH relocs. Not all of these appear in object + files. + -- : BFD_RELOC_ARC_B22_PCREL + ARC Cores relocs. ARC 22 bit pc-relative branch. The lowest two + bits must be zero and are not stored in the instruction. The high + 20 bits are installed in bits 26 through 7 of the instruction. + -- : BFD_RELOC_ARC_B26 + ARC 26 bit absolute branch. The lowest two bits must be zero and + are not stored in the instruction. The high 24 bits are installed + in bits 23 through 0. + -- : BFD_RELOC_BFIN_16_IMM + ADI Blackfin 16 bit immediate absolute reloc. + -- : BFD_RELOC_BFIN_16_HIGH + ADI Blackfin 16 bit immediate absolute reloc higher 16 bits. + -- : BFD_RELOC_BFIN_4_PCREL + ADI Blackfin 'a' part of LSETUP. + -- : BFD_RELOC_BFIN_5_PCREL + ADI Blackfin. + -- : BFD_RELOC_BFIN_16_LOW + ADI Blackfin 16 bit immediate absolute reloc lower 16 bits. + -- : BFD_RELOC_BFIN_10_PCREL + ADI Blackfin. + -- : BFD_RELOC_BFIN_11_PCREL + ADI Blackfin 'b' part of LSETUP. + -- : BFD_RELOC_BFIN_12_PCREL_JUMP + ADI Blackfin. + -- : BFD_RELOC_BFIN_12_PCREL_JUMP_S + ADI Blackfin Short jump, pcrel. + -- : BFD_RELOC_BFIN_24_PCREL_CALL_X + ADI Blackfin Call.x not implemented. + -- : BFD_RELOC_BFIN_24_PCREL_JUMP_L + ADI Blackfin Long Jump pcrel. + -- : BFD_RELOC_BFIN_GOT17M4 + -- : BFD_RELOC_BFIN_GOTHI + -- : BFD_RELOC_BFIN_GOTLO + -- : BFD_RELOC_BFIN_FUNCDESC + -- : BFD_RELOC_BFIN_FUNCDESC_GOT17M4 + -- : BFD_RELOC_BFIN_FUNCDESC_GOTHI + -- : BFD_RELOC_BFIN_FUNCDESC_GOTLO + -- : BFD_RELOC_BFIN_FUNCDESC_VALUE + -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4 + -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI + -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO + -- : BFD_RELOC_BFIN_GOTOFF17M4 + -- : BFD_RELOC_BFIN_GOTOFFHI + -- : BFD_RELOC_BFIN_GOTOFFLO + ADI Blackfin FD-PIC relocations. + -- : BFD_RELOC_BFIN_GOT + ADI Blackfin GOT relocation. + -- : BFD_RELOC_BFIN_PLTPC + ADI Blackfin PLTPC relocation. + -- : BFD_ARELOC_BFIN_PUSH + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_CONST + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_ADD + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_SUB + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_MULT + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_DIV + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_MOD + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_LSHIFT + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_RSHIFT + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_AND + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_OR + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_XOR + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_LAND + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_LOR + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_LEN + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_NEG + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_COMP + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_PAGE + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_HWPAGE + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_ADDR + ADI Blackfin arithmetic relocation. + -- : BFD_RELOC_D10V_10_PCREL_R + Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2 + bits assumed to be 0. + -- : BFD_RELOC_D10V_10_PCREL_L + Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2 + bits assumed to be 0. This is the same as the previous reloc + except it is in the left container, i.e., shifted left 15 bits. + -- : BFD_RELOC_D10V_18 + This is an 18-bit reloc with the right 2 bits assumed to be 0. + -- : BFD_RELOC_D10V_18_PCREL + This is an 18-bit reloc with the right 2 bits assumed to be 0. + -- : BFD_RELOC_D30V_6 + Mitsubishi D30V relocs. This is a 6-bit absolute reloc. + -- : BFD_RELOC_D30V_9_PCREL + This is a 6-bit pc-relative reloc with the right 3 bits assumed to + be 0. + -- : BFD_RELOC_D30V_9_PCREL_R + This is a 6-bit pc-relative reloc with the right 3 bits assumed to + be 0. Same as the previous reloc but on the right side of the + container. + -- : BFD_RELOC_D30V_15 + This is a 12-bit absolute reloc with the right 3 bitsassumed to be + 0. + -- : BFD_RELOC_D30V_15_PCREL + This is a 12-bit pc-relative reloc with the right 3 bits assumed to + be 0. + -- : BFD_RELOC_D30V_15_PCREL_R + This is a 12-bit pc-relative reloc with the right 3 bits assumed to + be 0. Same as the previous reloc but on the right side of the + container. + -- : BFD_RELOC_D30V_21 + This is an 18-bit absolute reloc with the right 3 bits assumed to + be 0. + -- : BFD_RELOC_D30V_21_PCREL + This is an 18-bit pc-relative reloc with the right 3 bits assumed + to be 0. + -- : BFD_RELOC_D30V_21_PCREL_R + This is an 18-bit pc-relative reloc with the right 3 bits assumed + to be 0. Same as the previous reloc but on the right side of the + container. + -- : BFD_RELOC_D30V_32 + This is a 32-bit absolute reloc. + -- : BFD_RELOC_D30V_32_PCREL + This is a 32-bit pc-relative reloc. + -- : BFD_RELOC_DLX_HI16_S + DLX relocs + -- : BFD_RELOC_DLX_LO16 + DLX relocs + -- : BFD_RELOC_DLX_JMP26 + DLX relocs + -- : BFD_RELOC_M32C_HI8 + -- : BFD_RELOC_M32C_RL_JUMP + -- : BFD_RELOC_M32C_RL_1ADDR + -- : BFD_RELOC_M32C_RL_2ADDR + Renesas M16C/M32C Relocations. + -- : BFD_RELOC_M32R_24 + Renesas M32R (formerly Mitsubishi M32R) relocs. This is a 24 bit + absolute address. + -- : BFD_RELOC_M32R_10_PCREL + This is a 10-bit pc-relative reloc with the right 2 bits assumed to + be 0. + -- : BFD_RELOC_M32R_18_PCREL + This is an 18-bit reloc with the right 2 bits assumed to be 0. + -- : BFD_RELOC_M32R_26_PCREL + This is a 26-bit reloc with the right 2 bits assumed to be 0. + -- : BFD_RELOC_M32R_HI16_ULO + This is a 16-bit reloc containing the high 16 bits of an address + used when the lower 16 bits are treated as unsigned. + -- : BFD_RELOC_M32R_HI16_SLO + This is a 16-bit reloc containing the high 16 bits of an address + used when the lower 16 bits are treated as signed. + -- : BFD_RELOC_M32R_LO16 + This is a 16-bit reloc containing the lower 16 bits of an address. + -- : BFD_RELOC_M32R_SDA16 + This is a 16-bit reloc containing the small data area offset for + use in add3, load, and store instructions. + -- : BFD_RELOC_M32R_GOT24 + -- : BFD_RELOC_M32R_26_PLTREL + -- : BFD_RELOC_M32R_COPY + -- : BFD_RELOC_M32R_GLOB_DAT + -- : BFD_RELOC_M32R_JMP_SLOT + -- : BFD_RELOC_M32R_RELATIVE + -- : BFD_RELOC_M32R_GOTOFF + -- : BFD_RELOC_M32R_GOTOFF_HI_ULO + -- : BFD_RELOC_M32R_GOTOFF_HI_SLO + -- : BFD_RELOC_M32R_GOTOFF_LO + -- : BFD_RELOC_M32R_GOTPC24 + -- : BFD_RELOC_M32R_GOT16_HI_ULO + -- : BFD_RELOC_M32R_GOT16_HI_SLO + -- : BFD_RELOC_M32R_GOT16_LO + -- : BFD_RELOC_M32R_GOTPC_HI_ULO + -- : BFD_RELOC_M32R_GOTPC_HI_SLO + -- : BFD_RELOC_M32R_GOTPC_LO + For PIC. + -- : BFD_RELOC_NDS32_20 + NDS32 relocs. This is a 20 bit absolute address. + -- : BFD_RELOC_NDS32_9_PCREL + This is a 9-bit pc-relative reloc with the right 1 bit assumed to + be 0. + -- : BFD_RELOC_NDS32_WORD_9_PCREL + This is a 9-bit pc-relative reloc with the right 1 bit assumed to + be 0. + -- : BFD_RELOC_NDS32_15_PCREL + This is an 15-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_NDS32_17_PCREL + This is an 17-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_NDS32_25_PCREL + This is a 25-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_NDS32_HI20 + This is a 20-bit reloc containing the high 20 bits of an address + used with the lower 12 bits + -- : BFD_RELOC_NDS32_LO12S3 + This is a 12-bit reloc containing the lower 12 bits of an address + then shift right by 3. This is used with ldi,sdi... + -- : BFD_RELOC_NDS32_LO12S2 + This is a 12-bit reloc containing the lower 12 bits of an address + then shift left by 2. This is used with lwi,swi... + -- : BFD_RELOC_NDS32_LO12S1 + This is a 12-bit reloc containing the lower 12 bits of an address + then shift left by 1. This is used with lhi,shi... + -- : BFD_RELOC_NDS32_LO12S0 + This is a 12-bit reloc containing the lower 12 bits of an address + then shift left by 0. This is used with lbisbi... + -- : BFD_RELOC_NDS32_LO12S0_ORI + This is a 12-bit reloc containing the lower 12 bits of an address + then shift left by 0. This is only used with branch relaxations + -- : BFD_RELOC_NDS32_SDA15S3 + This is a 15-bit reloc containing the small data area 18-bit signed + offset and shift left by 3 for use in ldi, sdi... + -- : BFD_RELOC_NDS32_SDA15S2 + This is a 15-bit reloc containing the small data area 17-bit signed + offset and shift left by 2 for use in lwi, swi... + -- : BFD_RELOC_NDS32_SDA15S1 + This is a 15-bit reloc containing the small data area 16-bit signed + offset and shift left by 1 for use in lhi, shi... + -- : BFD_RELOC_NDS32_SDA15S0 + This is a 15-bit reloc containing the small data area 15-bit signed + offset and shift left by 0 for use in lbi, sbi... + -- : BFD_RELOC_NDS32_SDA16S3 + This is a 16-bit reloc containing the small data area 16-bit signed + offset and shift left by 3 + -- : BFD_RELOC_NDS32_SDA17S2 + This is a 17-bit reloc containing the small data area 17-bit signed + offset and shift left by 2 for use in lwi.gp, swi.gp... + -- : BFD_RELOC_NDS32_SDA18S1 + This is a 18-bit reloc containing the small data area 18-bit signed + offset and shift left by 1 for use in lhi.gp, shi.gp... + -- : BFD_RELOC_NDS32_SDA19S0 + This is a 19-bit reloc containing the small data area 19-bit signed + offset and shift left by 0 for use in lbi.gp, sbi.gp... + -- : BFD_RELOC_NDS32_GOT20 + -- : BFD_RELOC_NDS32_9_PLTREL + -- : BFD_RELOC_NDS32_25_PLTREL + -- : BFD_RELOC_NDS32_COPY + -- : BFD_RELOC_NDS32_GLOB_DAT + -- : BFD_RELOC_NDS32_JMP_SLOT + -- : BFD_RELOC_NDS32_RELATIVE + -- : BFD_RELOC_NDS32_GOTOFF + -- : BFD_RELOC_NDS32_GOTOFF_HI20 + -- : BFD_RELOC_NDS32_GOTOFF_LO12 + -- : BFD_RELOC_NDS32_GOTPC20 + -- : BFD_RELOC_NDS32_GOT_HI20 + -- : BFD_RELOC_NDS32_GOT_LO12 + -- : BFD_RELOC_NDS32_GOTPC_HI20 + -- : BFD_RELOC_NDS32_GOTPC_LO12 + for PIC + -- : BFD_RELOC_NDS32_INSN16 + -- : BFD_RELOC_NDS32_LABEL + -- : BFD_RELOC_NDS32_LONGCALL1 + -- : BFD_RELOC_NDS32_LONGCALL2 + -- : BFD_RELOC_NDS32_LONGCALL3 + -- : BFD_RELOC_NDS32_LONGJUMP1 + -- : BFD_RELOC_NDS32_LONGJUMP2 + -- : BFD_RELOC_NDS32_LONGJUMP3 + -- : BFD_RELOC_NDS32_LOADSTORE + -- : BFD_RELOC_NDS32_9_FIXED + -- : BFD_RELOC_NDS32_15_FIXED + -- : BFD_RELOC_NDS32_17_FIXED + -- : BFD_RELOC_NDS32_25_FIXED + for relax + -- : BFD_RELOC_NDS32_PLTREL_HI20 + -- : BFD_RELOC_NDS32_PLTREL_LO12 + -- : BFD_RELOC_NDS32_PLT_GOTREL_HI20 + -- : BFD_RELOC_NDS32_PLT_GOTREL_LO12 + for PIC + -- : BFD_RELOC_NDS32_SDA12S2_DP + -- : BFD_RELOC_NDS32_SDA12S2_SP + -- : BFD_RELOC_NDS32_LO12S2_DP + -- : BFD_RELOC_NDS32_LO12S2_SP + for floating point + -- : BFD_RELOC_NDS32_DWARF2_OP1 + -- : BFD_RELOC_NDS32_DWARF2_OP2 + -- : BFD_RELOC_NDS32_DWARF2_LEB + for dwarf2 debug_line. + -- : BFD_RELOC_NDS32_UPDATE_TA + for eliminate 16-bit instructions + -- : BFD_RELOC_NDS32_PLT_GOTREL_LO20 + -- : BFD_RELOC_NDS32_PLT_GOTREL_LO15 + -- : BFD_RELOC_NDS32_PLT_GOTREL_LO19 + -- : BFD_RELOC_NDS32_GOT_LO15 + -- : BFD_RELOC_NDS32_GOT_LO19 + -- : BFD_RELOC_NDS32_GOTOFF_LO15 + -- : BFD_RELOC_NDS32_GOTOFF_LO19 + -- : BFD_RELOC_NDS32_GOT15S2 + -- : BFD_RELOC_NDS32_GOT17S2 + for PIC object relaxation + -- : BFD_RELOC_NDS32_5 + NDS32 relocs. This is a 5 bit absolute address. + -- : BFD_RELOC_NDS32_10_UPCREL + This is a 10-bit unsigned pc-relative reloc with the right 1 bit + assumed to be 0. + -- : BFD_RELOC_NDS32_SDA_FP7U2_RELA + If fp were omitted, fp can used as another gp. + -- : BFD_RELOC_NDS32_RELAX_ENTRY + -- : BFD_RELOC_NDS32_GOT_SUFF + -- : BFD_RELOC_NDS32_GOTOFF_SUFF + -- : BFD_RELOC_NDS32_PLT_GOT_SUFF + -- : BFD_RELOC_NDS32_MULCALL_SUFF + -- : BFD_RELOC_NDS32_PTR + -- : BFD_RELOC_NDS32_PTR_COUNT + -- : BFD_RELOC_NDS32_PTR_RESOLVED + -- : BFD_RELOC_NDS32_PLTBLOCK + -- : BFD_RELOC_NDS32_RELAX_REGION_BEGIN + -- : BFD_RELOC_NDS32_RELAX_REGION_END + -- : BFD_RELOC_NDS32_MINUEND + -- : BFD_RELOC_NDS32_SUBTRAHEND + -- : BFD_RELOC_NDS32_DIFF8 + -- : BFD_RELOC_NDS32_DIFF16 + -- : BFD_RELOC_NDS32_DIFF32 + -- : BFD_RELOC_NDS32_DIFF_ULEB128 + -- : BFD_RELOC_NDS32_25_ABS + -- : BFD_RELOC_NDS32_DATA + -- : BFD_RELOC_NDS32_TRAN + -- : BFD_RELOC_NDS32_17IFC_PCREL + -- : BFD_RELOC_NDS32_10IFCU_PCREL + relaxation relative relocation types + -- : BFD_RELOC_V850_9_PCREL + This is a 9-bit reloc + -- : BFD_RELOC_V850_22_PCREL + This is a 22-bit reloc + -- : BFD_RELOC_V850_SDA_16_16_OFFSET + This is a 16 bit offset from the short data area pointer. + -- : BFD_RELOC_V850_SDA_15_16_OFFSET + This is a 16 bit offset (of which only 15 bits are used) from the + short data area pointer. + -- : BFD_RELOC_V850_ZDA_16_16_OFFSET + This is a 16 bit offset from the zero data area pointer. + -- : BFD_RELOC_V850_ZDA_15_16_OFFSET + This is a 16 bit offset (of which only 15 bits are used) from the + zero data area pointer. + -- : BFD_RELOC_V850_TDA_6_8_OFFSET + This is an 8 bit offset (of which only 6 bits are used) from the + tiny data area pointer. + -- : BFD_RELOC_V850_TDA_7_8_OFFSET + This is an 8bit offset (of which only 7 bits are used) from the + tiny data area pointer. + -- : BFD_RELOC_V850_TDA_7_7_OFFSET + This is a 7 bit offset from the tiny data area pointer. + -- : BFD_RELOC_V850_TDA_16_16_OFFSET + This is a 16 bit offset from the tiny data area pointer. + -- : BFD_RELOC_V850_TDA_4_5_OFFSET + This is a 5 bit offset (of which only 4 bits are used) from the + tiny data area pointer. + -- : BFD_RELOC_V850_TDA_4_4_OFFSET + This is a 4 bit offset from the tiny data area pointer. + -- : BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET + This is a 16 bit offset from the short data area pointer, with the + bits placed non-contiguously in the instruction. + -- : BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET + This is a 16 bit offset from the zero data area pointer, with the + bits placed non-contiguously in the instruction. + -- : BFD_RELOC_V850_CALLT_6_7_OFFSET + This is a 6 bit offset from the call table base pointer. + -- : BFD_RELOC_V850_CALLT_16_16_OFFSET + This is a 16 bit offset from the call table base pointer. + -- : BFD_RELOC_V850_LONGCALL + Used for relaxing indirect function calls. + -- : BFD_RELOC_V850_LONGJUMP + Used for relaxing indirect jumps. + -- : BFD_RELOC_V850_ALIGN + Used to maintain alignment whilst relaxing. + -- : BFD_RELOC_V850_LO16_SPLIT_OFFSET + This is a variation of BFD_RELOC_LO16 that can be used in v850e + ld.bu instructions. + -- : BFD_RELOC_V850_16_PCREL + This is a 16-bit reloc. + -- : BFD_RELOC_V850_17_PCREL + This is a 17-bit reloc. + -- : BFD_RELOC_V850_23 + This is a 23-bit reloc. + -- : BFD_RELOC_V850_32_PCREL + This is a 32-bit reloc. + -- : BFD_RELOC_V850_32_ABS + This is a 32-bit reloc. + -- : BFD_RELOC_V850_16_SPLIT_OFFSET + This is a 16-bit reloc. + -- : BFD_RELOC_V850_16_S1 + This is a 16-bit reloc. + -- : BFD_RELOC_V850_LO16_S1 + Low 16 bits. 16 bit shifted by 1. + -- : BFD_RELOC_V850_CALLT_15_16_OFFSET + This is a 16 bit offset from the call table base pointer. + -- : BFD_RELOC_V850_32_GOTPCREL + DSO relocations. + -- : BFD_RELOC_V850_16_GOT + DSO relocations. + -- : BFD_RELOC_V850_32_GOT + DSO relocations. + -- : BFD_RELOC_V850_22_PLT_PCREL + DSO relocations. + -- : BFD_RELOC_V850_32_PLT_PCREL + DSO relocations. + -- : BFD_RELOC_V850_COPY + DSO relocations. + -- : BFD_RELOC_V850_GLOB_DAT + DSO relocations. + -- : BFD_RELOC_V850_JMP_SLOT + DSO relocations. + -- : BFD_RELOC_V850_RELATIVE + DSO relocations. + -- : BFD_RELOC_V850_16_GOTOFF + DSO relocations. + -- : BFD_RELOC_V850_32_GOTOFF + DSO relocations. + -- : BFD_RELOC_V850_CODE + start code. + -- : BFD_RELOC_V850_DATA + start data in text. + -- : BFD_RELOC_TIC30_LDP + This is a 8bit DP reloc for the tms320c30, where the most + significant 8 bits of a 24 bit word are placed into the least + significant 8 bits of the opcode. + -- : BFD_RELOC_TIC54X_PARTLS7 + This is a 7bit reloc for the tms320c54x, where the least + significant 7 bits of a 16 bit word are placed into the least + significant 7 bits of the opcode. + -- : BFD_RELOC_TIC54X_PARTMS9 + This is a 9bit DP reloc for the tms320c54x, where the most + significant 9 bits of a 16 bit word are placed into the least + significant 9 bits of the opcode. + -- : BFD_RELOC_TIC54X_23 + This is an extended address 23-bit reloc for the tms320c54x. + -- : BFD_RELOC_TIC54X_16_OF_23 + This is a 16-bit reloc for the tms320c54x, where the least + significant 16 bits of a 23-bit extended address are placed into + the opcode. + -- : BFD_RELOC_TIC54X_MS7_OF_23 + This is a reloc for the tms320c54x, where the most significant 7 + bits of a 23-bit extended address are placed into the opcode. + -- : BFD_RELOC_C6000_PCR_S21 + -- : BFD_RELOC_C6000_PCR_S12 + -- : BFD_RELOC_C6000_PCR_S10 + -- : BFD_RELOC_C6000_PCR_S7 + -- : BFD_RELOC_C6000_ABS_S16 + -- : BFD_RELOC_C6000_ABS_L16 + -- : BFD_RELOC_C6000_ABS_H16 + -- : BFD_RELOC_C6000_SBR_U15_B + -- : BFD_RELOC_C6000_SBR_U15_H + -- : BFD_RELOC_C6000_SBR_U15_W + -- : BFD_RELOC_C6000_SBR_S16 + -- : BFD_RELOC_C6000_SBR_L16_B + -- : BFD_RELOC_C6000_SBR_L16_H + -- : BFD_RELOC_C6000_SBR_L16_W + -- : BFD_RELOC_C6000_SBR_H16_B + -- : BFD_RELOC_C6000_SBR_H16_H + -- : BFD_RELOC_C6000_SBR_H16_W + -- : BFD_RELOC_C6000_SBR_GOT_U15_W + -- : BFD_RELOC_C6000_SBR_GOT_L16_W + -- : BFD_RELOC_C6000_SBR_GOT_H16_W + -- : BFD_RELOC_C6000_DSBT_INDEX + -- : BFD_RELOC_C6000_PREL31 + -- : BFD_RELOC_C6000_COPY + -- : BFD_RELOC_C6000_JUMP_SLOT + -- : BFD_RELOC_C6000_EHTYPE + -- : BFD_RELOC_C6000_PCR_H16 + -- : BFD_RELOC_C6000_PCR_L16 + -- : BFD_RELOC_C6000_ALIGN + -- : BFD_RELOC_C6000_FPHEAD + -- : BFD_RELOC_C6000_NOCMP + TMS320C6000 relocations. + -- : BFD_RELOC_FR30_48 + This is a 48 bit reloc for the FR30 that stores 32 bits. + -- : BFD_RELOC_FR30_20 + This is a 32 bit reloc for the FR30 that stores 20 bits split up + into two sections. + -- : BFD_RELOC_FR30_6_IN_4 + This is a 16 bit reloc for the FR30 that stores a 6 bit word offset + in 4 bits. + -- : BFD_RELOC_FR30_8_IN_8 + This is a 16 bit reloc for the FR30 that stores an 8 bit byte + offset into 8 bits. + -- : BFD_RELOC_FR30_9_IN_8 + This is a 16 bit reloc for the FR30 that stores a 9 bit short + offset into 8 bits. + -- : BFD_RELOC_FR30_10_IN_8 + This is a 16 bit reloc for the FR30 that stores a 10 bit word + offset into 8 bits. + -- : BFD_RELOC_FR30_9_PCREL + This is a 16 bit reloc for the FR30 that stores a 9 bit pc relative + short offset into 8 bits. + -- : BFD_RELOC_FR30_12_PCREL + This is a 16 bit reloc for the FR30 that stores a 12 bit pc + relative short offset into 11 bits. + -- : BFD_RELOC_MCORE_PCREL_IMM8BY4 + -- : BFD_RELOC_MCORE_PCREL_IMM11BY2 + -- : BFD_RELOC_MCORE_PCREL_IMM4BY2 + -- : BFD_RELOC_MCORE_PCREL_32 + -- : BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2 + -- : BFD_RELOC_MCORE_RVA + Motorola Mcore relocations. + -- : BFD_RELOC_MEP_8 + -- : BFD_RELOC_MEP_16 + -- : BFD_RELOC_MEP_32 + -- : BFD_RELOC_MEP_PCREL8A2 + -- : BFD_RELOC_MEP_PCREL12A2 + -- : BFD_RELOC_MEP_PCREL17A2 + -- : BFD_RELOC_MEP_PCREL24A2 + -- : BFD_RELOC_MEP_PCABS24A2 + -- : BFD_RELOC_MEP_LOW16 + -- : BFD_RELOC_MEP_HI16U + -- : BFD_RELOC_MEP_HI16S + -- : BFD_RELOC_MEP_GPREL + -- : BFD_RELOC_MEP_TPREL + -- : BFD_RELOC_MEP_TPREL7 + -- : BFD_RELOC_MEP_TPREL7A2 + -- : BFD_RELOC_MEP_TPREL7A4 + -- : BFD_RELOC_MEP_UIMM24 + -- : BFD_RELOC_MEP_ADDR24A4 + -- : BFD_RELOC_MEP_GNU_VTINHERIT + -- : BFD_RELOC_MEP_GNU_VTENTRY + Toshiba Media Processor Relocations. + -- : BFD_RELOC_METAG_HIADDR16 + -- : BFD_RELOC_METAG_LOADDR16 + -- : BFD_RELOC_METAG_RELBRANCH + -- : BFD_RELOC_METAG_GETSETOFF + -- : BFD_RELOC_METAG_HIOG + -- : BFD_RELOC_METAG_LOOG + -- : BFD_RELOC_METAG_REL8 + -- : BFD_RELOC_METAG_REL16 + -- : BFD_RELOC_METAG_HI16_GOTOFF + -- : BFD_RELOC_METAG_LO16_GOTOFF + -- : BFD_RELOC_METAG_GETSET_GOTOFF + -- : BFD_RELOC_METAG_GETSET_GOT + -- : BFD_RELOC_METAG_HI16_GOTPC + -- : BFD_RELOC_METAG_LO16_GOTPC + -- : BFD_RELOC_METAG_HI16_PLT + -- : BFD_RELOC_METAG_LO16_PLT + -- : BFD_RELOC_METAG_RELBRANCH_PLT + -- : BFD_RELOC_METAG_GOTOFF + -- : BFD_RELOC_METAG_PLT + -- : BFD_RELOC_METAG_COPY + -- : BFD_RELOC_METAG_JMP_SLOT + -- : BFD_RELOC_METAG_RELATIVE + -- : BFD_RELOC_METAG_GLOB_DAT + -- : BFD_RELOC_METAG_TLS_GD + -- : BFD_RELOC_METAG_TLS_LDM + -- : BFD_RELOC_METAG_TLS_LDO_HI16 + -- : BFD_RELOC_METAG_TLS_LDO_LO16 + -- : BFD_RELOC_METAG_TLS_LDO + -- : BFD_RELOC_METAG_TLS_IE + -- : BFD_RELOC_METAG_TLS_IENONPIC + -- : BFD_RELOC_METAG_TLS_IENONPIC_HI16 + -- : BFD_RELOC_METAG_TLS_IENONPIC_LO16 + -- : BFD_RELOC_METAG_TLS_TPOFF + -- : BFD_RELOC_METAG_TLS_DTPMOD + -- : BFD_RELOC_METAG_TLS_DTPOFF + -- : BFD_RELOC_METAG_TLS_LE + -- : BFD_RELOC_METAG_TLS_LE_HI16 + -- : BFD_RELOC_METAG_TLS_LE_LO16 + Imagination Technologies Meta relocations. + -- : BFD_RELOC_MMIX_GETA + -- : BFD_RELOC_MMIX_GETA_1 + -- : BFD_RELOC_MMIX_GETA_2 + -- : BFD_RELOC_MMIX_GETA_3 + These are relocations for the GETA instruction. + -- : BFD_RELOC_MMIX_CBRANCH + -- : BFD_RELOC_MMIX_CBRANCH_J + -- : BFD_RELOC_MMIX_CBRANCH_1 + -- : BFD_RELOC_MMIX_CBRANCH_2 + -- : BFD_RELOC_MMIX_CBRANCH_3 + These are relocations for a conditional branch instruction. + -- : BFD_RELOC_MMIX_PUSHJ + -- : BFD_RELOC_MMIX_PUSHJ_1 + -- : BFD_RELOC_MMIX_PUSHJ_2 + -- : BFD_RELOC_MMIX_PUSHJ_3 + -- : BFD_RELOC_MMIX_PUSHJ_STUBBABLE + These are relocations for the PUSHJ instruction. + -- : BFD_RELOC_MMIX_JMP + -- : BFD_RELOC_MMIX_JMP_1 + -- : BFD_RELOC_MMIX_JMP_2 + -- : BFD_RELOC_MMIX_JMP_3 + These are relocations for the JMP instruction. + -- : BFD_RELOC_MMIX_ADDR19 + This is a relocation for a relative address as in a GETA + instruction or a branch. + -- : BFD_RELOC_MMIX_ADDR27 + This is a relocation for a relative address as in a JMP + instruction. + -- : BFD_RELOC_MMIX_REG_OR_BYTE + This is a relocation for an instruction field that may be a general + register or a value 0..255. + -- : BFD_RELOC_MMIX_REG + This is a relocation for an instruction field that may be a general + register. + -- : BFD_RELOC_MMIX_BASE_PLUS_OFFSET + This is a relocation for two instruction fields holding a register + and an offset, the equivalent of the relocation. + -- : BFD_RELOC_MMIX_LOCAL + This relocation is an assertion that the expression is not + allocated as a global register. It does not modify contents. + -- : BFD_RELOC_AVR_7_PCREL + This is a 16 bit reloc for the AVR that stores 8 bit pc relative + short offset into 7 bits. + -- : BFD_RELOC_AVR_13_PCREL + This is a 16 bit reloc for the AVR that stores 13 bit pc relative + short offset into 12 bits. + -- : BFD_RELOC_AVR_16_PM + This is a 16 bit reloc for the AVR that stores 17 bit value + (usually program memory address) into 16 bits. + -- : BFD_RELOC_AVR_LO8_LDI + This is a 16 bit reloc for the AVR that stores 8 bit value (usually + data memory address) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_HI8_LDI + This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 + bit of data memory address) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_HH8_LDI + This is a 16 bit reloc for the AVR that stores 8 bit value (most + high 8 bit of program memory address) into 8 bit immediate value of + LDI insn. + -- : BFD_RELOC_AVR_MS8_LDI + This is a 16 bit reloc for the AVR that stores 8 bit value (most + high 8 bit of 32 bit value) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_LO8_LDI_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (usually data memory address) into 8 bit immediate value of SUBI + insn. + -- : BFD_RELOC_AVR_HI8_LDI_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (high 8 bit of data memory address) into 8 bit immediate value of + SUBI insn. + -- : BFD_RELOC_AVR_HH8_LDI_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (most high 8 bit of program memory address) into 8 bit immediate + value of LDI or SUBI insn. + -- : BFD_RELOC_AVR_MS8_LDI_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (msb of 32 bit value) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_LO8_LDI_PM + This is a 16 bit reloc for the AVR that stores 8 bit value (usually + command address) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_LO8_LDI_GS + This is a 16 bit reloc for the AVR that stores 8 bit value (command + address) into 8 bit immediate value of LDI insn. If the address is + beyond the 128k boundary, the linker inserts a jump stub for this + reloc in the lower 128k. + -- : BFD_RELOC_AVR_HI8_LDI_PM + This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 + bit of command address) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_HI8_LDI_GS + This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 + bit of command address) into 8 bit immediate value of LDI insn. If + the address is beyond the 128k boundary, the linker inserts a jump + stub for this reloc below 128k. + -- : BFD_RELOC_AVR_HH8_LDI_PM + This is a 16 bit reloc for the AVR that stores 8 bit value (most + high 8 bit of command address) into 8 bit immediate value of LDI + insn. + -- : BFD_RELOC_AVR_LO8_LDI_PM_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (usually command address) into 8 bit immediate value of SUBI insn. + -- : BFD_RELOC_AVR_HI8_LDI_PM_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (high 8 bit of 16 bit command address) into 8 bit immediate value + of SUBI insn. + -- : BFD_RELOC_AVR_HH8_LDI_PM_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (high 6 bit of 22 bit command address) into 8 bit immediate value + of SUBI insn. + -- : BFD_RELOC_AVR_CALL + This is a 32 bit reloc for the AVR that stores 23 bit value into 22 + bits. + -- : BFD_RELOC_AVR_LDI + This is a 16 bit reloc for the AVR that stores all needed bits for + absolute addressing with ldi with overflow check to linktime + -- : BFD_RELOC_AVR_6 + This is a 6 bit reloc for the AVR that stores offset for ldd/std + instructions + -- : BFD_RELOC_AVR_6_ADIW + This is a 6 bit reloc for the AVR that stores offset for adiw/sbiw + instructions + -- : BFD_RELOC_AVR_8_LO + This is a 8 bit reloc for the AVR that stores bits 0..7 of a symbol + in .byte lo8(symbol) + -- : BFD_RELOC_AVR_8_HI + This is a 8 bit reloc for the AVR that stores bits 8..15 of a + symbol in .byte hi8(symbol) + -- : BFD_RELOC_AVR_8_HLO + This is a 8 bit reloc for the AVR that stores bits 16..23 of a + symbol in .byte hlo8(symbol) + -- : BFD_RELOC_RL78_NEG8 + -- : BFD_RELOC_RL78_NEG16 + -- : BFD_RELOC_RL78_NEG24 + -- : BFD_RELOC_RL78_NEG32 + -- : BFD_RELOC_RL78_16_OP + -- : BFD_RELOC_RL78_24_OP + -- : BFD_RELOC_RL78_32_OP + -- : BFD_RELOC_RL78_8U + -- : BFD_RELOC_RL78_16U + -- : BFD_RELOC_RL78_24U + -- : BFD_RELOC_RL78_DIR3U_PCREL + -- : BFD_RELOC_RL78_DIFF + -- : BFD_RELOC_RL78_GPRELB + -- : BFD_RELOC_RL78_GPRELW + -- : BFD_RELOC_RL78_GPRELL + -- : BFD_RELOC_RL78_SYM + -- : BFD_RELOC_RL78_OP_SUBTRACT + -- : BFD_RELOC_RL78_OP_NEG + -- : BFD_RELOC_RL78_OP_AND + -- : BFD_RELOC_RL78_OP_SHRA + -- : BFD_RELOC_RL78_ABS8 + -- : BFD_RELOC_RL78_ABS16 + -- : BFD_RELOC_RL78_ABS16_REV + -- : BFD_RELOC_RL78_ABS32 + -- : BFD_RELOC_RL78_ABS32_REV + -- : BFD_RELOC_RL78_ABS16U + -- : BFD_RELOC_RL78_ABS16UW + -- : BFD_RELOC_RL78_ABS16UL + -- : BFD_RELOC_RL78_RELAX + -- : BFD_RELOC_RL78_HI16 + -- : BFD_RELOC_RL78_HI8 + -- : BFD_RELOC_RL78_LO16 + -- : BFD_RELOC_RL78_CODE + Renesas RL78 Relocations. + -- : BFD_RELOC_RX_NEG8 + -- : BFD_RELOC_RX_NEG16 + -- : BFD_RELOC_RX_NEG24 + -- : BFD_RELOC_RX_NEG32 + -- : BFD_RELOC_RX_16_OP + -- : BFD_RELOC_RX_24_OP + -- : BFD_RELOC_RX_32_OP + -- : BFD_RELOC_RX_8U + -- : BFD_RELOC_RX_16U + -- : BFD_RELOC_RX_24U + -- : BFD_RELOC_RX_DIR3U_PCREL + -- : BFD_RELOC_RX_DIFF + -- : BFD_RELOC_RX_GPRELB + -- : BFD_RELOC_RX_GPRELW + -- : BFD_RELOC_RX_GPRELL + -- : BFD_RELOC_RX_SYM + -- : BFD_RELOC_RX_OP_SUBTRACT + -- : BFD_RELOC_RX_OP_NEG + -- : BFD_RELOC_RX_ABS8 + -- : BFD_RELOC_RX_ABS16 + -- : BFD_RELOC_RX_ABS16_REV + -- : BFD_RELOC_RX_ABS32 + -- : BFD_RELOC_RX_ABS32_REV + -- : BFD_RELOC_RX_ABS16U + -- : BFD_RELOC_RX_ABS16UW + -- : BFD_RELOC_RX_ABS16UL + -- : BFD_RELOC_RX_RELAX + Renesas RX Relocations. + -- : BFD_RELOC_390_12 + Direct 12 bit. + -- : BFD_RELOC_390_GOT12 + 12 bit GOT offset. + -- : BFD_RELOC_390_PLT32 + 32 bit PC relative PLT address. + -- : BFD_RELOC_390_COPY + Copy symbol at runtime. + -- : BFD_RELOC_390_GLOB_DAT + Create GOT entry. + -- : BFD_RELOC_390_JMP_SLOT + Create PLT entry. + -- : BFD_RELOC_390_RELATIVE + Adjust by program base. + -- : BFD_RELOC_390_GOTPC + 32 bit PC relative offset to GOT. + -- : BFD_RELOC_390_GOT16 + 16 bit GOT offset. + -- : BFD_RELOC_390_PC12DBL + PC relative 12 bit shifted by 1. + -- : BFD_RELOC_390_PLT12DBL + 12 bit PC rel. PLT shifted by 1. + -- : BFD_RELOC_390_PC16DBL + PC relative 16 bit shifted by 1. + -- : BFD_RELOC_390_PLT16DBL + 16 bit PC rel. PLT shifted by 1. + -- : BFD_RELOC_390_PC24DBL + PC relative 24 bit shifted by 1. + -- : BFD_RELOC_390_PLT24DBL + 24 bit PC rel. PLT shifted by 1. + -- : BFD_RELOC_390_PC32DBL + PC relative 32 bit shifted by 1. + -- : BFD_RELOC_390_PLT32DBL + 32 bit PC rel. PLT shifted by 1. + -- : BFD_RELOC_390_GOTPCDBL + 32 bit PC rel. GOT shifted by 1. + -- : BFD_RELOC_390_GOT64 + 64 bit GOT offset. + -- : BFD_RELOC_390_PLT64 + 64 bit PC relative PLT address. + -- : BFD_RELOC_390_GOTENT + 32 bit rel. offset to GOT entry. + -- : BFD_RELOC_390_GOTOFF64 + 64 bit offset to GOT. + -- : BFD_RELOC_390_GOTPLT12 + 12-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_390_GOTPLT16 + 16-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_390_GOTPLT32 + 32-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_390_GOTPLT64 + 64-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_390_GOTPLTENT + 32-bit rel. offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_390_PLTOFF16 + 16-bit rel. offset from the GOT to a PLT entry. + -- : BFD_RELOC_390_PLTOFF32 + 32-bit rel. offset from the GOT to a PLT entry. + -- : BFD_RELOC_390_PLTOFF64 + 64-bit rel. offset from the GOT to a PLT entry. + -- : BFD_RELOC_390_TLS_LOAD + -- : BFD_RELOC_390_TLS_GDCALL + -- : BFD_RELOC_390_TLS_LDCALL + -- : BFD_RELOC_390_TLS_GD32 + -- : BFD_RELOC_390_TLS_GD64 + -- : BFD_RELOC_390_TLS_GOTIE12 + -- : BFD_RELOC_390_TLS_GOTIE32 + -- : BFD_RELOC_390_TLS_GOTIE64 + -- : BFD_RELOC_390_TLS_LDM32 + -- : BFD_RELOC_390_TLS_LDM64 + -- : BFD_RELOC_390_TLS_IE32 + -- : BFD_RELOC_390_TLS_IE64 + -- : BFD_RELOC_390_TLS_IEENT + -- : BFD_RELOC_390_TLS_LE32 + -- : BFD_RELOC_390_TLS_LE64 + -- : BFD_RELOC_390_TLS_LDO32 + -- : BFD_RELOC_390_TLS_LDO64 + -- : BFD_RELOC_390_TLS_DTPMOD + -- : BFD_RELOC_390_TLS_DTPOFF + -- : BFD_RELOC_390_TLS_TPOFF + s390 tls relocations. + -- : BFD_RELOC_390_20 + -- : BFD_RELOC_390_GOT20 + -- : BFD_RELOC_390_GOTPLT20 + -- : BFD_RELOC_390_TLS_GOTIE20 + Long displacement extension. + -- : BFD_RELOC_390_IRELATIVE + STT_GNU_IFUNC relocation. + -- : BFD_RELOC_SCORE_GPREL15 + Score relocations Low 16 bit for load/store + -- : BFD_RELOC_SCORE_DUMMY2 + -- : BFD_RELOC_SCORE_JMP + This is a 24-bit reloc with the right 1 bit assumed to be 0 + -- : BFD_RELOC_SCORE_BRANCH + This is a 19-bit reloc with the right 1 bit assumed to be 0 + -- : BFD_RELOC_SCORE_IMM30 + This is a 32-bit reloc for 48-bit instructions. + -- : BFD_RELOC_SCORE_IMM32 + This is a 32-bit reloc for 48-bit instructions. + -- : BFD_RELOC_SCORE16_JMP + This is a 11-bit reloc with the right 1 bit assumed to be 0 + -- : BFD_RELOC_SCORE16_BRANCH + This is a 8-bit reloc with the right 1 bit assumed to be 0 + -- : BFD_RELOC_SCORE_BCMP + This is a 9-bit reloc with the right 1 bit assumed to be 0 + -- : BFD_RELOC_SCORE_GOT15 + -- : BFD_RELOC_SCORE_GOT_LO16 + -- : BFD_RELOC_SCORE_CALL15 + -- : BFD_RELOC_SCORE_DUMMY_HI16 + Undocumented Score relocs + -- : BFD_RELOC_IP2K_FR9 + Scenix IP2K - 9-bit register number / data address + -- : BFD_RELOC_IP2K_BANK + Scenix IP2K - 4-bit register/data bank number + -- : BFD_RELOC_IP2K_ADDR16CJP + Scenix IP2K - low 13 bits of instruction word address + -- : BFD_RELOC_IP2K_PAGE3 + Scenix IP2K - high 3 bits of instruction word address + -- : BFD_RELOC_IP2K_LO8DATA + -- : BFD_RELOC_IP2K_HI8DATA + -- : BFD_RELOC_IP2K_EX8DATA + Scenix IP2K - ext/low/high 8 bits of data address + -- : BFD_RELOC_IP2K_LO8INSN + -- : BFD_RELOC_IP2K_HI8INSN + Scenix IP2K - low/high 8 bits of instruction word address + -- : BFD_RELOC_IP2K_PC_SKIP + Scenix IP2K - even/odd PC modifier to modify snb pcl.0 + -- : BFD_RELOC_IP2K_TEXT + Scenix IP2K - 16 bit word address in text section. + -- : BFD_RELOC_IP2K_FR_OFFSET + Scenix IP2K - 7-bit sp or dp offset + -- : BFD_RELOC_VPE4KMATH_DATA + -- : BFD_RELOC_VPE4KMATH_INSN + Scenix VPE4K coprocessor - data/insn-space addressing + -- : BFD_RELOC_VTABLE_INHERIT + -- : BFD_RELOC_VTABLE_ENTRY + These two relocations are used by the linker to determine which of + the entries in a C++ virtual function table are actually used. + When the -gc-sections option is given, the linker will zero out the + entries that are not used, so that the code for those functions + need not be included in the output. + + VTABLE_INHERIT is a zero-space relocation used to describe to the + linker the inheritance tree of a C++ virtual function table. The + relocation's symbol should be the parent class' vtable, and the + relocation should be located at the child vtable. + + VTABLE_ENTRY is a zero-space relocation that describes the use of a + virtual function table entry. The reloc's symbol should refer to + the table of the class mentioned in the code. Off of that base, an + offset describes the entry that is being used. For Rela hosts, + this offset is stored in the reloc's addend. For Rel hosts, we are + forced to put this offset in the reloc's section offset. + -- : BFD_RELOC_IA64_IMM14 + -- : BFD_RELOC_IA64_IMM22 + -- : BFD_RELOC_IA64_IMM64 + -- : BFD_RELOC_IA64_DIR32MSB + -- : BFD_RELOC_IA64_DIR32LSB + -- : BFD_RELOC_IA64_DIR64MSB + -- : BFD_RELOC_IA64_DIR64LSB + -- : BFD_RELOC_IA64_GPREL22 + -- : BFD_RELOC_IA64_GPREL64I + -- : BFD_RELOC_IA64_GPREL32MSB + -- : BFD_RELOC_IA64_GPREL32LSB + -- : BFD_RELOC_IA64_GPREL64MSB + -- : BFD_RELOC_IA64_GPREL64LSB + -- : BFD_RELOC_IA64_LTOFF22 + -- : BFD_RELOC_IA64_LTOFF64I + -- : BFD_RELOC_IA64_PLTOFF22 + -- : BFD_RELOC_IA64_PLTOFF64I + -- : BFD_RELOC_IA64_PLTOFF64MSB + -- : BFD_RELOC_IA64_PLTOFF64LSB + -- : BFD_RELOC_IA64_FPTR64I + -- : BFD_RELOC_IA64_FPTR32MSB + -- : BFD_RELOC_IA64_FPTR32LSB + -- : BFD_RELOC_IA64_FPTR64MSB + -- : BFD_RELOC_IA64_FPTR64LSB + -- : BFD_RELOC_IA64_PCREL21B + -- : BFD_RELOC_IA64_PCREL21BI + -- : BFD_RELOC_IA64_PCREL21M + -- : BFD_RELOC_IA64_PCREL21F + -- : BFD_RELOC_IA64_PCREL22 + -- : BFD_RELOC_IA64_PCREL60B + -- : BFD_RELOC_IA64_PCREL64I + -- : BFD_RELOC_IA64_PCREL32MSB + -- : BFD_RELOC_IA64_PCREL32LSB + -- : BFD_RELOC_IA64_PCREL64MSB + -- : BFD_RELOC_IA64_PCREL64LSB + -- : BFD_RELOC_IA64_LTOFF_FPTR22 + -- : BFD_RELOC_IA64_LTOFF_FPTR64I + -- : BFD_RELOC_IA64_LTOFF_FPTR32MSB + -- : BFD_RELOC_IA64_LTOFF_FPTR32LSB + -- : BFD_RELOC_IA64_LTOFF_FPTR64MSB + -- : BFD_RELOC_IA64_LTOFF_FPTR64LSB + -- : BFD_RELOC_IA64_SEGREL32MSB + -- : BFD_RELOC_IA64_SEGREL32LSB + -- : BFD_RELOC_IA64_SEGREL64MSB + -- : BFD_RELOC_IA64_SEGREL64LSB + -- : BFD_RELOC_IA64_SECREL32MSB + -- : BFD_RELOC_IA64_SECREL32LSB + -- : BFD_RELOC_IA64_SECREL64MSB + -- : BFD_RELOC_IA64_SECREL64LSB + -- : BFD_RELOC_IA64_REL32MSB + -- : BFD_RELOC_IA64_REL32LSB + -- : BFD_RELOC_IA64_REL64MSB + -- : BFD_RELOC_IA64_REL64LSB + -- : BFD_RELOC_IA64_LTV32MSB + -- : BFD_RELOC_IA64_LTV32LSB + -- : BFD_RELOC_IA64_LTV64MSB + -- : BFD_RELOC_IA64_LTV64LSB + -- : BFD_RELOC_IA64_IPLTMSB + -- : BFD_RELOC_IA64_IPLTLSB + -- : BFD_RELOC_IA64_COPY + -- : BFD_RELOC_IA64_LTOFF22X + -- : BFD_RELOC_IA64_LDXMOV + -- : BFD_RELOC_IA64_TPREL14 + -- : BFD_RELOC_IA64_TPREL22 + -- : BFD_RELOC_IA64_TPREL64I + -- : BFD_RELOC_IA64_TPREL64MSB + -- : BFD_RELOC_IA64_TPREL64LSB + -- : BFD_RELOC_IA64_LTOFF_TPREL22 + -- : BFD_RELOC_IA64_DTPMOD64MSB + -- : BFD_RELOC_IA64_DTPMOD64LSB + -- : BFD_RELOC_IA64_LTOFF_DTPMOD22 + -- : BFD_RELOC_IA64_DTPREL14 + -- : BFD_RELOC_IA64_DTPREL22 + -- : BFD_RELOC_IA64_DTPREL64I + -- : BFD_RELOC_IA64_DTPREL32MSB + -- : BFD_RELOC_IA64_DTPREL32LSB + -- : BFD_RELOC_IA64_DTPREL64MSB + -- : BFD_RELOC_IA64_DTPREL64LSB + -- : BFD_RELOC_IA64_LTOFF_DTPREL22 + Intel IA64 Relocations. + -- : BFD_RELOC_M68HC11_HI8 + Motorola 68HC11 reloc. This is the 8 bit high part of an absolute + address. + -- : BFD_RELOC_M68HC11_LO8 + Motorola 68HC11 reloc. This is the 8 bit low part of an absolute + address. + -- : BFD_RELOC_M68HC11_3B + Motorola 68HC11 reloc. This is the 3 bit of a value. + -- : BFD_RELOC_M68HC11_RL_JUMP + Motorola 68HC11 reloc. This reloc marks the beginning of a + jump/call instruction. It is used for linker relaxation to + correctly identify beginning of instruction and change some + branches to use PC-relative addressing mode. + -- : BFD_RELOC_M68HC11_RL_GROUP + Motorola 68HC11 reloc. This reloc marks a group of several + instructions that gcc generates and for which the linker relaxation + pass can modify and/or remove some of them. + -- : BFD_RELOC_M68HC11_LO16 + Motorola 68HC11 reloc. This is the 16-bit lower part of an + address. It is used for 'call' instruction to specify the symbol + address without any special transformation (due to memory bank + window). + -- : BFD_RELOC_M68HC11_PAGE + Motorola 68HC11 reloc. This is a 8-bit reloc that specifies the + page number of an address. It is used by 'call' instruction to + specify the page number of the symbol. + -- : BFD_RELOC_M68HC11_24 + Motorola 68HC11 reloc. This is a 24-bit reloc that represents the + address with a 16-bit value and a 8-bit page number. The symbol + address is transformed to follow the 16K memory bank of 68HC12 + (seen as mapped in the window). + -- : BFD_RELOC_M68HC12_5B + Motorola 68HC12 reloc. This is the 5 bits of a value. + -- : BFD_RELOC_XGATE_RL_JUMP + Freescale XGATE reloc. This reloc marks the beginning of a bra/jal + instruction. + -- : BFD_RELOC_XGATE_RL_GROUP + Freescale XGATE reloc. This reloc marks a group of several + instructions that gcc generates and for which the linker relaxation + pass can modify and/or remove some of them. + -- : BFD_RELOC_XGATE_LO16 + Freescale XGATE reloc. This is the 16-bit lower part of an + address. It is used for the '16-bit' instructions. + -- : BFD_RELOC_XGATE_GPAGE + Freescale XGATE reloc. + -- : BFD_RELOC_XGATE_24 + Freescale XGATE reloc. + -- : BFD_RELOC_XGATE_PCREL_9 + Freescale XGATE reloc. This is a 9-bit pc-relative reloc. + -- : BFD_RELOC_XGATE_PCREL_10 + Freescale XGATE reloc. This is a 10-bit pc-relative reloc. + -- : BFD_RELOC_XGATE_IMM8_LO + Freescale XGATE reloc. This is the 16-bit lower part of an + address. It is used for the '16-bit' instructions. + -- : BFD_RELOC_XGATE_IMM8_HI + Freescale XGATE reloc. This is the 16-bit higher part of an + address. It is used for the '16-bit' instructions. + -- : BFD_RELOC_XGATE_IMM3 + Freescale XGATE reloc. This is a 3-bit pc-relative reloc. + -- : BFD_RELOC_XGATE_IMM4 + Freescale XGATE reloc. This is a 4-bit pc-relative reloc. + -- : BFD_RELOC_XGATE_IMM5 + Freescale XGATE reloc. This is a 5-bit pc-relative reloc. + -- : BFD_RELOC_M68HC12_9B + Motorola 68HC12 reloc. This is the 9 bits of a value. + -- : BFD_RELOC_M68HC12_16B + Motorola 68HC12 reloc. This is the 16 bits of a value. + -- : BFD_RELOC_M68HC12_9_PCREL + Motorola 68HC12/XGATE reloc. This is a PCREL9 branch. + -- : BFD_RELOC_M68HC12_10_PCREL + Motorola 68HC12/XGATE reloc. This is a PCREL10 branch. + -- : BFD_RELOC_M68HC12_LO8XG + Motorola 68HC12/XGATE reloc. This is the 8 bit low part of an + absolute address and immediately precedes a matching HI8XG part. + -- : BFD_RELOC_M68HC12_HI8XG + Motorola 68HC12/XGATE reloc. This is the 8 bit high part of an + absolute address and immediately follows a matching LO8XG part. + -- : BFD_RELOC_16C_NUM08 + -- : BFD_RELOC_16C_NUM08_C + -- : BFD_RELOC_16C_NUM16 + -- : BFD_RELOC_16C_NUM16_C + -- : BFD_RELOC_16C_NUM32 + -- : BFD_RELOC_16C_NUM32_C + -- : BFD_RELOC_16C_DISP04 + -- : BFD_RELOC_16C_DISP04_C + -- : BFD_RELOC_16C_DISP08 + -- : BFD_RELOC_16C_DISP08_C + -- : BFD_RELOC_16C_DISP16 + -- : BFD_RELOC_16C_DISP16_C + -- : BFD_RELOC_16C_DISP24 + -- : BFD_RELOC_16C_DISP24_C + -- : BFD_RELOC_16C_DISP24a + -- : BFD_RELOC_16C_DISP24a_C + -- : BFD_RELOC_16C_REG04 + -- : BFD_RELOC_16C_REG04_C + -- : BFD_RELOC_16C_REG04a + -- : BFD_RELOC_16C_REG04a_C + -- : BFD_RELOC_16C_REG14 + -- : BFD_RELOC_16C_REG14_C + -- : BFD_RELOC_16C_REG16 + -- : BFD_RELOC_16C_REG16_C + -- : BFD_RELOC_16C_REG20 + -- : BFD_RELOC_16C_REG20_C + -- : BFD_RELOC_16C_ABS20 + -- : BFD_RELOC_16C_ABS20_C + -- : BFD_RELOC_16C_ABS24 + -- : BFD_RELOC_16C_ABS24_C + -- : BFD_RELOC_16C_IMM04 + -- : BFD_RELOC_16C_IMM04_C + -- : BFD_RELOC_16C_IMM16 + -- : BFD_RELOC_16C_IMM16_C + -- : BFD_RELOC_16C_IMM20 + -- : BFD_RELOC_16C_IMM20_C + -- : BFD_RELOC_16C_IMM24 + -- : BFD_RELOC_16C_IMM24_C + -- : BFD_RELOC_16C_IMM32 + -- : BFD_RELOC_16C_IMM32_C + NS CR16C Relocations. + -- : BFD_RELOC_CR16_NUM8 + -- : BFD_RELOC_CR16_NUM16 + -- : BFD_RELOC_CR16_NUM32 + -- : BFD_RELOC_CR16_NUM32a + -- : BFD_RELOC_CR16_REGREL0 + -- : BFD_RELOC_CR16_REGREL4 + -- : BFD_RELOC_CR16_REGREL4a + -- : BFD_RELOC_CR16_REGREL14 + -- : BFD_RELOC_CR16_REGREL14a + -- : BFD_RELOC_CR16_REGREL16 + -- : BFD_RELOC_CR16_REGREL20 + -- : BFD_RELOC_CR16_REGREL20a + -- : BFD_RELOC_CR16_ABS20 + -- : BFD_RELOC_CR16_ABS24 + -- : BFD_RELOC_CR16_IMM4 + -- : BFD_RELOC_CR16_IMM8 + -- : BFD_RELOC_CR16_IMM16 + -- : BFD_RELOC_CR16_IMM20 + -- : BFD_RELOC_CR16_IMM24 + -- : BFD_RELOC_CR16_IMM32 + -- : BFD_RELOC_CR16_IMM32a + -- : BFD_RELOC_CR16_DISP4 + -- : BFD_RELOC_CR16_DISP8 + -- : BFD_RELOC_CR16_DISP16 + -- : BFD_RELOC_CR16_DISP20 + -- : BFD_RELOC_CR16_DISP24 + -- : BFD_RELOC_CR16_DISP24a + -- : BFD_RELOC_CR16_SWITCH8 + -- : BFD_RELOC_CR16_SWITCH16 + -- : BFD_RELOC_CR16_SWITCH32 + -- : BFD_RELOC_CR16_GOT_REGREL20 + -- : BFD_RELOC_CR16_GOTC_REGREL20 + -- : BFD_RELOC_CR16_GLOB_DAT + NS CR16 Relocations. + -- : BFD_RELOC_CRX_REL4 + -- : BFD_RELOC_CRX_REL8 + -- : BFD_RELOC_CRX_REL8_CMP + -- : BFD_RELOC_CRX_REL16 + -- : BFD_RELOC_CRX_REL24 + -- : BFD_RELOC_CRX_REL32 + -- : BFD_RELOC_CRX_REGREL12 + -- : BFD_RELOC_CRX_REGREL22 + -- : BFD_RELOC_CRX_REGREL28 + -- : BFD_RELOC_CRX_REGREL32 + -- : BFD_RELOC_CRX_ABS16 + -- : BFD_RELOC_CRX_ABS32 + -- : BFD_RELOC_CRX_NUM8 + -- : BFD_RELOC_CRX_NUM16 + -- : BFD_RELOC_CRX_NUM32 + -- : BFD_RELOC_CRX_IMM16 + -- : BFD_RELOC_CRX_IMM32 + -- : BFD_RELOC_CRX_SWITCH8 + -- : BFD_RELOC_CRX_SWITCH16 + -- : BFD_RELOC_CRX_SWITCH32 + NS CRX Relocations. + -- : BFD_RELOC_CRIS_BDISP8 + -- : BFD_RELOC_CRIS_UNSIGNED_5 + -- : BFD_RELOC_CRIS_SIGNED_6 + -- : BFD_RELOC_CRIS_UNSIGNED_6 + -- : BFD_RELOC_CRIS_SIGNED_8 + -- : BFD_RELOC_CRIS_UNSIGNED_8 + -- : BFD_RELOC_CRIS_SIGNED_16 + -- : BFD_RELOC_CRIS_UNSIGNED_16 + -- : BFD_RELOC_CRIS_LAPCQ_OFFSET + -- : BFD_RELOC_CRIS_UNSIGNED_4 + These relocs are only used within the CRIS assembler. They are not + (at present) written to any object files. + -- : BFD_RELOC_CRIS_COPY + -- : BFD_RELOC_CRIS_GLOB_DAT + -- : BFD_RELOC_CRIS_JUMP_SLOT + -- : BFD_RELOC_CRIS_RELATIVE + Relocs used in ELF shared libraries for CRIS. + -- : BFD_RELOC_CRIS_32_GOT + 32-bit offset to symbol-entry within GOT. + -- : BFD_RELOC_CRIS_16_GOT + 16-bit offset to symbol-entry within GOT. + -- : BFD_RELOC_CRIS_32_GOTPLT + 32-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_CRIS_16_GOTPLT + 16-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_CRIS_32_GOTREL + 32-bit offset to symbol, relative to GOT. + -- : BFD_RELOC_CRIS_32_PLT_GOTREL + 32-bit offset to symbol with PLT entry, relative to GOT. + -- : BFD_RELOC_CRIS_32_PLT_PCREL + 32-bit offset to symbol with PLT entry, relative to this + relocation. + -- : BFD_RELOC_CRIS_32_GOT_GD + -- : BFD_RELOC_CRIS_16_GOT_GD + -- : BFD_RELOC_CRIS_32_GD + -- : BFD_RELOC_CRIS_DTP + -- : BFD_RELOC_CRIS_32_DTPREL + -- : BFD_RELOC_CRIS_16_DTPREL + -- : BFD_RELOC_CRIS_32_GOT_TPREL + -- : BFD_RELOC_CRIS_16_GOT_TPREL + -- : BFD_RELOC_CRIS_32_TPREL + -- : BFD_RELOC_CRIS_16_TPREL + -- : BFD_RELOC_CRIS_DTPMOD + -- : BFD_RELOC_CRIS_32_IE + Relocs used in TLS code for CRIS. + -- : BFD_RELOC_860_COPY + -- : BFD_RELOC_860_GLOB_DAT + -- : BFD_RELOC_860_JUMP_SLOT + -- : BFD_RELOC_860_RELATIVE + -- : BFD_RELOC_860_PC26 + -- : BFD_RELOC_860_PLT26 + -- : BFD_RELOC_860_PC16 + -- : BFD_RELOC_860_LOW0 + -- : BFD_RELOC_860_SPLIT0 + -- : BFD_RELOC_860_LOW1 + -- : BFD_RELOC_860_SPLIT1 + -- : BFD_RELOC_860_LOW2 + -- : BFD_RELOC_860_SPLIT2 + -- : BFD_RELOC_860_LOW3 + -- : BFD_RELOC_860_LOGOT0 + -- : BFD_RELOC_860_SPGOT0 + -- : BFD_RELOC_860_LOGOT1 + -- : BFD_RELOC_860_SPGOT1 + -- : BFD_RELOC_860_LOGOTOFF0 + -- : BFD_RELOC_860_SPGOTOFF0 + -- : BFD_RELOC_860_LOGOTOFF1 + -- : BFD_RELOC_860_SPGOTOFF1 + -- : BFD_RELOC_860_LOGOTOFF2 + -- : BFD_RELOC_860_LOGOTOFF3 + -- : BFD_RELOC_860_LOPC + -- : BFD_RELOC_860_HIGHADJ + -- : BFD_RELOC_860_HAGOT + -- : BFD_RELOC_860_HAGOTOFF + -- : BFD_RELOC_860_HAPC + -- : BFD_RELOC_860_HIGH + -- : BFD_RELOC_860_HIGOT + -- : BFD_RELOC_860_HIGOTOFF + Intel i860 Relocations. + -- : BFD_RELOC_OPENRISC_ABS_26 + -- : BFD_RELOC_OPENRISC_REL_26 + OpenRISC Relocations. + -- : BFD_RELOC_H8_DIR16A8 + -- : BFD_RELOC_H8_DIR16R8 + -- : BFD_RELOC_H8_DIR24A8 + -- : BFD_RELOC_H8_DIR24R8 + -- : BFD_RELOC_H8_DIR32A16 + -- : BFD_RELOC_H8_DISP32A16 + H8 elf Relocations. + -- : BFD_RELOC_XSTORMY16_REL_12 + -- : BFD_RELOC_XSTORMY16_12 + -- : BFD_RELOC_XSTORMY16_24 + -- : BFD_RELOC_XSTORMY16_FPTR16 + Sony Xstormy16 Relocations. + -- : BFD_RELOC_RELC + Self-describing complex relocations. + -- : BFD_RELOC_XC16X_PAG + -- : BFD_RELOC_XC16X_POF + -- : BFD_RELOC_XC16X_SEG + -- : BFD_RELOC_XC16X_SOF + Infineon Relocations. + -- : BFD_RELOC_VAX_GLOB_DAT + -- : BFD_RELOC_VAX_JMP_SLOT + -- : BFD_RELOC_VAX_RELATIVE + Relocations used by VAX ELF. + -- : BFD_RELOC_MT_PC16 + Morpho MT - 16 bit immediate relocation. + -- : BFD_RELOC_MT_HI16 + Morpho MT - Hi 16 bits of an address. + -- : BFD_RELOC_MT_LO16 + Morpho MT - Low 16 bits of an address. + -- : BFD_RELOC_MT_GNU_VTINHERIT + Morpho MT - Used to tell the linker which vtable entries are used. + -- : BFD_RELOC_MT_GNU_VTENTRY + Morpho MT - Used to tell the linker which vtable entries are used. + -- : BFD_RELOC_MT_PCINSN8 + Morpho MT - 8 bit immediate relocation. + -- : BFD_RELOC_MSP430_10_PCREL + -- : BFD_RELOC_MSP430_16_PCREL + -- : BFD_RELOC_MSP430_16 + -- : BFD_RELOC_MSP430_16_PCREL_BYTE + -- : BFD_RELOC_MSP430_16_BYTE + -- : BFD_RELOC_MSP430_2X_PCREL + -- : BFD_RELOC_MSP430_RL_PCREL + -- : BFD_RELOC_MSP430_ABS8 + -- : BFD_RELOC_MSP430X_PCR20_EXT_SRC + -- : BFD_RELOC_MSP430X_PCR20_EXT_DST + -- : BFD_RELOC_MSP430X_PCR20_EXT_ODST + -- : BFD_RELOC_MSP430X_ABS20_EXT_SRC + -- : BFD_RELOC_MSP430X_ABS20_EXT_DST + -- : BFD_RELOC_MSP430X_ABS20_EXT_ODST + -- : BFD_RELOC_MSP430X_ABS20_ADR_SRC + -- : BFD_RELOC_MSP430X_ABS20_ADR_DST + -- : BFD_RELOC_MSP430X_PCR16 + -- : BFD_RELOC_MSP430X_PCR20_CALL + -- : BFD_RELOC_MSP430X_ABS16 + -- : BFD_RELOC_MSP430_ABS_HI16 + -- : BFD_RELOC_MSP430_PREL31 + -- : BFD_RELOC_MSP430_SYM_DIFF + msp430 specific relocation codes + -- : BFD_RELOC_NIOS2_S16 + -- : BFD_RELOC_NIOS2_U16 + -- : BFD_RELOC_NIOS2_CALL26 + -- : BFD_RELOC_NIOS2_IMM5 + -- : BFD_RELOC_NIOS2_CACHE_OPX + -- : BFD_RELOC_NIOS2_IMM6 + -- : BFD_RELOC_NIOS2_IMM8 + -- : BFD_RELOC_NIOS2_HI16 + -- : BFD_RELOC_NIOS2_LO16 + -- : BFD_RELOC_NIOS2_HIADJ16 + -- : BFD_RELOC_NIOS2_GPREL + -- : BFD_RELOC_NIOS2_UJMP + -- : BFD_RELOC_NIOS2_CJMP + -- : BFD_RELOC_NIOS2_CALLR + -- : BFD_RELOC_NIOS2_ALIGN + -- : BFD_RELOC_NIOS2_GOT16 + -- : BFD_RELOC_NIOS2_CALL16 + -- : BFD_RELOC_NIOS2_GOTOFF_LO + -- : BFD_RELOC_NIOS2_GOTOFF_HA + -- : BFD_RELOC_NIOS2_PCREL_LO + -- : BFD_RELOC_NIOS2_PCREL_HA + -- : BFD_RELOC_NIOS2_TLS_GD16 + -- : BFD_RELOC_NIOS2_TLS_LDM16 + -- : BFD_RELOC_NIOS2_TLS_LDO16 + -- : BFD_RELOC_NIOS2_TLS_IE16 + -- : BFD_RELOC_NIOS2_TLS_LE16 + -- : BFD_RELOC_NIOS2_TLS_DTPMOD + -- : BFD_RELOC_NIOS2_TLS_DTPREL + -- : BFD_RELOC_NIOS2_TLS_TPREL + -- : BFD_RELOC_NIOS2_COPY + -- : BFD_RELOC_NIOS2_GLOB_DAT + -- : BFD_RELOC_NIOS2_JUMP_SLOT + -- : BFD_RELOC_NIOS2_RELATIVE + -- : BFD_RELOC_NIOS2_GOTOFF + Relocations used by the Altera Nios II core. + -- : BFD_RELOC_IQ2000_OFFSET_16 + -- : BFD_RELOC_IQ2000_OFFSET_21 + -- : BFD_RELOC_IQ2000_UHI16 + IQ2000 Relocations. + -- : BFD_RELOC_XTENSA_RTLD + Special Xtensa relocation used only by PLT entries in ELF shared + objects to indicate that the runtime linker should set the value to + one of its own internal functions or data structures. + -- : BFD_RELOC_XTENSA_GLOB_DAT + -- : BFD_RELOC_XTENSA_JMP_SLOT + -- : BFD_RELOC_XTENSA_RELATIVE + Xtensa relocations for ELF shared objects. + -- : BFD_RELOC_XTENSA_PLT + Xtensa relocation used in ELF object files for symbols that may + require PLT entries. Otherwise, this is just a generic 32-bit + relocation. + -- : BFD_RELOC_XTENSA_DIFF8 + -- : BFD_RELOC_XTENSA_DIFF16 + -- : BFD_RELOC_XTENSA_DIFF32 + Xtensa relocations to mark the difference of two local symbols. + These are only needed to support linker relaxation and can be + ignored when not relaxing. The field is set to the value of the + difference assuming no relaxation. The relocation encodes the + position of the first symbol so the linker can determine whether to + adjust the field value. + -- : BFD_RELOC_XTENSA_SLOT0_OP + -- : BFD_RELOC_XTENSA_SLOT1_OP + -- : BFD_RELOC_XTENSA_SLOT2_OP + -- : BFD_RELOC_XTENSA_SLOT3_OP + -- : BFD_RELOC_XTENSA_SLOT4_OP + -- : BFD_RELOC_XTENSA_SLOT5_OP + -- : BFD_RELOC_XTENSA_SLOT6_OP + -- : BFD_RELOC_XTENSA_SLOT7_OP + -- : BFD_RELOC_XTENSA_SLOT8_OP + -- : BFD_RELOC_XTENSA_SLOT9_OP + -- : BFD_RELOC_XTENSA_SLOT10_OP + -- : BFD_RELOC_XTENSA_SLOT11_OP + -- : BFD_RELOC_XTENSA_SLOT12_OP + -- : BFD_RELOC_XTENSA_SLOT13_OP + -- : BFD_RELOC_XTENSA_SLOT14_OP + Generic Xtensa relocations for instruction operands. Only the slot + number is encoded in the relocation. The relocation applies to the + last PC-relative immediate operand, or if there are no PC-relative + immediates, to the last immediate operand. + -- : BFD_RELOC_XTENSA_SLOT0_ALT + -- : BFD_RELOC_XTENSA_SLOT1_ALT + -- : BFD_RELOC_XTENSA_SLOT2_ALT + -- : BFD_RELOC_XTENSA_SLOT3_ALT + -- : BFD_RELOC_XTENSA_SLOT4_ALT + -- : BFD_RELOC_XTENSA_SLOT5_ALT + -- : BFD_RELOC_XTENSA_SLOT6_ALT + -- : BFD_RELOC_XTENSA_SLOT7_ALT + -- : BFD_RELOC_XTENSA_SLOT8_ALT + -- : BFD_RELOC_XTENSA_SLOT9_ALT + -- : BFD_RELOC_XTENSA_SLOT10_ALT + -- : BFD_RELOC_XTENSA_SLOT11_ALT + -- : BFD_RELOC_XTENSA_SLOT12_ALT + -- : BFD_RELOC_XTENSA_SLOT13_ALT + -- : BFD_RELOC_XTENSA_SLOT14_ALT + Alternate Xtensa relocations. Only the slot is encoded in the + relocation. The meaning of these relocations is opcode-specific. + -- : BFD_RELOC_XTENSA_OP0 + -- : BFD_RELOC_XTENSA_OP1 + -- : BFD_RELOC_XTENSA_OP2 + Xtensa relocations for backward compatibility. These have all been + replaced by BFD_RELOC_XTENSA_SLOT0_OP. + -- : BFD_RELOC_XTENSA_ASM_EXPAND + Xtensa relocation to mark that the assembler expanded the + instructions from an original target. The expansion size is + encoded in the reloc size. + -- : BFD_RELOC_XTENSA_ASM_SIMPLIFY + Xtensa relocation to mark that the linker should simplify + assembler-expanded instructions. This is commonly used internally + by the linker after analysis of a BFD_RELOC_XTENSA_ASM_EXPAND. + -- : BFD_RELOC_XTENSA_TLSDESC_FN + -- : BFD_RELOC_XTENSA_TLSDESC_ARG + -- : BFD_RELOC_XTENSA_TLS_DTPOFF + -- : BFD_RELOC_XTENSA_TLS_TPOFF + -- : BFD_RELOC_XTENSA_TLS_FUNC + -- : BFD_RELOC_XTENSA_TLS_ARG + -- : BFD_RELOC_XTENSA_TLS_CALL + Xtensa TLS relocations. + -- : BFD_RELOC_Z80_DISP8 + 8 bit signed offset in (ix+d) or (iy+d). + -- : BFD_RELOC_Z8K_DISP7 + DJNZ offset. + -- : BFD_RELOC_Z8K_CALLR + CALR offset. + -- : BFD_RELOC_Z8K_IMM4L + 4 bit value. + -- : BFD_RELOC_LM32_CALL + -- : BFD_RELOC_LM32_BRANCH + -- : BFD_RELOC_LM32_16_GOT + -- : BFD_RELOC_LM32_GOTOFF_HI16 + -- : BFD_RELOC_LM32_GOTOFF_LO16 + -- : BFD_RELOC_LM32_COPY + -- : BFD_RELOC_LM32_GLOB_DAT + -- : BFD_RELOC_LM32_JMP_SLOT + -- : BFD_RELOC_LM32_RELATIVE + Lattice Mico32 relocations. + -- : BFD_RELOC_MACH_O_SECTDIFF + Difference between two section addreses. Must be followed by a + BFD_RELOC_MACH_O_PAIR. + -- : BFD_RELOC_MACH_O_LOCAL_SECTDIFF + Like BFD_RELOC_MACH_O_SECTDIFF but with a local symbol. + -- : BFD_RELOC_MACH_O_PAIR + Pair of relocation. Contains the first symbol. + -- : BFD_RELOC_MACH_O_X86_64_BRANCH32 + -- : BFD_RELOC_MACH_O_X86_64_BRANCH8 + PCREL relocations. They are marked as branch to create PLT entry + if required. + -- : BFD_RELOC_MACH_O_X86_64_GOT + Used when referencing a GOT entry. + -- : BFD_RELOC_MACH_O_X86_64_GOT_LOAD + Used when loading a GOT entry with movq. It is specially marked so + that the linker could optimize the movq to a leaq if possible. + -- : BFD_RELOC_MACH_O_X86_64_SUBTRACTOR32 + Symbol will be substracted. Must be followed by a BFD_RELOC_64. + -- : BFD_RELOC_MACH_O_X86_64_SUBTRACTOR64 + Symbol will be substracted. Must be followed by a BFD_RELOC_64. + -- : BFD_RELOC_MACH_O_X86_64_PCREL32_1 + Same as BFD_RELOC_32_PCREL but with an implicit -1 addend. + -- : BFD_RELOC_MACH_O_X86_64_PCREL32_2 + Same as BFD_RELOC_32_PCREL but with an implicit -2 addend. + -- : BFD_RELOC_MACH_O_X86_64_PCREL32_4 + Same as BFD_RELOC_32_PCREL but with an implicit -4 addend. + -- : BFD_RELOC_MICROBLAZE_32_LO + This is a 32 bit reloc for the microblaze that stores the low 16 + bits of a value + -- : BFD_RELOC_MICROBLAZE_32_LO_PCREL + This is a 32 bit pc-relative reloc for the microblaze that stores + the low 16 bits of a value + -- : BFD_RELOC_MICROBLAZE_32_ROSDA + This is a 32 bit reloc for the microblaze that stores a value + relative to the read-only small data area anchor + -- : BFD_RELOC_MICROBLAZE_32_RWSDA + This is a 32 bit reloc for the microblaze that stores a value + relative to the read-write small data area anchor + -- : BFD_RELOC_MICROBLAZE_32_SYM_OP_SYM + This is a 32 bit reloc for the microblaze to handle expressions of + the form "Symbol Op Symbol" + -- : BFD_RELOC_MICROBLAZE_64_NONE + This is a 64 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). No relocation is done here - + only used for relaxing + -- : BFD_RELOC_MICROBLAZE_64_GOTPC + This is a 64 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). The relocation is PC-relative + GOT offset + -- : BFD_RELOC_MICROBLAZE_64_GOT + This is a 64 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). The relocation is GOT offset + -- : BFD_RELOC_MICROBLAZE_64_PLT + This is a 64 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). The relocation is PC-relative + offset into PLT + -- : BFD_RELOC_MICROBLAZE_64_GOTOFF + This is a 64 bit reloc that stores the 32 bit GOT relative value in + two words (with an imm instruction). The relocation is relative + offset from _GLOBAL_OFFSET_TABLE_ + -- : BFD_RELOC_MICROBLAZE_32_GOTOFF + This is a 32 bit reloc that stores the 32 bit GOT relative value in + a word. The relocation is relative offset from + -- : BFD_RELOC_MICROBLAZE_COPY + This is used to tell the dynamic linker to copy the value out of + the dynamic object into the runtime process image. + -- : BFD_RELOC_MICROBLAZE_64_TLS + Unused Reloc + -- : BFD_RELOC_MICROBLAZE_64_TLSGD + This is a 64 bit reloc that stores the 32 bit GOT relative value of + the GOT TLS GD info entry in two words (with an imm instruction). + The relocation is GOT offset. + -- : BFD_RELOC_MICROBLAZE_64_TLSLD + This is a 64 bit reloc that stores the 32 bit GOT relative value of + the GOT TLS LD info entry in two words (with an imm instruction). + The relocation is GOT offset. + -- : BFD_RELOC_MICROBLAZE_32_TLSDTPMOD + This is a 32 bit reloc that stores the Module ID to GOT(n). + -- : BFD_RELOC_MICROBLAZE_32_TLSDTPREL + This is a 32 bit reloc that stores TLS offset to GOT(n+1). + -- : BFD_RELOC_MICROBLAZE_64_TLSDTPREL + This is a 32 bit reloc for storing TLS offset to two words (uses + imm instruction) + -- : BFD_RELOC_MICROBLAZE_64_TLSGOTTPREL + This is a 64 bit reloc that stores 32-bit thread pointer relative + offset to two words (uses imm instruction). + -- : BFD_RELOC_MICROBLAZE_64_TLSTPREL + This is a 64 bit reloc that stores 32-bit thread pointer relative + offset to two words (uses imm instruction). + -- : BFD_RELOC_AARCH64_RELOC_START + AArch64 pseudo relocation code to mark the start of the AArch64 + relocation enumerators. N.B. the order of the enumerators is + important as several tables in the AArch64 bfd backend are indexed + by these enumerators; make sure they are all synced. + -- : BFD_RELOC_AARCH64_NONE + AArch64 null relocation code. + -- : BFD_RELOC_AARCH64_64 + -- : BFD_RELOC_AARCH64_32 + -- : BFD_RELOC_AARCH64_16 + Basic absolute relocations of N bits. These are equivalent to + BFD_RELOC_N and they were added to assist the indexing of the howto + table. + -- : BFD_RELOC_AARCH64_64_PCREL + -- : BFD_RELOC_AARCH64_32_PCREL + -- : BFD_RELOC_AARCH64_16_PCREL + PC-relative relocations. These are equivalent to BFD_RELOC_N_PCREL + and they were added to assist the indexing of the howto table. + -- : BFD_RELOC_AARCH64_MOVW_G0 + AArch64 MOV[NZK] instruction with most significant bits 0 to 15 of + an unsigned address/value. + -- : BFD_RELOC_AARCH64_MOVW_G0_NC + AArch64 MOV[NZK] instruction with less significant bits 0 to 15 of + an address/value. No overflow checking. + -- : BFD_RELOC_AARCH64_MOVW_G1 + AArch64 MOV[NZK] instruction with most significant bits 16 to 31 of + an unsigned address/value. + -- : BFD_RELOC_AARCH64_MOVW_G1_NC + AArch64 MOV[NZK] instruction with less significant bits 16 to 31 of + an address/value. No overflow checking. + -- : BFD_RELOC_AARCH64_MOVW_G2 + AArch64 MOV[NZK] instruction with most significant bits 32 to 47 of + an unsigned address/value. + -- : BFD_RELOC_AARCH64_MOVW_G2_NC + AArch64 MOV[NZK] instruction with less significant bits 32 to 47 of + an address/value. No overflow checking. + -- : BFD_RELOC_AARCH64_MOVW_G3 + AArch64 MOV[NZK] instruction with most signficant bits 48 to 64 of + a signed or unsigned address/value. + -- : BFD_RELOC_AARCH64_MOVW_G0_S + AArch64 MOV[NZ] instruction with most significant bits 0 to 15 of a + signed value. Changes instruction to MOVZ or MOVN depending on the + value's sign. + -- : BFD_RELOC_AARCH64_MOVW_G1_S + AArch64 MOV[NZ] instruction with most significant bits 16 to 31 of + a signed value. Changes instruction to MOVZ or MOVN depending on + the value's sign. + -- : BFD_RELOC_AARCH64_MOVW_G2_S + AArch64 MOV[NZ] instruction with most significant bits 32 to 47 of + a signed value. Changes instruction to MOVZ or MOVN depending on + the value's sign. + -- : BFD_RELOC_AARCH64_LD_LO19_PCREL + AArch64 Load Literal instruction, holding a 19 bit pc-relative word + offset. The lowest two bits must be zero and are not stored in the + instruction, giving a 21 bit signed byte offset. + -- : BFD_RELOC_AARCH64_ADR_LO21_PCREL + AArch64 ADR instruction, holding a simple 21 bit pc-relative byte + offset. + -- : BFD_RELOC_AARCH64_ADR_HI21_PCREL + AArch64 ADRP instruction, with bits 12 to 32 of a pc-relative page + offset, giving a 4KB aligned page base address. + -- : BFD_RELOC_AARCH64_ADR_HI21_NC_PCREL + AArch64 ADRP instruction, with bits 12 to 32 of a pc-relative page + offset, giving a 4KB aligned page base address, but with no + overflow checking. + -- : BFD_RELOC_AARCH64_ADD_LO12 + AArch64 ADD immediate instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_LDST8_LO12 + AArch64 8-bit load/store instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_TSTBR14 + AArch64 14 bit pc-relative test bit and branch. The lowest two + bits must be zero and are not stored in the instruction, giving a + 16 bit signed byte offset. + -- : BFD_RELOC_AARCH64_BRANCH19 + AArch64 19 bit pc-relative conditional branch and compare & branch. + The lowest two bits must be zero and are not stored in the + instruction, giving a 21 bit signed byte offset. + -- : BFD_RELOC_AARCH64_JUMP26 + AArch64 26 bit pc-relative unconditional branch. The lowest two + bits must be zero and are not stored in the instruction, giving a + 28 bit signed byte offset. + -- : BFD_RELOC_AARCH64_CALL26 + AArch64 26 bit pc-relative unconditional branch and link. The + lowest two bits must be zero and are not stored in the instruction, + giving a 28 bit signed byte offset. + -- : BFD_RELOC_AARCH64_LDST16_LO12 + AArch64 16-bit load/store instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_LDST32_LO12 + AArch64 32-bit load/store instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_LDST64_LO12 + AArch64 64-bit load/store instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_LDST128_LO12 + AArch64 128-bit load/store instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_GOT_LD_PREL19 + AArch64 Load Literal instruction, holding a 19 bit PC relative word + offset of the global offset table entry for a symbol. The lowest + two bits must be zero and are not stored in the instruction, giving + a 21 bit signed byte offset. This relocation type requires signed + overflow checking. + -- : BFD_RELOC_AARCH64_ADR_GOT_PAGE + Get to the page base of the global offset table entry for a symbol + as part of an ADRP instruction using a 21 bit PC relative + value.Used in conjunction with BFD_RELOC_AARCH64_LD64_GOT_LO12_NC. + -- : BFD_RELOC_AARCH64_LD64_GOT_LO12_NC + Unsigned 12 bit byte offset for 64 bit load/store from the page of + the GOT entry for this symbol. Used in conjunction with + BFD_RELOC_AARCH64_ADR_GOTPAGE. Valid in LP64 ABI only. + -- : BFD_RELOC_AARCH64_LD32_GOT_LO12_NC + Unsigned 12 bit byte offset for 32 bit load/store from the page of + the GOT entry for this symbol. Used in conjunction with + BFD_RELOC_AARCH64_ADR_GOTPAGE. Valid in ILP32 ABI only. + -- : BFD_RELOC_AARCH64_TLSGD_ADR_PAGE21 + Get to the page base of the global offset table entry for a symbols + tls_index structure as part of an adrp instruction using a 21 bit + PC relative value. Used in conjunction with + BFD_RELOC_AARCH64_TLSGD_ADD_LO12_NC. + -- : BFD_RELOC_AARCH64_TLSGD_ADD_LO12_NC + Unsigned 12 bit byte offset to global offset table entry for a + symbols tls_index structure. Used in conjunction with + BFD_RELOC_AARCH64_TLSGD_ADR_PAGE21. + -- : BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G1 + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G0_NC + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSIE_ADR_GOTTPREL_PAGE21 + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSIE_LD64_GOTTPREL_LO12_NC + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSIE_LD32_GOTTPREL_LO12_NC + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_PREL19 + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G2 + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1 + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1_NC + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0 + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0_NC + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_HI12 + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12 + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12_NC + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_LD_PREL19 + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_ADR_PREL21 + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_ADR_PAGE21 + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_LD64_LO12_NC + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_LD32_LO12_NC + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_ADD_LO12_NC + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_OFF_G1 + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_OFF_G0_NC + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_LDR + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_ADD + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_TLSDESC_CALL + AArch64 TLS DESC relocation. + -- : BFD_RELOC_AARCH64_COPY + AArch64 TLS relocation. + -- : BFD_RELOC_AARCH64_GLOB_DAT + AArch64 TLS relocation. + -- : BFD_RELOC_AARCH64_JUMP_SLOT + AArch64 TLS relocation. + -- : BFD_RELOC_AARCH64_RELATIVE + AArch64 TLS relocation. + -- : BFD_RELOC_AARCH64_TLS_DTPMOD + AArch64 TLS relocation. + -- : BFD_RELOC_AARCH64_TLS_DTPREL + AArch64 TLS relocation. + -- : BFD_RELOC_AARCH64_TLS_TPREL + AArch64 TLS relocation. + -- : BFD_RELOC_AARCH64_TLSDESC + AArch64 TLS relocation. + -- : BFD_RELOC_AARCH64_IRELATIVE + AArch64 support for STT_GNU_IFUNC. + -- : BFD_RELOC_AARCH64_RELOC_END + AArch64 pseudo relocation code to mark the end of the AArch64 + relocation enumerators that have direct mapping to ELF reloc codes. + There are a few more enumerators after this one; those are mainly + used by the AArch64 assembler for the internal fixup or to select + one of the above enumerators. + -- : BFD_RELOC_AARCH64_GAS_INTERNAL_FIXUP + AArch64 pseudo relocation code to be used internally by the AArch64 + assembler and not (currently) written to any object files. + -- : BFD_RELOC_AARCH64_LDST_LO12 + AArch64 unspecified load/store instruction, holding bits 0 to 11 of + the address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_LD_GOT_LO12_NC + AArch64 pseudo relocation code to be used internally by the AArch64 + assembler and not (currently) written to any object files. + -- : BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_LO12_NC + AArch64 pseudo relocation code to be used internally by the AArch64 + assembler and not (currently) written to any object files. + -- : BFD_RELOC_AARCH64_TLSDESC_LD_LO12_NC + AArch64 pseudo relocation code to be used internally by the AArch64 + assembler and not (currently) written to any object files. + -- : BFD_RELOC_TILEPRO_COPY + -- : BFD_RELOC_TILEPRO_GLOB_DAT + -- : BFD_RELOC_TILEPRO_JMP_SLOT + -- : BFD_RELOC_TILEPRO_RELATIVE + -- : BFD_RELOC_TILEPRO_BROFF_X1 + -- : BFD_RELOC_TILEPRO_JOFFLONG_X1 + -- : BFD_RELOC_TILEPRO_JOFFLONG_X1_PLT + -- : BFD_RELOC_TILEPRO_IMM8_X0 + -- : BFD_RELOC_TILEPRO_IMM8_Y0 + -- : BFD_RELOC_TILEPRO_IMM8_X1 + -- : BFD_RELOC_TILEPRO_IMM8_Y1 + -- : BFD_RELOC_TILEPRO_DEST_IMM8_X1 + -- : BFD_RELOC_TILEPRO_MT_IMM15_X1 + -- : BFD_RELOC_TILEPRO_MF_IMM15_X1 + -- : BFD_RELOC_TILEPRO_IMM16_X0 + -- : BFD_RELOC_TILEPRO_IMM16_X1 + -- : BFD_RELOC_TILEPRO_IMM16_X0_LO + -- : BFD_RELOC_TILEPRO_IMM16_X1_LO + -- : BFD_RELOC_TILEPRO_IMM16_X0_HI + -- : BFD_RELOC_TILEPRO_IMM16_X1_HI + -- : BFD_RELOC_TILEPRO_IMM16_X0_HA + -- : BFD_RELOC_TILEPRO_IMM16_X1_HA + -- : BFD_RELOC_TILEPRO_IMM16_X0_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X1_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X0_LO_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X1_LO_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X0_HI_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X1_HI_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X0_HA_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X1_HA_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X0_GOT + -- : BFD_RELOC_TILEPRO_IMM16_X1_GOT + -- : BFD_RELOC_TILEPRO_IMM16_X0_GOT_LO + -- : BFD_RELOC_TILEPRO_IMM16_X1_GOT_LO + -- : BFD_RELOC_TILEPRO_IMM16_X0_GOT_HI + -- : BFD_RELOC_TILEPRO_IMM16_X1_GOT_HI + -- : BFD_RELOC_TILEPRO_IMM16_X0_GOT_HA + -- : BFD_RELOC_TILEPRO_IMM16_X1_GOT_HA + -- : BFD_RELOC_TILEPRO_MMSTART_X0 + -- : BFD_RELOC_TILEPRO_MMEND_X0 + -- : BFD_RELOC_TILEPRO_MMSTART_X1 + -- : BFD_RELOC_TILEPRO_MMEND_X1 + -- : BFD_RELOC_TILEPRO_SHAMT_X0 + -- : BFD_RELOC_TILEPRO_SHAMT_X1 + -- : BFD_RELOC_TILEPRO_SHAMT_Y0 + -- : BFD_RELOC_TILEPRO_SHAMT_Y1 + -- : BFD_RELOC_TILEPRO_TLS_GD_CALL + -- : BFD_RELOC_TILEPRO_IMM8_X0_TLS_GD_ADD + -- : BFD_RELOC_TILEPRO_IMM8_X1_TLS_GD_ADD + -- : BFD_RELOC_TILEPRO_IMM8_Y0_TLS_GD_ADD + -- : BFD_RELOC_TILEPRO_IMM8_Y1_TLS_GD_ADD + -- : BFD_RELOC_TILEPRO_TLS_IE_LOAD + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_LO + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_LO + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HI + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HI + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HA + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HA + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_LO + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_LO + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HI + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HI + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HA + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HA + -- : BFD_RELOC_TILEPRO_TLS_DTPMOD32 + -- : BFD_RELOC_TILEPRO_TLS_DTPOFF32 + -- : BFD_RELOC_TILEPRO_TLS_TPOFF32 + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_LO + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_LO + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HI + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HI + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HA + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HA + Tilera TILEPro Relocations. + -- : BFD_RELOC_TILEGX_HW0 + -- : BFD_RELOC_TILEGX_HW1 + -- : BFD_RELOC_TILEGX_HW2 + -- : BFD_RELOC_TILEGX_HW3 + -- : BFD_RELOC_TILEGX_HW0_LAST + -- : BFD_RELOC_TILEGX_HW1_LAST + -- : BFD_RELOC_TILEGX_HW2_LAST + -- : BFD_RELOC_TILEGX_COPY + -- : BFD_RELOC_TILEGX_GLOB_DAT + -- : BFD_RELOC_TILEGX_JMP_SLOT + -- : BFD_RELOC_TILEGX_RELATIVE + -- : BFD_RELOC_TILEGX_BROFF_X1 + -- : BFD_RELOC_TILEGX_JUMPOFF_X1 + -- : BFD_RELOC_TILEGX_JUMPOFF_X1_PLT + -- : BFD_RELOC_TILEGX_IMM8_X0 + -- : BFD_RELOC_TILEGX_IMM8_Y0 + -- : BFD_RELOC_TILEGX_IMM8_X1 + -- : BFD_RELOC_TILEGX_IMM8_Y1 + -- : BFD_RELOC_TILEGX_DEST_IMM8_X1 + -- : BFD_RELOC_TILEGX_MT_IMM14_X1 + -- : BFD_RELOC_TILEGX_MF_IMM14_X1 + -- : BFD_RELOC_TILEGX_MMSTART_X0 + -- : BFD_RELOC_TILEGX_MMEND_X0 + -- : BFD_RELOC_TILEGX_SHAMT_X0 + -- : BFD_RELOC_TILEGX_SHAMT_X1 + -- : BFD_RELOC_TILEGX_SHAMT_Y0 + -- : BFD_RELOC_TILEGX_SHAMT_Y1 + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0 + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0 + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1 + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1 + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2 + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2 + -- : BFD_RELOC_TILEGX_IMM16_X0_HW3 + -- : BFD_RELOC_TILEGX_IMM16_X1_HW3 + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW3_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW3_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_GOT + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_GOT + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_GOT + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_GOT + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_GOT + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_GOT + -- : BFD_RELOC_TILEGX_IMM16_X0_HW3_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW3_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_IE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_IE + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_IE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_IE + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_IE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_IE + -- : BFD_RELOC_TILEGX_TLS_DTPMOD64 + -- : BFD_RELOC_TILEGX_TLS_DTPOFF64 + -- : BFD_RELOC_TILEGX_TLS_TPOFF64 + -- : BFD_RELOC_TILEGX_TLS_DTPMOD32 + -- : BFD_RELOC_TILEGX_TLS_DTPOFF32 + -- : BFD_RELOC_TILEGX_TLS_TPOFF32 + -- : BFD_RELOC_TILEGX_TLS_GD_CALL + -- : BFD_RELOC_TILEGX_IMM8_X0_TLS_GD_ADD + -- : BFD_RELOC_TILEGX_IMM8_X1_TLS_GD_ADD + -- : BFD_RELOC_TILEGX_IMM8_Y0_TLS_GD_ADD + -- : BFD_RELOC_TILEGX_IMM8_Y1_TLS_GD_ADD + -- : BFD_RELOC_TILEGX_TLS_IE_LOAD + -- : BFD_RELOC_TILEGX_IMM8_X0_TLS_ADD + -- : BFD_RELOC_TILEGX_IMM8_X1_TLS_ADD + -- : BFD_RELOC_TILEGX_IMM8_Y0_TLS_ADD + -- : BFD_RELOC_TILEGX_IMM8_Y1_TLS_ADD + Tilera TILE-Gx Relocations. + -- : BFD_RELOC_EPIPHANY_SIMM8 + Adapteva EPIPHANY - 8 bit signed pc-relative displacement + -- : BFD_RELOC_EPIPHANY_SIMM24 + Adapteva EPIPHANY - 24 bit signed pc-relative displacement + -- : BFD_RELOC_EPIPHANY_HIGH + Adapteva EPIPHANY - 16 most-significant bits of absolute address + -- : BFD_RELOC_EPIPHANY_LOW + Adapteva EPIPHANY - 16 least-significant bits of absolute address + -- : BFD_RELOC_EPIPHANY_SIMM11 + Adapteva EPIPHANY - 11 bit signed number - add/sub immediate + -- : BFD_RELOC_EPIPHANY_IMM11 + Adapteva EPIPHANY - 11 bit sign-magnitude number (ld/st + displacement) + -- : BFD_RELOC_EPIPHANY_IMM8 + Adapteva EPIPHANY - 8 bit immediate for 16 bit mov instruction. + + + typedef enum bfd_reloc_code_real bfd_reloc_code_real_type; + +2.10.2.2 'bfd_reloc_type_lookup' +................................ + +*Synopsis* + reloc_howto_type *bfd_reloc_type_lookup + (bfd *abfd, bfd_reloc_code_real_type code); + reloc_howto_type *bfd_reloc_name_lookup + (bfd *abfd, const char *reloc_name); + *Description* +Return a pointer to a howto structure which, when invoked, will perform +the relocation CODE on data from the architecture noted. + +2.10.2.3 'bfd_default_reloc_type_lookup' +........................................ + +*Synopsis* + reloc_howto_type *bfd_default_reloc_type_lookup + (bfd *abfd, bfd_reloc_code_real_type code); + *Description* +Provides a default relocation lookup routine for any architecture. + +2.10.2.4 'bfd_get_reloc_code_name' +.................................. + +*Synopsis* + const char *bfd_get_reloc_code_name (bfd_reloc_code_real_type code); + *Description* +Provides a printable name for the supplied relocation code. Useful +mainly for printing error messages. + +2.10.2.5 'bfd_generic_relax_section' +.................................... + +*Synopsis* + bfd_boolean bfd_generic_relax_section + (bfd *abfd, + asection *section, + struct bfd_link_info *, + bfd_boolean *); + *Description* +Provides default handling for relaxing for back ends which don't do +relaxing. + +2.10.2.6 'bfd_generic_gc_sections' +.................................. + +*Synopsis* + bfd_boolean bfd_generic_gc_sections + (bfd *, struct bfd_link_info *); + *Description* +Provides default handling for relaxing for back ends which don't do +section gc - i.e., does nothing. + +2.10.2.7 'bfd_generic_lookup_section_flags' +........................................... + +*Synopsis* + bfd_boolean bfd_generic_lookup_section_flags + (struct bfd_link_info *, struct flag_info *, asection *); + *Description* +Provides default handling for section flags lookup - i.e., does nothing. +Returns FALSE if the section should be omitted, otherwise TRUE. + +2.10.2.8 'bfd_generic_merge_sections' +..................................... + +*Synopsis* + bfd_boolean bfd_generic_merge_sections + (bfd *, struct bfd_link_info *); + *Description* +Provides default handling for SEC_MERGE section merging for back ends +which don't have SEC_MERGE support - i.e., does nothing. + +2.10.2.9 'bfd_generic_get_relocated_section_contents' +..................................................... + +*Synopsis* + bfd_byte *bfd_generic_get_relocated_section_contents + (bfd *abfd, + struct bfd_link_info *link_info, + struct bfd_link_order *link_order, + bfd_byte *data, + bfd_boolean relocatable, + asymbol **symbols); + *Description* +Provides default handling of relocation effort for back ends which can't +be bothered to do it efficiently. + + +File: bfd.info, Node: Core Files, Next: Targets, Prev: Relocations, Up: BFD front end + +2.11 Core files +=============== + +2.11.1 Core file functions +-------------------------- + +*Description* +These are functions pertaining to core files. + +2.11.1.1 'bfd_core_file_failing_command' +........................................ + +*Synopsis* + const char *bfd_core_file_failing_command (bfd *abfd); + *Description* +Return a read-only string explaining which program was running when it +failed and produced the core file ABFD. + +2.11.1.2 'bfd_core_file_failing_signal' +....................................... + +*Synopsis* + int bfd_core_file_failing_signal (bfd *abfd); + *Description* +Returns the signal number which caused the core dump which generated the +file the BFD ABFD is attached to. + +2.11.1.3 'bfd_core_file_pid' +............................ + +*Synopsis* + int bfd_core_file_pid (bfd *abfd); + *Description* +Returns the PID of the process the core dump the BFD ABFD is attached to +was generated from. + +2.11.1.4 'core_file_matches_executable_p' +......................................... + +*Synopsis* + bfd_boolean core_file_matches_executable_p + (bfd *core_bfd, bfd *exec_bfd); + *Description* +Return 'TRUE' if the core file attached to CORE_BFD was generated by a +run of the executable file attached to EXEC_BFD, 'FALSE' otherwise. + +2.11.1.5 'generic_core_file_matches_executable_p' +................................................. + +*Synopsis* + bfd_boolean generic_core_file_matches_executable_p + (bfd *core_bfd, bfd *exec_bfd); + *Description* +Return TRUE if the core file attached to CORE_BFD was generated by a run +of the executable file attached to EXEC_BFD. The match is based on +executable basenames only. + + Note: When not able to determine the core file failing command or the +executable name, we still return TRUE even though we're not sure that +core file and executable match. This is to avoid generating a false +warning in situations where we really don't know whether they match or +not. + + +File: bfd.info, Node: Targets, Next: Architectures, Prev: Core Files, Up: BFD front end + +2.12 Targets +============ + +*Description* +Each port of BFD to a different machine requires the creation of a +target back end. All the back end provides to the root part of BFD is a +structure containing pointers to functions which perform certain low +level operations on files. BFD translates the applications's requests +through a pointer into calls to the back end routines. + + When a file is opened with 'bfd_openr', its format and target are +unknown. BFD uses various mechanisms to determine how to interpret the +file. The operations performed are: + + * Create a BFD by calling the internal routine '_bfd_new_bfd', then + call 'bfd_find_target' with the target string supplied to + 'bfd_openr' and the new BFD pointer. + + * If a null target string was provided to 'bfd_find_target', look up + the environment variable 'GNUTARGET' and use that as the target + string. + + * If the target string is still 'NULL', or the target string is + 'default', then use the first item in the target vector as the + target type, and set 'target_defaulted' in the BFD to cause + 'bfd_check_format' to loop through all the targets. *Note + bfd_target::. *Note Formats::. + + * Otherwise, inspect the elements in the target vector one by one, + until a match on target name is found. When found, use it. + + * Otherwise return the error 'bfd_error_invalid_target' to + 'bfd_openr'. + + * 'bfd_openr' attempts to open the file using 'bfd_open_file', and + returns the BFD. + Once the BFD has been opened and the target selected, the file format +may be determined. This is done by calling 'bfd_check_format' on the +BFD with a suggested format. If 'target_defaulted' has been set, each +possible target type is tried to see if it recognizes the specified +format. 'bfd_check_format' returns 'TRUE' when the caller guesses +right. +* Menu: + +* bfd_target:: + + +File: bfd.info, Node: bfd_target, Prev: Targets, Up: Targets + +2.12.1 bfd_target +----------------- + +*Description* +This structure contains everything that BFD knows about a target. It +includes things like its byte order, name, and which routines to call to +do various operations. + + Every BFD points to a target structure with its 'xvec' member. + + The macros below are used to dispatch to functions through the +'bfd_target' vector. They are used in a number of macros further down +in 'bfd.h', and are also used when calling various routines by hand +inside the BFD implementation. The ARGLIST argument must be +parenthesized; it contains all the arguments to the called function. + + They make the documentation (more) unpleasant to read, so if someone +wants to fix this and not break the above, please do. + #define BFD_SEND(bfd, message, arglist) \ + ((*((bfd)->xvec->message)) arglist) + + #ifdef DEBUG_BFD_SEND + #undef BFD_SEND + #define BFD_SEND(bfd, message, arglist) \ + (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ + ((*((bfd)->xvec->message)) arglist) : \ + (bfd_assert (__FILE__,__LINE__), NULL)) + #endif + For operations which index on the BFD format: + #define BFD_SEND_FMT(bfd, message, arglist) \ + (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) + + #ifdef DEBUG_BFD_SEND + #undef BFD_SEND_FMT + #define BFD_SEND_FMT(bfd, message, arglist) \ + (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ + (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \ + (bfd_assert (__FILE__,__LINE__), NULL)) + #endif + + This is the structure which defines the type of BFD this is. The +'xvec' member of the struct 'bfd' itself points here. Each module that +implements access to a different target under BFD, defines one of these. + + FIXME, these names should be rationalised with the names of the entry +points which call them. Too bad we can't have one macro to define them +both! + enum bfd_flavour + { + bfd_target_unknown_flavour, + bfd_target_aout_flavour, + bfd_target_coff_flavour, + bfd_target_ecoff_flavour, + bfd_target_xcoff_flavour, + bfd_target_elf_flavour, + bfd_target_ieee_flavour, + bfd_target_nlm_flavour, + bfd_target_oasys_flavour, + bfd_target_tekhex_flavour, + bfd_target_srec_flavour, + bfd_target_verilog_flavour, + bfd_target_ihex_flavour, + bfd_target_som_flavour, + bfd_target_os9k_flavour, + bfd_target_versados_flavour, + bfd_target_msdos_flavour, + bfd_target_ovax_flavour, + bfd_target_evax_flavour, + bfd_target_mmo_flavour, + bfd_target_mach_o_flavour, + bfd_target_pef_flavour, + bfd_target_pef_xlib_flavour, + bfd_target_sym_flavour + }; + + enum bfd_endian { BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN }; + + /* Forward declaration. */ + typedef struct bfd_link_info _bfd_link_info; + + /* Forward declaration. */ + typedef struct flag_info flag_info; + + typedef struct bfd_target + { + /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc. */ + char *name; + + /* The "flavour" of a back end is a general indication about + the contents of a file. */ + enum bfd_flavour flavour; + + /* The order of bytes within the data area of a file. */ + enum bfd_endian byteorder; + + /* The order of bytes within the header parts of a file. */ + enum bfd_endian header_byteorder; + + /* A mask of all the flags which an executable may have set - + from the set BFD_NO_FLAGS, HAS_RELOC, ...D_PAGED. */ + flagword object_flags; + + /* A mask of all the flags which a section may have set - from + the set SEC_NO_FLAGS, SEC_ALLOC, ...SET_NEVER_LOAD. */ + flagword section_flags; + + /* The character normally found at the front of a symbol. + (if any), perhaps `_'. */ + char symbol_leading_char; + + /* The pad character for file names within an archive header. */ + char ar_pad_char; + + /* The maximum number of characters in an archive header. */ + unsigned char ar_max_namelen; + + /* How well this target matches, used to select between various + possible targets when more than one target matches. */ + unsigned char match_priority; + + /* Entries for byte swapping for data. These are different from the + other entry points, since they don't take a BFD as the first argument. + Certain other handlers could do the same. */ + bfd_uint64_t (*bfd_getx64) (const void *); + bfd_int64_t (*bfd_getx_signed_64) (const void *); + void (*bfd_putx64) (bfd_uint64_t, void *); + bfd_vma (*bfd_getx32) (const void *); + bfd_signed_vma (*bfd_getx_signed_32) (const void *); + void (*bfd_putx32) (bfd_vma, void *); + bfd_vma (*bfd_getx16) (const void *); + bfd_signed_vma (*bfd_getx_signed_16) (const void *); + void (*bfd_putx16) (bfd_vma, void *); + + /* Byte swapping for the headers. */ + bfd_uint64_t (*bfd_h_getx64) (const void *); + bfd_int64_t (*bfd_h_getx_signed_64) (const void *); + void (*bfd_h_putx64) (bfd_uint64_t, void *); + bfd_vma (*bfd_h_getx32) (const void *); + bfd_signed_vma (*bfd_h_getx_signed_32) (const void *); + void (*bfd_h_putx32) (bfd_vma, void *); + bfd_vma (*bfd_h_getx16) (const void *); + bfd_signed_vma (*bfd_h_getx_signed_16) (const void *); + void (*bfd_h_putx16) (bfd_vma, void *); + + /* Format dependent routines: these are vectors of entry points + within the target vector structure, one for each format to check. */ + + /* Check the format of a file being read. Return a bfd_target * or zero. */ + const struct bfd_target *(*_bfd_check_format[bfd_type_end]) (bfd *); + + /* Set the format of a file being written. */ + bfd_boolean (*_bfd_set_format[bfd_type_end]) (bfd *); + + /* Write cached information into a file being written, at bfd_close. */ + bfd_boolean (*_bfd_write_contents[bfd_type_end]) (bfd *); + + The general target vector. These vectors are initialized using the +BFD_JUMP_TABLE macros. + + /* Generic entry points. */ + #define BFD_JUMP_TABLE_GENERIC(NAME) \ + NAME##_close_and_cleanup, \ + NAME##_bfd_free_cached_info, \ + NAME##_new_section_hook, \ + NAME##_get_section_contents, \ + NAME##_get_section_contents_in_window + + /* Called when the BFD is being closed to do any necessary cleanup. */ + bfd_boolean (*_close_and_cleanup) (bfd *); + /* Ask the BFD to free all cached information. */ + bfd_boolean (*_bfd_free_cached_info) (bfd *); + /* Called when a new section is created. */ + bfd_boolean (*_new_section_hook) (bfd *, sec_ptr); + /* Read the contents of a section. */ + bfd_boolean (*_bfd_get_section_contents) + (bfd *, sec_ptr, void *, file_ptr, bfd_size_type); + bfd_boolean (*_bfd_get_section_contents_in_window) + (bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type); + + /* Entry points to copy private data. */ + #define BFD_JUMP_TABLE_COPY(NAME) \ + NAME##_bfd_copy_private_bfd_data, \ + NAME##_bfd_merge_private_bfd_data, \ + _bfd_generic_init_private_section_data, \ + NAME##_bfd_copy_private_section_data, \ + NAME##_bfd_copy_private_symbol_data, \ + NAME##_bfd_copy_private_header_data, \ + NAME##_bfd_set_private_flags, \ + NAME##_bfd_print_private_bfd_data + + /* Called to copy BFD general private data from one object file + to another. */ + bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *); + /* Called to merge BFD general private data from one object file + to a common output file when linking. */ + bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *); + /* Called to initialize BFD private section data from one object file + to another. */ + #define bfd_init_private_section_data(ibfd, isec, obfd, osec, link_info) \ + BFD_SEND (obfd, _bfd_init_private_section_data, (ibfd, isec, obfd, osec, link_info)) + bfd_boolean (*_bfd_init_private_section_data) + (bfd *, sec_ptr, bfd *, sec_ptr, struct bfd_link_info *); + /* Called to copy BFD private section data from one object file + to another. */ + bfd_boolean (*_bfd_copy_private_section_data) + (bfd *, sec_ptr, bfd *, sec_ptr); + /* Called to copy BFD private symbol data from one symbol + to another. */ + bfd_boolean (*_bfd_copy_private_symbol_data) + (bfd *, asymbol *, bfd *, asymbol *); + /* Called to copy BFD private header data from one object file + to another. */ + bfd_boolean (*_bfd_copy_private_header_data) + (bfd *, bfd *); + /* Called to set private backend flags. */ + bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword); + + /* Called to print private BFD data. */ + bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *); + + /* Core file entry points. */ + #define BFD_JUMP_TABLE_CORE(NAME) \ + NAME##_core_file_failing_command, \ + NAME##_core_file_failing_signal, \ + NAME##_core_file_matches_executable_p, \ + NAME##_core_file_pid + + char * (*_core_file_failing_command) (bfd *); + int (*_core_file_failing_signal) (bfd *); + bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *); + int (*_core_file_pid) (bfd *); + + /* Archive entry points. */ + #define BFD_JUMP_TABLE_ARCHIVE(NAME) \ + NAME##_slurp_armap, \ + NAME##_slurp_extended_name_table, \ + NAME##_construct_extended_name_table, \ + NAME##_truncate_arname, \ + NAME##_write_armap, \ + NAME##_read_ar_hdr, \ + NAME##_write_ar_hdr, \ + NAME##_openr_next_archived_file, \ + NAME##_get_elt_at_index, \ + NAME##_generic_stat_arch_elt, \ + NAME##_update_armap_timestamp + + bfd_boolean (*_bfd_slurp_armap) (bfd *); + bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *); + bfd_boolean (*_bfd_construct_extended_name_table) + (bfd *, char **, bfd_size_type *, const char **); + void (*_bfd_truncate_arname) (bfd *, const char *, char *); + bfd_boolean (*write_armap) + (bfd *, unsigned int, struct orl *, unsigned int, int); + void * (*_bfd_read_ar_hdr_fn) (bfd *); + bfd_boolean (*_bfd_write_ar_hdr_fn) (bfd *, bfd *); + bfd * (*openr_next_archived_file) (bfd *, bfd *); + #define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i)) + bfd * (*_bfd_get_elt_at_index) (bfd *, symindex); + int (*_bfd_stat_arch_elt) (bfd *, struct stat *); + bfd_boolean (*_bfd_update_armap_timestamp) (bfd *); + + /* Entry points used for symbols. */ + #define BFD_JUMP_TABLE_SYMBOLS(NAME) \ + NAME##_get_symtab_upper_bound, \ + NAME##_canonicalize_symtab, \ + NAME##_make_empty_symbol, \ + NAME##_print_symbol, \ + NAME##_get_symbol_info, \ + NAME##_bfd_is_local_label_name, \ + NAME##_bfd_is_target_special_symbol, \ + NAME##_get_lineno, \ + NAME##_find_nearest_line, \ + _bfd_generic_find_nearest_line_discriminator, \ + _bfd_generic_find_line, \ + NAME##_find_inliner_info, \ + NAME##_bfd_make_debug_symbol, \ + NAME##_read_minisymbols, \ + NAME##_minisymbol_to_symbol + + long (*_bfd_get_symtab_upper_bound) (bfd *); + long (*_bfd_canonicalize_symtab) + (bfd *, struct bfd_symbol **); + struct bfd_symbol * + (*_bfd_make_empty_symbol) (bfd *); + void (*_bfd_print_symbol) + (bfd *, void *, struct bfd_symbol *, bfd_print_symbol_type); + #define bfd_print_symbol(b,p,s,e) BFD_SEND (b, _bfd_print_symbol, (b,p,s,e)) + void (*_bfd_get_symbol_info) + (bfd *, struct bfd_symbol *, symbol_info *); + #define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e)) + bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *); + bfd_boolean (*_bfd_is_target_special_symbol) (bfd *, asymbol *); + alent * (*_get_lineno) (bfd *, struct bfd_symbol *); + bfd_boolean (*_bfd_find_nearest_line) + (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma, + const char **, const char **, unsigned int *); + bfd_boolean (*_bfd_find_nearest_line_discriminator) + (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma, + const char **, const char **, unsigned int *, unsigned int *); + bfd_boolean (*_bfd_find_line) + (bfd *, struct bfd_symbol **, struct bfd_symbol *, + const char **, unsigned int *); + bfd_boolean (*_bfd_find_inliner_info) + (bfd *, const char **, const char **, unsigned int *); + /* Back-door to allow format-aware applications to create debug symbols + while using BFD for everything else. Currently used by the assembler + when creating COFF files. */ + asymbol * (*_bfd_make_debug_symbol) + (bfd *, void *, unsigned long size); + #define bfd_read_minisymbols(b, d, m, s) \ + BFD_SEND (b, _read_minisymbols, (b, d, m, s)) + long (*_read_minisymbols) + (bfd *, bfd_boolean, void **, unsigned int *); + #define bfd_minisymbol_to_symbol(b, d, m, f) \ + BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f)) + asymbol * (*_minisymbol_to_symbol) + (bfd *, bfd_boolean, const void *, asymbol *); + + /* Routines for relocs. */ + #define BFD_JUMP_TABLE_RELOCS(NAME) \ + NAME##_get_reloc_upper_bound, \ + NAME##_canonicalize_reloc, \ + NAME##_bfd_reloc_type_lookup, \ + NAME##_bfd_reloc_name_lookup + + long (*_get_reloc_upper_bound) (bfd *, sec_ptr); + long (*_bfd_canonicalize_reloc) + (bfd *, sec_ptr, arelent **, struct bfd_symbol **); + /* See documentation on reloc types. */ + reloc_howto_type * + (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type); + reloc_howto_type * + (*reloc_name_lookup) (bfd *, const char *); + + + /* Routines used when writing an object file. */ + #define BFD_JUMP_TABLE_WRITE(NAME) \ + NAME##_set_arch_mach, \ + NAME##_set_section_contents + + bfd_boolean (*_bfd_set_arch_mach) + (bfd *, enum bfd_architecture, unsigned long); + bfd_boolean (*_bfd_set_section_contents) + (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type); + + /* Routines used by the linker. */ + #define BFD_JUMP_TABLE_LINK(NAME) \ + NAME##_sizeof_headers, \ + NAME##_bfd_get_relocated_section_contents, \ + NAME##_bfd_relax_section, \ + NAME##_bfd_link_hash_table_create, \ + NAME##_bfd_link_hash_table_free, \ + NAME##_bfd_link_add_symbols, \ + NAME##_bfd_link_just_syms, \ + NAME##_bfd_copy_link_hash_symbol_type, \ + NAME##_bfd_final_link, \ + NAME##_bfd_link_split_section, \ + NAME##_bfd_gc_sections, \ + NAME##_bfd_lookup_section_flags, \ + NAME##_bfd_merge_sections, \ + NAME##_bfd_is_group_section, \ + NAME##_bfd_discard_group, \ + NAME##_section_already_linked, \ + NAME##_bfd_define_common_symbol + + int (*_bfd_sizeof_headers) (bfd *, struct bfd_link_info *); + bfd_byte * (*_bfd_get_relocated_section_contents) + (bfd *, struct bfd_link_info *, struct bfd_link_order *, + bfd_byte *, bfd_boolean, struct bfd_symbol **); + + bfd_boolean (*_bfd_relax_section) + (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *); + + /* Create a hash table for the linker. Different backends store + different information in this table. */ + struct bfd_link_hash_table * + (*_bfd_link_hash_table_create) (bfd *); + + /* Release the memory associated with the linker hash table. */ + void (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *); + + /* Add symbols from this object file into the hash table. */ + bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *); + + /* Indicate that we are only retrieving symbol values from this section. */ + void (*_bfd_link_just_syms) (asection *, struct bfd_link_info *); + + /* Copy the symbol type of a linker hash table entry. */ + #define bfd_copy_link_hash_symbol_type(b, t, f) \ + BFD_SEND (b, _bfd_copy_link_hash_symbol_type, (b, t, f)) + void (*_bfd_copy_link_hash_symbol_type) + (bfd *, struct bfd_link_hash_entry *, struct bfd_link_hash_entry *); + + /* Do a link based on the link_order structures attached to each + section of the BFD. */ + bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *); + + /* Should this section be split up into smaller pieces during linking. */ + bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *); + + /* Remove sections that are not referenced from the output. */ + bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *); + + /* Sets the bitmask of allowed and disallowed section flags. */ + bfd_boolean (*_bfd_lookup_section_flags) (struct bfd_link_info *, + struct flag_info *, + asection *); + + /* Attempt to merge SEC_MERGE sections. */ + bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *); + + /* Is this section a member of a group? */ + bfd_boolean (*_bfd_is_group_section) (bfd *, const struct bfd_section *); + + /* Discard members of a group. */ + bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *); + + /* Check if SEC has been already linked during a reloceatable or + final link. */ + bfd_boolean (*_section_already_linked) (bfd *, asection *, + struct bfd_link_info *); + + /* Define a common symbol. */ + bfd_boolean (*_bfd_define_common_symbol) (bfd *, struct bfd_link_info *, + struct bfd_link_hash_entry *); + + /* Routines to handle dynamic symbols and relocs. */ + #define BFD_JUMP_TABLE_DYNAMIC(NAME) \ + NAME##_get_dynamic_symtab_upper_bound, \ + NAME##_canonicalize_dynamic_symtab, \ + NAME##_get_synthetic_symtab, \ + NAME##_get_dynamic_reloc_upper_bound, \ + NAME##_canonicalize_dynamic_reloc + + /* Get the amount of memory required to hold the dynamic symbols. */ + long (*_bfd_get_dynamic_symtab_upper_bound) (bfd *); + /* Read in the dynamic symbols. */ + long (*_bfd_canonicalize_dynamic_symtab) + (bfd *, struct bfd_symbol **); + /* Create synthetized symbols. */ + long (*_bfd_get_synthetic_symtab) + (bfd *, long, struct bfd_symbol **, long, struct bfd_symbol **, + struct bfd_symbol **); + /* Get the amount of memory required to hold the dynamic relocs. */ + long (*_bfd_get_dynamic_reloc_upper_bound) (bfd *); + /* Read in the dynamic relocs. */ + long (*_bfd_canonicalize_dynamic_reloc) + (bfd *, arelent **, struct bfd_symbol **); + + A pointer to an alternative bfd_target in case the current one is not +satisfactory. This can happen when the target cpu supports both big and +little endian code, and target chosen by the linker has the wrong +endianness. The function open_output() in ld/ldlang.c uses this field +to find an alternative output format that is suitable. + /* Opposite endian version of this target. */ + const struct bfd_target * alternative_target; + + /* Data for use by back-end routines, which isn't + generic enough to belong in this structure. */ + const void *backend_data; + + } bfd_target; + +2.12.1.1 'bfd_set_default_target' +................................. + +*Synopsis* + bfd_boolean bfd_set_default_target (const char *name); + *Description* +Set the default target vector to use when recognizing a BFD. This takes +the name of the target, which may be a BFD target name or a +configuration triplet. + +2.12.1.2 'bfd_find_target' +.......................... + +*Synopsis* + const bfd_target *bfd_find_target (const char *target_name, bfd *abfd); + *Description* +Return a pointer to the transfer vector for the object target named +TARGET_NAME. If TARGET_NAME is 'NULL', choose the one in the +environment variable 'GNUTARGET'; if that is null or not defined, then +choose the first entry in the target list. Passing in the string +"default" or setting the environment variable to "default" will cause +the first entry in the target list to be returned, and +"target_defaulted" will be set in the BFD if ABFD isn't 'NULL'. This +causes 'bfd_check_format' to loop over all the targets to find the one +that matches the file being read. + +2.12.1.3 'bfd_get_target_info' +.............................. + +*Synopsis* + const bfd_target *bfd_get_target_info (const char *target_name, + bfd *abfd, + bfd_boolean *is_bigendian, + int *underscoring, + const char **def_target_arch); + *Description* +Return a pointer to the transfer vector for the object target named +TARGET_NAME. If TARGET_NAME is 'NULL', choose the one in the +environment variable 'GNUTARGET'; if that is null or not defined, then +choose the first entry in the target list. Passing in the string +"default" or setting the environment variable to "default" will cause +the first entry in the target list to be returned, and +"target_defaulted" will be set in the BFD if ABFD isn't 'NULL'. This +causes 'bfd_check_format' to loop over all the targets to find the one +that matches the file being read. If IS_BIGENDIAN is not 'NULL', then +set this value to target's endian mode. True for big-endian, FALSE for +little-endian or for invalid target. If UNDERSCORING is not 'NULL', +then set this value to target's underscoring mode. Zero for +none-underscoring, -1 for invalid target, else the value of target +vector's symbol underscoring. If DEF_TARGET_ARCH is not 'NULL', then +set it to the architecture string specified by the target_name. + +2.12.1.4 'bfd_target_list' +.......................... + +*Synopsis* + const char ** bfd_target_list (void); + *Description* +Return a freshly malloced NULL-terminated vector of the names of all the +valid BFD targets. Do not modify the names. + +2.12.1.5 'bfd_seach_for_target' +............................... + +*Synopsis* + const bfd_target *bfd_search_for_target + (int (*search_func) (const bfd_target *, void *), + void *); + *Description* +Return a pointer to the first transfer vector in the list of transfer +vectors maintained by BFD that produces a non-zero result when passed to +the function SEARCH_FUNC. The parameter DATA is passed, unexamined, to +the search function. + + +File: bfd.info, Node: Architectures, Next: Opening and Closing, Prev: Targets, Up: BFD front end + +2.13 Architectures +================== + +BFD keeps one atom in a BFD describing the architecture of the data +attached to the BFD: a pointer to a 'bfd_arch_info_type'. + + Pointers to structures can be requested independently of a BFD so +that an architecture's information can be interrogated without access to +an open BFD. + + The architecture information is provided by each architecture +package. The set of default architectures is selected by the macro +'SELECT_ARCHITECTURES'. This is normally set up in the +'config/TARGET.mt' file of your choice. If the name is not defined, +then all the architectures supported are included. + + When BFD starts up, all the architectures are called with an +initialize method. It is up to the architecture back end to insert as +many items into the list of architectures as it wants to; generally this +would be one for each machine and one for the default case (an item with +a machine field of 0). + + BFD's idea of an architecture is implemented in 'archures.c'. + +2.13.1 bfd_architecture +----------------------- + +*Description* +This enum gives the object file's CPU architecture, in a global +sense--i.e., what processor family does it belong to? Another field +indicates which processor within the family is in use. The machine +gives a number which distinguishes different versions of the +architecture, containing, for example, 2 and 3 for Intel i960 KA and +i960 KB, and 68020 and 68030 for Motorola 68020 and 68030. + enum bfd_architecture + { + bfd_arch_unknown, /* File arch not known. */ + bfd_arch_obscure, /* Arch known, not one of these. */ + bfd_arch_m68k, /* Motorola 68xxx */ + #define bfd_mach_m68000 1 + #define bfd_mach_m68008 2 + #define bfd_mach_m68010 3 + #define bfd_mach_m68020 4 + #define bfd_mach_m68030 5 + #define bfd_mach_m68040 6 + #define bfd_mach_m68060 7 + #define bfd_mach_cpu32 8 + #define bfd_mach_fido 9 + #define bfd_mach_mcf_isa_a_nodiv 10 + #define bfd_mach_mcf_isa_a 11 + #define bfd_mach_mcf_isa_a_mac 12 + #define bfd_mach_mcf_isa_a_emac 13 + #define bfd_mach_mcf_isa_aplus 14 + #define bfd_mach_mcf_isa_aplus_mac 15 + #define bfd_mach_mcf_isa_aplus_emac 16 + #define bfd_mach_mcf_isa_b_nousp 17 + #define bfd_mach_mcf_isa_b_nousp_mac 18 + #define bfd_mach_mcf_isa_b_nousp_emac 19 + #define bfd_mach_mcf_isa_b 20 + #define bfd_mach_mcf_isa_b_mac 21 + #define bfd_mach_mcf_isa_b_emac 22 + #define bfd_mach_mcf_isa_b_float 23 + #define bfd_mach_mcf_isa_b_float_mac 24 + #define bfd_mach_mcf_isa_b_float_emac 25 + #define bfd_mach_mcf_isa_c 26 + #define bfd_mach_mcf_isa_c_mac 27 + #define bfd_mach_mcf_isa_c_emac 28 + #define bfd_mach_mcf_isa_c_nodiv 29 + #define bfd_mach_mcf_isa_c_nodiv_mac 30 + #define bfd_mach_mcf_isa_c_nodiv_emac 31 + bfd_arch_vax, /* DEC Vax */ + bfd_arch_i960, /* Intel 960 */ + /* The order of the following is important. + lower number indicates a machine type that + only accepts a subset of the instructions + available to machines with higher numbers. + The exception is the "ca", which is + incompatible with all other machines except + "core". */ + + #define bfd_mach_i960_core 1 + #define bfd_mach_i960_ka_sa 2 + #define bfd_mach_i960_kb_sb 3 + #define bfd_mach_i960_mc 4 + #define bfd_mach_i960_xa 5 + #define bfd_mach_i960_ca 6 + #define bfd_mach_i960_jx 7 + #define bfd_mach_i960_hx 8 + + bfd_arch_or32, /* OpenRISC 32 */ + + bfd_arch_sparc, /* SPARC */ + #define bfd_mach_sparc 1 + /* The difference between v8plus and v9 is that v9 is a true 64 bit env. */ + #define bfd_mach_sparc_sparclet 2 + #define bfd_mach_sparc_sparclite 3 + #define bfd_mach_sparc_v8plus 4 + #define bfd_mach_sparc_v8plusa 5 /* with ultrasparc add'ns. */ + #define bfd_mach_sparc_sparclite_le 6 + #define bfd_mach_sparc_v9 7 + #define bfd_mach_sparc_v9a 8 /* with ultrasparc add'ns. */ + #define bfd_mach_sparc_v8plusb 9 /* with cheetah add'ns. */ + #define bfd_mach_sparc_v9b 10 /* with cheetah add'ns. */ + /* Nonzero if MACH has the v9 instruction set. */ + #define bfd_mach_sparc_v9_p(mach) \ + ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9b \ + && (mach) != bfd_mach_sparc_sparclite_le) + /* Nonzero if MACH is a 64 bit sparc architecture. */ + #define bfd_mach_sparc_64bit_p(mach) \ + ((mach) >= bfd_mach_sparc_v9 && (mach) != bfd_mach_sparc_v8plusb) + bfd_arch_spu, /* PowerPC SPU */ + #define bfd_mach_spu 256 + bfd_arch_mips, /* MIPS Rxxxx */ + #define bfd_mach_mips3000 3000 + #define bfd_mach_mips3900 3900 + #define bfd_mach_mips4000 4000 + #define bfd_mach_mips4010 4010 + #define bfd_mach_mips4100 4100 + #define bfd_mach_mips4111 4111 + #define bfd_mach_mips4120 4120 + #define bfd_mach_mips4300 4300 + #define bfd_mach_mips4400 4400 + #define bfd_mach_mips4600 4600 + #define bfd_mach_mips4650 4650 + #define bfd_mach_mips5000 5000 + #define bfd_mach_mips5400 5400 + #define bfd_mach_mips5500 5500 + #define bfd_mach_mips5900 5900 + #define bfd_mach_mips6000 6000 + #define bfd_mach_mips7000 7000 + #define bfd_mach_mips8000 8000 + #define bfd_mach_mips9000 9000 + #define bfd_mach_mips10000 10000 + #define bfd_mach_mips12000 12000 + #define bfd_mach_mips14000 14000 + #define bfd_mach_mips16000 16000 + #define bfd_mach_mips16 16 + #define bfd_mach_mips5 5 + #define bfd_mach_mips_loongson_2e 3001 + #define bfd_mach_mips_loongson_2f 3002 + #define bfd_mach_mips_loongson_3a 3003 + #define bfd_mach_mips_sb1 12310201 /* octal 'SB', 01 */ + #define bfd_mach_mips_octeon 6501 + #define bfd_mach_mips_octeonp 6601 + #define bfd_mach_mips_octeon2 6502 + #define bfd_mach_mips_xlr 887682 /* decimal 'XLR' */ + #define bfd_mach_mipsisa32 32 + #define bfd_mach_mipsisa32r2 33 + #define bfd_mach_mipsisa64 64 + #define bfd_mach_mipsisa64r2 65 + #define bfd_mach_mips_micromips 96 + bfd_arch_i386, /* Intel 386 */ + #define bfd_mach_i386_intel_syntax (1 << 0) + #define bfd_mach_i386_i8086 (1 << 1) + #define bfd_mach_i386_i386 (1 << 2) + #define bfd_mach_x86_64 (1 << 3) + #define bfd_mach_x64_32 (1 << 4) + #define bfd_mach_i386_i386_intel_syntax (bfd_mach_i386_i386 | bfd_mach_i386_intel_syntax) + #define bfd_mach_x86_64_intel_syntax (bfd_mach_x86_64 | bfd_mach_i386_intel_syntax) + #define bfd_mach_x64_32_intel_syntax (bfd_mach_x64_32 | bfd_mach_i386_intel_syntax) + bfd_arch_l1om, /* Intel L1OM */ + #define bfd_mach_l1om (1 << 5) + #define bfd_mach_l1om_intel_syntax (bfd_mach_l1om | bfd_mach_i386_intel_syntax) + bfd_arch_k1om, /* Intel K1OM */ + #define bfd_mach_k1om (1 << 6) + #define bfd_mach_k1om_intel_syntax (bfd_mach_k1om | bfd_mach_i386_intel_syntax) + #define bfd_mach_i386_nacl (1 << 7) + #define bfd_mach_i386_i386_nacl (bfd_mach_i386_i386 | bfd_mach_i386_nacl) + #define bfd_mach_x86_64_nacl (bfd_mach_x86_64 | bfd_mach_i386_nacl) + #define bfd_mach_x64_32_nacl (bfd_mach_x64_32 | bfd_mach_i386_nacl) + bfd_arch_we32k, /* AT&T WE32xxx */ + bfd_arch_tahoe, /* CCI/Harris Tahoe */ + bfd_arch_i860, /* Intel 860 */ + bfd_arch_i370, /* IBM 360/370 Mainframes */ + bfd_arch_romp, /* IBM ROMP PC/RT */ + bfd_arch_convex, /* Convex */ + bfd_arch_m88k, /* Motorola 88xxx */ + bfd_arch_m98k, /* Motorola 98xxx */ + bfd_arch_pyramid, /* Pyramid Technology */ + bfd_arch_h8300, /* Renesas H8/300 (formerly Hitachi H8/300) */ + #define bfd_mach_h8300 1 + #define bfd_mach_h8300h 2 + #define bfd_mach_h8300s 3 + #define bfd_mach_h8300hn 4 + #define bfd_mach_h8300sn 5 + #define bfd_mach_h8300sx 6 + #define bfd_mach_h8300sxn 7 + bfd_arch_pdp11, /* DEC PDP-11 */ + bfd_arch_plugin, + bfd_arch_powerpc, /* PowerPC */ + #define bfd_mach_ppc 32 + #define bfd_mach_ppc64 64 + #define bfd_mach_ppc_403 403 + #define bfd_mach_ppc_403gc 4030 + #define bfd_mach_ppc_405 405 + #define bfd_mach_ppc_505 505 + #define bfd_mach_ppc_601 601 + #define bfd_mach_ppc_602 602 + #define bfd_mach_ppc_603 603 + #define bfd_mach_ppc_ec603e 6031 + #define bfd_mach_ppc_604 604 + #define bfd_mach_ppc_620 620 + #define bfd_mach_ppc_630 630 + #define bfd_mach_ppc_750 750 + #define bfd_mach_ppc_860 860 + #define bfd_mach_ppc_a35 35 + #define bfd_mach_ppc_rs64ii 642 + #define bfd_mach_ppc_rs64iii 643 + #define bfd_mach_ppc_7400 7400 + #define bfd_mach_ppc_e500 500 + #define bfd_mach_ppc_e500mc 5001 + #define bfd_mach_ppc_e500mc64 5005 + #define bfd_mach_ppc_e5500 5006 + #define bfd_mach_ppc_e6500 5007 + #define bfd_mach_ppc_titan 83 + #define bfd_mach_ppc_vle 84 + bfd_arch_rs6000, /* IBM RS/6000 */ + #define bfd_mach_rs6k 6000 + #define bfd_mach_rs6k_rs1 6001 + #define bfd_mach_rs6k_rsc 6003 + #define bfd_mach_rs6k_rs2 6002 + bfd_arch_hppa, /* HP PA RISC */ + #define bfd_mach_hppa10 10 + #define bfd_mach_hppa11 11 + #define bfd_mach_hppa20 20 + #define bfd_mach_hppa20w 25 + bfd_arch_d10v, /* Mitsubishi D10V */ + #define bfd_mach_d10v 1 + #define bfd_mach_d10v_ts2 2 + #define bfd_mach_d10v_ts3 3 + bfd_arch_d30v, /* Mitsubishi D30V */ + bfd_arch_dlx, /* DLX */ + bfd_arch_m68hc11, /* Motorola 68HC11 */ + bfd_arch_m68hc12, /* Motorola 68HC12 */ + #define bfd_mach_m6812_default 0 + #define bfd_mach_m6812 1 + #define bfd_mach_m6812s 2 + bfd_arch_m9s12x, /* Freescale S12X */ + bfd_arch_m9s12xg, /* Freescale XGATE */ + bfd_arch_z8k, /* Zilog Z8000 */ + #define bfd_mach_z8001 1 + #define bfd_mach_z8002 2 + bfd_arch_h8500, /* Renesas H8/500 (formerly Hitachi H8/500) */ + bfd_arch_sh, /* Renesas / SuperH SH (formerly Hitachi SH) */ + #define bfd_mach_sh 1 + #define bfd_mach_sh2 0x20 + #define bfd_mach_sh_dsp 0x2d + #define bfd_mach_sh2a 0x2a + #define bfd_mach_sh2a_nofpu 0x2b + #define bfd_mach_sh2a_nofpu_or_sh4_nommu_nofpu 0x2a1 + #define bfd_mach_sh2a_nofpu_or_sh3_nommu 0x2a2 + #define bfd_mach_sh2a_or_sh4 0x2a3 + #define bfd_mach_sh2a_or_sh3e 0x2a4 + #define bfd_mach_sh2e 0x2e + #define bfd_mach_sh3 0x30 + #define bfd_mach_sh3_nommu 0x31 + #define bfd_mach_sh3_dsp 0x3d + #define bfd_mach_sh3e 0x3e + #define bfd_mach_sh4 0x40 + #define bfd_mach_sh4_nofpu 0x41 + #define bfd_mach_sh4_nommu_nofpu 0x42 + #define bfd_mach_sh4a 0x4a + #define bfd_mach_sh4a_nofpu 0x4b + #define bfd_mach_sh4al_dsp 0x4d + #define bfd_mach_sh5 0x50 + bfd_arch_alpha, /* Dec Alpha */ + #define bfd_mach_alpha_ev4 0x10 + #define bfd_mach_alpha_ev5 0x20 + #define bfd_mach_alpha_ev6 0x30 + bfd_arch_arm, /* Advanced Risc Machines ARM. */ + #define bfd_mach_arm_unknown 0 + #define bfd_mach_arm_2 1 + #define bfd_mach_arm_2a 2 + #define bfd_mach_arm_3 3 + #define bfd_mach_arm_3M 4 + #define bfd_mach_arm_4 5 + #define bfd_mach_arm_4T 6 + #define bfd_mach_arm_5 7 + #define bfd_mach_arm_5T 8 + #define bfd_mach_arm_5TE 9 + #define bfd_mach_arm_XScale 10 + #define bfd_mach_arm_ep9312 11 + #define bfd_mach_arm_iWMMXt 12 + #define bfd_mach_arm_iWMMXt2 13 + bfd_arch_nds32, /* Andes NDS32 */ + #define bfd_mach_n1 1 + #define bfd_mach_n1h 2 + #define bfd_mach_n1h_v2 3 + #define bfd_mach_n1h_v3 4 + #define bfd_mach_n1h_v3m 5 + bfd_arch_ns32k, /* National Semiconductors ns32000 */ + bfd_arch_w65, /* WDC 65816 */ + bfd_arch_tic30, /* Texas Instruments TMS320C30 */ + bfd_arch_tic4x, /* Texas Instruments TMS320C3X/4X */ + #define bfd_mach_tic3x 30 + #define bfd_mach_tic4x 40 + bfd_arch_tic54x, /* Texas Instruments TMS320C54X */ + bfd_arch_tic6x, /* Texas Instruments TMS320C6X */ + bfd_arch_tic80, /* TI TMS320c80 (MVP) */ + bfd_arch_v850, /* NEC V850 */ + bfd_arch_v850_rh850,/* NEC V850 (using RH850 ABI) */ + #define bfd_mach_v850 1 + #define bfd_mach_v850e 'E' + #define bfd_mach_v850e1 '1' + #define bfd_mach_v850e2 0x4532 + #define bfd_mach_v850e2v3 0x45325633 + #define bfd_mach_v850e3v5 0x45335635 /* ('E'|'3'|'V'|'5') */ + bfd_arch_arc, /* ARC Cores */ + #define bfd_mach_arc_5 5 + #define bfd_mach_arc_6 6 + #define bfd_mach_arc_7 7 + #define bfd_mach_arc_8 8 + bfd_arch_m32c, /* Renesas M16C/M32C. */ + #define bfd_mach_m16c 0x75 + #define bfd_mach_m32c 0x78 + bfd_arch_m32r, /* Renesas M32R (formerly Mitsubishi M32R/D) */ + #define bfd_mach_m32r 1 /* For backwards compatibility. */ + #define bfd_mach_m32rx 'x' + #define bfd_mach_m32r2 '2' + bfd_arch_mn10200, /* Matsushita MN10200 */ + bfd_arch_mn10300, /* Matsushita MN10300 */ + #define bfd_mach_mn10300 300 + #define bfd_mach_am33 330 + #define bfd_mach_am33_2 332 + bfd_arch_fr30, + #define bfd_mach_fr30 0x46523330 + bfd_arch_frv, + #define bfd_mach_frv 1 + #define bfd_mach_frvsimple 2 + #define bfd_mach_fr300 300 + #define bfd_mach_fr400 400 + #define bfd_mach_fr450 450 + #define bfd_mach_frvtomcat 499 /* fr500 prototype */ + #define bfd_mach_fr500 500 + #define bfd_mach_fr550 550 + bfd_arch_moxie, /* The moxie processor */ + #define bfd_mach_moxie 1 + bfd_arch_mcore, + bfd_arch_mep, + #define bfd_mach_mep 1 + #define bfd_mach_mep_h1 0x6831 + #define bfd_mach_mep_c5 0x6335 + bfd_arch_metag, + #define bfd_mach_metag 1 + bfd_arch_ia64, /* HP/Intel ia64 */ + #define bfd_mach_ia64_elf64 64 + #define bfd_mach_ia64_elf32 32 + bfd_arch_ip2k, /* Ubicom IP2K microcontrollers. */ + #define bfd_mach_ip2022 1 + #define bfd_mach_ip2022ext 2 + bfd_arch_iq2000, /* Vitesse IQ2000. */ + #define bfd_mach_iq2000 1 + #define bfd_mach_iq10 2 + bfd_arch_epiphany, /* Adapteva EPIPHANY */ + #define bfd_mach_epiphany16 1 + #define bfd_mach_epiphany32 2 + bfd_arch_mt, + #define bfd_mach_ms1 1 + #define bfd_mach_mrisc2 2 + #define bfd_mach_ms2 3 + bfd_arch_pj, + bfd_arch_avr, /* Atmel AVR microcontrollers. */ + #define bfd_mach_avr1 1 + #define bfd_mach_avr2 2 + #define bfd_mach_avr25 25 + #define bfd_mach_avr3 3 + #define bfd_mach_avr31 31 + #define bfd_mach_avr35 35 + #define bfd_mach_avr4 4 + #define bfd_mach_avr5 5 + #define bfd_mach_avr51 51 + #define bfd_mach_avr6 6 + #define bfd_mach_avrxmega1 101 + #define bfd_mach_avrxmega2 102 + #define bfd_mach_avrxmega3 103 + #define bfd_mach_avrxmega4 104 + #define bfd_mach_avrxmega5 105 + #define bfd_mach_avrxmega6 106 + #define bfd_mach_avrxmega7 107 + bfd_arch_bfin, /* ADI Blackfin */ + #define bfd_mach_bfin 1 + bfd_arch_cr16, /* National Semiconductor CompactRISC (ie CR16). */ + #define bfd_mach_cr16 1 + bfd_arch_cr16c, /* National Semiconductor CompactRISC. */ + #define bfd_mach_cr16c 1 + bfd_arch_crx, /* National Semiconductor CRX. */ + #define bfd_mach_crx 1 + bfd_arch_cris, /* Axis CRIS */ + #define bfd_mach_cris_v0_v10 255 + #define bfd_mach_cris_v32 32 + #define bfd_mach_cris_v10_v32 1032 + bfd_arch_rl78, + #define bfd_mach_rl78 0x75 + bfd_arch_rx, /* Renesas RX. */ + #define bfd_mach_rx 0x75 + bfd_arch_s390, /* IBM s390 */ + #define bfd_mach_s390_31 31 + #define bfd_mach_s390_64 64 + bfd_arch_score, /* Sunplus score */ + #define bfd_mach_score3 3 + #define bfd_mach_score7 7 + bfd_arch_openrisc, /* OpenRISC */ + bfd_arch_mmix, /* Donald Knuth's educational processor. */ + bfd_arch_xstormy16, + #define bfd_mach_xstormy16 1 + bfd_arch_msp430, /* Texas Instruments MSP430 architecture. */ + #define bfd_mach_msp11 11 + #define bfd_mach_msp110 110 + #define bfd_mach_msp12 12 + #define bfd_mach_msp13 13 + #define bfd_mach_msp14 14 + #define bfd_mach_msp15 15 + #define bfd_mach_msp16 16 + #define bfd_mach_msp20 20 + #define bfd_mach_msp21 21 + #define bfd_mach_msp22 22 + #define bfd_mach_msp23 23 + #define bfd_mach_msp24 24 + #define bfd_mach_msp26 26 + #define bfd_mach_msp31 31 + #define bfd_mach_msp32 32 + #define bfd_mach_msp33 33 + #define bfd_mach_msp41 41 + #define bfd_mach_msp42 42 + #define bfd_mach_msp43 43 + #define bfd_mach_msp44 44 + #define bfd_mach_msp430x 45 + #define bfd_mach_msp46 46 + #define bfd_mach_msp47 47 + #define bfd_mach_msp54 54 + bfd_arch_xc16x, /* Infineon's XC16X Series. */ + #define bfd_mach_xc16x 1 + #define bfd_mach_xc16xl 2 + #define bfd_mach_xc16xs 3 + bfd_arch_xgate, /* Freescale XGATE */ + #define bfd_mach_xgate 1 + bfd_arch_xtensa, /* Tensilica's Xtensa cores. */ + #define bfd_mach_xtensa 1 + bfd_arch_z80, + #define bfd_mach_z80strict 1 /* No undocumented opcodes. */ + #define bfd_mach_z80 3 /* With ixl, ixh, iyl, and iyh. */ + #define bfd_mach_z80full 7 /* All undocumented instructions. */ + #define bfd_mach_r800 11 /* R800: successor with multiplication. */ + bfd_arch_lm32, /* Lattice Mico32 */ + #define bfd_mach_lm32 1 + bfd_arch_microblaze,/* Xilinx MicroBlaze. */ + bfd_arch_tilepro, /* Tilera TILEPro */ + bfd_arch_tilegx, /* Tilera TILE-Gx */ + #define bfd_mach_tilepro 1 + #define bfd_mach_tilegx 1 + #define bfd_mach_tilegx32 2 + bfd_arch_aarch64, /* AArch64 */ + #define bfd_mach_aarch64 0 + #define bfd_mach_aarch64_ilp32 32 + bfd_arch_nios2, + #define bfd_mach_nios2 0 + bfd_arch_last + }; + +2.13.2 bfd_arch_info +-------------------- + +*Description* +This structure contains information on architectures for use within BFD. + + typedef struct bfd_arch_info + { + int bits_per_word; + int bits_per_address; + int bits_per_byte; + enum bfd_architecture arch; + unsigned long mach; + const char *arch_name; + const char *printable_name; + unsigned int section_align_power; + /* TRUE if this is the default machine for the architecture. + The default arch should be the first entry for an arch so that + all the entries for that arch can be accessed via next. */ + bfd_boolean the_default; + const struct bfd_arch_info * (*compatible) + (const struct bfd_arch_info *a, const struct bfd_arch_info *b); + + bfd_boolean (*scan) (const struct bfd_arch_info *, const char *); + + /* Allocate via bfd_malloc and return a fill buffer of size COUNT. If + IS_BIGENDIAN is TRUE, the order of bytes is big endian. If CODE is + TRUE, the buffer contains code. */ + void *(*fill) (bfd_size_type count, bfd_boolean is_bigendian, + bfd_boolean code); + + const struct bfd_arch_info *next; + } + bfd_arch_info_type; + +2.13.2.1 'bfd_printable_name' +............................. + +*Synopsis* + const char *bfd_printable_name (bfd *abfd); + *Description* +Return a printable string representing the architecture and machine from +the pointer to the architecture info structure. + +2.13.2.2 'bfd_scan_arch' +........................ + +*Synopsis* + const bfd_arch_info_type *bfd_scan_arch (const char *string); + *Description* +Figure out if BFD supports any cpu which could be described with the +name STRING. Return a pointer to an 'arch_info' structure if a machine +is found, otherwise NULL. + +2.13.2.3 'bfd_arch_list' +........................ + +*Synopsis* + const char **bfd_arch_list (void); + *Description* +Return a freshly malloced NULL-terminated vector of the names of all the +valid BFD architectures. Do not modify the names. + +2.13.2.4 'bfd_arch_get_compatible' +.................................. + +*Synopsis* + const bfd_arch_info_type *bfd_arch_get_compatible + (const bfd *abfd, const bfd *bbfd, bfd_boolean accept_unknowns); + *Description* +Determine whether two BFDs' architectures and machine types are +compatible. Calculates the lowest common denominator between the two +architectures and machine types implied by the BFDs and returns a +pointer to an 'arch_info' structure describing the compatible machine. + +2.13.2.5 'bfd_default_arch_struct' +.................................. + +*Description* +The 'bfd_default_arch_struct' is an item of 'bfd_arch_info_type' which +has been initialized to a fairly generic state. A BFD starts life by +pointing to this structure, until the correct back end has determined +the real architecture of the file. + extern const bfd_arch_info_type bfd_default_arch_struct; + +2.13.2.6 'bfd_set_arch_info' +............................ + +*Synopsis* + void bfd_set_arch_info (bfd *abfd, const bfd_arch_info_type *arg); + *Description* +Set the architecture info of ABFD to ARG. + +2.13.2.7 'bfd_default_set_arch_mach' +.................................... + +*Synopsis* + bfd_boolean bfd_default_set_arch_mach + (bfd *abfd, enum bfd_architecture arch, unsigned long mach); + *Description* +Set the architecture and machine type in BFD ABFD to ARCH and MACH. +Find the correct pointer to a structure and insert it into the +'arch_info' pointer. + +2.13.2.8 'bfd_get_arch' +....................... + +*Synopsis* + enum bfd_architecture bfd_get_arch (bfd *abfd); + *Description* +Return the enumerated type which describes the BFD ABFD's architecture. + +2.13.2.9 'bfd_get_mach' +....................... + +*Synopsis* + unsigned long bfd_get_mach (bfd *abfd); + *Description* +Return the long type which describes the BFD ABFD's machine. + +2.13.2.10 'bfd_arch_bits_per_byte' +.................................. + +*Synopsis* + unsigned int bfd_arch_bits_per_byte (bfd *abfd); + *Description* +Return the number of bits in one of the BFD ABFD's architecture's bytes. + +2.13.2.11 'bfd_arch_bits_per_address' +..................................... + +*Synopsis* + unsigned int bfd_arch_bits_per_address (bfd *abfd); + *Description* +Return the number of bits in one of the BFD ABFD's architecture's +addresses. + +2.13.2.12 'bfd_default_compatible' +.................................. + +*Synopsis* + const bfd_arch_info_type *bfd_default_compatible + (const bfd_arch_info_type *a, const bfd_arch_info_type *b); + *Description* +The default function for testing for compatibility. + +2.13.2.13 'bfd_default_scan' +............................ + +*Synopsis* + bfd_boolean bfd_default_scan + (const struct bfd_arch_info *info, const char *string); + *Description* +The default function for working out whether this is an architecture hit +and a machine hit. + +2.13.2.14 'bfd_get_arch_info' +............................. + +*Synopsis* + const bfd_arch_info_type *bfd_get_arch_info (bfd *abfd); + *Description* +Return the architecture info struct in ABFD. + +2.13.2.15 'bfd_lookup_arch' +........................... + +*Synopsis* + const bfd_arch_info_type *bfd_lookup_arch + (enum bfd_architecture arch, unsigned long machine); + *Description* +Look for the architecture info structure which matches the arguments +ARCH and MACHINE. A machine of 0 matches the machine/architecture +structure which marks itself as the default. + +2.13.2.16 'bfd_printable_arch_mach' +................................... + +*Synopsis* + const char *bfd_printable_arch_mach + (enum bfd_architecture arch, unsigned long machine); + *Description* +Return a printable string representing the architecture and machine +type. + + This routine is depreciated. + +2.13.2.17 'bfd_octets_per_byte' +............................... + +*Synopsis* + unsigned int bfd_octets_per_byte (bfd *abfd); + *Description* +Return the number of octets (8-bit quantities) per target byte (minimum +addressable unit). In most cases, this will be one, but some DSP +targets have 16, 32, or even 48 bits per byte. + +2.13.2.18 'bfd_arch_mach_octets_per_byte' +......................................... + +*Synopsis* + unsigned int bfd_arch_mach_octets_per_byte + (enum bfd_architecture arch, unsigned long machine); + *Description* +See bfd_octets_per_byte. + + This routine is provided for those cases where a bfd * is not +available + +2.13.2.19 'bfd_arch_default_fill' +................................. + +*Synopsis* + void *bfd_arch_default_fill (bfd_size_type count, + bfd_boolean is_bigendian, + bfd_boolean code); + *Description* +Allocate via bfd_malloc and return a fill buffer of size COUNT. If +IS_BIGENDIAN is TRUE, the order of bytes is big endian. If CODE is +TRUE, the buffer contains code. + + +File: bfd.info, Node: Opening and Closing, Next: Internal, Prev: Architectures, Up: BFD front end + + /* Set to N to open the next N BFDs using an alternate id space. */ + extern unsigned int bfd_use_reserved_id; + +2.14 Opening and closing BFDs +============================= + +2.14.1 Functions for opening and closing +---------------------------------------- + +2.14.1.1 'bfd_fopen' +.................... + +*Synopsis* + bfd *bfd_fopen (const char *filename, const char *target, + const char *mode, int fd); + *Description* +Open the file FILENAME with the target TARGET. Return a pointer to the +created BFD. If FD is not -1, then 'fdopen' is used to open the file; +otherwise, 'fopen' is used. MODE is passed directly to 'fopen' or +'fdopen'. + + Calls 'bfd_find_target', so TARGET is interpreted as by that +function. + + The new BFD is marked as cacheable iff FD is -1. + + If 'NULL' is returned then an error has occured. Possible errors are +'bfd_error_no_memory', 'bfd_error_invalid_target' or 'system_call' +error. + + On error, FD is always closed. + + A copy of the FILENAME argument is stored in the newly created BFD. +It can be accessed via the bfd_get_filename() macro. + +2.14.1.2 'bfd_openr' +.................... + +*Synopsis* + bfd *bfd_openr (const char *filename, const char *target); + *Description* +Open the file FILENAME (using 'fopen') with the target TARGET. Return a +pointer to the created BFD. + + Calls 'bfd_find_target', so TARGET is interpreted as by that +function. + + If 'NULL' is returned then an error has occured. Possible errors are +'bfd_error_no_memory', 'bfd_error_invalid_target' or 'system_call' +error. + + A copy of the FILENAME argument is stored in the newly created BFD. +It can be accessed via the bfd_get_filename() macro. + +2.14.1.3 'bfd_fdopenr' +...................... + +*Synopsis* + bfd *bfd_fdopenr (const char *filename, const char *target, int fd); + *Description* +'bfd_fdopenr' is to 'bfd_fopenr' much like 'fdopen' is to 'fopen'. It +opens a BFD on a file already described by the FD supplied. + + When the file is later 'bfd_close'd, the file descriptor will be +closed. If the caller desires that this file descriptor be cached by +BFD (opened as needed, closed as needed to free descriptors for other +opens), with the supplied FD used as an initial file descriptor (but +subject to closure at any time), call bfd_set_cacheable(bfd, 1) on the +returned BFD. The default is to assume no caching; the file descriptor +will remain open until 'bfd_close', and will not be affected by BFD +operations on other files. + + Possible errors are 'bfd_error_no_memory', 'bfd_error_invalid_target' +and 'bfd_error_system_call'. + + On error, FD is closed. + + A copy of the FILENAME argument is stored in the newly created BFD. +It can be accessed via the bfd_get_filename() macro. + +2.14.1.4 'bfd_openstreamr' +.......................... + +*Synopsis* + bfd *bfd_openstreamr (const char * filename, const char * target, void * stream); + *Description* +Open a BFD for read access on an existing stdio stream. When the BFD is +passed to 'bfd_close', the stream will be closed. + + A copy of the FILENAME argument is stored in the newly created BFD. +It can be accessed via the bfd_get_filename() macro. + +2.14.1.5 'bfd_openr_iovec' +.......................... + +*Synopsis* + bfd *bfd_openr_iovec (const char *filename, const char *target, + void *(*open_func) (struct bfd *nbfd, + void *open_closure), + void *open_closure, + file_ptr (*pread_func) (struct bfd *nbfd, + void *stream, + void *buf, + file_ptr nbytes, + file_ptr offset), + int (*close_func) (struct bfd *nbfd, + void *stream), + int (*stat_func) (struct bfd *abfd, + void *stream, + struct stat *sb)); + *Description* +Create and return a BFD backed by a read-only STREAM. The STREAM is +created using OPEN_FUNC, accessed using PREAD_FUNC and destroyed using +CLOSE_FUNC. + + Calls 'bfd_find_target', so TARGET is interpreted as by that +function. + + Calls OPEN_FUNC (which can call 'bfd_zalloc' and 'bfd_get_filename') +to obtain the read-only stream backing the BFD. OPEN_FUNC either +succeeds returning the non-'NULL' STREAM, or fails returning 'NULL' +(setting 'bfd_error'). + + Calls PREAD_FUNC to request NBYTES of data from STREAM starting at +OFFSET (e.g., via a call to 'bfd_read'). PREAD_FUNC either succeeds +returning the number of bytes read (which can be less than NBYTES when +end-of-file), or fails returning -1 (setting 'bfd_error'). + + Calls CLOSE_FUNC when the BFD is later closed using 'bfd_close'. +CLOSE_FUNC either succeeds returning 0, or fails returning -1 (setting +'bfd_error'). + + Calls STAT_FUNC to fill in a stat structure for bfd_stat, +bfd_get_size, and bfd_get_mtime calls. STAT_FUNC returns 0 on success, +or returns -1 on failure (setting 'bfd_error'). + + If 'bfd_openr_iovec' returns 'NULL' then an error has occurred. +Possible errors are 'bfd_error_no_memory', 'bfd_error_invalid_target' +and 'bfd_error_system_call'. + + A copy of the FILENAME argument is stored in the newly created BFD. +It can be accessed via the bfd_get_filename() macro. + +2.14.1.6 'bfd_openw' +.................... + +*Synopsis* + bfd *bfd_openw (const char *filename, const char *target); + *Description* +Create a BFD, associated with file FILENAME, using the file format +TARGET, and return a pointer to it. + + Possible errors are 'bfd_error_system_call', 'bfd_error_no_memory', +'bfd_error_invalid_target'. + + A copy of the FILENAME argument is stored in the newly created BFD. +It can be accessed via the bfd_get_filename() macro. + +2.14.1.7 'bfd_close' +.................... + +*Synopsis* + bfd_boolean bfd_close (bfd *abfd); + *Description* +Close a BFD. If the BFD was open for writing, then pending operations +are completed and the file written out and closed. If the created file +is executable, then 'chmod' is called to mark it as such. + + All memory attached to the BFD is released. + + The file descriptor associated with the BFD is closed (even if it was +passed in to BFD by 'bfd_fdopenr'). + + *Returns* +'TRUE' is returned if all is ok, otherwise 'FALSE'. + +2.14.1.8 'bfd_close_all_done' +............................. + +*Synopsis* + bfd_boolean bfd_close_all_done (bfd *); + *Description* +Close a BFD. Differs from 'bfd_close' since it does not complete any +pending operations. This routine would be used if the application had +just used BFD for swapping and didn't want to use any of the writing +code. + + If the created file is executable, then 'chmod' is called to mark it +as such. + + All memory attached to the BFD is released. + + *Returns* +'TRUE' is returned if all is ok, otherwise 'FALSE'. + +2.14.1.9 'bfd_create' +..................... + +*Synopsis* + bfd *bfd_create (const char *filename, bfd *templ); + *Description* +Create a new BFD in the manner of 'bfd_openw', but without opening a +file. The new BFD takes the target from the target used by TEMPL. The +format is always set to 'bfd_object'. + + A copy of the FILENAME argument is stored in the newly created BFD. +It can be accessed via the bfd_get_filename() macro. + +2.14.1.10 'bfd_make_writable' +............................. + +*Synopsis* + bfd_boolean bfd_make_writable (bfd *abfd); + *Description* +Takes a BFD as created by 'bfd_create' and converts it into one like as +returned by 'bfd_openw'. It does this by converting the BFD to +BFD_IN_MEMORY. It's assumed that you will call 'bfd_make_readable' on +this bfd later. + + *Returns* +'TRUE' is returned if all is ok, otherwise 'FALSE'. + +2.14.1.11 'bfd_make_readable' +............................. + +*Synopsis* + bfd_boolean bfd_make_readable (bfd *abfd); + *Description* +Takes a BFD as created by 'bfd_create' and 'bfd_make_writable' and +converts it into one like as returned by 'bfd_openr'. It does this by +writing the contents out to the memory buffer, then reversing the +direction. + + *Returns* +'TRUE' is returned if all is ok, otherwise 'FALSE'. + +2.14.1.12 'bfd_alloc' +..................... + +*Synopsis* + void *bfd_alloc (bfd *abfd, bfd_size_type wanted); + *Description* +Allocate a block of WANTED bytes of memory attached to 'abfd' and return +a pointer to it. + +2.14.1.13 'bfd_alloc2' +...................... + +*Synopsis* + void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size); + *Description* +Allocate a block of NMEMB elements of SIZE bytes each of memory attached +to 'abfd' and return a pointer to it. + +2.14.1.14 'bfd_zalloc' +...................... + +*Synopsis* + void *bfd_zalloc (bfd *abfd, bfd_size_type wanted); + *Description* +Allocate a block of WANTED bytes of zeroed memory attached to 'abfd' and +return a pointer to it. + +2.14.1.15 'bfd_zalloc2' +....................... + +*Synopsis* + void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size); + *Description* +Allocate a block of NMEMB elements of SIZE bytes each of zeroed memory +attached to 'abfd' and return a pointer to it. + +2.14.1.16 'bfd_calc_gnu_debuglink_crc32' +........................................ + +*Synopsis* + unsigned long bfd_calc_gnu_debuglink_crc32 + (unsigned long crc, const unsigned char *buf, bfd_size_type len); + *Description* +Computes a CRC value as used in the .gnu_debuglink section. Advances +the previously computed CRC value by computing and adding in the crc32 +for LEN bytes of BUF. + + *Returns* +Return the updated CRC32 value. + +2.14.1.17 'bfd_get_debug_link_info' +................................... + +*Synopsis* + char *bfd_get_debug_link_info (bfd *abfd, unsigned long *crc32_out); + *Description* +Fetch the filename and CRC32 value for any separate debuginfo associated +with ABFD. Return NULL if no such info found, otherwise return filename +and update CRC32_OUT. The returned filename is allocated with 'malloc'; +freeing it is the responsibility of the caller. + +2.14.1.18 'bfd_get_alt_debug_link_info' +....................................... + +*Synopsis* + char *bfd_get_alt_debug_link_info (bfd * abfd, + bfd_size_type *buildid_len, + bfd_byte **buildid_out); + *Description* +Fetch the filename and BuildID value for any alternate debuginfo +associated with ABFD. Return NULL if no such info found, otherwise +return filename and update BUILDID_LEN and BUILDID_OUT. The returned +filename and build_id are allocated with 'malloc'; freeing them is the +responsibility of the caller. + +2.14.1.19 'separate_debug_file_exists' +...................................... + +*Synopsis* + bfd_boolean separate_debug_file_exists + (char *name, unsigned long crc32); + *Description* +Checks to see if NAME is a file and if its contents match CRC32. + +2.14.1.20 'separate_alt_debug_file_exists' +.......................................... + +*Synopsis* + bfd_boolean separate_alt_debug_file_exists + (char *name, unsigned long crc32); + *Description* +Checks to see if NAME is a file and if its BuildID matches BUILDID. + +2.14.1.21 'find_separate_debug_file' +.................................... + +*Synopsis* + char *find_separate_debug_file (bfd *abfd); + *Description* +Searches ABFD for a section called SECTION_NAME which is expected to +contain a reference to a file containing separate debugging information. +The function scans various locations in the filesystem, including the +file tree rooted at DEBUG_FILE_DIRECTORY, and returns the first matching +filename that it finds. If CHECK_CRC is TRUE then the contents of the +file must also match the CRC value contained in SECTION_NAME. Returns +NULL if no valid file could be found. + +2.14.1.22 'bfd_follow_gnu_debuglink' +.................................... + +*Synopsis* + char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir); + *Description* +Takes a BFD and searches it for a .gnu_debuglink section. If this +section is found, it examines the section for the name and checksum of a +'.debug' file containing auxiliary debugging information. It then +searches the filesystem for this .debug file in some standard locations, +including the directory tree rooted at DIR, and if found returns the +full filename. + + If DIR is NULL, it will search a default path configured into libbfd +at build time. [XXX this feature is not currently implemented]. + + *Returns* +'NULL' on any errors or failure to locate the .debug file, otherwise a +pointer to a heap-allocated string containing the filename. The caller +is responsible for freeing this string. + +2.14.1.23 'bfd_follow_gnu_debugaltlink' +....................................... + +*Synopsis* + char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir); + *Description* +Takes a BFD and searches it for a .gnu_debugaltlink section. If this +section is found, it examines the section for the name of a file +containing auxiliary debugging information. It then searches the +filesystem for this file in a set of standard locations, including the +directory tree rooted at DIR, and if found returns the full filename. + + If DIR is NULL, it will search a default path configured into libbfd +at build time. [FIXME: This feature is not currently implemented]. + + *Returns* +'NULL' on any errors or failure to locate the debug file, otherwise a +pointer to a heap-allocated string containing the filename. The caller +is responsible for freeing this string. + +2.14.1.24 'bfd_create_gnu_debuglink_section' +............................................ + +*Synopsis* + struct bfd_section *bfd_create_gnu_debuglink_section + (bfd *abfd, const char *filename); + *Description* +Takes a BFD and adds a .gnu_debuglink section to it. The section is +sized to be big enough to contain a link to the specified FILENAME. + + *Returns* +A pointer to the new section is returned if all is ok. Otherwise 'NULL' +is returned and bfd_error is set. + +2.14.1.25 'bfd_fill_in_gnu_debuglink_section' +............................................. + +*Synopsis* + bfd_boolean bfd_fill_in_gnu_debuglink_section + (bfd *abfd, struct bfd_section *sect, const char *filename); + *Description* +Takes a BFD and containing a .gnu_debuglink section SECT and fills in +the contents of the section to contain a link to the specified FILENAME. +The filename should be relative to the current directory. + + *Returns* +'TRUE' is returned if all is ok. Otherwise 'FALSE' is returned and +bfd_error is set. + + +File: bfd.info, Node: Internal, Next: File Caching, Prev: Opening and Closing, Up: BFD front end + +2.15 Implementation details +=========================== + +2.15.1 Internal functions +------------------------- + +*Description* +These routines are used within BFD. They are not intended for export, +but are documented here for completeness. + +2.15.1.1 'bfd_write_bigendian_4byte_int' +........................................ + +*Synopsis* + bfd_boolean bfd_write_bigendian_4byte_int (bfd *, unsigned int); + *Description* +Write a 4 byte integer I to the output BFD ABFD, in big endian order +regardless of what else is going on. This is useful in archives. + +2.15.1.2 'bfd_put_size' +....................... + +2.15.1.3 'bfd_get_size' +....................... + +*Description* +These macros as used for reading and writing raw data in sections; each +access (except for bytes) is vectored through the target format of the +BFD and mangled accordingly. The mangling performs any necessary endian +translations and removes alignment restrictions. Note that types +accepted and returned by these macros are identical so they can be +swapped around in macros--for example, 'libaout.h' defines 'GET_WORD' to +either 'bfd_get_32' or 'bfd_get_64'. + + In the put routines, VAL must be a 'bfd_vma'. If we are on a system +without prototypes, the caller is responsible for making sure that is +true, with a cast if necessary. We don't cast them in the macro +definitions because that would prevent 'lint' or 'gcc -Wall' from +detecting sins such as passing a pointer. To detect calling these with +less than a 'bfd_vma', use 'gcc -Wconversion' on a host with 64 bit +'bfd_vma''s. + + /* Byte swapping macros for user section data. */ + + #define bfd_put_8(abfd, val, ptr) \ + ((void) (*((unsigned char *) (ptr)) = (val) & 0xff)) + #define bfd_put_signed_8 \ + bfd_put_8 + #define bfd_get_8(abfd, ptr) \ + (*(const unsigned char *) (ptr) & 0xff) + #define bfd_get_signed_8(abfd, ptr) \ + (((*(const unsigned char *) (ptr) & 0xff) ^ 0x80) - 0x80) + + #define bfd_put_16(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx16, ((val),(ptr))) + #define bfd_put_signed_16 \ + bfd_put_16 + #define bfd_get_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx16, (ptr)) + #define bfd_get_signed_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_16, (ptr)) + + #define bfd_put_32(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx32, ((val),(ptr))) + #define bfd_put_signed_32 \ + bfd_put_32 + #define bfd_get_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx32, (ptr)) + #define bfd_get_signed_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_32, (ptr)) + + #define bfd_put_64(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx64, ((val), (ptr))) + #define bfd_put_signed_64 \ + bfd_put_64 + #define bfd_get_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx64, (ptr)) + #define bfd_get_signed_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_64, (ptr)) + + #define bfd_get(bits, abfd, ptr) \ + ((bits) == 8 ? (bfd_vma) bfd_get_8 (abfd, ptr) \ + : (bits) == 16 ? bfd_get_16 (abfd, ptr) \ + : (bits) == 32 ? bfd_get_32 (abfd, ptr) \ + : (bits) == 64 ? bfd_get_64 (abfd, ptr) \ + : (abort (), (bfd_vma) - 1)) + + #define bfd_put(bits, abfd, val, ptr) \ + ((bits) == 8 ? bfd_put_8 (abfd, val, ptr) \ + : (bits) == 16 ? bfd_put_16 (abfd, val, ptr) \ + : (bits) == 32 ? bfd_put_32 (abfd, val, ptr) \ + : (bits) == 64 ? bfd_put_64 (abfd, val, ptr) \ + : (abort (), (void) 0)) + +2.15.1.4 'bfd_h_put_size' +......................... + +*Description* +These macros have the same function as their 'bfd_get_x' brethren, +except that they are used for removing information for the header +records of object files. Believe it or not, some object files keep +their header records in big endian order and their data in little endian +order. + + /* Byte swapping macros for file header data. */ + + #define bfd_h_put_8(abfd, val, ptr) \ + bfd_put_8 (abfd, val, ptr) + #define bfd_h_put_signed_8(abfd, val, ptr) \ + bfd_put_8 (abfd, val, ptr) + #define bfd_h_get_8(abfd, ptr) \ + bfd_get_8 (abfd, ptr) + #define bfd_h_get_signed_8(abfd, ptr) \ + bfd_get_signed_8 (abfd, ptr) + + #define bfd_h_put_16(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx16, (val, ptr)) + #define bfd_h_put_signed_16 \ + bfd_h_put_16 + #define bfd_h_get_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx16, (ptr)) + #define bfd_h_get_signed_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr)) + + #define bfd_h_put_32(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx32, (val, ptr)) + #define bfd_h_put_signed_32 \ + bfd_h_put_32 + #define bfd_h_get_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx32, (ptr)) + #define bfd_h_get_signed_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr)) + + #define bfd_h_put_64(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx64, (val, ptr)) + #define bfd_h_put_signed_64 \ + bfd_h_put_64 + #define bfd_h_get_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx64, (ptr)) + #define bfd_h_get_signed_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr)) + + /* Aliases for the above, which should eventually go away. */ + + #define H_PUT_64 bfd_h_put_64 + #define H_PUT_32 bfd_h_put_32 + #define H_PUT_16 bfd_h_put_16 + #define H_PUT_8 bfd_h_put_8 + #define H_PUT_S64 bfd_h_put_signed_64 + #define H_PUT_S32 bfd_h_put_signed_32 + #define H_PUT_S16 bfd_h_put_signed_16 + #define H_PUT_S8 bfd_h_put_signed_8 + #define H_GET_64 bfd_h_get_64 + #define H_GET_32 bfd_h_get_32 + #define H_GET_16 bfd_h_get_16 + #define H_GET_8 bfd_h_get_8 + #define H_GET_S64 bfd_h_get_signed_64 + #define H_GET_S32 bfd_h_get_signed_32 + #define H_GET_S16 bfd_h_get_signed_16 + #define H_GET_S8 bfd_h_get_signed_8 + + +2.15.1.5 'bfd_log2' +................... + +*Synopsis* + unsigned int bfd_log2 (bfd_vma x); + *Description* +Return the log base 2 of the value supplied, rounded up. E.g., an X of +1025 returns 11. A X of 0 returns 0. + + +File: bfd.info, Node: File Caching, Next: Linker Functions, Prev: Internal, Up: BFD front end + +2.16 File caching +================= + +The file caching mechanism is embedded within BFD and allows the +application to open as many BFDs as it wants without regard to the +underlying operating system's file descriptor limit (often as low as 20 +open files). The module in 'cache.c' maintains a least recently used +list of 'bfd_cache_max_open' files, and exports the name +'bfd_cache_lookup', which runs around and makes sure that the required +BFD is open. If not, then it chooses a file to close, closes it and +opens the one wanted, returning its file handle. + +2.16.1 Caching functions +------------------------ + +2.16.1.1 'bfd_cache_init' +......................... + +*Synopsis* + bfd_boolean bfd_cache_init (bfd *abfd); + *Description* +Add a newly opened BFD to the cache. + +2.16.1.2 'bfd_cache_close' +.......................... + +*Synopsis* + bfd_boolean bfd_cache_close (bfd *abfd); + *Description* +Remove the BFD ABFD from the cache. If the attached file is open, then +close it too. + + *Returns* +'FALSE' is returned if closing the file fails, 'TRUE' is returned if all +is well. + +2.16.1.3 'bfd_cache_close_all' +.............................. + +*Synopsis* + bfd_boolean bfd_cache_close_all (void); + *Description* +Remove all BFDs from the cache. If the attached file is open, then +close it too. + + *Returns* +'FALSE' is returned if closing one of the file fails, 'TRUE' is returned +if all is well. + +2.16.1.4 'bfd_open_file' +........................ + +*Synopsis* + FILE* bfd_open_file (bfd *abfd); + *Description* +Call the OS to open a file for ABFD. Return the 'FILE *' (possibly +'NULL') that results from this operation. Set up the BFD so that future +accesses know the file is open. If the 'FILE *' returned is 'NULL', +then it won't have been put in the cache, so it won't have to be removed +from it. + + +File: bfd.info, Node: Linker Functions, Next: Hash Tables, Prev: File Caching, Up: BFD front end + +2.17 Linker Functions +===================== + +The linker uses three special entry points in the BFD target vector. It +is not necessary to write special routines for these entry points when +creating a new BFD back end, since generic versions are provided. +However, writing them can speed up linking and make it use significantly +less runtime memory. + + The first routine creates a hash table used by the other routines. +The second routine adds the symbols from an object file to the hash +table. The third routine takes all the object files and links them +together to create the output file. These routines are designed so that +the linker proper does not need to know anything about the symbols in +the object files that it is linking. The linker merely arranges the +sections as directed by the linker script and lets BFD handle the +details of symbols and relocs. + + The second routine and third routines are passed a pointer to a +'struct bfd_link_info' structure (defined in 'bfdlink.h') which holds +information relevant to the link, including the linker hash table (which +was created by the first routine) and a set of callback functions to the +linker proper. + + The generic linker routines are in 'linker.c', and use the header +file 'genlink.h'. As of this writing, the only back ends which have +implemented versions of these routines are a.out (in 'aoutx.h') and +ECOFF (in 'ecoff.c'). The a.out routines are used as examples +throughout this section. + +* Menu: + +* Creating a Linker Hash Table:: +* Adding Symbols to the Hash Table:: +* Performing the Final Link:: + + +File: bfd.info, Node: Creating a Linker Hash Table, Next: Adding Symbols to the Hash Table, Prev: Linker Functions, Up: Linker Functions + +2.17.1 Creating a linker hash table +----------------------------------- + +The linker routines must create a hash table, which must be derived from +'struct bfd_link_hash_table' described in 'bfdlink.c'. *Note Hash +Tables::, for information on how to create a derived hash table. This +entry point is called using the target vector of the linker output file. + + The '_bfd_link_hash_table_create' entry point must allocate and +initialize an instance of the desired hash table. If the back end does +not require any additional information to be stored with the entries in +the hash table, the entry point may simply create a 'struct +bfd_link_hash_table'. Most likely, however, some additional information +will be needed. + + For example, with each entry in the hash table the a.out linker keeps +the index the symbol has in the final output file (this index number is +used so that when doing a relocatable link the symbol index used in the +output file can be quickly filled in when copying over a reloc). The +a.out linker code defines the required structures and functions for a +hash table derived from 'struct bfd_link_hash_table'. The a.out linker +hash table is created by the function +'NAME(aout,link_hash_table_create)'; it simply allocates space for the +hash table, initializes it, and returns a pointer to it. + + When writing the linker routines for a new back end, you will +generally not know exactly which fields will be required until you have +finished. You should simply create a new hash table which defines no +additional fields, and then simply add fields as they become necessary. + + +File: bfd.info, Node: Adding Symbols to the Hash Table, Next: Performing the Final Link, Prev: Creating a Linker Hash Table, Up: Linker Functions + +2.17.2 Adding symbols to the hash table +--------------------------------------- + +The linker proper will call the '_bfd_link_add_symbols' entry point for +each object file or archive which is to be linked (typically these are +the files named on the command line, but some may also come from the +linker script). The entry point is responsible for examining the file. +For an object file, BFD must add any relevant symbol information to the +hash table. For an archive, BFD must determine which elements of the +archive should be used and adding them to the link. + + The a.out version of this entry point is +'NAME(aout,link_add_symbols)'. + +* Menu: + +* Differing file formats:: +* Adding symbols from an object file:: +* Adding symbols from an archive:: + + +File: bfd.info, Node: Differing file formats, Next: Adding symbols from an object file, Prev: Adding Symbols to the Hash Table, Up: Adding Symbols to the Hash Table + +2.17.2.1 Differing file formats +............................... + +Normally all the files involved in a link will be of the same format, +but it is also possible to link together different format object files, +and the back end must support that. The '_bfd_link_add_symbols' entry +point is called via the target vector of the file to be added. This has +an important consequence: the function may not assume that the hash +table is the type created by the corresponding +'_bfd_link_hash_table_create' vector. All the '_bfd_link_add_symbols' +function can assume about the hash table is that it is derived from +'struct bfd_link_hash_table'. + + Sometimes the '_bfd_link_add_symbols' function must store some +information in the hash table entry to be used by the '_bfd_final_link' +function. In such a case the output bfd xvec must be checked to make +sure that the hash table was created by an object file of the same +format. + + The '_bfd_final_link' routine must be prepared to handle a hash entry +without any extra information added by the '_bfd_link_add_symbols' +function. A hash entry without extra information will also occur when +the linker script directs the linker to create a symbol. Note that, +regardless of how a hash table entry is added, all the fields will be +initialized to some sort of null value by the hash table entry +initialization function. + + See 'ecoff_link_add_externals' for an example of how to check the +output bfd before saving information (in this case, the ECOFF external +symbol debugging information) in a hash table entry. + + +File: bfd.info, Node: Adding symbols from an object file, Next: Adding symbols from an archive, Prev: Differing file formats, Up: Adding Symbols to the Hash Table + +2.17.2.2 Adding symbols from an object file +........................................... + +When the '_bfd_link_add_symbols' routine is passed an object file, it +must add all externally visible symbols in that object file to the hash +table. The actual work of adding the symbol to the hash table is +normally handled by the function '_bfd_generic_link_add_one_symbol'. +The '_bfd_link_add_symbols' routine is responsible for reading all the +symbols from the object file and passing the correct information to +'_bfd_generic_link_add_one_symbol'. + + The '_bfd_link_add_symbols' routine should not use +'bfd_canonicalize_symtab' to read the symbols. The point of providing +this routine is to avoid the overhead of converting the symbols into +generic 'asymbol' structures. + + '_bfd_generic_link_add_one_symbol' handles the details of combining +common symbols, warning about multiple definitions, and so forth. It +takes arguments which describe the symbol to add, notably symbol flags, +a section, and an offset. The symbol flags include such things as +'BSF_WEAK' or 'BSF_INDIRECT'. The section is a section in the object +file, or something like 'bfd_und_section_ptr' for an undefined symbol or +'bfd_com_section_ptr' for a common symbol. + + If the '_bfd_final_link' routine is also going to need to read the +symbol information, the '_bfd_link_add_symbols' routine should save it +somewhere attached to the object file BFD. However, the information +should only be saved if the 'keep_memory' field of the 'info' argument +is TRUE, so that the '-no-keep-memory' linker switch is effective. + + The a.out function which adds symbols from an object file is +'aout_link_add_object_symbols', and most of the interesting work is in +'aout_link_add_symbols'. The latter saves pointers to the hash tables +entries created by '_bfd_generic_link_add_one_symbol' indexed by symbol +number, so that the '_bfd_final_link' routine does not have to call the +hash table lookup routine to locate the entry. + + +File: bfd.info, Node: Adding symbols from an archive, Prev: Adding symbols from an object file, Up: Adding Symbols to the Hash Table + +2.17.2.3 Adding symbols from an archive +....................................... + +When the '_bfd_link_add_symbols' routine is passed an archive, it must +look through the symbols defined by the archive and decide which +elements of the archive should be included in the link. For each such +element it must call the 'add_archive_element' linker callback, and it +must add the symbols from the object file to the linker hash table. +(The callback may in fact indicate that a replacement BFD should be +used, in which case the symbols from that BFD should be added to the +linker hash table instead.) + + In most cases the work of looking through the symbols in the archive +should be done by the '_bfd_generic_link_add_archive_symbols' function. +This function builds a hash table from the archive symbol table and +looks through the list of undefined symbols to see which elements should +be included. '_bfd_generic_link_add_archive_symbols' is passed a +function to call to make the final decision about adding an archive +element to the link and to do the actual work of adding the symbols to +the linker hash table. + + The function passed to '_bfd_generic_link_add_archive_symbols' must +read the symbols of the archive element and decide whether the archive +element should be included in the link. If the element is to be +included, the 'add_archive_element' linker callback routine must be +called with the element as an argument, and the element's symbols must +be added to the linker hash table just as though the element had itself +been passed to the '_bfd_link_add_symbols' function. The +'add_archive_element' callback has the option to indicate that it would +like to replace the element archive with a substitute BFD, in which case +it is the symbols of that substitute BFD that must be added to the +linker hash table instead. + + When the a.out '_bfd_link_add_symbols' function receives an archive, +it calls '_bfd_generic_link_add_archive_symbols' passing +'aout_link_check_archive_element' as the function argument. +'aout_link_check_archive_element' calls 'aout_link_check_ar_symbols'. +If the latter decides to add the element (an element is only added if it +provides a real, non-common, definition for a previously undefined or +common symbol) it calls the 'add_archive_element' callback and then +'aout_link_check_archive_element' calls 'aout_link_add_symbols' to +actually add the symbols to the linker hash table - possibly those of a +substitute BFD, if the 'add_archive_element' callback avails itself of +that option. + + The ECOFF back end is unusual in that it does not normally call +'_bfd_generic_link_add_archive_symbols', because ECOFF archives already +contain a hash table of symbols. The ECOFF back end searches the +archive itself to avoid the overhead of creating a new hash table. + + +File: bfd.info, Node: Performing the Final Link, Prev: Adding Symbols to the Hash Table, Up: Linker Functions + +2.17.3 Performing the final link +-------------------------------- + +When all the input files have been processed, the linker calls the +'_bfd_final_link' entry point of the output BFD. This routine is +responsible for producing the final output file, which has several +aspects. It must relocate the contents of the input sections and copy +the data into the output sections. It must build an output symbol table +including any local symbols from the input files and the global symbols +from the hash table. When producing relocatable output, it must modify +the input relocs and write them into the output file. There may also be +object format dependent work to be done. + + The linker will also call the 'write_object_contents' entry point +when the BFD is closed. The two entry points must work together in +order to produce the correct output file. + + The details of how this works are inevitably dependent upon the +specific object file format. The a.out '_bfd_final_link' routine is +'NAME(aout,final_link)'. + +* Menu: + +* Information provided by the linker:: +* Relocating the section contents:: +* Writing the symbol table:: + + +File: bfd.info, Node: Information provided by the linker, Next: Relocating the section contents, Prev: Performing the Final Link, Up: Performing the Final Link + +2.17.3.1 Information provided by the linker +........................................... + +Before the linker calls the '_bfd_final_link' entry point, it sets up +some data structures for the function to use. + + The 'input_bfds' field of the 'bfd_link_info' structure will point to +a list of all the input files included in the link. These files are +linked through the 'link_next' field of the 'bfd' structure. + + Each section in the output file will have a list of 'link_order' +structures attached to the 'map_head.link_order' field (the 'link_order' +structure is defined in 'bfdlink.h'). These structures describe how to +create the contents of the output section in terms of the contents of +various input sections, fill constants, and, eventually, other types of +information. They also describe relocs that must be created by the BFD +backend, but do not correspond to any input file; this is used to +support -Ur, which builds constructors while generating a relocatable +object file. + + +File: bfd.info, Node: Relocating the section contents, Next: Writing the symbol table, Prev: Information provided by the linker, Up: Performing the Final Link + +2.17.3.2 Relocating the section contents +........................................ + +The '_bfd_final_link' function should look through the 'link_order' +structures attached to each section of the output file. Each +'link_order' structure should either be handled specially, or it should +be passed to the function '_bfd_default_link_order' which will do the +right thing ('_bfd_default_link_order' is defined in 'linker.c'). + + For efficiency, a 'link_order' of type 'bfd_indirect_link_order' +whose associated section belongs to a BFD of the same format as the +output BFD must be handled specially. This type of 'link_order' +describes part of an output section in terms of a section belonging to +one of the input files. The '_bfd_final_link' function should read the +contents of the section and any associated relocs, apply the relocs to +the section contents, and write out the modified section contents. If +performing a relocatable link, the relocs themselves must also be +modified and written out. + + The functions '_bfd_relocate_contents' and '_bfd_final_link_relocate' +provide some general support for performing the actual relocations, +notably overflow checking. Their arguments include information about +the symbol the relocation is against and a 'reloc_howto_type' argument +which describes the relocation to perform. These functions are defined +in 'reloc.c'. + + The a.out function which handles reading, relocating, and writing +section contents is 'aout_link_input_section'. The actual relocation is +done in 'aout_link_input_section_std' and 'aout_link_input_section_ext'. + + +File: bfd.info, Node: Writing the symbol table, Prev: Relocating the section contents, Up: Performing the Final Link + +2.17.3.3 Writing the symbol table +................................. + +The '_bfd_final_link' function must gather all the symbols in the input +files and write them out. It must also write out all the symbols in the +global hash table. This must be controlled by the 'strip' and 'discard' +fields of the 'bfd_link_info' structure. + + The local symbols of the input files will not have been entered into +the linker hash table. The '_bfd_final_link' routine must consider each +input file and include the symbols in the output file. It may be +convenient to do this when looking through the 'link_order' structures, +or it may be done by stepping through the 'input_bfds' list. + + The '_bfd_final_link' routine must also traverse the global hash +table to gather all the externally visible symbols. It is possible that +most of the externally visible symbols may be written out when +considering the symbols of each input file, but it is still necessary to +traverse the hash table since the linker script may have defined some +symbols that are not in any of the input files. + + The 'strip' field of the 'bfd_link_info' structure controls which +symbols are written out. The possible values are listed in 'bfdlink.h'. +If the value is 'strip_some', then the 'keep_hash' field of the +'bfd_link_info' structure is a hash table of symbols to keep; each +symbol should be looked up in this hash table, and only symbols which +are present should be included in the output file. + + If the 'strip' field of the 'bfd_link_info' structure permits local +symbols to be written out, the 'discard' field is used to further +controls which local symbols are included in the output file. If the +value is 'discard_l', then all local symbols which begin with a certain +prefix are discarded; this is controlled by the +'bfd_is_local_label_name' entry point. + + The a.out backend handles symbols by calling +'aout_link_write_symbols' on each input BFD and then traversing the +global hash table with the function 'aout_link_write_other_symbol'. It +builds a string table while writing out the symbols, which is written to +the output file at the end of 'NAME(aout,final_link)'. + +2.17.3.4 'bfd_link_split_section' +................................. + +*Synopsis* + bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec); + *Description* +Return nonzero if SEC should be split during a reloceatable or final +link. + #define bfd_link_split_section(abfd, sec) \ + BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) + +2.17.3.5 'bfd_section_already_linked' +..................................... + +*Synopsis* + bfd_boolean bfd_section_already_linked (bfd *abfd, + asection *sec, + struct bfd_link_info *info); + *Description* +Check if DATA has been already linked during a reloceatable or final +link. Return TRUE if it has. + #define bfd_section_already_linked(abfd, sec, info) \ + BFD_SEND (abfd, _section_already_linked, (abfd, sec, info)) + +2.17.3.6 'bfd_generic_define_common_symbol' +........................................... + +*Synopsis* + bfd_boolean bfd_generic_define_common_symbol + (bfd *output_bfd, struct bfd_link_info *info, + struct bfd_link_hash_entry *h); + *Description* +Convert common symbol H into a defined symbol. Return TRUE on success +and FALSE on failure. + #define bfd_define_common_symbol(output_bfd, info, h) \ + BFD_SEND (output_bfd, _bfd_define_common_symbol, (output_bfd, info, h)) + +2.17.3.7 'bfd_find_version_for_sym' +................................... + +*Synopsis* + struct bfd_elf_version_tree * bfd_find_version_for_sym + (struct bfd_elf_version_tree *verdefs, + const char *sym_name, bfd_boolean *hide); + *Description* +Search an elf version script tree for symbol versioning info and export +/ don't-export status for a given symbol. Return non-NULL on success +and NULL on failure; also sets the output 'hide' boolean parameter. + +2.17.3.8 'bfd_hide_sym_by_version' +.................................. + +*Synopsis* + bfd_boolean bfd_hide_sym_by_version + (struct bfd_elf_version_tree *verdefs, const char *sym_name); + *Description* +Search an elf version script tree for symbol versioning info for a given +symbol. Return TRUE if the symbol is hidden. + + +File: bfd.info, Node: Hash Tables, Prev: Linker Functions, Up: BFD front end + +2.18 Hash Tables +================ + +BFD provides a simple set of hash table functions. Routines are +provided to initialize a hash table, to free a hash table, to look up a +string in a hash table and optionally create an entry for it, and to +traverse a hash table. There is currently no routine to delete an +string from a hash table. + + The basic hash table does not permit any data to be stored with a +string. However, a hash table is designed to present a base class from +which other types of hash tables may be derived. These derived types +may store additional information with the string. Hash tables were +implemented in this way, rather than simply providing a data pointer in +a hash table entry, because they were designed for use by the linker +back ends. The linker may create thousands of hash table entries, and +the overhead of allocating private data and storing and following +pointers becomes noticeable. + + The basic hash table code is in 'hash.c'. + +* Menu: + +* Creating and Freeing a Hash Table:: +* Looking Up or Entering a String:: +* Traversing a Hash Table:: +* Deriving a New Hash Table Type:: + + +File: bfd.info, Node: Creating and Freeing a Hash Table, Next: Looking Up or Entering a String, Prev: Hash Tables, Up: Hash Tables + +2.18.1 Creating and freeing a hash table +---------------------------------------- + +To create a hash table, create an instance of a 'struct bfd_hash_table' +(defined in 'bfd.h') and call 'bfd_hash_table_init' (if you know +approximately how many entries you will need, the function +'bfd_hash_table_init_n', which takes a SIZE argument, may be used). +'bfd_hash_table_init' returns 'FALSE' if some sort of error occurs. + + The function 'bfd_hash_table_init' take as an argument a function to +use to create new entries. For a basic hash table, use the function +'bfd_hash_newfunc'. *Note Deriving a New Hash Table Type::, for why you +would want to use a different value for this argument. + + 'bfd_hash_table_init' will create an objalloc which will be used to +allocate new entries. You may allocate memory on this objalloc using +'bfd_hash_allocate'. + + Use 'bfd_hash_table_free' to free up all the memory that has been +allocated for a hash table. This will not free up the 'struct +bfd_hash_table' itself, which you must provide. + + Use 'bfd_hash_set_default_size' to set the default size of hash table +to use. + + +File: bfd.info, Node: Looking Up or Entering a String, Next: Traversing a Hash Table, Prev: Creating and Freeing a Hash Table, Up: Hash Tables + +2.18.2 Looking up or entering a string +-------------------------------------- + +The function 'bfd_hash_lookup' is used both to look up a string in the +hash table and to create a new entry. + + If the CREATE argument is 'FALSE', 'bfd_hash_lookup' will look up a +string. If the string is found, it will returns a pointer to a 'struct +bfd_hash_entry'. If the string is not found in the table +'bfd_hash_lookup' will return 'NULL'. You should not modify any of the +fields in the returns 'struct bfd_hash_entry'. + + If the CREATE argument is 'TRUE', the string will be entered into the +hash table if it is not already there. Either way a pointer to a +'struct bfd_hash_entry' will be returned, either to the existing +structure or to a newly created one. In this case, a 'NULL' return +means that an error occurred. + + If the CREATE argument is 'TRUE', and a new entry is created, the +COPY argument is used to decide whether to copy the string onto the hash +table objalloc or not. If COPY is passed as 'FALSE', you must be +careful not to deallocate or modify the string as long as the hash table +exists. + + +File: bfd.info, Node: Traversing a Hash Table, Next: Deriving a New Hash Table Type, Prev: Looking Up or Entering a String, Up: Hash Tables + +2.18.3 Traversing a hash table +------------------------------ + +The function 'bfd_hash_traverse' may be used to traverse a hash table, +calling a function on each element. The traversal is done in a random +order. + + 'bfd_hash_traverse' takes as arguments a function and a generic 'void +*' pointer. The function is called with a hash table entry (a 'struct +bfd_hash_entry *') and the generic pointer passed to +'bfd_hash_traverse'. The function must return a 'boolean' value, which +indicates whether to continue traversing the hash table. If the +function returns 'FALSE', 'bfd_hash_traverse' will stop the traversal +and return immediately. + + +File: bfd.info, Node: Deriving a New Hash Table Type, Prev: Traversing a Hash Table, Up: Hash Tables + +2.18.4 Deriving a new hash table type +------------------------------------- + +Many uses of hash tables want to store additional information which each +entry in the hash table. Some also find it convenient to store +additional information with the hash table itself. This may be done +using a derived hash table. + + Since C is not an object oriented language, creating a derived hash +table requires sticking together some boilerplate routines with a few +differences specific to the type of hash table you want to create. + + An example of a derived hash table is the linker hash table. The +structures for this are defined in 'bfdlink.h'. The functions are in +'linker.c'. + + You may also derive a hash table from an already derived hash table. +For example, the a.out linker backend code uses a hash table derived +from the linker hash table. + +* Menu: + +* Define the Derived Structures:: +* Write the Derived Creation Routine:: +* Write Other Derived Routines:: + + +File: bfd.info, Node: Define the Derived Structures, Next: Write the Derived Creation Routine, Prev: Deriving a New Hash Table Type, Up: Deriving a New Hash Table Type + +2.18.4.1 Define the derived structures +...................................... + +You must define a structure for an entry in the hash table, and a +structure for the hash table itself. + + The first field in the structure for an entry in the hash table must +be of the type used for an entry in the hash table you are deriving +from. If you are deriving from a basic hash table this is 'struct +bfd_hash_entry', which is defined in 'bfd.h'. The first field in the +structure for the hash table itself must be of the type of the hash +table you are deriving from itself. If you are deriving from a basic +hash table, this is 'struct bfd_hash_table'. + + For example, the linker hash table defines 'struct +bfd_link_hash_entry' (in 'bfdlink.h'). The first field, 'root', is of +type 'struct bfd_hash_entry'. Similarly, the first field in 'struct +bfd_link_hash_table', 'table', is of type 'struct bfd_hash_table'. + + +File: bfd.info, Node: Write the Derived Creation Routine, Next: Write Other Derived Routines, Prev: Define the Derived Structures, Up: Deriving a New Hash Table Type + +2.18.4.2 Write the derived creation routine +........................................... + +You must write a routine which will create and initialize an entry in +the hash table. This routine is passed as the function argument to +'bfd_hash_table_init'. + + In order to permit other hash tables to be derived from the hash +table you are creating, this routine must be written in a standard way. + + The first argument to the creation routine is a pointer to a hash +table entry. This may be 'NULL', in which case the routine should +allocate the right amount of space. Otherwise the space has already +been allocated by a hash table type derived from this one. + + After allocating space, the creation routine must call the creation +routine of the hash table type it is derived from, passing in a pointer +to the space it just allocated. This will initialize any fields used by +the base hash table. + + Finally the creation routine must initialize any local fields for the +new hash table type. + + Here is a boilerplate example of a creation routine. FUNCTION_NAME +is the name of the routine. ENTRY_TYPE is the type of an entry in the +hash table you are creating. BASE_NEWFUNC is the name of the creation +routine of the hash table type your hash table is derived from. + + struct bfd_hash_entry * + FUNCTION_NAME (struct bfd_hash_entry *entry, + struct bfd_hash_table *table, + const char *string) + { + struct ENTRY_TYPE *ret = (ENTRY_TYPE *) entry; + + /* Allocate the structure if it has not already been allocated by a + derived class. */ + if (ret == NULL) + { + ret = bfd_hash_allocate (table, sizeof (* ret)); + if (ret == NULL) + return NULL; + } + + /* Call the allocation method of the base class. */ + ret = ((ENTRY_TYPE *) + BASE_NEWFUNC ((struct bfd_hash_entry *) ret, table, string)); + + /* Initialize the local fields here. */ + + return (struct bfd_hash_entry *) ret; + } + *Description* +The creation routine for the linker hash table, which is in 'linker.c', +looks just like this example. FUNCTION_NAME is +'_bfd_link_hash_newfunc'. ENTRY_TYPE is 'struct bfd_link_hash_entry'. +BASE_NEWFUNC is 'bfd_hash_newfunc', the creation routine for a basic +hash table. + + '_bfd_link_hash_newfunc' also initializes the local fields in a +linker hash table entry: 'type', 'written' and 'next'. + + +File: bfd.info, Node: Write Other Derived Routines, Prev: Write the Derived Creation Routine, Up: Deriving a New Hash Table Type + +2.18.4.3 Write other derived routines +..................................... + +You will want to write other routines for your new hash table, as well. + + You will want an initialization routine which calls the +initialization routine of the hash table you are deriving from and +initializes any other local fields. For the linker hash table, this is +'_bfd_link_hash_table_init' in 'linker.c'. + + You will want a lookup routine which calls the lookup routine of the +hash table you are deriving from and casts the result. The linker hash +table uses 'bfd_link_hash_lookup' in 'linker.c' (this actually takes an +additional argument which it uses to decide how to return the looked up +value). + + You may want a traversal routine. This should just call the +traversal routine of the hash table you are deriving from with +appropriate casts. The linker hash table uses 'bfd_link_hash_traverse' +in 'linker.c'. + + These routines may simply be defined as macros. For example, the +a.out backend linker hash table, which is derived from the linker hash +table, uses macros for the lookup and traversal routines. These are +'aout_link_hash_lookup' and 'aout_link_hash_traverse' in aoutx.h. + + +File: bfd.info, Node: BFD back ends, Next: GNU Free Documentation License, Prev: BFD front end, Up: Top + +3 BFD back ends +*************** + +* Menu: + +* What to Put Where:: +* aout :: a.out backends +* coff :: coff backends +* elf :: elf backends +* mmo :: mmo backend + + +File: bfd.info, Node: What to Put Where, Next: aout, Prev: BFD back ends, Up: BFD back ends + +3.1 What to Put Where +===================== + +All of BFD lives in one directory. + + +File: bfd.info, Node: aout, Next: coff, Prev: What to Put Where, Up: BFD back ends + +3.2 a.out backends +================== + +*Description* +BFD supports a number of different flavours of a.out format, though the +major differences are only the sizes of the structures on disk, and the +shape of the relocation information. + + The support is split into a basic support file 'aoutx.h' and other +files which derive functions from the base. One derivation file is +'aoutf1.h' (for a.out flavour 1), and adds to the basic a.out functions +support for sun3, sun4, 386 and 29k a.out files, to create a target jump +vector for a specific target. + + This information is further split out into more specific files for +each machine, including 'sunos.c' for sun3 and sun4, 'newsos3.c' for the +Sony NEWS, and 'demo64.c' for a demonstration of a 64 bit a.out format. + + The base file 'aoutx.h' defines general mechanisms for reading and +writing records to and from disk and various other methods which BFD +requires. It is included by 'aout32.c' and 'aout64.c' to form the names +'aout_32_swap_exec_header_in', 'aout_64_swap_exec_header_in', etc. + + As an example, this is what goes on to make the back end for a sun4, +from 'aout32.c': + + #define ARCH_SIZE 32 + #include "aoutx.h" + + Which exports names: + + ... + aout_32_canonicalize_reloc + aout_32_find_nearest_line + aout_32_get_lineno + aout_32_get_reloc_upper_bound + ... + + from 'sunos.c': + + #define TARGET_NAME "a.out-sunos-big" + #define VECNAME sunos_big_vec + #include "aoutf1.h" + + requires all the names from 'aout32.c', and produces the jump vector + + sunos_big_vec + + The file 'host-aout.c' is a special case. It is for a large set of +hosts that use "more or less standard" a.out files, and for which +cross-debugging is not interesting. It uses the standard 32-bit a.out +support routines, but determines the file offsets and addresses of the +text, data, and BSS sections, the machine architecture and machine type, +and the entry point address, in a host-dependent manner. Once these +values have been determined, generic code is used to handle the object +file. + + When porting it to run on a new system, you must supply: + + HOST_PAGE_SIZE + HOST_SEGMENT_SIZE + HOST_MACHINE_ARCH (optional) + HOST_MACHINE_MACHINE (optional) + HOST_TEXT_START_ADDR + HOST_STACK_END_ADDR + + in the file '../include/sys/h-XXX.h' (for your host). These values, +plus the structures and macros defined in 'a.out.h' on your host system, +will produce a BFD target that will access ordinary a.out files on your +host. To configure a new machine to use 'host-aout.c', specify: + + TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec + TDEPFILES= host-aout.o trad-core.o + + in the 'config/XXX.mt' file, and modify 'configure.in' to use the +'XXX.mt' file (by setting "'bfd_target=XXX'") when your configuration is +selected. + +3.2.1 Relocations +----------------- + +*Description* +The file 'aoutx.h' provides for both the _standard_ and _extended_ forms +of a.out relocation records. + + The standard records contain only an address, a symbol index, and a +type field. The extended records (used on 29ks and sparcs) also have a +full integer for an addend. + +3.2.2 Internal entry points +--------------------------- + +*Description* +'aoutx.h' exports several routines for accessing the contents of an +a.out file, which are gathered and exported in turn by various format +specific files (eg sunos.c). + +3.2.2.1 'aout_SIZE_swap_exec_header_in' +....................................... + +*Synopsis* + void aout_SIZE_swap_exec_header_in, + (bfd *abfd, + struct external_exec *bytes, + struct internal_exec *execp); + *Description* +Swap the information in an executable header RAW_BYTES taken from a raw +byte stream memory image into the internal exec header structure EXECP. + +3.2.2.2 'aout_SIZE_swap_exec_header_out' +........................................ + +*Synopsis* + void aout_SIZE_swap_exec_header_out + (bfd *abfd, + struct internal_exec *execp, + struct external_exec *raw_bytes); + *Description* +Swap the information in an internal exec header structure EXECP into the +buffer RAW_BYTES ready for writing to disk. + +3.2.2.3 'aout_SIZE_some_aout_object_p' +...................................... + +*Synopsis* + const bfd_target *aout_SIZE_some_aout_object_p + (bfd *abfd, + struct internal_exec *execp, + const bfd_target *(*callback_to_real_object_p) (bfd *)); + *Description* +Some a.out variant thinks that the file open in ABFD checking is an +a.out file. Do some more checking, and set up for access if it really +is. Call back to the calling environment's "finish up" function just +before returning, to handle any last-minute setup. + +3.2.2.4 'aout_SIZE_mkobject' +............................ + +*Synopsis* + bfd_boolean aout_SIZE_mkobject, (bfd *abfd); + *Description* +Initialize BFD ABFD for use with a.out files. + +3.2.2.5 'aout_SIZE_machine_type' +................................ + +*Synopsis* + enum machine_type aout_SIZE_machine_type + (enum bfd_architecture arch, + unsigned long machine, + bfd_boolean *unknown); + *Description* +Keep track of machine architecture and machine type for a.out's. Return +the 'machine_type' for a particular architecture and machine, or +'M_UNKNOWN' if that exact architecture and machine can't be represented +in a.out format. + + If the architecture is understood, machine type 0 (default) is always +understood. + +3.2.2.6 'aout_SIZE_set_arch_mach' +................................. + +*Synopsis* + bfd_boolean aout_SIZE_set_arch_mach, + (bfd *, + enum bfd_architecture arch, + unsigned long machine); + *Description* +Set the architecture and the machine of the BFD ABFD to the values ARCH +and MACHINE. Verify that ABFD's format can support the architecture +required. + +3.2.2.7 'aout_SIZE_new_section_hook' +.................................... + +*Synopsis* + bfd_boolean aout_SIZE_new_section_hook, + (bfd *abfd, + asection *newsect); + *Description* +Called by the BFD in response to a 'bfd_make_section' request. + + +File: bfd.info, Node: coff, Next: elf, Prev: aout, Up: BFD back ends + +3.3 coff backends +================= + +BFD supports a number of different flavours of coff format. The major +differences between formats are the sizes and alignments of fields in +structures on disk, and the occasional extra field. + + Coff in all its varieties is implemented with a few common files and +a number of implementation specific files. For example, The 88k bcs +coff format is implemented in the file 'coff-m88k.c'. This file +'#include's 'coff/m88k.h' which defines the external structure of the +coff format for the 88k, and 'coff/internal.h' which defines the +internal structure. 'coff-m88k.c' also defines the relocations used by +the 88k format *Note Relocations::. + + The Intel i960 processor version of coff is implemented in +'coff-i960.c'. This file has the same structure as 'coff-m88k.c', +except that it includes 'coff/i960.h' rather than 'coff-m88k.h'. + +3.3.1 Porting to a new version of coff +-------------------------------------- + +The recommended method is to select from the existing implementations +the version of coff which is most like the one you want to use. For +example, we'll say that i386 coff is the one you select, and that your +coff flavour is called foo. Copy 'i386coff.c' to 'foocoff.c', copy +'../include/coff/i386.h' to '../include/coff/foo.h', and add the lines +to 'targets.c' and 'Makefile.in' so that your new back end is used. +Alter the shapes of the structures in '../include/coff/foo.h' so that +they match what you need. You will probably also have to add '#ifdef's +to the code in 'coff/internal.h' and 'coffcode.h' if your version of +coff is too wild. + + You can verify that your new BFD backend works quite simply by +building 'objdump' from the 'binutils' directory, and making sure that +its version of what's going on and your host system's idea (assuming it +has the pretty standard coff dump utility, usually called 'att-dump' or +just 'dump') are the same. Then clean up your code, and send what +you've done to Cygnus. Then your stuff will be in the next release, and +you won't have to keep integrating it. + +3.3.2 How the coff backend works +-------------------------------- + +3.3.2.1 File layout +................... + +The Coff backend is split into generic routines that are applicable to +any Coff target and routines that are specific to a particular target. +The target-specific routines are further split into ones which are +basically the same for all Coff targets except that they use the +external symbol format or use different values for certain constants. + + The generic routines are in 'coffgen.c'. These routines work for any +Coff target. They use some hooks into the target specific code; the +hooks are in a 'bfd_coff_backend_data' structure, one of which exists +for each target. + + The essentially similar target-specific routines are in 'coffcode.h'. +This header file includes executable C code. The various Coff targets +first include the appropriate Coff header file, make any special defines +that are needed, and then include 'coffcode.h'. + + Some of the Coff targets then also have additional routines in the +target source file itself. + + For example, 'coff-i960.c' includes 'coff/internal.h' and +'coff/i960.h'. It then defines a few constants, such as 'I960', and +includes 'coffcode.h'. Since the i960 has complex relocation types, +'coff-i960.c' also includes some code to manipulate the i960 relocs. +This code is not in 'coffcode.h' because it would not be used by any +other target. + +3.3.2.2 Coff long section names +............................... + +In the standard Coff object format, section names are limited to the +eight bytes available in the 's_name' field of the 'SCNHDR' section +header structure. The format requires the field to be NUL-padded, but +not necessarily NUL-terminated, so the longest section names permitted +are a full eight characters. + + The Microsoft PE variants of the Coff object file format add an +extension to support the use of long section names. This extension is +defined in section 4 of the Microsoft PE/COFF specification (rev 8.1). +If a section name is too long to fit into the section header's 's_name' +field, it is instead placed into the string table, and the 's_name' +field is filled with a slash ("/") followed by the ASCII decimal +representation of the offset of the full name relative to the string +table base. + + Note that this implies that the extension can only be used in object +files, as executables do not contain a string table. The standard +specifies that long section names from objects emitted into executable +images are to be truncated. + + However, as a GNU extension, BFD can generate executable images that +contain a string table and long section names. This would appear to be +technically valid, as the standard only says that Coff debugging +information is deprecated, not forbidden, and in practice it works, +although some tools that parse PE files expecting the MS standard format +may become confused; 'PEview' is one known example. + + The functionality is supported in BFD by code implemented under the +control of the macro 'COFF_LONG_SECTION_NAMES'. If not defined, the +format does not support long section names in any way. If defined, it +is used to initialise a flag, '_bfd_coff_long_section_names', and a hook +function pointer, '_bfd_coff_set_long_section_names', in the Coff +backend data structure. The flag controls the generation of long +section names in output BFDs at runtime; if it is false, as it will be +by default when generating an executable image, long section names are +truncated; if true, the long section names extension is employed. The +hook points to a function that allows the value of the flag to be +altered at runtime, on formats that support long section names at all; +on other formats it points to a stub that returns an error indication. + + With input BFDs, the flag is set according to whether any long +section names are detected while reading the section headers. For a +completely new BFD, the flag is set to the default for the target +format. This information can be used by a client of the BFD library +when deciding what output format to generate, and means that a BFD that +is opened for read and subsequently converted to a writeable BFD and +modified in-place will retain whatever format it had on input. + + If 'COFF_LONG_SECTION_NAMES' is simply defined (blank), or is defined +to the value "1", then long section names are enabled by default; if it +is defined to the value zero, they are disabled by default (but still +accepted in input BFDs). The header 'coffcode.h' defines a macro, +'COFF_DEFAULT_LONG_SECTION_NAMES', which is used in the backends to +initialise the backend data structure fields appropriately; see the +comments for further detail. + +3.3.2.3 Bit twiddling +..................... + +Each flavour of coff supported in BFD has its own header file describing +the external layout of the structures. There is also an internal +description of the coff layout, in 'coff/internal.h'. A major function +of the coff backend is swapping the bytes and twiddling the bits to +translate the external form of the structures into the normal internal +form. This is all performed in the 'bfd_swap'_thing_direction routines. +Some elements are different sizes between different versions of coff; it +is the duty of the coff version specific include file to override the +definitions of various packing routines in 'coffcode.h'. E.g., the size +of line number entry in coff is sometimes 16 bits, and sometimes 32 +bits. '#define'ing 'PUT_LNSZ_LNNO' and 'GET_LNSZ_LNNO' will select the +correct one. No doubt, some day someone will find a version of coff +which has a varying field size not catered to at the moment. To port +BFD, that person will have to add more '#defines'. Three of the bit +twiddling routines are exported to 'gdb'; 'coff_swap_aux_in', +'coff_swap_sym_in' and 'coff_swap_lineno_in'. 'GDB' reads the symbol +table on its own, but uses BFD to fix things up. More of the bit +twiddlers are exported for 'gas'; 'coff_swap_aux_out', +'coff_swap_sym_out', 'coff_swap_lineno_out', 'coff_swap_reloc_out', +'coff_swap_filehdr_out', 'coff_swap_aouthdr_out', +'coff_swap_scnhdr_out'. 'Gas' currently keeps track of all the symbol +table and reloc drudgery itself, thereby saving the internal BFD +overhead, but uses BFD to swap things on the way out, making cross ports +much safer. Doing so also allows BFD (and thus the linker) to use the +same header files as 'gas', which makes one avenue to disaster +disappear. + +3.3.2.4 Symbol reading +...................... + +The simple canonical form for symbols used by BFD is not rich enough to +keep all the information available in a coff symbol table. The back end +gets around this problem by keeping the original symbol table around, +"behind the scenes". + + When a symbol table is requested (through a call to +'bfd_canonicalize_symtab'), a request gets through to +'coff_get_normalized_symtab'. This reads the symbol table from the coff +file and swaps all the structures inside into the internal form. It +also fixes up all the pointers in the table (represented in the file by +offsets from the first symbol in the table) into physical pointers to +elements in the new internal table. This involves some work since the +meanings of fields change depending upon context: a field that is a +pointer to another structure in the symbol table at one moment may be +the size in bytes of a structure at the next. Another pass is made over +the table. All symbols which mark file names ('C_FILE' symbols) are +modified so that the internal string points to the value in the auxent +(the real filename) rather than the normal text associated with the +symbol ('".file"'). + + At this time the symbol names are moved around. Coff stores all +symbols less than nine characters long physically within the symbol +table; longer strings are kept at the end of the file in the string +table. This pass moves all strings into memory and replaces them with +pointers to the strings. + + The symbol table is massaged once again, this time to create the +canonical table used by the BFD application. Each symbol is inspected +in turn, and a decision made (using the 'sclass' field) about the +various flags to set in the 'asymbol'. *Note Symbols::. The generated +canonical table shares strings with the hidden internal symbol table. + + Any linenumbers are read from the coff file too, and attached to the +symbols which own the functions the linenumbers belong to. + +3.3.2.5 Symbol writing +...................... + +Writing a symbol to a coff file which didn't come from a coff file will +lose any debugging information. The 'asymbol' structure remembers the +BFD from which the symbol was taken, and on output the back end makes +sure that the same destination target as source target is present. + + When the symbols have come from a coff file then all the debugging +information is preserved. + + Symbol tables are provided for writing to the back end in a vector of +pointers to pointers. This allows applications like the linker to +accumulate and output large symbol tables without having to do too much +byte copying. + + This function runs through the provided symbol table and patches each +symbol marked as a file place holder ('C_FILE') to point to the next +file place holder in the list. It also marks each 'offset' field in the +list with the offset from the first symbol of the current symbol. + + Another function of this procedure is to turn the canonical value +form of BFD into the form used by coff. Internally, BFD expects symbol +values to be offsets from a section base; so a symbol physically at +0x120, but in a section starting at 0x100, would have the value 0x20. +Coff expects symbols to contain their final value, so symbols have their +values changed at this point to reflect their sum with their owning +section. This transformation uses the 'output_section' field of the +'asymbol''s 'asection' *Note Sections::. + + * 'coff_mangle_symbols' + This routine runs though the provided symbol table and uses the +offsets generated by the previous pass and the pointers generated when +the symbol table was read in to create the structured hierarchy required +by coff. It changes each pointer to a symbol into the index into the +symbol table of the asymbol. + + * 'coff_write_symbols' + This routine runs through the symbol table and patches up the symbols +from their internal form into the coff way, calls the bit twiddlers, and +writes out the table to the file. + +3.3.2.6 'coff_symbol_type' +.......................... + +*Description* +The hidden information for an 'asymbol' is described in a +'combined_entry_type': + + + typedef struct coff_ptr_struct + { + /* Remembers the offset from the first symbol in the file for + this symbol. Generated by coff_renumber_symbols. */ + unsigned int offset; + + /* Should the value of this symbol be renumbered. Used for + XCOFF C_BSTAT symbols. Set by coff_slurp_symbol_table. */ + unsigned int fix_value : 1; + + /* Should the tag field of this symbol be renumbered. + Created by coff_pointerize_aux. */ + unsigned int fix_tag : 1; + + /* Should the endidx field of this symbol be renumbered. + Created by coff_pointerize_aux. */ + unsigned int fix_end : 1; + + /* Should the x_csect.x_scnlen field be renumbered. + Created by coff_pointerize_aux. */ + unsigned int fix_scnlen : 1; + + /* Fix up an XCOFF C_BINCL/C_EINCL symbol. The value is the + index into the line number entries. Set by coff_slurp_symbol_table. */ + unsigned int fix_line : 1; + + /* The container for the symbol structure as read and translated + from the file. */ + union + { + union internal_auxent auxent; + struct internal_syment syment; + } u; + } combined_entry_type; + + + /* Each canonical asymbol really looks like this: */ + + typedef struct coff_symbol_struct + { + /* The actual symbol which the rest of BFD works with */ + asymbol symbol; + + /* A pointer to the hidden information for this symbol */ + combined_entry_type *native; + + /* A pointer to the linenumber information for this symbol */ + struct lineno_cache_entry *lineno; + + /* Have the line numbers been relocated yet ? */ + bfd_boolean done_lineno; + } coff_symbol_type; + +3.3.2.7 'bfd_coff_backend_data' +............................... + + /* COFF symbol classifications. */ + + enum coff_symbol_classification + { + /* Global symbol. */ + COFF_SYMBOL_GLOBAL, + /* Common symbol. */ + COFF_SYMBOL_COMMON, + /* Undefined symbol. */ + COFF_SYMBOL_UNDEFINED, + /* Local symbol. */ + COFF_SYMBOL_LOCAL, + /* PE section symbol. */ + COFF_SYMBOL_PE_SECTION + }; + + Special entry points for gdb to swap in coff symbol table parts: + typedef struct + { + void (*_bfd_coff_swap_aux_in) + (bfd *, void *, int, int, int, int, void *); + + void (*_bfd_coff_swap_sym_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_lineno_in) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_aux_out) + (bfd *, void *, int, int, int, int, void *); + + unsigned int (*_bfd_coff_swap_sym_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_lineno_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_reloc_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_filehdr_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_aouthdr_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_scnhdr_out) + (bfd *, void *, void *); + + unsigned int _bfd_filhsz; + unsigned int _bfd_aoutsz; + unsigned int _bfd_scnhsz; + unsigned int _bfd_symesz; + unsigned int _bfd_auxesz; + unsigned int _bfd_relsz; + unsigned int _bfd_linesz; + unsigned int _bfd_filnmlen; + bfd_boolean _bfd_coff_long_filenames; + + bfd_boolean _bfd_coff_long_section_names; + bfd_boolean (*_bfd_coff_set_long_section_names) + (bfd *, int); + + unsigned int _bfd_coff_default_section_alignment_power; + bfd_boolean _bfd_coff_force_symnames_in_strings; + unsigned int _bfd_coff_debug_string_prefix_length; + + void (*_bfd_coff_swap_filehdr_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_aouthdr_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_scnhdr_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_reloc_in) + (bfd *abfd, void *, void *); + + bfd_boolean (*_bfd_coff_bad_format_hook) + (bfd *, void *); + + bfd_boolean (*_bfd_coff_set_arch_mach_hook) + (bfd *, void *); + + void * (*_bfd_coff_mkobject_hook) + (bfd *, void *, void *); + + bfd_boolean (*_bfd_styp_to_sec_flags_hook) + (bfd *, void *, const char *, asection *, flagword *); + + void (*_bfd_set_alignment_hook) + (bfd *, asection *, void *); + + bfd_boolean (*_bfd_coff_slurp_symbol_table) + (bfd *); + + bfd_boolean (*_bfd_coff_symname_in_debug) + (bfd *, struct internal_syment *); + + bfd_boolean (*_bfd_coff_pointerize_aux_hook) + (bfd *, combined_entry_type *, combined_entry_type *, + unsigned int, combined_entry_type *); + + bfd_boolean (*_bfd_coff_print_aux) + (bfd *, FILE *, combined_entry_type *, combined_entry_type *, + combined_entry_type *, unsigned int); + + void (*_bfd_coff_reloc16_extra_cases) + (bfd *, struct bfd_link_info *, struct bfd_link_order *, arelent *, + bfd_byte *, unsigned int *, unsigned int *); + + int (*_bfd_coff_reloc16_estimate) + (bfd *, asection *, arelent *, unsigned int, + struct bfd_link_info *); + + enum coff_symbol_classification (*_bfd_coff_classify_symbol) + (bfd *, struct internal_syment *); + + bfd_boolean (*_bfd_coff_compute_section_file_positions) + (bfd *); + + bfd_boolean (*_bfd_coff_start_final_link) + (bfd *, struct bfd_link_info *); + + bfd_boolean (*_bfd_coff_relocate_section) + (bfd *, struct bfd_link_info *, bfd *, asection *, bfd_byte *, + struct internal_reloc *, struct internal_syment *, asection **); + + reloc_howto_type *(*_bfd_coff_rtype_to_howto) + (bfd *, asection *, struct internal_reloc *, + struct coff_link_hash_entry *, struct internal_syment *, + bfd_vma *); + + bfd_boolean (*_bfd_coff_adjust_symndx) + (bfd *, struct bfd_link_info *, bfd *, asection *, + struct internal_reloc *, bfd_boolean *); + + bfd_boolean (*_bfd_coff_link_add_one_symbol) + (struct bfd_link_info *, bfd *, const char *, flagword, + asection *, bfd_vma, const char *, bfd_boolean, bfd_boolean, + struct bfd_link_hash_entry **); + + bfd_boolean (*_bfd_coff_link_output_has_begun) + (bfd *, struct coff_final_link_info *); + + bfd_boolean (*_bfd_coff_final_link_postscript) + (bfd *, struct coff_final_link_info *); + + bfd_boolean (*_bfd_coff_print_pdata) + (bfd *, void *); + + } bfd_coff_backend_data; + + #define coff_backend_info(abfd) \ + ((bfd_coff_backend_data *) (abfd)->xvec->backend_data) + + #define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \ + ((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i)) + + #define bfd_coff_swap_sym_in(a,e,i) \ + ((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i)) + + #define bfd_coff_swap_lineno_in(a,e,i) \ + ((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i)) + + #define bfd_coff_swap_reloc_out(abfd, i, o) \ + ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o)) + + #define bfd_coff_swap_lineno_out(abfd, i, o) \ + ((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o)) + + #define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \ + ((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o)) + + #define bfd_coff_swap_sym_out(abfd, i,o) \ + ((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o)) + + #define bfd_coff_swap_scnhdr_out(abfd, i,o) \ + ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o)) + + #define bfd_coff_swap_filehdr_out(abfd, i,o) \ + ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o)) + + #define bfd_coff_swap_aouthdr_out(abfd, i,o) \ + ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o)) + + #define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz) + #define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz) + #define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz) + #define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz) + #define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz) + #define bfd_coff_relsz(abfd) (coff_backend_info (abfd)->_bfd_relsz) + #define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz) + #define bfd_coff_filnmlen(abfd) (coff_backend_info (abfd)->_bfd_filnmlen) + #define bfd_coff_long_filenames(abfd) \ + (coff_backend_info (abfd)->_bfd_coff_long_filenames) + #define bfd_coff_long_section_names(abfd) \ + (coff_backend_info (abfd)->_bfd_coff_long_section_names) + #define bfd_coff_set_long_section_names(abfd, enable) \ + ((coff_backend_info (abfd)->_bfd_coff_set_long_section_names) (abfd, enable)) + #define bfd_coff_default_section_alignment_power(abfd) \ + (coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power) + #define bfd_coff_swap_filehdr_in(abfd, i,o) \ + ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o)) + + #define bfd_coff_swap_aouthdr_in(abfd, i,o) \ + ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o)) + + #define bfd_coff_swap_scnhdr_in(abfd, i,o) \ + ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o)) + + #define bfd_coff_swap_reloc_in(abfd, i, o) \ + ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o)) + + #define bfd_coff_bad_format_hook(abfd, filehdr) \ + ((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr)) + + #define bfd_coff_set_arch_mach_hook(abfd, filehdr)\ + ((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr)) + #define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\ + ((coff_backend_info (abfd)->_bfd_coff_mkobject_hook)\ + (abfd, filehdr, aouthdr)) + + #define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name, section, flags_ptr)\ + ((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook)\ + (abfd, scnhdr, name, section, flags_ptr)) + + #define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\ + ((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr)) + + #define bfd_coff_slurp_symbol_table(abfd)\ + ((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd)) + + #define bfd_coff_symname_in_debug(abfd, sym)\ + ((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym)) + + #define bfd_coff_force_symnames_in_strings(abfd)\ + (coff_backend_info (abfd)->_bfd_coff_force_symnames_in_strings) + + #define bfd_coff_debug_string_prefix_length(abfd)\ + (coff_backend_info (abfd)->_bfd_coff_debug_string_prefix_length) + + #define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\ + ((coff_backend_info (abfd)->_bfd_coff_print_aux)\ + (abfd, file, base, symbol, aux, indaux)) + + #define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order,\ + reloc, data, src_ptr, dst_ptr)\ + ((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\ + (abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr)) + + #define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\ + ((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\ + (abfd, section, reloc, shrink, link_info)) + + #define bfd_coff_classify_symbol(abfd, sym)\ + ((coff_backend_info (abfd)->_bfd_coff_classify_symbol)\ + (abfd, sym)) + + #define bfd_coff_compute_section_file_positions(abfd)\ + ((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\ + (abfd)) + + #define bfd_coff_start_final_link(obfd, info)\ + ((coff_backend_info (obfd)->_bfd_coff_start_final_link)\ + (obfd, info)) + #define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\ + ((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\ + (obfd, info, ibfd, o, con, rel, isyms, secs)) + #define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\ + ((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\ + (abfd, sec, rel, h, sym, addendp)) + #define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\ + ((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\ + (obfd, info, ibfd, sec, rel, adjustedp)) + #define bfd_coff_link_add_one_symbol(info, abfd, name, flags, section,\ + value, string, cp, coll, hashp)\ + ((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\ + (info, abfd, name, flags, section, value, string, cp, coll, hashp)) + + #define bfd_coff_link_output_has_begun(a,p) \ + ((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a, p)) + #define bfd_coff_final_link_postscript(a,p) \ + ((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a, p)) + + #define bfd_coff_have_print_pdata(a) \ + (coff_backend_info (a)->_bfd_coff_print_pdata) + #define bfd_coff_print_pdata(a,p) \ + ((coff_backend_info (a)->_bfd_coff_print_pdata) (a, p)) + + /* Macro: Returns true if the bfd is a PE executable as opposed to a + PE object file. */ + #define bfd_pei_p(abfd) \ + (CONST_STRNEQ ((abfd)->xvec->name, "pei-")) + +3.3.2.8 Writing relocations +........................... + +To write relocations, the back end steps though the canonical relocation +table and create an 'internal_reloc'. The symbol index to use is +removed from the 'offset' field in the symbol table supplied. The +address comes directly from the sum of the section base address and the +relocation offset; the type is dug directly from the howto field. Then +the 'internal_reloc' is swapped into the shape of an 'external_reloc' +and written out to disk. + +3.3.2.9 Reading linenumbers +........................... + +Creating the linenumber table is done by reading in the entire coff +linenumber table, and creating another table for internal use. + + A coff linenumber table is structured so that each function is marked +as having a line number of 0. Each line within the function is an +offset from the first line in the function. The base of the line number +information for the table is stored in the symbol associated with the +function. + + Note: The PE format uses line number 0 for a flag indicating a new +source file. + + The information is copied from the external to the internal table, +and each symbol which marks a function is marked by pointing its... + + How does this work ? + +3.3.2.10 Reading relocations +............................ + +Coff relocations are easily transformed into the internal BFD form +('arelent'). + + Reading a coff relocation table is done in the following stages: + + * Read the entire coff relocation table into memory. + + * Process each relocation in turn; first swap it from the external to + the internal form. + + * Turn the symbol referenced in the relocation's symbol index into a + pointer into the canonical symbol table. This table is the same as + the one returned by a call to 'bfd_canonicalize_symtab'. The back + end will call that routine and save the result if a + canonicalization hasn't been done. + + * The reloc index is turned into a pointer to a howto structure, in a + back end specific way. For instance, the 386 and 960 use the + 'r_type' to directly produce an index into a howto table vector; + the 88k subtracts a number from the 'r_type' field and creates an + addend field. + + +File: bfd.info, Node: elf, Next: mmo, Prev: coff, Up: BFD back ends + +3.4 ELF backends +================ + +BFD support for ELF formats is being worked on. Currently, the best +supported back ends are for sparc and i386 (running svr4 or Solaris 2). + + Documentation of the internals of the support code still needs to be +written. The code is changing quickly enough that we haven't bothered +yet. + + +File: bfd.info, Node: mmo, Prev: elf, Up: BFD back ends + +3.5 mmo backend +=============== + +The mmo object format is used exclusively together with Professor Donald +E. Knuth's educational 64-bit processor MMIX. The simulator 'mmix' which +is available at + +understands this format. That package also includes a combined +assembler and linker called 'mmixal'. The mmo format has no advantages +feature-wise compared to e.g. ELF. It is a simple non-relocatable +object format with no support for archives or debugging information, +except for symbol value information and line numbers (which is not yet +implemented in BFD). See + for more +information about MMIX. The ELF format is used for intermediate object +files in the BFD implementation. + +* Menu: + +* File layout:: +* Symbol-table:: +* mmo section mapping:: + + +File: bfd.info, Node: File layout, Next: Symbol-table, Prev: mmo, Up: mmo + +3.5.1 File layout +----------------- + +The mmo file contents is not partitioned into named sections as with +e.g. ELF. Memory areas is formed by specifying the location of the data +that follows. Only the memory area '0x0000...00' to '0x01ff...ff' is +executable, so it is used for code (and constants) and the area +'0x2000...00' to '0x20ff...ff' is used for writable data. *Note mmo +section mapping::. + + There is provision for specifying "special data" of 65536 different +types. We use type 80 (decimal), arbitrarily chosen the same as the ELF +'e_machine' number for MMIX, filling it with section information +normally found in ELF objects. *Note mmo section mapping::. + + Contents is entered as 32-bit words, xor:ed over previous contents, +always zero-initialized. A word that starts with the byte '0x98' forms +a command called a 'lopcode', where the next byte distinguished between +the thirteen lopcodes. The two remaining bytes, called the 'Y' and 'Z' +fields, or the 'YZ' field (a 16-bit big-endian number), are used for +various purposes different for each lopcode. As documented in +, the +lopcodes are: + +'lop_quote' + 0x98000001. The next word is contents, regardless of whether it + starts with 0x98 or not. + +'lop_loc' + 0x9801YYZZ, where 'Z' is 1 or 2. This is a location directive, + setting the location for the next data to the next 32-bit word (for + Z = 1) or 64-bit word (for Z = 2), plus Y * 2^56. Normally 'Y' is + 0 for the text segment and 2 for the data segment. + +'lop_skip' + 0x9802YYZZ. Increase the current location by 'YZ' bytes. + +'lop_fixo' + 0x9803YYZZ, where 'Z' is 1 or 2. Store the current location as 64 + bits into the location pointed to by the next 32-bit (Z = 1) or + 64-bit (Z = 2) word, plus Y * 2^56. + +'lop_fixr' + 0x9804YYZZ. 'YZ' is stored into the current location plus 2 - 4 * + YZ. + +'lop_fixrx' + 0x980500ZZ. 'Z' is 16 or 24. A value 'L' derived from the + following 32-bit word are used in a manner similar to 'YZ' in + lop_fixr: it is xor:ed into the current location minus 4 * L. The + first byte of the word is 0 or 1. If it is 1, then L = (LOWEST 24 + BITS OF WORD) - 2^Z, if 0, then L = (LOWEST 24 BITS OF WORD). + +'lop_file' + 0x9806YYZZ. 'Y' is the file number, 'Z' is count of 32-bit words. + Set the file number to 'Y' and the line counter to 0. The next Z * + 4 bytes contain the file name, padded with zeros if the count is + not a multiple of four. The same 'Y' may occur multiple times, but + 'Z' must be 0 for all but the first occurrence. + +'lop_line' + 0x9807YYZZ. 'YZ' is the line number. Together with lop_file, it + forms the source location for the next 32-bit word. Note that for + each non-lopcode 32-bit word, line numbers are assumed incremented + by one. + +'lop_spec' + 0x9808YYZZ. 'YZ' is the type number. Data until the next lopcode + other than lop_quote forms special data of type 'YZ'. *Note mmo + section mapping::. + + Other types than 80, (or type 80 with a content that does not + parse) is stored in sections named '.MMIX.spec_data.N' where N is + the 'YZ'-type. The flags for such a sections say not to allocate + or load the data. The vma is 0. Contents of multiple occurrences + of special data N is concatenated to the data of the previous + lop_spec Ns. The location in data or code at which the lop_spec + occurred is lost. + +'lop_pre' + 0x980901ZZ. The first lopcode in a file. The 'Z' field forms the + length of header information in 32-bit words, where the first word + tells the time in seconds since '00:00:00 GMT Jan 1 1970'. + +'lop_post' + 0x980a00ZZ. Z > 32. This lopcode follows after all + content-generating lopcodes in a program. The 'Z' field denotes + the value of 'rG' at the beginning of the program. The following + 256 - Z big-endian 64-bit words are loaded into global registers + '$G' ... '$255'. + +'lop_stab' + 0x980b0000. The next-to-last lopcode in a program. Must follow + immediately after the lop_post lopcode and its data. After this + lopcode follows all symbols in a compressed format (*note + Symbol-table::). + +'lop_end' + 0x980cYYZZ. The last lopcode in a program. It must follow the + lop_stab lopcode and its data. The 'YZ' field contains the number + of 32-bit words of symbol table information after the preceding + lop_stab lopcode. + + Note that the lopcode "fixups"; 'lop_fixr', 'lop_fixrx' and +'lop_fixo' are not generated by BFD, but are handled. They are +generated by 'mmixal'. + + This trivial one-label, one-instruction file: + + :Main TRAP 1,2,3 + + can be represented this way in mmo: + + 0x98090101 - lop_pre, one 32-bit word with timestamp. + + 0x98010002 - lop_loc, text segment, using a 64-bit address. + Note that mmixal does not emit this for the file above. + 0x00000000 - Address, high 32 bits. + 0x00000000 - Address, low 32 bits. + 0x98060002 - lop_file, 2 32-bit words for file-name. + 0x74657374 - "test" + 0x2e730000 - ".s\0\0" + 0x98070001 - lop_line, line 1. + 0x00010203 - TRAP 1,2,3 + 0x980a00ff - lop_post, setting $255 to 0. + 0x00000000 + 0x00000000 + 0x980b0000 - lop_stab for ":Main" = 0, serial 1. + 0x203a4040 *Note Symbol-table::. + 0x10404020 + 0x4d206120 + 0x69016e00 + 0x81000000 + 0x980c0005 - lop_end; symbol table contained five 32-bit words. + + +File: bfd.info, Node: Symbol-table, Next: mmo section mapping, Prev: File layout, Up: mmo + +3.5.2 Symbol table format +------------------------- + +From mmixal.w (or really, the generated mmixal.tex) in +): +"Symbols are stored and retrieved by means of a 'ternary search trie', +following ideas of Bentley and Sedgewick. (See ACM-SIAM Symp. on +Discrete Algorithms '8' (1997), 360-369; R.Sedgewick, 'Algorithms in C' +(Reading, Mass. Addison-Wesley, 1998), '15.4'.) Each trie node stores a +character, and there are branches to subtries for the cases where a +given character is less than, equal to, or greater than the character in +the trie. There also is a pointer to a symbol table entry if a symbol +ends at the current node." + + So it's a tree encoded as a stream of bytes. The stream of bytes +acts on a single virtual global symbol, adding and removing characters +and signalling complete symbol points. Here, we read the stream and +create symbols at the completion points. + + First, there's a control byte 'm'. If any of the listed bits in 'm' +is nonzero, we execute what stands at the right, in the listed order: + + (MMO3_LEFT) + 0x40 - Traverse left trie. + (Read a new command byte and recurse.) + + (MMO3_SYMBITS) + 0x2f - Read the next byte as a character and store it in the + current character position; increment character position. + Test the bits of m: + + (MMO3_WCHAR) + 0x80 - The character is 16-bit (so read another byte, + merge into current character. + + (MMO3_TYPEBITS) + 0xf - We have a complete symbol; parse the type, value + and serial number and do what should be done + with a symbol. The type and length information + is in j = (m & 0xf). + + (MMO3_REGQUAL_BITS) + j == 0xf: A register variable. The following + byte tells which register. + j <= 8: An absolute symbol. Read j bytes as the + big-endian number the symbol equals. + A j = 2 with two zero bytes denotes an + unknown symbol. + j > 8: As with j <= 8, but add (0x20 << 56) + to the value in the following j - 8 + bytes. + + Then comes the serial number, as a variant of + uleb128, but better named ubeb128: + Read bytes and shift the previous value left 7 + (multiply by 128). Add in the new byte, repeat + until a byte has bit 7 set. The serial number + is the computed value minus 128. + + (MMO3_MIDDLE) + 0x20 - Traverse middle trie. (Read a new command byte + and recurse.) Decrement character position. + + (MMO3_RIGHT) + 0x10 - Traverse right trie. (Read a new command byte and + recurse.) + + Let's look again at the 'lop_stab' for the trivial file (*note File +layout::). + + 0x980b0000 - lop_stab for ":Main" = 0, serial 1. + 0x203a4040 + 0x10404020 + 0x4d206120 + 0x69016e00 + 0x81000000 + + This forms the trivial trie (note that the path between ":" and "M" +is redundant): + + 203a ":" + 40 / + 40 / + 10 \ + 40 / + 40 / + 204d "M" + 2061 "a" + 2069 "i" + 016e "n" is the last character in a full symbol, and + with a value represented in one byte. + 00 The value is 0. + 81 The serial number is 1. + + +File: bfd.info, Node: mmo section mapping, Prev: Symbol-table, Up: mmo + +3.5.3 mmo section mapping +------------------------- + +The implementation in BFD uses special data type 80 (decimal) to +encapsulate and describe named sections, containing e.g. debug +information. If needed, any datum in the encapsulation will be quoted +using lop_quote. First comes a 32-bit word holding the number of 32-bit +words containing the zero-terminated zero-padded segment name. After +the name there's a 32-bit word holding flags describing the section +type. Then comes a 64-bit big-endian word with the section length (in +bytes), then another with the section start address. Depending on the +type of section, the contents might follow, zero-padded to 32-bit +boundary. For a loadable section (such as data or code), the contents +might follow at some later point, not necessarily immediately, as a +lop_loc with the same start address as in the section description, +followed by the contents. This in effect forms a descriptor that must +be emitted before the actual contents. Sections described this way must +not overlap. + + For areas that don't have such descriptors, synthetic sections are +formed by BFD. Consecutive contents in the two memory areas +'0x0000...00' to '0x01ff...ff' and '0x2000...00' to '0x20ff...ff' are +entered in sections named '.text' and '.data' respectively. If an area +is not otherwise described, but would together with a neighboring lower +area be less than '0x40000000' bytes long, it is joined with the lower +area and the gap is zero-filled. For other cases, a new section is +formed, named '.MMIX.sec.N'. Here, N is a number, a running count +through the mmo file, starting at 0. + + A loadable section specified as: + + .section secname,"ax" + TETRA 1,2,3,4,-1,-2009 + BYTE 80 + + and linked to address '0x4', is represented by the sequence: + + 0x98080050 - lop_spec 80 + 0x00000002 - two 32-bit words for the section name + 0x7365636e - "secn" + 0x616d6500 - "ame\0" + 0x00000033 - flags CODE, READONLY, LOAD, ALLOC + 0x00000000 - high 32 bits of section length + 0x0000001c - section length is 28 bytes; 6 * 4 + 1 + alignment to 32 bits + 0x00000000 - high 32 bits of section address + 0x00000004 - section address is 4 + 0x98010002 - 64 bits with address of following data + 0x00000000 - high 32 bits of address + 0x00000004 - low 32 bits: data starts at address 4 + 0x00000001 - 1 + 0x00000002 - 2 + 0x00000003 - 3 + 0x00000004 - 4 + 0xffffffff - -1 + 0xfffff827 - -2009 + 0x50000000 - 80 as a byte, padded with zeros. + + Note that the lop_spec wrapping does not include the section +contents. Compare this to a non-loaded section specified as: + + .section thirdsec + TETRA 200001,100002 + BYTE 38,40 + + This, when linked to address '0x200000000000001c', is represented by: + + 0x98080050 - lop_spec 80 + 0x00000002 - two 32-bit words for the section name + 0x7365636e - "thir" + 0x616d6500 - "dsec" + 0x00000010 - flag READONLY + 0x00000000 - high 32 bits of section length + 0x0000000c - section length is 12 bytes; 2 * 4 + 2 + alignment to 32 bits + 0x20000000 - high 32 bits of address + 0x0000001c - low 32 bits of address 0x200000000000001c + 0x00030d41 - 200001 + 0x000186a2 - 100002 + 0x26280000 - 38, 40 as bytes, padded with zeros + + For the latter example, the section contents must not be loaded in +memory, and is therefore specified as part of the special data. The +address is usually unimportant but might provide information for e.g. +the DWARF 2 debugging format. + + +File: bfd.info, Node: GNU Free Documentation License, Next: BFD Index, Prev: BFD back ends, Up: Top + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: bfd.info, Node: BFD Index, Prev: GNU Free Documentation License, Up: Top + +BFD Index +********* + +[index] +* Menu: + +* _bfd_final_link_relocate: Relocating the section contents. + (line 22) +* _bfd_generic_link_add_archive_symbols: Adding symbols from an archive. + (line 15) +* _bfd_generic_link_add_one_symbol: Adding symbols from an object file. + (line 19) +* _bfd_generic_make_empty_symbol: symbol handling functions. + (line 91) +* _bfd_link_add_symbols in target vector: Adding Symbols to the Hash Table. + (line 6) +* _bfd_link_final_link in target vector: Performing the Final Link. + (line 6) +* _bfd_link_hash_table_create in target vector: Creating a Linker Hash Table. + (line 6) +* _bfd_relocate_contents: Relocating the section contents. + (line 22) +* aout_SIZE_machine_type: aout. (line 145) +* aout_SIZE_mkobject: aout. (line 137) +* aout_SIZE_new_section_hook: aout. (line 175) +* aout_SIZE_set_arch_mach: aout. (line 162) +* aout_SIZE_some_aout_object_p: aout. (line 123) +* aout_SIZE_swap_exec_header_in: aout. (line 99) +* aout_SIZE_swap_exec_header_out: aout. (line 111) +* arelent_chain: typedef arelent. (line 336) +* BFD: Overview. (line 6) +* BFD canonical format: Canonical format. (line 11) +* bfd_alloc: Opening and Closing. + (line 238) +* bfd_alloc2: Opening and Closing. + (line 247) +* bfd_alt_mach_code: Miscellaneous. (line 302) +* bfd_arch_bits_per_address: Architectures. (line 589) +* bfd_arch_bits_per_byte: Architectures. (line 581) +* bfd_arch_default_fill: Architectures. (line 670) +* bfd_arch_get_compatible: Architectures. (line 524) +* bfd_arch_list: Architectures. (line 515) +* bfd_arch_mach_octets_per_byte: Architectures. (line 658) +* BFD_ARELOC_BFIN_ADD: howto manager. (line 1005) +* BFD_ARELOC_BFIN_ADDR: howto manager. (line 1039) +* BFD_ARELOC_BFIN_AND: howto manager. (line 1019) +* BFD_ARELOC_BFIN_COMP: howto manager. (line 1033) +* BFD_ARELOC_BFIN_CONST: howto manager. (line 1003) +* BFD_ARELOC_BFIN_DIV: howto manager. (line 1011) +* BFD_ARELOC_BFIN_HWPAGE: howto manager. (line 1037) +* BFD_ARELOC_BFIN_LAND: howto manager. (line 1025) +* BFD_ARELOC_BFIN_LEN: howto manager. (line 1029) +* BFD_ARELOC_BFIN_LOR: howto manager. (line 1027) +* BFD_ARELOC_BFIN_LSHIFT: howto manager. (line 1015) +* BFD_ARELOC_BFIN_MOD: howto manager. (line 1013) +* BFD_ARELOC_BFIN_MULT: howto manager. (line 1009) +* BFD_ARELOC_BFIN_NEG: howto manager. (line 1031) +* BFD_ARELOC_BFIN_OR: howto manager. (line 1021) +* BFD_ARELOC_BFIN_PAGE: howto manager. (line 1035) +* BFD_ARELOC_BFIN_PUSH: howto manager. (line 1001) +* BFD_ARELOC_BFIN_RSHIFT: howto manager. (line 1017) +* BFD_ARELOC_BFIN_SUB: howto manager. (line 1007) +* BFD_ARELOC_BFIN_XOR: howto manager. (line 1023) +* bfd_cache_close: File Caching. (line 25) +* bfd_cache_close_all: File Caching. (line 38) +* bfd_cache_init: File Caching. (line 17) +* bfd_calc_gnu_debuglink_crc32: Opening and Closing. + (line 274) +* bfd_canonicalize_reloc: Miscellaneous. (line 18) +* bfd_canonicalize_symtab: symbol handling functions. + (line 49) +* bfd_check_format: Formats. (line 20) +* bfd_check_format_matches: Formats. (line 51) +* bfd_check_overflow: typedef arelent. (line 348) +* bfd_close: Opening and Closing. + (line 160) +* bfd_close_all_done: Opening and Closing. + (line 178) +* bfd_coff_backend_data: coff. (line 304) +* bfd_copy_private_bfd_data: Miscellaneous. (line 155) +* bfd_copy_private_header_data: Miscellaneous. (line 138) +* bfd_copy_private_section_data: section prototypes. (line 277) +* bfd_copy_private_symbol_data: symbol handling functions. + (line 139) +* bfd_core_file_failing_command: Core Files. (line 11) +* bfd_core_file_failing_signal: Core Files. (line 20) +* bfd_core_file_pid: Core Files. (line 29) +* bfd_create: Opening and Closing. + (line 197) +* bfd_create_gnu_debuglink_section: Opening and Closing. + (line 386) +* bfd_decode_symclass: symbol handling functions. + (line 110) +* bfd_default_arch_struct: Architectures. (line 536) +* bfd_default_compatible: Architectures. (line 598) +* bfd_default_reloc_type_lookup: howto manager. (line 2913) +* bfd_default_scan: Architectures. (line 607) +* bfd_default_set_arch_mach: Architectures. (line 554) +* bfd_demangle: Miscellaneous. (line 353) +* bfd_emul_get_commonpagesize: Miscellaneous. (line 333) +* bfd_emul_get_maxpagesize: Miscellaneous. (line 313) +* bfd_emul_set_commonpagesize: Miscellaneous. (line 344) +* bfd_emul_set_maxpagesize: Miscellaneous. (line 324) +* bfd_errmsg: Error reporting. (line 66) +* bfd_fdopenr: Opening and Closing. + (line 56) +* bfd_fill_in_gnu_debuglink_section: Opening and Closing. + (line 400) +* bfd_find_target: bfd_target. (line 475) +* bfd_find_version_for_sym: Writing the symbol table. + (line 80) +* bfd_follow_gnu_debugaltlink: Opening and Closing. + (line 366) +* bfd_follow_gnu_debuglink: Opening and Closing. + (line 345) +* bfd_fopen: Opening and Closing. + (line 11) +* bfd_format_string: Formats. (line 78) +* bfd_generic_define_common_symbol: Writing the symbol table. + (line 67) +* bfd_generic_discard_group: section prototypes. (line 302) +* bfd_generic_gc_sections: howto manager. (line 2944) +* bfd_generic_get_relocated_section_contents: howto manager. (line 2974) +* bfd_generic_is_group_section: section prototypes. (line 294) +* bfd_generic_lookup_section_flags: howto manager. (line 2954) +* bfd_generic_merge_sections: howto manager. (line 2964) +* bfd_generic_relax_section: howto manager. (line 2931) +* bfd_get_alt_debug_link_info: Opening and Closing. + (line 299) +* bfd_get_arch: Architectures. (line 565) +* bfd_get_arch_info: Architectures. (line 617) +* bfd_get_arch_size: Miscellaneous. (line 61) +* bfd_get_assert_handler: Error reporting. (line 149) +* bfd_get_debug_link_info: Opening and Closing. + (line 288) +* bfd_get_error: Error reporting. (line 48) +* bfd_get_error_handler: Error reporting. (line 117) +* bfd_get_gp_size: Miscellaneous. (line 102) +* bfd_get_linker_section: section prototypes. (line 35) +* bfd_get_mach: Architectures. (line 573) +* bfd_get_mtime: Miscellaneous. (line 403) +* bfd_get_next_mapent: Archives. (line 57) +* bfd_get_next_section_by_name: section prototypes. (line 25) +* bfd_get_reloc_code_name: howto manager. (line 2922) +* bfd_get_reloc_size: typedef arelent. (line 327) +* bfd_get_reloc_upper_bound: Miscellaneous. (line 8) +* bfd_get_section_by_name: section prototypes. (line 16) +* bfd_get_section_by_name_if: section prototypes. (line 44) +* bfd_get_section_contents: section prototypes. (line 250) +* bfd_get_sign_extend_vma: Miscellaneous. (line 74) +* bfd_get_size: Miscellaneous. (line 412) +* bfd_get_size <1>: Internal. (line 24) +* bfd_get_symtab_upper_bound: symbol handling functions. + (line 5) +* bfd_get_target_info: bfd_target. (line 491) +* bfd_get_unique_section_name: section prototypes. (line 63) +* bfd_hash_allocate: Creating and Freeing a Hash Table. + (line 17) +* bfd_hash_lookup: Looking Up or Entering a String. + (line 6) +* bfd_hash_newfunc: Creating and Freeing a Hash Table. + (line 12) +* bfd_hash_set_default_size: Creating and Freeing a Hash Table. + (line 25) +* bfd_hash_table_free: Creating and Freeing a Hash Table. + (line 21) +* bfd_hash_table_init: Creating and Freeing a Hash Table. + (line 6) +* bfd_hash_table_init_n: Creating and Freeing a Hash Table. + (line 6) +* bfd_hash_traverse: Traversing a Hash Table. + (line 6) +* bfd_hide_sym_by_version: Writing the symbol table. + (line 92) +* bfd_h_put_size: Internal. (line 96) +* bfd_init: Initialization. (line 10) +* bfd_install_relocation: typedef arelent. (line 389) +* bfd_is_local_label: symbol handling functions. + (line 16) +* bfd_is_local_label_name: symbol handling functions. + (line 25) +* bfd_is_target_special_symbol: symbol handling functions. + (line 37) +* bfd_is_undefined_symclass: symbol handling functions. + (line 119) +* bfd_link_split_section: Writing the symbol table. + (line 43) +* bfd_log2: Internal. (line 164) +* bfd_lookup_arch: Architectures. (line 625) +* bfd_make_debug_symbol: symbol handling functions. + (line 101) +* bfd_make_empty_symbol: symbol handling functions. + (line 77) +* bfd_make_readable: Opening and Closing. + (line 224) +* bfd_make_section: section prototypes. (line 141) +* bfd_make_section_anyway: section prototypes. (line 113) +* bfd_make_section_anyway_with_flags: section prototypes. (line 95) +* bfd_make_section_old_way: section prototypes. (line 75) +* bfd_make_section_with_flags: section prototypes. (line 129) +* bfd_make_writable: Opening and Closing. + (line 210) +* bfd_malloc_and_get_section: section prototypes. (line 267) +* bfd_map_over_sections: section prototypes. (line 176) +* bfd_merge_private_bfd_data: Miscellaneous. (line 170) +* bfd_mmap: Miscellaneous. (line 440) +* bfd_octets_per_byte: Architectures. (line 648) +* bfd_openr: Opening and Closing. + (line 37) +* bfd_openr_iovec: Opening and Closing. + (line 94) +* bfd_openr_next_archived_file: Archives. (line 83) +* bfd_openstreamr: Opening and Closing. + (line 82) +* bfd_openw: Opening and Closing. + (line 145) +* bfd_open_file: File Caching. (line 51) +* bfd_perform_relocation: typedef arelent. (line 364) +* bfd_perror: Error reporting. (line 75) +* bfd_printable_arch_mach: Architectures. (line 636) +* bfd_printable_name: Architectures. (line 496) +* bfd_print_symbol_vandf: symbol handling functions. + (line 69) +* bfd_put_size: Internal. (line 21) +* BFD_RELOC_12_PCREL: howto manager. (line 37) +* BFD_RELOC_14: howto manager. (line 30) +* BFD_RELOC_16: howto manager. (line 29) +* BFD_RELOC_16C_ABS20: howto manager. (line 2038) +* BFD_RELOC_16C_ABS20_C: howto manager. (line 2039) +* BFD_RELOC_16C_ABS24: howto manager. (line 2040) +* BFD_RELOC_16C_ABS24_C: howto manager. (line 2041) +* BFD_RELOC_16C_DISP04: howto manager. (line 2018) +* BFD_RELOC_16C_DISP04_C: howto manager. (line 2019) +* BFD_RELOC_16C_DISP08: howto manager. (line 2020) +* BFD_RELOC_16C_DISP08_C: howto manager. (line 2021) +* BFD_RELOC_16C_DISP16: howto manager. (line 2022) +* BFD_RELOC_16C_DISP16_C: howto manager. (line 2023) +* BFD_RELOC_16C_DISP24: howto manager. (line 2024) +* BFD_RELOC_16C_DISP24a: howto manager. (line 2026) +* BFD_RELOC_16C_DISP24a_C: howto manager. (line 2027) +* BFD_RELOC_16C_DISP24_C: howto manager. (line 2025) +* BFD_RELOC_16C_IMM04: howto manager. (line 2042) +* BFD_RELOC_16C_IMM04_C: howto manager. (line 2043) +* BFD_RELOC_16C_IMM16: howto manager. (line 2044) +* BFD_RELOC_16C_IMM16_C: howto manager. (line 2045) +* BFD_RELOC_16C_IMM20: howto manager. (line 2046) +* BFD_RELOC_16C_IMM20_C: howto manager. (line 2047) +* BFD_RELOC_16C_IMM24: howto manager. (line 2048) +* BFD_RELOC_16C_IMM24_C: howto manager. (line 2049) +* BFD_RELOC_16C_IMM32: howto manager. (line 2050) +* BFD_RELOC_16C_IMM32_C: howto manager. (line 2051) +* BFD_RELOC_16C_NUM08: howto manager. (line 2012) +* BFD_RELOC_16C_NUM08_C: howto manager. (line 2013) +* BFD_RELOC_16C_NUM16: howto manager. (line 2014) +* BFD_RELOC_16C_NUM16_C: howto manager. (line 2015) +* BFD_RELOC_16C_NUM32: howto manager. (line 2016) +* BFD_RELOC_16C_NUM32_C: howto manager. (line 2017) +* BFD_RELOC_16C_REG04: howto manager. (line 2028) +* BFD_RELOC_16C_REG04a: howto manager. (line 2030) +* BFD_RELOC_16C_REG04a_C: howto manager. (line 2031) +* BFD_RELOC_16C_REG04_C: howto manager. (line 2029) +* BFD_RELOC_16C_REG14: howto manager. (line 2032) +* BFD_RELOC_16C_REG14_C: howto manager. (line 2033) +* BFD_RELOC_16C_REG16: howto manager. (line 2034) +* BFD_RELOC_16C_REG16_C: howto manager. (line 2035) +* BFD_RELOC_16C_REG20: howto manager. (line 2036) +* BFD_RELOC_16C_REG20_C: howto manager. (line 2037) +* BFD_RELOC_16_BASEREL: howto manager. (line 92) +* BFD_RELOC_16_GOTOFF: howto manager. (line 51) +* BFD_RELOC_16_GOT_PCREL: howto manager. (line 48) +* BFD_RELOC_16_PCREL: howto manager. (line 36) +* BFD_RELOC_16_PCREL_S2: howto manager. (line 102) +* BFD_RELOC_16_PLTOFF: howto manager. (line 63) +* BFD_RELOC_16_PLT_PCREL: howto manager. (line 59) +* BFD_RELOC_23_PCREL_S2: howto manager. (line 103) +* BFD_RELOC_24: howto manager. (line 28) +* BFD_RELOC_24_PCREL: howto manager. (line 35) +* BFD_RELOC_24_PLT_PCREL: howto manager. (line 58) +* BFD_RELOC_26: howto manager. (line 27) +* BFD_RELOC_32: howto manager. (line 26) +* BFD_RELOC_32_BASEREL: howto manager. (line 91) +* BFD_RELOC_32_GOTOFF: howto manager. (line 50) +* BFD_RELOC_32_GOT_PCREL: howto manager. (line 47) +* BFD_RELOC_32_PCREL: howto manager. (line 34) +* BFD_RELOC_32_PCREL_S2: howto manager. (line 101) +* BFD_RELOC_32_PLTOFF: howto manager. (line 62) +* BFD_RELOC_32_PLT_PCREL: howto manager. (line 57) +* BFD_RELOC_32_SECREL: howto manager. (line 45) +* BFD_RELOC_386_COPY: howto manager. (line 510) +* BFD_RELOC_386_GLOB_DAT: howto manager. (line 511) +* BFD_RELOC_386_GOT32: howto manager. (line 508) +* BFD_RELOC_386_GOTOFF: howto manager. (line 514) +* BFD_RELOC_386_GOTPC: howto manager. (line 515) +* BFD_RELOC_386_IRELATIVE: howto manager. (line 531) +* BFD_RELOC_386_JUMP_SLOT: howto manager. (line 512) +* BFD_RELOC_386_PLT32: howto manager. (line 509) +* BFD_RELOC_386_RELATIVE: howto manager. (line 513) +* BFD_RELOC_386_TLS_DESC: howto manager. (line 530) +* BFD_RELOC_386_TLS_DESC_CALL: howto manager. (line 529) +* BFD_RELOC_386_TLS_DTPMOD32: howto manager. (line 525) +* BFD_RELOC_386_TLS_DTPOFF32: howto manager. (line 526) +* BFD_RELOC_386_TLS_GD: howto manager. (line 520) +* BFD_RELOC_386_TLS_GOTDESC: howto manager. (line 528) +* BFD_RELOC_386_TLS_GOTIE: howto manager. (line 518) +* BFD_RELOC_386_TLS_IE: howto manager. (line 517) +* BFD_RELOC_386_TLS_IE_32: howto manager. (line 523) +* BFD_RELOC_386_TLS_LDM: howto manager. (line 521) +* BFD_RELOC_386_TLS_LDO_32: howto manager. (line 522) +* BFD_RELOC_386_TLS_LE: howto manager. (line 519) +* BFD_RELOC_386_TLS_LE_32: howto manager. (line 524) +* BFD_RELOC_386_TLS_TPOFF: howto manager. (line 516) +* BFD_RELOC_386_TLS_TPOFF32: howto manager. (line 527) +* BFD_RELOC_390_12: howto manager. (line 1702) +* BFD_RELOC_390_20: howto manager. (line 1783) +* BFD_RELOC_390_COPY: howto manager. (line 1708) +* BFD_RELOC_390_GLOB_DAT: howto manager. (line 1710) +* BFD_RELOC_390_GOT12: howto manager. (line 1704) +* BFD_RELOC_390_GOT16: howto manager. (line 1718) +* BFD_RELOC_390_GOT20: howto manager. (line 1784) +* BFD_RELOC_390_GOT64: howto manager. (line 1738) +* BFD_RELOC_390_GOTENT: howto manager. (line 1742) +* BFD_RELOC_390_GOTOFF64: howto manager. (line 1744) +* BFD_RELOC_390_GOTPC: howto manager. (line 1716) +* BFD_RELOC_390_GOTPCDBL: howto manager. (line 1736) +* BFD_RELOC_390_GOTPLT12: howto manager. (line 1746) +* BFD_RELOC_390_GOTPLT16: howto manager. (line 1748) +* BFD_RELOC_390_GOTPLT20: howto manager. (line 1785) +* BFD_RELOC_390_GOTPLT32: howto manager. (line 1750) +* BFD_RELOC_390_GOTPLT64: howto manager. (line 1752) +* BFD_RELOC_390_GOTPLTENT: howto manager. (line 1754) +* BFD_RELOC_390_IRELATIVE: howto manager. (line 1788) +* BFD_RELOC_390_JMP_SLOT: howto manager. (line 1712) +* BFD_RELOC_390_PC12DBL: howto manager. (line 1720) +* BFD_RELOC_390_PC16DBL: howto manager. (line 1724) +* BFD_RELOC_390_PC24DBL: howto manager. (line 1728) +* BFD_RELOC_390_PC32DBL: howto manager. (line 1732) +* BFD_RELOC_390_PLT12DBL: howto manager. (line 1722) +* BFD_RELOC_390_PLT16DBL: howto manager. (line 1726) +* BFD_RELOC_390_PLT24DBL: howto manager. (line 1730) +* BFD_RELOC_390_PLT32: howto manager. (line 1706) +* BFD_RELOC_390_PLT32DBL: howto manager. (line 1734) +* BFD_RELOC_390_PLT64: howto manager. (line 1740) +* BFD_RELOC_390_PLTOFF16: howto manager. (line 1756) +* BFD_RELOC_390_PLTOFF32: howto manager. (line 1758) +* BFD_RELOC_390_PLTOFF64: howto manager. (line 1760) +* BFD_RELOC_390_RELATIVE: howto manager. (line 1714) +* BFD_RELOC_390_TLS_DTPMOD: howto manager. (line 1779) +* BFD_RELOC_390_TLS_DTPOFF: howto manager. (line 1780) +* BFD_RELOC_390_TLS_GD32: howto manager. (line 1765) +* BFD_RELOC_390_TLS_GD64: howto manager. (line 1766) +* BFD_RELOC_390_TLS_GDCALL: howto manager. (line 1763) +* BFD_RELOC_390_TLS_GOTIE12: howto manager. (line 1767) +* BFD_RELOC_390_TLS_GOTIE20: howto manager. (line 1786) +* BFD_RELOC_390_TLS_GOTIE32: howto manager. (line 1768) +* BFD_RELOC_390_TLS_GOTIE64: howto manager. (line 1769) +* BFD_RELOC_390_TLS_IE32: howto manager. (line 1772) +* BFD_RELOC_390_TLS_IE64: howto manager. (line 1773) +* BFD_RELOC_390_TLS_IEENT: howto manager. (line 1774) +* BFD_RELOC_390_TLS_LDCALL: howto manager. (line 1764) +* BFD_RELOC_390_TLS_LDM32: howto manager. (line 1770) +* BFD_RELOC_390_TLS_LDM64: howto manager. (line 1771) +* BFD_RELOC_390_TLS_LDO32: howto manager. (line 1777) +* BFD_RELOC_390_TLS_LDO64: howto manager. (line 1778) +* BFD_RELOC_390_TLS_LE32: howto manager. (line 1775) +* BFD_RELOC_390_TLS_LE64: howto manager. (line 1776) +* BFD_RELOC_390_TLS_LOAD: howto manager. (line 1762) +* BFD_RELOC_390_TLS_TPOFF: howto manager. (line 1781) +* BFD_RELOC_64: howto manager. (line 25) +* BFD_RELOC_64_PCREL: howto manager. (line 33) +* BFD_RELOC_64_PLTOFF: howto manager. (line 61) +* BFD_RELOC_64_PLT_PCREL: howto manager. (line 56) +* BFD_RELOC_68K_GLOB_DAT: howto manager. (line 72) +* BFD_RELOC_68K_JMP_SLOT: howto manager. (line 73) +* BFD_RELOC_68K_RELATIVE: howto manager. (line 74) +* BFD_RELOC_68K_TLS_GD16: howto manager. (line 76) +* BFD_RELOC_68K_TLS_GD32: howto manager. (line 75) +* BFD_RELOC_68K_TLS_GD8: howto manager. (line 77) +* BFD_RELOC_68K_TLS_IE16: howto manager. (line 85) +* BFD_RELOC_68K_TLS_IE32: howto manager. (line 84) +* BFD_RELOC_68K_TLS_IE8: howto manager. (line 86) +* BFD_RELOC_68K_TLS_LDM16: howto manager. (line 79) +* BFD_RELOC_68K_TLS_LDM32: howto manager. (line 78) +* BFD_RELOC_68K_TLS_LDM8: howto manager. (line 80) +* BFD_RELOC_68K_TLS_LDO16: howto manager. (line 82) +* BFD_RELOC_68K_TLS_LDO32: howto manager. (line 81) +* BFD_RELOC_68K_TLS_LDO8: howto manager. (line 83) +* BFD_RELOC_68K_TLS_LE16: howto manager. (line 88) +* BFD_RELOC_68K_TLS_LE32: howto manager. (line 87) +* BFD_RELOC_68K_TLS_LE8: howto manager. (line 89) +* BFD_RELOC_8: howto manager. (line 31) +* BFD_RELOC_860_COPY: howto manager. (line 2153) +* BFD_RELOC_860_GLOB_DAT: howto manager. (line 2154) +* BFD_RELOC_860_HAGOT: howto manager. (line 2179) +* BFD_RELOC_860_HAGOTOFF: howto manager. (line 2180) +* BFD_RELOC_860_HAPC: howto manager. (line 2181) +* BFD_RELOC_860_HIGH: howto manager. (line 2182) +* BFD_RELOC_860_HIGHADJ: howto manager. (line 2178) +* BFD_RELOC_860_HIGOT: howto manager. (line 2183) +* BFD_RELOC_860_HIGOTOFF: howto manager. (line 2184) +* BFD_RELOC_860_JUMP_SLOT: howto manager. (line 2155) +* BFD_RELOC_860_LOGOT0: howto manager. (line 2167) +* BFD_RELOC_860_LOGOT1: howto manager. (line 2169) +* BFD_RELOC_860_LOGOTOFF0: howto manager. (line 2171) +* BFD_RELOC_860_LOGOTOFF1: howto manager. (line 2173) +* BFD_RELOC_860_LOGOTOFF2: howto manager. (line 2175) +* BFD_RELOC_860_LOGOTOFF3: howto manager. (line 2176) +* BFD_RELOC_860_LOPC: howto manager. (line 2177) +* BFD_RELOC_860_LOW0: howto manager. (line 2160) +* BFD_RELOC_860_LOW1: howto manager. (line 2162) +* BFD_RELOC_860_LOW2: howto manager. (line 2164) +* BFD_RELOC_860_LOW3: howto manager. (line 2166) +* BFD_RELOC_860_PC16: howto manager. (line 2159) +* BFD_RELOC_860_PC26: howto manager. (line 2157) +* BFD_RELOC_860_PLT26: howto manager. (line 2158) +* BFD_RELOC_860_RELATIVE: howto manager. (line 2156) +* BFD_RELOC_860_SPGOT0: howto manager. (line 2168) +* BFD_RELOC_860_SPGOT1: howto manager. (line 2170) +* BFD_RELOC_860_SPGOTOFF0: howto manager. (line 2172) +* BFD_RELOC_860_SPGOTOFF1: howto manager. (line 2174) +* BFD_RELOC_860_SPLIT0: howto manager. (line 2161) +* BFD_RELOC_860_SPLIT1: howto manager. (line 2163) +* BFD_RELOC_860_SPLIT2: howto manager. (line 2165) +* BFD_RELOC_8_BASEREL: howto manager. (line 96) +* BFD_RELOC_8_FFnn: howto manager. (line 99) +* BFD_RELOC_8_GOTOFF: howto manager. (line 55) +* BFD_RELOC_8_GOT_PCREL: howto manager. (line 49) +* BFD_RELOC_8_PCREL: howto manager. (line 38) +* BFD_RELOC_8_PLTOFF: howto manager. (line 67) +* BFD_RELOC_8_PLT_PCREL: howto manager. (line 60) +* BFD_RELOC_AARCH64_16: howto manager. (line 2480) +* BFD_RELOC_AARCH64_16_PCREL: howto manager. (line 2486) +* BFD_RELOC_AARCH64_32: howto manager. (line 2479) +* BFD_RELOC_AARCH64_32_PCREL: howto manager. (line 2485) +* BFD_RELOC_AARCH64_64: howto manager. (line 2478) +* BFD_RELOC_AARCH64_64_PCREL: howto manager. (line 2484) +* BFD_RELOC_AARCH64_ADD_LO12: howto manager. (line 2536) +* BFD_RELOC_AARCH64_ADR_GOT_PAGE: howto manager. (line 2582) +* BFD_RELOC_AARCH64_ADR_HI21_NC_PCREL: howto manager. (line 2532) +* BFD_RELOC_AARCH64_ADR_HI21_PCREL: howto manager. (line 2529) +* BFD_RELOC_AARCH64_ADR_LO21_PCREL: howto manager. (line 2526) +* BFD_RELOC_AARCH64_BRANCH19: howto manager. (line 2548) +* BFD_RELOC_AARCH64_CALL26: howto manager. (line 2556) +* BFD_RELOC_AARCH64_COPY: howto manager. (line 2653) +* BFD_RELOC_AARCH64_GAS_INTERNAL_FIXUP: howto manager. (line 2677) +* BFD_RELOC_AARCH64_GLOB_DAT: howto manager. (line 2655) +* BFD_RELOC_AARCH64_GOT_LD_PREL19: howto manager. (line 2576) +* BFD_RELOC_AARCH64_IRELATIVE: howto manager. (line 2669) +* BFD_RELOC_AARCH64_JUMP26: howto manager. (line 2552) +* BFD_RELOC_AARCH64_JUMP_SLOT: howto manager. (line 2657) +* BFD_RELOC_AARCH64_LD32_GOT_LO12_NC: howto manager. (line 2590) +* BFD_RELOC_AARCH64_LD64_GOT_LO12_NC: howto manager. (line 2586) +* BFD_RELOC_AARCH64_LDST128_LO12: howto manager. (line 2572) +* BFD_RELOC_AARCH64_LDST16_LO12: howto manager. (line 2560) +* BFD_RELOC_AARCH64_LDST32_LO12: howto manager. (line 2564) +* BFD_RELOC_AARCH64_LDST64_LO12: howto manager. (line 2568) +* BFD_RELOC_AARCH64_LDST8_LO12: howto manager. (line 2540) +* BFD_RELOC_AARCH64_LDST_LO12: howto manager. (line 2680) +* BFD_RELOC_AARCH64_LD_GOT_LO12_NC: howto manager. (line 2684) +* BFD_RELOC_AARCH64_LD_LO19_PCREL: howto manager. (line 2522) +* BFD_RELOC_AARCH64_MOVW_G0: howto manager. (line 2489) +* BFD_RELOC_AARCH64_MOVW_G0_NC: howto manager. (line 2492) +* BFD_RELOC_AARCH64_MOVW_G0_S: howto manager. (line 2510) +* BFD_RELOC_AARCH64_MOVW_G1: howto manager. (line 2495) +* BFD_RELOC_AARCH64_MOVW_G1_NC: howto manager. (line 2498) +* BFD_RELOC_AARCH64_MOVW_G1_S: howto manager. (line 2514) +* BFD_RELOC_AARCH64_MOVW_G2: howto manager. (line 2501) +* BFD_RELOC_AARCH64_MOVW_G2_NC: howto manager. (line 2504) +* BFD_RELOC_AARCH64_MOVW_G2_S: howto manager. (line 2518) +* BFD_RELOC_AARCH64_MOVW_G3: howto manager. (line 2507) +* BFD_RELOC_AARCH64_NONE: howto manager. (line 2476) +* BFD_RELOC_AARCH64_RELATIVE: howto manager. (line 2659) +* BFD_RELOC_AARCH64_RELOC_END: howto manager. (line 2671) +* BFD_RELOC_AARCH64_RELOC_START: howto manager. (line 2471) +* BFD_RELOC_AARCH64_TLSDESC: howto manager. (line 2667) +* BFD_RELOC_AARCH64_TLSDESC_ADD: howto manager. (line 2649) +* BFD_RELOC_AARCH64_TLSDESC_ADD_LO12_NC: howto manager. (line 2641) +* BFD_RELOC_AARCH64_TLSDESC_ADR_PAGE21: howto manager. (line 2635) +* BFD_RELOC_AARCH64_TLSDESC_ADR_PREL21: howto manager. (line 2633) +* BFD_RELOC_AARCH64_TLSDESC_CALL: howto manager. (line 2651) +* BFD_RELOC_AARCH64_TLSDESC_LD32_LO12_NC: howto manager. (line 2639) +* BFD_RELOC_AARCH64_TLSDESC_LD64_LO12_NC: howto manager. (line 2637) +* BFD_RELOC_AARCH64_TLSDESC_LDR: howto manager. (line 2647) +* BFD_RELOC_AARCH64_TLSDESC_LD_LO12_NC: howto manager. (line 2690) +* BFD_RELOC_AARCH64_TLSDESC_LD_PREL19: howto manager. (line 2631) +* BFD_RELOC_AARCH64_TLSDESC_OFF_G0_NC: howto manager. (line 2645) +* BFD_RELOC_AARCH64_TLSDESC_OFF_G1: howto manager. (line 2643) +* BFD_RELOC_AARCH64_TLSGD_ADD_LO12_NC: howto manager. (line 2599) +* BFD_RELOC_AARCH64_TLSGD_ADR_PAGE21: howto manager. (line 2594) +* BFD_RELOC_AARCH64_TLSIE_ADR_GOTTPREL_PAGE21: howto manager. + (line 2607) +* BFD_RELOC_AARCH64_TLSIE_LD32_GOTTPREL_LO12_NC: howto manager. + (line 2611) +* BFD_RELOC_AARCH64_TLSIE_LD64_GOTTPREL_LO12_NC: howto manager. + (line 2609) +* BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_LO12_NC: howto manager. + (line 2687) +* BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_PREL19: howto manager. (line 2613) +* BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G0_NC: howto manager. + (line 2605) +* BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G1: howto manager. (line 2603) +* BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_HI12: howto manager. (line 2625) +* BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12: howto manager. (line 2627) +* BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12_NC: howto manager. (line 2629) +* BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0: howto manager. (line 2621) +* BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0_NC: howto manager. (line 2623) +* BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1: howto manager. (line 2617) +* BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1_NC: howto manager. (line 2619) +* BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G2: howto manager. (line 2615) +* BFD_RELOC_AARCH64_TLS_DTPMOD: howto manager. (line 2661) +* BFD_RELOC_AARCH64_TLS_DTPREL: howto manager. (line 2663) +* BFD_RELOC_AARCH64_TLS_TPREL: howto manager. (line 2665) +* BFD_RELOC_AARCH64_TSTBR14: howto manager. (line 2544) +* BFD_RELOC_ALPHA_BOH: howto manager. (line 292) +* BFD_RELOC_ALPHA_BRSGP: howto manager. (line 279) +* BFD_RELOC_ALPHA_BSR: howto manager. (line 286) +* BFD_RELOC_ALPHA_CODEADDR: howto manager. (line 272) +* BFD_RELOC_ALPHA_DTPMOD64: howto manager. (line 297) +* BFD_RELOC_ALPHA_DTPREL16: howto manager. (line 302) +* BFD_RELOC_ALPHA_DTPREL64: howto manager. (line 299) +* BFD_RELOC_ALPHA_DTPREL_HI16: howto manager. (line 300) +* BFD_RELOC_ALPHA_DTPREL_LO16: howto manager. (line 301) +* BFD_RELOC_ALPHA_ELF_LITERAL: howto manager. (line 240) +* BFD_RELOC_ALPHA_GOTDTPREL16: howto manager. (line 298) +* BFD_RELOC_ALPHA_GOTTPREL16: howto manager. (line 303) +* BFD_RELOC_ALPHA_GPDISP: howto manager. (line 235) +* BFD_RELOC_ALPHA_GPDISP_HI16: howto manager. (line 223) +* BFD_RELOC_ALPHA_GPDISP_LO16: howto manager. (line 230) +* BFD_RELOC_ALPHA_GPREL_HI16: howto manager. (line 275) +* BFD_RELOC_ALPHA_GPREL_LO16: howto manager. (line 276) +* BFD_RELOC_ALPHA_HINT: howto manager. (line 265) +* BFD_RELOC_ALPHA_LDA: howto manager. (line 289) +* BFD_RELOC_ALPHA_LINKAGE: howto manager. (line 269) +* BFD_RELOC_ALPHA_LITERAL: howto manager. (line 239) +* BFD_RELOC_ALPHA_LITUSE: howto manager. (line 241) +* BFD_RELOC_ALPHA_NOP: howto manager. (line 283) +* BFD_RELOC_ALPHA_TLSGD: howto manager. (line 295) +* BFD_RELOC_ALPHA_TLSLDM: howto manager. (line 296) +* BFD_RELOC_ALPHA_TPREL16: howto manager. (line 307) +* BFD_RELOC_ALPHA_TPREL64: howto manager. (line 304) +* BFD_RELOC_ALPHA_TPREL_HI16: howto manager. (line 305) +* BFD_RELOC_ALPHA_TPREL_LO16: howto manager. (line 306) +* BFD_RELOC_ARC_B22_PCREL: howto manager. (line 952) +* BFD_RELOC_ARC_B26: howto manager. (line 956) +* BFD_RELOC_ARM_ADRL_IMMEDIATE: howto manager. (line 826) +* BFD_RELOC_ARM_ADR_IMM: howto manager. (line 840) +* BFD_RELOC_ARM_ALU_PC_G0: howto manager. (line 793) +* BFD_RELOC_ARM_ALU_PC_G0_NC: howto manager. (line 792) +* BFD_RELOC_ARM_ALU_PC_G1: howto manager. (line 795) +* BFD_RELOC_ARM_ALU_PC_G1_NC: howto manager. (line 794) +* BFD_RELOC_ARM_ALU_PC_G2: howto manager. (line 796) +* BFD_RELOC_ARM_ALU_SB_G0: howto manager. (line 807) +* BFD_RELOC_ARM_ALU_SB_G0_NC: howto manager. (line 806) +* BFD_RELOC_ARM_ALU_SB_G1: howto manager. (line 809) +* BFD_RELOC_ARM_ALU_SB_G1_NC: howto manager. (line 808) +* BFD_RELOC_ARM_ALU_SB_G2: howto manager. (line 810) +* BFD_RELOC_ARM_CP_OFF_IMM: howto manager. (line 836) +* BFD_RELOC_ARM_CP_OFF_IMM_S2: howto manager. (line 837) +* BFD_RELOC_ARM_GLOB_DAT: howto manager. (line 769) +* BFD_RELOC_ARM_GOT32: howto manager. (line 770) +* BFD_RELOC_ARM_GOTOFF: howto manager. (line 773) +* BFD_RELOC_ARM_GOTPC: howto manager. (line 774) +* BFD_RELOC_ARM_GOT_PREL: howto manager. (line 775) +* BFD_RELOC_ARM_HVC: howto manager. (line 833) +* BFD_RELOC_ARM_HWLITERAL: howto manager. (line 847) +* BFD_RELOC_ARM_IMMEDIATE: howto manager. (line 825) +* BFD_RELOC_ARM_IN_POOL: howto manager. (line 843) +* BFD_RELOC_ARM_IRELATIVE: howto manager. (line 823) +* BFD_RELOC_ARM_JUMP_SLOT: howto manager. (line 768) +* BFD_RELOC_ARM_LDC_PC_G0: howto manager. (line 803) +* BFD_RELOC_ARM_LDC_PC_G1: howto manager. (line 804) +* BFD_RELOC_ARM_LDC_PC_G2: howto manager. (line 805) +* BFD_RELOC_ARM_LDC_SB_G0: howto manager. (line 817) +* BFD_RELOC_ARM_LDC_SB_G1: howto manager. (line 818) +* BFD_RELOC_ARM_LDC_SB_G2: howto manager. (line 819) +* BFD_RELOC_ARM_LDRS_PC_G0: howto manager. (line 800) +* BFD_RELOC_ARM_LDRS_PC_G1: howto manager. (line 801) +* BFD_RELOC_ARM_LDRS_PC_G2: howto manager. (line 802) +* BFD_RELOC_ARM_LDRS_SB_G0: howto manager. (line 814) +* BFD_RELOC_ARM_LDRS_SB_G1: howto manager. (line 815) +* BFD_RELOC_ARM_LDRS_SB_G2: howto manager. (line 816) +* BFD_RELOC_ARM_LDR_IMM: howto manager. (line 841) +* BFD_RELOC_ARM_LDR_PC_G0: howto manager. (line 797) +* BFD_RELOC_ARM_LDR_PC_G1: howto manager. (line 798) +* BFD_RELOC_ARM_LDR_PC_G2: howto manager. (line 799) +* BFD_RELOC_ARM_LDR_SB_G0: howto manager. (line 811) +* BFD_RELOC_ARM_LDR_SB_G1: howto manager. (line 812) +* BFD_RELOC_ARM_LDR_SB_G2: howto manager. (line 813) +* BFD_RELOC_ARM_LITERAL: howto manager. (line 842) +* BFD_RELOC_ARM_MOVT: howto manager. (line 760) +* BFD_RELOC_ARM_MOVT_PCREL: howto manager. (line 762) +* BFD_RELOC_ARM_MOVW: howto manager. (line 759) +* BFD_RELOC_ARM_MOVW_PCREL: howto manager. (line 761) +* BFD_RELOC_ARM_MULTI: howto manager. (line 835) +* BFD_RELOC_ARM_OFFSET_IMM: howto manager. (line 740) +* BFD_RELOC_ARM_OFFSET_IMM8: howto manager. (line 844) +* BFD_RELOC_ARM_PCREL_BLX: howto manager. (line 716) +* BFD_RELOC_ARM_PCREL_BRANCH: howto manager. (line 713) +* BFD_RELOC_ARM_PCREL_CALL: howto manager. (line 724) +* BFD_RELOC_ARM_PCREL_JUMP: howto manager. (line 727) +* BFD_RELOC_ARM_PLT32: howto manager. (line 771) +* BFD_RELOC_ARM_PREL31: howto manager. (line 757) +* BFD_RELOC_ARM_RELATIVE: howto manager. (line 772) +* BFD_RELOC_ARM_ROSEGREL32: howto manager. (line 749) +* BFD_RELOC_ARM_SBREL32: howto manager. (line 751) +* BFD_RELOC_ARM_SHIFT_IMM: howto manager. (line 831) +* BFD_RELOC_ARM_SMC: howto manager. (line 832) +* BFD_RELOC_ARM_SWI: howto manager. (line 834) +* BFD_RELOC_ARM_T32_ADD_IMM: howto manager. (line 828) +* BFD_RELOC_ARM_T32_ADD_PC12: howto manager. (line 830) +* BFD_RELOC_ARM_T32_CP_OFF_IMM: howto manager. (line 838) +* BFD_RELOC_ARM_T32_CP_OFF_IMM_S2: howto manager. (line 839) +* BFD_RELOC_ARM_T32_IMM12: howto manager. (line 829) +* BFD_RELOC_ARM_T32_IMMEDIATE: howto manager. (line 827) +* BFD_RELOC_ARM_T32_OFFSET_IMM: howto manager. (line 846) +* BFD_RELOC_ARM_T32_OFFSET_U8: howto manager. (line 845) +* BFD_RELOC_ARM_TARGET1: howto manager. (line 746) +* BFD_RELOC_ARM_TARGET2: howto manager. (line 753) +* BFD_RELOC_ARM_THM_TLS_CALL: howto manager. (line 787) +* BFD_RELOC_ARM_THM_TLS_DESCSEQ: howto manager. (line 789) +* BFD_RELOC_ARM_THUMB_ADD: howto manager. (line 848) +* BFD_RELOC_ARM_THUMB_IMM: howto manager. (line 849) +* BFD_RELOC_ARM_THUMB_MOVT: howto manager. (line 764) +* BFD_RELOC_ARM_THUMB_MOVT_PCREL: howto manager. (line 766) +* BFD_RELOC_ARM_THUMB_MOVW: howto manager. (line 763) +* BFD_RELOC_ARM_THUMB_MOVW_PCREL: howto manager. (line 765) +* BFD_RELOC_ARM_THUMB_OFFSET: howto manager. (line 743) +* BFD_RELOC_ARM_THUMB_SHIFT: howto manager. (line 850) +* BFD_RELOC_ARM_TLS_CALL: howto manager. (line 786) +* BFD_RELOC_ARM_TLS_DESC: howto manager. (line 790) +* BFD_RELOC_ARM_TLS_DESCSEQ: howto manager. (line 788) +* BFD_RELOC_ARM_TLS_DTPMOD32: howto manager. (line 781) +* BFD_RELOC_ARM_TLS_DTPOFF32: howto manager. (line 780) +* BFD_RELOC_ARM_TLS_GD32: howto manager. (line 777) +* BFD_RELOC_ARM_TLS_GOTDESC: howto manager. (line 785) +* BFD_RELOC_ARM_TLS_IE32: howto manager. (line 783) +* BFD_RELOC_ARM_TLS_LDM32: howto manager. (line 779) +* BFD_RELOC_ARM_TLS_LDO32: howto manager. (line 778) +* BFD_RELOC_ARM_TLS_LE32: howto manager. (line 784) +* BFD_RELOC_ARM_TLS_TPOFF32: howto manager. (line 782) +* BFD_RELOC_ARM_V4BX: howto manager. (line 821) +* BFD_RELOC_AVR_13_PCREL: howto manager. (line 1554) +* BFD_RELOC_AVR_16_PM: howto manager. (line 1557) +* BFD_RELOC_AVR_6: howto manager. (line 1625) +* BFD_RELOC_AVR_6_ADIW: howto manager. (line 1628) +* BFD_RELOC_AVR_7_PCREL: howto manager. (line 1551) +* BFD_RELOC_AVR_8_HI: howto manager. (line 1634) +* BFD_RELOC_AVR_8_HLO: howto manager. (line 1637) +* BFD_RELOC_AVR_8_LO: howto manager. (line 1631) +* BFD_RELOC_AVR_CALL: howto manager. (line 1619) +* BFD_RELOC_AVR_HH8_LDI: howto manager. (line 1566) +* BFD_RELOC_AVR_HH8_LDI_NEG: howto manager. (line 1581) +* BFD_RELOC_AVR_HH8_LDI_PM: howto manager. (line 1604) +* BFD_RELOC_AVR_HH8_LDI_PM_NEG: howto manager. (line 1615) +* BFD_RELOC_AVR_HI8_LDI: howto manager. (line 1563) +* BFD_RELOC_AVR_HI8_LDI_GS: howto manager. (line 1599) +* BFD_RELOC_AVR_HI8_LDI_NEG: howto manager. (line 1577) +* BFD_RELOC_AVR_HI8_LDI_PM: howto manager. (line 1596) +* BFD_RELOC_AVR_HI8_LDI_PM_NEG: howto manager. (line 1611) +* BFD_RELOC_AVR_LDI: howto manager. (line 1622) +* BFD_RELOC_AVR_LO8_LDI: howto manager. (line 1560) +* BFD_RELOC_AVR_LO8_LDI_GS: howto manager. (line 1591) +* BFD_RELOC_AVR_LO8_LDI_NEG: howto manager. (line 1573) +* BFD_RELOC_AVR_LO8_LDI_PM: howto manager. (line 1588) +* BFD_RELOC_AVR_LO8_LDI_PM_NEG: howto manager. (line 1608) +* BFD_RELOC_AVR_MS8_LDI: howto manager. (line 1570) +* BFD_RELOC_AVR_MS8_LDI_NEG: howto manager. (line 1585) +* BFD_RELOC_BFIN_10_PCREL: howto manager. (line 970) +* BFD_RELOC_BFIN_11_PCREL: howto manager. (line 972) +* BFD_RELOC_BFIN_12_PCREL_JUMP: howto manager. (line 974) +* BFD_RELOC_BFIN_12_PCREL_JUMP_S: howto manager. (line 976) +* BFD_RELOC_BFIN_16_HIGH: howto manager. (line 962) +* BFD_RELOC_BFIN_16_IMM: howto manager. (line 960) +* BFD_RELOC_BFIN_16_LOW: howto manager. (line 968) +* BFD_RELOC_BFIN_24_PCREL_CALL_X: howto manager. (line 978) +* BFD_RELOC_BFIN_24_PCREL_JUMP_L: howto manager. (line 980) +* BFD_RELOC_BFIN_4_PCREL: howto manager. (line 964) +* BFD_RELOC_BFIN_5_PCREL: howto manager. (line 966) +* BFD_RELOC_BFIN_FUNCDESC: howto manager. (line 985) +* BFD_RELOC_BFIN_FUNCDESC_GOT17M4: howto manager. (line 986) +* BFD_RELOC_BFIN_FUNCDESC_GOTHI: howto manager. (line 987) +* BFD_RELOC_BFIN_FUNCDESC_GOTLO: howto manager. (line 988) +* BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4: howto manager. (line 990) +* BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI: howto manager. (line 991) +* BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO: howto manager. (line 992) +* BFD_RELOC_BFIN_FUNCDESC_VALUE: howto manager. (line 989) +* BFD_RELOC_BFIN_GOT: howto manager. (line 997) +* BFD_RELOC_BFIN_GOT17M4: howto manager. (line 982) +* BFD_RELOC_BFIN_GOTHI: howto manager. (line 983) +* BFD_RELOC_BFIN_GOTLO: howto manager. (line 984) +* BFD_RELOC_BFIN_GOTOFF17M4: howto manager. (line 993) +* BFD_RELOC_BFIN_GOTOFFHI: howto manager. (line 994) +* BFD_RELOC_BFIN_GOTOFFLO: howto manager. (line 995) +* BFD_RELOC_BFIN_PLTPC: howto manager. (line 999) +* BFD_RELOC_C6000_ABS_H16: howto manager. (line 1396) +* BFD_RELOC_C6000_ABS_L16: howto manager. (line 1395) +* BFD_RELOC_C6000_ABS_S16: howto manager. (line 1394) +* BFD_RELOC_C6000_ALIGN: howto manager. (line 1417) +* BFD_RELOC_C6000_COPY: howto manager. (line 1412) +* BFD_RELOC_C6000_DSBT_INDEX: howto manager. (line 1410) +* BFD_RELOC_C6000_EHTYPE: howto manager. (line 1414) +* BFD_RELOC_C6000_FPHEAD: howto manager. (line 1418) +* BFD_RELOC_C6000_JUMP_SLOT: howto manager. (line 1413) +* BFD_RELOC_C6000_NOCMP: howto manager. (line 1419) +* BFD_RELOC_C6000_PCR_H16: howto manager. (line 1415) +* BFD_RELOC_C6000_PCR_L16: howto manager. (line 1416) +* BFD_RELOC_C6000_PCR_S10: howto manager. (line 1392) +* BFD_RELOC_C6000_PCR_S12: howto manager. (line 1391) +* BFD_RELOC_C6000_PCR_S21: howto manager. (line 1390) +* BFD_RELOC_C6000_PCR_S7: howto manager. (line 1393) +* BFD_RELOC_C6000_PREL31: howto manager. (line 1411) +* BFD_RELOC_C6000_SBR_GOT_H16_W: howto manager. (line 1409) +* BFD_RELOC_C6000_SBR_GOT_L16_W: howto manager. (line 1408) +* BFD_RELOC_C6000_SBR_GOT_U15_W: howto manager. (line 1407) +* BFD_RELOC_C6000_SBR_H16_B: howto manager. (line 1404) +* BFD_RELOC_C6000_SBR_H16_H: howto manager. (line 1405) +* BFD_RELOC_C6000_SBR_H16_W: howto manager. (line 1406) +* BFD_RELOC_C6000_SBR_L16_B: howto manager. (line 1401) +* BFD_RELOC_C6000_SBR_L16_H: howto manager. (line 1402) +* BFD_RELOC_C6000_SBR_L16_W: howto manager. (line 1403) +* BFD_RELOC_C6000_SBR_S16: howto manager. (line 1400) +* BFD_RELOC_C6000_SBR_U15_B: howto manager. (line 1397) +* BFD_RELOC_C6000_SBR_U15_H: howto manager. (line 1398) +* BFD_RELOC_C6000_SBR_U15_W: howto manager. (line 1399) +* bfd_reloc_code_type: howto manager. (line 9) +* BFD_RELOC_CR16_ABS20: howto manager. (line 2065) +* BFD_RELOC_CR16_ABS24: howto manager. (line 2066) +* BFD_RELOC_CR16_DISP16: howto manager. (line 2076) +* BFD_RELOC_CR16_DISP20: howto manager. (line 2077) +* BFD_RELOC_CR16_DISP24: howto manager. (line 2078) +* BFD_RELOC_CR16_DISP24a: howto manager. (line 2079) +* BFD_RELOC_CR16_DISP4: howto manager. (line 2074) +* BFD_RELOC_CR16_DISP8: howto manager. (line 2075) +* BFD_RELOC_CR16_GLOB_DAT: howto manager. (line 2085) +* BFD_RELOC_CR16_GOTC_REGREL20: howto manager. (line 2084) +* BFD_RELOC_CR16_GOT_REGREL20: howto manager. (line 2083) +* BFD_RELOC_CR16_IMM16: howto manager. (line 2069) +* BFD_RELOC_CR16_IMM20: howto manager. (line 2070) +* BFD_RELOC_CR16_IMM24: howto manager. (line 2071) +* BFD_RELOC_CR16_IMM32: howto manager. (line 2072) +* BFD_RELOC_CR16_IMM32a: howto manager. (line 2073) +* BFD_RELOC_CR16_IMM4: howto manager. (line 2067) +* BFD_RELOC_CR16_IMM8: howto manager. (line 2068) +* BFD_RELOC_CR16_NUM16: howto manager. (line 2054) +* BFD_RELOC_CR16_NUM32: howto manager. (line 2055) +* BFD_RELOC_CR16_NUM32a: howto manager. (line 2056) +* BFD_RELOC_CR16_NUM8: howto manager. (line 2053) +* BFD_RELOC_CR16_REGREL0: howto manager. (line 2057) +* BFD_RELOC_CR16_REGREL14: howto manager. (line 2060) +* BFD_RELOC_CR16_REGREL14a: howto manager. (line 2061) +* BFD_RELOC_CR16_REGREL16: howto manager. (line 2062) +* BFD_RELOC_CR16_REGREL20: howto manager. (line 2063) +* BFD_RELOC_CR16_REGREL20a: howto manager. (line 2064) +* BFD_RELOC_CR16_REGREL4: howto manager. (line 2058) +* BFD_RELOC_CR16_REGREL4a: howto manager. (line 2059) +* BFD_RELOC_CR16_SWITCH16: howto manager. (line 2081) +* BFD_RELOC_CR16_SWITCH32: howto manager. (line 2082) +* BFD_RELOC_CR16_SWITCH8: howto manager. (line 2080) +* BFD_RELOC_CRIS_16_DTPREL: howto manager. (line 2145) +* BFD_RELOC_CRIS_16_GOT: howto manager. (line 2127) +* BFD_RELOC_CRIS_16_GOTPLT: howto manager. (line 2131) +* BFD_RELOC_CRIS_16_GOT_GD: howto manager. (line 2141) +* BFD_RELOC_CRIS_16_GOT_TPREL: howto manager. (line 2147) +* BFD_RELOC_CRIS_16_TPREL: howto manager. (line 2149) +* BFD_RELOC_CRIS_32_DTPREL: howto manager. (line 2144) +* BFD_RELOC_CRIS_32_GD: howto manager. (line 2142) +* BFD_RELOC_CRIS_32_GOT: howto manager. (line 2125) +* BFD_RELOC_CRIS_32_GOTPLT: howto manager. (line 2129) +* BFD_RELOC_CRIS_32_GOTREL: howto manager. (line 2133) +* BFD_RELOC_CRIS_32_GOT_GD: howto manager. (line 2140) +* BFD_RELOC_CRIS_32_GOT_TPREL: howto manager. (line 2146) +* BFD_RELOC_CRIS_32_IE: howto manager. (line 2151) +* BFD_RELOC_CRIS_32_PLT_GOTREL: howto manager. (line 2135) +* BFD_RELOC_CRIS_32_PLT_PCREL: howto manager. (line 2137) +* BFD_RELOC_CRIS_32_TPREL: howto manager. (line 2148) +* BFD_RELOC_CRIS_BDISP8: howto manager. (line 2108) +* BFD_RELOC_CRIS_COPY: howto manager. (line 2120) +* BFD_RELOC_CRIS_DTP: howto manager. (line 2143) +* BFD_RELOC_CRIS_DTPMOD: howto manager. (line 2150) +* BFD_RELOC_CRIS_GLOB_DAT: howto manager. (line 2121) +* BFD_RELOC_CRIS_JUMP_SLOT: howto manager. (line 2122) +* BFD_RELOC_CRIS_LAPCQ_OFFSET: howto manager. (line 2116) +* BFD_RELOC_CRIS_RELATIVE: howto manager. (line 2123) +* BFD_RELOC_CRIS_SIGNED_16: howto manager. (line 2114) +* BFD_RELOC_CRIS_SIGNED_6: howto manager. (line 2110) +* BFD_RELOC_CRIS_SIGNED_8: howto manager. (line 2112) +* BFD_RELOC_CRIS_UNSIGNED_16: howto manager. (line 2115) +* BFD_RELOC_CRIS_UNSIGNED_4: howto manager. (line 2117) +* BFD_RELOC_CRIS_UNSIGNED_5: howto manager. (line 2109) +* BFD_RELOC_CRIS_UNSIGNED_6: howto manager. (line 2111) +* BFD_RELOC_CRIS_UNSIGNED_8: howto manager. (line 2113) +* BFD_RELOC_CRX_ABS16: howto manager. (line 2097) +* BFD_RELOC_CRX_ABS32: howto manager. (line 2098) +* BFD_RELOC_CRX_IMM16: howto manager. (line 2102) +* BFD_RELOC_CRX_IMM32: howto manager. (line 2103) +* BFD_RELOC_CRX_NUM16: howto manager. (line 2100) +* BFD_RELOC_CRX_NUM32: howto manager. (line 2101) +* BFD_RELOC_CRX_NUM8: howto manager. (line 2099) +* BFD_RELOC_CRX_REGREL12: howto manager. (line 2093) +* BFD_RELOC_CRX_REGREL22: howto manager. (line 2094) +* BFD_RELOC_CRX_REGREL28: howto manager. (line 2095) +* BFD_RELOC_CRX_REGREL32: howto manager. (line 2096) +* BFD_RELOC_CRX_REL16: howto manager. (line 2090) +* BFD_RELOC_CRX_REL24: howto manager. (line 2091) +* BFD_RELOC_CRX_REL32: howto manager. (line 2092) +* BFD_RELOC_CRX_REL4: howto manager. (line 2087) +* BFD_RELOC_CRX_REL8: howto manager. (line 2088) +* BFD_RELOC_CRX_REL8_CMP: howto manager. (line 2089) +* BFD_RELOC_CRX_SWITCH16: howto manager. (line 2105) +* BFD_RELOC_CRX_SWITCH32: howto manager. (line 2106) +* BFD_RELOC_CRX_SWITCH8: howto manager. (line 2104) +* BFD_RELOC_CTOR: howto manager. (line 708) +* BFD_RELOC_D10V_10_PCREL_L: howto manager. (line 1044) +* BFD_RELOC_D10V_10_PCREL_R: howto manager. (line 1041) +* BFD_RELOC_D10V_18: howto manager. (line 1048) +* BFD_RELOC_D10V_18_PCREL: howto manager. (line 1050) +* BFD_RELOC_D30V_15: howto manager. (line 1061) +* BFD_RELOC_D30V_15_PCREL: howto manager. (line 1064) +* BFD_RELOC_D30V_15_PCREL_R: howto manager. (line 1067) +* BFD_RELOC_D30V_21: howto manager. (line 1071) +* BFD_RELOC_D30V_21_PCREL: howto manager. (line 1074) +* BFD_RELOC_D30V_21_PCREL_R: howto manager. (line 1077) +* BFD_RELOC_D30V_32: howto manager. (line 1081) +* BFD_RELOC_D30V_32_PCREL: howto manager. (line 1083) +* BFD_RELOC_D30V_6: howto manager. (line 1052) +* BFD_RELOC_D30V_9_PCREL: howto manager. (line 1054) +* BFD_RELOC_D30V_9_PCREL_R: howto manager. (line 1057) +* BFD_RELOC_DLX_HI16_S: howto manager. (line 1085) +* BFD_RELOC_DLX_JMP26: howto manager. (line 1089) +* BFD_RELOC_DLX_LO16: howto manager. (line 1087) +* BFD_RELOC_EPIPHANY_HIGH: howto manager. (line 2887) +* BFD_RELOC_EPIPHANY_IMM11: howto manager. (line 2893) +* BFD_RELOC_EPIPHANY_IMM8: howto manager. (line 2896) +* BFD_RELOC_EPIPHANY_LOW: howto manager. (line 2889) +* BFD_RELOC_EPIPHANY_SIMM11: howto manager. (line 2891) +* BFD_RELOC_EPIPHANY_SIMM24: howto manager. (line 2885) +* BFD_RELOC_EPIPHANY_SIMM8: howto manager. (line 2883) +* BFD_RELOC_FR30_10_IN_8: howto manager. (line 1435) +* BFD_RELOC_FR30_12_PCREL: howto manager. (line 1441) +* BFD_RELOC_FR30_20: howto manager. (line 1423) +* BFD_RELOC_FR30_48: howto manager. (line 1421) +* BFD_RELOC_FR30_6_IN_4: howto manager. (line 1426) +* BFD_RELOC_FR30_8_IN_8: howto manager. (line 1429) +* BFD_RELOC_FR30_9_IN_8: howto manager. (line 1432) +* BFD_RELOC_FR30_9_PCREL: howto manager. (line 1438) +* BFD_RELOC_FRV_FUNCDESC: howto manager. (line 438) +* BFD_RELOC_FRV_FUNCDESC_GOT12: howto manager. (line 439) +* BFD_RELOC_FRV_FUNCDESC_GOTHI: howto manager. (line 440) +* BFD_RELOC_FRV_FUNCDESC_GOTLO: howto manager. (line 441) +* BFD_RELOC_FRV_FUNCDESC_GOTOFF12: howto manager. (line 443) +* BFD_RELOC_FRV_FUNCDESC_GOTOFFHI: howto manager. (line 444) +* BFD_RELOC_FRV_FUNCDESC_GOTOFFLO: howto manager. (line 445) +* BFD_RELOC_FRV_FUNCDESC_VALUE: howto manager. (line 442) +* BFD_RELOC_FRV_GETTLSOFF: howto manager. (line 449) +* BFD_RELOC_FRV_GETTLSOFF_RELAX: howto manager. (line 462) +* BFD_RELOC_FRV_GOT12: howto manager. (line 435) +* BFD_RELOC_FRV_GOTHI: howto manager. (line 436) +* BFD_RELOC_FRV_GOTLO: howto manager. (line 437) +* BFD_RELOC_FRV_GOTOFF12: howto manager. (line 446) +* BFD_RELOC_FRV_GOTOFFHI: howto manager. (line 447) +* BFD_RELOC_FRV_GOTOFFLO: howto manager. (line 448) +* BFD_RELOC_FRV_GOTTLSDESC12: howto manager. (line 451) +* BFD_RELOC_FRV_GOTTLSDESCHI: howto manager. (line 452) +* BFD_RELOC_FRV_GOTTLSDESCLO: howto manager. (line 453) +* BFD_RELOC_FRV_GOTTLSOFF12: howto manager. (line 457) +* BFD_RELOC_FRV_GOTTLSOFFHI: howto manager. (line 458) +* BFD_RELOC_FRV_GOTTLSOFFLO: howto manager. (line 459) +* BFD_RELOC_FRV_GPREL12: howto manager. (line 430) +* BFD_RELOC_FRV_GPREL32: howto manager. (line 432) +* BFD_RELOC_FRV_GPRELHI: howto manager. (line 433) +* BFD_RELOC_FRV_GPRELLO: howto manager. (line 434) +* BFD_RELOC_FRV_GPRELU12: howto manager. (line 431) +* BFD_RELOC_FRV_HI16: howto manager. (line 429) +* BFD_RELOC_FRV_LABEL16: howto manager. (line 426) +* BFD_RELOC_FRV_LABEL24: howto manager. (line 427) +* BFD_RELOC_FRV_LO16: howto manager. (line 428) +* BFD_RELOC_FRV_TLSDESC_RELAX: howto manager. (line 461) +* BFD_RELOC_FRV_TLSDESC_VALUE: howto manager. (line 450) +* BFD_RELOC_FRV_TLSMOFF: howto manager. (line 464) +* BFD_RELOC_FRV_TLSMOFF12: howto manager. (line 454) +* BFD_RELOC_FRV_TLSMOFFHI: howto manager. (line 455) +* BFD_RELOC_FRV_TLSMOFFLO: howto manager. (line 456) +* BFD_RELOC_FRV_TLSOFF: howto manager. (line 460) +* BFD_RELOC_FRV_TLSOFF_RELAX: howto manager. (line 463) +* BFD_RELOC_GPREL16: howto manager. (line 114) +* BFD_RELOC_GPREL32: howto manager. (line 115) +* BFD_RELOC_H8_DIR16A8: howto manager. (line 2189) +* BFD_RELOC_H8_DIR16R8: howto manager. (line 2190) +* BFD_RELOC_H8_DIR24A8: howto manager. (line 2191) +* BFD_RELOC_H8_DIR24R8: howto manager. (line 2192) +* BFD_RELOC_H8_DIR32A16: howto manager. (line 2193) +* BFD_RELOC_H8_DISP32A16: howto manager. (line 2194) +* BFD_RELOC_HI16: howto manager. (line 316) +* BFD_RELOC_HI16_BASEREL: howto manager. (line 94) +* BFD_RELOC_HI16_GOTOFF: howto manager. (line 53) +* BFD_RELOC_HI16_PCREL: howto manager. (line 325) +* BFD_RELOC_HI16_PLTOFF: howto manager. (line 65) +* BFD_RELOC_HI16_S: howto manager. (line 318) +* BFD_RELOC_HI16_S_BASEREL: howto manager. (line 95) +* BFD_RELOC_HI16_S_GOTOFF: howto manager. (line 54) +* BFD_RELOC_HI16_S_PCREL: howto manager. (line 327) +* BFD_RELOC_HI16_S_PLTOFF: howto manager. (line 66) +* BFD_RELOC_HI22: howto manager. (line 110) +* BFD_RELOC_I370_D12: howto manager. (line 706) +* BFD_RELOC_I960_CALLJ: howto manager. (line 120) +* BFD_RELOC_IA64_COPY: howto manager. (line 1914) +* BFD_RELOC_IA64_DIR32LSB: howto manager. (line 1859) +* BFD_RELOC_IA64_DIR32MSB: howto manager. (line 1858) +* BFD_RELOC_IA64_DIR64LSB: howto manager. (line 1861) +* BFD_RELOC_IA64_DIR64MSB: howto manager. (line 1860) +* BFD_RELOC_IA64_DTPMOD64LSB: howto manager. (line 1924) +* BFD_RELOC_IA64_DTPMOD64MSB: howto manager. (line 1923) +* BFD_RELOC_IA64_DTPREL14: howto manager. (line 1926) +* BFD_RELOC_IA64_DTPREL22: howto manager. (line 1927) +* BFD_RELOC_IA64_DTPREL32LSB: howto manager. (line 1930) +* BFD_RELOC_IA64_DTPREL32MSB: howto manager. (line 1929) +* BFD_RELOC_IA64_DTPREL64I: howto manager. (line 1928) +* BFD_RELOC_IA64_DTPREL64LSB: howto manager. (line 1932) +* BFD_RELOC_IA64_DTPREL64MSB: howto manager. (line 1931) +* BFD_RELOC_IA64_FPTR32LSB: howto manager. (line 1876) +* BFD_RELOC_IA64_FPTR32MSB: howto manager. (line 1875) +* BFD_RELOC_IA64_FPTR64I: howto manager. (line 1874) +* BFD_RELOC_IA64_FPTR64LSB: howto manager. (line 1878) +* BFD_RELOC_IA64_FPTR64MSB: howto manager. (line 1877) +* BFD_RELOC_IA64_GPREL22: howto manager. (line 1862) +* BFD_RELOC_IA64_GPREL32LSB: howto manager. (line 1865) +* BFD_RELOC_IA64_GPREL32MSB: howto manager. (line 1864) +* BFD_RELOC_IA64_GPREL64I: howto manager. (line 1863) +* BFD_RELOC_IA64_GPREL64LSB: howto manager. (line 1867) +* BFD_RELOC_IA64_GPREL64MSB: howto manager. (line 1866) +* BFD_RELOC_IA64_IMM14: howto manager. (line 1855) +* BFD_RELOC_IA64_IMM22: howto manager. (line 1856) +* BFD_RELOC_IA64_IMM64: howto manager. (line 1857) +* BFD_RELOC_IA64_IPLTLSB: howto manager. (line 1913) +* BFD_RELOC_IA64_IPLTMSB: howto manager. (line 1912) +* BFD_RELOC_IA64_LDXMOV: howto manager. (line 1916) +* BFD_RELOC_IA64_LTOFF22: howto manager. (line 1868) +* BFD_RELOC_IA64_LTOFF22X: howto manager. (line 1915) +* BFD_RELOC_IA64_LTOFF64I: howto manager. (line 1869) +* BFD_RELOC_IA64_LTOFF_DTPMOD22: howto manager. (line 1925) +* BFD_RELOC_IA64_LTOFF_DTPREL22: howto manager. (line 1933) +* BFD_RELOC_IA64_LTOFF_FPTR22: howto manager. (line 1890) +* BFD_RELOC_IA64_LTOFF_FPTR32LSB: howto manager. (line 1893) +* BFD_RELOC_IA64_LTOFF_FPTR32MSB: howto manager. (line 1892) +* BFD_RELOC_IA64_LTOFF_FPTR64I: howto manager. (line 1891) +* BFD_RELOC_IA64_LTOFF_FPTR64LSB: howto manager. (line 1895) +* BFD_RELOC_IA64_LTOFF_FPTR64MSB: howto manager. (line 1894) +* BFD_RELOC_IA64_LTOFF_TPREL22: howto manager. (line 1922) +* BFD_RELOC_IA64_LTV32LSB: howto manager. (line 1909) +* BFD_RELOC_IA64_LTV32MSB: howto manager. (line 1908) +* BFD_RELOC_IA64_LTV64LSB: howto manager. (line 1911) +* BFD_RELOC_IA64_LTV64MSB: howto manager. (line 1910) +* BFD_RELOC_IA64_PCREL21B: howto manager. (line 1879) +* BFD_RELOC_IA64_PCREL21BI: howto manager. (line 1880) +* BFD_RELOC_IA64_PCREL21F: howto manager. (line 1882) +* BFD_RELOC_IA64_PCREL21M: howto manager. (line 1881) +* BFD_RELOC_IA64_PCREL22: howto manager. (line 1883) +* BFD_RELOC_IA64_PCREL32LSB: howto manager. (line 1887) +* BFD_RELOC_IA64_PCREL32MSB: howto manager. (line 1886) +* BFD_RELOC_IA64_PCREL60B: howto manager. (line 1884) +* BFD_RELOC_IA64_PCREL64I: howto manager. (line 1885) +* BFD_RELOC_IA64_PCREL64LSB: howto manager. (line 1889) +* BFD_RELOC_IA64_PCREL64MSB: howto manager. (line 1888) +* BFD_RELOC_IA64_PLTOFF22: howto manager. (line 1870) +* BFD_RELOC_IA64_PLTOFF64I: howto manager. (line 1871) +* BFD_RELOC_IA64_PLTOFF64LSB: howto manager. (line 1873) +* BFD_RELOC_IA64_PLTOFF64MSB: howto manager. (line 1872) +* BFD_RELOC_IA64_REL32LSB: howto manager. (line 1905) +* BFD_RELOC_IA64_REL32MSB: howto manager. (line 1904) +* BFD_RELOC_IA64_REL64LSB: howto manager. (line 1907) +* BFD_RELOC_IA64_REL64MSB: howto manager. (line 1906) +* BFD_RELOC_IA64_SECREL32LSB: howto manager. (line 1901) +* BFD_RELOC_IA64_SECREL32MSB: howto manager. (line 1900) +* BFD_RELOC_IA64_SECREL64LSB: howto manager. (line 1903) +* BFD_RELOC_IA64_SECREL64MSB: howto manager. (line 1902) +* BFD_RELOC_IA64_SEGREL32LSB: howto manager. (line 1897) +* BFD_RELOC_IA64_SEGREL32MSB: howto manager. (line 1896) +* BFD_RELOC_IA64_SEGREL64LSB: howto manager. (line 1899) +* BFD_RELOC_IA64_SEGREL64MSB: howto manager. (line 1898) +* BFD_RELOC_IA64_TPREL14: howto manager. (line 1917) +* BFD_RELOC_IA64_TPREL22: howto manager. (line 1918) +* BFD_RELOC_IA64_TPREL64I: howto manager. (line 1919) +* BFD_RELOC_IA64_TPREL64LSB: howto manager. (line 1921) +* BFD_RELOC_IA64_TPREL64MSB: howto manager. (line 1920) +* BFD_RELOC_IP2K_ADDR16CJP: howto manager. (line 1816) +* BFD_RELOC_IP2K_BANK: howto manager. (line 1814) +* BFD_RELOC_IP2K_EX8DATA: howto manager. (line 1822) +* BFD_RELOC_IP2K_FR9: howto manager. (line 1812) +* BFD_RELOC_IP2K_FR_OFFSET: howto manager. (line 1831) +* BFD_RELOC_IP2K_HI8DATA: howto manager. (line 1821) +* BFD_RELOC_IP2K_HI8INSN: howto manager. (line 1825) +* BFD_RELOC_IP2K_LO8DATA: howto manager. (line 1820) +* BFD_RELOC_IP2K_LO8INSN: howto manager. (line 1824) +* BFD_RELOC_IP2K_PAGE3: howto manager. (line 1818) +* BFD_RELOC_IP2K_PC_SKIP: howto manager. (line 1827) +* BFD_RELOC_IP2K_TEXT: howto manager. (line 1829) +* BFD_RELOC_IQ2000_OFFSET_16: howto manager. (line 2282) +* BFD_RELOC_IQ2000_OFFSET_21: howto manager. (line 2283) +* BFD_RELOC_IQ2000_UHI16: howto manager. (line 2284) +* BFD_RELOC_LM32_16_GOT: howto manager. (line 2374) +* BFD_RELOC_LM32_BRANCH: howto manager. (line 2373) +* BFD_RELOC_LM32_CALL: howto manager. (line 2372) +* BFD_RELOC_LM32_COPY: howto manager. (line 2377) +* BFD_RELOC_LM32_GLOB_DAT: howto manager. (line 2378) +* BFD_RELOC_LM32_GOTOFF_HI16: howto manager. (line 2375) +* BFD_RELOC_LM32_GOTOFF_LO16: howto manager. (line 2376) +* BFD_RELOC_LM32_JMP_SLOT: howto manager. (line 2379) +* BFD_RELOC_LM32_RELATIVE: howto manager. (line 2380) +* BFD_RELOC_LO10: howto manager. (line 111) +* BFD_RELOC_LO16: howto manager. (line 323) +* BFD_RELOC_LO16_BASEREL: howto manager. (line 93) +* BFD_RELOC_LO16_GOTOFF: howto manager. (line 52) +* BFD_RELOC_LO16_PCREL: howto manager. (line 329) +* BFD_RELOC_LO16_PLTOFF: howto manager. (line 64) +* BFD_RELOC_M32C_HI8: howto manager. (line 1091) +* BFD_RELOC_M32C_RL_1ADDR: howto manager. (line 1093) +* BFD_RELOC_M32C_RL_2ADDR: howto manager. (line 1094) +* BFD_RELOC_M32C_RL_JUMP: howto manager. (line 1092) +* BFD_RELOC_M32R_10_PCREL: howto manager. (line 1099) +* BFD_RELOC_M32R_18_PCREL: howto manager. (line 1102) +* BFD_RELOC_M32R_24: howto manager. (line 1096) +* BFD_RELOC_M32R_26_PCREL: howto manager. (line 1104) +* BFD_RELOC_M32R_26_PLTREL: howto manager. (line 1118) +* BFD_RELOC_M32R_COPY: howto manager. (line 1119) +* BFD_RELOC_M32R_GLOB_DAT: howto manager. (line 1120) +* BFD_RELOC_M32R_GOT16_HI_SLO: howto manager. (line 1129) +* BFD_RELOC_M32R_GOT16_HI_ULO: howto manager. (line 1128) +* BFD_RELOC_M32R_GOT16_LO: howto manager. (line 1130) +* BFD_RELOC_M32R_GOT24: howto manager. (line 1117) +* BFD_RELOC_M32R_GOTOFF: howto manager. (line 1123) +* BFD_RELOC_M32R_GOTOFF_HI_SLO: howto manager. (line 1125) +* BFD_RELOC_M32R_GOTOFF_HI_ULO: howto manager. (line 1124) +* BFD_RELOC_M32R_GOTOFF_LO: howto manager. (line 1126) +* BFD_RELOC_M32R_GOTPC24: howto manager. (line 1127) +* BFD_RELOC_M32R_GOTPC_HI_SLO: howto manager. (line 1132) +* BFD_RELOC_M32R_GOTPC_HI_ULO: howto manager. (line 1131) +* BFD_RELOC_M32R_GOTPC_LO: howto manager. (line 1133) +* BFD_RELOC_M32R_HI16_SLO: howto manager. (line 1109) +* BFD_RELOC_M32R_HI16_ULO: howto manager. (line 1106) +* BFD_RELOC_M32R_JMP_SLOT: howto manager. (line 1121) +* BFD_RELOC_M32R_LO16: howto manager. (line 1112) +* BFD_RELOC_M32R_RELATIVE: howto manager. (line 1122) +* BFD_RELOC_M32R_SDA16: howto manager. (line 1114) +* BFD_RELOC_M68HC11_24: howto manager. (line 1961) +* BFD_RELOC_M68HC11_3B: howto manager. (line 1941) +* BFD_RELOC_M68HC11_HI8: howto manager. (line 1935) +* BFD_RELOC_M68HC11_LO16: howto manager. (line 1952) +* BFD_RELOC_M68HC11_LO8: howto manager. (line 1938) +* BFD_RELOC_M68HC11_PAGE: howto manager. (line 1957) +* BFD_RELOC_M68HC11_RL_GROUP: howto manager. (line 1948) +* BFD_RELOC_M68HC11_RL_JUMP: howto manager. (line 1943) +* BFD_RELOC_M68HC12_10_PCREL: howto manager. (line 2004) +* BFD_RELOC_M68HC12_16B: howto manager. (line 2000) +* BFD_RELOC_M68HC12_5B: howto manager. (line 1966) +* BFD_RELOC_M68HC12_9B: howto manager. (line 1998) +* BFD_RELOC_M68HC12_9_PCREL: howto manager. (line 2002) +* BFD_RELOC_M68HC12_HI8XG: howto manager. (line 2009) +* BFD_RELOC_M68HC12_LO8XG: howto manager. (line 2006) +* BFD_RELOC_MACH_O_LOCAL_SECTDIFF: howto manager. (line 2385) +* BFD_RELOC_MACH_O_PAIR: howto manager. (line 2387) +* BFD_RELOC_MACH_O_SECTDIFF: howto manager. (line 2382) +* BFD_RELOC_MACH_O_X86_64_BRANCH32: howto manager. (line 2389) +* BFD_RELOC_MACH_O_X86_64_BRANCH8: howto manager. (line 2390) +* BFD_RELOC_MACH_O_X86_64_GOT: howto manager. (line 2393) +* BFD_RELOC_MACH_O_X86_64_GOT_LOAD: howto manager. (line 2395) +* BFD_RELOC_MACH_O_X86_64_PCREL32_1: howto manager. (line 2402) +* BFD_RELOC_MACH_O_X86_64_PCREL32_2: howto manager. (line 2404) +* BFD_RELOC_MACH_O_X86_64_PCREL32_4: howto manager. (line 2406) +* BFD_RELOC_MACH_O_X86_64_SUBTRACTOR32: howto manager. (line 2398) +* BFD_RELOC_MACH_O_X86_64_SUBTRACTOR64: howto manager. (line 2400) +* BFD_RELOC_MCORE_PCREL_32: howto manager. (line 1447) +* BFD_RELOC_MCORE_PCREL_IMM11BY2: howto manager. (line 1445) +* BFD_RELOC_MCORE_PCREL_IMM4BY2: howto manager. (line 1446) +* BFD_RELOC_MCORE_PCREL_IMM8BY4: howto manager. (line 1444) +* BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2: howto manager. (line 1448) +* BFD_RELOC_MCORE_RVA: howto manager. (line 1449) +* BFD_RELOC_MEP_16: howto manager. (line 1452) +* BFD_RELOC_MEP_32: howto manager. (line 1453) +* BFD_RELOC_MEP_8: howto manager. (line 1451) +* BFD_RELOC_MEP_ADDR24A4: howto manager. (line 1468) +* BFD_RELOC_MEP_GNU_VTENTRY: howto manager. (line 1470) +* BFD_RELOC_MEP_GNU_VTINHERIT: howto manager. (line 1469) +* BFD_RELOC_MEP_GPREL: howto manager. (line 1462) +* BFD_RELOC_MEP_HI16S: howto manager. (line 1461) +* BFD_RELOC_MEP_HI16U: howto manager. (line 1460) +* BFD_RELOC_MEP_LOW16: howto manager. (line 1459) +* BFD_RELOC_MEP_PCABS24A2: howto manager. (line 1458) +* BFD_RELOC_MEP_PCREL12A2: howto manager. (line 1455) +* BFD_RELOC_MEP_PCREL17A2: howto manager. (line 1456) +* BFD_RELOC_MEP_PCREL24A2: howto manager. (line 1457) +* BFD_RELOC_MEP_PCREL8A2: howto manager. (line 1454) +* BFD_RELOC_MEP_TPREL: howto manager. (line 1463) +* BFD_RELOC_MEP_TPREL7: howto manager. (line 1464) +* BFD_RELOC_MEP_TPREL7A2: howto manager. (line 1465) +* BFD_RELOC_MEP_TPREL7A4: howto manager. (line 1466) +* BFD_RELOC_MEP_UIMM24: howto manager. (line 1467) +* BFD_RELOC_METAG_COPY: howto manager. (line 1491) +* BFD_RELOC_METAG_GETSETOFF: howto manager. (line 1475) +* BFD_RELOC_METAG_GETSET_GOT: howto manager. (line 1483) +* BFD_RELOC_METAG_GETSET_GOTOFF: howto manager. (line 1482) +* BFD_RELOC_METAG_GLOB_DAT: howto manager. (line 1494) +* BFD_RELOC_METAG_GOTOFF: howto manager. (line 1489) +* BFD_RELOC_METAG_HI16_GOTOFF: howto manager. (line 1480) +* BFD_RELOC_METAG_HI16_GOTPC: howto manager. (line 1484) +* BFD_RELOC_METAG_HI16_PLT: howto manager. (line 1486) +* BFD_RELOC_METAG_HIADDR16: howto manager. (line 1472) +* BFD_RELOC_METAG_HIOG: howto manager. (line 1476) +* BFD_RELOC_METAG_JMP_SLOT: howto manager. (line 1492) +* BFD_RELOC_METAG_LO16_GOTOFF: howto manager. (line 1481) +* BFD_RELOC_METAG_LO16_GOTPC: howto manager. (line 1485) +* BFD_RELOC_METAG_LO16_PLT: howto manager. (line 1487) +* BFD_RELOC_METAG_LOADDR16: howto manager. (line 1473) +* BFD_RELOC_METAG_LOOG: howto manager. (line 1477) +* BFD_RELOC_METAG_PLT: howto manager. (line 1490) +* BFD_RELOC_METAG_REL16: howto manager. (line 1479) +* BFD_RELOC_METAG_REL8: howto manager. (line 1478) +* BFD_RELOC_METAG_RELATIVE: howto manager. (line 1493) +* BFD_RELOC_METAG_RELBRANCH: howto manager. (line 1474) +* BFD_RELOC_METAG_RELBRANCH_PLT: howto manager. (line 1488) +* BFD_RELOC_METAG_TLS_DTPMOD: howto manager. (line 1505) +* BFD_RELOC_METAG_TLS_DTPOFF: howto manager. (line 1506) +* BFD_RELOC_METAG_TLS_GD: howto manager. (line 1495) +* BFD_RELOC_METAG_TLS_IE: howto manager. (line 1500) +* BFD_RELOC_METAG_TLS_IENONPIC: howto manager. (line 1501) +* BFD_RELOC_METAG_TLS_IENONPIC_HI16: howto manager. (line 1502) +* BFD_RELOC_METAG_TLS_IENONPIC_LO16: howto manager. (line 1503) +* BFD_RELOC_METAG_TLS_LDM: howto manager. (line 1496) +* BFD_RELOC_METAG_TLS_LDO: howto manager. (line 1499) +* BFD_RELOC_METAG_TLS_LDO_HI16: howto manager. (line 1497) +* BFD_RELOC_METAG_TLS_LDO_LO16: howto manager. (line 1498) +* BFD_RELOC_METAG_TLS_LE: howto manager. (line 1507) +* BFD_RELOC_METAG_TLS_LE_HI16: howto manager. (line 1508) +* BFD_RELOC_METAG_TLS_LE_LO16: howto manager. (line 1509) +* BFD_RELOC_METAG_TLS_TPOFF: howto manager. (line 1504) +* BFD_RELOC_MICROBLAZE_32_GOTOFF: howto manager. (line 2442) +* BFD_RELOC_MICROBLAZE_32_LO: howto manager. (line 2408) +* BFD_RELOC_MICROBLAZE_32_LO_PCREL: howto manager. (line 2411) +* BFD_RELOC_MICROBLAZE_32_ROSDA: howto manager. (line 2414) +* BFD_RELOC_MICROBLAZE_32_RWSDA: howto manager. (line 2417) +* BFD_RELOC_MICROBLAZE_32_SYM_OP_SYM: howto manager. (line 2420) +* BFD_RELOC_MICROBLAZE_32_TLSDTPMOD: howto manager. (line 2458) +* BFD_RELOC_MICROBLAZE_32_TLSDTPREL: howto manager. (line 2460) +* BFD_RELOC_MICROBLAZE_64_GOT: howto manager. (line 2431) +* BFD_RELOC_MICROBLAZE_64_GOTOFF: howto manager. (line 2438) +* BFD_RELOC_MICROBLAZE_64_GOTPC: howto manager. (line 2427) +* BFD_RELOC_MICROBLAZE_64_NONE: howto manager. (line 2423) +* BFD_RELOC_MICROBLAZE_64_PLT: howto manager. (line 2434) +* BFD_RELOC_MICROBLAZE_64_TLS: howto manager. (line 2448) +* BFD_RELOC_MICROBLAZE_64_TLSDTPREL: howto manager. (line 2462) +* BFD_RELOC_MICROBLAZE_64_TLSGD: howto manager. (line 2450) +* BFD_RELOC_MICROBLAZE_64_TLSGOTTPREL: howto manager. (line 2465) +* BFD_RELOC_MICROBLAZE_64_TLSLD: howto manager. (line 2454) +* BFD_RELOC_MICROBLAZE_64_TLSTPREL: howto manager. (line 2468) +* BFD_RELOC_MICROBLAZE_COPY: howto manager. (line 2445) +* BFD_RELOC_MICROMIPS_10_PCREL_S1: howto manager. (line 356) +* BFD_RELOC_MICROMIPS_16_PCREL_S1: howto manager. (line 357) +* BFD_RELOC_MICROMIPS_7_PCREL_S1: howto manager. (line 355) +* BFD_RELOC_MICROMIPS_CALL16: howto manager. (line 367) +* BFD_RELOC_MICROMIPS_CALL_HI16: howto manager. (line 373) +* BFD_RELOC_MICROMIPS_CALL_LO16: howto manager. (line 375) +* BFD_RELOC_MICROMIPS_GOT16: howto manager. (line 365) +* BFD_RELOC_MICROMIPS_GOT_DISP: howto manager. (line 383) +* BFD_RELOC_MICROMIPS_GOT_HI16: howto manager. (line 369) +* BFD_RELOC_MICROMIPS_GOT_LO16: howto manager. (line 371) +* BFD_RELOC_MICROMIPS_GOT_OFST: howto manager. (line 381) +* BFD_RELOC_MICROMIPS_GOT_PAGE: howto manager. (line 379) +* BFD_RELOC_MICROMIPS_GPREL16: howto manager. (line 359) +* BFD_RELOC_MICROMIPS_HI16: howto manager. (line 360) +* BFD_RELOC_MICROMIPS_HI16_S: howto manager. (line 361) +* BFD_RELOC_MICROMIPS_HIGHER: howto manager. (line 392) +* BFD_RELOC_MICROMIPS_HIGHEST: howto manager. (line 390) +* BFD_RELOC_MICROMIPS_JALR: howto manager. (line 398) +* BFD_RELOC_MICROMIPS_JMP: howto manager. (line 310) +* BFD_RELOC_MICROMIPS_LITERAL: howto manager. (line 353) +* BFD_RELOC_MICROMIPS_LO16: howto manager. (line 362) +* BFD_RELOC_MICROMIPS_SCN_DISP: howto manager. (line 394) +* BFD_RELOC_MICROMIPS_SUB: howto manager. (line 377) +* BFD_RELOC_MICROMIPS_TLS_DTPREL_HI16: howto manager. (line 408) +* BFD_RELOC_MICROMIPS_TLS_DTPREL_LO16: howto manager. (line 410) +* BFD_RELOC_MICROMIPS_TLS_GD: howto manager. (line 404) +* BFD_RELOC_MICROMIPS_TLS_GOTTPREL: howto manager. (line 412) +* BFD_RELOC_MICROMIPS_TLS_LDM: howto manager. (line 406) +* BFD_RELOC_MICROMIPS_TLS_TPREL_HI16: howto manager. (line 416) +* BFD_RELOC_MICROMIPS_TLS_TPREL_LO16: howto manager. (line 418) +* BFD_RELOC_MIPS16_CALL16: howto manager. (line 332) +* BFD_RELOC_MIPS16_GOT16: howto manager. (line 331) +* BFD_RELOC_MIPS16_GPREL: howto manager. (line 314) +* BFD_RELOC_MIPS16_HI16: howto manager. (line 335) +* BFD_RELOC_MIPS16_HI16_S: howto manager. (line 337) +* BFD_RELOC_MIPS16_JMP: howto manager. (line 312) +* BFD_RELOC_MIPS16_LO16: howto manager. (line 342) +* BFD_RELOC_MIPS16_TLS_DTPREL_HI16: howto manager. (line 346) +* BFD_RELOC_MIPS16_TLS_DTPREL_LO16: howto manager. (line 347) +* BFD_RELOC_MIPS16_TLS_GD: howto manager. (line 344) +* BFD_RELOC_MIPS16_TLS_GOTTPREL: howto manager. (line 348) +* BFD_RELOC_MIPS16_TLS_LDM: howto manager. (line 345) +* BFD_RELOC_MIPS16_TLS_TPREL_HI16: howto manager. (line 349) +* BFD_RELOC_MIPS16_TLS_TPREL_LO16: howto manager. (line 350) +* BFD_RELOC_MIPS_CALL16: howto manager. (line 366) +* BFD_RELOC_MIPS_CALL_HI16: howto manager. (line 372) +* BFD_RELOC_MIPS_CALL_LO16: howto manager. (line 374) +* BFD_RELOC_MIPS_COPY: howto manager. (line 421) +* BFD_RELOC_MIPS_DELETE: howto manager. (line 388) +* BFD_RELOC_MIPS_EH: howto manager. (line 419) +* BFD_RELOC_MIPS_GOT16: howto manager. (line 364) +* BFD_RELOC_MIPS_GOT_DISP: howto manager. (line 382) +* BFD_RELOC_MIPS_GOT_HI16: howto manager. (line 368) +* BFD_RELOC_MIPS_GOT_LO16: howto manager. (line 370) +* BFD_RELOC_MIPS_GOT_OFST: howto manager. (line 380) +* BFD_RELOC_MIPS_GOT_PAGE: howto manager. (line 378) +* BFD_RELOC_MIPS_HIGHER: howto manager. (line 391) +* BFD_RELOC_MIPS_HIGHEST: howto manager. (line 389) +* BFD_RELOC_MIPS_INSERT_A: howto manager. (line 386) +* BFD_RELOC_MIPS_INSERT_B: howto manager. (line 387) +* BFD_RELOC_MIPS_JALR: howto manager. (line 397) +* BFD_RELOC_MIPS_JMP: howto manager. (line 309) +* BFD_RELOC_MIPS_JUMP_SLOT: howto manager. (line 422) +* BFD_RELOC_MIPS_LITERAL: howto manager. (line 352) +* BFD_RELOC_MIPS_REL16: howto manager. (line 395) +* BFD_RELOC_MIPS_RELGOT: howto manager. (line 396) +* BFD_RELOC_MIPS_SCN_DISP: howto manager. (line 393) +* BFD_RELOC_MIPS_SHIFT5: howto manager. (line 384) +* BFD_RELOC_MIPS_SHIFT6: howto manager. (line 385) +* BFD_RELOC_MIPS_SUB: howto manager. (line 376) +* BFD_RELOC_MIPS_TLS_DTPMOD32: howto manager. (line 399) +* BFD_RELOC_MIPS_TLS_DTPMOD64: howto manager. (line 401) +* BFD_RELOC_MIPS_TLS_DTPREL32: howto manager. (line 400) +* BFD_RELOC_MIPS_TLS_DTPREL64: howto manager. (line 402) +* BFD_RELOC_MIPS_TLS_DTPREL_HI16: howto manager. (line 407) +* BFD_RELOC_MIPS_TLS_DTPREL_LO16: howto manager. (line 409) +* BFD_RELOC_MIPS_TLS_GD: howto manager. (line 403) +* BFD_RELOC_MIPS_TLS_GOTTPREL: howto manager. (line 411) +* BFD_RELOC_MIPS_TLS_LDM: howto manager. (line 405) +* BFD_RELOC_MIPS_TLS_TPREL32: howto manager. (line 413) +* BFD_RELOC_MIPS_TLS_TPREL64: howto manager. (line 414) +* BFD_RELOC_MIPS_TLS_TPREL_HI16: howto manager. (line 415) +* BFD_RELOC_MIPS_TLS_TPREL_LO16: howto manager. (line 417) +* BFD_RELOC_MMIX_ADDR19: howto manager. (line 1533) +* BFD_RELOC_MMIX_ADDR27: howto manager. (line 1536) +* BFD_RELOC_MMIX_BASE_PLUS_OFFSET: howto manager. (line 1545) +* BFD_RELOC_MMIX_CBRANCH: howto manager. (line 1516) +* BFD_RELOC_MMIX_CBRANCH_1: howto manager. (line 1518) +* BFD_RELOC_MMIX_CBRANCH_2: howto manager. (line 1519) +* BFD_RELOC_MMIX_CBRANCH_3: howto manager. (line 1520) +* BFD_RELOC_MMIX_CBRANCH_J: howto manager. (line 1517) +* BFD_RELOC_MMIX_GETA: howto manager. (line 1511) +* BFD_RELOC_MMIX_GETA_1: howto manager. (line 1512) +* BFD_RELOC_MMIX_GETA_2: howto manager. (line 1513) +* BFD_RELOC_MMIX_GETA_3: howto manager. (line 1514) +* BFD_RELOC_MMIX_JMP: howto manager. (line 1528) +* BFD_RELOC_MMIX_JMP_1: howto manager. (line 1529) +* BFD_RELOC_MMIX_JMP_2: howto manager. (line 1530) +* BFD_RELOC_MMIX_JMP_3: howto manager. (line 1531) +* BFD_RELOC_MMIX_LOCAL: howto manager. (line 1548) +* BFD_RELOC_MMIX_PUSHJ: howto manager. (line 1522) +* BFD_RELOC_MMIX_PUSHJ_1: howto manager. (line 1523) +* BFD_RELOC_MMIX_PUSHJ_2: howto manager. (line 1524) +* BFD_RELOC_MMIX_PUSHJ_3: howto manager. (line 1525) +* BFD_RELOC_MMIX_PUSHJ_STUBBABLE: howto manager. (line 1526) +* BFD_RELOC_MMIX_REG: howto manager. (line 1542) +* BFD_RELOC_MMIX_REG_OR_BYTE: howto manager. (line 1539) +* BFD_RELOC_MN10300_16_PCREL: howto manager. (line 505) +* BFD_RELOC_MN10300_32_PCREL: howto manager. (line 502) +* BFD_RELOC_MN10300_ALIGN: howto manager. (line 489) +* BFD_RELOC_MN10300_COPY: howto manager. (line 477) +* BFD_RELOC_MN10300_GLOB_DAT: howto manager. (line 479) +* BFD_RELOC_MN10300_GOT16: howto manager. (line 474) +* BFD_RELOC_MN10300_GOT24: howto manager. (line 471) +* BFD_RELOC_MN10300_GOT32: howto manager. (line 468) +* BFD_RELOC_MN10300_GOTOFF24: howto manager. (line 466) +* BFD_RELOC_MN10300_JMP_SLOT: howto manager. (line 481) +* BFD_RELOC_MN10300_RELATIVE: howto manager. (line 483) +* BFD_RELOC_MN10300_SYM_DIFF: howto manager. (line 485) +* BFD_RELOC_MN10300_TLS_DTPMOD: howto manager. (line 498) +* BFD_RELOC_MN10300_TLS_DTPOFF: howto manager. (line 499) +* BFD_RELOC_MN10300_TLS_GD: howto manager. (line 492) +* BFD_RELOC_MN10300_TLS_GOTIE: howto manager. (line 495) +* BFD_RELOC_MN10300_TLS_IE: howto manager. (line 496) +* BFD_RELOC_MN10300_TLS_LD: howto manager. (line 493) +* BFD_RELOC_MN10300_TLS_LDO: howto manager. (line 494) +* BFD_RELOC_MN10300_TLS_LE: howto manager. (line 497) +* BFD_RELOC_MN10300_TLS_TPOFF: howto manager. (line 500) +* BFD_RELOC_MOXIE_10_PCREL: howto manager. (line 424) +* BFD_RELOC_MSP430X_ABS16: howto manager. (line 2242) +* BFD_RELOC_MSP430X_ABS20_ADR_DST: howto manager. (line 2239) +* BFD_RELOC_MSP430X_ABS20_ADR_SRC: howto manager. (line 2238) +* BFD_RELOC_MSP430X_ABS20_EXT_DST: howto manager. (line 2236) +* BFD_RELOC_MSP430X_ABS20_EXT_ODST: howto manager. (line 2237) +* BFD_RELOC_MSP430X_ABS20_EXT_SRC: howto manager. (line 2235) +* BFD_RELOC_MSP430X_PCR16: howto manager. (line 2240) +* BFD_RELOC_MSP430X_PCR20_CALL: howto manager. (line 2241) +* BFD_RELOC_MSP430X_PCR20_EXT_DST: howto manager. (line 2233) +* BFD_RELOC_MSP430X_PCR20_EXT_ODST: howto manager. (line 2234) +* BFD_RELOC_MSP430X_PCR20_EXT_SRC: howto manager. (line 2232) +* BFD_RELOC_MSP430_10_PCREL: howto manager. (line 2224) +* BFD_RELOC_MSP430_16: howto manager. (line 2226) +* BFD_RELOC_MSP430_16_BYTE: howto manager. (line 2228) +* BFD_RELOC_MSP430_16_PCREL: howto manager. (line 2225) +* BFD_RELOC_MSP430_16_PCREL_BYTE: howto manager. (line 2227) +* BFD_RELOC_MSP430_2X_PCREL: howto manager. (line 2229) +* BFD_RELOC_MSP430_ABS8: howto manager. (line 2231) +* BFD_RELOC_MSP430_ABS_HI16: howto manager. (line 2243) +* BFD_RELOC_MSP430_PREL31: howto manager. (line 2244) +* BFD_RELOC_MSP430_RL_PCREL: howto manager. (line 2230) +* BFD_RELOC_MSP430_SYM_DIFF: howto manager. (line 2245) +* BFD_RELOC_MT_GNU_VTENTRY: howto manager. (line 2220) +* BFD_RELOC_MT_GNU_VTINHERIT: howto manager. (line 2218) +* BFD_RELOC_MT_HI16: howto manager. (line 2214) +* BFD_RELOC_MT_LO16: howto manager. (line 2216) +* BFD_RELOC_MT_PC16: howto manager. (line 2212) +* BFD_RELOC_MT_PCINSN8: howto manager. (line 2222) +* BFD_RELOC_NDS32_10IFCU_PCREL: howto manager. (line 1275) +* BFD_RELOC_NDS32_10_UPCREL: howto manager. (line 1249) +* BFD_RELOC_NDS32_15_FIXED: howto manager. (line 1217) +* BFD_RELOC_NDS32_15_PCREL: howto manager. (line 1143) +* BFD_RELOC_NDS32_17IFC_PCREL: howto manager. (line 1274) +* BFD_RELOC_NDS32_17_FIXED: howto manager. (line 1218) +* BFD_RELOC_NDS32_17_PCREL: howto manager. (line 1145) +* BFD_RELOC_NDS32_20: howto manager. (line 1135) +* BFD_RELOC_NDS32_25_ABS: howto manager. (line 1271) +* BFD_RELOC_NDS32_25_FIXED: howto manager. (line 1219) +* BFD_RELOC_NDS32_25_PCREL: howto manager. (line 1147) +* BFD_RELOC_NDS32_25_PLTREL: howto manager. (line 1193) +* BFD_RELOC_NDS32_5: howto manager. (line 1247) +* BFD_RELOC_NDS32_9_FIXED: howto manager. (line 1216) +* BFD_RELOC_NDS32_9_PCREL: howto manager. (line 1137) +* BFD_RELOC_NDS32_9_PLTREL: howto manager. (line 1192) +* BFD_RELOC_NDS32_COPY: howto manager. (line 1194) +* BFD_RELOC_NDS32_DATA: howto manager. (line 1272) +* BFD_RELOC_NDS32_DIFF16: howto manager. (line 1268) +* BFD_RELOC_NDS32_DIFF32: howto manager. (line 1269) +* BFD_RELOC_NDS32_DIFF8: howto manager. (line 1267) +* BFD_RELOC_NDS32_DIFF_ULEB128: howto manager. (line 1270) +* BFD_RELOC_NDS32_DWARF2_LEB: howto manager. (line 1233) +* BFD_RELOC_NDS32_DWARF2_OP1: howto manager. (line 1231) +* BFD_RELOC_NDS32_DWARF2_OP2: howto manager. (line 1232) +* BFD_RELOC_NDS32_GLOB_DAT: howto manager. (line 1195) +* BFD_RELOC_NDS32_GOT15S2: howto manager. (line 1244) +* BFD_RELOC_NDS32_GOT17S2: howto manager. (line 1245) +* BFD_RELOC_NDS32_GOT20: howto manager. (line 1191) +* BFD_RELOC_NDS32_GOTOFF: howto manager. (line 1198) +* BFD_RELOC_NDS32_GOTOFF_HI20: howto manager. (line 1199) +* BFD_RELOC_NDS32_GOTOFF_LO12: howto manager. (line 1200) +* BFD_RELOC_NDS32_GOTOFF_LO15: howto manager. (line 1242) +* BFD_RELOC_NDS32_GOTOFF_LO19: howto manager. (line 1243) +* BFD_RELOC_NDS32_GOTOFF_SUFF: howto manager. (line 1256) +* BFD_RELOC_NDS32_GOTPC20: howto manager. (line 1201) +* BFD_RELOC_NDS32_GOTPC_HI20: howto manager. (line 1204) +* BFD_RELOC_NDS32_GOTPC_LO12: howto manager. (line 1205) +* BFD_RELOC_NDS32_GOT_HI20: howto manager. (line 1202) +* BFD_RELOC_NDS32_GOT_LO12: howto manager. (line 1203) +* BFD_RELOC_NDS32_GOT_LO15: howto manager. (line 1240) +* BFD_RELOC_NDS32_GOT_LO19: howto manager. (line 1241) +* BFD_RELOC_NDS32_GOT_SUFF: howto manager. (line 1255) +* BFD_RELOC_NDS32_HI20: howto manager. (line 1149) +* BFD_RELOC_NDS32_INSN16: howto manager. (line 1207) +* BFD_RELOC_NDS32_JMP_SLOT: howto manager. (line 1196) +* BFD_RELOC_NDS32_LABEL: howto manager. (line 1208) +* BFD_RELOC_NDS32_LO12S0: howto manager. (line 1161) +* BFD_RELOC_NDS32_LO12S0_ORI: howto manager. (line 1164) +* BFD_RELOC_NDS32_LO12S1: howto manager. (line 1158) +* BFD_RELOC_NDS32_LO12S2: howto manager. (line 1155) +* BFD_RELOC_NDS32_LO12S2_DP: howto manager. (line 1228) +* BFD_RELOC_NDS32_LO12S2_SP: howto manager. (line 1229) +* BFD_RELOC_NDS32_LO12S3: howto manager. (line 1152) +* BFD_RELOC_NDS32_LOADSTORE: howto manager. (line 1215) +* BFD_RELOC_NDS32_LONGCALL1: howto manager. (line 1209) +* BFD_RELOC_NDS32_LONGCALL2: howto manager. (line 1210) +* BFD_RELOC_NDS32_LONGCALL3: howto manager. (line 1211) +* BFD_RELOC_NDS32_LONGJUMP1: howto manager. (line 1212) +* BFD_RELOC_NDS32_LONGJUMP2: howto manager. (line 1213) +* BFD_RELOC_NDS32_LONGJUMP3: howto manager. (line 1214) +* BFD_RELOC_NDS32_MINUEND: howto manager. (line 1265) +* BFD_RELOC_NDS32_MULCALL_SUFF: howto manager. (line 1258) +* BFD_RELOC_NDS32_PLTBLOCK: howto manager. (line 1262) +* BFD_RELOC_NDS32_PLTREL_HI20: howto manager. (line 1221) +* BFD_RELOC_NDS32_PLTREL_LO12: howto manager. (line 1222) +* BFD_RELOC_NDS32_PLT_GOTREL_HI20: howto manager. (line 1223) +* BFD_RELOC_NDS32_PLT_GOTREL_LO12: howto manager. (line 1224) +* BFD_RELOC_NDS32_PLT_GOTREL_LO15: howto manager. (line 1238) +* BFD_RELOC_NDS32_PLT_GOTREL_LO19: howto manager. (line 1239) +* BFD_RELOC_NDS32_PLT_GOTREL_LO20: howto manager. (line 1237) +* BFD_RELOC_NDS32_PLT_GOT_SUFF: howto manager. (line 1257) +* BFD_RELOC_NDS32_PTR: howto manager. (line 1259) +* BFD_RELOC_NDS32_PTR_COUNT: howto manager. (line 1260) +* BFD_RELOC_NDS32_PTR_RESOLVED: howto manager. (line 1261) +* BFD_RELOC_NDS32_RELATIVE: howto manager. (line 1197) +* BFD_RELOC_NDS32_RELAX_ENTRY: howto manager. (line 1254) +* BFD_RELOC_NDS32_RELAX_REGION_BEGIN: howto manager. (line 1263) +* BFD_RELOC_NDS32_RELAX_REGION_END: howto manager. (line 1264) +* BFD_RELOC_NDS32_SDA12S2_DP: howto manager. (line 1226) +* BFD_RELOC_NDS32_SDA12S2_SP: howto manager. (line 1227) +* BFD_RELOC_NDS32_SDA15S0: howto manager. (line 1176) +* BFD_RELOC_NDS32_SDA15S1: howto manager. (line 1173) +* BFD_RELOC_NDS32_SDA15S2: howto manager. (line 1170) +* BFD_RELOC_NDS32_SDA15S3: howto manager. (line 1167) +* BFD_RELOC_NDS32_SDA16S3: howto manager. (line 1179) +* BFD_RELOC_NDS32_SDA17S2: howto manager. (line 1182) +* BFD_RELOC_NDS32_SDA18S1: howto manager. (line 1185) +* BFD_RELOC_NDS32_SDA19S0: howto manager. (line 1188) +* BFD_RELOC_NDS32_SDA_FP7U2_RELA: howto manager. (line 1252) +* BFD_RELOC_NDS32_SUBTRAHEND: howto manager. (line 1266) +* BFD_RELOC_NDS32_TRAN: howto manager. (line 1273) +* BFD_RELOC_NDS32_UPDATE_TA: howto manager. (line 1235) +* BFD_RELOC_NDS32_WORD_9_PCREL: howto manager. (line 1140) +* BFD_RELOC_NIOS2_ALIGN: howto manager. (line 2261) +* BFD_RELOC_NIOS2_CACHE_OPX: howto manager. (line 2251) +* BFD_RELOC_NIOS2_CALL16: howto manager. (line 2263) +* BFD_RELOC_NIOS2_CALL26: howto manager. (line 2249) +* BFD_RELOC_NIOS2_CALLR: howto manager. (line 2260) +* BFD_RELOC_NIOS2_CJMP: howto manager. (line 2259) +* BFD_RELOC_NIOS2_COPY: howto manager. (line 2276) +* BFD_RELOC_NIOS2_GLOB_DAT: howto manager. (line 2277) +* BFD_RELOC_NIOS2_GOT16: howto manager. (line 2262) +* BFD_RELOC_NIOS2_GOTOFF: howto manager. (line 2280) +* BFD_RELOC_NIOS2_GOTOFF_HA: howto manager. (line 2265) +* BFD_RELOC_NIOS2_GOTOFF_LO: howto manager. (line 2264) +* BFD_RELOC_NIOS2_GPREL: howto manager. (line 2257) +* BFD_RELOC_NIOS2_HI16: howto manager. (line 2254) +* BFD_RELOC_NIOS2_HIADJ16: howto manager. (line 2256) +* BFD_RELOC_NIOS2_IMM5: howto manager. (line 2250) +* BFD_RELOC_NIOS2_IMM6: howto manager. (line 2252) +* BFD_RELOC_NIOS2_IMM8: howto manager. (line 2253) +* BFD_RELOC_NIOS2_JUMP_SLOT: howto manager. (line 2278) +* BFD_RELOC_NIOS2_LO16: howto manager. (line 2255) +* BFD_RELOC_NIOS2_PCREL_HA: howto manager. (line 2267) +* BFD_RELOC_NIOS2_PCREL_LO: howto manager. (line 2266) +* BFD_RELOC_NIOS2_RELATIVE: howto manager. (line 2279) +* BFD_RELOC_NIOS2_S16: howto manager. (line 2247) +* BFD_RELOC_NIOS2_TLS_DTPMOD: howto manager. (line 2273) +* BFD_RELOC_NIOS2_TLS_DTPREL: howto manager. (line 2274) +* BFD_RELOC_NIOS2_TLS_GD16: howto manager. (line 2268) +* BFD_RELOC_NIOS2_TLS_IE16: howto manager. (line 2271) +* BFD_RELOC_NIOS2_TLS_LDM16: howto manager. (line 2269) +* BFD_RELOC_NIOS2_TLS_LDO16: howto manager. (line 2270) +* BFD_RELOC_NIOS2_TLS_LE16: howto manager. (line 2272) +* BFD_RELOC_NIOS2_TLS_TPREL: howto manager. (line 2275) +* BFD_RELOC_NIOS2_U16: howto manager. (line 2248) +* BFD_RELOC_NIOS2_UJMP: howto manager. (line 2258) +* BFD_RELOC_NONE: howto manager. (line 122) +* BFD_RELOC_NS32K_DISP_16: howto manager. (line 570) +* BFD_RELOC_NS32K_DISP_16_PCREL: howto manager. (line 573) +* BFD_RELOC_NS32K_DISP_32: howto manager. (line 571) +* BFD_RELOC_NS32K_DISP_32_PCREL: howto manager. (line 574) +* BFD_RELOC_NS32K_DISP_8: howto manager. (line 569) +* BFD_RELOC_NS32K_DISP_8_PCREL: howto manager. (line 572) +* BFD_RELOC_NS32K_IMM_16: howto manager. (line 564) +* BFD_RELOC_NS32K_IMM_16_PCREL: howto manager. (line 567) +* BFD_RELOC_NS32K_IMM_32: howto manager. (line 565) +* BFD_RELOC_NS32K_IMM_32_PCREL: howto manager. (line 568) +* BFD_RELOC_NS32K_IMM_8: howto manager. (line 563) +* BFD_RELOC_NS32K_IMM_8_PCREL: howto manager. (line 566) +* BFD_RELOC_OPENRISC_ABS_26: howto manager. (line 2186) +* BFD_RELOC_OPENRISC_REL_26: howto manager. (line 2187) +* BFD_RELOC_PDP11_DISP_6_PCREL: howto manager. (line 577) +* BFD_RELOC_PDP11_DISP_8_PCREL: howto manager. (line 576) +* BFD_RELOC_PJ_CODE_DIR16: howto manager. (line 581) +* BFD_RELOC_PJ_CODE_DIR32: howto manager. (line 582) +* BFD_RELOC_PJ_CODE_HI16: howto manager. (line 579) +* BFD_RELOC_PJ_CODE_LO16: howto manager. (line 580) +* BFD_RELOC_PJ_CODE_REL16: howto manager. (line 583) +* BFD_RELOC_PJ_CODE_REL32: howto manager. (line 584) +* BFD_RELOC_PPC64_ADDR16_DS: howto manager. (line 645) +* BFD_RELOC_PPC64_ADDR16_HIGH: howto manager. (line 656) +* BFD_RELOC_PPC64_ADDR16_HIGHA: howto manager. (line 657) +* BFD_RELOC_PPC64_ADDR16_LO_DS: howto manager. (line 646) +* BFD_RELOC_PPC64_DTPREL16_DS: howto manager. (line 695) +* BFD_RELOC_PPC64_DTPREL16_HIGH: howto manager. (line 703) +* BFD_RELOC_PPC64_DTPREL16_HIGHA: howto manager. (line 704) +* BFD_RELOC_PPC64_DTPREL16_HIGHER: howto manager. (line 697) +* BFD_RELOC_PPC64_DTPREL16_HIGHERA: howto manager. (line 698) +* BFD_RELOC_PPC64_DTPREL16_HIGHEST: howto manager. (line 699) +* BFD_RELOC_PPC64_DTPREL16_HIGHESTA: howto manager. (line 700) +* BFD_RELOC_PPC64_DTPREL16_LO_DS: howto manager. (line 696) +* BFD_RELOC_PPC64_GOT16_DS: howto manager. (line 647) +* BFD_RELOC_PPC64_GOT16_LO_DS: howto manager. (line 648) +* BFD_RELOC_PPC64_HIGHER: howto manager. (line 633) +* BFD_RELOC_PPC64_HIGHER_S: howto manager. (line 634) +* BFD_RELOC_PPC64_HIGHEST: howto manager. (line 635) +* BFD_RELOC_PPC64_HIGHEST_S: howto manager. (line 636) +* BFD_RELOC_PPC64_PLT16_LO_DS: howto manager. (line 649) +* BFD_RELOC_PPC64_PLTGOT16: howto manager. (line 641) +* BFD_RELOC_PPC64_PLTGOT16_DS: howto manager. (line 654) +* BFD_RELOC_PPC64_PLTGOT16_HA: howto manager. (line 644) +* BFD_RELOC_PPC64_PLTGOT16_HI: howto manager. (line 643) +* BFD_RELOC_PPC64_PLTGOT16_LO: howto manager. (line 642) +* BFD_RELOC_PPC64_PLTGOT16_LO_DS: howto manager. (line 655) +* BFD_RELOC_PPC64_SECTOFF_DS: howto manager. (line 650) +* BFD_RELOC_PPC64_SECTOFF_LO_DS: howto manager. (line 651) +* BFD_RELOC_PPC64_TOC: howto manager. (line 640) +* BFD_RELOC_PPC64_TOC16_DS: howto manager. (line 652) +* BFD_RELOC_PPC64_TOC16_HA: howto manager. (line 639) +* BFD_RELOC_PPC64_TOC16_HI: howto manager. (line 638) +* BFD_RELOC_PPC64_TOC16_LO: howto manager. (line 637) +* BFD_RELOC_PPC64_TOC16_LO_DS: howto manager. (line 653) +* BFD_RELOC_PPC64_TPREL16_DS: howto manager. (line 689) +* BFD_RELOC_PPC64_TPREL16_HIGH: howto manager. (line 701) +* BFD_RELOC_PPC64_TPREL16_HIGHA: howto manager. (line 702) +* BFD_RELOC_PPC64_TPREL16_HIGHER: howto manager. (line 691) +* BFD_RELOC_PPC64_TPREL16_HIGHERA: howto manager. (line 692) +* BFD_RELOC_PPC64_TPREL16_HIGHEST: howto manager. (line 693) +* BFD_RELOC_PPC64_TPREL16_HIGHESTA: howto manager. (line 694) +* BFD_RELOC_PPC64_TPREL16_LO_DS: howto manager. (line 690) +* BFD_RELOC_PPC_B16: howto manager. (line 589) +* BFD_RELOC_PPC_B16_BRNTAKEN: howto manager. (line 591) +* BFD_RELOC_PPC_B16_BRTAKEN: howto manager. (line 590) +* BFD_RELOC_PPC_B26: howto manager. (line 586) +* BFD_RELOC_PPC_BA16: howto manager. (line 592) +* BFD_RELOC_PPC_BA16_BRNTAKEN: howto manager. (line 594) +* BFD_RELOC_PPC_BA16_BRTAKEN: howto manager. (line 593) +* BFD_RELOC_PPC_BA26: howto manager. (line 587) +* BFD_RELOC_PPC_COPY: howto manager. (line 595) +* BFD_RELOC_PPC_DTPMOD: howto manager. (line 662) +* BFD_RELOC_PPC_DTPREL: howto manager. (line 672) +* BFD_RELOC_PPC_DTPREL16: howto manager. (line 668) +* BFD_RELOC_PPC_DTPREL16_HA: howto manager. (line 671) +* BFD_RELOC_PPC_DTPREL16_HI: howto manager. (line 670) +* BFD_RELOC_PPC_DTPREL16_LO: howto manager. (line 669) +* BFD_RELOC_PPC_EMB_BIT_FLD: howto manager. (line 614) +* BFD_RELOC_PPC_EMB_MRKREF: howto manager. (line 609) +* BFD_RELOC_PPC_EMB_NADDR16: howto manager. (line 601) +* BFD_RELOC_PPC_EMB_NADDR16_HA: howto manager. (line 604) +* BFD_RELOC_PPC_EMB_NADDR16_HI: howto manager. (line 603) +* BFD_RELOC_PPC_EMB_NADDR16_LO: howto manager. (line 602) +* BFD_RELOC_PPC_EMB_NADDR32: howto manager. (line 600) +* BFD_RELOC_PPC_EMB_RELSDA: howto manager. (line 615) +* BFD_RELOC_PPC_EMB_RELSEC16: howto manager. (line 610) +* BFD_RELOC_PPC_EMB_RELST_HA: howto manager. (line 613) +* BFD_RELOC_PPC_EMB_RELST_HI: howto manager. (line 612) +* BFD_RELOC_PPC_EMB_RELST_LO: howto manager. (line 611) +* BFD_RELOC_PPC_EMB_SDA21: howto manager. (line 608) +* BFD_RELOC_PPC_EMB_SDA2I16: howto manager. (line 606) +* BFD_RELOC_PPC_EMB_SDA2REL: howto manager. (line 607) +* BFD_RELOC_PPC_EMB_SDAI16: howto manager. (line 605) +* BFD_RELOC_PPC_GLOB_DAT: howto manager. (line 596) +* BFD_RELOC_PPC_GOT_DTPREL16: howto manager. (line 685) +* BFD_RELOC_PPC_GOT_DTPREL16_HA: howto manager. (line 688) +* BFD_RELOC_PPC_GOT_DTPREL16_HI: howto manager. (line 687) +* BFD_RELOC_PPC_GOT_DTPREL16_LO: howto manager. (line 686) +* BFD_RELOC_PPC_GOT_TLSGD16: howto manager. (line 673) +* BFD_RELOC_PPC_GOT_TLSGD16_HA: howto manager. (line 676) +* BFD_RELOC_PPC_GOT_TLSGD16_HI: howto manager. (line 675) +* BFD_RELOC_PPC_GOT_TLSGD16_LO: howto manager. (line 674) +* BFD_RELOC_PPC_GOT_TLSLD16: howto manager. (line 677) +* BFD_RELOC_PPC_GOT_TLSLD16_HA: howto manager. (line 680) +* BFD_RELOC_PPC_GOT_TLSLD16_HI: howto manager. (line 679) +* BFD_RELOC_PPC_GOT_TLSLD16_LO: howto manager. (line 678) +* BFD_RELOC_PPC_GOT_TPREL16: howto manager. (line 681) +* BFD_RELOC_PPC_GOT_TPREL16_HA: howto manager. (line 684) +* BFD_RELOC_PPC_GOT_TPREL16_HI: howto manager. (line 683) +* BFD_RELOC_PPC_GOT_TPREL16_LO: howto manager. (line 682) +* BFD_RELOC_PPC_JMP_SLOT: howto manager. (line 597) +* BFD_RELOC_PPC_LOCAL24PC: howto manager. (line 599) +* BFD_RELOC_PPC_RELATIVE: howto manager. (line 598) +* BFD_RELOC_PPC_TLS: howto manager. (line 659) +* BFD_RELOC_PPC_TLSGD: howto manager. (line 660) +* BFD_RELOC_PPC_TLSLD: howto manager. (line 661) +* BFD_RELOC_PPC_TOC16: howto manager. (line 588) +* BFD_RELOC_PPC_TPREL: howto manager. (line 667) +* BFD_RELOC_PPC_TPREL16: howto manager. (line 663) +* BFD_RELOC_PPC_TPREL16_HA: howto manager. (line 666) +* BFD_RELOC_PPC_TPREL16_HI: howto manager. (line 665) +* BFD_RELOC_PPC_TPREL16_LO: howto manager. (line 664) +* BFD_RELOC_PPC_VLE_HA16A: howto manager. (line 623) +* BFD_RELOC_PPC_VLE_HA16D: howto manager. (line 624) +* BFD_RELOC_PPC_VLE_HI16A: howto manager. (line 621) +* BFD_RELOC_PPC_VLE_HI16D: howto manager. (line 622) +* BFD_RELOC_PPC_VLE_LO16A: howto manager. (line 619) +* BFD_RELOC_PPC_VLE_LO16D: howto manager. (line 620) +* BFD_RELOC_PPC_VLE_REL15: howto manager. (line 617) +* BFD_RELOC_PPC_VLE_REL24: howto manager. (line 618) +* BFD_RELOC_PPC_VLE_REL8: howto manager. (line 616) +* BFD_RELOC_PPC_VLE_SDA21: howto manager. (line 625) +* BFD_RELOC_PPC_VLE_SDA21_LO: howto manager. (line 626) +* BFD_RELOC_PPC_VLE_SDAREL_HA16A: howto manager. (line 631) +* BFD_RELOC_PPC_VLE_SDAREL_HA16D: howto manager. (line 632) +* BFD_RELOC_PPC_VLE_SDAREL_HI16A: howto manager. (line 629) +* BFD_RELOC_PPC_VLE_SDAREL_HI16D: howto manager. (line 630) +* BFD_RELOC_PPC_VLE_SDAREL_LO16A: howto manager. (line 627) +* BFD_RELOC_PPC_VLE_SDAREL_LO16D: howto manager. (line 628) +* BFD_RELOC_RELC: howto manager. (line 2201) +* BFD_RELOC_RL78_16U: howto manager. (line 1648) +* BFD_RELOC_RL78_16_OP: howto manager. (line 1644) +* BFD_RELOC_RL78_24U: howto manager. (line 1649) +* BFD_RELOC_RL78_24_OP: howto manager. (line 1645) +* BFD_RELOC_RL78_32_OP: howto manager. (line 1646) +* BFD_RELOC_RL78_8U: howto manager. (line 1647) +* BFD_RELOC_RL78_ABS16: howto manager. (line 1661) +* BFD_RELOC_RL78_ABS16U: howto manager. (line 1665) +* BFD_RELOC_RL78_ABS16UL: howto manager. (line 1667) +* BFD_RELOC_RL78_ABS16UW: howto manager. (line 1666) +* BFD_RELOC_RL78_ABS16_REV: howto manager. (line 1662) +* BFD_RELOC_RL78_ABS32: howto manager. (line 1663) +* BFD_RELOC_RL78_ABS32_REV: howto manager. (line 1664) +* BFD_RELOC_RL78_ABS8: howto manager. (line 1660) +* BFD_RELOC_RL78_CODE: howto manager. (line 1672) +* BFD_RELOC_RL78_DIFF: howto manager. (line 1651) +* BFD_RELOC_RL78_DIR3U_PCREL: howto manager. (line 1650) +* BFD_RELOC_RL78_GPRELB: howto manager. (line 1652) +* BFD_RELOC_RL78_GPRELL: howto manager. (line 1654) +* BFD_RELOC_RL78_GPRELW: howto manager. (line 1653) +* BFD_RELOC_RL78_HI16: howto manager. (line 1669) +* BFD_RELOC_RL78_HI8: howto manager. (line 1670) +* BFD_RELOC_RL78_LO16: howto manager. (line 1671) +* BFD_RELOC_RL78_NEG16: howto manager. (line 1641) +* BFD_RELOC_RL78_NEG24: howto manager. (line 1642) +* BFD_RELOC_RL78_NEG32: howto manager. (line 1643) +* BFD_RELOC_RL78_NEG8: howto manager. (line 1640) +* BFD_RELOC_RL78_OP_AND: howto manager. (line 1658) +* BFD_RELOC_RL78_OP_NEG: howto manager. (line 1657) +* BFD_RELOC_RL78_OP_SHRA: howto manager. (line 1659) +* BFD_RELOC_RL78_OP_SUBTRACT: howto manager. (line 1656) +* BFD_RELOC_RL78_RELAX: howto manager. (line 1668) +* BFD_RELOC_RL78_SYM: howto manager. (line 1655) +* BFD_RELOC_RVA: howto manager. (line 97) +* BFD_RELOC_RX_16U: howto manager. (line 1682) +* BFD_RELOC_RX_16_OP: howto manager. (line 1678) +* BFD_RELOC_RX_24U: howto manager. (line 1683) +* BFD_RELOC_RX_24_OP: howto manager. (line 1679) +* BFD_RELOC_RX_32_OP: howto manager. (line 1680) +* BFD_RELOC_RX_8U: howto manager. (line 1681) +* BFD_RELOC_RX_ABS16: howto manager. (line 1693) +* BFD_RELOC_RX_ABS16U: howto manager. (line 1697) +* BFD_RELOC_RX_ABS16UL: howto manager. (line 1699) +* BFD_RELOC_RX_ABS16UW: howto manager. (line 1698) +* BFD_RELOC_RX_ABS16_REV: howto manager. (line 1694) +* BFD_RELOC_RX_ABS32: howto manager. (line 1695) +* BFD_RELOC_RX_ABS32_REV: howto manager. (line 1696) +* BFD_RELOC_RX_ABS8: howto manager. (line 1692) +* BFD_RELOC_RX_DIFF: howto manager. (line 1685) +* BFD_RELOC_RX_DIR3U_PCREL: howto manager. (line 1684) +* BFD_RELOC_RX_GPRELB: howto manager. (line 1686) +* BFD_RELOC_RX_GPRELL: howto manager. (line 1688) +* BFD_RELOC_RX_GPRELW: howto manager. (line 1687) +* BFD_RELOC_RX_NEG16: howto manager. (line 1675) +* BFD_RELOC_RX_NEG24: howto manager. (line 1676) +* BFD_RELOC_RX_NEG32: howto manager. (line 1677) +* BFD_RELOC_RX_NEG8: howto manager. (line 1674) +* BFD_RELOC_RX_OP_NEG: howto manager. (line 1691) +* BFD_RELOC_RX_OP_SUBTRACT: howto manager. (line 1690) +* BFD_RELOC_RX_RELAX: howto manager. (line 1700) +* BFD_RELOC_RX_SYM: howto manager. (line 1689) +* BFD_RELOC_SCORE16_BRANCH: howto manager. (line 1803) +* BFD_RELOC_SCORE16_JMP: howto manager. (line 1801) +* BFD_RELOC_SCORE_BCMP: howto manager. (line 1805) +* BFD_RELOC_SCORE_BRANCH: howto manager. (line 1795) +* BFD_RELOC_SCORE_CALL15: howto manager. (line 1809) +* BFD_RELOC_SCORE_DUMMY2: howto manager. (line 1792) +* BFD_RELOC_SCORE_DUMMY_HI16: howto manager. (line 1810) +* BFD_RELOC_SCORE_GOT15: howto manager. (line 1807) +* BFD_RELOC_SCORE_GOT_LO16: howto manager. (line 1808) +* BFD_RELOC_SCORE_GPREL15: howto manager. (line 1790) +* BFD_RELOC_SCORE_IMM30: howto manager. (line 1797) +* BFD_RELOC_SCORE_IMM32: howto manager. (line 1799) +* BFD_RELOC_SCORE_JMP: howto manager. (line 1793) +* BFD_RELOC_SH_ALIGN: howto manager. (line 875) +* BFD_RELOC_SH_CODE: howto manager. (line 876) +* BFD_RELOC_SH_COPY: howto manager. (line 881) +* BFD_RELOC_SH_COPY64: howto manager. (line 906) +* BFD_RELOC_SH_COUNT: howto manager. (line 874) +* BFD_RELOC_SH_DATA: howto manager. (line 877) +* BFD_RELOC_SH_DISP12: howto manager. (line 857) +* BFD_RELOC_SH_DISP12BY2: howto manager. (line 858) +* BFD_RELOC_SH_DISP12BY4: howto manager. (line 859) +* BFD_RELOC_SH_DISP12BY8: howto manager. (line 860) +* BFD_RELOC_SH_DISP20: howto manager. (line 861) +* BFD_RELOC_SH_DISP20BY8: howto manager. (line 862) +* BFD_RELOC_SH_FUNCDESC: howto manager. (line 949) +* BFD_RELOC_SH_GLOB_DAT: howto manager. (line 882) +* BFD_RELOC_SH_GLOB_DAT64: howto manager. (line 907) +* BFD_RELOC_SH_GOT10BY4: howto manager. (line 910) +* BFD_RELOC_SH_GOT10BY8: howto manager. (line 911) +* BFD_RELOC_SH_GOT20: howto manager. (line 943) +* BFD_RELOC_SH_GOTFUNCDESC: howto manager. (line 945) +* BFD_RELOC_SH_GOTFUNCDESC20: howto manager. (line 946) +* BFD_RELOC_SH_GOTOFF20: howto manager. (line 944) +* BFD_RELOC_SH_GOTOFFFUNCDESC: howto manager. (line 947) +* BFD_RELOC_SH_GOTOFFFUNCDESC20: howto manager. (line 948) +* BFD_RELOC_SH_GOTOFF_HI16: howto manager. (line 901) +* BFD_RELOC_SH_GOTOFF_LOW16: howto manager. (line 898) +* BFD_RELOC_SH_GOTOFF_MEDHI16: howto manager. (line 900) +* BFD_RELOC_SH_GOTOFF_MEDLOW16: howto manager. (line 899) +* BFD_RELOC_SH_GOTPC: howto manager. (line 885) +* BFD_RELOC_SH_GOTPC_HI16: howto manager. (line 905) +* BFD_RELOC_SH_GOTPC_LOW16: howto manager. (line 902) +* BFD_RELOC_SH_GOTPC_MEDHI16: howto manager. (line 904) +* BFD_RELOC_SH_GOTPC_MEDLOW16: howto manager. (line 903) +* BFD_RELOC_SH_GOTPLT10BY4: howto manager. (line 912) +* BFD_RELOC_SH_GOTPLT10BY8: howto manager. (line 913) +* BFD_RELOC_SH_GOTPLT32: howto manager. (line 914) +* BFD_RELOC_SH_GOTPLT_HI16: howto manager. (line 893) +* BFD_RELOC_SH_GOTPLT_LOW16: howto manager. (line 890) +* BFD_RELOC_SH_GOTPLT_MEDHI16: howto manager. (line 892) +* BFD_RELOC_SH_GOTPLT_MEDLOW16: howto manager. (line 891) +* BFD_RELOC_SH_GOT_HI16: howto manager. (line 889) +* BFD_RELOC_SH_GOT_LOW16: howto manager. (line 886) +* BFD_RELOC_SH_GOT_MEDHI16: howto manager. (line 888) +* BFD_RELOC_SH_GOT_MEDLOW16: howto manager. (line 887) +* BFD_RELOC_SH_IMM3: howto manager. (line 855) +* BFD_RELOC_SH_IMM3U: howto manager. (line 856) +* BFD_RELOC_SH_IMM4: howto manager. (line 863) +* BFD_RELOC_SH_IMM4BY2: howto manager. (line 864) +* BFD_RELOC_SH_IMM4BY4: howto manager. (line 865) +* BFD_RELOC_SH_IMM8: howto manager. (line 866) +* BFD_RELOC_SH_IMM8BY2: howto manager. (line 867) +* BFD_RELOC_SH_IMM8BY4: howto manager. (line 868) +* BFD_RELOC_SH_IMMS10: howto manager. (line 920) +* BFD_RELOC_SH_IMMS10BY2: howto manager. (line 921) +* BFD_RELOC_SH_IMMS10BY4: howto manager. (line 922) +* BFD_RELOC_SH_IMMS10BY8: howto manager. (line 923) +* BFD_RELOC_SH_IMMS16: howto manager. (line 924) +* BFD_RELOC_SH_IMMS6: howto manager. (line 917) +* BFD_RELOC_SH_IMMS6BY32: howto manager. (line 918) +* BFD_RELOC_SH_IMMU16: howto manager. (line 925) +* BFD_RELOC_SH_IMMU5: howto manager. (line 916) +* BFD_RELOC_SH_IMMU6: howto manager. (line 919) +* BFD_RELOC_SH_IMM_HI16: howto manager. (line 932) +* BFD_RELOC_SH_IMM_HI16_PCREL: howto manager. (line 933) +* BFD_RELOC_SH_IMM_LOW16: howto manager. (line 926) +* BFD_RELOC_SH_IMM_LOW16_PCREL: howto manager. (line 927) +* BFD_RELOC_SH_IMM_MEDHI16: howto manager. (line 930) +* BFD_RELOC_SH_IMM_MEDHI16_PCREL: howto manager. (line 931) +* BFD_RELOC_SH_IMM_MEDLOW16: howto manager. (line 928) +* BFD_RELOC_SH_IMM_MEDLOW16_PCREL: howto manager. (line 929) +* BFD_RELOC_SH_JMP_SLOT: howto manager. (line 883) +* BFD_RELOC_SH_JMP_SLOT64: howto manager. (line 908) +* BFD_RELOC_SH_LABEL: howto manager. (line 878) +* BFD_RELOC_SH_LOOP_END: howto manager. (line 880) +* BFD_RELOC_SH_LOOP_START: howto manager. (line 879) +* BFD_RELOC_SH_PCDISP12BY2: howto manager. (line 854) +* BFD_RELOC_SH_PCDISP8BY2: howto manager. (line 853) +* BFD_RELOC_SH_PCRELIMM8BY2: howto manager. (line 869) +* BFD_RELOC_SH_PCRELIMM8BY4: howto manager. (line 870) +* BFD_RELOC_SH_PLT_HI16: howto manager. (line 897) +* BFD_RELOC_SH_PLT_LOW16: howto manager. (line 894) +* BFD_RELOC_SH_PLT_MEDHI16: howto manager. (line 896) +* BFD_RELOC_SH_PLT_MEDLOW16: howto manager. (line 895) +* BFD_RELOC_SH_PT_16: howto manager. (line 934) +* BFD_RELOC_SH_RELATIVE: howto manager. (line 884) +* BFD_RELOC_SH_RELATIVE64: howto manager. (line 909) +* BFD_RELOC_SH_SHMEDIA_CODE: howto manager. (line 915) +* BFD_RELOC_SH_SWITCH16: howto manager. (line 871) +* BFD_RELOC_SH_SWITCH32: howto manager. (line 872) +* BFD_RELOC_SH_TLS_DTPMOD32: howto manager. (line 940) +* BFD_RELOC_SH_TLS_DTPOFF32: howto manager. (line 941) +* BFD_RELOC_SH_TLS_GD_32: howto manager. (line 935) +* BFD_RELOC_SH_TLS_IE_32: howto manager. (line 938) +* BFD_RELOC_SH_TLS_LDO_32: howto manager. (line 937) +* BFD_RELOC_SH_TLS_LD_32: howto manager. (line 936) +* BFD_RELOC_SH_TLS_LE_32: howto manager. (line 939) +* BFD_RELOC_SH_TLS_TPOFF32: howto manager. (line 942) +* BFD_RELOC_SH_USES: howto manager. (line 873) +* BFD_RELOC_SIZE32: howto manager. (line 69) +* BFD_RELOC_SIZE64: howto manager. (line 70) +* BFD_RELOC_SPARC13: howto manager. (line 125) +* BFD_RELOC_SPARC22: howto manager. (line 124) +* BFD_RELOC_SPARC_10: howto manager. (line 152) +* BFD_RELOC_SPARC_11: howto manager. (line 153) +* BFD_RELOC_SPARC_5: howto manager. (line 165) +* BFD_RELOC_SPARC_6: howto manager. (line 164) +* BFD_RELOC_SPARC_64: howto manager. (line 151) +* BFD_RELOC_SPARC_7: howto manager. (line 163) +* BFD_RELOC_SPARC_BASE13: howto manager. (line 148) +* BFD_RELOC_SPARC_BASE22: howto manager. (line 149) +* BFD_RELOC_SPARC_COPY: howto manager. (line 132) +* BFD_RELOC_SPARC_DISP64: howto manager. (line 166) +* BFD_RELOC_SPARC_GLOB_DAT: howto manager. (line 133) +* BFD_RELOC_SPARC_GOT10: howto manager. (line 126) +* BFD_RELOC_SPARC_GOT13: howto manager. (line 127) +* BFD_RELOC_SPARC_GOT22: howto manager. (line 128) +* BFD_RELOC_SPARC_GOTDATA_HIX22: howto manager. (line 139) +* BFD_RELOC_SPARC_GOTDATA_LOX10: howto manager. (line 140) +* BFD_RELOC_SPARC_GOTDATA_OP: howto manager. (line 143) +* BFD_RELOC_SPARC_GOTDATA_OP_HIX22: howto manager. (line 141) +* BFD_RELOC_SPARC_GOTDATA_OP_LOX10: howto manager. (line 142) +* BFD_RELOC_SPARC_H34: howto manager. (line 175) +* BFD_RELOC_SPARC_H44: howto manager. (line 171) +* BFD_RELOC_SPARC_HH22: howto manager. (line 155) +* BFD_RELOC_SPARC_HIX22: howto manager. (line 169) +* BFD_RELOC_SPARC_HM10: howto manager. (line 156) +* BFD_RELOC_SPARC_IRELATIVE: howto manager. (line 145) +* BFD_RELOC_SPARC_JMP_IREL: howto manager. (line 144) +* BFD_RELOC_SPARC_JMP_SLOT: howto manager. (line 134) +* BFD_RELOC_SPARC_L44: howto manager. (line 173) +* BFD_RELOC_SPARC_LM22: howto manager. (line 157) +* BFD_RELOC_SPARC_LOX10: howto manager. (line 170) +* BFD_RELOC_SPARC_M44: howto manager. (line 172) +* BFD_RELOC_SPARC_OLO10: howto manager. (line 154) +* BFD_RELOC_SPARC_PC10: howto manager. (line 129) +* BFD_RELOC_SPARC_PC22: howto manager. (line 130) +* BFD_RELOC_SPARC_PC_HH22: howto manager. (line 158) +* BFD_RELOC_SPARC_PC_HM10: howto manager. (line 159) +* BFD_RELOC_SPARC_PC_LM22: howto manager. (line 160) +* BFD_RELOC_SPARC_PLT32: howto manager. (line 167) +* BFD_RELOC_SPARC_PLT64: howto manager. (line 168) +* BFD_RELOC_SPARC_REGISTER: howto manager. (line 174) +* BFD_RELOC_SPARC_RELATIVE: howto manager. (line 135) +* BFD_RELOC_SPARC_REV32: howto manager. (line 180) +* BFD_RELOC_SPARC_SIZE32: howto manager. (line 176) +* BFD_RELOC_SPARC_SIZE64: howto manager. (line 177) +* BFD_RELOC_SPARC_TLS_DTPMOD32: howto manager. (line 200) +* BFD_RELOC_SPARC_TLS_DTPMOD64: howto manager. (line 201) +* BFD_RELOC_SPARC_TLS_DTPOFF32: howto manager. (line 202) +* BFD_RELOC_SPARC_TLS_DTPOFF64: howto manager. (line 203) +* BFD_RELOC_SPARC_TLS_GD_ADD: howto manager. (line 184) +* BFD_RELOC_SPARC_TLS_GD_CALL: howto manager. (line 185) +* BFD_RELOC_SPARC_TLS_GD_HI22: howto manager. (line 182) +* BFD_RELOC_SPARC_TLS_GD_LO10: howto manager. (line 183) +* BFD_RELOC_SPARC_TLS_IE_ADD: howto manager. (line 197) +* BFD_RELOC_SPARC_TLS_IE_HI22: howto manager. (line 193) +* BFD_RELOC_SPARC_TLS_IE_LD: howto manager. (line 195) +* BFD_RELOC_SPARC_TLS_IE_LDX: howto manager. (line 196) +* BFD_RELOC_SPARC_TLS_IE_LO10: howto manager. (line 194) +* BFD_RELOC_SPARC_TLS_LDM_ADD: howto manager. (line 188) +* BFD_RELOC_SPARC_TLS_LDM_CALL: howto manager. (line 189) +* BFD_RELOC_SPARC_TLS_LDM_HI22: howto manager. (line 186) +* BFD_RELOC_SPARC_TLS_LDM_LO10: howto manager. (line 187) +* BFD_RELOC_SPARC_TLS_LDO_ADD: howto manager. (line 192) +* BFD_RELOC_SPARC_TLS_LDO_HIX22: howto manager. (line 190) +* BFD_RELOC_SPARC_TLS_LDO_LOX10: howto manager. (line 191) +* BFD_RELOC_SPARC_TLS_LE_HIX22: howto manager. (line 198) +* BFD_RELOC_SPARC_TLS_LE_LOX10: howto manager. (line 199) +* BFD_RELOC_SPARC_TLS_TPOFF32: howto manager. (line 204) +* BFD_RELOC_SPARC_TLS_TPOFF64: howto manager. (line 205) +* BFD_RELOC_SPARC_UA16: howto manager. (line 136) +* BFD_RELOC_SPARC_UA32: howto manager. (line 137) +* BFD_RELOC_SPARC_UA64: howto manager. (line 138) +* BFD_RELOC_SPARC_WDISP10: howto manager. (line 178) +* BFD_RELOC_SPARC_WDISP16: howto manager. (line 161) +* BFD_RELOC_SPARC_WDISP19: howto manager. (line 162) +* BFD_RELOC_SPARC_WDISP22: howto manager. (line 123) +* BFD_RELOC_SPARC_WPLT30: howto manager. (line 131) +* BFD_RELOC_SPU_ADD_PIC: howto manager. (line 221) +* BFD_RELOC_SPU_HI16: howto manager. (line 218) +* BFD_RELOC_SPU_IMM10: howto manager. (line 209) +* BFD_RELOC_SPU_IMM10W: howto manager. (line 210) +* BFD_RELOC_SPU_IMM16: howto manager. (line 211) +* BFD_RELOC_SPU_IMM16W: howto manager. (line 212) +* BFD_RELOC_SPU_IMM18: howto manager. (line 213) +* BFD_RELOC_SPU_IMM7: howto manager. (line 207) +* BFD_RELOC_SPU_IMM8: howto manager. (line 208) +* BFD_RELOC_SPU_LO16: howto manager. (line 217) +* BFD_RELOC_SPU_PCREL16: howto manager. (line 216) +* BFD_RELOC_SPU_PCREL9a: howto manager. (line 214) +* BFD_RELOC_SPU_PCREL9b: howto manager. (line 215) +* BFD_RELOC_SPU_PPU32: howto manager. (line 219) +* BFD_RELOC_SPU_PPU64: howto manager. (line 220) +* BFD_RELOC_THUMB_PCREL_BLX: howto manager. (line 720) +* BFD_RELOC_THUMB_PCREL_BRANCH12: howto manager. (line 731) +* BFD_RELOC_THUMB_PCREL_BRANCH20: howto manager. (line 732) +* BFD_RELOC_THUMB_PCREL_BRANCH23: howto manager. (line 733) +* BFD_RELOC_THUMB_PCREL_BRANCH25: howto manager. (line 734) +* BFD_RELOC_THUMB_PCREL_BRANCH7: howto manager. (line 729) +* BFD_RELOC_THUMB_PCREL_BRANCH9: howto manager. (line 730) +* BFD_RELOC_TIC30_LDP: howto manager. (line 1369) +* BFD_RELOC_TIC54X_16_OF_23: howto manager. (line 1383) +* BFD_RELOC_TIC54X_23: howto manager. (line 1381) +* BFD_RELOC_TIC54X_MS7_OF_23: howto manager. (line 1387) +* BFD_RELOC_TIC54X_PARTLS7: howto manager. (line 1373) +* BFD_RELOC_TIC54X_PARTMS9: howto manager. (line 1377) +* BFD_RELOC_TILEGX_BROFF_X1: howto manager. (line 2784) +* BFD_RELOC_TILEGX_COPY: howto manager. (line 2780) +* BFD_RELOC_TILEGX_DEST_IMM8_X1: howto manager. (line 2791) +* BFD_RELOC_TILEGX_GLOB_DAT: howto manager. (line 2781) +* BFD_RELOC_TILEGX_HW0: howto manager. (line 2773) +* BFD_RELOC_TILEGX_HW0_LAST: howto manager. (line 2777) +* BFD_RELOC_TILEGX_HW1: howto manager. (line 2774) +* BFD_RELOC_TILEGX_HW1_LAST: howto manager. (line 2778) +* BFD_RELOC_TILEGX_HW2: howto manager. (line 2775) +* BFD_RELOC_TILEGX_HW2_LAST: howto manager. (line 2779) +* BFD_RELOC_TILEGX_HW3: howto manager. (line 2776) +* BFD_RELOC_TILEGX_IMM16_X0_HW0: howto manager. (line 2800) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_GOT: howto manager. (line 2828) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST: howto manager. (line 2808) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_GOT: howto manager. (line 2836) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PCREL: howto manager. (line 2822) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PLT_PCREL: howto manager. + (line 2856) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_GD: howto manager. (line 2850) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_IE: howto manager. (line 2862) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_LE: howto manager. (line 2846) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_PCREL: howto manager. (line 2814) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_PLT_PCREL: howto manager. (line 2830) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_GD: howto manager. (line 2842) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_IE: howto manager. (line 2854) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_LE: howto manager. (line 2844) +* BFD_RELOC_TILEGX_IMM16_X0_HW1: howto manager. (line 2802) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST: howto manager. (line 2810) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_GOT: howto manager. (line 2838) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PCREL: howto manager. (line 2824) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PLT_PCREL: howto manager. + (line 2858) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_GD: howto manager. (line 2852) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_IE: howto manager. (line 2864) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_LE: howto manager. (line 2848) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_PCREL: howto manager. (line 2816) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_PLT_PCREL: howto manager. (line 2832) +* BFD_RELOC_TILEGX_IMM16_X0_HW2: howto manager. (line 2804) +* BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST: howto manager. (line 2812) +* BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PCREL: howto manager. (line 2826) +* BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PLT_PCREL: howto manager. + (line 2860) +* BFD_RELOC_TILEGX_IMM16_X0_HW2_PCREL: howto manager. (line 2818) +* BFD_RELOC_TILEGX_IMM16_X0_HW2_PLT_PCREL: howto manager. (line 2834) +* BFD_RELOC_TILEGX_IMM16_X0_HW3: howto manager. (line 2806) +* BFD_RELOC_TILEGX_IMM16_X0_HW3_PCREL: howto manager. (line 2820) +* BFD_RELOC_TILEGX_IMM16_X0_HW3_PLT_PCREL: howto manager. (line 2840) +* BFD_RELOC_TILEGX_IMM16_X1_HW0: howto manager. (line 2801) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_GOT: howto manager. (line 2829) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST: howto manager. (line 2809) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_GOT: howto manager. (line 2837) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PCREL: howto manager. (line 2823) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PLT_PCREL: howto manager. + (line 2857) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_GD: howto manager. (line 2851) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_IE: howto manager. (line 2863) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_LE: howto manager. (line 2847) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_PCREL: howto manager. (line 2815) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_PLT_PCREL: howto manager. (line 2831) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_GD: howto manager. (line 2843) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_IE: howto manager. (line 2855) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_LE: howto manager. (line 2845) +* BFD_RELOC_TILEGX_IMM16_X1_HW1: howto manager. (line 2803) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST: howto manager. (line 2811) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_GOT: howto manager. (line 2839) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PCREL: howto manager. (line 2825) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PLT_PCREL: howto manager. + (line 2859) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_GD: howto manager. (line 2853) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_IE: howto manager. (line 2865) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_LE: howto manager. (line 2849) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_PCREL: howto manager. (line 2817) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_PLT_PCREL: howto manager. (line 2833) +* BFD_RELOC_TILEGX_IMM16_X1_HW2: howto manager. (line 2805) +* BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST: howto manager. (line 2813) +* BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PCREL: howto manager. (line 2827) +* BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PLT_PCREL: howto manager. + (line 2861) +* BFD_RELOC_TILEGX_IMM16_X1_HW2_PCREL: howto manager. (line 2819) +* BFD_RELOC_TILEGX_IMM16_X1_HW2_PLT_PCREL: howto manager. (line 2835) +* BFD_RELOC_TILEGX_IMM16_X1_HW3: howto manager. (line 2807) +* BFD_RELOC_TILEGX_IMM16_X1_HW3_PCREL: howto manager. (line 2821) +* BFD_RELOC_TILEGX_IMM16_X1_HW3_PLT_PCREL: howto manager. (line 2841) +* BFD_RELOC_TILEGX_IMM8_X0: howto manager. (line 2787) +* BFD_RELOC_TILEGX_IMM8_X0_TLS_ADD: howto manager. (line 2878) +* BFD_RELOC_TILEGX_IMM8_X0_TLS_GD_ADD: howto manager. (line 2873) +* BFD_RELOC_TILEGX_IMM8_X1: howto manager. (line 2789) +* BFD_RELOC_TILEGX_IMM8_X1_TLS_ADD: howto manager. (line 2879) +* BFD_RELOC_TILEGX_IMM8_X1_TLS_GD_ADD: howto manager. (line 2874) +* BFD_RELOC_TILEGX_IMM8_Y0: howto manager. (line 2788) +* BFD_RELOC_TILEGX_IMM8_Y0_TLS_ADD: howto manager. (line 2880) +* BFD_RELOC_TILEGX_IMM8_Y0_TLS_GD_ADD: howto manager. (line 2875) +* BFD_RELOC_TILEGX_IMM8_Y1: howto manager. (line 2790) +* BFD_RELOC_TILEGX_IMM8_Y1_TLS_ADD: howto manager. (line 2881) +* BFD_RELOC_TILEGX_IMM8_Y1_TLS_GD_ADD: howto manager. (line 2876) +* BFD_RELOC_TILEGX_JMP_SLOT: howto manager. (line 2782) +* BFD_RELOC_TILEGX_JUMPOFF_X1: howto manager. (line 2785) +* BFD_RELOC_TILEGX_JUMPOFF_X1_PLT: howto manager. (line 2786) +* BFD_RELOC_TILEGX_MF_IMM14_X1: howto manager. (line 2793) +* BFD_RELOC_TILEGX_MMEND_X0: howto manager. (line 2795) +* BFD_RELOC_TILEGX_MMSTART_X0: howto manager. (line 2794) +* BFD_RELOC_TILEGX_MT_IMM14_X1: howto manager. (line 2792) +* BFD_RELOC_TILEGX_RELATIVE: howto manager. (line 2783) +* BFD_RELOC_TILEGX_SHAMT_X0: howto manager. (line 2796) +* BFD_RELOC_TILEGX_SHAMT_X1: howto manager. (line 2797) +* BFD_RELOC_TILEGX_SHAMT_Y0: howto manager. (line 2798) +* BFD_RELOC_TILEGX_SHAMT_Y1: howto manager. (line 2799) +* BFD_RELOC_TILEGX_TLS_DTPMOD32: howto manager. (line 2869) +* BFD_RELOC_TILEGX_TLS_DTPMOD64: howto manager. (line 2866) +* BFD_RELOC_TILEGX_TLS_DTPOFF32: howto manager. (line 2870) +* BFD_RELOC_TILEGX_TLS_DTPOFF64: howto manager. (line 2867) +* BFD_RELOC_TILEGX_TLS_GD_CALL: howto manager. (line 2872) +* BFD_RELOC_TILEGX_TLS_IE_LOAD: howto manager. (line 2877) +* BFD_RELOC_TILEGX_TLS_TPOFF32: howto manager. (line 2871) +* BFD_RELOC_TILEGX_TLS_TPOFF64: howto manager. (line 2868) +* BFD_RELOC_TILEPRO_BROFF_X1: howto manager. (line 2697) +* BFD_RELOC_TILEPRO_COPY: howto manager. (line 2693) +* BFD_RELOC_TILEPRO_DEST_IMM8_X1: howto manager. (line 2704) +* BFD_RELOC_TILEPRO_GLOB_DAT: howto manager. (line 2694) +* BFD_RELOC_TILEPRO_IMM16_X0: howto manager. (line 2707) +* BFD_RELOC_TILEPRO_IMM16_X0_GOT: howto manager. (line 2723) +* BFD_RELOC_TILEPRO_IMM16_X0_GOT_HA: howto manager. (line 2729) +* BFD_RELOC_TILEPRO_IMM16_X0_GOT_HI: howto manager. (line 2727) +* BFD_RELOC_TILEPRO_IMM16_X0_GOT_LO: howto manager. (line 2725) +* BFD_RELOC_TILEPRO_IMM16_X0_HA: howto manager. (line 2713) +* BFD_RELOC_TILEPRO_IMM16_X0_HA_PCREL: howto manager. (line 2721) +* BFD_RELOC_TILEPRO_IMM16_X0_HI: howto manager. (line 2711) +* BFD_RELOC_TILEPRO_IMM16_X0_HI_PCREL: howto manager. (line 2719) +* BFD_RELOC_TILEPRO_IMM16_X0_LO: howto manager. (line 2709) +* BFD_RELOC_TILEPRO_IMM16_X0_LO_PCREL: howto manager. (line 2717) +* BFD_RELOC_TILEPRO_IMM16_X0_PCREL: howto manager. (line 2715) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD: howto manager. (line 2745) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HA: howto manager. (line 2751) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HI: howto manager. (line 2749) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_LO: howto manager. (line 2747) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE: howto manager. (line 2753) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HA: howto manager. (line 2759) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HI: howto manager. (line 2757) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_LO: howto manager. (line 2755) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE: howto manager. (line 2764) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HA: howto manager. (line 2770) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HI: howto manager. (line 2768) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_LO: howto manager. (line 2766) +* BFD_RELOC_TILEPRO_IMM16_X1: howto manager. (line 2708) +* BFD_RELOC_TILEPRO_IMM16_X1_GOT: howto manager. (line 2724) +* BFD_RELOC_TILEPRO_IMM16_X1_GOT_HA: howto manager. (line 2730) +* BFD_RELOC_TILEPRO_IMM16_X1_GOT_HI: howto manager. (line 2728) +* BFD_RELOC_TILEPRO_IMM16_X1_GOT_LO: howto manager. (line 2726) +* BFD_RELOC_TILEPRO_IMM16_X1_HA: howto manager. (line 2714) +* BFD_RELOC_TILEPRO_IMM16_X1_HA_PCREL: howto manager. (line 2722) +* BFD_RELOC_TILEPRO_IMM16_X1_HI: howto manager. (line 2712) +* BFD_RELOC_TILEPRO_IMM16_X1_HI_PCREL: howto manager. (line 2720) +* BFD_RELOC_TILEPRO_IMM16_X1_LO: howto manager. (line 2710) +* BFD_RELOC_TILEPRO_IMM16_X1_LO_PCREL: howto manager. (line 2718) +* BFD_RELOC_TILEPRO_IMM16_X1_PCREL: howto manager. (line 2716) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD: howto manager. (line 2746) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HA: howto manager. (line 2752) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HI: howto manager. (line 2750) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_LO: howto manager. (line 2748) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE: howto manager. (line 2754) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HA: howto manager. (line 2760) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HI: howto manager. (line 2758) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_LO: howto manager. (line 2756) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE: howto manager. (line 2765) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HA: howto manager. (line 2771) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HI: howto manager. (line 2769) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_LO: howto manager. (line 2767) +* BFD_RELOC_TILEPRO_IMM8_X0: howto manager. (line 2700) +* BFD_RELOC_TILEPRO_IMM8_X0_TLS_GD_ADD: howto manager. (line 2740) +* BFD_RELOC_TILEPRO_IMM8_X1: howto manager. (line 2702) +* BFD_RELOC_TILEPRO_IMM8_X1_TLS_GD_ADD: howto manager. (line 2741) +* BFD_RELOC_TILEPRO_IMM8_Y0: howto manager. (line 2701) +* BFD_RELOC_TILEPRO_IMM8_Y0_TLS_GD_ADD: howto manager. (line 2742) +* BFD_RELOC_TILEPRO_IMM8_Y1: howto manager. (line 2703) +* BFD_RELOC_TILEPRO_IMM8_Y1_TLS_GD_ADD: howto manager. (line 2743) +* BFD_RELOC_TILEPRO_JMP_SLOT: howto manager. (line 2695) +* BFD_RELOC_TILEPRO_JOFFLONG_X1: howto manager. (line 2698) +* BFD_RELOC_TILEPRO_JOFFLONG_X1_PLT: howto manager. (line 2699) +* BFD_RELOC_TILEPRO_MF_IMM15_X1: howto manager. (line 2706) +* BFD_RELOC_TILEPRO_MMEND_X0: howto manager. (line 2732) +* BFD_RELOC_TILEPRO_MMEND_X1: howto manager. (line 2734) +* BFD_RELOC_TILEPRO_MMSTART_X0: howto manager. (line 2731) +* BFD_RELOC_TILEPRO_MMSTART_X1: howto manager. (line 2733) +* BFD_RELOC_TILEPRO_MT_IMM15_X1: howto manager. (line 2705) +* BFD_RELOC_TILEPRO_RELATIVE: howto manager. (line 2696) +* BFD_RELOC_TILEPRO_SHAMT_X0: howto manager. (line 2735) +* BFD_RELOC_TILEPRO_SHAMT_X1: howto manager. (line 2736) +* BFD_RELOC_TILEPRO_SHAMT_Y0: howto manager. (line 2737) +* BFD_RELOC_TILEPRO_SHAMT_Y1: howto manager. (line 2738) +* BFD_RELOC_TILEPRO_TLS_DTPMOD32: howto manager. (line 2761) +* BFD_RELOC_TILEPRO_TLS_DTPOFF32: howto manager. (line 2762) +* BFD_RELOC_TILEPRO_TLS_GD_CALL: howto manager. (line 2739) +* BFD_RELOC_TILEPRO_TLS_IE_LOAD: howto manager. (line 2744) +* BFD_RELOC_TILEPRO_TLS_TPOFF32: howto manager. (line 2763) +* bfd_reloc_type_lookup: howto manager. (line 2900) +* BFD_RELOC_V850_16_GOT: howto manager. (line 1345) +* BFD_RELOC_V850_16_GOTOFF: howto manager. (line 1361) +* BFD_RELOC_V850_16_PCREL: howto manager. (line 1325) +* BFD_RELOC_V850_16_S1: howto manager. (line 1337) +* BFD_RELOC_V850_16_SPLIT_OFFSET: howto manager. (line 1335) +* BFD_RELOC_V850_17_PCREL: howto manager. (line 1327) +* BFD_RELOC_V850_22_PCREL: howto manager. (line 1279) +* BFD_RELOC_V850_22_PLT_PCREL: howto manager. (line 1349) +* BFD_RELOC_V850_23: howto manager. (line 1329) +* BFD_RELOC_V850_32_ABS: howto manager. (line 1333) +* BFD_RELOC_V850_32_GOT: howto manager. (line 1347) +* BFD_RELOC_V850_32_GOTOFF: howto manager. (line 1363) +* BFD_RELOC_V850_32_GOTPCREL: howto manager. (line 1343) +* BFD_RELOC_V850_32_PCREL: howto manager. (line 1331) +* BFD_RELOC_V850_32_PLT_PCREL: howto manager. (line 1351) +* BFD_RELOC_V850_9_PCREL: howto manager. (line 1277) +* BFD_RELOC_V850_ALIGN: howto manager. (line 1320) +* BFD_RELOC_V850_CALLT_15_16_OFFSET: howto manager. (line 1341) +* BFD_RELOC_V850_CALLT_16_16_OFFSET: howto manager. (line 1314) +* BFD_RELOC_V850_CALLT_6_7_OFFSET: howto manager. (line 1312) +* BFD_RELOC_V850_CODE: howto manager. (line 1365) +* BFD_RELOC_V850_COPY: howto manager. (line 1353) +* BFD_RELOC_V850_DATA: howto manager. (line 1367) +* BFD_RELOC_V850_GLOB_DAT: howto manager. (line 1355) +* BFD_RELOC_V850_JMP_SLOT: howto manager. (line 1357) +* BFD_RELOC_V850_LO16_S1: howto manager. (line 1339) +* BFD_RELOC_V850_LO16_SPLIT_OFFSET: howto manager. (line 1322) +* BFD_RELOC_V850_LONGCALL: howto manager. (line 1316) +* BFD_RELOC_V850_LONGJUMP: howto manager. (line 1318) +* BFD_RELOC_V850_RELATIVE: howto manager. (line 1359) +* BFD_RELOC_V850_SDA_15_16_OFFSET: howto manager. (line 1283) +* BFD_RELOC_V850_SDA_16_16_OFFSET: howto manager. (line 1281) +* BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET: howto manager. (line 1306) +* BFD_RELOC_V850_TDA_16_16_OFFSET: howto manager. (line 1299) +* BFD_RELOC_V850_TDA_4_4_OFFSET: howto manager. (line 1304) +* BFD_RELOC_V850_TDA_4_5_OFFSET: howto manager. (line 1301) +* BFD_RELOC_V850_TDA_6_8_OFFSET: howto manager. (line 1291) +* BFD_RELOC_V850_TDA_7_7_OFFSET: howto manager. (line 1297) +* BFD_RELOC_V850_TDA_7_8_OFFSET: howto manager. (line 1294) +* BFD_RELOC_V850_ZDA_15_16_OFFSET: howto manager. (line 1288) +* BFD_RELOC_V850_ZDA_16_16_OFFSET: howto manager. (line 1286) +* BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET: howto manager. (line 1309) +* BFD_RELOC_VAX_GLOB_DAT: howto manager. (line 2208) +* BFD_RELOC_VAX_JMP_SLOT: howto manager. (line 2209) +* BFD_RELOC_VAX_RELATIVE: howto manager. (line 2210) +* BFD_RELOC_VPE4KMATH_DATA: howto manager. (line 1833) +* BFD_RELOC_VPE4KMATH_INSN: howto manager. (line 1834) +* BFD_RELOC_VTABLE_ENTRY: howto manager. (line 1837) +* BFD_RELOC_VTABLE_INHERIT: howto manager. (line 1836) +* BFD_RELOC_X86_64_32S: howto manager. (line 540) +* BFD_RELOC_X86_64_COPY: howto manager. (line 535) +* BFD_RELOC_X86_64_DTPMOD64: howto manager. (line 541) +* BFD_RELOC_X86_64_DTPOFF32: howto manager. (line 546) +* BFD_RELOC_X86_64_DTPOFF64: howto manager. (line 542) +* BFD_RELOC_X86_64_GLOB_DAT: howto manager. (line 536) +* BFD_RELOC_X86_64_GOT32: howto manager. (line 533) +* BFD_RELOC_X86_64_GOT64: howto manager. (line 551) +* BFD_RELOC_X86_64_GOTOFF64: howto manager. (line 549) +* BFD_RELOC_X86_64_GOTPC32: howto manager. (line 550) +* BFD_RELOC_X86_64_GOTPC32_TLSDESC: howto manager. (line 556) +* BFD_RELOC_X86_64_GOTPC64: howto manager. (line 553) +* BFD_RELOC_X86_64_GOTPCREL: howto manager. (line 539) +* BFD_RELOC_X86_64_GOTPCREL64: howto manager. (line 552) +* BFD_RELOC_X86_64_GOTPLT64: howto manager. (line 554) +* BFD_RELOC_X86_64_GOTTPOFF: howto manager. (line 547) +* BFD_RELOC_X86_64_IRELATIVE: howto manager. (line 559) +* BFD_RELOC_X86_64_JUMP_SLOT: howto manager. (line 537) +* BFD_RELOC_X86_64_PC32_BND: howto manager. (line 560) +* BFD_RELOC_X86_64_PLT32: howto manager. (line 534) +* BFD_RELOC_X86_64_PLT32_BND: howto manager. (line 561) +* BFD_RELOC_X86_64_PLTOFF64: howto manager. (line 555) +* BFD_RELOC_X86_64_RELATIVE: howto manager. (line 538) +* BFD_RELOC_X86_64_TLSDESC: howto manager. (line 558) +* BFD_RELOC_X86_64_TLSDESC_CALL: howto manager. (line 557) +* BFD_RELOC_X86_64_TLSGD: howto manager. (line 544) +* BFD_RELOC_X86_64_TLSLD: howto manager. (line 545) +* BFD_RELOC_X86_64_TPOFF32: howto manager. (line 548) +* BFD_RELOC_X86_64_TPOFF64: howto manager. (line 543) +* BFD_RELOC_XC16X_PAG: howto manager. (line 2203) +* BFD_RELOC_XC16X_POF: howto manager. (line 2204) +* BFD_RELOC_XC16X_SEG: howto manager. (line 2205) +* BFD_RELOC_XC16X_SOF: howto manager. (line 2206) +* BFD_RELOC_XGATE_24: howto manager. (line 1980) +* BFD_RELOC_XGATE_GPAGE: howto manager. (line 1978) +* BFD_RELOC_XGATE_IMM3: howto manager. (line 1992) +* BFD_RELOC_XGATE_IMM4: howto manager. (line 1994) +* BFD_RELOC_XGATE_IMM5: howto manager. (line 1996) +* BFD_RELOC_XGATE_IMM8_HI: howto manager. (line 1989) +* BFD_RELOC_XGATE_IMM8_LO: howto manager. (line 1986) +* BFD_RELOC_XGATE_LO16: howto manager. (line 1975) +* BFD_RELOC_XGATE_PCREL_10: howto manager. (line 1984) +* BFD_RELOC_XGATE_PCREL_9: howto manager. (line 1982) +* BFD_RELOC_XGATE_RL_GROUP: howto manager. (line 1971) +* BFD_RELOC_XGATE_RL_JUMP: howto manager. (line 1968) +* BFD_RELOC_XSTORMY16_12: howto manager. (line 2197) +* BFD_RELOC_XSTORMY16_24: howto manager. (line 2198) +* BFD_RELOC_XSTORMY16_FPTR16: howto manager. (line 2199) +* BFD_RELOC_XSTORMY16_REL_12: howto manager. (line 2196) +* BFD_RELOC_XTENSA_ASM_EXPAND: howto manager. (line 2348) +* BFD_RELOC_XTENSA_ASM_SIMPLIFY: howto manager. (line 2352) +* BFD_RELOC_XTENSA_DIFF16: howto manager. (line 2299) +* BFD_RELOC_XTENSA_DIFF32: howto manager. (line 2300) +* BFD_RELOC_XTENSA_DIFF8: howto manager. (line 2298) +* BFD_RELOC_XTENSA_GLOB_DAT: howto manager. (line 2290) +* BFD_RELOC_XTENSA_JMP_SLOT: howto manager. (line 2291) +* BFD_RELOC_XTENSA_OP0: howto manager. (line 2343) +* BFD_RELOC_XTENSA_OP1: howto manager. (line 2344) +* BFD_RELOC_XTENSA_OP2: howto manager. (line 2345) +* BFD_RELOC_XTENSA_PLT: howto manager. (line 2294) +* BFD_RELOC_XTENSA_RELATIVE: howto manager. (line 2292) +* BFD_RELOC_XTENSA_RTLD: howto manager. (line 2286) +* BFD_RELOC_XTENSA_SLOT0_ALT: howto manager. (line 2326) +* BFD_RELOC_XTENSA_SLOT0_OP: howto manager. (line 2307) +* BFD_RELOC_XTENSA_SLOT10_ALT: howto manager. (line 2336) +* BFD_RELOC_XTENSA_SLOT10_OP: howto manager. (line 2317) +* BFD_RELOC_XTENSA_SLOT11_ALT: howto manager. (line 2337) +* BFD_RELOC_XTENSA_SLOT11_OP: howto manager. (line 2318) +* BFD_RELOC_XTENSA_SLOT12_ALT: howto manager. (line 2338) +* BFD_RELOC_XTENSA_SLOT12_OP: howto manager. (line 2319) +* BFD_RELOC_XTENSA_SLOT13_ALT: howto manager. (line 2339) +* BFD_RELOC_XTENSA_SLOT13_OP: howto manager. (line 2320) +* BFD_RELOC_XTENSA_SLOT14_ALT: howto manager. (line 2340) +* BFD_RELOC_XTENSA_SLOT14_OP: howto manager. (line 2321) +* BFD_RELOC_XTENSA_SLOT1_ALT: howto manager. (line 2327) +* BFD_RELOC_XTENSA_SLOT1_OP: howto manager. (line 2308) +* BFD_RELOC_XTENSA_SLOT2_ALT: howto manager. (line 2328) +* BFD_RELOC_XTENSA_SLOT2_OP: howto manager. (line 2309) +* BFD_RELOC_XTENSA_SLOT3_ALT: howto manager. (line 2329) +* BFD_RELOC_XTENSA_SLOT3_OP: howto manager. (line 2310) +* BFD_RELOC_XTENSA_SLOT4_ALT: howto manager. (line 2330) +* BFD_RELOC_XTENSA_SLOT4_OP: howto manager. (line 2311) +* BFD_RELOC_XTENSA_SLOT5_ALT: howto manager. (line 2331) +* BFD_RELOC_XTENSA_SLOT5_OP: howto manager. (line 2312) +* BFD_RELOC_XTENSA_SLOT6_ALT: howto manager. (line 2332) +* BFD_RELOC_XTENSA_SLOT6_OP: howto manager. (line 2313) +* BFD_RELOC_XTENSA_SLOT7_ALT: howto manager. (line 2333) +* BFD_RELOC_XTENSA_SLOT7_OP: howto manager. (line 2314) +* BFD_RELOC_XTENSA_SLOT8_ALT: howto manager. (line 2334) +* BFD_RELOC_XTENSA_SLOT8_OP: howto manager. (line 2315) +* BFD_RELOC_XTENSA_SLOT9_ALT: howto manager. (line 2335) +* BFD_RELOC_XTENSA_SLOT9_OP: howto manager. (line 2316) +* BFD_RELOC_XTENSA_TLSDESC_ARG: howto manager. (line 2357) +* BFD_RELOC_XTENSA_TLSDESC_FN: howto manager. (line 2356) +* BFD_RELOC_XTENSA_TLS_ARG: howto manager. (line 2361) +* BFD_RELOC_XTENSA_TLS_CALL: howto manager. (line 2362) +* BFD_RELOC_XTENSA_TLS_DTPOFF: howto manager. (line 2358) +* BFD_RELOC_XTENSA_TLS_FUNC: howto manager. (line 2360) +* BFD_RELOC_XTENSA_TLS_TPOFF: howto manager. (line 2359) +* BFD_RELOC_Z80_DISP8: howto manager. (line 2364) +* BFD_RELOC_Z8K_CALLR: howto manager. (line 2368) +* BFD_RELOC_Z8K_DISP7: howto manager. (line 2366) +* BFD_RELOC_Z8K_IMM4L: howto manager. (line 2370) +* bfd_rename_section: section prototypes. (line 167) +* bfd_scan_arch: Architectures. (line 505) +* bfd_scan_vma: Miscellaneous. (line 122) +* bfd_seach_for_target: bfd_target. (line 526) +* bfd_sections_find_if: section prototypes. (line 197) +* bfd_section_already_linked: Writing the symbol table. + (line 54) +* bfd_section_list_clear: section prototypes. (line 7) +* bfd_set_archive_head: Archives. (line 74) +* bfd_set_arch_info: Architectures. (line 546) +* bfd_set_assert_handler: Error reporting. (line 141) +* bfd_set_default_target: bfd_target. (line 465) +* bfd_set_error: Error reporting. (line 56) +* bfd_set_error_handler: Error reporting. (line 99) +* bfd_set_error_program_name: Error reporting. (line 107) +* bfd_set_file_flags: Miscellaneous. (line 43) +* bfd_set_format: Formats. (line 67) +* bfd_set_gp_size: Miscellaneous. (line 112) +* bfd_set_private_flags: Miscellaneous. (line 186) +* bfd_set_reloc: Miscellaneous. (line 33) +* bfd_set_section_contents: section prototypes. (line 229) +* bfd_set_section_flags: section prototypes. (line 152) +* bfd_set_section_size: section prototypes. (line 214) +* bfd_set_start_address: Miscellaneous. (line 91) +* bfd_set_symtab: symbol handling functions. + (line 59) +* bfd_symbol_info: symbol handling functions. + (line 129) +* bfd_target_list: bfd_target. (line 517) +* bfd_write_bigendian_4byte_int: Internal. (line 12) +* bfd_zalloc: Opening and Closing. + (line 256) +* bfd_zalloc2: Opening and Closing. + (line 265) +* coff_symbol_type: coff. (line 244) +* core_file_matches_executable_p: Core Files. (line 38) +* find_separate_debug_file: Opening and Closing. + (line 331) +* generic_core_file_matches_executable_p: Core Files. (line 48) +* Hash tables: Hash Tables. (line 6) +* internal object-file format: Canonical format. (line 11) +* Linker: Linker Functions. (line 6) +* Other functions: Miscellaneous. (line 200) +* separate_alt_debug_file_exists: Opening and Closing. + (line 322) +* separate_debug_file_exists: Opening and Closing. + (line 313) +* struct bfd_iovec: Miscellaneous. (line 364) +* target vector (_bfd_final_link): Performing the Final Link. + (line 6) +* target vector (_bfd_link_add_symbols): Adding Symbols to the Hash Table. + (line 6) +* target vector (_bfd_link_hash_table_create): Creating a Linker Hash Table. + (line 6) +* The HOWTO Macro: typedef arelent. (line 289) +* what is it?: Overview. (line 6) + + + +Tag Table: +Node: Top1056 +Node: Overview1392 +Node: History2450 +Node: How It Works3395 +Node: What BFD Version 2 Can Do4932 +Node: BFD information loss6249 +Node: Canonical format8790 +Node: BFD front end13167 +Node: typedef bfd13591 +Node: Error reporting24512 +Node: Miscellaneous29371 +Node: Memory Usage46501 +Node: Initialization47732 +Node: Sections48191 +Node: Section Input48674 +Node: Section Output50043 +Node: typedef asection52530 +Node: section prototypes78656 +Node: Symbols88924 +Node: Reading Symbols90527 +Node: Writing Symbols91635 +Node: Mini Symbols93379 +Node: typedef asymbol94353 +Node: symbol handling functions100394 +Node: Archives105725 +Node: Formats109753 +Node: Relocations112704 +Node: typedef arelent113431 +Node: howto manager129082 +Node: Core Files240822 +Node: Targets242860 +Node: bfd_target244835 +Node: Architectures268049 +Node: Opening and Closing295156 +Node: Internal309471 +Node: File Caching315818 +Node: Linker Functions317736 +Node: Creating a Linker Hash Table319410 +Node: Adding Symbols to the Hash Table321149 +Node: Differing file formats322049 +Node: Adding symbols from an object file323774 +Node: Adding symbols from an archive325924 +Node: Performing the Final Link328853 +Node: Information provided by the linker330094 +Node: Relocating the section contents331248 +Node: Writing the symbol table333000 +Node: Hash Tables337383 +Node: Creating and Freeing a Hash Table338581 +Node: Looking Up or Entering a String339831 +Node: Traversing a Hash Table341084 +Node: Deriving a New Hash Table Type341873 +Node: Define the Derived Structures342939 +Node: Write the Derived Creation Routine344020 +Node: Write Other Derived Routines346644 +Node: BFD back ends347959 +Node: What to Put Where348229 +Node: aout348409 +Node: coff354732 +Node: elf383206 +Node: mmo383607 +Node: File layout384532 +Node: Symbol-table390170 +Node: mmo section mapping393937 +Node: GNU Free Documentation License397591 +Node: BFD Index422654 + +End Tag Table diff --git a/util/X86MAC64/share/info/configure.info b/util/X86MAC64/share/info/configure.info new file mode 100644 index 0000000000..360084a935 --- /dev/null +++ b/util/X86MAC64/share/info/configure.info @@ -0,0 +1,2721 @@ +This is configure.info, produced by makeinfo version 5.1 from +configure.texi. + +INFO-DIR-SECTION GNU admin +START-INFO-DIR-ENTRY +* configure: (configure). The GNU configure and build system +END-INFO-DIR-ENTRY + +This file documents the GNU configure and build system. + + Copyright (C) 1998 Cygnus Solutions. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + +File: configure.info, Node: Top, Next: Introduction, Up: (dir) + +GNU configure and build system +****************************** + +The GNU configure and build system. + +* Menu: + +* Introduction:: Introduction. +* Getting Started:: Getting Started. +* Files:: Files. +* Configuration Names:: Configuration Names. +* Cross Compilation Tools:: Cross Compilation Tools. +* Canadian Cross:: Canadian Cross. +* Cygnus Configure:: Cygnus Configure. +* Multilibs:: Multilibs. +* FAQ:: Frequently Asked Questions. +* Index:: Index. + + +File: configure.info, Node: Introduction, Next: Getting Started, Prev: Top, Up: Top + +1 Introduction +************** + +This document describes the GNU configure and build systems. It +describes how autoconf, automake, libtool, and make fit together. It +also includes a discussion of the older Cygnus configure system. + + This document does not describe in detail how to use each of the +tools; see the respective manuals for that. Instead, it describes which +files the developer must write, which files are machine generated and +how they are generated, and where certain common problems should be +addressed. + + This document draws on several sources, including the autoconf manual +by David MacKenzie (*note autoconf overview: (autoconf)Top.), the +automake manual by David MacKenzie and Tom Tromey (*note automake +overview: (automake)Top.), the libtool manual by Gordon Matzigkeit +(*note libtool overview: (libtool)Top.), and the Cygnus configure manual +by K. Richard Pixley. + +* Menu: + +* Goals:: Goals. +* Tools:: The tools. +* History:: History. +* Building:: Building. + + +File: configure.info, Node: Goals, Next: Tools, Up: Introduction + +1.1 Goals +========= + +The GNU configure and build system has two main goals. + + The first is to simplify the development of portable programs. The +system permits the developer to concentrate on writing the program, +simplifying many details of portability across Unix and even Windows +systems, and permitting the developer to describe how to build the +program using simple rules rather than complex Makefiles. + + The second is to simplify the building of programs distributed as +source code. All programs are built using a simple, standardized, two +step process. The program builder need not install any special tools in +order to build the program. + + +File: configure.info, Node: Tools, Next: History, Prev: Goals, Up: Introduction + +1.2 Tools +========= + +The GNU configure and build system is comprised of several different +tools. Program developers must build and install all of these tools. + + People who just want to build programs from distributed sources +normally do not need any special tools beyond a Unix shell, a make +program, and a C compiler. + +autoconf + provides a general portability framework, based on testing the + features of the host system at build time. +automake + a system for describing how to build a program, permitting the + developer to write a simplified 'Makefile'. +libtool + a standardized approach to building shared libraries. +gettext + provides a framework for translation of text messages into other + languages; not really discussed in this document. +m4 + autoconf requires the GNU version of m4; the standard Unix m4 does + not suffice. +perl + automake requires perl. + + +File: configure.info, Node: History, Next: Building, Prev: Tools, Up: Introduction + +1.3 History +=========== + +This is a very brief and probably inaccurate history. + + As the number of Unix variants increased during the 1980s, it became +harder to write programs which could run on all variants. While it was +often possible to use '#ifdef' to identify particular systems, +developers frequently did not have access to every system, and the +characteristics of some systems changed from version to version. + + By 1992, at least three different approaches had been developed: + * The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael + Manfredi. + * The Cygnus configure script, by K. Richard Pixley, and the gcc + configure script, by Richard Stallman. These use essentially the + same approach, and the developers communicated regularly. + * The autoconf program, by David MacKenzie. + + The Metaconfig program is still used for Perl and a few other +programs. It is part of the Dist package. I do not know if it is being +developed. + + In 1994, David MacKenzie and others modified autoconf to incorporate +all the features of Cygnus configure. Since then, there has been a slow +but steady conversion of GNU programs from Cygnus configure to autoconf. +gcc has been converted, eliminating the gcc configure script. + + GNU autoconf was regularly maintained until late 1996. As of this +writing in June, 1998, it has no public maintainer. + + Most programs are built using the make program, which requires the +developer to write Makefiles describing how to build the programs. +Since most programs are built in pretty much the same way, this led to a +lot of duplication. + + The X Window system is built using the imake tool, which uses a +database of rules to eliminate the duplication. However, building a +tool which was developed using imake requires that the builder have +imake installed, violating one of the goals of the GNU system. + + The new BSD make provides a standard library of Makefile fragments, +which permits developers to write very simple Makefiles. However, this +requires that the builder install the new BSD make program. + + In 1994, David MacKenzie wrote the first version of automake, which +permitted writing a simple build description which was converted into a +Makefile which could be used by the standard make program. In 1995, Tom +Tromey completely rewrote automake in Perl, and he continues to enhance +it. + + Various free packages built libraries, and by around 1995 several +included support to build shared libraries on various platforms. +However, there was no consistent approach. In early 1996, Gordon +Matzigkeit began working on libtool, which provided a standardized +approach to building shared libraries. This was integrated into +automake from the start. + + The development of automake and libtool was driven by the GNITS +project, a group of GNU maintainers who designed standardized tools to +help meet the GNU coding standards. + + +File: configure.info, Node: Building, Prev: History, Up: Introduction + +1.4 Building +============ + +Most readers of this document should already know how to build a tool by +running 'configure' and 'make'. This section may serve as a quick +introduction or reminder. + + Building a tool is normally as simple as running 'configure' followed +by 'make'. You should normally run 'configure' from an empty directory, +using some path to refer to the 'configure' script in the source +directory. The directory in which you run 'configure' is called the +"object directory". + + In order to use a object directory which is different from the source +directory, you must be using the GNU version of 'make', which has the +required 'VPATH' support. Despite this restriction, using a different +object directory is highly recommended: + * It keeps the files generated during the build from cluttering up + your sources. + * It permits you to remove the built files by simply removing the + entire build directory. + * It permits you to build from the same sources with several sets of + configure options simultaneously. + + If you don't have GNU 'make', you will have to run 'configure' in the +source directory. All GNU packages should support this; in particular, +GNU packages should not assume the presence of GNU 'make'. + + After running 'configure', you can build the tools by running 'make'. + + To install the tools, run 'make install'. Installing the tools will +copy the programs and any required support files to the "installation +directory". The location of the installation directory is controlled by +'configure' options, as described below. + + In the Cygnus tree at present, the info files are built and installed +as a separate step. To build them, run 'make info'. To install them, +run 'make install-info'. The equivalent html files are also built and +installed in a separate step. To build the html files, run 'make html'. +To install the html files run 'make install-html'. + + All 'configure' scripts support a wide variety of options. The most +interesting ones are '--with' and '--enable' options which are generally +specific to particular tools. You can usually use the '--help' option +to get a list of interesting options for a particular configure script. + + The only generic options you are likely to use are the '--prefix' and +'--exec-prefix' options. These options are used to specify the +installation directory. + + The directory named by the '--prefix' option will hold machine +independent files such as info files. + + The directory named by the '--exec-prefix' option, which is normally +a subdirectory of the '--prefix' directory, will hold machine dependent +files such as executables. + + The default for '--prefix' is '/usr/local'. The default for +'--exec-prefix' is the value used for '--prefix'. + + The convention used in Cygnus releases is to use a '--prefix' option +of '/usr/cygnus/RELEASE', where RELEASE is the name of the release, and +to use a '--exec-prefix' option of '/usr/cygnus/RELEASE/H-HOST', where +HOST is the configuration name of the host system (*note Configuration +Names::). + + Do not use either the source or the object directory as the +installation directory. That will just lead to confusion. + + +File: configure.info, Node: Getting Started, Next: Files, Prev: Introduction, Up: Top + +2 Getting Started +***************** + +To start using the GNU configure and build system with your software +package, you must write three files, and you must run some tools to +manually generate additional files. + +* Menu: + +* Write configure.in:: Write configure.in. +* Write Makefile.am:: Write Makefile.am. +* Write acconfig.h:: Write acconfig.h. +* Generate files:: Generate files. +* Getting Started Example:: Example. + + +File: configure.info, Node: Write configure.in, Next: Write Makefile.am, Up: Getting Started + +2.1 Write configure.in +====================== + +You must first write the file 'configure.in'. This is an autoconf input +file, and the autoconf manual describes in detail what this file should +look like. + + You will write tests in your 'configure.in' file to check for +conditions that may change from one system to another, such as the +presence of particular header files or functions. + + For example, not all systems support the 'gettimeofday' function. If +you want to use the 'gettimeofday' function when it is available, and to +use some other function when it is not, you would check for this by +putting 'AC_CHECK_FUNCS(gettimeofday)' in 'configure.in'. + + When the configure script is run at build time, this will arrange to +define the preprocessor macro 'HAVE_GETTIMEOFDAY' to the value 1 if the +'gettimeofday' function is available, and to not define the macro at all +if the function is not available. Your code can then use '#ifdef' to +test whether it is safe to call 'gettimeofday'. + + If you have an existing body of code, the 'autoscan' program may help +identify potential portability problems, and hence configure tests that +you will want to use. *Note (autoconf)Invoking autoscan::. + + Another handy tool for an existing body of code is 'ifnames'. This +will show you all the preprocessor conditionals that the code already +uses. *Note (autoconf)Invoking ifnames::. + + Besides the portability tests which are specific to your particular +package, every 'configure.in' file should contain the following macros. + +'AC_INIT' + This macro takes a single argument, which is the name of a file in + your package. For example, 'AC_INIT(foo.c)'. + +'AC_PREREQ(VERSION)' + This macro is optional. It may be used to indicate the version of + 'autoconf' that you are using. This will prevent users from + running an earlier version of 'autoconf' and perhaps getting an + invalid 'configure' script. For example, 'AC_PREREQ(2.12)'. + +'AM_INIT_AUTOMAKE' + This macro takes two arguments: the name of the package, and a + version number. For example, 'AM_INIT_AUTOMAKE(foo, 1.0)'. (This + macro is not needed if you are not using automake). + +'AM_CONFIG_HEADER' + This macro names the header file which will hold the preprocessor + macro definitions at run time. Normally this should be 'config.h'. + Your sources would then use '#include "config.h"' to include it. + + This macro may optionally name the input file for that header file; + by default, this is 'config.h.in', but that file name works poorly + on DOS filesystems. Therefore, it is often better to name it + explicitly as 'config.in'. + + This is what you should normally put in 'configure.in': + AM_CONFIG_HEADER(config.h:config.in) + + (If you are not using automake, use 'AC_CONFIG_HEADER' rather than + 'AM_CONFIG_HEADER'). + +'AM_MAINTAINER_MODE' + This macro always appears in Cygnus configure scripts. Other + programs may or may not use it. + + If this macro is used, the '--enable-maintainer-mode' option is + required to enable automatic rebuilding of generated files used by + the configure system. This of course requires that developers be + aware of, and use, that option. + + If this macro is not used, then the generated files will always be + rebuilt automatically. This will cause problems if the wrong + versions of autoconf, automake, or others are in the builder's + 'PATH'. + + (If you are not using automake, you do not need to use this macro). + +'AC_EXEEXT' + Either this macro or 'AM_EXEEXT' always appears in Cygnus configure + files. Other programs may or may not use one of them. + + This macro looks for the executable suffix used on the host system. + On Unix systems, this is the empty string. On Windows systems, + this is '.exe'. This macro directs automake to use the executable + suffix as appropriate when creating programs. This macro does not + take any arguments. + + The 'AC_EXEEXT' form is new, and is part of a Cygnus patch to + autoconf to support compiling with Visual C++. Older programs use + 'AM_EXEEXT' instead. + + (Programs which do not use automake use neither 'AC_EXEEXT' nor + 'AM_EXEEXT'). + +'AC_PROG_CC' + If you are writing C code, you will normally want to use this + macro. It locates the C compiler to use. It does not take any + arguments. + + However, if this 'configure.in' file is for a library which is to + be compiled by a cross compiler which may not fully work, then you + will not want to use 'AC_PROG_CC'. Instead, you will want to use a + variant which does not call the macro 'AC_PROG_CC_WORKS'. Examples + can be found in various 'configure.in' files for libraries that are + compiled with cross compilers, such as libiberty or libgloss. This + is essentially a bug in autoconf, and there will probably be a + better workaround at some point. + +'AC_PROG_CXX' + If you are writing C++ code, you will want to use this macro. It + locates the C++ compiler to use. It does not take any arguments. + The same cross compiler comments apply as for 'AC_PROG_CC'. + +'AM_PROG_LIBTOOL' + If you want to build libraries, and you want to permit them to be + shared, or you want to link against libraries which were built + using libtool, then you will need this macro. This macro is + required in order to use libtool. + + By default, this will cause all libraries to be built as shared + libraries. To prevent this-to change the default-use + 'AM_DISABLE_SHARED' before 'AM_PROG_LIBTOOL'. The configure + options '--enable-shared' and '--disable-shared' may be used to + override the default at build time. + +'AC_DEFINE(_GNU_SOURCE)' + GNU packages should normally include this line before any other + feature tests. This defines the macro '_GNU_SOURCE' when + compiling, which directs the libc header files to provide the + standard GNU system interfaces including all GNU extensions. If + this macro is not defined, certain GNU extensions may not be + available. + +'AC_OUTPUT' + This macro takes a list of file names which the configure process + should produce. This is normally a list of one or more 'Makefile' + files in different directories. If your package lives entirely in + a single directory, you would use simply 'AC_OUTPUT(Makefile)'. If + you also have, for example, a 'lib' subdirectory, you would use + 'AC_OUTPUT(Makefile lib/Makefile)'. + + If you want to use locally defined macros in your 'configure.in' +file, then you will need to write a 'acinclude.m4' file which defines +them (if not using automake, this file is called 'aclocal.m4'). +Alternatively, you can put separate macros in an 'm4' subdirectory, and +put 'ACLOCAL_AMFLAGS = -I m4' in your 'Makefile.am' file so that the +'aclocal' program will be able to find them. + + The different macro prefixes indicate which tool defines the macro. +Macros which start with 'AC_' are part of autoconf. Macros which start +with 'AM_' are provided by automake or libtool. + + +File: configure.info, Node: Write Makefile.am, Next: Write acconfig.h, Prev: Write configure.in, Up: Getting Started + +2.2 Write Makefile.am +===================== + +You must write the file 'Makefile.am'. This is an automake input file, +and the automake manual describes in detail what this file should look +like. + + The automake commands in 'Makefile.am' mostly look like variable +assignments in a 'Makefile'. automake recognizes special variable +names, and automatically add make rules to the output as needed. + + There will be one 'Makefile.am' file for each directory in your +package. For each directory with subdirectories, the 'Makefile.am' file +should contain the line + SUBDIRS = DIR DIR ... +where each DIR is the name of a subdirectory. + + For each 'Makefile.am', there should be a corresponding 'Makefile' in +the 'AC_OUTPUT' macro in 'configure.in'. + + Every 'Makefile.am' written at Cygnus should contain the line + AUTOMAKE_OPTIONS = cygnus +This puts automake into Cygnus mode. See the automake manual for +details. + + You may to include the version number of 'automake' that you are +using on the 'AUTOMAKE_OPTIONS' line. For example, + AUTOMAKE_OPTIONS = cygnus 1.3 +This will prevent users from running an earlier version of 'automake' +and perhaps getting an invalid 'Makefile.in'. + + If your package builds a program, then in the directory where that +program is built you will normally want a line like + bin_PROGRAMS = PROGRAM +where PROGRAM is the name of the program. You will then want a line +like + PROGRAM_SOURCES = FILE FILE ... +where each FILE is the name of a source file to link into the program +(e.g., 'foo.c'). + + If your package builds a library, and you do not want the library to +ever be built as a shared library, then in the directory where that +library is built you will normally want a line like + lib_LIBRARIES = libNAME.a +where 'libNAME.a' is the name of the library. You will then want a line +like + libNAME_a_SOURCES = FILE FILE ... +where each FILE is the name of a source file to add to the library. + + If your package builds a library, and you want to permit building the +library as a shared library, then in the directory where that library is +built you will normally want a line like + lib_LTLIBRARIES = libNAME.la + The use of 'LTLIBRARIES', and the '.la' extension, indicate a library +to be built using libtool. As usual, you will then want a line like + libNAME_la_SOURCES = FILE FILE ... + + The strings 'bin' and 'lib' that appear above in 'bin_PROGRAMS' and +'lib_LIBRARIES' are not arbitrary. They refer to particular +directories, which may be set by the '--bindir' and '--libdir' options +to 'configure'. If those options are not used, the default values are +based on the '--prefix' or '--exec-prefix' options to 'configure'. It +is possible to use other names if the program or library should be +installed in some other directory. + + The 'Makefile.am' file may also contain almost anything that may +appear in a normal 'Makefile'. automake also supports many other +special variables, as well as conditionals. + + See the automake manual for more information. + + +File: configure.info, Node: Write acconfig.h, Next: Generate files, Prev: Write Makefile.am, Up: Getting Started + +2.3 Write acconfig.h +==================== + +If you are generating a portability header file, (i.e., you are using +'AM_CONFIG_HEADER' in 'configure.in'), then you will have to write a +'acconfig.h' file. It will have to contain the following lines. + + /* Name of package. */ + #undef PACKAGE + + /* Version of package. */ + #undef VERSION + + This requirement is really a bug in the system, and the requirement +may be eliminated at some later date. + + The 'acconfig.h' file will also similar comment and '#undef' lines +for any unusual macros in the 'configure.in' file, including any macro +which appears in a 'AC_DEFINE' macro. + + In particular, if you are writing a GNU package and therefore include +'AC_DEFINE(_GNU_SOURCE)' in 'configure.in' as suggested above, you will +need lines like this in 'acconfig.h': + /* Enable GNU extensions. */ + #undef _GNU_SOURCE + + Normally the 'autoheader' program will inform you of any such +requirements by printing an error message when it is run. However, if +you do anything particular odd in your 'configure.in' file, you will +have to make sure that the right entries appear in 'acconfig.h', since +otherwise the results of the tests may not be available in the +'config.h' file which your code will use. + + (Thee 'PACKAGE' and 'VERSION' lines are not required if you are not +using automake, and in that case you may not need a 'acconfig.h' file at +all). + + +File: configure.info, Node: Generate files, Next: Getting Started Example, Prev: Write acconfig.h, Up: Getting Started + +2.4 Generate files +================== + +Once you have written 'configure.in', 'Makefile.am', 'acconfig.h', and +possibly 'acinclude.m4', you must use autoconf and automake programs to +produce the first versions of the generated files. This is done by +executing the following sequence of commands. + + aclocal + autoconf + autoheader + automake + + The 'aclocal' and 'automake' commands are part of the automake +package, and the 'autoconf' and 'autoheader' commands are part of the +autoconf package. + + If you are using a 'm4' subdirectory for your macros, you will need +to use the '-I m4' option when you run 'aclocal'. + + If you are not using the Cygnus tree, use the '-a' option when +running 'automake' command in order to copy the required support files +into your source directory. + + If you are using libtool, you must build and install the libtool +package with the same '--prefix' and '--exec-prefix' options as you used +with the autoconf and automake packages. You must do this before +running any of the above commands. If you are not using the Cygnus +tree, you will need to run the 'libtoolize' program to copy the libtool +support files into your directory. + + Once you have managed to run these commands without getting any +errors, you should create a new empty directory, and run the 'configure' +script which will have been created by 'autoconf' with the +'--enable-maintainer-mode' option. This will give you a set of +Makefiles which will include rules to automatically rebuild all the +generated files. + + After doing that, whenever you have changed some of the input files +and want to regenerated the other files, go to your object directory and +run 'make'. Doing this is more reliable than trying to rebuild the +files manually, because there are complex order dependencies and it is +easy to forget something. + + +File: configure.info, Node: Getting Started Example, Prev: Generate files, Up: Getting Started + +2.5 Example +=========== + +Let's consider a trivial example. + + Suppose we want to write a simple version of 'touch'. Our program, +which we will call 'poke', will take a single file name argument, and +use the 'utime' system call to set the modification and access times of +the file to the current time. We want this program to be highly +portable. + + We'll first see what this looks like without using autoconf and +automake, and then see what it looks like with them. + +* Menu: + +* Getting Started Example 1:: First Try. +* Getting Started Example 2:: Second Try. +* Getting Started Example 3:: Third Try. +* Generate Files in Example:: Generate Files. + + +File: configure.info, Node: Getting Started Example 1, Next: Getting Started Example 2, Up: Getting Started Example + +2.5.1 First Try +--------------- + +Here is our first try at 'poke.c'. Note that we've written it without +ANSI/ISO C prototypes, since we want it to be highly portable. + + #include + #include + #include + #include + + int + main (argc, argv) + int argc; + char **argv; + { + if (argc != 2) + { + fprintf (stderr, "Usage: poke file\n"); + exit (1); + } + + if (utime (argv[1], NULL) < 0) + { + perror ("utime"); + exit (1); + } + + exit (0); + } + + We also write a simple 'Makefile'. + + CC = gcc + CFLAGS = -g -O2 + + all: poke + + poke: poke.o + $(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o + + So far, so good. + + Unfortunately, there are a few problems. + + On older Unix systems derived from BSD 4.3, the 'utime' system call +does not accept a second argument of 'NULL'. On those systems, we need +to pass a pointer to 'struct utimbuf' structure. Unfortunately, even +older systems don't define that structure; on those systems, we need to +pass an array of two 'long' values. + + The header file 'stdlib.h' was invented by ANSI C, and older systems +don't have a copy. We included it above to get a declaration of 'exit'. + + We can find some of these portability problems by running 'autoscan', +which will create a 'configure.scan' file which we can use as a +prototype for our 'configure.in' file. I won't show the output, but it +will notice the potential problems with 'utime' and 'stdlib.h'. + + In our 'Makefile', we don't provide any way to install the program. +This doesn't matter much for such a simple example, but a real program +will need an 'install' target. For that matter, we will also want a +'clean' target. + + +File: configure.info, Node: Getting Started Example 2, Next: Getting Started Example 3, Prev: Getting Started Example 1, Up: Getting Started Example + +2.5.2 Second Try +---------------- + +Here is our second try at this program. + + We modify 'poke.c' to use preprocessor macros to control what +features are available. (I've cheated a bit by using the same macro +names which autoconf will use). + + #include + + #ifdef STDC_HEADERS + #include + #endif + + #include + + #ifdef HAVE_UTIME_H + #include + #endif + + #ifndef HAVE_UTIME_NULL + + #include + + #ifndef HAVE_STRUCT_UTIMBUF + + struct utimbuf + { + long actime; + long modtime; + }; + + #endif + + static int + utime_now (file) + char *file; + { + struct utimbuf now; + + now.actime = now.modtime = time (NULL); + return utime (file, &now); + } + + #define utime(f, p) utime_now (f) + + #endif /* HAVE_UTIME_NULL */ + + int + main (argc, argv) + int argc; + char **argv; + { + if (argc != 2) + { + fprintf (stderr, "Usage: poke file\n"); + exit (1); + } + + if (utime (argv[1], NULL) < 0) + { + perror ("utime"); + exit (1); + } + + exit (0); + } + + Here is the associated 'Makefile'. We've added support for the +preprocessor flags we use. We've also added 'install' and 'clean' +targets. + + # Set this to your installation directory. + bindir = /usr/local/bin + + # Uncomment this if you have the standard ANSI/ISO C header files. + # STDC_HDRS = -DSTDC_HEADERS + + # Uncomment this if you have utime.h. + # UTIME_H = -DHAVE_UTIME_H + + # Uncomment this if utime (FILE, NULL) works on your system. + # UTIME_NULL = -DHAVE_UTIME_NULL + + # Uncomment this if struct utimbuf is defined in utime.h. + # UTIMBUF = -DHAVE_STRUCT_UTIMBUF + + CC = gcc + CFLAGS = -g -O2 + + ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS) + + all: poke + + poke: poke.o + $(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o + + .c.o: + $(CC) -c $(ALL_CFLAGS) poke.c + + install: poke + cp poke $(bindir)/poke + + clean: + rm poke poke.o + + Some problems with this approach should be clear. + + Users who want to compile poke will have to know how 'utime' works on +their systems, so that they can uncomment the 'Makefile' correctly. + + The installation is done using 'cp', but many systems have an +'install' program which may be used, and which supports optional +features such as stripping debugging information out of the installed +binary. + + The use of 'Makefile' variables like 'CC', 'CFLAGS' and 'LDFLAGS' +follows the requirements of the GNU standards. This is convenient for +all packages, since it reduces surprises for users. However, it is easy +to get the details wrong, and wind up with a slightly nonstandard +distribution. + + +File: configure.info, Node: Getting Started Example 3, Next: Generate Files in Example, Prev: Getting Started Example 2, Up: Getting Started Example + +2.5.3 Third Try +--------------- + +For our third try at this program, we will write a 'configure.in' script +to discover the configuration features on the host system, rather than +requiring the user to edit the 'Makefile'. We will also write a +'Makefile.am' rather than a 'Makefile'. + + The only change to 'poke.c' is to add a line at the start of the +file: + #include "config.h" + + The new 'configure.in' file is as follows. + + AC_INIT(poke.c) + AM_INIT_AUTOMAKE(poke, 1.0) + AM_CONFIG_HEADER(config.h:config.in) + AC_PROG_CC + AC_HEADER_STDC + AC_CHECK_HEADERS(utime.h) + AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF)) + AC_FUNC_UTIME_NULL + AC_OUTPUT(Makefile) + + The first four macros in this file, and the last one, were described +above; see *note Write configure.in::. If we omit these macros, then +when we run 'automake' we will get a reminder that we need them. + + The other macros are standard autoconf macros. + +'AC_HEADER_STDC' + Check for standard C headers. +'AC_CHECK_HEADERS' + Check whether a particular header file exists. +'AC_EGREP_HEADER' + Check for a particular string in a particular header file, in this + case checking for 'utimbuf' in 'utime.h'. +'AC_FUNC_UTIME_NULL' + Check whether 'utime' accepts a NULL second argument to set the + file change time to the current time. + + See the autoconf manual for a more complete description. + + The new 'Makefile.am' file is as follows. Note how simple this is +compared to our earlier 'Makefile'. + + bin_PROGRAMS = poke + + poke_SOURCES = poke.c + + This means that we should build a single program name 'poke'. It +should be installed in the binary directory, which we called 'bindir' +earlier. The program 'poke' is built from the source file 'poke.c'. + + We must also write a 'acconfig.h' file. Besides 'PACKAGE' and +'VERSION', which must be mentioned for all packages which use automake, +we must include 'HAVE_STRUCT_UTIMBUF', since we mentioned it in an +'AC_DEFINE'. + + /* Name of package. */ + #undef PACKAGE + + /* Version of package. */ + #undef VERSION + + /* Whether utime.h defines struct utimbuf. */ + #undef HAVE_STRUCT_UTIMBUF + + +File: configure.info, Node: Generate Files in Example, Prev: Getting Started Example 3, Up: Getting Started Example + +2.5.4 Generate Files +-------------------- + +We must now generate the other files, using the following commands. + + aclocal + autoconf + autoheader + automake + + When we run 'autoheader', it will remind us of any macros we forgot +to add to 'acconfig.h'. + + When we run 'automake', it will want to add some files to our +distribution. It will add them automatically if we use the +'--add-missing' option. + + By default, 'automake' will run in GNU mode, which means that it will +want us to create certain additional files; as of this writing, it will +want 'NEWS', 'README', 'AUTHORS', and 'ChangeLog', all of which are +files which should appear in a standard GNU distribution. We can either +add those files, or run 'automake' with the '--foreign' option. + + Running these tools will generate the following files, all of which +are described in the next chapter. + + * 'aclocal.m4' + * 'configure' + * 'config.in' + * 'Makefile.in' + * 'stamp-h.in' + + +File: configure.info, Node: Files, Next: Configuration Names, Prev: Getting Started, Up: Top + +3 Files +******* + +As was seen in the previous chapter, the GNU configure and build system +uses a number of different files. The developer must write a few files. +The others are generated by various tools. + + The system is rather flexible, and can be used in many different +ways. In describing the files that it uses, I will describe the common +case, and mention some other cases that may arise. + +* Menu: + +* Developer Files:: Developer Files. +* Build Files:: Build Files. +* Support Files:: Support Files. + + +File: configure.info, Node: Developer Files, Next: Build Files, Up: Files + +3.1 Developer Files +=================== + +This section describes the files written or generated by the developer +of a package. + +* Menu: + +* Developer Files Picture:: Developer Files Picture. +* Written Developer Files:: Written Developer Files. +* Generated Developer Files:: Generated Developer Files. + + +File: configure.info, Node: Developer Files Picture, Next: Written Developer Files, Up: Developer Files + +3.1.1 Developer Files Picture +----------------------------- + +Here is a picture of the files which are written by the developer, the +generated files which would be included with a complete source +distribution, and the tools which create those files. The file names +are plain text and the tool names are enclosed by '*' characters (e.g., +'autoheader' is the name of a tool, not the name of a file). + + acconfig.h configure.in Makefile.am + | | | + | --------------+---------------------- | + | | | | | + v v | acinclude.m4 | | + *autoheader* | | v v + | | v --->*automake* + v |--->*aclocal* | | + config.in | | | v + | v | Makefile.in + | aclocal.m4--- + | | + v v + *autoconf* + | + v + configure + +File: configure.info, Node: Written Developer Files, Next: Generated Developer Files, Prev: Developer Files Picture, Up: Developer Files + +3.1.2 Written Developer Files +----------------------------- + +The following files would be written by the developer. + +'configure.in' + This is the configuration script. This script contains invocations + of autoconf macros. It may also contain ordinary shell script + code. This file will contain feature tests for portability issues. + The last thing in the file will normally be an 'AC_OUTPUT' macro + listing which files to create when the builder runs the configure + script. This file is always required when using the GNU configure + system. *Note Write configure.in::. + +'Makefile.am' + This is the automake input file. It describes how the code should + be built. It consists of definitions of automake variables. It + may also contain ordinary Makefile targets. This file is only + needed when using automake (newer tools normally use automake, but + there are still older tools which have not been converted, in which + the developer writes 'Makefile.in' directly). *Note Write + Makefile.am::. + +'acconfig.h' + When the configure script creates a portability header file, by + using 'AM_CONFIG_HEADER' (or, if not using automake, + 'AC_CONFIG_HEADER'), this file is used to describe macros which are + not recognized by the 'autoheader' command. This is normally a + fairly uninteresting file, consisting of a collection of '#undef' + lines with comments. Normally any call to 'AC_DEFINE' in + 'configure.in' will require a line in this file. *Note Write + acconfig.h::. + +'acinclude.m4' + This file is not always required. It defines local autoconf + macros. These macros may then be used in 'configure.in'. If you + don't need any local autoconf macros, then you don't need this file + at all. In fact, in general, you never need local autoconf macros, + since you can put everything in 'configure.in', but sometimes a + local macro is convenient. + + Newer tools may omit 'acinclude.m4', and instead use a + subdirectory, typically named 'm4', and define 'ACLOCAL_AMFLAGS = + -I m4' in 'Makefile.am' to force 'aclocal' to look there for macro + definitions. The macro definitions are then placed in separate + files in that directory. + + The 'acinclude.m4' file is only used when using automake; in older + tools, the developer writes 'aclocal.m4' directly, if it is needed. + + +File: configure.info, Node: Generated Developer Files, Prev: Written Developer Files, Up: Developer Files + +3.1.3 Generated Developer Files +------------------------------- + +The following files would be generated by the developer. + + When using automake, these files are normally not generated manually +after the first time. Instead, the generated 'Makefile' contains rules +to automatically rebuild the files as required. When +'AM_MAINTAINER_MODE' is used in 'configure.in' (the normal case in +Cygnus code), the automatic rebuilding rules will only be defined if you +configure using the '--enable-maintainer-mode' option. + + When using automatic rebuilding, it is important to ensure that all +the various tools have been built and installed on your 'PATH'. Using +automatic rebuilding is highly recommended, so much so that I'm not +going to explain what you have to do if you don't use it. + +'configure' + This is the configure script which will be run when building the + package. This is generated by 'autoconf' from 'configure.in' and + 'aclocal.m4'. This is a shell script. + +'Makefile.in' + This is the file which the configure script will turn into the + 'Makefile' at build time. This file is generated by 'automake' + from 'Makefile.am'. If you aren't using automake, you must write + this file yourself. This file is pretty much a normal 'Makefile', + with some configure substitutions for certain variables. + +'aclocal.m4' + This file is created by the 'aclocal' program, based on the + contents of 'configure.in' and 'acinclude.m4' (or, as noted in the + description of 'acinclude.m4' above, on the contents of an 'm4' + subdirectory). This file contains definitions of autoconf macros + which 'autoconf' will use when generating the file 'configure'. + These autoconf macros may be defined by you in 'acinclude.m4' or + they may be defined by other packages such as automake, libtool or + gettext. If you aren't using automake, you will normally write + this file yourself; in that case, if 'configure.in' uses only + standard autoconf macros, this file will not be needed at all. + +'config.in' + This file is created by 'autoheader' based on 'acconfig.h' and + 'configure.in'. At build time, the configure script will define + some of the macros in it to create 'config.h', which may then be + included by your program. This permits your C code to use + preprocessor conditionals to change its behaviour based on the + characteristics of the host system. This file may also be called + 'config.h.in'. + +'stamp.h-in' + This rather uninteresting file, which I omitted from the picture, + is generated by 'automake'. It always contains the string + 'timestamp'. It is used as a timestamp file indicating whether + 'config.in' is up to date. Using a timestamp file means that + 'config.in' can be marked as up to date without actually changing + its modification time. This is useful since 'config.in' depends + upon 'configure.in', but it is easy to change 'configure.in' in a + way which does not affect 'config.in'. + + +File: configure.info, Node: Build Files, Next: Support Files, Prev: Developer Files, Up: Files + +3.2 Build Files +=============== + +This section describes the files which are created at configure and +build time. These are the files which somebody who builds the package +will see. + + Of course, the developer will also build the package. The +distinction between developer files and build files is not that the +developer does not see the build files, but that somebody who only +builds the package does not have to worry about the developer files. + +* Menu: + +* Build Files Picture:: Build Files Picture. +* Build Files Description:: Build Files Description. + + +File: configure.info, Node: Build Files Picture, Next: Build Files Description, Up: Build Files + +3.2.1 Build Files Picture +------------------------- + +Here is a picture of the files which will be created at build time. +'config.status' is both a created file and a shell script which is run +to create other files, and the picture attempts to show that. + + config.in *configure* Makefile.in + | | | + | v | + | config.status | + | | | + *config.status*<======+==========>*config.status* + | | + v v + config.h Makefile + +File: configure.info, Node: Build Files Description, Prev: Build Files Picture, Up: Build Files + +3.2.2 Build Files Description +----------------------------- + +This is a description of the files which are created at build time. + +'config.status' + The first step in building a package is to run the 'configure' + script. The 'configure' script will create the file + 'config.status', which is itself a shell script. When you first + run 'configure', it will automatically run 'config.status'. An + 'Makefile' derived from an automake generated 'Makefile.in' will + contain rules to automatically run 'config.status' again when + necessary to recreate certain files if their inputs change. + +'Makefile' + This is the file which make will read to build the program. The + 'config.status' script will transform 'Makefile.in' into + 'Makefile'. + +'config.h' + This file defines C preprocessor macros which C code can use to + adjust its behaviour on different systems. The 'config.status' + script will transform 'config.in' into 'config.h'. + +'config.cache' + This file did not fit neatly into the picture, and I omitted it. + It is used by the 'configure' script to cache results between runs. + This can be an important speedup. If you modify 'configure.in' in + such a way that the results of old tests should change (perhaps you + have added a new library to 'LDFLAGS'), then you will have to + remove 'config.cache' to force the tests to be rerun. + + The autoconf manual explains how to set up a site specific cache + file. This can speed up running 'configure' scripts on your + system. + +'stamp.h' + This file, which I omitted from the picture, is similar to + 'stamp-h.in'. It is used as a timestamp file indicating whether + 'config.h' is up to date. This is useful since 'config.h' depends + upon 'config.status', but it is easy for 'config.status' to change + in a way which does not affect 'config.h'. + + +File: configure.info, Node: Support Files, Prev: Build Files, Up: Files + +3.3 Support Files +================= + +The GNU configure and build system requires several support files to be +included with your distribution. You do not normally need to concern +yourself with these. If you are using the Cygnus tree, most are already +present. Otherwise, they will be installed with your source by +'automake' (with the '--add-missing' option) and 'libtoolize'. + + You don't have to put the support files in the top level directory. +You can put them in a subdirectory, and use the 'AC_CONFIG_AUX_DIR' +macro in 'configure.in' to tell 'automake' and the 'configure' script +where they are. + + In this section, I describe the support files, so that you can know +what they are and why they are there. + +'ABOUT-NLS' + Added by automake if you are using gettext. This is a + documentation file about the gettext project. +'ansi2knr.c' + Used by an automake generated 'Makefile' if you put 'ansi2knr' in + 'AUTOMAKE_OPTIONS' in 'Makefile.am'. This permits compiling ANSI C + code with a K&R C compiler. +'ansi2knr.1' + The man page which goes with 'ansi2knr.c'. +'config.guess' + A shell script which determines the configuration name for the + system on which it is run. +'config.sub' + A shell script which canonicalizes a configuration name entered by + a user. +'elisp-comp' + Used to compile Emacs LISP files. +'install-sh' + A shell script which installs a program. This is used if the + configure script can not find an install binary. +'ltconfig' + Used by libtool. This is a shell script which configures libtool + for the particular system on which it is used. +'ltmain.sh' + Used by libtool. This is the actual libtool script which is used, + after it is configured by 'ltconfig' to build a library. +'mdate-sh' + A shell script used by an automake generated 'Makefile' to pretty + print the modification time of a file. This is used to maintain + version numbers for texinfo files. +'missing' + A shell script used if some tool is missing entirely. This is used + by an automake generated 'Makefile' to avoid certain sorts of + timestamp problems. +'mkinstalldirs' + A shell script which creates a directory, including all parent + directories. This is used by an automake generated 'Makefile' + during installation. +'texinfo.tex' + Required if you have any texinfo files. This is used when + converting Texinfo files into DVI using 'texi2dvi' and TeX. +'ylwrap' + A shell script used by an automake generated 'Makefile' to run + programs like 'bison', 'yacc', 'flex', and 'lex'. These programs + default to producing output files with a fixed name, and the + 'ylwrap' script runs them in a subdirectory to avoid file name + conflicts when using a parallel make program. + + +File: configure.info, Node: Configuration Names, Next: Cross Compilation Tools, Prev: Files, Up: Top + +4 Configuration Names +********************* + +The GNU configure system names all systems using a "configuration name". +All such names used to be triplets (they may now contain four parts in +certain cases), and the term "configuration triplet" is still seen. + +* Menu: + +* Configuration Name Definition:: Configuration Name Definition. +* Using Configuration Names:: Using Configuration Names. + + +File: configure.info, Node: Configuration Name Definition, Next: Using Configuration Names, Up: Configuration Names + +4.1 Configuration Name Definition +================================= + +This is a string of the form CPU-MANUFACTURER-OPERATING_SYSTEM. In some +cases, this is extended to a four part form: +CPU-MANUFACTURER-KERNEL-OPERATING_SYSTEM. + + When using a configuration name in a configure option, it is normally +not necessary to specify an entire name. In particular, the +MANUFACTURER field is often omitted, leading to strings such as +'i386-linux' or 'sparc-sunos'. The shell script 'config.sub' will +translate these shortened strings into the canonical form. autoconf +will arrange for 'config.sub' to be run automatically when it is needed. + + The fields of a configuration name are as follows: + +CPU + The type of processor. This is typically something like 'i386' or + 'sparc'. More specific variants are used as well, such as 'mipsel' + to indicate a little endian MIPS processor. +MANUFACTURER + A somewhat freeform field which indicates the manufacturer of the + system. This is often simply 'unknown'. Other common strings are + 'pc' for an IBM PC compatible system, or the name of a workstation + vendor, such as 'sun'. +OPERATING_SYSTEM + The name of the operating system which is run on the system. This + will be something like 'solaris2.5' or 'irix6.3'. There is no + particular restriction on the version number, and strings like + 'aix4.1.4.0' are seen. For an embedded system, which has no + operating system, this field normally indicates the type of object + file format, such as 'elf' or 'coff'. +KERNEL + This is used mainly for GNU/Linux. A typical GNU/Linux + configuration name is 'i586-pc-linux-gnulibc1'. In this case the + kernel, 'linux', is separated from the operating system, + 'gnulibc1'. + + The shell script 'config.guess' will normally print the correct +configuration name for the system on which it is run. It does by +running 'uname' and by examining other characteristics of the system. + + Because 'config.guess' can normally determine the configuration name +for a machine, it is normally only necessary to specify a configuration +name when building a cross-compiler or when building using a +cross-compiler. + + +File: configure.info, Node: Using Configuration Names, Prev: Configuration Name Definition, Up: Configuration Names + +4.2 Using Configuration Names +============================= + +A configure script will sometimes have to make a decision based on a +configuration name. You will need to do this if you have to compile +code differently based on something which can not be tested using a +standard autoconf feature test. + + It is normally better to test for particular features, rather than to +test for a particular system. This is because as Unix evolves, +different systems copy features from one another. Even if you need to +determine whether the feature is supported based on a configuration +name, you should define a macro which describes the feature, rather than +defining a macro which describes the particular system you are on. + + Testing for a particular system is normally done using a case +statement in 'configure.in'. The case statement might look something +like the following, assuming that 'host' is a shell variable holding a +canonical configuration name (which will be the case if 'configure.in' +uses the 'AC_CANONICAL_HOST' or 'AC_CANONICAL_SYSTEM' macro). + + case "${host}" in + i[3-7]86-*-linux-gnu*) do something ;; + sparc*-sun-solaris2.[56789]*) do something ;; + sparc*-sun-solaris*) do something ;; + mips*-*-elf*) do something ;; + esac + + It is particularly important to use '*' after the operating system +field, in order to match the version number which will be generated by +'config.guess'. + + In most cases you must be careful to match a range of processor +types. For most processor families, a trailing '*' suffices, as in +'mips*' above. For the i386 family, something along the lines of +'i[3-7]86' suffices at present. For the m68k family, you will need +something like 'm68*'. Of course, if you do not need to match on the +processor, it is simpler to just replace the entire field by a '*', as +in '*-*-irix*'. + + +File: configure.info, Node: Cross Compilation Tools, Next: Canadian Cross, Prev: Configuration Names, Up: Top + +5 Cross Compilation Tools +************************* + +The GNU configure and build system can be used to build "cross +compilation" tools. A cross compilation tool is a tool which runs on +one system and produces code which runs on another system. + +* Menu: + +* Cross Compilation Concepts:: Cross Compilation Concepts. +* Host and Target:: Host and Target. +* Using the Host Type:: Using the Host Type. +* Specifying the Target:: Specifying the Target. +* Using the Target Type:: Using the Target Type. +* Cross Tools in the Cygnus Tree:: Cross Tools in the Cygnus Tree + + +File: configure.info, Node: Cross Compilation Concepts, Next: Host and Target, Up: Cross Compilation Tools + +5.1 Cross Compilation Concepts +============================== + +A compiler which produces programs which run on a different system is a +cross compilation compiler, or simply a "cross compiler". Similarly, we +speak of cross assemblers, cross linkers, etc. + + In the normal case, a compiler produces code which runs on the same +system as the one on which the compiler runs. When it is necessary to +distinguish this case from the cross compilation case, such a compiler +is called a "native compiler". Similarly, we speak of native +assemblers, etc. + + Although the debugger is not strictly speaking a compilation tool, it +is nevertheless meaningful to speak of a cross debugger: a debugger +which is used to debug code which runs on another system. Everything +that is said below about configuring cross compilation tools applies to +the debugger as well. + + +File: configure.info, Node: Host and Target, Next: Using the Host Type, Prev: Cross Compilation Concepts, Up: Cross Compilation Tools + +5.2 Host and Target +=================== + +When building cross compilation tools, there are two different systems +involved: the system on which the tools will run, and the system for +which the tools generate code. + + The system on which the tools will run is called the "host" system. + + The system for which the tools generate code is called the "target" +system. + + For example, suppose you have a compiler which runs on a GNU/Linux +system and generates ELF programs for a MIPS embedded system. In this +case the GNU/Linux system is the host, and the MIPS ELF system is the +target. Such a compiler could be called a GNU/Linux cross MIPS ELF +compiler, or, equivalently, a 'i386-linux-gnu' cross 'mips-elf' +compiler. + + Naturally, most programs are not cross compilation tools. For those +programs, it does not make sense to speak of a target. It only makes +sense to speak of a target for tools like 'gcc' or the 'binutils' which +actually produce running code. For example, it does not make sense to +speak of the target of a tool like 'bison' or 'make'. + + Most cross compilation tools can also serve as native tools. For a +native compilation tool, it is still meaningful to speak of a target. +For a native tool, the target is the same as the host. For example, for +a GNU/Linux native compiler, the host is GNU/Linux, and the target is +also GNU/Linux. + + +File: configure.info, Node: Using the Host Type, Next: Specifying the Target, Prev: Host and Target, Up: Cross Compilation Tools + +5.3 Using the Host Type +======================= + +In almost all cases the host system is the system on which you run the +'configure' script, and on which you build the tools (for the case when +they differ, *note Canadian Cross::). + + If your configure script needs to know the configuration name of the +host system, and the package is not a cross compilation tool and +therefore does not have a target, put 'AC_CANONICAL_HOST' in +'configure.in'. This macro will arrange to define a few shell variables +when the 'configure' script is run. + +'host' + The canonical configuration name of the host. This will normally + be determined by running the 'config.guess' shell script, although + the user is permitted to override this by using an explicit + '--host' option. +'host_alias' + In the unusual case that the user used an explicit '--host' option, + this will be the argument to '--host'. In the normal case, this + will be the same as the 'host' variable. +'host_cpu' +'host_vendor' +'host_os' + The first three parts of the canonical configuration name. + + The shell variables may be used by putting shell code in +'configure.in'. For an example, see *note Using Configuration Names::. + + +File: configure.info, Node: Specifying the Target, Next: Using the Target Type, Prev: Using the Host Type, Up: Cross Compilation Tools + +5.4 Specifying the Target +========================= + +By default, the 'configure' script will assume that the target is the +same as the host. This is the more common case; for example, it leads +to a native compiler rather than a cross compiler. + + If you want to build a cross compilation tool, you must specify the +target explicitly by using the '--target' option when you run +'configure'. The argument to '--target' is the configuration name of +the system for which you wish to generate code. *Note Configuration +Names::. + + For example, to build tools which generate code for a MIPS ELF +embedded system, you would use '--target mips-elf'. + + +File: configure.info, Node: Using the Target Type, Next: Cross Tools in the Cygnus Tree, Prev: Specifying the Target, Up: Cross Compilation Tools + +5.5 Using the Target Type +========================= + +When writing 'configure.in' for a cross compilation tool, you will need +to use information about the target. To do this, put +'AC_CANONICAL_SYSTEM' in 'configure.in'. + + 'AC_CANONICAL_SYSTEM' will look for a '--target' option and +canonicalize it using the 'config.sub' shell script. It will also run +'AC_CANONICAL_HOST' (*note Using the Host Type::). + + The target type will be recorded in the following shell variables. +Note that the host versions of these variables will also be defined by +'AC_CANONICAL_HOST'. + +'target' + The canonical configuration name of the target. +'target_alias' + The argument to the '--target' option. If the user did not specify + a '--target' option, this will be the same as 'host_alias'. +'target_cpu' +'target_vendor' +'target_os' + The first three parts of the canonical target configuration name. + + Note that if 'host' and 'target' are the same string, you can assume +a native configuration. If they are different, you can assume a cross +configuration. + + It is arguably possible for 'host' and 'target' to represent the same +system, but for the strings to not be identical. For example, if +'config.guess' returns 'sparc-sun-sunos4.1.4', and somebody configures +with '--target sparc-sun-sunos4.1', then the slight differences between +the two versions of SunOS may be unimportant for your tool. However, in +the general case it can be quite difficult to determine whether the +differences between two configuration names are significant or not. +Therefore, by convention, if the user specifies a '--target' option +without specifying a '--host' option, it is assumed that the user wants +to configure a cross compilation tool. + + The variables 'target' and 'target_alias' should be handled +differently. + + In general, whenever the user may actually see a string, +'target_alias' should be used. This includes anything which may appear +in the file system, such as a directory name or part of a tool name. It +also includes any tool output, unless it is clearly labelled as the +canonical target configuration name. This permits the user to use the +'--target' option to specify how the tool will appear to the outside +world. + + On the other hand, when checking for characteristics of the target +system, 'target' should be used. This is because a wide variety of +'--target' options may map into the same canonical configuration name. +You should not attempt to duplicate the canonicalization done by +'config.sub' in your own code. + + By convention, cross tools are installed with a prefix of the +argument used with the '--target' option, also known as 'target_alias' +(*note Using the Target Type::). If the user does not use the +'--target' option, and thus is building a native tool, no prefix is +used. + + For example, if gcc is configured with '--target mips-elf', then the +installed binary will be named 'mips-elf-gcc'. If gcc is configured +without a '--target' option, then the installed binary will be named +'gcc'. + + The autoconf macro 'AC_ARG_PROGRAM' will handle this for you. If you +are using automake, no more need be done; the programs will +automatically be installed with the correct prefixes. Otherwise, see +the autoconf documentation for 'AC_ARG_PROGRAM'. + + +File: configure.info, Node: Cross Tools in the Cygnus Tree, Prev: Using the Target Type, Up: Cross Compilation Tools + +5.6 Cross Tools in the Cygnus Tree +================================== + +The Cygnus tree is used for various packages including gdb, the GNU +binutils, and egcs. It is also, of course, used for Cygnus releases. + + In the Cygnus tree, the top level 'configure' script uses the old +Cygnus configure system, not autoconf. The top level 'Makefile.in' is +written to build packages based on what is in the source tree, and +supports building a large number of tools in a single 'configure'/'make' +step. + + The Cygnus tree may be configured with a '--target' option. The +'--target' option applies recursively to every subdirectory, and permits +building an entire set of cross tools at once. + +* Menu: + +* Host and Target Libraries:: Host and Target Libraries. +* Target Library Configure Scripts:: Target Library Configure Scripts. +* Make Targets in Cygnus Tree:: Make Targets in Cygnus Tree. +* Target libiberty:: Target libiberty + + +File: configure.info, Node: Host and Target Libraries, Next: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree + +5.6.1 Host and Target Libraries +------------------------------- + +The Cygnus tree distinguishes host libraries from target libraries. + + Host libraries are built with the compiler used to build the programs +which run on the host, which is called the host compiler. This includes +libraries such as 'bfd' and 'tcl'. These libraries are built with the +host compiler, and are linked into programs like the binutils or gcc +which run on the host. + + Target libraries are built with the target compiler. If gcc is +present in the source tree, then the target compiler is the gcc that is +built using the host compiler. Target libraries are libraries such as +'newlib' and 'libstdc++'. These libraries are not linked into the host +programs, but are instead made available for use with programs built +with the target compiler. + + For the rest of this section, assume that gcc is present in the +source tree, so that it will be used to build the target libraries. + + There is a complication here. The configure process needs to know +which compiler you are going to use to build a tool; otherwise, the +feature tests will not work correctly. The Cygnus tree handles this by +not configuring the target libraries until the target compiler is built. +In order to permit everything to build using a single +'configure'/'make', the configuration of the target libraries is +actually triggered during the make step. + + When the target libraries are configured, the '--target' option is +not used. Instead, the '--host' option is used with the argument of the +'--target' option for the overall configuration. If no '--target' +option was used for the overall configuration, the '--host' option will +be passed with the output of the 'config.guess' shell script. Any +'--build' option is passed down unchanged. + + This translation of configuration options is done because since the +target libraries are compiled with the target compiler, they are being +built in order to run on the target of the overall configuration. By +the definition of host, this means that their host system is the same as +the target system of the overall configuration. + + The same process is used for both a native configuration and a cross +configuration. Even when using a native configuration, the target +libraries will be configured and built using the newly built compiler. +This is particularly important for the C++ libraries, since there is no +reason to assume that the C++ compiler used to build the host tools (if +there even is one) uses the same ABI as the g++ compiler which will be +used to build the target libraries. + + There is one difference between a native configuration and a cross +configuration. In a native configuration, the target libraries are +normally configured and built as siblings of the host tools. In a cross +configuration, the target libraries are normally built in a subdirectory +whose name is the argument to '--target'. This is mainly for historical +reasons. + + To summarize, running 'configure' in the Cygnus tree configures all +the host libraries and tools, but does not configure any of the target +libraries. Running 'make' then does the following steps: + + * Build the host libraries. + * Build the host programs, including gcc. Note that we call gcc both + a host program (since it runs on the host) and a target compiler + (since it generates code for the target). + * Using the newly built target compiler, configure the target + libraries. + * Build the target libraries. + + The steps need not be done in precisely this order, since they are +actually controlled by 'Makefile' targets. + + +File: configure.info, Node: Target Library Configure Scripts, Next: Make Targets in Cygnus Tree, Prev: Host and Target Libraries, Up: Cross Tools in the Cygnus Tree + +5.6.2 Target Library Configure Scripts +-------------------------------------- + +There are a few things you must know in order to write a configure +script for a target library. This is just a quick sketch, and beginners +shouldn't worry if they don't follow everything here. + + The target libraries are configured and built using a newly built +target compiler. There may not be any startup files or libraries for +this target compiler. In fact, those files will probably be built as +part of some target library, which naturally means that they will not +exist when your target library is configured. + + This means that the configure script for a target library may not use +any test which requires doing a link. This unfortunately includes many +useful autoconf macros, such as 'AC_CHECK_FUNCS'. autoconf macros which +do a compile but not a link, such as 'AC_CHECK_HEADERS', may be used. + + This is a severe restriction, but normally not a fatal one, as target +libraries can often assume the presence of other target libraries, and +thus know which functions will be available. + + As of this writing, the autoconf macro 'AC_PROG_CC' does a link to +make sure that the compiler works. This may fail in a target library, +so target libraries must use a different set of macros to locate the +compiler. See the 'configure.in' file in a directory like 'libiberty' +or 'libgloss' for an example. + + As noted in the previous section, target libraries are sometimes +built in directories which are siblings to the host tools, and are +sometimes built in a subdirectory. The '--with-target-subdir' configure +option will be passed when the library is configured. Its value will be +an empty string if the target library is a sibling. Its value will be +the name of the subdirectory if the target library is in a subdirectory. + + If the overall build is not a native build (i.e., the overall +configure used the '--target' option), then the library will be +configured with the '--with-cross-host' option. The value of this +option will be the host system of the overall build. Recall that the +host system of the library will be the target of the overall build. If +the overall build is a native build, the '--with-cross-host' option will +not be used. + + A library which can be built both standalone and as a target library +may want to install itself into different directories depending upon the +case. When built standalone, or when built native, the library should +be installed in '$(libdir)'. When built as a target library which is +not native, the library should be installed in '$(tooldir)/lib'. The +'--with-cross-host' option may be used to distinguish these cases. + + This same test of '--with-cross-host' may be used to see whether it +is OK to use link tests in the configure script. If the +'--with-cross-host' option is not used, then the library is being built +either standalone or native, and a link should work. + + +File: configure.info, Node: Make Targets in Cygnus Tree, Next: Target libiberty, Prev: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree + +5.6.3 Make Targets in Cygnus Tree +--------------------------------- + +The top level 'Makefile' in the Cygnus tree defines targets for every +known subdirectory. + + For every subdirectory DIR which holds a host library or program, the +'Makefile' target 'all-DIR' will build that library or program. + + There are dependencies among host tools. For example, building gcc +requires first building gas, because the gcc build process invokes the +target assembler. These dependencies are reflected in the top level +'Makefile'. + + For every subdirectory DIR which holds a target library, the +'Makefile' target 'configure-target-DIR' will configure that library. +The 'Makefile' target 'all-target-DIR' will build that library. + + Every 'configure-target-DIR' target depends upon 'all-gcc', since +gcc, the target compiler, is required to configure the tool. Every +'all-target-DIR' target depends upon the corresponding +'configure-target-DIR' target. + + There are several other targets which may be of interest for each +directory: 'install-DIR', 'clean-DIR', and 'check-DIR'. There are also +corresponding 'target' versions of these for the target libraries , such +as 'install-target-DIR'. + + +File: configure.info, Node: Target libiberty, Prev: Make Targets in Cygnus Tree, Up: Cross Tools in the Cygnus Tree + +5.6.4 Target libiberty +---------------------- + +The 'libiberty' subdirectory is currently a special case, in that it is +the only directory which is built both using the host compiler and using +the target compiler. + + This is because the files in 'libiberty' are used when building the +host tools, and they are also incorporated into the 'libstdc++' target +library as support code. + + This duality does not pose any particular difficulties. It means +that there are targets for both 'all-libiberty' and +'all-target-libiberty'. + + In a native configuration, when target libraries are not built in a +subdirectory, the same objects are normally used as both the host build +and the target build. This is normally OK, since libiberty contains +only C code, and in a native configuration the results of the host +compiler and the target compiler are normally interoperable. + + Irix 6 is again an exception here, since the SGI native compiler +defaults to using the 'O32' ABI, and gcc defaults to using the 'N32' +ABI. On Irix 6, the target libraries are built in a subdirectory even +for a native configuration, avoiding this problem. + + There are currently no other libraries built for both the host and +the target, but there is no conceptual problem with adding more. + + +File: configure.info, Node: Canadian Cross, Next: Cygnus Configure, Prev: Cross Compilation Tools, Up: Top + +6 Canadian Cross +**************** + +It is possible to use the GNU configure and build system to build a +program which will run on a system which is different from the system on +which the tools are built. In other words, it is possible to build +programs using a cross compiler. + + This is referred to as a "Canadian Cross". + +* Menu: + +* Canadian Cross Example:: Canadian Cross Example. +* Canadian Cross Concepts:: Canadian Cross Concepts. +* Build Cross Host Tools:: Build Cross Host Tools. +* Build and Host Options:: Build and Host Options. +* CCross not in Cygnus Tree:: Canadian Cross not in Cygnus Tree. +* CCross in Cygnus Tree:: Canadian Cross in Cygnus Tree. +* Supporting Canadian Cross:: Supporting Canadian Cross. + + +File: configure.info, Node: Canadian Cross Example, Next: Canadian Cross Concepts, Up: Canadian Cross + +6.1 Canadian Cross Example +========================== + +Here is an example of a Canadian Cross. + + While running on a GNU/Linux, you can build a program which will run +on a Solaris system. You would use a GNU/Linux cross Solaris compiler +to build the program. + + Of course, you could not run the resulting program on your GNU/Linux +system. You would have to copy it over to a Solaris system before you +would run it. + + Of course, you could also simply build the programs on the Solaris +system in the first place. However, perhaps the Solaris system is not +available for some reason; perhaps you actually don't have one, but you +want to build the tools for somebody else to use. Or perhaps your +GNU/Linux system is much faster than your Solaris system. + + A Canadian Cross build is most frequently used when building programs +to run on a non-Unix system, such as DOS or Windows. It may be simpler +to configure and build on a Unix system than to support the +configuration machinery on a non-Unix system. + + +File: configure.info, Node: Canadian Cross Concepts, Next: Build Cross Host Tools, Prev: Canadian Cross Example, Up: Canadian Cross + +6.2 Canadian Cross Concepts +=========================== + +When building a Canadian Cross, there are at least two different systems +involved: the system on which the tools are being built, and the system +on which the tools will run. + + The system on which the tools are being built is called the "build" +system. + + The system on which the tools will run is called the host system. + + For example, if you are building a Solaris program on a GNU/Linux +system, as in the previous section, the build system would be GNU/Linux, +and the host system would be Solaris. + + It is, of course, possible to build a cross compiler using a Canadian +Cross (i.e., build a cross compiler using a cross compiler). In this +case, the system for which the resulting cross compiler generates code +is called the target system. (For a more complete discussion of host +and target systems, *note Host and Target::). + + An example of building a cross compiler using a Canadian Cross would +be building a Windows cross MIPS ELF compiler on a GNU/Linux system. In +this case the build system would be GNU/Linux, the host system would be +Windows, and the target system would be MIPS ELF. + + The name Canadian Cross comes from the case when the build, host, and +target systems are all different. At the time that these issues were +all being hashed out, Canada had three national political parties. + + +File: configure.info, Node: Build Cross Host Tools, Next: Build and Host Options, Prev: Canadian Cross Concepts, Up: Canadian Cross + +6.3 Build Cross Host Tools +========================== + +In order to configure a program for a Canadian Cross build, you must +first build and install the set of cross tools you will use to build the +program. + + These tools will be build cross host tools. That is, they will run +on the build system, and will produce code that runs on the host system. + + It is easy to confuse the meaning of build and host here. Always +remember that the build system is where you are doing the build, and the +host system is where the resulting program will run. Therefore, you +need a build cross host compiler. + + In general, you must have a complete cross environment in order to do +the build. This normally means a cross compiler, cross assembler, and +so forth, as well as libraries and include files for the host system. + + +File: configure.info, Node: Build and Host Options, Next: CCross not in Cygnus Tree, Prev: Build Cross Host Tools, Up: Canadian Cross + +6.4 Build and Host Options +========================== + +When you run 'configure', you must use both the '--build' and '--host' +options. + + The '--build' option is used to specify the configuration name of the +build system. This can normally be the result of running the +'config.guess' shell script, and it is reasonable to use +'--build=`config.guess`'. + + The '--host' option is used to specify the configuration name of the +host system. + + As we explained earlier, 'config.guess' is used to set the default +value for the '--host' option (*note Using the Host Type::). We can now +see that since 'config.guess' returns the type of system on which it is +run, it really identifies the build system. Since the host system is +normally the same as the build system (i.e., people do not normally +build using a cross compiler), it is reasonable to use the result of +'config.guess' as the default for the host system when the '--host' +option is not used. + + It might seem that if the '--host' option were used without the +'--build' option that the configure script could run 'config.guess' to +determine the build system, and presume a Canadian Cross if the result +of 'config.guess' differed from the '--host' option. However, for +historical reasons, some configure scripts are routinely run using an +explicit '--host' option, rather than using the default from +'config.guess'. As noted earlier, it is difficult or impossible to +reliably compare configuration names (*note Using the Target Type::). +Therefore, by convention, if the '--host' option is used, but the +'--build' option is not used, then the build system defaults to the host +system. + + +File: configure.info, Node: CCross not in Cygnus Tree, Next: CCross in Cygnus Tree, Prev: Build and Host Options, Up: Canadian Cross + +6.5 Canadian Cross not in Cygnus Tree. +====================================== + +If you are not using the Cygnus tree, you must explicitly specify the +cross tools which you want to use to build the program. This is done by +setting environment variables before running the 'configure' script. + + You must normally set at least the environment variables 'CC', 'AR', +and 'RANLIB' to the cross tools which you want to use to build. + + For some programs, you must set additional cross tools as well, such +as 'AS', 'LD', or 'NM'. + + You would set these environment variables to the build cross tools +which you are going to use. + + For example, if you are building a Solaris program on a GNU/Linux +system, and your GNU/Linux cross Solaris compiler were named +'solaris-gcc', then you would set the environment variable 'CC' to +'solaris-gcc'. + + +File: configure.info, Node: CCross in Cygnus Tree, Next: Supporting Canadian Cross, Prev: CCross not in Cygnus Tree, Up: Canadian Cross + +6.6 Canadian Cross in Cygnus Tree +================================= + +This section describes configuring and building a Canadian Cross when +using the Cygnus tree. + +* Menu: + +* Standard Cygnus CCross:: Building a Normal Program. +* Cross Cygnus CCross:: Building a Cross Program. + + +File: configure.info, Node: Standard Cygnus CCross, Next: Cross Cygnus CCross, Up: CCross in Cygnus Tree + +6.6.1 Building a Normal Program +------------------------------- + +When configuring a Canadian Cross in the Cygnus tree, all the +appropriate environment variables are automatically set to 'HOST-TOOL', +where HOST is the value used for the '--host' option, and TOOL is the +name of the tool (e.g., 'gcc', 'as', etc.). These tools must be on your +'PATH'. + + Adding a prefix of HOST will give the usual name for the build cross +host tools. To see this, consider that when these cross tools were +built, they were configured to run on the build system and to produce +code for the host system. That is, they were configured with a +'--target' option that is the same as the system which we are now +calling the host. Recall that the default name for installed cross +tools uses the target system as a prefix (*note Using the Target +Type::). Since that is the system which we are now calling the host, +HOST is the right prefix to use. + + For example, if you configure with '--build=i386-linux-gnu' and +'--host=solaris', then the Cygnus tree will automatically default to +using the compiler 'solaris-gcc'. You must have previously built and +installed this compiler, probably by doing a build with no '--host' +option and with a '--target' option of 'solaris'. + + +File: configure.info, Node: Cross Cygnus CCross, Prev: Standard Cygnus CCross, Up: CCross in Cygnus Tree + +6.6.2 Building a Cross Program +------------------------------ + +There are additional considerations if you want to build a cross +compiler, rather than a native compiler, in the Cygnus tree using a +Canadian Cross. + + When you build a cross compiler using the Cygnus tree, then the +target libraries will normally be built with the newly built target +compiler (*note Host and Target Libraries::). However, this will not +work when building with a Canadian Cross. This is because the newly +built target compiler will be a program which runs on the host system, +and therefore will not be able to run on the build system. + + Therefore, when building a cross compiler with the Cygnus tree, you +must first install a set of build cross target tools. These tools will +be used when building the target libraries. + + Note that this is not a requirement of a Canadian Cross in general. +For example, it would be possible to build just the host cross target +tools on the build system, to copy the tools to the host system, and to +build the target libraries on the host system. The requirement for +build cross target tools is imposed by the Cygnus tree, which expects to +be able to build both host programs and target libraries in a single +'configure'/'make' step. Because it builds these in a single step, it +expects to be able to build the target libraries on the build system, +which means that it must use a build cross target toolchain. + + For example, suppose you want to build a Windows cross MIPS ELF +compiler on a GNU/Linux system. You must have previously installed both +a GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF +compiler. + + In order to build the Windows (configuration name 'i386-cygwin32') +cross MIPS ELF (configure name 'mips-elf') compiler, you might execute +the following commands (long command lines are broken across lines with +a trailing backslash as a continuation character). + + mkdir linux-x-cygwin32 + cd linux-x-cygwin32 + SRCDIR/configure --target i386-cygwin32 --prefix=INSTALLDIR \ + --exec-prefix=INSTALLDIR/H-i386-linux + make + make install + cd .. + mkdir linux-x-mips-elf + cd linux-x-mips-elf + SRCDIR/configure --target mips-elf --prefix=INSTALLDIR \ + --exec-prefix=INSTALLDIR/H-i386-linux + make + make install + cd .. + mkdir cygwin32-x-mips-elf + cd cygwin32-x-mips-elf + SRCDIR/configure --build=i386-linux-gnu --host=i386-cygwin32 \ + --target=mips-elf --prefix=WININSTALLDIR \ + --exec-prefix=WININSTALLDIR/H-i386-cygwin32 + make + make install + + You would then copy the contents of WININSTALLDIR over to the Windows +machine, and run the resulting programs. + + +File: configure.info, Node: Supporting Canadian Cross, Prev: CCross in Cygnus Tree, Up: Canadian Cross + +6.7 Supporting Canadian Cross +============================= + +If you want to make it possible to build a program you are developing +using a Canadian Cross, you must take some care when writing your +configure and make rules. Simple cases will normally work correctly. +However, it is not hard to write configure and make tests which will +fail in a Canadian Cross. + +* Menu: + +* CCross in Configure:: Supporting Canadian Cross in Configure Scripts. +* CCross in Make:: Supporting Canadian Cross in Makefiles. + + +File: configure.info, Node: CCross in Configure, Next: CCross in Make, Up: Supporting Canadian Cross + +6.7.1 Supporting Canadian Cross in Configure Scripts +---------------------------------------------------- + +In a 'configure.in' file, after calling 'AC_PROG_CC', you can find out +whether this is a Canadian Cross configure by examining the shell +variable 'cross_compiling'. In a Canadian Cross, which means that the +compiler is a cross compiler, 'cross_compiling' will be 'yes'. In a +normal configuration, 'cross_compiling' will be 'no'. + + You ordinarily do not need to know the type of the build system in a +configure script. However, if you do need that information, you can get +it by using the macro 'AC_CANONICAL_SYSTEM', the same macro that is used +to determine the target system. This macro will set the variables +'build', 'build_alias', 'build_cpu', 'build_vendor', and 'build_os', +which correspond to the similar 'target' and 'host' variables, except +that they describe the build system. + + When writing tests in 'configure.in', you must remember that you want +to test the host environment, not the build environment. + + Macros like 'AC_CHECK_FUNCS' which use the compiler will test the +host environment. That is because the tests will be done by running the +compiler, which is actually a build cross host compiler. If the +compiler can find the function, that means that the function is present +in the host environment. + + Tests like 'test -f /dev/ptyp0', on the other hand, will test the +build environment. Remember that the configure script is running on the +build system, not the host system. If your configure scripts examines +files, those files will be on the build system. Whatever you determine +based on those files may or may not be the case on the host system. + + Most autoconf macros will work correctly for a Canadian Cross. The +main exception is 'AC_TRY_RUN'. This macro tries to compile and run a +test program. This will fail in a Canadian Cross, because the program +will be compiled for the host system, which means that it will not run +on the build system. + + The 'AC_TRY_RUN' macro provides an optional argument to tell the +configure script what to do in a Canadian Cross. If that argument is +not present, you will get a warning when you run 'autoconf': + warning: AC_TRY_RUN called without default to allow cross compiling +This tells you that the resulting 'configure' script will not work with +a Canadian Cross. + + In some cases while it may better to perform a test at configure +time, it is also possible to perform the test at run time. In such a +case you can use the cross compiling argument to 'AC_TRY_RUN' to tell +your program that the test could not be performed at configure time. + + There are a few other autoconf macros which will not work correctly +with a Canadian Cross: a partial list is 'AC_FUNC_GETPGRP', +'AC_FUNC_SETPGRP', 'AC_FUNC_SETVBUF_REVERSED', and +'AC_SYS_RESTARTABLE_SYSCALLS'. The 'AC_CHECK_SIZEOF' macro is generally +not very useful with a Canadian Cross; it permits an optional argument +indicating the default size, but there is no way to know what the +correct default should be. + + +File: configure.info, Node: CCross in Make, Prev: CCross in Configure, Up: Supporting Canadian Cross + +6.7.2 Supporting Canadian Cross in Makefiles. +--------------------------------------------- + +The main Canadian Cross issue in a 'Makefile' arises when you want to +use a subsidiary program to generate code or data which you will then +include in your real program. + + If you compile this subsidiary program using '$(CC)' in the usual +way, you will not be able to run it. This is because '$(CC)' will build +a program for the host system, but the program is being built on the +build system. + + You must instead use a compiler for the build system, rather than the +host system. In the Cygnus tree, this make variable '$(CC_FOR_BUILD)' +will hold a compiler for the build system. + + Note that you should not include 'config.h' in a file you are +compiling with '$(CC_FOR_BUILD)'. The 'configure' script will build +'config.h' with information for the host system. However, you are +compiling the file using a compiler for the build system (a native +compiler). Subsidiary programs are normally simple filters which do no +user interaction, and it is normally possible to write them in a highly +portable fashion so that the absence of 'config.h' is not crucial. + + The gcc 'Makefile.in' shows a complex situation in which certain +files, such as 'rtl.c', must be compiled into both subsidiary programs +run on the build system and into the final program. This approach may +be of interest for advanced build system hackers. Note that the build +system compiler is rather confusingly called 'HOST_CC'. + + +File: configure.info, Node: Cygnus Configure, Next: Multilibs, Prev: Canadian Cross, Up: Top + +7 Cygnus Configure +****************** + +The Cygnus configure script predates autoconf. All of its interesting +features have been incorporated into autoconf. No new programs should +be written to use the Cygnus configure script. + + However, the Cygnus configure script is still used in a few places: +at the top of the Cygnus tree and in a few target libraries in the +Cygnus tree. Until those uses have been replaced with autoconf, some +brief notes are appropriate here. This is not complete documentation, +but it should be possible to use this as a guide while examining the +scripts themselves. + +* Menu: + +* Cygnus Configure Basics:: Cygnus Configure Basics. +* Cygnus Configure in C++ Libraries:: Cygnus Configure in C++ Libraries. + + +File: configure.info, Node: Cygnus Configure Basics, Next: Cygnus Configure in C++ Libraries, Up: Cygnus Configure + +7.1 Cygnus Configure Basics +=========================== + +Cygnus configure does not use any generated files; there is no program +corresponding to 'autoconf'. Instead, there is a single shell script +named 'configure' which may be found at the top of the Cygnus tree. +This shell script was written by hand; it was not generated by autoconf, +and it is incorrect, and indeed harmful, to run 'autoconf' in the top +level of a Cygnus tree. + + Cygnus configure works in a particular directory by examining the +file 'configure.in' in that directory. That file is broken into four +separate shell scripts. + + The first is the contents of 'configure.in' up to a line that starts +with '# per-host:'. This is the common part. + + The second is the rest of 'configure.in' up to a line that starts +with '# per-target:'. This is the per host part. + + The third is the rest of 'configure.in' up to a line that starts with +'# post-target:'. This is the per target part. + + The fourth is the remainder of 'configure.in'. This is the post +target part. + + If any of these comment lines are missing, the corresponding shell +script is empty. + + Cygnus configure will first execute the common part. This must set +the shell variable 'srctrigger' to the name of a source file, to confirm +that Cygnus configure is looking at the right directory. This may set +the shell variables 'package_makefile_frag' and +'package_makefile_rules_frag'. + + Cygnus configure will next set the 'build' and 'host' shell +variables, and execute the per host part. This may set the shell +variable 'host_makefile_frag'. + + Cygnus configure will next set the 'target' variable, and execute the +per target part. This may set the shell variable +'target_makefile_frag'. + + Any of these scripts may set the 'subdirs' shell variable. This +variable is a list of subdirectories where a 'Makefile.in' file may be +found. Cygnus configure will automatically look for a 'Makefile.in' +file in the current directory. The 'subdirs' shell variable is not +normally used, and I believe that the only directory which uses it at +present is 'newlib'. + + For each 'Makefile.in', Cygnus configure will automatically create a +'Makefile' by adding definitions for 'make' variables such as 'host' and +'target', and automatically editing the values of 'make' variables such +as 'prefix' if they are present. + + Also, if any of the 'makefile_frag' shell variables are set, Cygnus +configure will interpret them as file names relative to either the +working directory or the source directory, and will read the contents of +the file into the generated 'Makefile'. The file contents will be read +in after the first line in 'Makefile.in' which starts with '####'. + + These 'Makefile' fragments are used to customize behaviour for a +particular host or target. They serve to select particular files to +compile, and to define particular preprocessor macros by providing +values for 'make' variables which are then used during compilation. +Cygnus configure, unlike autoconf, normally does not do feature tests, +and normally requires support to be added manually for each new host. + + The 'Makefile' fragment support is similar to the autoconf +'AC_SUBST_FILE' macro. + + After creating each 'Makefile', the post target script will be run +(i.e., it may be run several times). This script may further customize +the 'Makefile'. When it is run, the shell variable 'Makefile' will hold +the name of the 'Makefile', including the appropriate directory +component. + + Like an autoconf generated 'configure' script, Cygnus configure will +create a file named 'config.status' which, when run, will automatically +recreate the configuration. The 'config.status' file will simply +execute the Cygnus configure script again with the appropriate +arguments. + + Any of the parts of 'configure.in' may set the shell variables +'files' and 'links'. Cygnus configure will set up symlinks from the +names in 'links' to the files named in 'files'. This is similar to the +autoconf 'AC_LINK_FILES' macro. + + Finally, any of the parts of 'configure.in' may set the shell +variable 'configdirs' to a set of subdirectories. If it is set, Cygnus +configure will recursively run the configure process in each +subdirectory. If the subdirectory uses Cygnus configure, it will +contain a 'configure.in' file but no 'configure' file, in which case +Cygnus configure will invoke itself recursively. If the subdirectory +has a 'configure' file, Cygnus configure assumes that it is an autoconf +generated 'configure' script, and simply invokes it directly. + + +File: configure.info, Node: Cygnus Configure in C++ Libraries, Prev: Cygnus Configure Basics, Up: Cygnus Configure + +7.2 Cygnus Configure in C++ Libraries +===================================== + +The C++ library configure system, written by Per Bothner, deserves +special mention. It uses Cygnus configure, but it does feature testing +like that done by autoconf generated 'configure' scripts. This approach +is used in the libraries 'libio', 'libstdc++', and 'libg++'. + + Most of the 'Makefile' information is written out by the shell script +'libio/config.shared'. Each 'configure.in' file sets certain shell +variables, and then invokes 'config.shared' to create two package +'Makefile' fragments. These fragments are then incorporated into the +resulting 'Makefile' by the Cygnus configure script. + + The file '_G_config.h' is created in the 'libio' object directory by +running the shell script 'libio/gen-params'. This shell script uses +feature tests to define macros and typedefs in '_G_config.h'. + + +File: configure.info, Node: Multilibs, Next: FAQ, Prev: Cygnus Configure, Up: Top + +8 Multilibs +*********** + +For some targets gcc may have different processor requirements depending +upon command line options. An obvious example is the '-msoft-float' +option supported on several processors. This option means that the +floating point registers are not available, which means that floating +point operations must be done by calling an emulation subroutine rather +than by using machine instructions. + + For such options, gcc is often configured to compile target libraries +twice: once with '-msoft-float' and once without. When gcc compiles +target libraries more than once, the resulting libraries are called +"multilibs". + + Multilibs are not really part of the GNU configure and build system, +but we discuss them here since they require support in the 'configure' +scripts and 'Makefile's used for target libraries. + +* Menu: + +* Multilibs in gcc:: Multilibs in gcc. +* Multilibs in Target Libraries:: Multilibs in Target Libraries. + + +File: configure.info, Node: Multilibs in gcc, Next: Multilibs in Target Libraries, Up: Multilibs + +8.1 Multilibs in gcc +==================== + +In gcc, multilibs are defined by setting the variable 'MULTILIB_OPTIONS' +in the target 'Makefile' fragment. Several other 'MULTILIB' variables +may also be defined there. *Note The Target Makefile Fragment: +(gcc)Target Fragment. + + If you have built gcc, you can see what multilibs it uses by running +it with the '-print-multi-lib' option. The output '.;' means that no +multilibs are used. In general, the output is a sequence of lines, one +per multilib. The first part of each line, up to the ';', is the name +of the multilib directory. The second part is a list of compiler +options separated by '@' characters. + + Multilibs are built in a tree of directories. The top of the tree, +represented by '.' in the list of multilib directories, is the default +library to use when no special compiler options are used. The +subdirectories of the tree hold versions of the library to use when +particular compiler options are used. + + +File: configure.info, Node: Multilibs in Target Libraries, Prev: Multilibs in gcc, Up: Multilibs + +8.2 Multilibs in Target Libraries +================================= + +The target libraries in the Cygnus tree are automatically built with +multilibs. That means that each library is built multiple times. + + This default is set in the top level 'configure.in' file, by adding +'--enable-multilib' to the list of arguments passed to configure when it +is run for the target libraries (*note Host and Target Libraries::). + + Each target library uses the shell script 'config-ml.in', written by +Doug Evans, to prepare to build target libraries. This shell script is +invoked after the 'Makefile' has been created by the 'configure' script. +If multilibs are not enabled, it does nothing, otherwise it modifies the +'Makefile' to support multilibs. + + The 'config-ml.in' script makes one copy of the 'Makefile' for each +multilib in the appropriate subdirectory. When configuring in the +source directory (which is not recommended), it will build a symlink +tree of the sources in each subdirectory. + + The 'config-ml.in' script sets several variables in the various +'Makefile's. The 'Makefile.in' must have definitions for these +variables already; 'config-ml.in' simply changes the existing values. +The 'Makefile' should use default values for these variables which will +do the right thing in the subdirectories. + +'MULTISRCTOP' + 'config-ml.in' will set this to a sequence of '../' strings, where + the number of strings is the number of multilib levels in the + source tree. The default value should be the empty string. +'MULTIBUILDTOP' + 'config-ml.in' will set this to a sequence of '../' strings, where + the number of strings is number of multilib levels in the object + directory. The default value should be the empty string. This + will differ from 'MULTISRCTOP' when configuring in the source tree + (which is not recommended). +'MULTIDIRS' + In the top level 'Makefile' only, 'config-ml.in' will set this to + the list of multilib subdirectories. The default value should be + the empty string. +'MULTISUBDIR' + 'config-ml.in' will set this to the installed subdirectory name to + use for this subdirectory, with a leading '/'. The default value + shold be the empty string. +'MULTIDO' +'MULTICLEAN' + In the top level 'Makefile' only, 'config-ml.in' will set these + variables to commands to use when doing a recursive make. These + variables should both default to the string 'true', so that by + default nothing happens. + + All references to the parent of the source directory should use the +variable 'MULTISRCTOP'. Instead of writing '$(srcdir)/..', you must +write '$(srcdir)/$(MULTISRCTOP)..'. + + Similarly, references to the parent of the object directory should +use the variable 'MULTIBUILDTOP'. + + In the installation target, the libraries should be installed in the +subdirectory 'MULTISUBDIR'. Instead of installing '$(libdir)/libfoo.a', +install '$(libdir)$(MULTISUBDIR)/libfoo.a'. + + The 'config-ml.in' script also modifies the top level 'Makefile' to +add 'multi-do' and 'multi-clean' targets which are used when building +multilibs. + + The default target of the 'Makefile' should include the following +command: + @$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do +This assumes that '$(FLAGS_TO_PASS)' is defined as a set of variables to +pass to a recursive invocation of 'make'. This will build all the +multilibs. Note that the default value of 'MULTIDO' is 'true', so by +default this command will do nothing. It will only do something in the +top level 'Makefile' if multilibs were enabled. + + The 'install' target of the 'Makefile' should include the following +command: + @$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do + + In general, any operation, other than clean, which should be +performed on all the multilibs should use a '$(MULTIDO)' line, setting +the variable 'DO' to the target of each recursive call to 'make'. + + The 'clean' targets ('clean', 'mostlyclean', etc.) should use +'$(MULTICLEAN)'. For example, the 'clean' target should do this: + @$(MULTICLEAN) DO=clean multi-clean + + +File: configure.info, Node: FAQ, Next: Index, Prev: Multilibs, Up: Top + +9 Frequently Asked Questions +**************************** + +Which do I run first, 'autoconf' or 'automake'? + Except when you first add autoconf or automake support to a + package, you shouldn't run either by hand. Instead, configure with + the '--enable-maintainer-mode' option, and let 'make' take care of + it. + +'autoconf' says something about undefined macros. + This means that you have macros in your 'configure.in' which are + not defined by 'autoconf'. You may be using an old version of + 'autoconf'; try building and installing a newer one. Make sure the + newly installled 'autoconf' is first on your 'PATH'. Also, see the + next question. + +My 'configure' script has stuff like 'CY_GNU_GETTEXT' in it. + This means that you have macros in your 'configure.in' which should + be defined in your 'aclocal.m4' file, but aren't. This usually + means that 'aclocal' was not able to appropriate definitions of the + macros. Make sure that you have installed all the packages you + need. In particular, make sure that you have installed libtool + (this is where 'AM_PROG_LIBTOOL' is defined) and gettext (this is + where 'CY_GNU_GETTEXT' is defined, at least in the Cygnus version + of gettext). + +My 'Makefile' has '@' characters in it. + This may mean that you tried to use an autoconf substitution in + your 'Makefile.in' without adding the appropriate 'AC_SUBST' call + to your 'configure' script. Or it may just mean that you need to + rebuild 'Makefile' in your build directory. To rebuild 'Makefile' + from 'Makefile.in', run the shell script 'config.status' with no + arguments. If you need to force 'configure' to run again, first + run 'config.status --recheck'. These runs are normally done + automatically by 'Makefile' targets, but if your 'Makefile' has + gotten messed up you'll need to help them along. + +Why do I have to run both 'config.status --recheck' and 'config.status'? + Normally, you don't; they will be run automatically by 'Makefile' + targets. If you do need to run them, use 'config.status --recheck' + to run the 'configure' script again with the same arguments as the + first time you ran it. Use 'config.status' (with no arguments) to + regenerate all files ('Makefile', 'config.h', etc.) based on the + results of the configure script. The two cases are separate + because it isn't always necessary to regenerate all the files after + running 'config.status --recheck'. The 'Makefile' targets + generated by automake will use the environment variables + 'CONFIG_FILES' and 'CONFIG_HEADERS' to only regenerate files as + they are needed. + +What is the Cygnus tree? + The Cygnus tree is used for various packages including gdb, the GNU + binutils, and egcs. It is also, of course, used for Cygnus + releases. It is the build system which was developed at Cygnus, + using the Cygnus configure script. It permits building many + different packages with a single configure and make. The configure + scripts in the tree are being converted to autoconf, but the + general build structure remains intact. + +Why do I have to keep rebuilding and reinstalling the tools? + I know, it's a pain. Unfortunately, there are bugs in the tools + themselves which need to be fixed, and each time that happens + everybody who uses the tools need to reinstall new versions of + them. I don't know if there is going to be a clever fix until the + tools stabilize. + +Why not just have a Cygnus tree 'make' target to update the tools? + The tools unfortunately need to be installed before they can be + used. That means that they must be built using an appropriate + prefix, and it seems unwise to assume that every configuration uses + an appropriate prefix. It might be possible to make them work in + place, or it might be possible to install them in some + subdirectory; so far these approaches have not been implemented. + + +File: configure.info, Node: Index, Prev: FAQ, Up: Top + +Index +***** + +[index] +* Menu: + +* '--build' option: Build and Host Options. + (line 9) +* '--host' option: Build and Host Options. + (line 14) +* '--target' option: Specifying the Target. + (line 10) +* '_GNU_SOURCE': Write configure.in. (line 132) +* 'acconfig.h': Written Developer Files. + (line 27) +* 'acconfig.h', writing: Write acconfig.h. (line 6) +* 'acinclude.m4': Written Developer Files. + (line 37) +* 'aclocal.m4': Generated Developer Files. + (line 33) +* 'AC_CANONICAL_HOST': Using the Host Type. (line 10) +* 'AC_CANONICAL_SYSTEM': Using the Target Type. + (line 6) +* 'AC_CONFIG_HEADER': Write configure.in. (line 64) +* 'AC_EXEEXT': Write configure.in. (line 84) +* 'AC_INIT': Write configure.in. (line 37) +* 'AC_OUTPUT': Write configure.in. (line 140) +* 'AC_PREREQ': Write configure.in. (line 41) +* 'AC_PROG_CC': Write configure.in. (line 101) +* 'AC_PROG_CXX': Write configure.in. (line 115) +* 'AM_CONFIG_HEADER': Write configure.in. (line 52) +* 'AM_DISABLE_SHARED': Write configure.in. (line 125) +* 'AM_EXEEXT': Write configure.in. (line 84) +* 'AM_INIT_AUTOMAKE': Write configure.in. (line 47) +* 'AM_MAINTAINER_MODE': Write configure.in. (line 68) +* 'AM_PROG_LIBTOOL': Write configure.in. (line 120) +* 'AM_PROG_LIBTOOL' in 'configure': FAQ. (line 19) +* build option: Build and Host Options. + (line 9) +* building with a cross compiler: Canadian Cross. (line 6) +* canadian cross: Canadian Cross. (line 6) +* canadian cross in configure: CCross in Configure. (line 6) +* canadian cross in cygnus tree: CCross in Cygnus Tree. + (line 6) +* canadian cross in makefile: CCross in Make. (line 6) +* canadian cross, configuring: Build and Host Options. + (line 6) +* canonical system names: Configuration Names. (line 6) +* 'config.cache': Build Files Description. + (line 28) +* 'config.h': Build Files Description. + (line 23) +* 'config.h.in': Generated Developer Files. + (line 45) +* 'config.in': Generated Developer Files. + (line 45) +* 'config.status': Build Files Description. + (line 9) +* 'config.status --recheck': FAQ. (line 40) +* configuration names: Configuration Names. (line 6) +* configuration triplets: Configuration Names. (line 6) +* 'configure': Generated Developer Files. + (line 21) +* configure build system: Build and Host Options. + (line 9) +* configure host: Build and Host Options. + (line 14) +* configure target: Specifying the Target. + (line 10) +* 'configure.in': Written Developer Files. + (line 9) +* 'configure.in', writing: Write configure.in. (line 6) +* configuring a canadian cross: Build and Host Options. + (line 6) +* cross compiler: Cross Compilation Concepts. + (line 6) +* cross compiler, building with: Canadian Cross. (line 6) +* cross tools: Cross Compilation Tools. + (line 6) +* cygnus configure: Cygnus Configure. (line 6) +* 'CY_GNU_GETTEXT' in 'configure': FAQ. (line 19) +* goals: Goals. (line 6) +* history: History. (line 6) +* host names: Configuration Names. (line 6) +* host option: Build and Host Options. + (line 14) +* host system: Host and Target. (line 6) +* host triplets: Configuration Names. (line 6) +* 'HOST_CC': CCross in Make. (line 27) +* 'libg++' configure: Cygnus Configure in C++ Libraries. + (line 6) +* 'libio' configure: Cygnus Configure in C++ Libraries. + (line 6) +* 'libstdc++' configure: Cygnus Configure in C++ Libraries. + (line 6) +* 'Makefile': Build Files Description. + (line 18) +* 'Makefile', garbage characters: FAQ. (line 29) +* 'Makefile.am': Written Developer Files. + (line 18) +* 'Makefile.am', writing: Write Makefile.am. (line 6) +* 'Makefile.in': Generated Developer Files. + (line 26) +* multilibs: Multilibs. (line 6) +* 'stamp-h': Build Files Description. + (line 40) +* 'stamp-h.in': Generated Developer Files. + (line 54) +* system names: Configuration Names. (line 6) +* system types: Configuration Names. (line 6) +* target option: Specifying the Target. + (line 10) +* target system: Host and Target. (line 6) +* triplets: Configuration Names. (line 6) +* undefined macros: FAQ. (line 12) + + + +Tag Table: +Node: Top966 +Node: Introduction1494 +Node: Goals2576 +Node: Tools3300 +Node: History4289 +Node: Building7285 +Node: Getting Started10548 +Node: Write configure.in11061 +Node: Write Makefile.am18275 +Node: Write acconfig.h21431 +Node: Generate files22968 +Node: Getting Started Example24934 +Node: Getting Started Example 125689 +Node: Getting Started Example 227610 +Node: Getting Started Example 330605 +Node: Generate Files in Example32966 +Node: Files34052 +Node: Developer Files34663 +Node: Developer Files Picture35043 +Node: Written Developer Files36343 +Node: Generated Developer Files38895 +Node: Build Files42039 +Node: Build Files Picture42700 +Node: Build Files Description43463 +Node: Support Files45463 +Node: Configuration Names48332 +Node: Configuration Name Definition48831 +Node: Using Configuration Names51151 +Node: Cross Compilation Tools53121 +Node: Cross Compilation Concepts53812 +Node: Host and Target54780 +Node: Using the Host Type56281 +Node: Specifying the Target57628 +Node: Using the Target Type58417 +Node: Cross Tools in the Cygnus Tree61847 +Node: Host and Target Libraries62904 +Node: Target Library Configure Scripts66649 +Node: Make Targets in Cygnus Tree69741 +Node: Target libiberty71089 +Node: Canadian Cross72475 +Node: Canadian Cross Example73316 +Node: Canadian Cross Concepts74435 +Node: Build Cross Host Tools75947 +Node: Build and Host Options76899 +Node: CCross not in Cygnus Tree78685 +Node: CCross in Cygnus Tree79663 +Node: Standard Cygnus CCross80084 +Node: Cross Cygnus CCross81448 +Node: Supporting Canadian Cross84248 +Node: CCross in Configure84863 +Node: CCross in Make88028 +Node: Cygnus Configure89631 +Node: Cygnus Configure Basics90466 +Node: Cygnus Configure in C++ Libraries95144 +Node: Multilibs96151 +Node: Multilibs in gcc97196 +Node: Multilibs in Target Libraries98274 +Node: FAQ102458 +Node: Index106559 + +End Tag Table diff --git a/util/X86MAC64/share/info/gdb.info b/util/X86MAC64/share/info/gdb.info new file mode 100644 index 0000000000..9606580337 --- /dev/null +++ b/util/X86MAC64/share/info/gdb.info @@ -0,0 +1,45806 @@ +This is gdb.info, produced by makeinfo version 5.1 from gdb.texinfo. + +Copyright (C) 1988-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 7.7.1. + + Copyright (C) 1988-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir) + +Debugging with GDB +****************** + +This file describes GDB, the GNU symbolic debugger. + + This is the Tenth Edition, for GDB (GDB) Version 7.7.1. + + Copyright (C) 1988-2014 Free Software Foundation, Inc. + + This edition of the GDB manual is dedicated to the memory of Fred +Fish. Fred was a long-standing contributor to GDB and to Free software +in general. We will miss him. + +* Menu: + +* Summary:: Summary of GDB +* Sample Session:: A sample GDB session + +* Invocation:: Getting in and out of GDB +* Commands:: GDB commands +* Running:: Running programs under GDB +* Stopping:: Stopping and continuing +* Reverse Execution:: Running programs backward +* Process Record and Replay:: Recording inferior's execution and replaying it +* Stack:: Examining the stack +* Source:: Examining source files +* Data:: Examining data +* Optimized Code:: Debugging optimized code +* Macros:: Preprocessor Macros +* Tracepoints:: Debugging remote targets non-intrusively +* Overlays:: Debugging programs that use overlays + +* Languages:: Using GDB with different languages + +* Symbols:: Examining the symbol table +* Altering:: Altering execution +* GDB Files:: GDB files +* Targets:: Specifying a debugging target +* Remote Debugging:: Debugging remote programs +* Configurations:: Configuration-specific information +* Controlling GDB:: Controlling GDB +* Extending GDB:: Extending GDB +* Interpreters:: Command Interpreters +* TUI:: GDB Text User Interface +* Emacs:: Using GDB under GNU Emacs +* GDB/MI:: GDB's Machine Interface. +* Annotations:: GDB's annotation interface. +* JIT Interface:: Using the JIT debugging interface. +* In-Process Agent:: In-Process Agent + +* GDB Bugs:: Reporting bugs in GDB + +* Command Line Editing:: Command Line Editing +* Using History Interactively:: Using History Interactively +* In Memoriam:: In Memoriam +* Formatting Documentation:: How to format and print GDB documentation +* Installing GDB:: Installing GDB +* Maintenance Commands:: Maintenance Commands +* Remote Protocol:: GDB Remote Serial Protocol +* Agent Expressions:: The GDB Agent Expression Mechanism +* Target Descriptions:: How targets can describe themselves to + GDB +* Operating System Information:: Getting additional information from + the operating system +* Trace File Format:: GDB trace file format +* Index Section Format:: .gdb_index section format +* Man Pages:: Manual pages +* Copying:: GNU General Public License says + how you can copy and share GDB +* GNU Free Documentation License:: The license for this documentation +* Concept Index:: Index of GDB concepts +* Command and Variable Index:: Index of GDB commands, variables, + functions, and Python data types + + +File: gdb.info, Node: Summary, Next: Sample Session, Up: Top + +Summary of GDB +************** + +The purpose of a debugger such as GDB is to allow you to see what is +going on "inside" another program while it executes--or what another +program was doing at the moment it crashed. + + GDB can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: + + * Start your program, specifying anything that might affect its + behavior. + + * Make your program stop on specified conditions. + + * Examine what has happened, when your program has stopped. + + * Change things in your program, so you can experiment with + correcting the effects of one bug and go on to learn about another. + + You can use GDB to debug programs written in C and C++. For more +information, see *note Supported Languages: Supported Languages. For +more information, see *note C and C++: C. + + Support for D is partial. For information on D, see *note D: D. + + Support for Modula-2 is partial. For information on Modula-2, see +*note Modula-2: Modula-2. + + Support for OpenCL C is partial. For information on OpenCL C, see +*note OpenCL C: OpenCL C. + + Debugging Pascal programs which use sets, subranges, file variables, +or nested functions does not currently work. GDB does not support +entering expressions, printing values, or similar features using Pascal +syntax. + + GDB can be used to debug programs written in Fortran, although it may +be necessary to refer to some variables with a trailing underscore. + + GDB can be used to debug programs written in Objective-C, using +either the Apple/NeXT or the GNU Objective-C runtime. + +* Menu: + +* Free Software:: Freely redistributable software +* Free Documentation:: Free Software Needs Free Documentation +* Contributors:: Contributors to GDB + + +File: gdb.info, Node: Free Software, Next: Free Documentation, Up: Summary + +Free Software +============= + +GDB is "free software", protected by the GNU General Public License +(GPL). The GPL gives you the freedom to copy or adapt a licensed +program--but every person getting a copy also gets with it the freedom +to modify that copy (which means that they must get access to the source +code), and the freedom to distribute further copies. Typical software +companies use copyrights to limit your freedoms; the Free Software +Foundation uses the GPL to preserve these freedoms. + + Fundamentally, the General Public License is a license which says +that you have these freedoms and that you cannot take these freedoms +away from anyone else. + + +File: gdb.info, Node: Free Documentation, Next: Contributors, Prev: Free Software, Up: Summary + +Free Software Needs Free Documentation +====================================== + +The biggest deficiency in the free software community today is not in +the software--it is the lack of good free documentation that we can +include with the free software. Many of our most important programs do +not come with free reference manuals and free introductory texts. +Documentation is an essential part of any software package; when an +important free software package does not come with a free manual and a +free tutorial, that is a major gap. We have many such gaps today. + + Consider Perl, for instance. The tutorial manuals that people +normally use are non-free. How did this come about? Because the +authors of those manuals published them with restrictive terms--no +copying, no modification, source files not available--which exclude them +from the free software world. + + That wasn't the first time this sort of thing happened, and it was +far from the last. Many times we have heard a GNU user eagerly describe +a manual that he is writing, his intended contribution to the community, +only to learn that he had ruined everything by signing a publication +contract to make it non-free. + + Free documentation, like free software, is a matter of freedom, not +price. The problem with the non-free manual is not that publishers +charge a price for printed copies--that in itself is fine. (The Free +Software Foundation sells printed copies of manuals, too.) The problem +is the restrictions on the use of the manual. Free manuals are +available in source code form, and give you permission to copy and +modify. Non-free manuals do not allow this. + + The criteria of freedom for a free manual are roughly the same as for +free software. Redistribution (including the normal kinds of commercial +redistribution) must be permitted, so that the manual can accompany +every copy of the program, both on-line and on paper. + + Permission for modification of the technical content is crucial too. +When people modify the software, adding or changing features, if they +are conscientious they will change the manual too--so they can provide +accurate and clear documentation for the modified program. A manual +that leaves you no choice but to write a new manual to document a +changed version of the program is not really available to our community. + + Some kinds of limits on the way modification is handled are +acceptable. For example, requirements to preserve the original author's +copyright notice, the distribution terms, or the list of authors, are +ok. It is also no problem to require modified versions to include +notice that they were modified. Even entire sections that may not be +deleted or changed are acceptable, as long as they deal with +nontechnical topics (like this one). These kinds of restrictions are +acceptable because they don't obstruct the community's normal use of the +manual. + + However, it must be possible to modify all the _technical_ content of +the manual, and then distribute the result in all the usual media, +through all the usual channels. Otherwise, the restrictions obstruct +the use of the manual, it is not free, and we need another manual to +replace it. + + Please spread the word about this issue. Our community continues to +lose manuals to proprietary publishing. If we spread the word that free +software needs free reference manuals and free tutorials, perhaps the +next person who wants to contribute by writing documentation will +realize, before it is too late, that only free manuals contribute to the +free software community. + + If you are writing documentation, please insist on publishing it +under the GNU Free Documentation License or another free documentation +license. Remember that this decision requires your approval--you don't +have to let the publisher decide. Some commercial publishers will use a +free license if you insist, but they will not propose the option; it is +up to you to raise the issue and say firmly that this is what you want. +If the publisher you are dealing with refuses, please try other +publishers. If you're not sure whether a proposed license is free, +write to . + + You can encourage commercial publishers to sell more free, copylefted +manuals and tutorials by buying them, and particularly by buying copies +from the publishers that paid for their writing or for major +improvements. Meanwhile, try to avoid buying non-free documentation at +all. Check the distribution terms of a manual before you buy it, and +insist that whoever seeks your business must respect your freedom. +Check the history of the book, and try to reward the publishers that +have paid or pay the authors to work on it. + + The Free Software Foundation maintains a list of free documentation +published by other publishers, at +. + + +File: gdb.info, Node: Contributors, Prev: Free Documentation, Up: Summary + +Contributors to GDB +=================== + +Richard Stallman was the original author of GDB, and of many other GNU +programs. Many others have contributed to its development. This +section attempts to credit major contributors. One of the virtues of +free software is that everyone is free to contribute to it; with regret, +we cannot actually acknowledge everyone here. The file 'ChangeLog' in +the GDB distribution approximates a blow-by-blow account. + + Changes much prior to version 2.0 are lost in the mists of time. + + _Plea:_ Additions to this section are particularly welcome. If you + or your friends (or enemies, to be evenhanded) have been unfairly + omitted from this list, we would like to add your names! + + So that they may not regard their many labors as thankless, we +particularly thank those who shepherded GDB through major releases: +Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim +Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs (release +4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); +Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); +John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon +(releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 3.1, and +3.0). + + Richard Stallman, assisted at various times by Peter TerMaat, Chris +Hanson, and Richard Mlynarik, handled releases through 2.8. + + Michael Tiemann is the author of most of the GNU C++ support in GDB, +with significant additional contributions from Per Bothner and Daniel +Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ was +by Peter TerMaat (who also did much general update work leading to +release 3.0). + + GDB uses the BFD subroutine library to examine multiple object-file +formats; BFD was a joint project of David V. Henkel-Wallace, Rich +Pixley, Steve Chamberlain, and John Gilmore. + + David Johnson wrote the original COFF support; Pace Willison did the +original support for encapsulated COFF. + + Brent Benson of Harris Computer Systems contributed DWARF 2 support. + + Adam de Boor and Bradley Davis contributed the ISI Optimum V support. +Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS +support. Jean-Daniel Fekete contributed Sun 386i support. Chris Hanson +improved the HP9000 support. Noboyuki Hikichi and Tomoyuki Hasei +contributed Sony/News OS 3 support. David Johnson contributed Encore +Umax support. Jyrki Kuoppala contributed Altos 3068 support. Jeff Law +contributed HP PA and SOM support. Keith Packard contributed NS32K +support. Doug Rabson contributed Acorn Risc Machine support. Bob Rusk +contributed Harris Nighthawk CX-UX support. Chris Smith contributed +Convex support (and Fortran debugging). Jonathan Stone contributed +Pyramid support. Michael Tiemann contributed SPARC support. Tim Tucker +contributed support for the Gould NP1 and Gould Powernode. Pace +Willison contributed Intel 386 support. Jay Vosburgh contributed +Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. + + Andreas Schwab contributed M68K GNU/Linux support. + + Rich Schaefer and Peter Schauer helped with support of SunOS shared +libraries. + + Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about +several machine instruction sets. + + Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped +develop remote debugging. Intel Corporation, Wind River Systems, AMD, +and ARM contributed remote debugging modules for the i960, VxWorks, A29K +UDI, and RDI targets, respectively. + + Brian Fox is the author of the readline libraries providing +command-line editing and command history. + + Andrew Beers of SUNY Buffalo wrote the language-switching code, the +Modula-2 support, and contributed the Languages chapter of this manual. + + Fred Fish wrote most of the support for Unix System Vr4. He also +enhanced the command-completion support to cover C++ overloaded symbols. + + Hitachi America (now Renesas America), Ltd. sponsored the support +for H8/300, H8/500, and Super-H processors. + + NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx +processors. + + Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and +M32R/D processors. + + Toshiba sponsored the support for the TX39 Mips processor. + + Matsushita sponsored the support for the MN10200 and MN10300 +processors. + + Fujitsu sponsored the support for SPARClite and FR30 processors. + + Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware +watchpoints. + + Michael Snyder added support for tracepoints. + + Stu Grossman wrote gdbserver. + + Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly +innumerable bug fixes and cleanups throughout GDB. + + The following people at the Hewlett-Packard Company contributed +support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 +(narrow mode), HP's implementation of kernel threads, HP's aC++ +compiler, and the Text User Interface (nee Terminal User Interface): Ben +Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, Satish +Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase provided +HP-specific information in this manual. + + DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert +Hoehne made significant contributions to the DJGPP port. + + Cygnus Solutions has sponsored GDB maintenance and much of its +development since 1991. Cygnus engineers who have worked on GDB +fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin +Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim +Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, +Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek +Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In +addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, +JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug +Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff +Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, +Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin +Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela +Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David +Zuhn have made contributions both large and small. + + Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for +Cygnus Solutions, implemented the original GDB/MI interface. + + Jim Blandy added support for preprocessor macros, while working for +Red Hat. + + Andrew Cagney designed GDB's architecture vector. Many people +including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, +Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, +Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna +Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration +of old architectures to this new framework. + + Andrew Cagney completely re-designed and re-implemented GDB's +unwinder framework, this consisting of a fresh new design featuring +frame IDs, independent frame sniffers, and the sentinel frame. Mark +Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind +unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad +unwinders. The architecture-specific changes, each involving a complete +rewrite of the architecture's frame code, were carried out by Jim +Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane Carrez, +Randolph Chung, Orjan Friberg, Richard Henderson, Daniel Jacobowitz, +Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei Sakamoto, Yoshinori +Sato, Michael Snyder, Corinna Vinschen, and Ulrich Weigand. + + Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from +Tensilica, Inc. contributed support for Xtensa processors. Others who +have worked on the Xtensa port of GDB in the past include Steve Tjiang, +John Newlin, and Scott Foehner. + + Michael Eager and staff of Xilinx, Inc., contributed support for the +Xilinx MicroBlaze architecture. + + +File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top + +1 A Sample GDB Session +********************** + +You can use this manual at your leisure to read all about GDB. However, +a handful of commands are enough to get started using the debugger. +This chapter illustrates those commands. + + One of the preliminary versions of GNU 'm4' (a generic macro +processor) exhibits the following bug: sometimes, when we change its +quote strings from the default, the commands used to capture one macro +definition within another stop working. In the following short 'm4' +session, we define a macro 'foo' which expands to '0000'; we then use +the 'm4' built-in 'defn' to define 'bar' as the same thing. However, +when we change the open quote string to '' and the close quote +string to '', the same procedure fails to define a new synonym +'baz': + + $ cd gnu/m4 + $ ./m4 + define(foo,0000) + + foo + 0000 + define(bar,defn('foo')) + + bar + 0000 + changequote(,) + + define(baz,defn(foo)) + baz + Ctrl-d + m4: End of input: 0: fatal error: EOF in string + +Let us use GDB to try to see what is going on. + + $ gdb m4 + GDB is free software and you are welcome to distribute copies + of it under certain conditions; type "show copying" to see + the conditions. + There is absolutely no warranty for GDB; type "show warranty" + for details. + + GDB 7.7.1, Copyright 1999 Free Software Foundation, Inc... + (gdb) + +GDB reads only enough symbol data to know where to find the rest when +needed; as a result, the first prompt comes up very quickly. We now +tell GDB to use a narrower display width than usual, so that examples +fit in this manual. + + (gdb) set width 70 + +We need to see how the 'm4' built-in 'changequote' works. Having looked +at the source, we know the relevant subroutine is 'm4_changequote', so +we set a breakpoint there with the GDB 'break' command. + + (gdb) break m4_changequote + Breakpoint 1 at 0x62f4: file builtin.c, line 879. + +Using the 'run' command, we start 'm4' running under GDB control; as +long as control does not reach the 'm4_changequote' subroutine, the +program runs as usual: + + (gdb) run + Starting program: /work/Editorial/gdb/gnu/m4/m4 + define(foo,0000) + + foo + 0000 + +To trigger the breakpoint, we call 'changequote'. GDB suspends +execution of 'm4', displaying information about the context where it +stops. + + changequote(,) + + Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) + at builtin.c:879 + 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) + +Now we use the command 'n' ('next') to advance execution to the next +line of the current function. + + (gdb) n + 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ + : nil, + +'set_quotes' looks like a promising subroutine. We can go into it by +using the command 's' ('step') instead of 'next'. 'step' goes to the +next line to be executed in _any_ subroutine, so it steps into +'set_quotes'. + + (gdb) s + set_quotes (lq=0x34c78 "", rq=0x34c88 "") + at input.c:530 + 530 if (lquote != def_lquote) + +The display that shows the subroutine where 'm4' is now suspended (and +its arguments) is called a stack frame display. It shows a summary of +the stack. We can use the 'backtrace' command (which can also be +spelled 'bt'), to see where we are in the stack as a whole: the +'backtrace' command displays a stack frame for each active subroutine. + + (gdb) bt + #0 set_quotes (lq=0x34c78 "", rq=0x34c88 "") + at input.c:530 + #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) + at builtin.c:882 + #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 + #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) + at macro.c:71 + #4 0x79dc in expand_input () at macro.c:40 + #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 + +We step through a few more lines to see what happens. The first two +times, we can use 's'; the next two times we use 'n' to avoid falling +into the 'xstrdup' subroutine. + + (gdb) s + 0x3b5c 532 if (rquote != def_rquote) + (gdb) s + 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ + def_lquote : xstrdup(lq); + (gdb) n + 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ + : xstrdup(rq); + (gdb) n + 538 len_lquote = strlen(rquote); + +The last line displayed looks a little odd; we can examine the variables +'lquote' and 'rquote' to see if they are in fact the new left and right +quotes we specified. We use the command 'p' ('print') to see their +values. + + (gdb) p lquote + $1 = 0x35d40 "" + (gdb) p rquote + $2 = 0x35d50 "" + +'lquote' and 'rquote' are indeed the new left and right quotes. To look +at some context, we can display ten lines of source surrounding the +current line with the 'l' ('list') command. + + (gdb) l + 533 xfree(rquote); + 534 + 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ + : xstrdup (lq); + 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ + : xstrdup (rq); + 537 + 538 len_lquote = strlen(rquote); + 539 len_rquote = strlen(lquote); + 540 } + 541 + 542 void + +Let us step past the two lines that set 'len_lquote' and 'len_rquote', +and then examine the values of those variables. + + (gdb) n + 539 len_rquote = strlen(lquote); + (gdb) n + 540 } + (gdb) p len_lquote + $3 = 9 + (gdb) p len_rquote + $4 = 7 + +That certainly looks wrong, assuming 'len_lquote' and 'len_rquote' are +meant to be the lengths of 'lquote' and 'rquote' respectively. We can +set them to better values using the 'p' command, since it can print the +value of any expression--and that expression can include subroutine +calls and assignments. + + (gdb) p len_lquote=strlen(lquote) + $5 = 7 + (gdb) p len_rquote=strlen(rquote) + $6 = 9 + +Is that enough to fix the problem of using the new quotes with the 'm4' +built-in 'defn'? We can allow 'm4' to continue executing with the 'c' +('continue') command, and then try the example that caused trouble +initially: + + (gdb) c + Continuing. + + define(baz,defn(foo)) + + baz + 0000 + +Success! The new quotes now work just as well as the default ones. The +problem seems to have been just the two typos defining the wrong +lengths. We allow 'm4' exit by giving it an EOF as input: + + Ctrl-d + Program exited normally. + +The message 'Program exited normally.' is from GDB; it indicates 'm4' +has finished executing. We can end our GDB session with the GDB 'quit' +command. + + (gdb) quit + + +File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top + +2 Getting In and Out of GDB +*************************** + +This chapter discusses how to start GDB, and how to get out of it. The +essentials are: + * type 'gdb' to start GDB. + * type 'quit' or 'Ctrl-d' to exit. + +* Menu: + +* Invoking GDB:: How to start GDB +* Quitting GDB:: How to quit GDB +* Shell Commands:: How to use shell commands inside GDB +* Logging Output:: How to log GDB's output to a file + + +File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation + +2.1 Invoking GDB +================ + +Invoke GDB by running the program 'gdb'. Once started, GDB reads +commands from the terminal until you tell it to exit. + + You can also run 'gdb' with a variety of arguments and options, to +specify more of your debugging environment at the outset. + + The command-line options described here are designed to cover a +variety of situations; in some environments, some of these options may +effectively be unavailable. + + The most usual way to start GDB is with one argument, specifying an +executable program: + + gdb PROGRAM + +You can also start with both an executable program and a core file +specified: + + gdb PROGRAM CORE + + You can, instead, specify a process ID as a second argument, if you +want to debug a running process: + + gdb PROGRAM 1234 + +would attach GDB to process '1234' (unless you also have a file named +'1234'; GDB does check for a core file first). + + Taking advantage of the second command-line argument requires a +fairly complete operating system; when you use GDB as a remote debugger +attached to a bare board, there may not be any notion of "process", and +there is often no way to get a core dump. GDB will warn you if it is +unable to attach or to read core dumps. + + You can optionally have 'gdb' pass any arguments after the executable +file to the inferior using '--args'. This option stops option +processing. + gdb --args gcc -O2 -c foo.c + This will cause 'gdb' to debug 'gcc', and to set 'gcc''s command-line +arguments (*note Arguments::) to '-O2 -c foo.c'. + + You can run 'gdb' without printing the front material, which +describes GDB's non-warranty, by specifying '-silent': + + gdb -silent + +You can further control how GDB starts up by using command-line options. +GDB itself can remind you of the options available. + +Type + + gdb -help + +to display all available options and briefly describe their use ('gdb +-h' is a shorter equivalent). + + All options and command line arguments you give are processed in +sequential order. The order makes a difference when the '-x' option is +used. + +* Menu: + +* File Options:: Choosing files +* Mode Options:: Choosing modes +* Startup:: What GDB does during startup + + +File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB + +2.1.1 Choosing Files +-------------------- + +When GDB starts, it reads any arguments other than options as specifying +an executable file and core file (or process ID). This is the same as if +the arguments were specified by the '-se' and '-c' (or '-p') options +respectively. (GDB reads the first argument that does not have an +associated option flag as equivalent to the '-se' option followed by +that argument; and the second argument that does not have an associated +option flag, if any, as equivalent to the '-c'/'-p' option followed by +that argument.) If the second argument begins with a decimal digit, GDB +will first attempt to attach to it as a process, and if that fails, +attempt to open it as a corefile. If you have a corefile whose name +begins with a digit, you can prevent GDB from treating it as a pid by +prefixing it with './', e.g. './12345'. + + If GDB has not been configured to included core file support, such as +for most embedded targets, then it will complain about a second argument +and ignore it. + + Many options have both long and short forms; both are shown in the +following list. GDB also recognizes the long forms if you truncate +them, so long as enough of the option is present to be unambiguous. (If +you prefer, you can flag option arguments with '--' rather than '-', +though we illustrate the more usual convention.) + +'-symbols FILE' +'-s FILE' + Read symbol table from file FILE. + +'-exec FILE' +'-e FILE' + Use file FILE as the executable file to execute when appropriate, + and for examining pure data in conjunction with a core dump. + +'-se FILE' + Read symbol table from file FILE and use it as the executable file. + +'-core FILE' +'-c FILE' + Use file FILE as a core dump to examine. + +'-pid NUMBER' +'-p NUMBER' + Connect to process ID NUMBER, as with the 'attach' command. + +'-command FILE' +'-x FILE' + Execute commands from file FILE. The contents of this file is + evaluated exactly as the 'source' command would. *Note Command + files: Command Files. + +'-eval-command COMMAND' +'-ex COMMAND' + Execute a single GDB command. + + This option may be used multiple times to call multiple commands. + It may also be interleaved with '-command' as required. + + gdb -ex 'target sim' -ex 'load' \ + -x setbreakpoints -ex 'run' a.out + +'-init-command FILE' +'-ix FILE' + Execute commands from file FILE before loading the inferior (but + after loading gdbinit files). *Note Startup::. + +'-init-eval-command COMMAND' +'-iex COMMAND' + Execute a single GDB command before loading the inferior (but after + loading gdbinit files). *Note Startup::. + +'-directory DIRECTORY' +'-d DIRECTORY' + Add DIRECTORY to the path to search for source and script files. + +'-r' +'-readnow' + Read each symbol file's entire symbol table immediately, rather + than the default, which is to read it incrementally as it is + needed. This makes startup slower, but makes future operations + faster. + + +File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB + +2.1.2 Choosing Modes +-------------------- + +You can run GDB in various alternative modes--for example, in batch mode +or quiet mode. + +'-nx' +'-n' + Do not execute commands found in any initialization file. There + are three init files, loaded in the following order: + + 'system.gdbinit' + This is the system-wide init file. Its location is specified + with the '--with-system-gdbinit' configure option (*note + System-wide configuration::). It is loaded first when GDB + starts, before command line options have been processed. + '~/.gdbinit' + This is the init file in your home directory. It is loaded + next, after 'system.gdbinit', and before command options have + been processed. + './.gdbinit' + This is the init file in the current directory. It is loaded + last, after command line options other than '-x' and '-ex' + have been processed. Command line options '-x' and '-ex' are + processed last, after './.gdbinit' has been loaded. + + For further documentation on startup processing, *Note Startup::. + For documentation on how to write command files, *Note Command + Files: Command Files. + +'-nh' + Do not execute commands found in '~/.gdbinit', the init file in + your home directory. *Note Startup::. + +'-quiet' +'-silent' +'-q' + "Quiet". Do not print the introductory and copyright messages. + These messages are also suppressed in batch mode. + +'-batch' + Run in batch mode. Exit with status '0' after processing all the + command files specified with '-x' (and all commands from + initialization files, if not inhibited with '-n'). Exit with + nonzero status if an error occurs in executing the GDB commands in + the command files. Batch mode also disables pagination, sets + unlimited terminal width and height *note Screen Size::, and acts + as if 'set confirm off' were in effect (*note Messages/Warnings::). + + Batch mode may be useful for running GDB as a filter, for example + to download and run a program on another computer; in order to make + this more useful, the message + + Program exited normally. + + (which is ordinarily issued whenever a program running under GDB + control terminates) is not issued when running in batch mode. + +'-batch-silent' + Run in batch mode exactly like '-batch', but totally silently. All + GDB output to 'stdout' is prevented ('stderr' is unaffected). This + is much quieter than '-silent' and would be useless for an + interactive session. + + This is particularly useful when using targets that give 'Loading + section' messages, for example. + + Note that targets that give their output via GDB, as opposed to + writing directly to 'stdout', will also be made silent. + +'-return-child-result' + The return code from GDB will be the return code from the child + process (the process being debugged), with the following + exceptions: + + * GDB exits abnormally. E.g., due to an incorrect argument or + an internal error. In this case the exit code is the same as + it would have been without '-return-child-result'. + * The user quits with an explicit value. E.g., 'quit 1'. + * The child process never runs, or is not allowed to terminate, + in which case the exit code will be -1. + + This option is useful in conjunction with '-batch' or + '-batch-silent', when GDB is being used as a remote program loader + or simulator interface. + +'-nowindows' +'-nw' + "No windows". If GDB comes with a graphical user interface (GUI) + built in, then this option tells GDB to only use the command-line + interface. If no GUI is available, this option has no effect. + +'-windows' +'-w' + If GDB includes a GUI, then this option requires it to be used if + possible. + +'-cd DIRECTORY' + Run GDB using DIRECTORY as its working directory, instead of the + current directory. + +'-data-directory DIRECTORY' + Run GDB using DIRECTORY as its data directory. The data directory + is where GDB searches for its auxiliary files. *Note Data Files::. + +'-fullname' +'-f' + GNU Emacs sets this option when it runs GDB as a subprocess. It + tells GDB to output the full file name and line number in a + standard, recognizable fashion each time a stack frame is displayed + (which includes each time your program stops). This recognizable + format looks like two '\032' characters, followed by the file name, + line number and character position separated by colons, and a + newline. The Emacs-to-GDB interface program uses the two '\032' + characters as a signal to display the source code for the frame. + +'-annotate LEVEL' + This option sets the "annotation level" inside GDB. Its effect is + identical to using 'set annotate LEVEL' (*note Annotations::). The + annotation LEVEL controls how much information GDB prints together + with its prompt, values of expressions, source lines, and other + types of output. Level 0 is the normal, level 1 is for use when + GDB is run as a subprocess of GNU Emacs, level 3 is the maximum + annotation suitable for programs that control GDB, and level 2 has + been deprecated. + + The annotation mechanism has largely been superseded by GDB/MI + (*note GDB/MI::). + +'--args' + Change interpretation of command line so that arguments following + the executable file are passed as command line arguments to the + inferior. This option stops option processing. + +'-baud BPS' +'-b BPS' + Set the line speed (baud rate or bits per second) of any serial + interface used by GDB for remote debugging. + +'-l TIMEOUT' + Set the timeout (in seconds) of any communication used by GDB for + remote debugging. + +'-tty DEVICE' +'-t DEVICE' + Run using DEVICE for your program's standard input and output. + +'-tui' + Activate the "Text User Interface" when starting. The Text User + Interface manages several text windows on the terminal, showing + source, assembly, registers and GDB command outputs (*note GDB Text + User Interface: TUI.). Do not use this option if you run GDB from + Emacs (*note Using GDB under GNU Emacs: Emacs.). + +'-interpreter INTERP' + Use the interpreter INTERP for interface with the controlling + program or device. This option is meant to be set by programs + which communicate with GDB using it as a back end. *Note Command + Interpreters: Interpreters. + + '--interpreter=mi' (or '--interpreter=mi2') causes GDB to use the + "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included + since GDB version 6.0. The previous GDB/MI interface, included in + GDB version 5.3 and selected with '--interpreter=mi1', is + deprecated. Earlier GDB/MI interfaces are no longer supported. + +'-write' + Open the executable and core files for both reading and writing. + This is equivalent to the 'set write on' command inside GDB (*note + Patching::). + +'-statistics' + This option causes GDB to print statistics about time and memory + usage after it completes each command and returns to the prompt. + +'-version' + This option causes GDB to print its version number and no-warranty + blurb, and exit. + +'-configuration' + This option causes GDB to print details about its build-time + configuration parameters, and then exit. These details can be + important when reporting GDB bugs (*note GDB Bugs::). + + +File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB + +2.1.3 What GDB Does During Startup +---------------------------------- + +Here's the description of what GDB does during session startup: + + 1. Sets up the command interpreter as specified by the command line + (*note interpreter: Mode Options.). + + 2. Reads the system-wide "init file" (if '--with-system-gdbinit' was + used when building GDB; *note System-wide configuration and + settings: System-wide configuration.) and executes all the commands + in that file. + + 3. Reads the init file (if any) in your home directory(1) and executes + all the commands in that file. + + 4. Executes commands and command files specified by the '-iex' and + '-ix' options in their specified order. Usually you should use the + '-ex' and '-x' options instead, but this way you can apply settings + before GDB init files get executed and before inferior gets loaded. + + 5. Processes command line options and operands. + + 6. Reads and executes the commands from init file (if any) in the + current working directory as long as 'set auto-load local-gdbinit' + is set to 'on' (*note Init File in the Current Directory::). This + is only done if the current directory is different from your home + directory. Thus, you can have more than one init file, one generic + in your home directory, and another, specific to the program you + are debugging, in the directory where you invoke GDB. + + 7. If the command line specified a program to debug, or a process to + attach to, or a core file, GDB loads any auto-loaded scripts + provided for the program or for its loaded shared libraries. *Note + Auto-loading::. + + If you wish to disable the auto-loading during startup, you must do + something like the following: + + $ gdb -iex "set auto-load python-scripts off" myprogram + + Option '-ex' does not work because the auto-loading is then turned + off too late. + + 8. Executes commands and command files specified by the '-ex' and '-x' + options in their specified order. *Note Command Files::, for more + details about GDB command files. + + 9. Reads the command history recorded in the "history file". *Note + Command History::, for more details about the command history and + the files where GDB records it. + + Init files use the same syntax as "command files" (*note Command +Files::) and are processed by GDB in the same way. The init file in +your home directory can set options (such as 'set complaints') that +affect subsequent processing of command line options and operands. Init +files are not executed if you use the '-nx' option (*note Choosing +Modes: Mode Options.). + + To display the list of init files loaded by gdb at startup, you can +use 'gdb --help'. + + The GDB init files are normally called '.gdbinit'. The DJGPP port of +GDB uses the name 'gdb.ini', due to the limitations of file names +imposed by DOS filesystems. The Windows port of GDB uses the standard +name, but if it finds a 'gdb.ini' file in your home directory, it warns +you about that and suggests to rename the file to the standard name. + + ---------- Footnotes ---------- + + (1) On DOS/Windows systems, the home directory is the one pointed to +by the 'HOME' environment variable. + + +File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation + +2.2 Quitting GDB +================ + +'quit [EXPRESSION]' +'q' + To exit GDB, use the 'quit' command (abbreviated 'q'), or type an + end-of-file character (usually 'Ctrl-d'). If you do not supply + EXPRESSION, GDB will terminate normally; otherwise it will + terminate using the result of EXPRESSION as the error code. + + An interrupt (often 'Ctrl-c') does not exit from GDB, but rather +terminates the action of any GDB command that is in progress and returns +to GDB command level. It is safe to type the interrupt character at any +time because GDB does not allow it to take effect until a time when it +is safe. + + If you have been using GDB to control an attached process or device, +you can release it with the 'detach' command (*note Debugging an +Already-running Process: Attach.). + + +File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation + +2.3 Shell Commands +================== + +If you need to execute occasional shell commands during your debugging +session, there is no need to leave or suspend GDB; you can just use the +'shell' command. + +'shell COMMAND-STRING' +'!COMMAND-STRING' + Invoke a standard shell to execute COMMAND-STRING. Note that no + space is needed between '!' and COMMAND-STRING. If it exists, the + environment variable 'SHELL' determines which shell to run. + Otherwise GDB uses the default shell ('/bin/sh' on Unix systems, + 'COMMAND.COM' on MS-DOS, etc.). + + The utility 'make' is often needed in development environments. You +do not have to use the 'shell' command for this purpose in GDB: + +'make MAKE-ARGS' + Execute the 'make' program with the specified arguments. This is + equivalent to 'shell make MAKE-ARGS'. + + +File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation + +2.4 Logging Output +================== + +You may want to save the output of GDB commands to a file. There are +several commands to control GDB's logging. + +'set logging on' + Enable logging. +'set logging off' + Disable logging. +'set logging file FILE' + Change the name of the current logfile. The default logfile is + 'gdb.txt'. +'set logging overwrite [on|off]' + By default, GDB will append to the logfile. Set 'overwrite' if you + want 'set logging on' to overwrite the logfile instead. +'set logging redirect [on|off]' + By default, GDB output will go to both the terminal and the + logfile. Set 'redirect' if you want output to go only to the log + file. +'show logging' + Show the current values of the logging settings. + + +File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top + +3 GDB Commands +************** + +You can abbreviate a GDB command to the first few letters of the command +name, if that abbreviation is unambiguous; and you can repeat certain +GDB commands by typing just . You can also use the key to +get GDB to fill out the rest of a word in a command (or to show you the +alternatives available, if there is more than one possibility). + +* Menu: + +* Command Syntax:: How to give commands to GDB +* Completion:: Command completion +* Help:: How to ask GDB for help + + +File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands + +3.1 Command Syntax +================== + +A GDB command is a single line of input. There is no limit on how long +it can be. It starts with a command name, which is followed by +arguments whose meaning depends on the command name. For example, the +command 'step' accepts an argument which is the number of times to step, +as in 'step 5'. You can also use the 'step' command with no arguments. +Some commands do not allow any arguments. + + GDB command names may always be truncated if that abbreviation is +unambiguous. Other possible command abbreviations are listed in the +documentation for individual commands. In some cases, even ambiguous +abbreviations are allowed; for example, 's' is specially defined as +equivalent to 'step' even though there are other commands whose names +start with 's'. You can test abbreviations by using them as arguments +to the 'help' command. + + A blank line as input to GDB (typing just ) means to repeat the +previous command. Certain commands (for example, 'run') will not repeat +this way; these are commands whose unintentional repetition might cause +trouble and which you are unlikely to want to repeat. User-defined +commands can disable this feature; see *note dont-repeat: Define. + + The 'list' and 'x' commands, when you repeat them with , +construct new arguments rather than repeating exactly as typed. This +permits easy scanning of source or memory. + + GDB can also use in another way: to partition lengthy output, +in a way similar to the common utility 'more' (*note Screen Size: Screen +Size.). Since it is easy to press one too many in this situation, +GDB disables command repetition after any command that generates this +sort of display. + + Any text from a '#' to the end of the line is a comment; it does +nothing. This is useful mainly in command files (*note Command Files: +Command Files.). + + The 'Ctrl-o' binding is useful for repeating a complex sequence of +commands. This command accepts the current line, like , and then +fetches the next line relative to the current line from the history for +editing. + + +File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands + +3.2 Command Completion +====================== + +GDB can fill in the rest of a word in a command for you, if there is +only one possibility; it can also show you what the valid possibilities +are for the next word in a command, at any time. This works for GDB +commands, GDB subcommands, and the names of symbols in your program. + + Press the key whenever you want GDB to fill out the rest of a +word. If there is only one possibility, GDB fills in the word, and +waits for you to finish the command (or press to enter it). For +example, if you type + + (gdb) info bre + +GDB fills in the rest of the word 'breakpoints', since that is the only +'info' subcommand beginning with 'bre': + + (gdb) info breakpoints + +You can either press at this point, to run the 'info breakpoints' +command, or backspace and enter something else, if 'breakpoints' does +not look like the command you expected. (If you were sure you wanted +'info breakpoints' in the first place, you might as well just type +immediately after 'info bre', to exploit command abbreviations rather +than command completion). + + If there is more than one possibility for the next word when you +press , GDB sounds a bell. You can either supply more characters +and try again, or just press a second time; GDB displays all the +possible completions for that word. For example, you might want to set +a breakpoint on a subroutine whose name begins with 'make_', but when +you type 'b make_' GDB just sounds the bell. Typing again +displays all the function names in your program that begin with those +characters, for example: + + (gdb) b make_ +GDB sounds bell; press again, to see: + make_a_section_from_file make_environ + make_abs_section make_function_type + make_blockvector make_pointer_type + make_cleanup make_reference_type + make_command make_symbol_completion_list + (gdb) b make_ + +After displaying the available possibilities, GDB copies your partial +input ('b make_' in the example) so you can finish the command. + + If you just want to see the list of alternatives in the first place, +you can press 'M-?' rather than pressing twice. 'M-?' means +' ?'. You can type this either by holding down a key designated +as the shift on your keyboard (if there is one) while typing '?', +or as followed by '?'. + + Sometimes the string you need, while logically a "word", may contain +parentheses or other characters that GDB normally excludes from its +notion of a word. To permit word completion to work in this situation, +you may enclose words in ''' (single quote marks) in GDB commands. + + The most likely situation where you might need this is in typing the +name of a C++ function. This is because C++ allows function overloading +(multiple definitions of the same function, distinguished by argument +type). For example, when you want to set a breakpoint you may need to +distinguish whether you mean the version of 'name' that takes an 'int' +parameter, 'name(int)', or the version that takes a 'float' parameter, +'name(float)'. To use the word-completion facilities in this situation, +type a single quote ''' at the beginning of the function name. This +alerts GDB that it may need to consider more information than usual when +you press or 'M-?' to request word completion: + + (gdb) b 'bubble( M-? + bubble(double,double) bubble(int,int) + (gdb) b 'bubble( + + In some cases, GDB can tell that completing a name requires using +quotes. When this happens, GDB inserts the quote for you (while +completing as much as it can) if you do not type the quote in the first +place: + + (gdb) b bub +GDB alters your input line to the following, and rings a bell: + (gdb) b 'bubble( + +In general, GDB can tell that a quote is needed (and inserts it) if you +have not yet started typing the argument list when you ask for +completion on an overloaded symbol. + + For more information about overloaded functions, see *note C++ +Expressions: C Plus Plus Expressions. You can use the command 'set +overload-resolution off' to disable overload resolution; see *note GDB +Features for C++: Debugging C Plus Plus. + + When completing in an expression which looks up a field in a +structure, GDB also tries(1) to limit completions to the field names +available in the type of the left-hand-side: + + (gdb) p gdb_stdout.M-? + magic to_fputs to_rewind + to_data to_isatty to_write + to_delete to_put to_write_async_safe + to_flush to_read + +This is because the 'gdb_stdout' is a variable of the type 'struct +ui_file' that is defined in GDB sources as follows: + + struct ui_file + { + int *magic; + ui_file_flush_ftype *to_flush; + ui_file_write_ftype *to_write; + ui_file_write_async_safe_ftype *to_write_async_safe; + ui_file_fputs_ftype *to_fputs; + ui_file_read_ftype *to_read; + ui_file_delete_ftype *to_delete; + ui_file_isatty_ftype *to_isatty; + ui_file_rewind_ftype *to_rewind; + ui_file_put_ftype *to_put; + void *to_data; + } + + ---------- Footnotes ---------- + + (1) The completer can be confused by certain kinds of invalid +expressions. Also, it only examines the static type of the expression, +not the dynamic type. + + +File: gdb.info, Node: Help, Prev: Completion, Up: Commands + +3.3 Getting Help +================ + +You can always ask GDB itself for information on its commands, using the +command 'help'. + +'help' +'h' + You can use 'help' (abbreviated 'h') with no arguments to display a + short list of named classes of commands: + + (gdb) help + List of classes of commands: + + aliases -- Aliases of other commands + breakpoints -- Making program stop at certain points + data -- Examining data + files -- Specifying and examining files + internals -- Maintenance commands + obscure -- Obscure features + running -- Running the program + stack -- Examining the stack + status -- Status inquiries + support -- Support facilities + tracepoints -- Tracing of program execution without + stopping the program + user-defined -- User-defined commands + + Type "help" followed by a class name for a list of + commands in that class. + Type "help" followed by command name for full + documentation. + Command name abbreviations are allowed if unambiguous. + (gdb) + +'help CLASS' + Using one of the general help classes as an argument, you can get a + list of the individual commands in that class. For example, here + is the help display for the class 'status': + + (gdb) help status + Status inquiries. + + List of commands: + + info -- Generic command for showing things + about the program being debugged + show -- Generic command for showing things + about the debugger + + Type "help" followed by command name for full + documentation. + Command name abbreviations are allowed if unambiguous. + (gdb) + +'help COMMAND' + With a command name as 'help' argument, GDB displays a short + paragraph on how to use that command. + +'apropos ARGS' + The 'apropos' command searches through all of the GDB commands, and + their documentation, for the regular expression specified in ARGS. + It prints out all matches found. For example: + + apropos alias + + results in: + + alias -- Define a new command that is an alias of an existing command + aliases -- Aliases of other commands + d -- Delete some breakpoints or auto-display expressions + del -- Delete some breakpoints or auto-display expressions + delete -- Delete some breakpoints or auto-display expressions + +'complete ARGS' + The 'complete ARGS' command lists all the possible completions for + the beginning of a command. Use ARGS to specify the beginning of + the command you want completed. For example: + + complete i + + results in: + + if + ignore + info + inspect + + This is intended for use by GNU Emacs. + + In addition to 'help', you can use the GDB commands 'info' and 'show' +to inquire about the state of your program, or the state of GDB itself. +Each command supports many topics of inquiry; this manual introduces +each of them in the appropriate context. The listings under 'info' and +under 'show' in the Command, Variable, and Function Index point to all +the sub-commands. *Note Command and Variable Index::. + +'info' + This command (abbreviated 'i') is for describing the state of your + program. For example, you can show the arguments passed to a + function with 'info args', list the registers currently in use with + 'info registers', or list the breakpoints you have set with 'info + breakpoints'. You can get a complete list of the 'info' + sub-commands with 'help info'. + +'set' + You can assign the result of an expression to an environment + variable with 'set'. For example, you can set the GDB prompt to a + $-sign with 'set prompt $'. + +'show' + In contrast to 'info', 'show' is for describing the state of GDB + itself. You can change most of the things you can 'show', by using + the related command 'set'; for example, you can control what number + system is used for displays with 'set radix', or simply inquire + which is currently in use with 'show radix'. + + To display all the settable parameters and their current values, + you can use 'show' with no arguments; you may also use 'info set'. + Both commands produce the same display. + + Here are several miscellaneous 'show' subcommands, all of which are +exceptional in lacking corresponding 'set' commands: + +'show version' + Show what version of GDB is running. You should include this + information in GDB bug-reports. If multiple versions of GDB are in + use at your site, you may need to determine which version of GDB + you are running; as GDB evolves, new commands are introduced, and + old ones may wither away. Also, many system vendors ship variant + versions of GDB, and there are variant versions of GDB in GNU/Linux + distributions as well. The version number is the same as the one + announced when you start GDB. + +'show copying' +'info copying' + Display information about permission for copying GDB. + +'show warranty' +'info warranty' + Display the GNU "NO WARRANTY" statement, or a warranty, if your + version of GDB comes with one. + +'show configuration' + Display detailed information about the way GDB was configured when + it was built. This displays the optional arguments passed to the + 'configure' script and also configuration parameters detected + automatically by 'configure'. When reporting a GDB bug (*note GDB + Bugs::), it is important to include this information in your + report. + + +File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top + +4 Running Programs Under GDB +**************************** + +When you run a program under GDB, you must first generate debugging +information when you compile it. + + You may start GDB with its arguments, if any, in an environment of +your choice. If you are doing native debugging, you may redirect your +program's input and output, debug an already running process, or kill a +child process. + +* Menu: + +* Compilation:: Compiling for debugging +* Starting:: Starting your program +* Arguments:: Your program's arguments +* Environment:: Your program's environment + +* Working Directory:: Your program's working directory +* Input/Output:: Your program's input and output +* Attach:: Debugging an already-running process +* Kill Process:: Killing the child process + +* Inferiors and Programs:: Debugging multiple inferiors and programs +* Threads:: Debugging programs with multiple threads +* Forks:: Debugging forks +* Checkpoint/Restart:: Setting a _bookmark_ to return to later + + +File: gdb.info, Node: Compilation, Next: Starting, Up: Running + +4.1 Compiling for Debugging +=========================== + +In order to debug a program effectively, you need to generate debugging +information when you compile it. This debugging information is stored +in the object file; it describes the data type of each variable or +function and the correspondence between source line numbers and +addresses in the executable code. + + To request debugging information, specify the '-g' option when you +run the compiler. + + Programs that are to be shipped to your customers are compiled with +optimizations, using the '-O' compiler option. However, some compilers +are unable to handle the '-g' and '-O' options together. Using those +compilers, you cannot generate optimized executables containing +debugging information. + + GCC, the GNU C/C++ compiler, supports '-g' with or without '-O', +making it possible to debug optimized code. We recommend that you +_always_ use '-g' whenever you compile a program. You may think your +program is correct, but there is no sense in pushing your luck. For +more information, see *note Optimized Code::. + + Older versions of the GNU C compiler permitted a variant option '-gg' +for debugging information. GDB no longer supports this format; if your +GNU C compiler has this option, do not use it. + + GDB knows about preprocessor macros and can show you their expansion +(*note Macros::). Most compilers do not include information about +preprocessor macros in the debugging information if you specify the '-g' +flag alone. Version 3.1 and later of GCC, the GNU C compiler, provides +macro information if you are using the DWARF debugging format, and +specify the option '-g3'. + + *Note Options for Debugging Your Program or GCC: (gcc.info)Debugging +Options, for more information on GCC options affecting debug +information. + + You will have the best debugging experience if you use the latest +version of the DWARF debugging format that your compiler supports. +DWARF is currently the most expressive and best supported debugging +format in GDB. + + +File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running + +4.2 Starting your Program +========================= + +'run' +'r' + Use the 'run' command to start your program under GDB. You must + first specify the program name (except on VxWorks) with an argument + to GDB (*note Getting In and Out of GDB: Invocation.), or by using + the 'file' or 'exec-file' command (*note Commands to Specify Files: + Files.). + + If you are running your program in an execution environment that +supports processes, 'run' creates an inferior process and makes that +process run your program. In some environments without processes, 'run' +jumps to the start of your program. Other targets, like 'remote', are +always running. If you get an error message like this one: + + The "remote" target does not support "run". + Try "help target" or "continue". + +then use 'continue' to run your program. You may need 'load' first +(*note load::). + + The execution of a program is affected by certain information it +receives from its superior. GDB provides ways to specify this +information, which you must do _before_ starting your program. (You can +change it after starting your program, but such changes only affect your +program the next time you start it.) This information may be divided +into four categories: + +The _arguments._ + Specify the arguments to give your program as the arguments of the + 'run' command. If a shell is available on your target, the shell + is used to pass the arguments, so that you may use normal + conventions (such as wildcard expansion or variable substitution) + in describing the arguments. In Unix systems, you can control + which shell is used with the 'SHELL' environment variable. If you + do not define 'SHELL', GDB uses the default shell ('/bin/sh'). You + can disable use of any shell with the 'set startup-with-shell' + command (see below for details). + +The _environment._ + Your program normally inherits its environment from GDB, but you + can use the GDB commands 'set environment' and 'unset environment' + to change parts of the environment that affect your program. *Note + Your Program's Environment: Environment. + +The _working directory._ + Your program inherits its working directory from GDB. You can set + the GDB working directory with the 'cd' command in GDB. *Note Your + Program's Working Directory: Working Directory. + +The _standard input and output._ + Your program normally uses the same device for standard input and + standard output as GDB is using. You can redirect input and output + in the 'run' command line, or you can use the 'tty' command to set + a different device for your program. *Note Your Program's Input + and Output: Input/Output. + + _Warning:_ While input and output redirection work, you cannot use + pipes to pass the output of the program you are debugging to + another program; if you attempt this, GDB is likely to wind up + debugging the wrong program. + + When you issue the 'run' command, your program begins to execute +immediately. *Note Stopping and Continuing: Stopping, for discussion of +how to arrange for your program to stop. Once your program has stopped, +you may call functions in your program, using the 'print' or 'call' +commands. *Note Examining Data: Data. + + If the modification time of your symbol file has changed since the +last time GDB read its symbols, GDB discards its symbol table, and reads +it again. When it does this, GDB tries to retain your current +breakpoints. + +'start' + The name of the main procedure can vary from language to language. + With C or C++, the main procedure name is always 'main', but other + languages such as Ada do not require a specific name for their main + procedure. The debugger provides a convenient way to start the + execution of the program and to stop at the beginning of the main + procedure, depending on the language used. + + The 'start' command does the equivalent of setting a temporary + breakpoint at the beginning of the main procedure and then invoking + the 'run' command. + + Some programs contain an "elaboration" phase where some startup + code is executed before the main procedure is called. This depends + on the languages used to write your program. In C++, for instance, + constructors for static and global objects are executed before + 'main' is called. It is therefore possible that the debugger stops + before reaching the main procedure. However, the temporary + breakpoint will remain to halt execution. + + Specify the arguments to give to your program as arguments to the + 'start' command. These arguments will be given verbatim to the + underlying 'run' command. Note that the same arguments will be + reused if no argument is provided during subsequent calls to + 'start' or 'run'. + + It is sometimes necessary to debug the program during elaboration. + In these cases, using the 'start' command would stop the execution + of your program too late, as the program would have already + completed the elaboration phase. Under these circumstances, insert + breakpoints in your elaboration code before running your program. + +'set exec-wrapper WRAPPER' +'show exec-wrapper' +'unset exec-wrapper' + When 'exec-wrapper' is set, the specified wrapper is used to launch + programs for debugging. GDB starts your program with a shell + command of the form 'exec WRAPPER PROGRAM'. Quoting is added to + PROGRAM and its arguments, but not to WRAPPER, so you should add + quotes if appropriate for your shell. The wrapper runs until it + executes your program, and then GDB takes control. + + You can use any program that eventually calls 'execve' with its + arguments as a wrapper. Several standard Unix utilities do this, + e.g. 'env' and 'nohup'. Any Unix shell script ending with 'exec + "$@"' will also work. + + For example, you can use 'env' to pass an environment variable to + the debugged program, without setting the variable in your shell's + environment: + + (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so' + (gdb) run + + This command is available when debugging locally on most targets, + excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino. + +'set startup-with-shell' +'set startup-with-shell on' +'set startup-with-shell off' +'show set startup-with-shell' + On Unix systems, by default, if a shell is available on your + target, GDB) uses it to start your program. Arguments of the 'run' + command are passed to the shell, which does variable substitution, + expands wildcard characters and performs redirection of I/O. In + some circumstances, it may be useful to disable such use of a + shell, for example, when debugging the shell itself or diagnosing + startup failures such as: + + (gdb) run + Starting program: ./a.out + During startup program terminated with signal SIGSEGV, Segmentation fault. + + which indicates the shell or the wrapper specified with + 'exec-wrapper' crashed, not your program. Most often, this is + caused by something odd in your shell's non-interactive mode + initialization file--such as '.cshrc' for C-shell, $'.zshenv' for + the Z shell, or the file specified in the 'BASH_ENV' environment + variable for BASH. + +'set disable-randomization' +'set disable-randomization on' + This option (enabled by default in GDB) will turn off the native + randomization of the virtual address space of the started program. + This option is useful for multiple debugging sessions to make the + execution better reproducible and memory addresses reusable across + debugging sessions. + + This feature is implemented only on certain targets, including + GNU/Linux. On GNU/Linux you can get the same behavior using + + (gdb) set exec-wrapper setarch `uname -m` -R + +'set disable-randomization off' + Leave the behavior of the started executable unchanged. Some bugs + rear their ugly heads only when the program is loaded at certain + addresses. If your bug disappears when you run the program under + GDB, that might be because GDB by default disables the address + randomization on platforms, such as GNU/Linux, which do that for + stand-alone programs. Use 'set disable-randomization off' to try + to reproduce such elusive bugs. + + On targets where it is available, virtual address space + randomization protects the programs against certain kinds of + security attacks. In these cases the attacker needs to know the + exact location of a concrete executable code. Randomizing its + location makes it impossible to inject jumps misusing a code at its + expected addresses. + + Prelinking shared libraries provides a startup performance + advantage but it makes addresses in these libraries predictable for + privileged processes by having just unprivileged access at the + target system. Reading the shared library binary gives enough + information for assembling the malicious code misusing it. Still + even a prelinked shared library can get loaded at a new random + address just requiring the regular relocation process during the + startup. Shared libraries not already prelinked are always loaded + at a randomly chosen address. + + Position independent executables (PIE) contain position independent + code similar to the shared libraries and therefore such executables + get loaded at a randomly chosen address upon startup. PIE + executables always load even already prelinked shared libraries at + a random address. You can build such executable using 'gcc -fPIE + -pie'. + + Heap (malloc storage), stack and custom mmap areas are always + placed randomly (as long as the randomization is enabled). + +'show disable-randomization' + Show the current setting of the explicit disable of the native + randomization of the virtual address space of the started program. + + +File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running + +4.3 Your Program's Arguments +============================ + +The arguments to your program can be specified by the arguments of the +'run' command. They are passed to a shell, which expands wildcard +characters and performs redirection of I/O, and thence to your program. +Your 'SHELL' environment variable (if it exists) specifies what shell +GDB uses. If you do not define 'SHELL', GDB uses the default shell +('/bin/sh' on Unix). + + On non-Unix systems, the program is usually invoked directly by GDB, +which emulates I/O redirection via the appropriate system calls, and the +wildcard characters are expanded by the startup code of the program, not +by the shell. + + 'run' with no arguments uses the same arguments used by the previous +'run', or those set by the 'set args' command. + +'set args' + Specify the arguments to be used the next time your program is run. + If 'set args' has no arguments, 'run' executes your program with no + arguments. Once you have run your program with arguments, using + 'set args' before the next 'run' is the only way to run it again + without arguments. + +'show args' + Show the arguments to give your program when it is started. + + +File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running + +4.4 Your Program's Environment +============================== + +The "environment" consists of a set of environment variables and their +values. Environment variables conventionally record such things as your +user name, your home directory, your terminal type, and your search path +for programs to run. Usually you set up environment variables with the +shell and they are inherited by all the other programs you run. When +debugging, it can be useful to try running your program with a modified +environment without having to start GDB over again. + +'path DIRECTORY' + Add DIRECTORY to the front of the 'PATH' environment variable (the + search path for executables) that will be passed to your program. + The value of 'PATH' used by GDB does not change. You may specify + several directory names, separated by whitespace or by a + system-dependent separator character (':' on Unix, ';' on MS-DOS + and MS-Windows). If DIRECTORY is already in the path, it is moved + to the front, so it is searched sooner. + + You can use the string '$cwd' to refer to whatever is the current + working directory at the time GDB searches the path. If you use + '.' instead, it refers to the directory where you executed the + 'path' command. GDB replaces '.' in the DIRECTORY argument (with + the current path) before adding DIRECTORY to the search path. + +'show paths' + Display the list of search paths for executables (the 'PATH' + environment variable). + +'show environment [VARNAME]' + Print the value of environment variable VARNAME to be given to your + program when it starts. If you do not supply VARNAME, print the + names and values of all environment variables to be given to your + program. You can abbreviate 'environment' as 'env'. + +'set environment VARNAME [=VALUE]' + Set environment variable VARNAME to VALUE. The value changes for + your program only, not for GDB itself. VALUE may be any string; + the values of environment variables are just strings, and any + interpretation is supplied by your program itself. The VALUE + parameter is optional; if it is eliminated, the variable is set to + a null value. + + For example, this command: + + set env USER = foo + + tells the debugged program, when subsequently run, that its user is + named 'foo'. (The spaces around '=' are used for clarity here; + they are not actually required.) + +'unset environment VARNAME' + Remove variable VARNAME from the environment to be passed to your + program. This is different from 'set env VARNAME ='; 'unset + environment' removes the variable from the environment, rather than + assigning it an empty value. + + _Warning:_ On Unix systems, GDB runs your program using the shell +indicated by your 'SHELL' environment variable if it exists (or +'/bin/sh' if not). If your 'SHELL' variable names a shell that runs an +initialization file when started non-interactively--such as '.cshrc' for +C-shell, $'.zshenv' for the Z shell, or the file specified in the +'BASH_ENV' environment variable for BASH--any variables you set in that +file affect your program. You may wish to move setting of environment +variables to files that are only run when you sign on, such as '.login' +or '.profile'. + + +File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running + +4.5 Your Program's Working Directory +==================================== + +Each time you start your program with 'run', it inherits its working +directory from the current working directory of GDB. The GDB working +directory is initially whatever it inherited from its parent process +(typically the shell), but you can specify a new working directory in +GDB with the 'cd' command. + + The GDB working directory also serves as a default for the commands +that specify files for GDB to operate on. *Note Commands to Specify +Files: Files. + +'cd [DIRECTORY]' + Set the GDB working directory to DIRECTORY. If not given, + DIRECTORY uses ''~''. + +'pwd' + Print the GDB working directory. + + It is generally impossible to find the current working directory of +the process being debugged (since a program can change its directory +during its run). If you work on a system where GDB is configured with +the '/proc' support, you can use the 'info proc' command (*note SVR4 +Process Information::) to find out the current working directory of the +debuggee. + + +File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running + +4.6 Your Program's Input and Output +=================================== + +By default, the program you run under GDB does input and output to the +same terminal that GDB uses. GDB switches the terminal to its own +terminal modes to interact with you, but it records the terminal modes +your program was using and switches back to them when you continue +running your program. + +'info terminal' + Displays information recorded by GDB about the terminal modes your + program is using. + + You can redirect your program's input and/or output using shell +redirection with the 'run' command. For example, + + run > outfile + +starts your program, diverting its output to the file 'outfile'. + + Another way to specify where your program should do input and output +is with the 'tty' command. This command accepts a file name as +argument, and causes this file to be the default for future 'run' +commands. It also resets the controlling terminal for the child +process, for future 'run' commands. For example, + + tty /dev/ttyb + +directs that processes started with subsequent 'run' commands default to +do input and output on the terminal '/dev/ttyb' and have that as their +controlling terminal. + + An explicit redirection in 'run' overrides the 'tty' command's effect +on the input/output device, but not its effect on the controlling +terminal. + + When you use the 'tty' command or redirect input in the 'run' +command, only the input _for your program_ is affected. The input for +GDB still comes from your terminal. 'tty' is an alias for 'set +inferior-tty'. + + You can use the 'show inferior-tty' command to tell GDB to display +the name of the terminal that will be used for future runs of your +program. + +'set inferior-tty /dev/ttyb' + Set the tty for the program being debugged to /dev/ttyb. + +'show inferior-tty' + Show the current tty for the program being debugged. + + +File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running + +4.7 Debugging an Already-running Process +======================================== + +'attach PROCESS-ID' + This command attaches to a running process--one that was started + outside GDB. ('info files' shows your active targets.) The + command takes as argument a process ID. The usual way to find out + the PROCESS-ID of a Unix process is with the 'ps' utility, or with + the 'jobs -l' shell command. + + 'attach' does not repeat if you press a second time after + executing the command. + + To use 'attach', your program must be running in an environment which +supports processes; for example, 'attach' does not work for programs on +bare-board targets that lack an operating system. You must also have +permission to send the process a signal. + + When you use 'attach', the debugger finds the program running in the +process first by looking in the current working directory, then (if the +program is not found) by using the source file search path (*note +Specifying Source Directories: Source Path.). You can also use the +'file' command to load the program. *Note Commands to Specify Files: +Files. + + The first thing GDB does after arranging to debug the specified +process is to stop it. You can examine and modify an attached process +with all the GDB commands that are ordinarily available when you start +processes with 'run'. You can insert breakpoints; you can step and +continue; you can modify storage. If you would rather the process +continue running, you may use the 'continue' command after attaching GDB +to the process. + +'detach' + When you have finished debugging the attached process, you can use + the 'detach' command to release it from GDB control. Detaching the + process continues its execution. After the 'detach' command, that + process and GDB become completely independent once more, and you + are ready to 'attach' another process or start one with 'run'. + 'detach' does not repeat if you press again after executing + the command. + + If you exit GDB while you have an attached process, you detach that +process. If you use the 'run' command, you kill that process. By +default, GDB asks for confirmation if you try to do either of these +things; you can control whether or not you need to confirm by using the +'set confirm' command (*note Optional Warnings and Messages: +Messages/Warnings.). + + +File: gdb.info, Node: Kill Process, Next: Inferiors and Programs, Prev: Attach, Up: Running + +4.8 Killing the Child Process +============================= + +'kill' + Kill the child process in which your program is running under GDB. + + This command is useful if you wish to debug a core dump instead of a +running process. GDB ignores any core dump file while your program is +running. + + On some operating systems, a program cannot be executed outside GDB +while you have breakpoints set on it inside GDB. You can use the 'kill' +command in this situation to permit running your program outside the +debugger. + + The 'kill' command is also useful if you wish to recompile and relink +your program, since on many systems it is impossible to modify an +executable file while it is running in a process. In this case, when +you next type 'run', GDB notices that the file has changed, and reads +the symbol table again (while trying to preserve your current breakpoint +settings). + + +File: gdb.info, Node: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running + +4.9 Debugging Multiple Inferiors and Programs +============================================= + +GDB lets you run and debug multiple programs in a single session. In +addition, GDB on some systems may let you run several programs +simultaneously (otherwise you have to exit from one before starting +another). In the most general case, you can have multiple threads of +execution in each of multiple processes, launched from multiple +executables. + + GDB represents the state of each program execution with an object +called an "inferior". An inferior typically corresponds to a process, +but is more general and applies also to targets that do not have +processes. Inferiors may be created before a process runs, and may be +retained after a process exits. Inferiors have unique identifiers that +are different from process ids. Usually each inferior will also have +its own distinct address space, although some embedded targets may have +several inferiors running in different parts of a single address space. +Each inferior may in turn have multiple threads running in it. + + To find out what inferiors exist at any moment, use 'info inferiors': + +'info inferiors' + Print a list of all inferiors currently being managed by GDB. + + GDB displays for each inferior (in this order): + + 1. the inferior number assigned by GDB + + 2. the target system's inferior identifier + + 3. the name of the executable the inferior is running. + + An asterisk '*' preceding the GDB inferior number indicates the + current inferior. + + For example, + + (gdb) info inferiors + Num Description Executable + 2 process 2307 hello + * 1 process 3401 goodbye + + To switch focus between inferiors, use the 'inferior' command: + +'inferior INFNO' + Make inferior number INFNO the current inferior. The argument + INFNO is the inferior number assigned by GDB, as shown in the first + field of the 'info inferiors' display. + + You can get multiple executables into a debugging session via the +'add-inferior' and 'clone-inferior' commands. On some systems GDB can +add inferiors to the debug session automatically by following calls to +'fork' and 'exec'. To remove inferiors from the debugging session use +the 'remove-inferiors' command. + +'add-inferior [ -copies N ] [ -exec EXECUTABLE ]' + Adds N inferiors to be run using EXECUTABLE as the executable. N + defaults to 1. If no executable is specified, the inferiors begins + empty, with no program. You can still assign or change the program + assigned to the inferior at any time by using the 'file' command + with the executable name as its argument. + +'clone-inferior [ -copies N ] [ INFNO ]' + Adds N inferiors ready to execute the same program as inferior + INFNO. N defaults to 1. INFNO defaults to the number of the + current inferior. This is a convenient command when you want to + run another instance of the inferior you are debugging. + + (gdb) info inferiors + Num Description Executable + * 1 process 29964 helloworld + (gdb) clone-inferior + Added inferior 2. + 1 inferiors added. + (gdb) info inferiors + Num Description Executable + 2 helloworld + * 1 process 29964 helloworld + + You can now simply switch focus to inferior 2 and run it. + +'remove-inferiors INFNO...' + Removes the inferior or inferiors INFNO.... It is not possible to + remove an inferior that is running with this command. For those, + use the 'kill' or 'detach' command first. + + To quit debugging one of the running inferiors that is not the +current inferior, you can either detach from it by using the 'detach inferior' +command (allowing it to run independently), or kill it using the 'kill inferiors' +command: + +'detach inferior INFNO...' + Detach from the inferior or inferiors identified by GDB inferior + number(s) INFNO.... Note that the inferior's entry still stays on + the list of inferiors shown by 'info inferiors', but its + Description will show ''. + +'kill inferiors INFNO...' + Kill the inferior or inferiors identified by GDB inferior number(s) + INFNO.... Note that the inferior's entry still stays on the list + of inferiors shown by 'info inferiors', but its Description will + show ''. + + After the successful completion of a command such as 'detach', +'detach inferiors', 'kill' or 'kill inferiors', or after a normal +process exit, the inferior is still valid and listed with 'info +inferiors', ready to be restarted. + + To be notified when inferiors are started or exit under GDB's control +use 'set print inferior-events': + +'set print inferior-events' +'set print inferior-events on' +'set print inferior-events off' + The 'set print inferior-events' command allows you to enable or + disable printing of messages when GDB notices that new inferiors + have started or that inferiors have exited or have been detached. + By default, these messages will not be printed. + +'show print inferior-events' + Show whether messages will be printed when GDB detects that + inferiors have started, exited or have been detached. + + Many commands will work the same with multiple programs as with a +single program: e.g., 'print myglobal' will simply display the value of +'myglobal' in the current inferior. + + Occasionaly, when debugging GDB itself, it may be useful to get more +info about the relationship of inferiors, programs, address spaces in a +debug session. You can do that with the 'maint info program-spaces' +command. + +'maint info program-spaces' + Print a list of all program spaces currently being managed by GDB. + + GDB displays for each program space (in this order): + + 1. the program space number assigned by GDB + + 2. the name of the executable loaded into the program space, with + e.g., the 'file' command. + + An asterisk '*' preceding the GDB program space number indicates + the current program space. + + In addition, below each program space line, GDB prints extra + information that isn't suitable to display in tabular form. For + example, the list of inferiors bound to the program space. + + (gdb) maint info program-spaces + Id Executable + 2 goodbye + Bound inferiors: ID 1 (process 21561) + * 1 hello + + Here we can see that no inferior is running the program 'hello', + while 'process 21561' is running the program 'goodbye'. On some + targets, it is possible that multiple inferiors are bound to the + same program space. The most common example is that of debugging + both the parent and child processes of a 'vfork' call. For + example, + + (gdb) maint info program-spaces + Id Executable + * 1 vfork-test + Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) + + Here, both inferior 2 and inferior 1 are running in the same + program space as a result of inferior 1 having executed a 'vfork' + call. + + +File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running + +4.10 Debugging Programs with Multiple Threads +============================================= + +In some operating systems, such as HP-UX and Solaris, a single program +may have more than one "thread" of execution. The precise semantics of +threads differ from one operating system to another, but in general the +threads of a single program are akin to multiple processes--except that +they share one address space (that is, they can all examine and modify +the same variables). On the other hand, each thread has its own +registers and execution stack, and perhaps private memory. + + GDB provides these facilities for debugging multi-thread programs: + + * automatic notification of new threads + * 'thread THREADNO', a command to switch among threads + * 'info threads', a command to inquire about existing threads + * 'thread apply [THREADNO] [ALL] ARGS', a command to apply a command + to a list of threads + * thread-specific breakpoints + * 'set print thread-events', which controls printing of messages on + thread start and exit. + * 'set libthread-db-search-path PATH', which lets the user specify + which 'libthread_db' to use if the default choice isn't compatible + with the program. + + _Warning:_ These facilities are not yet available on every GDB + configuration where the operating system supports threads. If your + GDB does not support threads, these commands have no effect. For + example, a system without thread support shows no output from 'info + threads', and always rejects the 'thread' command, like this: + + (gdb) info threads + (gdb) thread 1 + Thread ID 1 not known. Use the "info threads" command to + see the IDs of currently known threads. + + The GDB thread debugging facility allows you to observe all threads +while your program runs--but whenever GDB takes control, one thread in +particular is always the focus of debugging. This thread is called the +"current thread". Debugging commands show program information from the +perspective of the current thread. + + Whenever GDB detects a new thread in your program, it displays the +target system's identification for the thread with a message in the form +'[New SYSTAG]'. SYSTAG is a thread identifier whose form varies +depending on the particular system. For example, on GNU/Linux, you +might see + + [New Thread 0x41e02940 (LWP 25582)] + +when GDB notices a new thread. In contrast, on an SGI system, the +SYSTAG is simply something like 'process 368', with no further +qualifier. + + For debugging purposes, GDB associates its own thread number--always +a single integer--with each thread in your program. + +'info threads [ID...]' + Display a summary of all threads currently in your program. + Optional argument ID... is one or more thread ids separated by + spaces, and means to print information only about the specified + thread or threads. GDB displays for each thread (in this order): + + 1. the thread number assigned by GDB + + 2. the target system's thread identifier (SYSTAG) + + 3. the thread's name, if one is known. A thread can either be + named by the user (see 'thread name', below), or, in some + cases, by the program itself. + + 4. the current stack frame summary for that thread + + An asterisk '*' to the left of the GDB thread number indicates the + current thread. + + For example, + + (gdb) info threads + Id Target Id Frame + 3 process 35 thread 27 0x34e5 in sigpause () + 2 process 35 thread 23 0x34e5 in sigpause () + * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) + at threadtest.c:68 + + On Solaris, you can display more information about user threads with +a Solaris-specific command: + +'maint info sol-threads' + Display info on Solaris user threads. + +'thread THREADNO' + Make thread number THREADNO the current thread. The command + argument THREADNO is the internal GDB thread number, as shown in + the first field of the 'info threads' display. GDB responds by + displaying the system identifier of the thread you selected, and + its current stack frame summary: + + (gdb) thread 2 + [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))] + #0 some_function (ignore=0x0) at example.c:8 + 8 printf ("hello\n"); + + As with the '[New ...]' message, the form of the text after + 'Switching to' depends on your system's conventions for identifying + threads. + + The debugger convenience variable '$_thread' contains the number of + the current thread. You may find this useful in writing breakpoint + conditional expressions, command scripts, and so forth. See *Note + Convenience Variables: Convenience Vars, for general information on + convenience variables. + +'thread apply [THREADNO | all] COMMAND' + The 'thread apply' command allows you to apply the named COMMAND to + one or more threads. Specify the numbers of the threads that you + want affected with the command argument THREADNO. It can be a + single thread number, one of the numbers shown in the first field + of the 'info threads' display; or it could be a range of thread + numbers, as in '2-4'. To apply a command to all threads, type + 'thread apply all COMMAND'. + +'thread name [NAME]' + This command assigns a name to the current thread. If no argument + is given, any existing user-specified name is removed. The thread + name appears in the 'info threads' display. + + On some systems, such as GNU/Linux, GDB is able to determine the + name of the thread as given by the OS. On these systems, a name + specified with 'thread name' will override the system-give name, + and removing the user-specified name will cause GDB to once again + display the system-specified name. + +'thread find [REGEXP]' + Search for and display thread ids whose name or SYSTAG matches the + supplied regular expression. + + As well as being the complement to the 'thread name' command, this + command also allows you to identify a thread by its target SYSTAG. + For instance, on GNU/Linux, the target SYSTAG is the LWP id. + + (GDB) thread find 26688 + Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' + (GDB) info thread 4 + Id Target Id Frame + 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () + +'set print thread-events' +'set print thread-events on' +'set print thread-events off' + The 'set print thread-events' command allows you to enable or + disable printing of messages when GDB notices that new threads have + started or that threads have exited. By default, these messages + will be printed if detection of these events is supported by the + target. Note that these messages cannot be disabled on all + targets. + +'show print thread-events' + Show whether messages will be printed when GDB detects that threads + have started and exited. + + *Note Stopping and Starting Multi-thread Programs: Thread Stops, for +more information about how GDB behaves when you stop and start programs +with multiple threads. + + *Note Setting Watchpoints: Set Watchpoints, for information about +watchpoints in programs with multiple threads. + +'set libthread-db-search-path [PATH]' + If this variable is set, PATH is a colon-separated list of + directories GDB will use to search for 'libthread_db'. If you omit + PATH, 'libthread-db-search-path' will be reset to its default value + ('$sdir:$pdir' on GNU/Linux and Solaris systems). Internally, the + default value comes from the 'LIBTHREAD_DB_SEARCH_PATH' macro. + + On GNU/Linux and Solaris systems, GDB uses a "helper" + 'libthread_db' library to obtain information about threads in the + inferior process. GDB will use 'libthread-db-search-path' to find + 'libthread_db'. GDB also consults first if inferior specific + thread debugging library loading is enabled by 'set auto-load + libthread-db' (*note libthread_db.so.1 file::). + + A special entry '$sdir' for 'libthread-db-search-path' refers to + the default system directories that are normally searched for + loading shared libraries. The '$sdir' entry is the only kind not + needing to be enabled by 'set auto-load libthread-db' (*note + libthread_db.so.1 file::). + + A special entry '$pdir' for 'libthread-db-search-path' refers to + the directory from which 'libpthread' was loaded in the inferior + process. + + For any 'libthread_db' library GDB finds in above directories, GDB + attempts to initialize it with the current inferior process. If + this initialization fails (which could happen because of a version + mismatch between 'libthread_db' and 'libpthread'), GDB will unload + 'libthread_db', and continue with the next directory. If none of + 'libthread_db' libraries initialize successfully, GDB will issue a + warning and thread debugging will be disabled. + + Setting 'libthread-db-search-path' is currently implemented only on + some platforms. + +'show libthread-db-search-path' + Display current libthread_db search path. + +'set debug libthread-db' +'show debug libthread-db' + Turns on or off display of 'libthread_db'-related events. Use '1' + to enable, '0' to disable. + + +File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running + +4.11 Debugging Forks +==================== + +On most systems, GDB has no special support for debugging programs which +create additional processes using the 'fork' function. When a program +forks, GDB will continue to debug the parent process and the child +process will run unimpeded. If you have set a breakpoint in any code +which the child then executes, the child will get a 'SIGTRAP' signal +which (unless it catches the signal) will cause it to terminate. + + However, if you want to debug the child process there is a workaround +which isn't too painful. Put a call to 'sleep' in the code which the +child process executes after the fork. It may be useful to sleep only +if a certain environment variable is set, or a certain file exists, so +that the delay need not occur when you don't want to run GDB on the +child. While the child is sleeping, use the 'ps' program to get its +process ID. Then tell GDB (a new invocation of GDB if you are also +debugging the parent process) to attach to the child process (*note +Attach::). From that point on you can debug the child process just like +any other process which you attached to. + + On some systems, GDB provides support for debugging programs that +create additional processes using the 'fork' or 'vfork' functions. +Currently, the only platforms with this feature are HP-UX (11.x and +later only?) and GNU/Linux (kernel version 2.5.60 and later). + + By default, when a program forks, GDB will continue to debug the +parent process and the child process will run unimpeded. + + If you want to follow the child process instead of the parent +process, use the command 'set follow-fork-mode'. + +'set follow-fork-mode MODE' + Set the debugger response to a program call of 'fork' or 'vfork'. + A call to 'fork' or 'vfork' creates a new process. The MODE + argument can be: + + 'parent' + The original process is debugged after a fork. The child + process runs unimpeded. This is the default. + + 'child' + The new process is debugged after a fork. The parent process + runs unimpeded. + +'show follow-fork-mode' + Display the current debugger response to a 'fork' or 'vfork' call. + + On Linux, if you want to debug both the parent and child processes, +use the command 'set detach-on-fork'. + +'set detach-on-fork MODE' + Tells gdb whether to detach one of the processes after a fork, or + retain debugger control over them both. + + 'on' + The child process (or parent process, depending on the value + of 'follow-fork-mode') will be detached and allowed to run + independently. This is the default. + + 'off' + Both processes will be held under the control of GDB. One + process (child or parent, depending on the value of + 'follow-fork-mode') is debugged as usual, while the other is + held suspended. + +'show detach-on-fork' + Show whether detach-on-fork mode is on/off. + + If you choose to set 'detach-on-fork' mode off, then GDB will retain +control of all forked processes (including nested forks). You can list +the forked processes under the control of GDB by using the 'info inferiors' +command, and switch from one fork to another by using the 'inferior' +command (*note Debugging Multiple Inferiors and Programs: Inferiors and +Programs.). + + To quit debugging one of the forked processes, you can either detach +from it by using the 'detach inferiors' command (allowing it to run +independently), or kill it using the 'kill inferiors' command. *Note +Debugging Multiple Inferiors and Programs: Inferiors and Programs. + + If you ask to debug a child process and a 'vfork' is followed by an +'exec', GDB executes the new target up to the first breakpoint in the +new target. If you have a breakpoint set on 'main' in your original +program, the breakpoint will also be set on the child process's 'main'. + + On some systems, when a child process is spawned by 'vfork', you +cannot debug the child or parent until an 'exec' call completes. + + If you issue a 'run' command to GDB after an 'exec' call executes, +the new target restarts. To restart the parent process, use the 'file' +command with the parent executable name as its argument. By default, +after an 'exec' call executes, GDB discards the symbols of the previous +executable image. You can change this behaviour with the 'set follow-exec-mode' +command. + +'set follow-exec-mode MODE' + + Set debugger response to a program call of 'exec'. An 'exec' call + replaces the program image of a process. + + 'follow-exec-mode' can be: + + 'new' + GDB creates a new inferior and rebinds the process to this new + inferior. The program the process was running before the + 'exec' call can be restarted afterwards by restarting the + original inferior. + + For example: + + (gdb) info inferiors + (gdb) info inferior + Id Description Executable + * 1 prog1 + (gdb) run + process 12020 is executing new program: prog2 + Program exited normally. + (gdb) info inferiors + Id Description Executable + * 2 prog2 + 1 prog1 + + 'same' + GDB keeps the process bound to the same inferior. The new + executable image replaces the previous executable loaded in + the inferior. Restarting the inferior after the 'exec' call, + with e.g., the 'run' command, restarts the executable the + process was running after the 'exec' call. This is the + default mode. + + For example: + + (gdb) info inferiors + Id Description Executable + * 1 prog1 + (gdb) run + process 12020 is executing new program: prog2 + Program exited normally. + (gdb) info inferiors + Id Description Executable + * 1 prog2 + + You can use the 'catch' command to make GDB stop whenever a 'fork', +'vfork', or 'exec' call is made. *Note Setting Catchpoints: Set +Catchpoints. + + +File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running + +4.12 Setting a _Bookmark_ to Return to Later +============================================ + +On certain operating systems(1), GDB is able to save a "snapshot" of a +program's state, called a "checkpoint", and come back to it later. + + Returning to a checkpoint effectively undoes everything that has +happened in the program since the 'checkpoint' was saved. This includes +changes in memory, registers, and even (within some limits) system +state. Effectively, it is like going back in time to the moment when +the checkpoint was saved. + + Thus, if you're stepping thru a program and you think you're getting +close to the point where things go wrong, you can save a checkpoint. +Then, if you accidentally go too far and miss the critical statement, +instead of having to restart your program from the beginning, you can +just go back to the checkpoint and start again from there. + + This can be especially useful if it takes a lot of time or steps to +reach the point where you think the bug occurs. + + To use the 'checkpoint'/'restart' method of debugging: + +'checkpoint' + Save a snapshot of the debugged program's current execution state. + The 'checkpoint' command takes no arguments, but each checkpoint is + assigned a small integer id, similar to a breakpoint id. + +'info checkpoints' + List the checkpoints that have been saved in the current debugging + session. For each checkpoint, the following information will be + listed: + + 'Checkpoint ID' + 'Process ID' + 'Code Address' + 'Source line, or label' + +'restart CHECKPOINT-ID' + Restore the program state that was saved as checkpoint number + CHECKPOINT-ID. All program variables, registers, stack frames etc. + will be returned to the values that they had when the checkpoint + was saved. In essence, gdb will "wind back the clock" to the point + in time when the checkpoint was saved. + + Note that breakpoints, GDB variables, command history etc. are not + affected by restoring a checkpoint. In general, a checkpoint only + restores things that reside in the program being debugged, not in + the debugger. + +'delete checkpoint CHECKPOINT-ID' + Delete the previously-saved checkpoint identified by CHECKPOINT-ID. + + Returning to a previously saved checkpoint will restore the user +state of the program being debugged, plus a significant subset of the +system (OS) state, including file pointers. It won't "un-write" data +from a file, but it will rewind the file pointer to the previous +location, so that the previously written data can be overwritten. For +files opened in read mode, the pointer will also be restored so that the +previously read data can be read again. + + Of course, characters that have been sent to a printer (or other +external device) cannot be "snatched back", and characters received from +eg. a serial device can be removed from internal program buffers, but +they cannot be "pushed back" into the serial pipeline, ready to be +received again. Similarly, the actual contents of files that have been +changed cannot be restored (at this time). + + However, within those constraints, you actually can "rewind" your +program to a previously saved point in time, and begin debugging it +again -- and you can change the course of events so as to debug a +different execution path this time. + + Finally, there is one bit of internal program state that will be +different when you return to a checkpoint -- the program's process id. +Each checkpoint will have a unique process id (or PID), and each will be +different from the program's original PID. If your program has saved a +local copy of its process id, this could potentially pose a problem. + +4.12.1 A Non-obvious Benefit of Using Checkpoints +------------------------------------------------- + +On some systems such as GNU/Linux, address space randomization is +performed on new processes for security reasons. This makes it +difficult or impossible to set a breakpoint, or watchpoint, on an +absolute address if you have to restart the program, since the absolute +location of a symbol will change from one execution to the next. + + A checkpoint, however, is an _identical_ copy of a process. +Therefore if you create a checkpoint at (eg.) the start of main, and +simply return to that checkpoint instead of restarting the process, you +can avoid the effects of address randomization and your symbols will all +stay in the same place. + + ---------- Footnotes ---------- + + (1) Currently, only GNU/Linux. + + +File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top + +5 Stopping and Continuing +************************* + +The principal purposes of using a debugger are so that you can stop your +program before it terminates; or so that, if your program runs into +trouble, you can investigate and find out why. + + Inside GDB, your program may stop for any of several reasons, such as +a signal, a breakpoint, or reaching a new line after a GDB command such +as 'step'. You may then examine and change variables, set new +breakpoints or remove old ones, and then continue execution. Usually, +the messages shown by GDB provide ample explanation of the status of +your program--but you can also explicitly request this information at +any time. + +'info program' + Display information about the status of your program: whether it is + running or not, what process it is, and why it stopped. + +* Menu: + +* Breakpoints:: Breakpoints, watchpoints, and catchpoints +* Continuing and Stepping:: Resuming execution +* Skipping Over Functions and Files:: + Skipping over functions and files +* Signals:: Signals +* Thread Stops:: Stopping and starting multi-thread programs + + +File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping + +5.1 Breakpoints, Watchpoints, and Catchpoints +============================================= + +A "breakpoint" makes your program stop whenever a certain point in the +program is reached. For each breakpoint, you can add conditions to +control in finer detail whether your program stops. You can set +breakpoints with the 'break' command and its variants (*note Setting +Breakpoints: Set Breaks.), to specify the place where your program +should stop by line number, function name or exact address in the +program. + + On some systems, you can set breakpoints in shared libraries before +the executable is run. There is a minor limitation on HP-UX systems: +you must wait until the executable is run in order to set breakpoints in +shared library routines that are not called directly by the program (for +example, routines that are arguments in a 'pthread_create' call). + + A "watchpoint" is a special breakpoint that stops your program when +the value of an expression changes. The expression may be a value of a +variable, or it could involve values of one or more variables combined +by operators, such as 'a + b'. This is sometimes called "data +breakpoints". You must use a different command to set watchpoints +(*note Setting Watchpoints: Set Watchpoints.), but aside from that, you +can manage a watchpoint like any other breakpoint: you enable, disable, +and delete both breakpoints and watchpoints using the same commands. + + You can arrange to have values from your program displayed +automatically whenever GDB stops at a breakpoint. *Note Automatic +Display: Auto Display. + + A "catchpoint" is another special breakpoint that stops your program +when a certain kind of event occurs, such as the throwing of a C++ +exception or the loading of a library. As with watchpoints, you use a +different command to set a catchpoint (*note Setting Catchpoints: Set +Catchpoints.), but aside from that, you can manage a catchpoint like any +other breakpoint. (To stop when your program receives a signal, use the +'handle' command; see *note Signals: Signals.) + + GDB assigns a number to each breakpoint, watchpoint, or catchpoint +when you create it; these numbers are successive integers starting with +one. In many of the commands for controlling various features of +breakpoints you use the breakpoint number to say which breakpoint you +want to change. Each breakpoint may be "enabled" or "disabled"; if +disabled, it has no effect on your program until you enable it again. + + Some GDB commands accept a range of breakpoints on which to operate. +A breakpoint range is either a single breakpoint number, like '5', or +two such numbers, in increasing order, separated by a hyphen, like +'5-7'. When a breakpoint range is given to a command, all breakpoints +in that range are operated on. + +* Menu: + +* Set Breaks:: Setting breakpoints +* Set Watchpoints:: Setting watchpoints +* Set Catchpoints:: Setting catchpoints +* Delete Breaks:: Deleting breakpoints +* Disabling:: Disabling breakpoints +* Conditions:: Break conditions +* Break Commands:: Breakpoint command lists +* Dynamic Printf:: Dynamic printf +* Save Breakpoints:: How to save breakpoints in a file +* Static Probe Points:: Listing static probe points +* Error in Breakpoints:: "Cannot insert breakpoints" +* Breakpoint-related Warnings:: "Breakpoint address adjusted..." + + +File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints + +5.1.1 Setting Breakpoints +------------------------- + +Breakpoints are set with the 'break' command (abbreviated 'b'). The +debugger convenience variable '$bpnum' records the number of the +breakpoint you've set most recently; see *note Convenience Variables: +Convenience Vars, for a discussion of what you can do with convenience +variables. + +'break LOCATION' + Set a breakpoint at the given LOCATION, which can specify a + function name, a line number, or an address of an instruction. + (*Note Specify Location::, for a list of all the possible ways to + specify a LOCATION.) The breakpoint will stop your program just + before it executes any of the code in the specified LOCATION. + + When using source languages that permit overloading of symbols, + such as C++, a function name may refer to more than one possible + place to break. *Note Ambiguous Expressions: Ambiguous + Expressions, for a discussion of that situation. + + It is also possible to insert a breakpoint that will stop the + program only if a specific thread (*note Thread-Specific + Breakpoints::) or a specific task (*note Ada Tasks::) hits that + breakpoint. + +'break' + When called without any arguments, 'break' sets a breakpoint at the + next instruction to be executed in the selected stack frame (*note + Examining the Stack: Stack.). In any selected frame but the + innermost, this makes your program stop as soon as control returns + to that frame. This is similar to the effect of a 'finish' command + in the frame inside the selected frame--except that 'finish' does + not leave an active breakpoint. If you use 'break' without an + argument in the innermost frame, GDB stops the next time it reaches + the current location; this may be useful inside loops. + + GDB normally ignores breakpoints when it resumes execution, until + at least one instruction has been executed. If it did not do this, + you would be unable to proceed past a breakpoint without first + disabling the breakpoint. This rule applies whether or not the + breakpoint already existed when your program stopped. + +'break ... if COND' + Set a breakpoint with condition COND; evaluate the expression COND + each time the breakpoint is reached, and stop only if the value is + nonzero--that is, if COND evaluates as true. '...' stands for one + of the possible arguments described above (or no argument) + specifying where to break. *Note Break Conditions: Conditions, for + more information on breakpoint conditions. + +'tbreak ARGS' + Set a breakpoint enabled only for one stop. ARGS are the same as + for the 'break' command, and the breakpoint is set in the same way, + but the breakpoint is automatically deleted after the first time + your program stops there. *Note Disabling Breakpoints: Disabling. + +'hbreak ARGS' + Set a hardware-assisted breakpoint. ARGS are the same as for the + 'break' command and the breakpoint is set in the same way, but the + breakpoint requires hardware support and some target hardware may + not have this support. The main purpose of this is EPROM/ROM code + debugging, so you can set a breakpoint at an instruction without + changing the instruction. This can be used with the new + trap-generation provided by SPARClite DSU and most x86-based + targets. These targets will generate traps when a program accesses + some data or instruction address that is assigned to the debug + registers. However the hardware breakpoint registers can take a + limited number of breakpoints. For example, on the DSU, only two + data breakpoints can be set at a time, and GDB will reject this + command if more than two are used. Delete or disable unused + hardware breakpoints before setting new ones (*note Disabling + Breakpoints: Disabling.). *Note Break Conditions: Conditions. For + remote targets, you can restrict the number of hardware breakpoints + GDB will use, see *note set remote hardware-breakpoint-limit::. + +'thbreak ARGS' + Set a hardware-assisted breakpoint enabled only for one stop. ARGS + are the same as for the 'hbreak' command and the breakpoint is set + in the same way. However, like the 'tbreak' command, the + breakpoint is automatically deleted after the first time your + program stops there. Also, like the 'hbreak' command, the + breakpoint requires hardware support and some target hardware may + not have this support. *Note Disabling Breakpoints: Disabling. + See also *note Break Conditions: Conditions. + +'rbreak REGEX' + Set breakpoints on all functions matching the regular expression + REGEX. This command sets an unconditional breakpoint on all + matches, printing a list of all breakpoints it set. Once these + breakpoints are set, they are treated just like the breakpoints set + with the 'break' command. You can delete them, disable them, or + make them conditional the same way as any other breakpoint. + + The syntax of the regular expression is the standard one used with + tools like 'grep'. Note that this is different from the syntax + used by shells, so for instance 'foo*' matches all functions that + include an 'fo' followed by zero or more 'o's. There is an + implicit '.*' leading and trailing the regular expression you + supply, so to match only functions that begin with 'foo', use + '^foo'. + + When debugging C++ programs, 'rbreak' is useful for setting + breakpoints on overloaded functions that are not members of any + special classes. + + The 'rbreak' command can be used to set breakpoints in *all* the + functions in a program, like this: + + (gdb) rbreak . + +'rbreak FILE:REGEX' + If 'rbreak' is called with a filename qualification, it limits the + search for functions matching the given regular expression to the + specified FILE. This can be used, for example, to set breakpoints + on every function in a given file: + + (gdb) rbreak file.c:. + + The colon separating the filename qualifier from the regex may + optionally be surrounded by spaces. + +'info breakpoints [N...]' +'info break [N...]' + Print a table of all breakpoints, watchpoints, and catchpoints set + and not deleted. Optional argument N means print information only + about the specified breakpoint(s) (or watchpoint(s) or + catchpoint(s)). For each breakpoint, following columns are + printed: + + _Breakpoint Numbers_ + _Type_ + Breakpoint, watchpoint, or catchpoint. + _Disposition_ + Whether the breakpoint is marked to be disabled or deleted + when hit. + _Enabled or Disabled_ + Enabled breakpoints are marked with 'y'. 'n' marks + breakpoints that are not enabled. + _Address_ + Where the breakpoint is in your program, as a memory address. + For a pending breakpoint whose address is not yet known, this + field will contain ''. Such breakpoint won't fire + until a shared library that has the symbol or line referred by + breakpoint is loaded. See below for details. A breakpoint + with several locations will have '' in this + field--see below for details. + _What_ + Where the breakpoint is in the source for your program, as a + file and line number. For a pending breakpoint, the original + string passed to the breakpoint command will be listed as it + cannot be resolved until the appropriate shared library is + loaded in the future. + + If a breakpoint is conditional, there are two evaluation modes: + "host" and "target". If mode is "host", breakpoint condition + evaluation is done by GDB on the host's side. If it is "target", + then the condition is evaluated by the target. The 'info break' + command shows the condition on the line following the affected + breakpoint, together with its condition evaluation mode in between + parentheses. + + Breakpoint commands, if any, are listed after that. A pending + breakpoint is allowed to have a condition specified for it. The + condition is not parsed for validity until a shared library is + loaded that allows the pending breakpoint to resolve to a valid + location. + + 'info break' with a breakpoint number N as argument lists only that + breakpoint. The convenience variable '$_' and the default + examining-address for the 'x' command are set to the address of the + last breakpoint listed (*note Examining Memory: Memory.). + + 'info break' displays a count of the number of times the breakpoint + has been hit. This is especially useful in conjunction with the + 'ignore' command. You can ignore a large number of breakpoint + hits, look at the breakpoint info to see how many times the + breakpoint was hit, and then run again, ignoring one less than that + number. This will get you quickly to the last hit of that + breakpoint. + + For a breakpoints with an enable count (xref) greater than 1, 'info + break' also displays that count. + + GDB allows you to set any number of breakpoints at the same place in +your program. There is nothing silly or meaningless about this. When +the breakpoints are conditional, this is even useful (*note Break +Conditions: Conditions.). + + It is possible that a breakpoint corresponds to several locations in +your program. Examples of this situation are: + + * Multiple functions in the program may have the same name. + + * For a C++ constructor, the GCC compiler generates several instances + of the function body, used in different cases. + + * For a C++ template function, a given line in the function can + correspond to any number of instantiations. + + * For an inlined function, a given source line can correspond to + several places where that function is inlined. + + In all those cases, GDB will insert a breakpoint at all the relevant +locations. + + A breakpoint with multiple locations is displayed in the breakpoint +table using several rows--one header row, followed by one row for each +breakpoint location. The header row has '' in the address +column. The rows for individual locations contain the actual addresses +for locations, and show the functions to which those locations belong. +The number column for a location is of the form +BREAKPOINT-NUMBER.LOCATION-NUMBER. + + For example: + + Num Type Disp Enb Address What + 1 breakpoint keep y + stop only if i==1 + breakpoint already hit 1 time + 1.1 y 0x080486a2 in void foo() at t.cc:8 + 1.2 y 0x080486ca in void foo() at t.cc:8 + + Each location can be individually enabled or disabled by passing +BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the 'enable' and +'disable' commands. Note that you cannot delete the individual +locations from the list, you can only delete the entire list of +locations that belong to their parent breakpoint (with the 'delete NUM' +command, where NUM is the number of the parent breakpoint, 1 in the +above example). Disabling or enabling the parent breakpoint (*note +Disabling::) affects all of the locations that belong to that +breakpoint. + + It's quite common to have a breakpoint inside a shared library. +Shared libraries can be loaded and unloaded explicitly, and possibly +repeatedly, as the program is executed. To support this use case, GDB +updates breakpoint locations whenever any shared library is loaded or +unloaded. Typically, you would set a breakpoint in a shared library at +the beginning of your debugging session, when the library is not loaded, +and when the symbols from the library are not available. When you try +to set breakpoint, GDB will ask you if you want to set a so called +"pending breakpoint"--breakpoint whose address is not yet resolved. + + After the program is run, whenever a new shared library is loaded, +GDB reevaluates all the breakpoints. When a newly loaded shared library +contains the symbol or line referred to by some pending breakpoint, that +breakpoint is resolved and becomes an ordinary breakpoint. When a +library is unloaded, all breakpoints that refer to its symbols or source +lines become pending again. + + This logic works for breakpoints with multiple locations, too. For +example, if you have a breakpoint in a C++ template function, and a +newly loaded shared library has an instantiation of that template, a new +location is added to the list of locations for the breakpoint. + + Except for having unresolved address, pending breakpoints do not +differ from regular breakpoints. You can set conditions or commands, +enable and disable them and perform other breakpoint operations. + + GDB provides some additional commands for controlling what happens +when the 'break' command cannot resolve breakpoint address specification +to an address: + +'set breakpoint pending auto' + This is the default behavior. When GDB cannot find the breakpoint + location, it queries you whether a pending breakpoint should be + created. + +'set breakpoint pending on' + This indicates that an unrecognized breakpoint location should + automatically result in a pending breakpoint being created. + +'set breakpoint pending off' + This indicates that pending breakpoints are not to be created. Any + unrecognized breakpoint location results in an error. This setting + does not affect any pending breakpoints previously created. + +'show breakpoint pending' + Show the current behavior setting for creating pending breakpoints. + + The settings above only affect the 'break' command and its variants. +Once breakpoint is set, it will be automatically updated as shared +libraries are loaded and unloaded. + + For some targets, GDB can automatically decide if hardware or +software breakpoints should be used, depending on whether the breakpoint +address is read-only or read-write. This applies to breakpoints set +with the 'break' command as well as to internal breakpoints set by +commands like 'next' and 'finish'. For breakpoints set with 'hbreak', +GDB will always use hardware breakpoints. + + You can control this automatic behaviour with the following +commands:: + +'set breakpoint auto-hw on' + This is the default behavior. When GDB sets a breakpoint, it will + try to use the target memory map to decide if software or hardware + breakpoint must be used. + +'set breakpoint auto-hw off' + This indicates GDB should not automatically select breakpoint type. + If the target provides a memory map, GDB will warn when trying to + set software breakpoint at a read-only address. + + GDB normally implements breakpoints by replacing the program code at +the breakpoint address with a special instruction, which, when executed, +given control to the debugger. By default, the program code is so +modified only when the program is resumed. As soon as the program +stops, GDB restores the original instructions. This behaviour guards +against leaving breakpoints inserted in the target should gdb abrubptly +disconnect. However, with slow remote targets, inserting and removing +breakpoint can reduce the performance. This behavior can be controlled +with the following commands:: + +'set breakpoint always-inserted off' + All breakpoints, including newly added by the user, are inserted in + the target only when the target is resumed. All breakpoints are + removed from the target when it stops. + +'set breakpoint always-inserted on' + Causes all breakpoints to be inserted in the target at all times. + If the user adds a new breakpoint, or changes an existing + breakpoint, the breakpoints in the target are updated immediately. + A breakpoint is removed from the target only when breakpoint itself + is removed. + +'set breakpoint always-inserted auto' + This is the default mode. If GDB is controlling the inferior in + non-stop mode (*note Non-Stop Mode::), gdb behaves as if + 'breakpoint always-inserted' mode is on. If GDB is controlling the + inferior in all-stop mode, GDB behaves as if 'breakpoint + always-inserted' mode is off. + + GDB handles conditional breakpoints by evaluating these conditions +when a breakpoint breaks. If the condition is true, then the process +being debugged stops, otherwise the process is resumed. + + If the target supports evaluating conditions on its end, GDB may +download the breakpoint, together with its conditions, to it. + + This feature can be controlled via the following commands: + +'set breakpoint condition-evaluation host' + This option commands GDB to evaluate the breakpoint conditions on + the host's side. Unconditional breakpoints are sent to the target + which in turn receives the triggers and reports them back to GDB + for condition evaluation. This is the standard evaluation mode. + +'set breakpoint condition-evaluation target' + This option commands GDB to download breakpoint conditions to the + target at the moment of their insertion. The target is responsible + for evaluating the conditional expression and reporting breakpoint + stop events back to GDB whenever the condition is true. Due to + limitations of target-side evaluation, some conditions cannot be + evaluated there, e.g., conditions that depend on local data that is + only known to the host. Examples include conditional expressions + involving convenience variables, complex types that cannot be + handled by the agent expression parser and expressions that are too + long to be sent over to the target, specially when the target is a + remote system. In these cases, the conditions will be evaluated by + GDB. + +'set breakpoint condition-evaluation auto' + This is the default mode. If the target supports evaluating + breakpoint conditions on its end, GDB will download breakpoint + conditions to the target (limitations mentioned previously apply). + If the target does not support breakpoint condition evaluation, + then GDB will fallback to evaluating all these conditions on the + host's side. + + GDB itself sometimes sets breakpoints in your program for special +purposes, such as proper handling of 'longjmp' (in C programs). These +internal breakpoints are assigned negative numbers, starting with '-1'; +'info breakpoints' does not display them. You can see these breakpoints +with the GDB maintenance command 'maint info breakpoints' (*note maint +info breakpoints::). + + +File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints + +5.1.2 Setting Watchpoints +------------------------- + +You can use a watchpoint to stop execution whenever the value of an +expression changes, without having to predict a particular place where +this may happen. (This is sometimes called a "data breakpoint".) The +expression may be as simple as the value of a single variable, or as +complex as many variables combined by operators. Examples include: + + * A reference to the value of a single variable. + + * An address cast to an appropriate data type. For example, '*(int + *)0x12345678' will watch a 4-byte region at the specified address + (assuming an 'int' occupies 4 bytes). + + * An arbitrarily complex expression, such as 'a*b + c/d'. The + expression can use any operators valid in the program's native + language (*note Languages::). + + You can set a watchpoint on an expression even if the expression can +not be evaluated yet. For instance, you can set a watchpoint on +'*global_ptr' before 'global_ptr' is initialized. GDB will stop when +your program sets 'global_ptr' and the expression produces a valid +value. If the expression becomes valid in some other way than changing +a variable (e.g. if the memory pointed to by '*global_ptr' becomes +readable as the result of a 'malloc' call), GDB may not stop until the +next time the expression changes. + + Depending on your system, watchpoints may be implemented in software +or hardware. GDB does software watchpointing by single-stepping your +program and testing the variable's value each time, which is hundreds of +times slower than normal execution. (But this may still be worth it, to +catch errors where you have no clue what part of your program is the +culprit.) + + On some systems, such as HP-UX, PowerPC, GNU/Linux and most other +x86-based targets, GDB includes support for hardware watchpoints, which +do not slow down the running of your program. + +'watch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]' + Set a watchpoint for an expression. GDB will break when the + expression EXPR is written into by the program and its value + changes. The simplest (and the most popular) use of this command + is to watch the value of a single variable: + + (gdb) watch foo + + If the command includes a '[thread THREADNUM]' argument, GDB breaks + only when the thread identified by THREADNUM changes the value of + EXPR. If any other threads change the value of EXPR, GDB will not + break. Note that watchpoints restricted to a single thread in this + way only work with Hardware Watchpoints. + + Ordinarily a watchpoint respects the scope of variables in EXPR + (see below). The '-location' argument tells GDB to instead watch + the memory referred to by EXPR. In this case, GDB will evaluate + EXPR, take the address of the result, and watch the memory at that + address. The type of the result is used to determine the size of + the watched memory. If the expression's result does not have an + address, then GDB will print an error. + + The '[mask MASKVALUE]' argument allows creation of masked + watchpoints, if the current architecture supports this feature + (e.g., PowerPC Embedded architecture, see *note PowerPC + Embedded::.) A "masked watchpoint" specifies a mask in addition to + an address to watch. The mask specifies that some bits of an + address (the bits which are reset in the mask) should be ignored + when matching the address accessed by the inferior against the + watchpoint address. Thus, a masked watchpoint watches many + addresses simultaneously--those addresses whose unmasked bits are + identical to the unmasked bits in the watchpoint address. The + 'mask' argument implies '-location'. Examples: + + (gdb) watch foo mask 0xffff00ff + (gdb) watch *0xdeadbeef mask 0xffffff00 + +'rwatch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]' + Set a watchpoint that will break when the value of EXPR is read by + the program. + +'awatch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]' + Set a watchpoint that will break when EXPR is either read from or + written into by the program. + +'info watchpoints [N...]' + This command prints a list of watchpoints, using the same format as + 'info break' (*note Set Breaks::). + + If you watch for a change in a numerically entered address you need +to dereference it, as the address itself is just a constant number which +will never change. GDB refuses to create a watchpoint that watches a +never-changing value: + + (gdb) watch 0x600850 + Cannot watch constant value 0x600850. + (gdb) watch *(int *) 0x600850 + Watchpoint 1: *(int *) 6293584 + + GDB sets a "hardware watchpoint" if possible. Hardware watchpoints +execute very quickly, and the debugger reports a change in value at the +exact instruction where the change occurs. If GDB cannot set a hardware +watchpoint, it sets a software watchpoint, which executes more slowly +and reports the change in value at the next _statement_, not the +instruction, after the change occurs. + + You can force GDB to use only software watchpoints with the 'set +can-use-hw-watchpoints 0' command. With this variable set to zero, GDB +will never try to use hardware watchpoints, even if the underlying +system supports them. (Note that hardware-assisted watchpoints that +were set _before_ setting 'can-use-hw-watchpoints' to zero will still +use the hardware mechanism of watching expression values.) + +'set can-use-hw-watchpoints' + Set whether or not to use hardware watchpoints. + +'show can-use-hw-watchpoints' + Show the current mode of using hardware watchpoints. + + For remote targets, you can restrict the number of hardware +watchpoints GDB will use, see *note set remote +hardware-breakpoint-limit::. + + When you issue the 'watch' command, GDB reports + + Hardware watchpoint NUM: EXPR + +if it was able to set a hardware watchpoint. + + Currently, the 'awatch' and 'rwatch' commands can only set hardware +watchpoints, because accesses to data that don't change the value of the +watched expression cannot be detected without examining every +instruction as it is being executed, and GDB does not do that currently. +If GDB finds that it is unable to set a hardware breakpoint with the +'awatch' or 'rwatch' command, it will print a message like this: + + Expression cannot be implemented with read/access watchpoint. + + Sometimes, GDB cannot set a hardware watchpoint because the data type +of the watched expression is wider than what a hardware watchpoint on +the target machine can handle. For example, some systems can only watch +regions that are up to 4 bytes wide; on such systems you cannot set +hardware watchpoints for an expression that yields a double-precision +floating-point number (which is typically 8 bytes wide). As a +work-around, it might be possible to break the large region into a +series of smaller ones and watch them with separate watchpoints. + + If you set too many hardware watchpoints, GDB might be unable to +insert all of them when you resume the execution of your program. Since +the precise number of active watchpoints is unknown until such time as +the program is about to be resumed, GDB might not be able to warn you +about this when you set the watchpoints, and the warning will be printed +only when the program is resumed: + + Hardware watchpoint NUM: Could not insert watchpoint + +If this happens, delete or disable some of the watchpoints. + + Watching complex expressions that reference many variables can also +exhaust the resources available for hardware-assisted watchpoints. +That's because GDB needs to watch every variable in the expression with +separately allocated resources. + + If you call a function interactively using 'print' or 'call', any +watchpoints you have set will be inactive until GDB reaches another kind +of breakpoint or the call completes. + + GDB automatically deletes watchpoints that watch local (automatic) +variables, or expressions that involve such variables, when they go out +of scope, that is, when the execution leaves the block in which these +variables were defined. In particular, when the program being debugged +terminates, _all_ local variables go out of scope, and so only +watchpoints that watch global variables remain set. If you rerun the +program, you will need to set all such watchpoints again. One way of +doing that would be to set a code breakpoint at the entry to the 'main' +function and when it breaks, set all the watchpoints. + + In multi-threaded programs, watchpoints will detect changes to the +watched expression from every thread. + + _Warning:_ In multi-threaded programs, software watchpoints have + only limited usefulness. If GDB creates a software watchpoint, it + can only watch the value of an expression _in a single thread_. If + you are confident that the expression can only change due to the + current thread's activity (and if you are also confident that no + other thread can become current), then you can use software + watchpoints as usual. However, GDB may not notice when a + non-current thread's activity changes the expression. (Hardware + watchpoints, in contrast, watch an expression in all threads.) + + *Note set remote hardware-watchpoint-limit::. + + +File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints + +5.1.3 Setting Catchpoints +------------------------- + +You can use "catchpoints" to cause the debugger to stop for certain +kinds of program events, such as C++ exceptions or the loading of a +shared library. Use the 'catch' command to set a catchpoint. + +'catch EVENT' + Stop when EVENT occurs. EVENT can be any of the following: + + 'throw [REGEXP]' + 'rethrow [REGEXP]' + 'catch [REGEXP]' + The throwing, re-throwing, or catching of a C++ exception. + + If REGEXP is given, then only exceptions whose type matches + the regular expression will be caught. + + The convenience variable '$_exception' is available at an + exception-related catchpoint, on some systems. This holds the + exception being thrown. + + There are currently some limitations to C++ exception handling + in GDB: + + * The support for these commands is system-dependent. + Currently, only systems using the 'gnu-v3' C++ ABI (*note + ABI::) are supported. + + * The regular expression feature and the '$_exception' + convenience variable rely on the presence of some SDT + probes in 'libstdc++'. If these probes are not present, + then these features cannot be used. These probes were + first available in the GCC 4.8 release, but whether or + not they are available in your GCC also depends on how it + was built. + + * The '$_exception' convenience variable is only valid at + the instruction at which an exception-related catchpoint + is set. + + * When an exception-related catchpoint is hit, GDB stops at + a location in the system library which implements runtime + exception support for C++, usually 'libstdc++'. You can + use 'up' (*note Selection::) to get to your code. + + * If you call a function interactively, GDB normally + returns control to you when the function has finished + executing. If the call raises an exception, however, the + call may bypass the mechanism that returns control to you + and cause your program either to abort or to simply + continue running until it hits a breakpoint, catches a + signal that GDB is listening for, or exits. This is the + case even if you set a catchpoint for the exception; + catchpoints on exceptions are disabled within interactive + calls. *Note Calling::, for information on controlling + this with 'set unwind-on-terminating-exception'. + + * You cannot raise an exception interactively. + + * You cannot install an exception handler interactively. + + 'exception' + An Ada exception being raised. If an exception name is + specified at the end of the command (eg 'catch exception + Program_Error'), the debugger will stop only when this + specific exception is raised. Otherwise, the debugger stops + execution when any Ada exception is raised. + + When inserting an exception catchpoint on a user-defined + exception whose name is identical to one of the exceptions + defined by the language, the fully qualified name must be used + as the exception name. Otherwise, GDB will assume that it + should stop on the pre-defined exception rather than the + user-defined one. For instance, assuming an exception called + 'Constraint_Error' is defined in package 'Pck', then the + command to use to catch such exceptions is 'catch exception + Pck.Constraint_Error'. + + 'exception unhandled' + An exception that was raised but is not handled by the + program. + + 'assert' + A failed Ada assertion. + + 'exec' + A call to 'exec'. This is currently only available for HP-UX + and GNU/Linux. + + 'syscall' + 'syscall [NAME | NUMBER] ...' + A call to or return from a system call, a.k.a. "syscall". A + syscall is a mechanism for application programs to request a + service from the operating system (OS) or one of the OS system + services. GDB can catch some or all of the syscalls issued by + the debuggee, and show the related information for each + syscall. If no argument is specified, calls to and returns + from all system calls will be caught. + + NAME can be any system call name that is valid for the + underlying OS. Just what syscalls are valid depends on the OS. + On GNU and Unix systems, you can find the full list of valid + syscall names on '/usr/include/asm/unistd.h'. + + Normally, GDB knows in advance which syscalls are valid for + each OS, so you can use the GDB command-line completion + facilities (*note command completion: Completion.) to list the + available choices. + + You may also specify the system call numerically. A syscall's + number is the value passed to the OS's syscall dispatcher to + identify the requested service. When you specify the syscall + by its name, GDB uses its database of syscalls to convert the + name into the corresponding numeric code, but using the number + directly may be useful if GDB's database does not have the + complete list of syscalls on your system (e.g., because GDB + lags behind the OS upgrades). + + The example below illustrates how this command works if you + don't provide arguments to it: + + (gdb) catch syscall + Catchpoint 1 (syscall) + (gdb) r + Starting program: /tmp/catch-syscall + + Catchpoint 1 (call to syscall 'close'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) c + Continuing. + + Catchpoint 1 (returned from syscall 'close'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) + + Here is an example of catching a system call by name: + + (gdb) catch syscall chroot + Catchpoint 1 (syscall 'chroot' [61]) + (gdb) r + Starting program: /tmp/catch-syscall + + Catchpoint 1 (call to syscall 'chroot'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) c + Continuing. + + Catchpoint 1 (returned from syscall 'chroot'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) + + An example of specifying a system call numerically. In the + case below, the syscall number has a corresponding entry in + the XML file, so GDB finds its name and prints it: + + (gdb) catch syscall 252 + Catchpoint 1 (syscall(s) 'exit_group') + (gdb) r + Starting program: /tmp/catch-syscall + + Catchpoint 1 (call to syscall 'exit_group'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) c + Continuing. + + Program exited normally. + (gdb) + + However, there can be situations when there is no + corresponding name in XML file for that syscall number. In + this case, GDB prints a warning message saying that it was not + able to find the syscall name, but the catchpoint will be set + anyway. See the example below: + + (gdb) catch syscall 764 + warning: The number '764' does not represent a known syscall. + Catchpoint 2 (syscall 764) + (gdb) + + If you configure GDB using the '--without-expat' option, it + will not be able to display syscall names. Also, if your + architecture does not have an XML file describing its system + calls, you will not be able to see the syscall names. It is + important to notice that these two features are used for + accessing the syscall name database. In either case, you will + see a warning like this: + + (gdb) catch syscall + warning: Could not open "syscalls/i386-linux.xml" + warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. + GDB will not be able to display syscall names. + Catchpoint 1 (syscall) + (gdb) + + Of course, the file name will change depending on your + architecture and system. + + Still using the example above, you can also try to catch a + syscall by its number. In this case, you would see something + like: + + (gdb) catch syscall 252 + Catchpoint 1 (syscall(s) 252) + + Again, in this case GDB would not be able to display syscall's + names. + + 'fork' + A call to 'fork'. This is currently only available for HP-UX + and GNU/Linux. + + 'vfork' + A call to 'vfork'. This is currently only available for HP-UX + and GNU/Linux. + + 'load [regexp]' + 'unload [regexp]' + The loading or unloading of a shared library. If REGEXP is + given, then the catchpoint will stop only if the regular + expression matches one of the affected libraries. + + 'signal [SIGNAL... | 'all']' + The delivery of a signal. + + With no arguments, this catchpoint will catch any signal that + is not used internally by GDB, specifically, all signals + except 'SIGTRAP' and 'SIGINT'. + + With the argument 'all', all signals, including those used by + GDB, will be caught. This argument cannot be used with other + signal names. + + Otherwise, the arguments are a list of signal names as given + to 'handle' (*note Signals::). Only signals specified in this + list will be caught. + + One reason that 'catch signal' can be more useful than + 'handle' is that you can attach commands and conditions to the + catchpoint. + + When a signal is caught by a catchpoint, the signal's 'stop' + and 'print' settings, as specified by 'handle', are ignored. + However, whether the signal is still delivered to the inferior + depends on the 'pass' setting; this can be changed in the + catchpoint's commands. + +'tcatch EVENT' + Set a catchpoint that is enabled only for one stop. The catchpoint + is automatically deleted after the first time the event is caught. + + Use the 'info break' command to list the current catchpoints. + + +File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints + +5.1.4 Deleting Breakpoints +-------------------------- + +It is often necessary to eliminate a breakpoint, watchpoint, or +catchpoint once it has done its job and you no longer want your program +to stop there. This is called "deleting" the breakpoint. A breakpoint +that has been deleted no longer exists; it is forgotten. + + With the 'clear' command you can delete breakpoints according to +where they are in your program. With the 'delete' command you can +delete individual breakpoints, watchpoints, or catchpoints by specifying +their breakpoint numbers. + + It is not necessary to delete a breakpoint to proceed past it. GDB +automatically ignores breakpoints on the first instruction to be +executed when you continue execution without changing the execution +address. + +'clear' + Delete any breakpoints at the next instruction to be executed in + the selected stack frame (*note Selecting a Frame: Selection.). + When the innermost frame is selected, this is a good way to delete + a breakpoint where your program just stopped. + +'clear LOCATION' + Delete any breakpoints set at the specified LOCATION. *Note + Specify Location::, for the various forms of LOCATION; the most + useful ones are listed below: + + 'clear FUNCTION' + 'clear FILENAME:FUNCTION' + Delete any breakpoints set at entry to the named FUNCTION. + + 'clear LINENUM' + 'clear FILENAME:LINENUM' + Delete any breakpoints set at or within the code of the + specified LINENUM of the specified FILENAME. + +'delete [breakpoints] [RANGE...]' + Delete the breakpoints, watchpoints, or catchpoints of the + breakpoint ranges specified as arguments. If no argument is + specified, delete all breakpoints (GDB asks confirmation, unless + you have 'set confirm off'). You can abbreviate this command as + 'd'. + + +File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints + +5.1.5 Disabling Breakpoints +--------------------------- + +Rather than deleting a breakpoint, watchpoint, or catchpoint, you might +prefer to "disable" it. This makes the breakpoint inoperative as if it +had been deleted, but remembers the information on the breakpoint so +that you can "enable" it again later. + + You disable and enable breakpoints, watchpoints, and catchpoints with +the 'enable' and 'disable' commands, optionally specifying one or more +breakpoint numbers as arguments. Use 'info break' to print a list of +all breakpoints, watchpoints, and catchpoints if you do not know which +numbers to use. + + Disabling and enabling a breakpoint that has multiple locations +affects all of its locations. + + A breakpoint, watchpoint, or catchpoint can have any of several +different states of enablement: + + * Enabled. The breakpoint stops your program. A breakpoint set with + the 'break' command starts out in this state. + * Disabled. The breakpoint has no effect on your program. + * Enabled once. The breakpoint stops your program, but then becomes + disabled. + * Enabled for a count. The breakpoint stops your program for the + next N times, then becomes disabled. + * Enabled for deletion. The breakpoint stops your program, but + immediately after it does so it is deleted permanently. A + breakpoint set with the 'tbreak' command starts out in this state. + + You can use the following commands to enable or disable breakpoints, +watchpoints, and catchpoints: + +'disable [breakpoints] [RANGE...]' + Disable the specified breakpoints--or all breakpoints, if none are + listed. A disabled breakpoint has no effect but is not forgotten. + All options such as ignore-counts, conditions and commands are + remembered in case the breakpoint is enabled again later. You may + abbreviate 'disable' as 'dis'. + +'enable [breakpoints] [RANGE...]' + Enable the specified breakpoints (or all defined breakpoints). + They become effective once again in stopping your program. + +'enable [breakpoints] once RANGE...' + Enable the specified breakpoints temporarily. GDB disables any of + these breakpoints immediately after stopping your program. + +'enable [breakpoints] count COUNT RANGE...' + Enable the specified breakpoints temporarily. GDB records COUNT + with each of the specified breakpoints, and decrements a + breakpoint's count when it is hit. When any count reaches 0, GDB + disables that breakpoint. If a breakpoint has an ignore count + (*note Break Conditions: Conditions.), that will be decremented to + 0 before COUNT is affected. + +'enable [breakpoints] delete RANGE...' + Enable the specified breakpoints to work once, then die. GDB + deletes any of these breakpoints as soon as your program stops + there. Breakpoints set by the 'tbreak' command start out in this + state. + + Except for a breakpoint set with 'tbreak' (*note Setting Breakpoints: +Set Breaks.), breakpoints that you set are initially enabled; +subsequently, they become disabled or enabled only when you use one of +the commands above. (The command 'until' can set and delete a +breakpoint of its own, but it does not change the state of your other +breakpoints; see *note Continuing and Stepping: Continuing and +Stepping.) + + +File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints + +5.1.6 Break Conditions +---------------------- + +The simplest sort of breakpoint breaks every time your program reaches a +specified place. You can also specify a "condition" for a breakpoint. +A condition is just a Boolean expression in your programming language +(*note Expressions: Expressions.). A breakpoint with a condition +evaluates the expression each time your program reaches it, and your +program stops only if the condition is _true_. + + This is the converse of using assertions for program validation; in +that situation, you want to stop when the assertion is violated--that +is, when the condition is false. In C, if you want to test an assertion +expressed by the condition ASSERT, you should set the condition '! +ASSERT' on the appropriate breakpoint. + + Conditions are also accepted for watchpoints; you may not need them, +since a watchpoint is inspecting the value of an expression anyhow--but +it might be simpler, say, to just set a watchpoint on a variable name, +and specify a condition that tests whether the new value is an +interesting one. + + Break conditions can have side effects, and may even call functions +in your program. This can be useful, for example, to activate functions +that log program progress, or to use your own print functions to format +special data structures. The effects are completely predictable unless +there is another enabled breakpoint at the same address. (In that case, +GDB might see the other breakpoint first and stop your program without +checking the condition of this one.) Note that breakpoint commands are +usually more convenient and flexible than break conditions for the +purpose of performing side effects when a breakpoint is reached (*note +Breakpoint Command Lists: Break Commands.). + + Breakpoint conditions can also be evaluated on the target's side if +the target supports it. Instead of evaluating the conditions locally, +GDB encodes the expression into an agent expression (*note Agent +Expressions::) suitable for execution on the target, independently of +GDB. Global variables become raw memory locations, locals become stack +accesses, and so forth. + + In this case, GDB will only be notified of a breakpoint trigger when +its condition evaluates to true. This mechanism may provide faster +response times depending on the performance characteristics of the +target since it does not need to keep GDB informed about every +breakpoint trigger, even those with false conditions. + + Break conditions can be specified when a breakpoint is set, by using +'if' in the arguments to the 'break' command. *Note Setting +Breakpoints: Set Breaks. They can also be changed at any time with the +'condition' command. + + You can also use the 'if' keyword with the 'watch' command. The +'catch' command does not recognize the 'if' keyword; 'condition' is the +only way to impose a further condition on a catchpoint. + +'condition BNUM EXPRESSION' + Specify EXPRESSION as the break condition for breakpoint, + watchpoint, or catchpoint number BNUM. After you set a condition, + breakpoint BNUM stops your program only if the value of EXPRESSION + is true (nonzero, in C). When you use 'condition', GDB checks + EXPRESSION immediately for syntactic correctness, and to determine + whether symbols in it have referents in the context of your + breakpoint. If EXPRESSION uses symbols not referenced in the + context of the breakpoint, GDB prints an error message: + + No symbol "foo" in current context. + + GDB does not actually evaluate EXPRESSION at the time the + 'condition' command (or a command that sets a breakpoint with a + condition, like 'break if ...') is given, however. *Note + Expressions: Expressions. + +'condition BNUM' + Remove the condition from breakpoint number BNUM. It becomes an + ordinary unconditional breakpoint. + + A special case of a breakpoint condition is to stop only when the +breakpoint has been reached a certain number of times. This is so +useful that there is a special way to do it, using the "ignore count" of +the breakpoint. Every breakpoint has an ignore count, which is an +integer. Most of the time, the ignore count is zero, and therefore has +no effect. But if your program reaches a breakpoint whose ignore count +is positive, then instead of stopping, it just decrements the ignore +count by one and continues. As a result, if the ignore count value is +N, the breakpoint does not stop the next N times your program reaches +it. + +'ignore BNUM COUNT' + Set the ignore count of breakpoint number BNUM to COUNT. The next + COUNT times the breakpoint is reached, your program's execution + does not stop; other than to decrement the ignore count, GDB takes + no action. + + To make the breakpoint stop the next time it is reached, specify a + count of zero. + + When you use 'continue' to resume execution of your program from a + breakpoint, you can specify an ignore count directly as an argument + to 'continue', rather than using 'ignore'. *Note Continuing and + Stepping: Continuing and Stepping. + + If a breakpoint has a positive ignore count and a condition, the + condition is not checked. Once the ignore count reaches zero, GDB + resumes checking the condition. + + You could achieve the effect of the ignore count with a condition + such as '$foo-- <= 0' using a debugger convenience variable that is + decremented each time. *Note Convenience Variables: Convenience + Vars. + + Ignore counts apply to breakpoints, watchpoints, and catchpoints. + + +File: gdb.info, Node: Break Commands, Next: Dynamic Printf, Prev: Conditions, Up: Breakpoints + +5.1.7 Breakpoint Command Lists +------------------------------ + +You can give any breakpoint (or watchpoint or catchpoint) a series of +commands to execute when your program stops due to that breakpoint. For +example, you might want to print the values of certain expressions, or +enable other breakpoints. + +'commands [RANGE...]' +'... COMMAND-LIST ...' +'end' + Specify a list of commands for the given breakpoints. The commands + themselves appear on the following lines. Type a line containing + just 'end' to terminate the commands. + + To remove all commands from a breakpoint, type 'commands' and + follow it immediately with 'end'; that is, give no commands. + + With no argument, 'commands' refers to the last breakpoint, + watchpoint, or catchpoint set (not to the breakpoint most recently + encountered). If the most recent breakpoints were set with a + single command, then the 'commands' will apply to all the + breakpoints set by that command. This applies to breakpoints set + by 'rbreak', and also applies when a single 'break' command creates + multiple breakpoints (*note Ambiguous Expressions: Ambiguous + Expressions.). + + Pressing as a means of repeating the last GDB command is +disabled within a COMMAND-LIST. + + You can use breakpoint commands to start your program up again. +Simply use the 'continue' command, or 'step', or any other command that +resumes execution. + + Any other commands in the command list, after a command that resumes +execution, are ignored. This is because any time you resume execution +(even with a simple 'next' or 'step'), you may encounter another +breakpoint--which could have its own command list, leading to +ambiguities about which list to execute. + + If the first command you specify in a command list is 'silent', the +usual message about stopping at a breakpoint is not printed. This may +be desirable for breakpoints that are to print a specific message and +then continue. If none of the remaining commands print anything, you +see no sign that the breakpoint was reached. 'silent' is meaningful +only at the beginning of a breakpoint command list. + + The commands 'echo', 'output', and 'printf' allow you to print +precisely controlled output, and are often useful in silent breakpoints. +*Note Commands for Controlled Output: Output. + + For example, here is how you could use breakpoint commands to print +the value of 'x' at entry to 'foo' whenever 'x' is positive. + + break foo if x>0 + commands + silent + printf "x is %d\n",x + cont + end + + One application for breakpoint commands is to compensate for one bug +so you can test for another. Put a breakpoint just after the erroneous +line of code, give it a condition to detect the case in which something +erroneous has been done, and give it commands to assign correct values +to any variables that need them. End with the 'continue' command so +that your program does not stop, and start with the 'silent' command so +that no output is produced. Here is an example: + + break 403 + commands + silent + set x = y + 4 + cont + end + + +File: gdb.info, Node: Dynamic Printf, Next: Save Breakpoints, Prev: Break Commands, Up: Breakpoints + +5.1.8 Dynamic Printf +-------------------- + +The dynamic printf command 'dprintf' combines a breakpoint with +formatted printing of your program's data to give you the effect of +inserting 'printf' calls into your program on-the-fly, without having to +recompile it. + + In its most basic form, the output goes to the GDB console. However, +you can set the variable 'dprintf-style' for alternate handling. For +instance, you can ask to format the output by calling your program's +'printf' function. This has the advantage that the characters go to the +program's output device, so they can recorded in redirects to files and +so forth. + + If you are doing remote debugging with a stub or agent, you can also +ask to have the printf handled by the remote agent. In addition to +ensuring that the output goes to the remote program's device along with +any other output the program might produce, you can also ask that the +dprintf remain active even after disconnecting from the remote target. +Using the stub/agent is also more efficient, as it can do everything +without needing to communicate with GDB. + +'dprintf LOCATION,TEMPLATE,EXPRESSION[,EXPRESSION...]' + Whenever execution reaches LOCATION, print the values of one or + more EXPRESSIONS under the control of the string TEMPLATE. To + print several values, separate them with commas. + +'set dprintf-style STYLE' + Set the dprintf output to be handled in one of several different + styles enumerated below. A change of style affects all existing + dynamic printfs immediately. (If you need individual control over + the print commands, simply define normal breakpoints with + explicitly-supplied command lists.) + +'gdb' + Handle the output using the GDB 'printf' command. + +'call' + Handle the output by calling a function in your program (normally + 'printf'). + +'agent' + Have the remote debugging agent (such as 'gdbserver') handle the + output itself. This style is only available for agents that + support running commands on the target. + +'set dprintf-function FUNCTION' + Set the function to call if the dprintf style is 'call'. By + default its value is 'printf'. You may set it to any expression. + that GDB can evaluate to a function, as per the 'call' command. + +'set dprintf-channel CHANNEL' + Set a "channel" for dprintf. If set to a non-empty value, GDB will + evaluate it as an expression and pass the result as a first + argument to the 'dprintf-function', in the manner of 'fprintf' and + similar functions. Otherwise, the dprintf format string will be + the first argument, in the manner of 'printf'. + + As an example, if you wanted 'dprintf' output to go to a logfile + that is a standard I/O stream assigned to the variable 'mylog', you + could do the following: + + (gdb) set dprintf-style call + (gdb) set dprintf-function fprintf + (gdb) set dprintf-channel mylog + (gdb) dprintf 25,"at line 25, glob=%d\n",glob + Dprintf 1 at 0x123456: file main.c, line 25. + (gdb) info break + 1 dprintf keep y 0x00123456 in main at main.c:25 + call (void) fprintf (mylog,"at line 25, glob=%d\n",glob) + continue + (gdb) + + Note that the 'info break' displays the dynamic printf commands as + normal breakpoint commands; you can thus easily see the effect of + the variable settings. + +'set disconnected-dprintf on' +'set disconnected-dprintf off' + Choose whether 'dprintf' commands should continue to run if GDB has + disconnected from the target. This only applies if the + 'dprintf-style' is 'agent'. + +'show disconnected-dprintf off' + Show the current choice for disconnected 'dprintf'. + + GDB does not check the validity of function and channel, relying on +you to supply values that are meaningful for the contexts in which they +are being used. For instance, the function and channel may be the +values of local variables, but if that is the case, then all enabled +dynamic prints must be at locations within the scope of those locals. +If evaluation fails, GDB will report an error. + + +File: gdb.info, Node: Save Breakpoints, Next: Static Probe Points, Prev: Dynamic Printf, Up: Breakpoints + +5.1.9 How to save breakpoints to a file +--------------------------------------- + +To save breakpoint definitions to a file use the 'save breakpoints' +command. + +'save breakpoints [FILENAME]' + This command saves all current breakpoint definitions together with + their commands and ignore counts, into a file 'FILENAME' suitable + for use in a later debugging session. This includes all types of + breakpoints (breakpoints, watchpoints, catchpoints, tracepoints). + To read the saved breakpoint definitions, use the 'source' command + (*note Command Files::). Note that watchpoints with expressions + involving local variables may fail to be recreated because it may + not be possible to access the context where the watchpoint is valid + anymore. Because the saved breakpoint definitions are simply a + sequence of GDB commands that recreate the breakpoints, you can + edit the file in your favorite editing program, and remove the + breakpoint definitions you're not interested in, or that can no + longer be recreated. + + +File: gdb.info, Node: Static Probe Points, Next: Error in Breakpoints, Prev: Save Breakpoints, Up: Breakpoints + +5.1.10 Static Probe Points +-------------------------- + +GDB supports "SDT" probes in the code. SDT stands for Statically +Defined Tracing, and the probes are designed to have a tiny runtime code +and data footprint, and no dynamic relocations. They are usable from +assembly, C and C++ languages. See + for +a good reference on how the SDT probes are implemented. + + Currently, 'SystemTap' () SDT +probes are supported on ELF-compatible systems. See + for +more information on how to add 'SystemTap' SDT probes in your +applications. + + Some probes have an associated semaphore variable; for instance, this +happens automatically if you defined your probe using a DTrace-style +'.d' file. If your probe has a semaphore, GDB will automatically enable +it when you specify a breakpoint using the '-probe-stap' notation. But, +if you put a breakpoint at a probe's location by some other method +(e.g., 'break file:line'), then GDB will not automatically set the +semaphore. + + You can examine the available static static probes using 'info +probes', with optional arguments: + +'info probes stap [PROVIDER [NAME [OBJFILE]]]' + If given, PROVIDER is a regular expression used to match against + provider names when selecting which probes to list. If omitted, + probes by all probes from all providers are listed. + + If given, NAME is a regular expression to match against probe names + when selecting which probes to list. If omitted, probe names are + not considered when deciding whether to display them. + + If given, OBJFILE is a regular expression used to select which + object files (executable or shared libraries) to examine. If not + given, all object files are considered. + +'info probes all' + List the available static probes, from all types. + + A probe may specify up to twelve arguments. These are available at +the point at which the probe is defined--that is, when the current PC is +at the probe's location. The arguments are available using the +convenience variables (*note Convenience Vars::) +'$_probe_arg0'...'$_probe_arg11'. Each probe argument is an integer of +the appropriate size; types are not preserved. The convenience variable +'$_probe_argc' holds the number of arguments at the current probe point. + + These variables are always available, but attempts to access them at +any location other than a probe point will cause GDB to give an error +message. + + +File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Static Probe Points, Up: Breakpoints + +5.1.11 "Cannot insert breakpoints" +---------------------------------- + +If you request too many active hardware-assisted breakpoints and +watchpoints, you will see this error message: + + Stopped; cannot insert breakpoints. + You may have requested too many hardware breakpoints and watchpoints. + +This message is printed when you attempt to resume the program, since +only then GDB knows exactly how many hardware breakpoints and +watchpoints it needs to insert. + + When this message is printed, you need to disable or remove some of +the hardware-assisted breakpoints and watchpoints, and then continue. + + +File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints + +5.1.12 "Breakpoint address adjusted..." +--------------------------------------- + +Some processor architectures place constraints on the addresses at which +breakpoints may be placed. For architectures thus constrained, GDB will +attempt to adjust the breakpoint's address to comply with the +constraints dictated by the architecture. + + One example of such an architecture is the Fujitsu FR-V. The FR-V is +a VLIW architecture in which a number of RISC-like instructions may be +bundled together for parallel execution. The FR-V architecture +constrains the location of a breakpoint instruction within such a bundle +to the instruction with the lowest address. GDB honors this constraint +by adjusting a breakpoint's address to the first in the bundle. + + It is not uncommon for optimized code to have bundles which contain +instructions from different source statements, thus it may happen that a +breakpoint's address will be adjusted from one source statement to +another. Since this adjustment may significantly alter GDB's breakpoint +related behavior from what the user expects, a warning is printed when +the breakpoint is first set and also when the breakpoint is hit. + + A warning like the one below is printed when setting a breakpoint +that's been subject to address adjustment: + + warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. + + Such warnings are printed both for user settable and GDB's internal +breakpoints. If you see one of these warnings, you should verify that a +breakpoint set at the adjusted address will have the desired affect. If +not, the breakpoint in question may be removed and other breakpoints may +be set which will have the desired behavior. E.g., it may be sufficient +to place the breakpoint at a later instruction. A conditional +breakpoint may also be useful in some cases to prevent the breakpoint +from triggering too often. + + GDB will also issue a warning when stopping at one of these adjusted +breakpoints: + + warning: Breakpoint 1 address previously adjusted from 0x00010414 + to 0x00010410. + + When this warning is encountered, it may be too late to take remedial +action except in cases where the breakpoint is hit earlier or more +frequently than expected. + + +File: gdb.info, Node: Continuing and Stepping, Next: Skipping Over Functions and Files, Prev: Breakpoints, Up: Stopping + +5.2 Continuing and Stepping +=========================== + +"Continuing" means resuming program execution until your program +completes normally. In contrast, "stepping" means executing just one +more "step" of your program, where "step" may mean either one line of +source code, or one machine instruction (depending on what particular +command you use). Either when continuing or when stepping, your program +may stop even sooner, due to a breakpoint or a signal. (If it stops due +to a signal, you may want to use 'handle', or use 'signal 0' to resume +execution. *Note Signals: Signals.) + +'continue [IGNORE-COUNT]' +'c [IGNORE-COUNT]' +'fg [IGNORE-COUNT]' + Resume program execution, at the address where your program last + stopped; any breakpoints set at that address are bypassed. The + optional argument IGNORE-COUNT allows you to specify a further + number of times to ignore a breakpoint at this location; its effect + is like that of 'ignore' (*note Break Conditions: Conditions.). + + The argument IGNORE-COUNT is meaningful only when your program + stopped due to a breakpoint. At other times, the argument to + 'continue' is ignored. + + The synonyms 'c' and 'fg' (for "foreground", as the debugged + program is deemed to be the foreground program) are provided purely + for convenience, and have exactly the same behavior as 'continue'. + + To resume execution at a different place, you can use 'return' (*note +Returning from a Function: Returning.) to go back to the calling +function; or 'jump' (*note Continuing at a Different Address: Jumping.) +to go to an arbitrary location in your program. + + A typical technique for using stepping is to set a breakpoint (*note +Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the +beginning of the function or the section of your program where a problem +is believed to lie, run your program until it stops at that breakpoint, +and then step through the suspect area, examining the variables that are +interesting, until you see the problem happen. + +'step' + Continue running your program until control reaches a different + source line, then stop it and return control to GDB. This command + is abbreviated 's'. + + _Warning:_ If you use the 'step' command while control is + within a function that was compiled without debugging + information, execution proceeds until control reaches a + function that does have debugging information. Likewise, it + will not step into a function which is compiled without + debugging information. To step through functions without + debugging information, use the 'stepi' command, described + below. + + The 'step' command only stops at the first instruction of a source + line. This prevents the multiple stops that could otherwise occur + in 'switch' statements, 'for' loops, etc. 'step' continues to stop + if a function that has debugging information is called within the + line. In other words, 'step' _steps inside_ any functions called + within the line. + + Also, the 'step' command only enters a function if there is line + number information for the function. Otherwise it acts like the + 'next' command. This avoids problems when using 'cc -gl' on MIPS + machines. Previously, 'step' entered subroutines if there was any + debugging information about the routine. + +'step COUNT' + Continue running as in 'step', but do so COUNT times. If a + breakpoint is reached, or a signal not related to stepping occurs + before COUNT steps, stepping stops right away. + +'next [COUNT]' + Continue to the next source line in the current (innermost) stack + frame. This is similar to 'step', but function calls that appear + within the line of code are executed without stopping. Execution + stops when control reaches a different line of code at the original + stack level that was executing when you gave the 'next' command. + This command is abbreviated 'n'. + + An argument COUNT is a repeat count, as for 'step'. + + The 'next' command only stops at the first instruction of a source + line. This prevents multiple stops that could otherwise occur in + 'switch' statements, 'for' loops, etc. + +'set step-mode' +'set step-mode on' + The 'set step-mode on' command causes the 'step' command to stop at + the first instruction of a function which contains no debug line + information rather than stepping over it. + + This is useful in cases where you may be interested in inspecting + the machine instructions of a function which has no symbolic info + and do not want GDB to automatically skip over this function. + +'set step-mode off' + Causes the 'step' command to step over any functions which contains + no debug information. This is the default. + +'show step-mode' + Show whether GDB will stop in or step over functions without source + line debug information. + +'finish' + Continue running until just after function in the selected stack + frame returns. Print the returned value (if any). This command + can be abbreviated as 'fin'. + + Contrast this with the 'return' command (*note Returning from a + Function: Returning.). + +'until' +'u' + Continue running until a source line past the current line, in the + current stack frame, is reached. This command is used to avoid + single stepping through a loop more than once. It is like the + 'next' command, except that when 'until' encounters a jump, it + automatically continues execution until the program counter is + greater than the address of the jump. + + This means that when you reach the end of a loop after single + stepping though it, 'until' makes your program continue execution + until it exits the loop. In contrast, a 'next' command at the end + of a loop simply steps back to the beginning of the loop, which + forces you to step through the next iteration. + + 'until' always stops your program if it attempts to exit the + current stack frame. + + 'until' may produce somewhat counterintuitive results if the order + of machine code does not match the order of the source lines. For + example, in the following excerpt from a debugging session, the 'f' + ('frame') command shows that execution is stopped at line '206'; + yet when we use 'until', we get to line '195': + + (gdb) f + #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 + 206 expand_input(); + (gdb) until + 195 for ( ; argc > 0; NEXTARG) { + + This happened because, for execution efficiency, the compiler had + generated code for the loop closure test at the end, rather than + the start, of the loop--even though the test in a C 'for'-loop is + written before the body of the loop. The 'until' command appeared + to step back to the beginning of the loop when it advanced to this + expression; however, it has not really gone to an earlier + statement--not in terms of the actual machine code. + + 'until' with no argument works by means of single instruction + stepping, and hence is slower than 'until' with an argument. + +'until LOCATION' +'u LOCATION' + Continue running your program until either the specified location + is reached, or the current stack frame returns. LOCATION is any of + the forms described in *note Specify Location::. This form of the + command uses temporary breakpoints, and hence is quicker than + 'until' without an argument. The specified location is actually + reached only if it is in the current frame. This implies that + 'until' can be used to skip over recursive function invocations. + For instance in the code below, if the current location is line + '96', issuing 'until 99' will execute the program up to line '99' + in the same invocation of factorial, i.e., after the inner + invocations have returned. + + 94 int factorial (int value) + 95 { + 96 if (value > 1) { + 97 value *= factorial (value - 1); + 98 } + 99 return (value); + 100 } + +'advance LOCATION' + Continue running the program up to the given LOCATION. An argument + is required, which should be of one of the forms described in *note + Specify Location::. Execution will also stop upon exit from the + current stack frame. This command is similar to 'until', but + 'advance' will not skip over recursive function calls, and the + target location doesn't have to be in the same frame as the current + one. + +'stepi' +'stepi ARG' +'si' + Execute one machine instruction, then stop and return to the + debugger. + + It is often useful to do 'display/i $pc' when stepping by machine + instructions. This makes GDB automatically display the next + instruction to be executed, each time your program stops. *Note + Automatic Display: Auto Display. + + An argument is a repeat count, as in 'step'. + +'nexti' +'nexti ARG' +'ni' + Execute one machine instruction, but if it is a function call, + proceed until the function returns. + + An argument is a repeat count, as in 'next'. + + By default, and if available, GDB makes use of target-assisted "range +stepping". In other words, whenever you use a stepping command (e.g., +'step', 'next'), GDB tells the target to step the corresponding range of +instruction addresses instead of issuing multiple single-steps. This +speeds up line stepping, particularly for remote targets. Ideally, +there should be no reason you would want to turn range stepping off. +However, it's possible that a bug in the debug info, a bug in the remote +stub (for remote targets), or even a bug in GDB could make line stepping +behave incorrectly when target-assisted range stepping is enabled. You +can use the following command to turn off range stepping if necessary: + +'set range-stepping' +'show range-stepping' + Control whether range stepping is enabled. + + If 'on', and the target supports it, GDB tells the target to step a + range of addresses itself, instead of issuing multiple + single-steps. If 'off', GDB always issues single-steps, even if + range stepping is supported by the target. The default is 'on'. + + +File: gdb.info, Node: Skipping Over Functions and Files, Next: Signals, Prev: Continuing and Stepping, Up: Stopping + +5.3 Skipping Over Functions and Files +===================================== + +The program you are debugging may contain some functions which are +uninteresting to debug. The 'skip' comand lets you tell GDB to skip a +function or all functions in a file when stepping. + + For example, consider the following C function: + + 101 int func() + 102 { + 103 foo(boring()); + 104 bar(boring()); + 105 } + +Suppose you wish to step into the functions 'foo' and 'bar', but you are +not interested in stepping through 'boring'. If you run 'step' at line +103, you'll enter 'boring()', but if you run 'next', you'll step over +both 'foo' and 'boring'! + + One solution is to 'step' into 'boring' and use the 'finish' command +to immediately exit it. But this can become tedious if 'boring' is +called from many places. + + A more flexible solution is to execute 'skip boring'. This instructs +GDB never to step into 'boring'. Now when you execute 'step' at line +103, you'll step over 'boring' and directly into 'foo'. + + You can also instruct GDB to skip all functions in a file, with, for +example, 'skip file boring.c'. + +'skip [LINESPEC]' +'skip function [LINESPEC]' + After running this command, the function named by LINESPEC or the + function containing the line named by LINESPEC will be skipped over + when stepping. *Note Specify Location::. + + If you do not specify LINESPEC, the function you're currently + debugging will be skipped. + + (If you have a function called 'file' that you want to skip, use + 'skip function file'.) + +'skip file [FILENAME]' + After running this command, any function whose source lives in + FILENAME will be skipped over when stepping. + + If you do not specify FILENAME, functions whose source lives in the + file you're currently debugging will be skipped. + + Skips can be listed, deleted, disabled, and enabled, much like +breakpoints. These are the commands for managing your list of skips: + +'info skip [RANGE]' + Print details about the specified skip(s). If RANGE is not + specified, print a table with details about all functions and files + marked for skipping. 'info skip' prints the following information + about each skip: + + _Identifier_ + A number identifying this skip. + _Type_ + The type of this skip, either 'function' or 'file'. + _Enabled or Disabled_ + Enabled skips are marked with 'y'. Disabled skips are marked + with 'n'. + _Address_ + For function skips, this column indicates the address in + memory of the function being skipped. If you've set a + function skip on a function which has not yet been loaded, + this field will contain ''. Once a shared library + which has the function is loaded, 'info skip' will show the + function's address here. + _What_ + For file skips, this field contains the filename being + skipped. For functions skips, this field contains the + function name and its line number in the file where it is + defined. + +'skip delete [RANGE]' + Delete the specified skip(s). If RANGE is not specified, delete + all skips. + +'skip enable [RANGE]' + Enable the specified skip(s). If RANGE is not specified, enable + all skips. + +'skip disable [RANGE]' + Disable the specified skip(s). If RANGE is not specified, disable + all skips. + + +File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Skipping Over Functions and Files, Up: Stopping + +5.4 Signals +=========== + +A signal is an asynchronous event that can happen in a program. The +operating system defines the possible kinds of signals, and gives each +kind a name and a number. For example, in Unix 'SIGINT' is the signal a +program gets when you type an interrupt character (often 'Ctrl-c'); +'SIGSEGV' is the signal a program gets from referencing a place in +memory far away from all the areas in use; 'SIGALRM' occurs when the +alarm clock timer goes off (which happens only if your program has +requested an alarm). + + Some signals, including 'SIGALRM', are a normal part of the +functioning of your program. Others, such as 'SIGSEGV', indicate +errors; these signals are "fatal" (they kill your program immediately) +if the program has not specified in advance some other way to handle the +signal. 'SIGINT' does not indicate an error in your program, but it is +normally fatal so it can carry out the purpose of the interrupt: to kill +the program. + + GDB has the ability to detect any occurrence of a signal in your +program. You can tell GDB in advance what to do for each kind of +signal. + + Normally, GDB is set up to let the non-erroneous signals like +'SIGALRM' be silently passed to your program (so as not to interfere +with their role in the program's functioning) but to stop your program +immediately whenever an error signal happens. You can change these +settings with the 'handle' command. + +'info signals' +'info handle' + Print a table of all the kinds of signals and how GDB has been told + to handle each one. You can use this to see the signal numbers of + all the defined types of signals. + +'info signals SIG' + Similar, but print information only about the specified signal + number. + + 'info handle' is an alias for 'info signals'. + +'catch signal [SIGNAL... | 'all']' + Set a catchpoint for the indicated signals. *Note Set + Catchpoints::, for details about this command. + +'handle SIGNAL [KEYWORDS...]' + Change the way GDB handles signal SIGNAL. SIGNAL can be the number + of a signal or its name (with or without the 'SIG' at the + beginning); a list of signal numbers of the form 'LOW-HIGH'; or the + word 'all', meaning all the known signals. Optional arguments + KEYWORDS, described below, say what change to make. + + The keywords allowed by the 'handle' command can be abbreviated. +Their full names are: + +'nostop' + GDB should not stop your program when this signal happens. It may + still print a message telling you that the signal has come in. + +'stop' + GDB should stop your program when this signal happens. This + implies the 'print' keyword as well. + +'print' + GDB should print a message when this signal happens. + +'noprint' + GDB should not mention the occurrence of the signal at all. This + implies the 'nostop' keyword as well. + +'pass' +'noignore' + GDB should allow your program to see this signal; your program can + handle the signal, or else it may terminate if the signal is fatal + and not handled. 'pass' and 'noignore' are synonyms. + +'nopass' +'ignore' + GDB should not allow your program to see this signal. 'nopass' and + 'ignore' are synonyms. + + When a signal stops your program, the signal is not visible to the +program until you continue. Your program sees the signal then, if +'pass' is in effect for the signal in question _at that time_. In other +words, after GDB reports a signal, you can use the 'handle' command with +'pass' or 'nopass' to control whether your program sees that signal when +you continue. + + The default is set to 'nostop', 'noprint', 'pass' for non-erroneous +signals such as 'SIGALRM', 'SIGWINCH' and 'SIGCHLD', and to 'stop', +'print', 'pass' for the erroneous signals. + + You can also use the 'signal' command to prevent your program from +seeing a signal, or cause it to see a signal it normally would not see, +or to give it any signal at any time. For example, if your program +stopped due to some sort of memory reference error, you might store +correct values into the erroneous variables and continue, hoping to see +more execution; but your program would probably terminate immediately as +a result of the fatal signal once it saw the signal. To prevent this, +you can continue with 'signal 0'. *Note Giving your Program a Signal: +Signaling. + + On some targets, GDB can inspect extra signal information associated +with the intercepted signal, before it is actually delivered to the +program being debugged. This information is exported by the convenience +variable '$_siginfo', and consists of data that is passed by the kernel +to the signal handler at the time of the receipt of a signal. The data +type of the information itself is target dependent. You can see the +data type using the 'ptype $_siginfo' command. On Unix systems, it +typically corresponds to the standard 'siginfo_t' type, as defined in +the 'signal.h' system header. + + Here's an example, on a GNU/Linux system, printing the stray +referenced address that raised a segmentation fault. + + (gdb) continue + Program received signal SIGSEGV, Segmentation fault. + 0x0000000000400766 in main () + 69 *(int *)p = 0; + (gdb) ptype $_siginfo + type = struct { + int si_signo; + int si_errno; + int si_code; + union { + int _pad[28]; + struct {...} _kill; + struct {...} _timer; + struct {...} _rt; + struct {...} _sigchld; + struct {...} _sigfault; + struct {...} _sigpoll; + } _sifields; + } + (gdb) ptype $_siginfo._sifields._sigfault + type = struct { + void *si_addr; + } + (gdb) p $_siginfo._sifields._sigfault.si_addr + $1 = (void *) 0x7ffff7ff7000 + + Depending on target support, '$_siginfo' may also be writable. + + +File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping + +5.5 Stopping and Starting Multi-thread Programs +=============================================== + +GDB supports debugging programs with multiple threads (*note Debugging +Programs with Multiple Threads: Threads.). There are two modes of +controlling execution of your program within the debugger. In the +default mode, referred to as "all-stop mode", when any thread in your +program stops (for example, at a breakpoint or while being stepped), all +other threads in the program are also stopped by GDB. On some targets, +GDB also supports "non-stop mode", in which other threads can continue +to run freely while you examine the stopped thread in the debugger. + +* Menu: + +* All-Stop Mode:: All threads stop when GDB takes control +* Non-Stop Mode:: Other threads continue to execute +* Background Execution:: Running your program asynchronously +* Thread-Specific Breakpoints:: Controlling breakpoints +* Interrupted System Calls:: GDB may interfere with system calls +* Observer Mode:: GDB does not alter program behavior + + +File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops + +5.5.1 All-Stop Mode +------------------- + +In all-stop mode, whenever your program stops under GDB for any reason, +_all_ threads of execution stop, not just the current thread. This +allows you to examine the overall state of the program, including +switching between threads, without worrying that things may change +underfoot. + + Conversely, whenever you restart the program, _all_ threads start +executing. _This is true even when single-stepping_ with commands like +'step' or 'next'. + + In particular, GDB cannot single-step all threads in lockstep. Since +thread scheduling is up to your debugging target's operating system (not +controlled by GDB), other threads may execute more than one statement +while the current thread completes a single step. Moreover, in general +other threads stop in the middle of a statement, rather than at a clean +statement boundary, when the program stops. + + You might even find your program stopped in another thread after +continuing or even single-stepping. This happens whenever some other +thread runs into a breakpoint, a signal, or an exception before the +first thread completes whatever you requested. + + Whenever GDB stops your program, due to a breakpoint or a signal, it +automatically selects the thread where that breakpoint or signal +happened. GDB alerts you to the context switch with a message such as +'[Switching to Thread N]' to identify the thread. + + On some OSes, you can modify GDB's default behavior by locking the OS +scheduler to allow only a single thread to run. + +'set scheduler-locking MODE' + Set the scheduler locking mode. If it is 'off', then there is no + locking and any thread may run at any time. If 'on', then only the + current thread may run when the inferior is resumed. The 'step' + mode optimizes for single-stepping; it prevents other threads from + preempting the current thread while you are stepping, so that the + focus of debugging does not change unexpectedly. Other threads + only rarely (or never) get a chance to run when you step. They are + more likely to run when you 'next' over a function call, and they + are completely free to run when you use commands like 'continue', + 'until', or 'finish'. However, unless another thread hits a + breakpoint during its timeslice, GDB does not change the current + thread away from the thread that you are debugging. + +'show scheduler-locking' + Display the current scheduler locking mode. + + By default, when you issue one of the execution commands such as +'continue', 'next' or 'step', GDB allows only threads of the current +inferior to run. For example, if GDB is attached to two inferiors, each +with two threads, the 'continue' command resumes only the two threads of +the current inferior. This is useful, for example, when you debug a +program that forks and you want to hold the parent stopped (so that, for +instance, it doesn't run to exit), while you debug the child. In other +situations, you may not be interested in inspecting the current state of +any of the processes GDB is attached to, and you may want to resume them +all until some breakpoint is hit. In the latter case, you can instruct +GDB to allow all threads of all the inferiors to run with the 'set schedule-multiple' +command. + +'set schedule-multiple' + Set the mode for allowing threads of multiple processes to be + resumed when an execution command is issued. When 'on', all + threads of all processes are allowed to run. When 'off', only the + threads of the current process are resumed. The default is 'off'. + The 'scheduler-locking' mode takes precedence when set to 'on', or + while you are stepping and set to 'step'. + +'show schedule-multiple' + Display the current mode for resuming the execution of threads of + multiple processes. + + +File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops + +5.5.2 Non-Stop Mode +------------------- + +For some multi-threaded targets, GDB supports an optional mode of +operation in which you can examine stopped program threads in the +debugger while other threads continue to execute freely. This minimizes +intrusion when debugging live systems, such as programs where some +threads have real-time constraints or must continue to respond to +external events. This is referred to as "non-stop" mode. + + In non-stop mode, when a thread stops to report a debugging event, +_only_ that thread is stopped; GDB does not stop other threads as well, +in contrast to the all-stop mode behavior. Additionally, execution +commands such as 'continue' and 'step' apply by default only to the +current thread in non-stop mode, rather than all threads as in all-stop +mode. This allows you to control threads explicitly in ways that are +not possible in all-stop mode -- for example, stepping one thread while +allowing others to run freely, stepping one thread while holding all +others stopped, or stepping several threads independently and +simultaneously. + + To enter non-stop mode, use this sequence of commands before you run +or attach to your program: + + # Enable the async interface. + set target-async 1 + + # If using the CLI, pagination breaks non-stop. + set pagination off + + # Finally, turn it on! + set non-stop on + + You can use these commands to manipulate the non-stop mode setting: + +'set non-stop on' + Enable selection of non-stop mode. +'set non-stop off' + Disable selection of non-stop mode. +'show non-stop' + Show the current non-stop enablement setting. + + Note these commands only reflect whether non-stop mode is enabled, +not whether the currently-executing program is being run in non-stop +mode. In particular, the 'set non-stop' preference is only consulted +when GDB starts or connects to the target program, and it is generally +not possible to switch modes once debugging has started. Furthermore, +since not all targets support non-stop mode, even when you have enabled +non-stop mode, GDB may still fall back to all-stop operation by default. + + In non-stop mode, all execution commands apply only to the current +thread by default. That is, 'continue' only continues one thread. To +continue all threads, issue 'continue -a' or 'c -a'. + + You can use GDB's background execution commands (*note Background +Execution::) to run some threads in the background while you continue to +examine or step others from GDB. The MI execution commands (*note +GDB/MI Program Execution::) are always executed asynchronously in +non-stop mode. + + Suspending execution is done with the 'interrupt' command when +running in the background, or 'Ctrl-c' during foreground execution. In +all-stop mode, this stops the whole process; but in non-stop mode the +interrupt applies only to the current thread. To stop the whole +program, use 'interrupt -a'. + + Other execution commands do not currently support the '-a' option. + + In non-stop mode, when a thread stops, GDB doesn't automatically make +that thread current, as it does in all-stop mode. This is because the +thread stop notifications are asynchronous with respect to GDB's command +interpreter, and it would be confusing if GDB unexpectedly changed to a +different thread just as you entered a command to operate on the +previously current thread. + + +File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops + +5.5.3 Background Execution +-------------------------- + +GDB's execution commands have two variants: the normal foreground +(synchronous) behavior, and a background (asynchronous) behavior. In +foreground execution, GDB waits for the program to report that some +thread has stopped before prompting for another command. In background +execution, GDB immediately gives a command prompt so that you can issue +other commands while your program runs. + + You need to explicitly enable asynchronous mode before you can use +background execution commands. You can use these commands to manipulate +the asynchronous mode setting: + +'set target-async on' + Enable asynchronous mode. +'set target-async off' + Disable asynchronous mode. +'show target-async' + Show the current target-async setting. + + If the target doesn't support async mode, GDB issues an error message +if you attempt to use the background execution commands. + + To specify background execution, add a '&' to the command. For +example, the background form of the 'continue' command is 'continue&', +or just 'c&'. The execution commands that accept background execution +are: + +'run' + *Note Starting your Program: Starting. + +'attach' + *Note Debugging an Already-running Process: Attach. + +'step' + *Note step: Continuing and Stepping. + +'stepi' + *Note stepi: Continuing and Stepping. + +'next' + *Note next: Continuing and Stepping. + +'nexti' + *Note nexti: Continuing and Stepping. + +'continue' + *Note continue: Continuing and Stepping. + +'finish' + *Note finish: Continuing and Stepping. + +'until' + *Note until: Continuing and Stepping. + + Background execution is especially useful in conjunction with +non-stop mode for debugging programs with multiple threads; see *note +Non-Stop Mode::. However, you can also use these commands in the normal +all-stop mode with the restriction that you cannot issue another +execution command until the previous one finishes. Examples of commands +that are valid in all-stop mode while the program is running include +'help' and 'info break'. + + You can interrupt your program while it is running in the background +by using the 'interrupt' command. + +'interrupt' +'interrupt -a' + + Suspend execution of the running program. In all-stop mode, + 'interrupt' stops the whole process, but in non-stop mode, it stops + only the current thread. To stop the whole program in non-stop + mode, use 'interrupt -a'. + + +File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops + +5.5.4 Thread-Specific Breakpoints +--------------------------------- + +When your program has multiple threads (*note Debugging Programs with +Multiple Threads: Threads.), you can choose whether to set breakpoints +on all threads, or on a particular thread. + +'break LINESPEC thread THREADNO' +'break LINESPEC thread THREADNO if ...' + LINESPEC specifies source lines; there are several ways of writing + them (*note Specify Location::), but the effect is always to + specify some source line. + + Use the qualifier 'thread THREADNO' with a breakpoint command to + specify that you only want GDB to stop the program when a + particular thread reaches this breakpoint. THREADNO is one of the + numeric thread identifiers assigned by GDB, shown in the first + column of the 'info threads' display. + + If you do not specify 'thread THREADNO' when you set a breakpoint, + the breakpoint applies to _all_ threads of your program. + + You can use the 'thread' qualifier on conditional breakpoints as + well; in this case, place 'thread THREADNO' before or after the + breakpoint condition, like this: + + (gdb) break frik.c:13 thread 28 if bartab > lim + + Thread-specific breakpoints are automatically deleted when GDB +detects the corresponding thread is no longer in the thread list. For +example: + + (gdb) c + Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list. + + There are several ways for a thread to disappear, such as a regular +thread exit, but also when you detach from the process with the 'detach' +command (*note Debugging an Already-running Process: Attach.), or if GDB +loses the remote connection (*note Remote Debugging::), etc. Note that +with some targets, GDB is only able to detect a thread has exited when +the user explictly asks for the thread list with the 'info threads' +command. + + +File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops + +5.5.5 Interrupted System Calls +------------------------------ + +There is an unfortunate side effect when using GDB to debug +multi-threaded programs. If one thread stops for a breakpoint, or for +some other reason, and another thread is blocked in a system call, then +the system call may return prematurely. This is a consequence of the +interaction between multiple threads and the signals that GDB uses to +implement breakpoints and other events that stop execution. + + To handle this problem, your program should check the return value of +each system call and react appropriately. This is good programming +style anyways. + + For example, do not write code like this: + + sleep (10); + + The call to 'sleep' will return early if a different thread stops at +a breakpoint or for some other reason. + + Instead, write this: + + int unslept = 10; + while (unslept > 0) + unslept = sleep (unslept); + + A system call is allowed to return early, so the system is still +conforming to its specification. But GDB does cause your multi-threaded +program to behave differently than it would without GDB. + + Also, GDB uses internal breakpoints in the thread library to monitor +certain events such as thread creation and thread destruction. When +such an event happens, a system call in another thread may return +prematurely, even though your program does not appear to stop. + + +File: gdb.info, Node: Observer Mode, Prev: Interrupted System Calls, Up: Thread Stops + +5.5.6 Observer Mode +------------------- + +If you want to build on non-stop mode and observe program behavior +without any chance of disruption by GDB, you can set variables to +disable all of the debugger's attempts to modify state, whether by +writing memory, inserting breakpoints, etc. These operate at a low +level, intercepting operations from all commands. + + When all of these are set to 'off', then GDB is said to be "observer +mode". As a convenience, the variable 'observer' can be set to disable +these, plus enable non-stop mode. + + Note that GDB will not prevent you from making nonsensical +combinations of these settings. For instance, if you have enabled +'may-insert-breakpoints' but disabled 'may-write-memory', then +breakpoints that work by writing trap instructions into the code stream +will still not be able to be placed. + +'set observer on' +'set observer off' + When set to 'on', this disables all the permission variables below + (except for 'insert-fast-tracepoints'), plus enables non-stop + debugging. Setting this to 'off' switches back to normal + debugging, though remaining in non-stop mode. + +'show observer' + Show whether observer mode is on or off. + +'set may-write-registers on' +'set may-write-registers off' + This controls whether GDB will attempt to alter the values of + registers, such as with assignment expressions in 'print', or the + 'jump' command. It defaults to 'on'. + +'show may-write-registers' + Show the current permission to write registers. + +'set may-write-memory on' +'set may-write-memory off' + This controls whether GDB will attempt to alter the contents of + memory, such as with assignment expressions in 'print'. It + defaults to 'on'. + +'show may-write-memory' + Show the current permission to write memory. + +'set may-insert-breakpoints on' +'set may-insert-breakpoints off' + This controls whether GDB will attempt to insert breakpoints. This + affects all breakpoints, including internal breakpoints defined by + GDB. It defaults to 'on'. + +'show may-insert-breakpoints' + Show the current permission to insert breakpoints. + +'set may-insert-tracepoints on' +'set may-insert-tracepoints off' + This controls whether GDB will attempt to insert (regular) + tracepoints at the beginning of a tracing experiment. It affects + only non-fast tracepoints, fast tracepoints being under the control + of 'may-insert-fast-tracepoints'. It defaults to 'on'. + +'show may-insert-tracepoints' + Show the current permission to insert tracepoints. + +'set may-insert-fast-tracepoints on' +'set may-insert-fast-tracepoints off' + This controls whether GDB will attempt to insert fast tracepoints + at the beginning of a tracing experiment. It affects only fast + tracepoints, regular (non-fast) tracepoints being under the control + of 'may-insert-tracepoints'. It defaults to 'on'. + +'show may-insert-fast-tracepoints' + Show the current permission to insert fast tracepoints. + +'set may-interrupt on' +'set may-interrupt off' + This controls whether GDB will attempt to interrupt or stop program + execution. When this variable is 'off', the 'interrupt' command + will have no effect, nor will 'Ctrl-c'. It defaults to 'on'. + +'show may-interrupt' + Show the current permission to interrupt or stop the program. + + +File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top + +6 Running programs backward +*************************** + +When you are debugging a program, it is not unusual to realize that you +have gone too far, and some event of interest has already happened. If +the target environment supports it, GDB can allow you to "rewind" the +program by running it backward. + + A target environment that supports reverse execution should be able +to "undo" the changes in machine state that have taken place as the +program was executing normally. Variables, registers etc. should revert +to their previous values. Obviously this requires a great deal of +sophistication on the part of the target environment; not all target +environments can support reverse execution. + + When a program is executed in reverse, the instructions that have +most recently been executed are "un-executed", in reverse order. The +program counter runs backward, following the previous thread of +execution in reverse. As each instruction is "un-executed", the values +of memory and/or registers that were changed by that instruction are +reverted to their previous states. After executing a piece of source +code in reverse, all side effects of that code should be "undone", and +all variables should be returned to their prior values(1). + + If you are debugging in a target environment that supports reverse +execution, GDB provides the following commands. + +'reverse-continue [IGNORE-COUNT]' +'rc [IGNORE-COUNT]' + Beginning at the point where your program last stopped, start + executing in reverse. Reverse execution will stop for breakpoints + and synchronous exceptions (signals), just like normal execution. + Behavior of asynchronous signals depends on the target environment. + +'reverse-step [COUNT]' + Run the program backward until control reaches the start of a + different source line; then stop it, and return control to GDB. + + Like the 'step' command, 'reverse-step' will only stop at the + beginning of a source line. It "un-executes" the previously + executed source line. If the previous source line included calls + to debuggable functions, 'reverse-step' will step (backward) into + the called function, stopping at the beginning of the _last_ + statement in the called function (typically a return statement). + + Also, as with the 'step' command, if non-debuggable functions are + called, 'reverse-step' will run thru them backward without + stopping. + +'reverse-stepi [COUNT]' + Reverse-execute one machine instruction. Note that the instruction + to be reverse-executed is _not_ the one pointed to by the program + counter, but the instruction executed prior to that one. For + instance, if the last instruction was a jump, 'reverse-stepi' will + take you back from the destination of the jump to the jump + instruction itself. + +'reverse-next [COUNT]' + Run backward to the beginning of the previous line executed in the + current (innermost) stack frame. If the line contains function + calls, they will be "un-executed" without stopping. Starting from + the first line of a function, 'reverse-next' will take you back to + the caller of that function, _before_ the function was called, just + as the normal 'next' command would take you from the last line of a + function back to its return to its caller (2). + +'reverse-nexti [COUNT]' + Like 'nexti', 'reverse-nexti' executes a single instruction in + reverse, except that called functions are "un-executed" atomically. + That is, if the previously executed instruction was a return from + another function, 'reverse-nexti' will continue to execute in + reverse until the call to that function (from the current stack + frame) is reached. + +'reverse-finish' + Just as the 'finish' command takes you to the point where the + current function returns, 'reverse-finish' takes you to the point + where it was called. Instead of ending up at the end of the + current function invocation, you end up at the beginning. + +'set exec-direction' + Set the direction of target execution. +'set exec-direction reverse' + GDB will perform all execution commands in reverse, until the + exec-direction mode is changed to "forward". Affected commands + include 'step, stepi, next, nexti, continue, and finish'. The + 'return' command cannot be used in reverse mode. +'set exec-direction forward' + GDB will perform all execution commands in the normal fashion. + This is the default. + + ---------- Footnotes ---------- + + (1) Note that some side effects are easier to undo than others. For +instance, memory and registers are relatively easy, but device I/O is +hard. Some targets may be able undo things like device I/O, and some +may not. + + The contract between GDB and the reverse executing target requires +only that the target do something reasonable when GDB tells it to +execute backwards, and then report the results back to GDB. Whatever +the target reports back to GDB, GDB will report back to the user. GDB +assumes that the memory and registers that the target reports are in a +consistant state, but GDB accepts whatever it is given. + + (2) Unless the code is too heavily optimized. + + +File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top + +7 Recording Inferior's Execution and Replaying It +************************************************* + +On some platforms, GDB provides a special "process record and replay" +target that can record a log of the process execution, and replay it +later with both forward and reverse execution commands. + + When this target is in use, if the execution log includes the record +for the next instruction, GDB will debug in "replay mode". In the +replay mode, the inferior does not really execute code instructions. +Instead, all the events that normally happen during code execution are +taken from the execution log. While code is not really executed in +replay mode, the values of registers (including the program counter +register) and the memory of the inferior are still changed as they +normally would. Their contents are taken from the execution log. + + If the record for the next instruction is not in the execution log, +GDB will debug in "record mode". In this mode, the inferior executes +normally, and GDB records the execution log for future replay. + + The process record and replay target supports reverse execution +(*note Reverse Execution::), even if the platform on which the inferior +runs does not. However, the reverse execution is limited in this case +by the range of the instructions recorded in the execution log. In +other words, reverse execution on platforms that don't support it +directly can only be done in the replay mode. + + When debugging in the reverse direction, GDB will work in replay mode +as long as the execution log includes the record for the previous +instruction; otherwise, it will work in record mode, if the platform +supports reverse execution, or stop if not. + + For architecture environments that support process record and replay, +GDB provides the following commands: + +'record METHOD' + This command starts the process record and replay target. The + recording method can be specified as parameter. Without a + parameter the command uses the 'full' recording method. The + following recording methods are available: + + 'full' + Full record/replay recording using GDB's software record and + replay implementation. This method allows replaying and + reverse execution. + + 'btrace' + Hardware-supported instruction recording. This method does + not allow replaying and reverse execution. + + This recording method may not be available on all processors. + + The process record and replay target can only debug a process that + is already running. Therefore, you need first to start the process + with the 'run' or 'start' commands, and then start the recording + with the 'record METHOD' command. + + Both 'record METHOD' and 'rec METHOD' are aliases of 'target + record-METHOD'. + + Displaced stepping (*note displaced stepping: Maintenance + Commands.) will be automatically disabled when process record and + replay target is started. That's because the process record and + replay target doesn't support displaced stepping. + + If the inferior is in the non-stop mode (*note Non-Stop Mode::) or + in the asynchronous execution mode (*note Background Execution::), + not all recording methods are available. The 'full' recording + method does not support these two modes. + +'record stop' + Stop the process record and replay target. When process record and + replay target stops, the entire execution log will be deleted and + the inferior will either be terminated, or will remain in its final + state. + + When you stop the process record and replay target in record mode + (at the end of the execution log), the inferior will be stopped at + the next instruction that would have been recorded. In other + words, if you record for a while and then stop recording, the + inferior process will be left in the same state as if the recording + never happened. + + On the other hand, if the process record and replay target is + stopped while in replay mode (that is, not at the end of the + execution log, but at some earlier point), the inferior process + will become "live" at that earlier state, and it will then be + possible to continue the usual "live" debugging of the process from + that state. + + When the inferior process exits, or GDB detaches from it, process + record and replay target will automatically stop itself. + +'record goto' + Go to a specific location in the execution log. There are several + ways to specify the location to go to: + + 'record goto begin' + 'record goto start' + Go to the beginning of the execution log. + + 'record goto end' + Go to the end of the execution log. + + 'record goto N' + Go to instruction number N in the execution log. + +'record save FILENAME' + Save the execution log to a file 'FILENAME'. Default filename is + 'gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the + inferior. + + This command may not be available for all recording methods. + +'record restore FILENAME' + Restore the execution log from a file 'FILENAME'. File must have + been created with 'record save'. + +'set record full insn-number-max LIMIT' +'set record full insn-number-max unlimited' + Set the limit of instructions to be recorded for the 'full' + recording method. Default value is 200000. + + If LIMIT is a positive number, then GDB will start deleting + instructions from the log once the number of the record + instructions becomes greater than LIMIT. For every new recorded + instruction, GDB will delete the earliest recorded instruction to + keep the number of recorded instructions at the limit. (Since + deleting recorded instructions loses information, GDB lets you + control what happens when the limit is reached, by means of the + 'stop-at-limit' option, described below.) + + If LIMIT is 'unlimited' or zero, GDB will never delete recorded + instructions from the execution log. The number of recorded + instructions is limited only by the available memory. + +'show record full insn-number-max' + Show the limit of instructions to be recorded with the 'full' + recording method. + +'set record full stop-at-limit' + Control the behavior of the 'full' recording method when the number + of recorded instructions reaches the limit. If ON (the default), + GDB will stop when the limit is reached for the first time and ask + you whether you want to stop the inferior or continue running it + and recording the execution log. If you decide to continue + recording, each new recorded instruction will cause the oldest one + to be deleted. + + If this option is OFF, GDB will automatically delete the oldest + record to make room for each new one, without asking. + +'show record full stop-at-limit' + Show the current setting of 'stop-at-limit'. + +'set record full memory-query' + Control the behavior when GDB is unable to record memory changes + caused by an instruction for the 'full' recording method. If ON, + GDB will query whether to stop the inferior in that case. + + If this option is OFF (the default), GDB will automatically ignore + the effect of such instructions on memory. Later, when GDB replays + this execution log, it will mark the log of this instruction as not + accessible, and it will not affect the replay results. + +'show record full memory-query' + Show the current setting of 'memory-query'. + +'info record' + Show various statistics about the recording depending on the + recording method: + + 'full' + For the 'full' recording method, it shows the state of process + record and its in-memory execution log buffer, including: + + * Whether in record mode or replay mode. + * Lowest recorded instruction number (counting from when + the current execution log started recording + instructions). + * Highest recorded instruction number. + * Current instruction about to be replayed (if in replay + mode). + * Number of instructions contained in the execution log. + * Maximum number of instructions that may be contained in + the execution log. + + 'btrace' + For the 'btrace' recording method, it shows the number of + instructions that have been recorded and the number of blocks + of sequential control-flow that is formed by the recorded + instructions. + +'record delete' + When record target runs in replay mode ("in the past"), delete the + subsequent execution log and begin to record a new execution log + starting from the current address. This means you will abandon the + previously recorded "future" and begin recording a new "future". + +'record instruction-history' + Disassembles instructions from the recorded execution log. By + default, ten instructions are disassembled. This can be changed + using the 'set record instruction-history-size' command. + Instructions are printed in execution order. There are several + ways to specify what part of the execution log to disassemble: + + 'record instruction-history INSN' + Disassembles ten instructions starting from instruction number + INSN. + + 'record instruction-history INSN, +/-N' + Disassembles N instructions around instruction number INSN. + If N is preceded with '+', disassembles N instructions after + instruction number INSN. If N is preceded with '-', + disassembles N instructions before instruction number INSN. + + 'record instruction-history' + Disassembles ten more instructions after the last disassembly. + + 'record instruction-history -' + Disassembles ten more instructions before the last + disassembly. + + 'record instruction-history BEGIN END' + Disassembles instructions beginning with instruction number + BEGIN until instruction number END. The instruction number + END is not included. + + This command may not be available for all recording methods. + +'set record instruction-history-size SIZE' +'set record instruction-history-size unlimited' + Define how many instructions to disassemble in the 'record + instruction-history' command. The default value is 10. A SIZE of + 'unlimited' means unlimited instructions. + +'show record instruction-history-size' + Show how many instructions to disassemble in the 'record + instruction-history' command. + +'record function-call-history' + Prints the execution history at function granularity. It prints + one line for each sequence of instructions that belong to the same + function giving the name of that function, the source lines for + this instruction sequence (if the '/l' modifier is specified), and + the instructions numbers that form the sequence (if the '/i' + modifier is specified). + + (gdb) list 1, 10 + 1 void foo (void) + 2 { + 3 } + 4 + 5 void bar (void) + 6 { + 7 ... + 8 foo (); + 9 ... + 10 } + (gdb) record function-call-history /l + 1 foo.c:6-8 bar + 2 foo.c:2-3 foo + 3 foo.c:9-10 bar + + By default, ten lines are printed. This can be changed using the + 'set record function-call-history-size' command. Functions are + printed in execution order. There are several ways to specify what + to print: + + 'record function-call-history FUNC' + Prints ten functions starting from function number FUNC. + + 'record function-call-history FUNC, +/-N' + Prints N functions around function number FUNC. If N is + preceded with '+', prints N functions after function number + FUNC. If N is preceded with '-', prints N functions before + function number FUNC. + + 'record function-call-history' + Prints ten more functions after the last ten-line print. + + 'record function-call-history -' + Prints ten more functions before the last ten-line print. + + 'record function-call-history BEGIN END' + Prints functions beginning with function number BEGIN until + function number END. The function number END is not included. + + This command may not be available for all recording methods. + +'set record function-call-history-size SIZE' +'set record function-call-history-size unlimited' + Define how many lines to print in the 'record + function-call-history' command. The default value is 10. A size + of 'unlimited' means unlimited lines. + +'show record function-call-history-size' + Show how many lines to print in the 'record function-call-history' + command. + + +File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top + +8 Examining the Stack +********************* + +When your program has stopped, the first thing you need to know is where +it stopped and how it got there. + + Each time your program performs a function call, information about +the call is generated. That information includes the location of the +call in your program, the arguments of the call, and the local variables +of the function being called. The information is saved in a block of +data called a "stack frame". The stack frames are allocated in a region +of memory called the "call stack". + + When your program stops, the GDB commands for examining the stack +allow you to see all of this information. + + One of the stack frames is "selected" by GDB and many GDB commands +refer implicitly to the selected frame. In particular, whenever you ask +GDB for the value of a variable in your program, the value is found in +the selected frame. There are special GDB commands to select whichever +frame you are interested in. *Note Selecting a Frame: Selection. + + When your program stops, GDB automatically selects the currently +executing frame and describes it briefly, similar to the 'frame' command +(*note Information about a Frame: Frame Info.). + +* Menu: + +* Frames:: Stack frames +* Backtrace:: Backtraces +* Frame Filter Management:: Managing frame filters +* Selection:: Selecting a frame +* Frame Info:: Information on a frame + + +File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack + +8.1 Stack Frames +================ + +The call stack is divided up into contiguous pieces called "stack +frames", or "frames" for short; each frame is the data associated with +one call to one function. The frame contains the arguments given to the +function, the function's local variables, and the address at which the +function is executing. + + When your program is started, the stack has only one frame, that of +the function 'main'. This is called the "initial" frame or the +"outermost" frame. Each time a function is called, a new frame is made. +Each time a function returns, the frame for that function invocation is +eliminated. If a function is recursive, there can be many frames for +the same function. The frame for the function in which execution is +actually occurring is called the "innermost" frame. This is the most +recently created of all the stack frames that still exist. + + Inside your program, stack frames are identified by their addresses. +A stack frame consists of many bytes, each of which has its own address; +each kind of computer has a convention for choosing one byte whose +address serves as the address of the frame. Usually this address is +kept in a register called the "frame pointer register" (*note $fp: +Registers.) while execution is going on in that frame. + + GDB assigns numbers to all existing stack frames, starting with zero +for the innermost frame, one for the frame that called it, and so on +upward. These numbers do not really exist in your program; they are +assigned by GDB to give you a way of designating stack frames in GDB +commands. + + Some compilers provide a way to compile functions so that they +operate without stack frames. (For example, the GCC option + '-fomit-frame-pointer' + generates functions without a frame.) This is occasionally done with +heavily used library functions to save the frame setup time. GDB has +limited facilities for dealing with these function invocations. If the +innermost function invocation has no stack frame, GDB nevertheless +regards it as though it had a separate frame, which is numbered zero as +usual, allowing correct tracing of the function call chain. However, +GDB has no provision for frameless functions elsewhere in the stack. + +'frame ARGS' + The 'frame' command allows you to move from one stack frame to + another, and to print the stack frame you select. ARGS may be + either the address of the frame or the stack frame number. Without + an argument, 'frame' prints the current stack frame. + +'select-frame' + The 'select-frame' command allows you to move from one stack frame + to another without printing the frame. This is the silent version + of 'frame'. + + +File: gdb.info, Node: Backtrace, Next: Frame Filter Management, Prev: Frames, Up: Stack + +8.2 Backtraces +============== + +A backtrace is a summary of how your program got where it is. It shows +one line per frame, for many frames, starting with the currently +executing frame (frame zero), followed by its caller (frame one), and on +up the stack. + +'backtrace' +'bt' + Print a backtrace of the entire stack: one line per frame for all + frames in the stack. + + You can stop the backtrace at any time by typing the system + interrupt character, normally 'Ctrl-c'. + +'backtrace N' +'bt N' + Similar, but print only the innermost N frames. + +'backtrace -N' +'bt -N' + Similar, but print only the outermost N frames. + +'backtrace full' +'bt full' +'bt full N' +'bt full -N' + Print the values of the local variables also. N specifies the + number of frames to print, as described above. + +'backtrace no-filters' +'bt no-filters' +'bt no-filters N' +'bt no-filters -N' +'bt no-filters full' +'bt no-filters full N' +'bt no-filters full -N' + Do not run Python frame filters on this backtrace. *Note Frame + Filter API::, for more information. Additionally use *note disable + frame-filter all:: to turn off all frame filters. This is only + relevant when GDB has been configured with 'Python' support. + + The names 'where' and 'info stack' (abbreviated 'info s') are +additional aliases for 'backtrace'. + + In a multi-threaded program, GDB by default shows the backtrace only +for the current thread. To display the backtrace for several or all of +the threads, use the command 'thread apply' (*note thread apply: +Threads.). For example, if you type 'thread apply all backtrace', GDB +will display the backtrace for all the threads; this is handy when you +debug a core dump of a multi-threaded program. + + Each line in the backtrace shows the frame number and the function +name. The program counter value is also shown--unless you use 'set +print address off'. The backtrace also shows the source file name and +line number, as well as the arguments to the function. The program +counter value is omitted if it is at the beginning of the code for that +line number. + + Here is an example of a backtrace. It was made with the command 'bt +3', so it shows the innermost three frames. + + #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) + at builtin.c:993 + #1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242 + #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) + at macro.c:71 + (More stack frames follow...) + +The display for frame zero does not begin with a program counter value, +indicating that your program has stopped at the beginning of the code +for line '993' of 'builtin.c'. + +The value of parameter 'data' in frame 1 has been replaced by '...'. By +default, GDB prints the value of a parameter only if it is a scalar +(integer, pointer, enumeration, etc). See command 'set print +frame-arguments' in *note Print Settings:: for more details on how to +configure the way function parameter values are printed. + + If your program was compiled with optimizations, some compilers will +optimize away arguments passed to functions if those arguments are never +used after the call. Such optimizations generate code that passes +arguments through registers, but doesn't store those arguments in the +stack frame. GDB has no way of displaying such arguments in stack +frames other than the innermost one. Here's what such a backtrace might +look like: + + #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) + at builtin.c:993 + #1 0x6e38 in expand_macro (sym=) at macro.c:242 + #2 0x6840 in expand_token (obs=0x0, t=, td=0xf7fffb08) + at macro.c:71 + (More stack frames follow...) + +The values of arguments that were not saved in their stack frames are +shown as ''. + + If you need to display the values of such optimized-out arguments, +either deduce that from other variables whose values depend on the one +you are interested in, or recompile without optimizations. + + Most programs have a standard user entry point--a place where system +libraries and startup code transition into user code. For C this is +'main'(1). When GDB finds the entry function in a backtrace it will +terminate the backtrace, to avoid tracing into highly system-specific +(and generally uninteresting) code. + + If you need to examine the startup code, or limit the number of +levels in a backtrace, you can change this behavior: + +'set backtrace past-main' +'set backtrace past-main on' + Backtraces will continue past the user entry point. + +'set backtrace past-main off' + Backtraces will stop when they encounter the user entry point. + This is the default. + +'show backtrace past-main' + Display the current user entry point backtrace policy. + +'set backtrace past-entry' +'set backtrace past-entry on' + Backtraces will continue past the internal entry point of an + application. This entry point is encoded by the linker when the + application is built, and is likely before the user entry point + 'main' (or equivalent) is called. + +'set backtrace past-entry off' + Backtraces will stop when they encounter the internal entry point + of an application. This is the default. + +'show backtrace past-entry' + Display the current internal entry point backtrace policy. + +'set backtrace limit N' +'set backtrace limit 0' +'set backtrace limit unlimited' + Limit the backtrace to N levels. A value of 'unlimited' or zero + means unlimited levels. + +'show backtrace limit' + Display the current limit on backtrace levels. + + You can control how file names are displayed. + +'set filename-display' +'set filename-display relative' + Display file names relative to the compilation directory. This is + the default. + +'set filename-display basename' + Display only basename of a filename. + +'set filename-display absolute' + Display an absolute filename. + +'show filename-display' + Show the current way to display filenames. + + ---------- Footnotes ---------- + + (1) Note that embedded programs (the so-called "free-standing" +environment) are not required to have a 'main' function as the entry +point. They could even have multiple entry points. + + +File: gdb.info, Node: Frame Filter Management, Next: Selection, Prev: Backtrace, Up: Stack + +8.3 Management of Frame Filters. +================================ + +Frame filters are Python based utilities to manage and decorate the +output of frames. *Note Frame Filter API::, for further information. + + Managing frame filters is performed by several commands available +within GDB, detailed here. + +'info frame-filter' + Print a list of installed frame filters from all dictionaries, + showing their name, priority and enabled status. + +'disable frame-filter FILTER-DICTIONARY FILTER-NAME' + Disable a frame filter in the dictionary matching + FILTER-DICTIONARY, or 'all', and FILTER-NAME. FILTER-DICTIONARY + may be 'all', 'global', 'progspace' or the name of the object file + where the frame filter dictionary resides. When 'all' is + specified, all frame filters across all dictionaries are disabled. + FILTER-NAME is the name of the frame filter and is used when 'all' + is not the option for FILTER-DICTIONARY. A disabled frame-filter + is not deleted, it may be enabled again later. + +'enable frame-filter FILTER-DICTIONARY FILTER-NAME' + Enable a frame filter in the dictionary matching FILTER-DICTIONARY, + or 'all', and FILTER-NAME. FILTER-DICTIONARY may be 'all', + 'global', 'progspace' or the name of the object file where the + frame filter dictionary resides. When 'all' is specified, all + frame filters across all dictionaries are enabled. FILTER-NAME is + the name of the frame filter and is used when 'all' is not the + option for FILTER-DICTIONARY. + + Example: + + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 No PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 Yes BuildProgra Filter + + (gdb) disable frame-filter /build/test BuildProgramFilter + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 No PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + + (gdb) enable frame-filter global PrimaryFunctionFilter + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + +'set frame-filter priority FILTER-DICTIONARY FILTER-NAME PRIORITY' + Set the PRIORITY of a frame filter in the dictionary matching + FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME. + FILTER-DICTIONARY may be 'global', 'progspace' or the name of the + object file where the frame filter dictionary resides. PRIORITY is + an integer. + +'show frame-filter priority FILTER-DICTIONARY FILTER-NAME' + Show the PRIORITY of a frame filter in the dictionary matching + FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME. + FILTER-DICTIONARY may be 'global', 'progspace' or the name of the + object file where the frame filter dictionary resides. + + Example: + + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + + (gdb) set frame-filter priority global Reverse 50 + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 50 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + + +File: gdb.info, Node: Selection, Next: Frame Info, Prev: Frame Filter Management, Up: Stack + +8.4 Selecting a Frame +===================== + +Most commands for examining the stack and other data in your program +work on whichever stack frame is selected at the moment. Here are the +commands for selecting a stack frame; all of them finish by printing a +brief description of the stack frame just selected. + +'frame N' +'f N' + Select frame number N. Recall that frame zero is the innermost + (currently executing) frame, frame one is the frame that called the + innermost one, and so on. The highest-numbered frame is the one + for 'main'. + +'frame ADDR' +'f ADDR' + Select the frame at address ADDR. This is useful mainly if the + chaining of stack frames has been damaged by a bug, making it + impossible for GDB to assign numbers properly to all frames. In + addition, this can be useful when your program has multiple stacks + and switches between them. + + On the SPARC architecture, 'frame' needs two addresses to select an + arbitrary frame: a frame pointer and a stack pointer. + + On the MIPS and Alpha architecture, it needs two addresses: a stack + pointer and a program counter. + + On the 29k architecture, it needs three addresses: a register stack + pointer, a program counter, and a memory stack pointer. + +'up N' + Move N frames up the stack. For positive numbers N, this advances + toward the outermost frame, to higher frame numbers, to frames that + have existed longer. N defaults to one. + +'down N' + Move N frames down the stack. For positive numbers N, this + advances toward the innermost frame, to lower frame numbers, to + frames that were created more recently. N defaults to one. You + may abbreviate 'down' as 'do'. + + All of these commands end by printing two lines of output describing +the frame. The first line shows the frame number, the function name, +the arguments, and the source file and line number of execution in that +frame. The second line shows the text of that source line. + + For example: + + (gdb) up + #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) + at env.c:10 + 10 read_input_file (argv[i]); + + After such a printout, the 'list' command with no arguments prints +ten lines centered on the point of execution in the frame. You can also +edit the program at the point of execution with your favorite editing +program by typing 'edit'. *Note Printing Source Lines: List, for +details. + +'up-silently N' +'down-silently N' + These two commands are variants of 'up' and 'down', respectively; + they differ in that they do their work silently, without causing + display of the new frame. They are intended primarily for use in + GDB command scripts, where the output might be unnecessary and + distracting. + + +File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack + +8.5 Information About a Frame +============================= + +There are several other commands to print information about the selected +stack frame. + +'frame' +'f' + When used without any argument, this command does not change which + frame is selected, but prints a brief description of the currently + selected stack frame. It can be abbreviated 'f'. With an + argument, this command is used to select a stack frame. *Note + Selecting a Frame: Selection. + +'info frame' +'info f' + This command prints a verbose description of the selected stack + frame, including: + + * the address of the frame + * the address of the next frame down (called by this frame) + * the address of the next frame up (caller of this frame) + * the language in which the source code corresponding to this + frame is written + * the address of the frame's arguments + * the address of the frame's local variables + * the program counter saved in it (the address of execution in + the caller frame) + * which registers were saved in the frame + + The verbose description is useful when something has gone wrong + that has made the stack format fail to fit the usual conventions. + +'info frame ADDR' +'info f ADDR' + Print a verbose description of the frame at address ADDR, without + selecting that frame. The selected frame remains unchanged by this + command. This requires the same kind of address (more than one for + some architectures) that you specify in the 'frame' command. *Note + Selecting a Frame: Selection. + +'info args' + Print the arguments of the selected frame, each on a separate line. + +'info locals' + Print the local variables of the selected frame, each on a separate + line. These are all variables (declared either static or + automatic) accessible at the point of execution of the selected + frame. + + +File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top + +9 Examining Source Files +************************ + +GDB can print parts of your program's source, since the debugging +information recorded in the program tells GDB what source files were +used to build it. When your program stops, GDB spontaneously prints the +line where it stopped. Likewise, when you select a stack frame (*note +Selecting a Frame: Selection.), GDB prints the line where execution in +that frame has stopped. You can print other portions of source files by +explicit command. + + If you use GDB through its GNU Emacs interface, you may prefer to use +Emacs facilities to view source; see *note Using GDB under GNU Emacs: +Emacs. + +* Menu: + +* List:: Printing source lines +* Specify Location:: How to specify code locations +* Edit:: Editing source files +* Search:: Searching source files +* Source Path:: Specifying source directories +* Machine Code:: Source and machine code + + +File: gdb.info, Node: List, Next: Specify Location, Up: Source + +9.1 Printing Source Lines +========================= + +To print lines from a source file, use the 'list' command (abbreviated +'l'). By default, ten lines are printed. There are several ways to +specify what part of the file you want to print; see *note Specify +Location::, for the full list. + + Here are the forms of the 'list' command most commonly used: + +'list LINENUM' + Print lines centered around line number LINENUM in the current + source file. + +'list FUNCTION' + Print lines centered around the beginning of function FUNCTION. + +'list' + Print more lines. If the last lines printed were printed with a + 'list' command, this prints lines following the last lines printed; + however, if the last line printed was a solitary line printed as + part of displaying a stack frame (*note Examining the Stack: + Stack.), this prints lines centered around that line. + +'list -' + Print lines just before the lines last printed. + + By default, GDB prints ten source lines with any of these forms of +the 'list' command. You can change this using 'set listsize': + +'set listsize COUNT' +'set listsize unlimited' + Make the 'list' command display COUNT source lines (unless the + 'list' argument explicitly specifies some other number). Setting + COUNT to 'unlimited' or 0 means there's no limit. + +'show listsize' + Display the number of lines that 'list' prints. + + Repeating a 'list' command with discards the argument, so it is +equivalent to typing just 'list'. This is more useful than listing the +same lines again. An exception is made for an argument of '-'; that +argument is preserved in repetition so that each repetition moves up in +the source file. + + In general, the 'list' command expects you to supply zero, one or two +"linespecs". Linespecs specify source lines; there are several ways of +writing them (*note Specify Location::), but the effect is always to +specify some source line. + + Here is a complete description of the possible arguments for 'list': + +'list LINESPEC' + Print lines centered around the line specified by LINESPEC. + +'list FIRST,LAST' + Print lines from FIRST to LAST. Both arguments are linespecs. + When a 'list' command has two linespecs, and the source file of the + second linespec is omitted, this refers to the same source file as + the first linespec. + +'list ,LAST' + Print lines ending with LAST. + +'list FIRST,' + Print lines starting with FIRST. + +'list +' + Print lines just after the lines last printed. + +'list -' + Print lines just before the lines last printed. + +'list' + As described in the preceding table. + + +File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source + +9.2 Specifying a Location +========================= + +Several GDB commands accept arguments that specify a location of your +program's code. Since GDB is a source-level debugger, a location +usually specifies some line in the source code; for that reason, +locations are also known as "linespecs". + + Here are all the different ways of specifying a code location that +GDB understands: + +'LINENUM' + Specifies the line number LINENUM of the current source file. + +'-OFFSET' +'+OFFSET' + Specifies the line OFFSET lines before or after the "current line". + For the 'list' command, the current line is the last one printed; + for the breakpoint commands, this is the line at which execution + stopped in the currently selected "stack frame" (*note Frames: + Frames, for a description of stack frames.) When used as the + second of the two linespecs in a 'list' command, this specifies the + line OFFSET lines up or down from the first linespec. + +'FILENAME:LINENUM' + Specifies the line LINENUM in the source file FILENAME. If + FILENAME is a relative file name, then it will match any source + file name with the same trailing components. For example, if + FILENAME is 'gcc/expr.c', then it will match source file name of + '/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or + '/build/trunk/gcc/x-expr.c'. + +'FUNCTION' + Specifies the line that begins the body of the function FUNCTION. + For example, in C, this is the line with the open brace. + +'FUNCTION:LABEL' + Specifies the line where LABEL appears in FUNCTION. + +'FILENAME:FUNCTION' + Specifies the line that begins the body of the function FUNCTION in + the file FILENAME. You only need the file name with a function + name to avoid ambiguity when there are identically named functions + in different source files. + +'LABEL' + Specifies the line at which the label named LABEL appears. GDB + searches for the label in the function corresponding to the + currently selected stack frame. If there is no current selected + stack frame (for instance, if the inferior is not running), then + GDB will not search for a label. + +'*ADDRESS' + Specifies the program address ADDRESS. For line-oriented commands, + such as 'list' and 'edit', this specifies a source line that + contains ADDRESS. For 'break' and other breakpoint oriented + commands, this can be used to set breakpoints in parts of your + program which do not have debugging information or source files. + + Here ADDRESS may be any expression valid in the current working + language (*note working language: Languages.) that specifies a code + address. In addition, as a convenience, GDB extends the semantics + of expressions used in locations to cover the situations that + frequently happen during debugging. Here are the various forms of + ADDRESS: + + 'EXPRESSION' + Any expression valid in the current working language. + + 'FUNCADDR' + An address of a function or procedure derived from its name. + In C, C++, Java, Objective-C, Fortran, minimal, and assembly, + this is simply the function's name FUNCTION (and actually a + special case of a valid expression). In Pascal and Modula-2, + this is '&FUNCTION'. In Ada, this is 'FUNCTION'Address' + (although the Pascal form also works). + + This form specifies the address of the function's first + instruction, before the stack frame and arguments have been + set up. + + ''FILENAME'::FUNCADDR' + Like FUNCADDR above, but also specifies the name of the source + file explicitly. This is useful if the name of the function + does not specify the function unambiguously, e.g., if there + are several functions with identical names in different source + files. + +'-pstap|-probe-stap [OBJFILE:[PROVIDER:]]NAME' + The GNU/Linux tool 'SystemTap' provides a way for applications to + embed static probes. *Note Static Probe Points::, for more + information on finding and using static probes. This form of + linespec specifies the location of such a static probe. + + If OBJFILE is given, only probes coming from that shared library or + executable matching OBJFILE as a regular expression are considered. + If PROVIDER is given, then only probes from that provider are + considered. If several probes match the spec, GDB will insert a + breakpoint at each one of those probes. + + +File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source + +9.3 Editing Source Files +======================== + +To edit the lines in a source file, use the 'edit' command. The editing +program of your choice is invoked with the current line set to the +active line in the program. Alternatively, there are several ways to +specify what part of the file you want to print if you want to see other +parts of the program: + +'edit LOCATION' + Edit the source file specified by 'location'. Editing starts at + that LOCATION, e.g., at the specified source line of the specified + file. *Note Specify Location::, for all the possible forms of the + LOCATION argument; here are the forms of the 'edit' command most + commonly used: + + 'edit NUMBER' + Edit the current source file with NUMBER as the active line + number. + + 'edit FUNCTION' + Edit the file containing FUNCTION at the beginning of its + definition. + +9.3.1 Choosing your Editor +-------------------------- + +You can customize GDB to use any editor you want (1). By default, it is +'/bin/ex', but you can change this by setting the environment variable +'EDITOR' before using GDB. For example, to configure GDB to use the +'vi' editor, you could use these commands with the 'sh' shell: + EDITOR=/usr/bin/vi + export EDITOR + gdb ... + or in the 'csh' shell, + setenv EDITOR /usr/bin/vi + gdb ... + + ---------- Footnotes ---------- + + (1) The only restriction is that your editor (say 'ex'), recognizes +the following command-line syntax: + ex +NUMBER file + The optional numeric value +NUMBER specifies the number of the line +in the file where to start editing. + + +File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source + +9.4 Searching Source Files +========================== + +There are two commands for searching through the current source file for +a regular expression. + +'forward-search REGEXP' +'search REGEXP' + The command 'forward-search REGEXP' checks each line, starting with + the one following the last line listed, for a match for REGEXP. It + lists the line that is found. You can use the synonym 'search + REGEXP' or abbreviate the command name as 'fo'. + +'reverse-search REGEXP' + The command 'reverse-search REGEXP' checks each line, starting with + the one before the last line listed and going backward, for a match + for REGEXP. It lists the line that is found. You can abbreviate + this command as 'rev'. + + +File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source + +9.5 Specifying Source Directories +================================= + +Executable programs sometimes do not record the directories of the +source files from which they were compiled, just the names. Even when +they do, the directories could be moved between the compilation and your +debugging session. GDB has a list of directories to search for source +files; this is called the "source path". Each time GDB wants a source +file, it tries all the directories in the list, in the order they are +present in the list, until it finds a file with the desired name. + + For example, suppose an executable references the file +'/usr/src/foo-1.0/lib/foo.c', and our source path is '/mnt/cross'. The +file is first looked up literally; if this fails, +'/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails, +'/mnt/cross/foo.c' is opened; if this fails, an error message is +printed. GDB does not look up the parts of the source file name, such +as '/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of +the source path are not searched: if the source path is '/mnt/cross', +and the binary refers to 'foo.c', GDB would not find it under +'/mnt/cross/usr/src/foo-1.0/lib'. + + Plain file names, relative file names with leading directories, file +names containing dots, etc. are all treated as described above; for +instance, if the source path is '/mnt/cross', and the source file is +recorded as '../lib/foo.c', GDB would first try '../lib/foo.c', then +'/mnt/cross/../lib/foo.c', and after that--'/mnt/cross/foo.c'. + + Note that the executable search path is _not_ used to locate the +source files. + + Whenever you reset or rearrange the source path, GDB clears out any +information it has cached about where source files are found and where +each line is in the file. + + When you start GDB, its source path includes only 'cdir' and 'cwd', +in that order. To add other directories, use the 'directory' command. + + The search path is used to find both program source files and GDB +script files (read using the '-command' option and 'source' command). + + In addition to the source path, GDB provides a set of commands that +manage a list of source path substitution rules. A "substitution rule" +specifies how to rewrite source directories stored in the program's +debug information in case the sources were moved to a different +directory between compilation and debugging. A rule is made of two +strings, the first specifying what needs to be rewritten in the path, +and the second specifying how it should be rewritten. In *note set +substitute-path::, we name these two parts FROM and TO respectively. +GDB does a simple string replacement of FROM with TO at the start of the +directory part of the source file name, and uses that result instead of +the original file name to look up the sources. + + Using the previous example, suppose the 'foo-1.0' tree has been moved +from '/usr/src' to '/mnt/cross', then you can tell GDB to replace +'/usr/src' in all source path names with '/mnt/cross'. The first lookup +will then be '/mnt/cross/foo-1.0/lib/foo.c' in place of the original +location of '/usr/src/foo-1.0/lib/foo.c'. To define a source path +substitution rule, use the 'set substitute-path' command (*note set +substitute-path::). + + To avoid unexpected substitution results, a rule is applied only if +the FROM part of the directory name ends at a directory separator. For +instance, a rule substituting '/usr/source' into '/mnt/cross' will be +applied to '/usr/source/foo-1.0' but not to '/usr/sourceware/foo-2.0'. +And because the substitution is applied only at the beginning of the +directory name, this rule will not be applied to +'/root/usr/source/baz.c' either. + + In many cases, you can achieve the same result using the 'directory' +command. However, 'set substitute-path' can be more efficient in the +case where the sources are organized in a complex tree with multiple +subdirectories. With the 'directory' command, you need to add each +subdirectory of your project. If you moved the entire tree while +preserving its internal organization, then 'set substitute-path' allows +you to direct the debugger to all the sources with one single command. + + 'set substitute-path' is also more than just a shortcut command. The +source path is only used if the file at the original location no longer +exists. On the other hand, 'set substitute-path' modifies the debugger +behavior to look at the rewritten location instead. So, if for any +reason a source file that is not relevant to your executable is located +at the original location, a substitution rule is the only method +available to point GDB at the new location. + + You can configure a default source path substitution rule by +configuring GDB with the '--with-relocated-sources=DIR' option. The DIR +should be the name of a directory under GDB's configured prefix (set +with '--prefix' or '--exec-prefix'), and directory names in debug +information under DIR will be adjusted automatically if the installed +GDB is moved to a new location. This is useful if GDB, libraries or +executables with debug information and corresponding source code are +being moved together. + +'directory DIRNAME ...' +'dir DIRNAME ...' + Add directory DIRNAME to the front of the source path. Several + directory names may be given to this command, separated by ':' (';' + on MS-DOS and MS-Windows, where ':' usually appears as part of + absolute file names) or whitespace. You may specify a directory + that is already in the source path; this moves it forward, so GDB + searches it sooner. + + You can use the string '$cdir' to refer to the compilation + directory (if one is recorded), and '$cwd' to refer to the current + working directory. '$cwd' is not the same as '.'--the former + tracks the current working directory as it changes during your GDB + session, while the latter is immediately expanded to the current + directory at the time you add an entry to the source path. + +'directory' + Reset the source path to its default value ('$cdir:$cwd' on Unix + systems). This requires confirmation. + +'set directories PATH-LIST' + Set the source path to PATH-LIST. '$cdir:$cwd' are added if + missing. + +'show directories' + Print the source path: show which directories it contains. + +'set substitute-path FROM TO' + Define a source path substitution rule, and add it at the end of + the current list of existing substitution rules. If a rule with + the same FROM was already defined, then the old rule is also + deleted. + + For example, if the file '/foo/bar/baz.c' was moved to + '/mnt/cross/baz.c', then the command + + (gdb) set substitute-path /usr/src /mnt/cross + + will tell GDB to replace '/usr/src' with '/mnt/cross', which will + allow GDB to find the file 'baz.c' even though it was moved. + + In the case when more than one substitution rule have been defined, + the rules are evaluated one by one in the order where they have + been defined. The first one matching, if any, is selected to + perform the substitution. + + For instance, if we had entered the following commands: + + (gdb) set substitute-path /usr/src/include /mnt/include + (gdb) set substitute-path /usr/src /mnt/src + + GDB would then rewrite '/usr/src/include/defs.h' into + '/mnt/include/defs.h' by using the first rule. However, it would + use the second rule to rewrite '/usr/src/lib/foo.c' into + '/mnt/src/lib/foo.c'. + +'unset substitute-path [path]' + If a path is specified, search the current list of substitution + rules for a rule that would rewrite that path. Delete that rule if + found. A warning is emitted by the debugger if no rule could be + found. + + If no path is specified, then all substitution rules are deleted. + +'show substitute-path [path]' + If a path is specified, then print the source path substitution + rule which would rewrite that path, if any. + + If no path is specified, then print all existing source path + substitution rules. + + If your source path is cluttered with directories that are no longer +of interest, GDB may sometimes cause confusion by finding the wrong +versions of source. You can correct the situation as follows: + + 1. Use 'directory' with no argument to reset the source path to its + default value. + + 2. Use 'directory' with suitable arguments to reinstall the + directories you want in the source path. You can add all the + directories in one command. + + +File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source + +9.6 Source and Machine Code +=========================== + +You can use the command 'info line' to map source lines to program +addresses (and vice versa), and the command 'disassemble' to display a +range of addresses as machine instructions. You can use the command +'set disassemble-next-line' to set whether to disassemble next source +line when execution stops. When run under GNU Emacs mode, the 'info +line' command causes the arrow to point to the line specified. Also, +'info line' prints addresses in symbolic form as well as hex. + +'info line LINESPEC' + Print the starting and ending addresses of the compiled code for + source line LINESPEC. You can specify source lines in any of the + ways documented in *note Specify Location::. + + For example, we can use 'info line' to discover the location of the +object code for the first line of function 'm4_changequote': + + (gdb) info line m4_changequote + Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. + +We can also inquire (using '*ADDR' as the form for LINESPEC) what source +line covers a particular address: + (gdb) info line *0x63ff + Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. + + After 'info line', the default address for the 'x' command is changed +to the starting address of the line, so that 'x/i' is sufficient to +begin examining the machine code (*note Examining Memory: Memory.). +Also, this address is saved as the value of the convenience variable +'$_' (*note Convenience Variables: Convenience Vars.). + +'disassemble' +'disassemble /m' +'disassemble /r' + This specialized command dumps a range of memory as machine + instructions. It can also print mixed source+disassembly by + specifying the '/m' modifier and print the raw instructions in hex + as well as in symbolic form by specifying the '/r'. The default + memory range is the function surrounding the program counter of the + selected frame. A single argument to this command is a program + counter value; GDB dumps the function surrounding this value. When + two arguments are given, they should be separated by a comma, + possibly surrounded by whitespace. The arguments specify a range + of addresses to dump, in one of two forms: + + 'START,END' + the addresses from START (inclusive) to END (exclusive) + 'START,+LENGTH' + the addresses from START (inclusive) to 'START+LENGTH' + (exclusive). + + When 2 arguments are specified, the name of the function is also + printed (since there could be several functions in the given + range). + + The argument(s) can be any expression yielding a numeric value, + such as '0x32c4', '&main+10' or '$pc - 8'. + + If the range of memory being disassembled contains current program + counter, the instruction at that location is shown with a '=>' + marker. + + The following example shows the disassembly of a range of addresses +of HP PA-RISC 2.0 code: + + (gdb) disas 0x32c4, 0x32e4 + Dump of assembler code from 0x32c4 to 0x32e4: + 0x32c4 : addil 0,dp + 0x32c8 : ldw 0x22c(sr0,r1),r26 + 0x32cc : ldil 0x3000,r31 + 0x32d0 : ble 0x3f8(sr4,r31) + 0x32d4 : ldo 0(r31),rp + 0x32d8 : addil -0x800,dp + 0x32dc : ldo 0x588(r1),r26 + 0x32e0 : ldil 0x3000,r31 + End of assembler dump. + + Here is an example showing mixed source+assembly for Intel x86, when +the program is stopped just after function prologue: + + (gdb) disas /m main + Dump of assembler code for function main: + 5 { + 0x08048330 <+0>: push %ebp + 0x08048331 <+1>: mov %esp,%ebp + 0x08048333 <+3>: sub $0x8,%esp + 0x08048336 <+6>: and $0xfffffff0,%esp + 0x08048339 <+9>: sub $0x10,%esp + + 6 printf ("Hello.\n"); + => 0x0804833c <+12>: movl $0x8048440,(%esp) + 0x08048343 <+19>: call 0x8048284 + + 7 return 0; + 8 } + 0x08048348 <+24>: mov $0x0,%eax + 0x0804834d <+29>: leave + 0x0804834e <+30>: ret + + End of assembler dump. + + Here is another example showing raw instructions in hex for AMD +x86-64, + + (gdb) disas /r 0x400281,+10 + Dump of assembler code from 0x400281 to 0x40028b: + 0x0000000000400281: 38 36 cmp %dh,(%rsi) + 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax + 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) + 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al + End of assembler dump. + + Addresses cannot be specified as a linespec (*note Specify +Location::). So, for example, if you want to disassemble function 'bar' +in file 'foo.c', you must type 'disassemble 'foo.c'::bar' and not +'disassemble foo.c:bar'. + + Some architectures have more than one commonly-used set of +instruction mnemonics or other syntax. + + For programs that were dynamically linked and use shared libraries, +instructions that call functions or branch to locations in the shared +libraries might show a seemingly bogus location--it's actually a +location of the relocation table. On some architectures, GDB might be +able to resolve these to actual function names. + +'set disassembly-flavor INSTRUCTION-SET' + Select the instruction set to use when disassembling the program + via the 'disassemble' or 'x/i' commands. + + Currently this command is only defined for the Intel x86 family. + You can set INSTRUCTION-SET to either 'intel' or 'att'. The + default is 'att', the AT&T flavor used by default by Unix + assemblers for x86-based targets. + +'show disassembly-flavor' + Show the current setting of the disassembly flavor. + +'set disassemble-next-line' +'show disassemble-next-line' + Control whether or not GDB will disassemble the next source line or + instruction when execution stops. If ON, GDB will display + disassembly of the next source line when execution of the program + being debugged stops. This is _in addition_ to displaying the + source line itself, which GDB always does if possible. If the next + source line cannot be displayed for some reason (e.g., if GDB + cannot find the source file, or there's no line info in the debug + info), GDB will display disassembly of the next _instruction_ + instead of showing the next source line. If AUTO, GDB will display + disassembly of next instruction only if the source line cannot be + displayed. This setting causes GDB to display some feedback when + you step through a function with no line info or whose source file + is unavailable. The default is OFF, which means never display the + disassembly of the next line or instruction. + + +File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top + +10 Examining Data +***************** + +The usual way to examine data in your program is with the 'print' +command (abbreviated 'p'), or its synonym 'inspect'. It evaluates and +prints the value of an expression of the language your program is +written in (*note Using GDB with Different Languages: Languages.). It +may also print the expression using a Python-based pretty-printer (*note +Pretty Printing::). + +'print EXPR' +'print /F EXPR' + EXPR is an expression (in the source language). By default the + value of EXPR is printed in a format appropriate to its data type; + you can choose a different format by specifying '/F', where F is a + letter specifying the format; see *note Output Formats: Output + Formats. + +'print' +'print /F' + If you omit EXPR, GDB displays the last value again (from the + "value history"; *note Value History: Value History.). This allows + you to conveniently inspect the same value in an alternative + format. + + A more low-level way of examining data is with the 'x' command. It +examines data in memory at a specified address and prints it in a +specified format. *Note Examining Memory: Memory. + + If you are interested in information about types, or about how the +fields of a struct or a class are declared, use the 'ptype EXP' command +rather than 'print'. *Note Examining the Symbol Table: Symbols. + + Another way of examining values of expressions and type information +is through the Python extension command 'explore' (available only if the +GDB build is configured with '--with-python'). It offers an interactive +way to start at the highest level (or, the most abstract level) of the +data type of an expression (or, the data type itself) and explore all +the way down to leaf scalar values/fields embedded in the higher level +data types. + +'explore ARG' + ARG is either an expression (in the source language), or a type + visible in the current context of the program being debugged. + + The working of the 'explore' command can be illustrated with an +example. If a data type 'struct ComplexStruct' is defined in your C +program as + + struct SimpleStruct + { + int i; + double d; + }; + + struct ComplexStruct + { + struct SimpleStruct *ss_p; + int arr[10]; + }; + +followed by variable declarations as + + struct SimpleStruct ss = { 10, 1.11 }; + struct ComplexStruct cs = { &ss, { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 } }; + +then, the value of the variable 'cs' can be explored using the 'explore' +command as follows. + + (gdb) explore cs + The value of `cs' is a struct/class of type `struct ComplexStruct' with + the following fields: + + ss_p = + arr = + + Enter the field number of choice: + +Since the fields of 'cs' are not scalar values, you are being prompted +to chose the field you want to explore. Let's say you choose the field +'ss_p' by entering '0'. Then, since this field is a pointer, you will +be asked if it is pointing to a single value. From the declaration of +'cs' above, it is indeed pointing to a single value, hence you enter +'y'. If you enter 'n', then you will be asked if it were pointing to an +array of values, in which case this field will be explored as if it were +an array. + + `cs.ss_p' is a pointer to a value of type `struct SimpleStruct' + Continue exploring it as a pointer to a single value [y/n]: y + The value of `*(cs.ss_p)' is a struct/class of type `struct + SimpleStruct' with the following fields: + + i = 10 .. (Value of type `int') + d = 1.1100000000000001 .. (Value of type `double') + + Press enter to return to parent value: + +If the field 'arr' of 'cs' was chosen for exploration by entering '1' +earlier, then since it is as array, you will be prompted to enter the +index of the element in the array that you want to explore. + + `cs.arr' is an array of `int'. + Enter the index of the element you want to explore in `cs.arr': 5 + + `(cs.arr)[5]' is a scalar value of type `int'. + + (cs.arr)[5] = 4 + + Press enter to return to parent value: + + In general, at any stage of exploration, you can go deeper towards +the leaf values by responding to the prompts appropriately, or hit the +return key to return to the enclosing data structure (the higher level +data structure). + + Similar to exploring values, you can use the 'explore' command to +explore types. Instead of specifying a value (which is typically a +variable name or an expression valid in the current context of the +program being debugged), you specify a type name. If you consider the +same example as above, your can explore the type 'struct ComplexStruct' +by passing the argument 'struct ComplexStruct' to the 'explore' command. + + (gdb) explore struct ComplexStruct + +By responding to the prompts appropriately in the subsequent interactive +session, you can explore the type 'struct ComplexStruct' in a manner +similar to how the value 'cs' was explored in the above example. + + The 'explore' command also has two sub-commands, 'explore value' and +'explore type'. The former sub-command is a way to explicitly specify +that value exploration of the argument is being invoked, while the +latter is a way to explicitly specify that type exploration of the +argument is being invoked. + +'explore value EXPR' + This sub-command of 'explore' explores the value of the expression + EXPR (if EXPR is an expression valid in the current context of the + program being debugged). The behavior of this command is identical + to that of the behavior of the 'explore' command being passed the + argument EXPR. + +'explore type ARG' + This sub-command of 'explore' explores the type of ARG (if ARG is a + type visible in the current context of program being debugged), or + the type of the value/expression ARG (if ARG is an expression valid + in the current context of the program being debugged). If ARG is a + type, then the behavior of this command is identical to that of the + 'explore' command being passed the argument ARG. If ARG is an + expression, then the behavior of this command will be identical to + that of the 'explore' command being passed the type of ARG as the + argument. + +* Menu: + +* Expressions:: Expressions +* Ambiguous Expressions:: Ambiguous Expressions +* Variables:: Program variables +* Arrays:: Artificial arrays +* Output Formats:: Output formats +* Memory:: Examining memory +* Auto Display:: Automatic display +* Print Settings:: Print settings +* Pretty Printing:: Python pretty printing +* Value History:: Value history +* Convenience Vars:: Convenience variables +* Convenience Funs:: Convenience functions +* Registers:: Registers +* Floating Point Hardware:: Floating point hardware +* Vector Unit:: Vector Unit +* OS Information:: Auxiliary data provided by operating system +* Memory Region Attributes:: Memory region attributes +* Dump/Restore Files:: Copy between memory and a file +* Core File Generation:: Cause a program dump its core +* Character Sets:: Debugging programs that use a different + character set than GDB does +* Caching Target Data:: Data caching for targets +* Searching Memory:: Searching memory for a sequence of bytes + + +File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data + +10.1 Expressions +================ + +'print' and many other GDB commands accept an expression and compute its +value. Any kind of constant, variable or operator defined by the +programming language you are using is valid in an expression in GDB. +This includes conditional expressions, function calls, casts, and string +constants. It also includes preprocessor macros, if you compiled your +program to include this information; see *note Compilation::. + + GDB supports array constants in expressions input by the user. The +syntax is {ELEMENT, ELEMENT...}. For example, you can use the command +'print {1, 2, 3}' to create an array of three integers. If you pass an +array to a function or assign it to a program variable, GDB copies the +array to memory that is 'malloc'ed in the target program. + + Because C is so widespread, most of the expressions shown in examples +in this manual are in C. *Note Using GDB with Different Languages: +Languages, for information on how to use expressions in other languages. + + In this section, we discuss operators that you can use in GDB +expressions regardless of your programming language. + + Casts are supported in all languages, not just in C, because it is so +useful to cast a number into a pointer in order to examine a structure +at that address in memory. + + GDB supports these operators, in addition to those common to +programming languages: + +'@' + '@' is a binary operator for treating parts of memory as arrays. + *Note Artificial Arrays: Arrays, for more information. + +'::' + '::' allows you to specify a variable in terms of the file or + function where it is defined. *Note Program Variables: Variables. + +'{TYPE} ADDR' + Refers to an object of type TYPE stored at address ADDR in memory. + ADDR may be any expression whose value is an integer or pointer + (but parentheses are required around binary operators, just as in a + cast). This construct is allowed regardless of what kind of data + is normally supposed to reside at ADDR. + + +File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data + +10.2 Ambiguous Expressions +========================== + +Expressions can sometimes contain some ambiguous elements. For +instance, some programming languages (notably Ada, C++ and Objective-C) +permit a single function name to be defined several times, for +application in different contexts. This is called "overloading". +Another example involving Ada is generics. A "generic package" is +similar to C++ templates and is typically instantiated several times, +resulting in the same function name being defined in different contexts. + + In some cases and depending on the language, it is possible to adjust +the expression to remove the ambiguity. For instance in C++, you can +specify the signature of the function you want to break on, as in 'break +FUNCTION(TYPES)'. In Ada, using the fully qualified name of your +function often makes the expression unambiguous as well. + + When an ambiguity that needs to be resolved is detected, the debugger +has the capability to display a menu of numbered choices for each +possibility, and then waits for the selection with the prompt '>'. The +first option is always '[0] cancel', and typing '0 ' aborts the +current command. If the command in which the expression was used allows +more than one choice to be selected, the next option in the menu is '[1] +all', and typing '1 ' selects all possible choices. + + For example, the following session excerpt shows an attempt to set a +breakpoint at the overloaded symbol 'String::after'. We choose three +particular definitions of that function name: + + (gdb) b String::after + [0] cancel + [1] all + [2] file:String.cc; line number:867 + [3] file:String.cc; line number:860 + [4] file:String.cc; line number:875 + [5] file:String.cc; line number:853 + [6] file:String.cc; line number:846 + [7] file:String.cc; line number:735 + > 2 4 6 + Breakpoint 1 at 0xb26c: file String.cc, line 867. + Breakpoint 2 at 0xb344: file String.cc, line 875. + Breakpoint 3 at 0xafcc: file String.cc, line 846. + Multiple breakpoints were set. + Use the "delete" command to delete unwanted + breakpoints. + (gdb) + +'set multiple-symbols MODE' + + This option allows you to adjust the debugger behavior when an + expression is ambiguous. + + By default, MODE is set to 'all'. If the command with which the + expression is used allows more than one choice, then GDB + automatically selects all possible choices. For instance, + inserting a breakpoint on a function using an ambiguous name + results in a breakpoint inserted on each possible match. However, + if a unique choice must be made, then GDB uses the menu to help you + disambiguate the expression. For instance, printing the address of + an overloaded function will result in the use of the menu. + + When MODE is set to 'ask', the debugger always uses the menu when + an ambiguity is detected. + + Finally, when MODE is set to 'cancel', the debugger reports an + error due to the ambiguity and the command is aborted. + +'show multiple-symbols' + Show the current value of the 'multiple-symbols' setting. + + +File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data + +10.3 Program Variables +====================== + +The most common kind of expression to use is the name of a variable in +your program. + + Variables in expressions are understood in the selected stack frame +(*note Selecting a Frame: Selection.); they must be either: + + * global (or file-static) + +or + + * visible according to the scope rules of the programming language + from the point of execution in that frame + +This means that in the function + + foo (a) + int a; + { + bar (a); + { + int b = test (); + bar (b); + } + } + +you can examine and use the variable 'a' whenever your program is +executing within the function 'foo', but you can only use or examine the +variable 'b' while your program is executing inside the block where 'b' +is declared. + + There is an exception: you can refer to a variable or function whose +scope is a single source file even if the current execution point is not +in this file. But it is possible to have more than one such variable or +function with the same name (in different source files). If that +happens, referring to that name has unpredictable effects. If you wish, +you can specify a static variable in a particular function or file by +using the colon-colon ('::') notation: + + FILE::VARIABLE + FUNCTION::VARIABLE + +Here FILE or FUNCTION is the name of the context for the static +VARIABLE. In the case of file names, you can use quotes to make sure +GDB parses the file name as a single word--for example, to print a +global value of 'x' defined in 'f2.c': + + (gdb) p 'f2.c'::x + + The '::' notation is normally used for referring to static variables, +since you typically disambiguate uses of local variables in functions by +selecting the appropriate frame and using the simple name of the +variable. However, you may also use this notation to refer to local +variables in frames enclosing the selected frame: + + void + foo (int a) + { + if (a < 10) + bar (a); + else + process (a); /* Stop here */ + } + + int + bar (int a) + { + foo (a + 5); + } + +For example, if there is a breakpoint at the commented line, here is +what you might see when the program stops after executing the call +'bar(0)': + + (gdb) p a + $1 = 10 + (gdb) p bar::a + $2 = 5 + (gdb) up 2 + #2 0x080483d0 in foo (a=5) at foobar.c:12 + (gdb) p a + $3 = 5 + (gdb) p bar::a + $4 = 0 + + These uses of '::' are very rarely in conflict with the very similar +use of the same notation in C++. When they are in conflict, the C++ +meaning takes precedence; however, this can be overridden by quoting the +file or function name with single quotes. + + For example, suppose the program is stopped in a method of a class +that has a field named 'includefile', and there is also an include file +named 'includefile' that defines a variable, 'some_global'. + + (gdb) p includefile + $1 = 23 + (gdb) p includefile::some_global + A syntax error in expression, near `'. + (gdb) p 'includefile'::some_global + $2 = 27 + + _Warning:_ Occasionally, a local variable may appear to have the + wrong value at certain points in a function--just after entry to a + new scope, and just before exit. + You may see this problem when you are stepping by machine +instructions. This is because, on most machines, it takes more than one +instruction to set up a stack frame (including local variable +definitions); if you are stepping by machine instructions, variables may +appear to have the wrong values until the stack frame is completely +built. On exit, it usually also takes more than one machine instruction +to destroy a stack frame; after you begin stepping through that group of +instructions, local variable definitions may be gone. + + This may also happen when the compiler does significant +optimizations. To be sure of always seeing accurate values, turn off +all optimization when compiling. + + Another possible effect of compiler optimizations is to optimize +unused variables out of existence, or assign variables to registers (as +opposed to memory addresses). Depending on the support for such cases +offered by the debug info format used by the compiler, GDB might not be +able to display values for such local variables. If that happens, GDB +will print a message like this: + + No symbol "foo" in current context. + + To solve such problems, either recompile without optimizations, or +use a different debug info format, if the compiler supports several such +formats. *Note Compilation::, for more information on choosing compiler +options. *Note C and C++: C, for more information about debug info +formats that are best suited to C++ programs. + + If you ask to print an object whose contents are unknown to GDB, +e.g., because its data type is not completely specified by the debug +information, GDB will say ''. *Note incomplete type: +Symbols, for more about this. + + If you append '@entry' string to a function parameter name you get +its value at the time the function got called. If the value is not +available an error message is printed. Entry values are available only +with some compilers. Entry values are normally also printed at the +function parameter list according to *note set print entry-values::. + + Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29 + 29 i++; + (gdb) next + 30 e (i); + (gdb) print i + $1 = 31 + (gdb) print i@entry + $2 = 30 + + Strings are identified as arrays of 'char' values without specified +signedness. Arrays of either 'signed char' or 'unsigned char' get +printed as arrays of 1 byte sized integers. '-fsigned-char' or +'-funsigned-char' GCC options have no effect as GDB defines literal +string type '"char"' as 'char' without a sign. For program code + + char var0[] = "A"; + signed char var1[] = "A"; + + You get during debugging + (gdb) print var0 + $1 = "A" + (gdb) print var1 + $2 = {65 'A', 0 '\0'} + + +File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data + +10.4 Artificial Arrays +====================== + +It is often useful to print out several successive objects of the same +type in memory; a section of an array, or an array of dynamically +determined size for which only a pointer exists in the program. + + You can do this by referring to a contiguous span of memory as an +"artificial array", using the binary operator '@'. The left operand of +'@' should be the first element of the desired array and be an +individual object. The right operand should be the desired length of +the array. The result is an array value whose elements are all of the +type of the left argument. The first element is actually the left +argument; the second element comes from bytes of memory immediately +following those that hold the first element, and so on. Here is an +example. If a program says + + int *array = (int *) malloc (len * sizeof (int)); + +you can print the contents of 'array' with + + p *array@len + + The left operand of '@' must reside in memory. Array values made +with '@' in this way behave just like other arrays in terms of +subscripting, and are coerced to pointers when used in expressions. +Artificial arrays most often appear in expressions via the value history +(*note Value History: Value History.), after printing one out. + + Another way to create an artificial array is to use a cast. This +re-interprets a value as if it were an array. The value need not be in +memory: + (gdb) p/x (short[2])0x12345678 + $1 = {0x1234, 0x5678} + + As a convenience, if you leave the array length out (as in +'(TYPE[])VALUE') GDB calculates the size to fill the value (as +'sizeof(VALUE)/sizeof(TYPE)': + (gdb) p/x (short[])0x12345678 + $2 = {0x1234, 0x5678} + + Sometimes the artificial array mechanism is not quite enough; in +moderately complex data structures, the elements of interest may not +actually be adjacent--for example, if you are interested in the values +of pointers in an array. One useful work-around in this situation is to +use a convenience variable (*note Convenience Variables: Convenience +Vars.) as a counter in an expression that prints the first interesting +value, and then repeat that expression via . For instance, suppose +you have an array 'dtab' of pointers to structures, and you are +interested in the values of a field 'fv' in each structure. Here is an +example of what you might type: + + set $i = 0 + p dtab[$i++]->fv + + + ... + + +File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data + +10.5 Output Formats +=================== + +By default, GDB prints a value according to its data type. Sometimes +this is not what you want. For example, you might want to print a +number in hex, or a pointer in decimal. Or you might want to view data +in memory at a certain address as a character string or as an +instruction. To do these things, specify an "output format" when you +print a value. + + The simplest use of output formats is to say how to print a value +already computed. This is done by starting the arguments of the 'print' +command with a slash and a format letter. The format letters supported +are: + +'x' + Regard the bits of the value as an integer, and print the integer + in hexadecimal. + +'d' + Print as integer in signed decimal. + +'u' + Print as integer in unsigned decimal. + +'o' + Print as integer in octal. + +'t' + Print as integer in binary. The letter 't' stands for "two". (1) + +'a' + Print as an address, both absolute in hexadecimal and as an offset + from the nearest preceding symbol. You can use this format used to + discover where (in what function) an unknown address is located: + + (gdb) p/a 0x54320 + $3 = 0x54320 <_initialize_vx+396> + + The command 'info symbol 0x54320' yields similar results. *Note + info symbol: Symbols. + +'c' + Regard as an integer and print it as a character constant. This + prints both the numerical value and its character representation. + The character representation is replaced with the octal escape + '\nnn' for characters outside the 7-bit ASCII range. + + Without this format, GDB displays 'char', 'unsigned char', and 'signed char' + data as character constants. Single-byte members of vectors are + displayed as integer data. + +'f' + Regard the bits of the value as a floating point number and print + using typical floating point syntax. + +'s' + Regard as a string, if possible. With this format, pointers to + single-byte data are displayed as null-terminated strings and + arrays of single-byte data are displayed as fixed-length strings. + Other values are displayed in their natural types. + + Without this format, GDB displays pointers to and arrays of 'char', + 'unsigned char', and 'signed char' as strings. Single-byte members + of a vector are displayed as an integer array. + +'z' + Like 'x' formatting, the value is treated as an integer and printed + as hexadecimal, but leading zeros are printed to pad the value to + the size of the integer type. + +'r' + Print using the 'raw' formatting. By default, GDB will use a + Python-based pretty-printer, if one is available (*note Pretty + Printing::). This typically results in a higher-level display of + the value's contents. The 'r' format bypasses any Python + pretty-printer which might exist. + + For example, to print the program counter in hex (*note Registers::), +type + + p/x $pc + +Note that no space is required before the slash; this is because command +names in GDB cannot contain a slash. + + To reprint the last value in the value history with a different +format, you can use the 'print' command with just a format and no +expression. For example, 'p/x' reprints the last value in hex. + + ---------- Footnotes ---------- + + (1) 'b' cannot be used because these format letters are also used +with the 'x' command, where 'b' stands for "byte"; see *note Examining +Memory: Memory. + + +File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data + +10.6 Examining Memory +===================== + +You can use the command 'x' (for "examine") to examine memory in any of +several formats, independently of your program's data types. + +'x/NFU ADDR' +'x ADDR' +'x' + Use the 'x' command to examine memory. + + N, F, and U are all optional parameters that specify how much memory +to display and how to format it; ADDR is an expression giving the +address where you want to start displaying memory. If you use defaults +for NFU, you need not type the slash '/'. Several commands set +convenient defaults for ADDR. + +N, the repeat count + The repeat count is a decimal integer; the default is 1. It + specifies how much memory (counting by units U) to display. + +F, the display format + The display format is one of the formats used by 'print' ('x', 'd', + 'u', 'o', 't', 'a', 'c', 'f', 's'), and in addition 'i' (for + machine instructions). The default is 'x' (hexadecimal) initially. + The default changes each time you use either 'x' or 'print'. + +U, the unit size + The unit size is any of + + 'b' + Bytes. + 'h' + Halfwords (two bytes). + 'w' + Words (four bytes). This is the initial default. + 'g' + Giant words (eight bytes). + + Each time you specify a unit size with 'x', that size becomes the + default unit the next time you use 'x'. For the 'i' format, the + unit size is ignored and is normally not written. For the 's' + format, the unit size defaults to 'b', unless it is explicitly + given. Use 'x /hs' to display 16-bit char strings and 'x /ws' to + display 32-bit strings. The next use of 'x /s' will again display + 8-bit strings. Note that the results depend on the programming + language of the current compilation unit. If the language is C, + the 's' modifier will use the UTF-16 encoding while 'w' will use + UTF-32. The encoding is set by the programming language and cannot + be altered. + +ADDR, starting display address + ADDR is the address where you want GDB to begin displaying memory. + The expression need not have a pointer value (though it may); it is + always interpreted as an integer address of a byte of memory. + *Note Expressions: Expressions, for more information on + expressions. The default for ADDR is usually just after the last + address examined--but several other commands also set the default + address: 'info breakpoints' (to the address of the last breakpoint + listed), 'info line' (to the starting address of a line), and + 'print' (if you use it to display a value from memory). + + For example, 'x/3uh 0x54320' is a request to display three halfwords +('h') of memory, formatted as unsigned decimal integers ('u'), starting +at address '0x54320'. 'x/4xw $sp' prints the four words ('w') of memory +above the stack pointer (here, '$sp'; *note Registers: Registers.) in +hexadecimal ('x'). + + Since the letters indicating unit sizes are all distinct from the +letters specifying output formats, you do not have to remember whether +unit size or format comes first; either order works. The output +specifications '4xw' and '4wx' mean exactly the same thing. (However, +the count N must come first; 'wx4' does not work.) + + Even though the unit size U is ignored for the formats 's' and 'i', +you might still want to use a count N; for example, '3i' specifies that +you want to see three machine instructions, including any operands. For +convenience, especially when used with the 'display' command, the 'i' +format also prints branch delay slot instructions, if any, beyond the +count specified, which immediately follow the last instruction that is +within the count. The command 'disassemble' gives an alternative way of +inspecting machine instructions; see *note Source and Machine Code: +Machine Code. + + All the defaults for the arguments to 'x' are designed to make it +easy to continue scanning memory with minimal specifications each time +you use 'x'. For example, after you have inspected three machine +instructions with 'x/3i ADDR', you can inspect the next seven with just +'x/7'. If you use to repeat the 'x' command, the repeat count N +is used again; the other arguments default as for successive uses of +'x'. + + When examining machine instructions, the instruction at current +program counter is shown with a '=>' marker. For example: + + (gdb) x/5i $pc-6 + 0x804837f : mov %esp,%ebp + 0x8048381 : push %ecx + 0x8048382 : sub $0x4,%esp + => 0x8048385 : movl $0x8048460,(%esp) + 0x804838c : call 0x80482d4 + + The addresses and contents printed by the 'x' command are not saved +in the value history because there is often too much of them and they +would get in the way. Instead, GDB makes these values available for +subsequent use in expressions as values of the convenience variables +'$_' and '$__'. After an 'x' command, the last address examined is +available for use in expressions in the convenience variable '$_'. The +contents of that address, as examined, are available in the convenience +variable '$__'. + + If the 'x' command has a repeat count, the address and contents saved +are from the last memory unit printed; this is not the same as the last +address printed if several units were printed on the last line of +output. + + When you are debugging a program running on a remote target machine +(*note Remote Debugging::), you may wish to verify the program's image +in the remote machine's memory against the executable file you +downloaded to the target. The 'compare-sections' command is provided +for such situations. + +'compare-sections [SECTION-NAME]' + Compare the data of a loadable section SECTION-NAME in the + executable file of the program being debugged with the same section + in the remote machine's memory, and report any mismatches. With no + arguments, compares all loadable sections. This command's + availability depends on the target's support for the '"qCRC"' + remote request. + + +File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data + +10.7 Automatic Display +====================== + +If you find that you want to print the value of an expression frequently +(to see how it changes), you might want to add it to the "automatic +display list" so that GDB prints its value each time your program stops. +Each expression added to the list is given a number to identify it; to +remove an expression from the list, you specify that number. The +automatic display looks like this: + + 2: foo = 38 + 3: bar[5] = (struct hack *) 0x3804 + +This display shows item numbers, expressions and their current values. +As with displays you request manually using 'x' or 'print', you can +specify the output format you prefer; in fact, 'display' decides whether +to use 'print' or 'x' depending your format specification--it uses 'x' +if you specify either the 'i' or 's' format, or a unit size; otherwise +it uses 'print'. + +'display EXPR' + Add the expression EXPR to the list of expressions to display each + time your program stops. *Note Expressions: Expressions. + + 'display' does not repeat if you press again after using it. + +'display/FMT EXPR' + For FMT specifying only a display format and not a size or count, + add the expression EXPR to the auto-display list but arrange to + display it each time in the specified format FMT. *Note Output + Formats: Output Formats. + +'display/FMT ADDR' + For FMT 'i' or 's', or including a unit-size or a number of units, + add the expression ADDR as a memory address to be examined each + time your program stops. Examining means in effect doing 'x/FMT + ADDR'. *Note Examining Memory: Memory. + + For example, 'display/i $pc' can be helpful, to see the machine +instruction about to be executed each time execution stops ('$pc' is a +common name for the program counter; *note Registers: Registers.). + +'undisplay DNUMS...' +'delete display DNUMS...' + Remove items from the list of expressions to display. Specify the + numbers of the displays that you want affected with the command + argument DNUMS. It can be a single display number, one of the + numbers shown in the first field of the 'info display' display; or + it could be a range of display numbers, as in '2-4'. + + 'undisplay' does not repeat if you press after using it. + (Otherwise you would just get the error 'No display number ...'.) + +'disable display DNUMS...' + Disable the display of item numbers DNUMS. A disabled display item + is not printed automatically, but is not forgotten. It may be + enabled again later. Specify the numbers of the displays that you + want affected with the command argument DNUMS. It can be a single + display number, one of the numbers shown in the first field of the + 'info display' display; or it could be a range of display numbers, + as in '2-4'. + +'enable display DNUMS...' + Enable display of item numbers DNUMS. It becomes effective once + again in auto display of its expression, until you specify + otherwise. Specify the numbers of the displays that you want + affected with the command argument DNUMS. It can be a single + display number, one of the numbers shown in the first field of the + 'info display' display; or it could be a range of display numbers, + as in '2-4'. + +'display' + Display the current values of the expressions on the list, just as + is done when your program stops. + +'info display' + Print the list of expressions previously set up to display + automatically, each one with its item number, but without showing + the values. This includes disabled expressions, which are marked + as such. It also includes expressions which would not be displayed + right now because they refer to automatic variables not currently + available. + + If a display expression refers to local variables, then it does not +make sense outside the lexical context for which it was set up. Such an +expression is disabled when execution enters a context where one of its +variables is not defined. For example, if you give the command 'display +last_char' while inside a function with an argument 'last_char', GDB +displays this argument while your program continues to stop inside that +function. When it stops elsewhere--where there is no variable +'last_char'--the display is disabled automatically. The next time your +program stops where 'last_char' is meaningful, you can enable the +display expression once again. + + +File: gdb.info, Node: Print Settings, Next: Pretty Printing, Prev: Auto Display, Up: Data + +10.8 Print Settings +=================== + +GDB provides the following ways to control how arrays, structures, and +symbols are printed. + +These settings are useful for debugging programs in any language: + +'set print address' +'set print address on' + GDB prints memory addresses showing the location of stack traces, + structure values, pointer values, breakpoints, and so forth, even + when it also displays the contents of those addresses. The default + is 'on'. For example, this is what a stack frame display looks + like with 'set print address on': + + (gdb) f + #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") + at input.c:530 + 530 if (lquote != def_lquote) + +'set print address off' + Do not print addresses when displaying their contents. For + example, this is the same stack frame displayed with 'set print + address off': + + (gdb) set print addr off + (gdb) f + #0 set_quotes (lq="<<", rq=">>") at input.c:530 + 530 if (lquote != def_lquote) + + You can use 'set print address off' to eliminate all machine + dependent displays from the GDB interface. For example, with + 'print address off', you should get the same text for backtraces on + all machines--whether or not they involve pointer arguments. + +'show print address' + Show whether or not addresses are to be printed. + + When GDB prints a symbolic address, it normally prints the closest +earlier symbol plus an offset. If that symbol does not uniquely +identify the address (for example, it is a name whose scope is a single +source file), you may need to clarify. One way to do this is with 'info +line', for example 'info line *0x4537'. Alternately, you can set GDB to +print the source file and line number when it prints a symbolic address: + +'set print symbol-filename on' + Tell GDB to print the source file name and line number of a symbol + in the symbolic form of an address. + +'set print symbol-filename off' + Do not print source file name and line number of a symbol. This is + the default. + +'show print symbol-filename' + Show whether or not GDB will print the source file name and line + number of a symbol in the symbolic form of an address. + + Another situation where it is helpful to show symbol filenames and +line numbers is when disassembling code; GDB shows you the line number +and source file that corresponds to each instruction. + + Also, you may wish to see the symbolic form only if the address being +printed is reasonably close to the closest earlier symbol: + +'set print max-symbolic-offset MAX-OFFSET' +'set print max-symbolic-offset unlimited' + Tell GDB to only display the symbolic form of an address if the + offset between the closest earlier symbol and the address is less + than MAX-OFFSET. The default is 'unlimited', which tells GDB to + always print the symbolic form of an address if any symbol precedes + it. Zero is equivalent to 'unlimited'. + +'show print max-symbolic-offset' + Ask how large the maximum offset is that GDB prints in a symbolic + address. + + If you have a pointer and you are not sure where it points, try 'set +print symbol-filename on'. Then you can determine the name and source +file location of the variable where it points, using 'p/a POINTER'. +This interprets the address in symbolic form. For example, here GDB +shows that a variable 'ptt' points at another variable 't', defined in +'hi2.c': + + (gdb) set print symbol-filename on + (gdb) p/a ptt + $4 = 0xe008 + + _Warning:_ For pointers that point to a local variable, 'p/a' does + not show the symbol name and filename of the referent, even with + the appropriate 'set print' options turned on. + + You can also enable '/a'-like formatting all the time using 'set +print symbol on': + +'set print symbol on' + Tell GDB to print the symbol corresponding to an address, if one + exists. + +'set print symbol off' + Tell GDB not to print the symbol corresponding to an address. In + this mode, GDB will still print the symbol corresponding to + pointers to functions. This is the default. + +'show print symbol' + Show whether GDB will display the symbol corresponding to an + address. + + Other settings control how different kinds of objects are printed: + +'set print array' +'set print array on' + Pretty print arrays. This format is more convenient to read, but + uses more space. The default is off. + +'set print array off' + Return to compressed format for arrays. + +'show print array' + Show whether compressed or pretty format is selected for displaying + arrays. + +'set print array-indexes' +'set print array-indexes on' + Print the index of each element when displaying arrays. May be + more convenient to locate a given element in the array or quickly + find the index of a given element in that printed array. The + default is off. + +'set print array-indexes off' + Stop printing element indexes when displaying arrays. + +'show print array-indexes' + Show whether the index of each element is printed when displaying + arrays. + +'set print elements NUMBER-OF-ELEMENTS' +'set print elements unlimited' + Set a limit on how many elements of an array GDB will print. If + GDB is printing a large array, it stops printing after it has + printed the number of elements set by the 'set print elements' + command. This limit also applies to the display of strings. When + GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS + to 'unlimited' or zero means that the number of elements to print + is unlimited. + +'show print elements' + Display the number of elements of a large array that GDB will + print. If the number is 0, then the printing is unlimited. + +'set print frame-arguments VALUE' + This command allows to control how the values of arguments are + printed when the debugger prints a frame (*note Frames::). The + possible values are: + + 'all' + The values of all arguments are printed. + + 'scalars' + Print the value of an argument only if it is a scalar. The + value of more complex arguments such as arrays, structures, + unions, etc, is replaced by '...'. This is the default. Here + is an example where only scalar arguments are shown: + + #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) + at frame-args.c:23 + + 'none' + None of the argument values are printed. Instead, the value + of each argument is replaced by '...'. In this case, the + example above now becomes: + + #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) + at frame-args.c:23 + + By default, only scalar arguments are printed. This command can be + used to configure the debugger to print the value of all arguments, + regardless of their type. However, it is often advantageous to not + print the value of more complex parameters. For instance, it + reduces the amount of information printed in each frame, making the + backtrace more readable. Also, it improves performance when + displaying Ada frames, because the computation of large arguments + can sometimes be CPU-intensive, especially in large applications. + Setting 'print frame-arguments' to 'scalars' (the default) or + 'none' avoids this computation, thus speeding up the display of + each Ada frame. + +'show print frame-arguments' + Show how the value of arguments should be displayed when printing a + frame. + +'set print raw frame-arguments on' + Print frame arguments in raw, non pretty-printed, form. + +'set print raw frame-arguments off' + Print frame arguments in pretty-printed form, if there is a + pretty-printer for the value (*note Pretty Printing::), otherwise + print the value in raw form. This is the default. + +'show print raw frame-arguments' + Show whether to print frame arguments in raw form. + +'set print entry-values VALUE' + Set printing of frame argument values at function entry. In some + cases GDB can determine the value of function argument which was + passed by the function caller, even if the value was modified + inside the called function and therefore is different. With + optimized code, the current value could be unavailable, but the + entry value may still be known. + + The default value is 'default' (see below for its description). + Older GDB behaved as with the setting 'no'. Compilers not + supporting this feature will behave in the 'default' setting the + same way as with the 'no' setting. + + This functionality is currently supported only by DWARF 2 debugging + format and the compiler has to produce 'DW_TAG_GNU_call_site' tags. + With GCC, you need to specify '-O -g' during compilation, to get + this information. + + The VALUE parameter can be one of the following: + + 'no' + Print only actual parameter values, never print values from + function entry point. + #0 equal (val=5) + #0 different (val=6) + #0 lost (val=) + #0 born (val=10) + #0 invalid (val=) + + 'only' + Print only parameter values from function entry point. The + actual parameter values are never printed. + #0 equal (val@entry=5) + #0 different (val@entry=5) + #0 lost (val@entry=5) + #0 born (val@entry=) + #0 invalid (val@entry=) + + 'preferred' + Print only parameter values from function entry point. If + value from function entry point is not known while the actual + value is known, print the actual value for such parameter. + #0 equal (val@entry=5) + #0 different (val@entry=5) + #0 lost (val@entry=5) + #0 born (val=10) + #0 invalid (val@entry=) + + 'if-needed' + Print actual parameter values. If actual parameter value is + not known while value from function entry point is known, + print the entry point value for such parameter. + #0 equal (val=5) + #0 different (val=6) + #0 lost (val@entry=5) + #0 born (val=10) + #0 invalid (val=) + + 'both' + Always print both the actual parameter value and its value + from function entry point, even if values of one or both are + not available due to compiler optimizations. + #0 equal (val=5, val@entry=5) + #0 different (val=6, val@entry=5) + #0 lost (val=, val@entry=5) + #0 born (val=10, val@entry=) + #0 invalid (val=, val@entry=) + + 'compact' + Print the actual parameter value if it is known and also its + value from function entry point if it is known. If neither is + known, print for the actual value ''. If not + in MI mode (*note GDB/MI::) and if both values are known and + identical, print the shortened 'param=param@entry=VALUE' + notation. + #0 equal (val=val@entry=5) + #0 different (val=6, val@entry=5) + #0 lost (val@entry=5) + #0 born (val=10) + #0 invalid (val=) + + 'default' + Always print the actual parameter value. Print also its value + from function entry point, but only if it is known. If not in + MI mode (*note GDB/MI::) and if both values are known and + identical, print the shortened 'param=param@entry=VALUE' + notation. + #0 equal (val=val@entry=5) + #0 different (val=6, val@entry=5) + #0 lost (val=, val@entry=5) + #0 born (val=10) + #0 invalid (val=) + + For analysis messages on possible failures of frame argument values + at function entry resolution see *note set debug entry-values::. + +'show print entry-values' + Show the method being used for printing of frame argument values at + function entry. + +'set print repeats NUMBER-OF-REPEATS' +'set print repeats unlimited' + Set the threshold for suppressing display of repeated array + elements. When the number of consecutive identical elements of an + array exceeds the threshold, GDB prints the string '""', where N is the number of identical repetitions, instead + of displaying the identical elements themselves. Setting the + threshold to 'unlimited' or zero will cause all elements to be + individually printed. The default threshold is 10. + +'show print repeats' + Display the current threshold for printing repeated identical + elements. + +'set print null-stop' + Cause GDB to stop printing the characters of an array when the + first NULL is encountered. This is useful when large arrays + actually contain only short strings. The default is off. + +'show print null-stop' + Show whether GDB stops printing an array on the first NULL + character. + +'set print pretty on' + Cause GDB to print structures in an indented format with one member + per line, like this: + + $1 = { + next = 0x0, + flags = { + sweet = 1, + sour = 1 + }, + meat = 0x54 "Pork" + } + +'set print pretty off' + Cause GDB to print structures in a compact format, like this: + + $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ + meat = 0x54 "Pork"} + + This is the default format. + +'show print pretty' + Show which format GDB is using to print structures. + +'set print sevenbit-strings on' + Print using only seven-bit characters; if this option is set, GDB + displays any eight-bit characters (in strings or character values) + using the notation '\'NNN. This setting is best if you are working + in English (ASCII) and you use the high-order bit of characters as + a marker or "meta" bit. + +'set print sevenbit-strings off' + Print full eight-bit characters. This allows the use of more + international character sets, and is the default. + +'show print sevenbit-strings' + Show whether or not GDB is printing only seven-bit characters. + +'set print union on' + Tell GDB to print unions which are contained in structures and + other unions. This is the default setting. + +'set print union off' + Tell GDB not to print unions which are contained in structures and + other unions. GDB will print '"{...}"' instead. + +'show print union' + Ask GDB whether or not it will print unions which are contained in + structures and other unions. + + For example, given the declarations + + typedef enum {Tree, Bug} Species; + typedef enum {Big_tree, Acorn, Seedling} Tree_forms; + typedef enum {Caterpillar, Cocoon, Butterfly} + Bug_forms; + + struct thing { + Species it; + union { + Tree_forms tree; + Bug_forms bug; + } form; + }; + + struct thing foo = {Tree, {Acorn}}; + + with 'set print union on' in effect 'p foo' would print + + $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} + + and with 'set print union off' in effect it would print + + $1 = {it = Tree, form = {...}} + + 'set print union' affects programs written in C-like languages and + in Pascal. + +These settings are of interest when debugging C++ programs: + +'set print demangle' +'set print demangle on' + Print C++ names in their source form rather than in the encoded + ("mangled") form passed to the assembler and linker for type-safe + linkage. The default is on. + +'show print demangle' + Show whether C++ names are printed in mangled or demangled form. + +'set print asm-demangle' +'set print asm-demangle on' + Print C++ names in their source form rather than their mangled + form, even in assembler code printouts such as instruction + disassemblies. The default is off. + +'show print asm-demangle' + Show whether C++ names in assembly listings are printed in mangled + or demangled form. + +'set demangle-style STYLE' + Choose among several encoding schemes used by different compilers + to represent C++ names. The choices for STYLE are currently: + + 'auto' + Allow GDB to choose a decoding style by inspecting your + program. This is the default. + + 'gnu' + Decode based on the GNU C++ compiler ('g++') encoding + algorithm. + + 'hp' + Decode based on the HP ANSI C++ ('aCC') encoding algorithm. + + 'lucid' + Decode based on the Lucid C++ compiler ('lcc') encoding + algorithm. + + 'arm' + Decode using the algorithm in the 'C++ Annotated Reference + Manual'. *Warning:* this setting alone is not sufficient to + allow debugging 'cfront'-generated executables. GDB would + require further enhancement to permit that. + + If you omit STYLE, you will see a list of possible formats. + +'show demangle-style' + Display the encoding style currently in use for decoding C++ + symbols. + +'set print object' +'set print object on' + When displaying a pointer to an object, identify the _actual_ + (derived) type of the object rather than the _declared_ type, using + the virtual function table. Note that the virtual function table + is required--this feature can only work for objects that have + run-time type identification; a single virtual method in the + object's declared type is sufficient. Note that this setting is + also taken into account when working with variable objects via MI + (*note GDB/MI::). + +'set print object off' + Display only the declared type of objects, without reference to the + virtual function table. This is the default setting. + +'show print object' + Show whether actual, or declared, object types are displayed. + +'set print static-members' +'set print static-members on' + Print static members when displaying a C++ object. The default is + on. + +'set print static-members off' + Do not print static members when displaying a C++ object. + +'show print static-members' + Show whether C++ static members are printed or not. + +'set print pascal_static-members' +'set print pascal_static-members on' + Print static members when displaying a Pascal object. The default + is on. + +'set print pascal_static-members off' + Do not print static members when displaying a Pascal object. + +'show print pascal_static-members' + Show whether Pascal static members are printed or not. + +'set print vtbl' +'set print vtbl on' + Pretty print C++ virtual function tables. The default is off. + (The 'vtbl' commands do not work on programs compiled with the HP + ANSI C++ compiler ('aCC').) + +'set print vtbl off' + Do not pretty print C++ virtual function tables. + +'show print vtbl' + Show whether C++ virtual function tables are pretty printed, or + not. + + +File: gdb.info, Node: Pretty Printing, Next: Value History, Prev: Print Settings, Up: Data + +10.9 Pretty Printing +==================== + +GDB provides a mechanism to allow pretty-printing of values using Python +code. It greatly simplifies the display of complex objects. This +mechanism works for both MI and the CLI. + +* Menu: + +* Pretty-Printer Introduction:: Introduction to pretty-printers +* Pretty-Printer Example:: An example pretty-printer +* Pretty-Printer Commands:: Pretty-printer commands + + +File: gdb.info, Node: Pretty-Printer Introduction, Next: Pretty-Printer Example, Up: Pretty Printing + +10.9.1 Pretty-Printer Introduction +---------------------------------- + +When GDB prints a value, it first sees if there is a pretty-printer +registered for the value. If there is then GDB invokes the +pretty-printer to print the value. Otherwise the value is printed +normally. + + Pretty-printers are normally named. This makes them easy to manage. +The 'info pretty-printer' command will list all the installed +pretty-printers with their names. If a pretty-printer can handle +multiple data types, then its "subprinters" are the printers for the +individual data types. Each such subprinter has its own name. The +format of the name is PRINTER-NAME;SUBPRINTER-NAME. + + Pretty-printers are installed by "registering" them with GDB. +Typically they are automatically loaded and registered when the +corresponding debug information is loaded, thus making them available +without having to do anything special. + + There are three places where a pretty-printer can be registered. + + * Pretty-printers registered globally are available when debugging + all inferiors. + + * Pretty-printers registered with a program space are available only + when debugging that program. *Note Progspaces In Python::, for + more details on program spaces in Python. + + * Pretty-printers registered with an objfile are loaded and unloaded + with the corresponding objfile (e.g., shared library). *Note + Objfiles In Python::, for more details on objfiles in Python. + + *Note Selecting Pretty-Printers::, for further information on how +pretty-printers are selected, + + *Note Writing a Pretty-Printer::, for implementing pretty printers +for new types. + + +File: gdb.info, Node: Pretty-Printer Example, Next: Pretty-Printer Commands, Prev: Pretty-Printer Introduction, Up: Pretty Printing + +10.9.2 Pretty-Printer Example +----------------------------- + +Here is how a C++ 'std::string' looks without a pretty-printer: + + (gdb) print s + $1 = { + static npos = 4294967295, + _M_dataplus = { + > = { + <__gnu_cxx::new_allocator> = { + }, + }, + members of std::basic_string, + std::allocator >::_Alloc_hider: + _M_p = 0x804a014 "abcd" + } + } + + With a pretty-printer for 'std::string' only the contents are +printed: + + (gdb) print s + $2 = "abcd" + + +File: gdb.info, Node: Pretty-Printer Commands, Prev: Pretty-Printer Example, Up: Pretty Printing + +10.9.3 Pretty-Printer Commands +------------------------------ + +'info pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' + Print the list of installed pretty-printers. This includes + disabled pretty-printers, which are marked as such. + + OBJECT-REGEXP is a regular expression matching the objects whose + pretty-printers to list. Objects can be 'global', the program + space's file (*note Progspaces In Python::), and the object files + within that program space (*note Objfiles In Python::). *Note + Selecting Pretty-Printers::, for details on how GDB looks up a + printer from these three objects. + + NAME-REGEXP is a regular expression matching the name of the + printers to list. + +'disable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' + Disable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. A + disabled pretty-printer is not forgotten, it may be enabled again + later. + +'enable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' + Enable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. + + Example: + + Suppose we have three pretty-printers installed: one from library1.so +named 'foo' that prints objects of type 'foo', and another from +library2.so named 'bar' that prints two types of objects, 'bar1' and +'bar2'. + + (gdb) info pretty-printer + library1.so: + foo + library2.so: + bar + bar1 + bar2 + (gdb) info pretty-printer library2 + library2.so: + bar + bar1 + bar2 + (gdb) disable pretty-printer library1 + 1 printer disabled + 2 of 3 printers enabled + (gdb) info pretty-printer + library1.so: + foo [disabled] + library2.so: + bar + bar1 + bar2 + (gdb) disable pretty-printer library2 bar:bar1 + 1 printer disabled + 1 of 3 printers enabled + (gdb) info pretty-printer library2 + library1.so: + foo [disabled] + library2.so: + bar + bar1 [disabled] + bar2 + (gdb) disable pretty-printer library2 bar + 1 printer disabled + 0 of 3 printers enabled + (gdb) info pretty-printer library2 + library1.so: + foo [disabled] + library2.so: + bar [disabled] + bar1 [disabled] + bar2 + + Note that for 'bar' the entire printer can be disabled, as can each +individual subprinter. + + +File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Pretty Printing, Up: Data + +10.10 Value History +=================== + +Values printed by the 'print' command are saved in the GDB "value +history". This allows you to refer to them in other expressions. +Values are kept until the symbol table is re-read or discarded (for +example with the 'file' or 'symbol-file' commands). When the symbol +table changes, the value history is discarded, since the values may +contain pointers back to the types defined in the symbol table. + + The values printed are given "history numbers" by which you can refer +to them. These are successive integers starting with one. 'print' +shows you the history number assigned to a value by printing '$NUM = ' +before the value; here NUM is the history number. + + To refer to any previous value, use '$' followed by the value's +history number. The way 'print' labels its output is designed to remind +you of this. Just '$' refers to the most recent value in the history, +and '$$' refers to the value before that. '$$N' refers to the Nth value +from the end; '$$2' is the value just prior to '$$', '$$1' is equivalent +to '$$', and '$$0' is equivalent to '$'. + + For example, suppose you have just printed a pointer to a structure +and want to see the contents of the structure. It suffices to type + + p *$ + + If you have a chain of structures where the component 'next' points +to the next one, you can print the contents of the next one with this: + + p *$.next + +You can print successive links in the chain by repeating this +command--which you can do by just typing . + + Note that the history records values, not expressions. If the value +of 'x' is 4 and you type these commands: + + print x + set x=5 + +then the value recorded in the value history by the 'print' command +remains 4 even though the value of 'x' has changed. + +'show values' + Print the last ten values in the value history, with their item + numbers. This is like 'p $$9' repeated ten times, except that + 'show values' does not change the history. + +'show values N' + Print ten history values centered on history item number N. + +'show values +' + Print ten history values just after the values last printed. If no + more values are available, 'show values +' produces no display. + + Pressing to repeat 'show values N' has exactly the same effect +as 'show values +'. + + +File: gdb.info, Node: Convenience Vars, Next: Convenience Funs, Prev: Value History, Up: Data + +10.11 Convenience Variables +=========================== + +GDB provides "convenience variables" that you can use within GDB to hold +on to a value and refer to it later. These variables exist entirely +within GDB; they are not part of your program, and setting a convenience +variable has no direct effect on further execution of your program. +That is why you can use them freely. + + Convenience variables are prefixed with '$'. Any name preceded by +'$' can be used for a convenience variable, unless it is one of the +predefined machine-specific register names (*note Registers: +Registers.). (Value history references, in contrast, are _numbers_ +preceded by '$'. *Note Value History: Value History.) + + You can save a value in a convenience variable with an assignment +expression, just as you would set a variable in your program. For +example: + + set $foo = *object_ptr + +would save in '$foo' the value contained in the object pointed to by +'object_ptr'. + + Using a convenience variable for the first time creates it, but its +value is 'void' until you assign a new value. You can alter the value +with another assignment at any time. + + Convenience variables have no fixed types. You can assign a +convenience variable any type of value, including structures and arrays, +even if that variable already has a value of a different type. The +convenience variable, when used as an expression, has the type of its +current value. + +'show convenience' + Print a list of convenience variables used so far, and their + values, as well as a list of the convenience functions. + Abbreviated 'show conv'. + +'init-if-undefined $VARIABLE = EXPRESSION' + Set a convenience variable if it has not already been set. This is + useful for user-defined commands that keep some state. It is + similar, in concept, to using local static variables with + initializers in C (except that convenience variables are global). + It can also be used to allow users to override default values used + in a command script. + + If the variable is already defined then the expression is not + evaluated so any side-effects do not occur. + + One of the ways to use a convenience variable is as a counter to be +incremented or a pointer to be advanced. For example, to print a field +from successive elements of an array of structures: + + set $i = 0 + print bar[$i++]->contents + +Repeat that command by typing . + + Some convenience variables are created automatically by GDB and given +values likely to be useful. + +'$_' + The variable '$_' is automatically set by the 'x' command to the + last address examined (*note Examining Memory: Memory.). Other + commands which provide a default address for 'x' to examine also + set '$_' to that address; these commands include 'info line' and + 'info breakpoint'. The type of '$_' is 'void *' except when set by + the 'x' command, in which case it is a pointer to the type of + '$__'. + +'$__' + The variable '$__' is automatically set by the 'x' command to the + value found in the last address examined. Its type is chosen to + match the format in which the data was printed. + +'$_exitcode' + When the program being debugged terminates normally, GDB + automatically sets this variable to the exit code of the program, + and resets '$_exitsignal' to 'void'. + +'$_exitsignal' + When the program being debugged dies due to an uncaught signal, GDB + automatically sets this variable to that signal's number, and + resets '$_exitcode' to 'void'. + + To distinguish between whether the program being debugged has + exited (i.e., '$_exitcode' is not 'void') or signalled (i.e., + '$_exitsignal' is not 'void'), the convenience function '$_isvoid' + can be used (*note Convenience Functions: Convenience Funs.). For + example, considering the following source code: + + #include + + int + main (int argc, char *argv[]) + { + raise (SIGALRM); + return 0; + } + + A valid way of telling whether the program being debugged has + exited or signalled would be: + + (gdb) define has_exited_or_signalled + Type commands for definition of ``has_exited_or_signalled''. + End with a line saying just ``end''. + >if $_isvoid ($_exitsignal) + >echo The program has exited\n + >else + >echo The program has signalled\n + >end + >end + (gdb) run + Starting program: + + Program terminated with signal SIGALRM, Alarm clock. + The program no longer exists. + (gdb) has_exited_or_signalled + The program has signalled + + As can be seen, GDB correctly informs that the program being + debugged has signalled, since it calls 'raise' and raises a + 'SIGALRM' signal. If the program being debugged had not called + 'raise', then GDB would report a normal exit: + + (gdb) has_exited_or_signalled + The program has exited + +'$_exception' + The variable '$_exception' is set to the exception object being + thrown at an exception-related catchpoint. *Note Set + Catchpoints::. + +'$_probe_argc' +'$_probe_arg0...$_probe_arg11' + Arguments to a static probe. *Note Static Probe Points::. + +'$_sdata' + The variable '$_sdata' contains extra collected static tracepoint + data. *Note Tracepoint Action Lists: Tracepoint Actions. Note + that '$_sdata' could be empty, if not inspecting a trace buffer, or + if extra static tracepoint data has not been collected. + +'$_siginfo' + The variable '$_siginfo' contains extra signal information (*note + extra signal information::). Note that '$_siginfo' could be empty, + if the application has not yet received any signals. For example, + it will be empty before you execute the 'run' command. + +'$_tlb' + The variable '$_tlb' is automatically set when debugging + applications running on MS-Windows in native mode or connected to + gdbserver that supports the 'qGetTIBAddr' request. *Note General + Query Packets::. This variable contains the address of the thread + information block. + + On HP-UX systems, if you refer to a function or variable name that +begins with a dollar sign, GDB searches for a user or system name first, +before it searches for a convenience variable. + + +File: gdb.info, Node: Convenience Funs, Next: Registers, Prev: Convenience Vars, Up: Data + +10.12 Convenience Functions +=========================== + +GDB also supplies some "convenience functions". These have a syntax +similar to convenience variables. A convenience function can be used in +an expression just like an ordinary function; however, a convenience +function is implemented internally to GDB. + + These functions do not require GDB to be configured with 'Python' +support, which means that they are always available. + +'$_isvoid (EXPR)' + Return one if the expression EXPR is 'void'. Otherwise it returns + zero. + + A 'void' expression is an expression where the type of the result + is 'void'. For example, you can examine a convenience variable + (see *note Convenience Variables: Convenience Vars.) to check + whether it is 'void': + + (gdb) print $_exitcode + $1 = void + (gdb) print $_isvoid ($_exitcode) + $2 = 1 + (gdb) run + Starting program: ./a.out + [Inferior 1 (process 29572) exited normally] + (gdb) print $_exitcode + $3 = 0 + (gdb) print $_isvoid ($_exitcode) + $4 = 0 + + In the example above, we used '$_isvoid' to check whether + '$_exitcode' is 'void' before and after the execution of the + program being debugged. Before the execution there is no exit code + to be examined, therefore '$_exitcode' is 'void'. After the + execution the program being debugged returned zero, therefore + '$_exitcode' is zero, which means that it is not 'void' anymore. + + The 'void' expression can also be a call of a function from the + program being debugged. For example, given the following function: + + void + foo (void) + { + } + + The result of calling it inside GDB is 'void': + + (gdb) print foo () + $1 = void + (gdb) print $_isvoid (foo ()) + $2 = 1 + (gdb) set $v = foo () + (gdb) print $v + $3 = void + (gdb) print $_isvoid ($v) + $4 = 1 + + These functions require GDB to be configured with 'Python' support. + +'$_memeq(BUF1, BUF2, LENGTH)' + Returns one if the LENGTH bytes at the addresses given by BUF1 and + BUF2 are equal. Otherwise it returns zero. + +'$_regex(STR, REGEX)' + Returns one if the string STR matches the regular expression REGEX. + Otherwise it returns zero. The syntax of the regular expression is + that specified by 'Python''s regular expression support. + +'$_streq(STR1, STR2)' + Returns one if the strings STR1 and STR2 are equal. Otherwise it + returns zero. + +'$_strlen(STR)' + Returns the length of string STR. + + GDB provides the ability to list and get help on convenience +functions. + +'help function' + Print a list of all convenience functions. + + +File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Funs, Up: Data + +10.13 Registers +=============== + +You can refer to machine register contents, in expressions, as variables +with names starting with '$'. The names of registers are different for +each machine; use 'info registers' to see the names used on your +machine. + +'info registers' + Print the names and values of all registers except floating-point + and vector registers (in the selected stack frame). + +'info all-registers' + Print the names and values of all registers, including + floating-point and vector registers (in the selected stack frame). + +'info registers REGNAME ...' + Print the "relativized" value of each specified register REGNAME. + As discussed in detail below, register values are normally relative + to the selected stack frame. REGNAME may be any register name + valid on the machine you are using, with or without the initial + '$'. + + GDB has four "standard" register names that are available (in +expressions) on most machines--whenever they do not conflict with an +architecture's canonical mnemonics for registers. The register names +'$pc' and '$sp' are used for the program counter register and the stack +pointer. '$fp' is used for a register that contains a pointer to the +current stack frame, and '$ps' is used for a register that contains the +processor status. For example, you could print the program counter in +hex with + + p/x $pc + +or print the instruction to be executed next with + + x/i $pc + +or add four to the stack pointer(1) with + + set $sp += 4 + + Whenever possible, these four standard register names are available +on your machine even though the machine has different canonical +mnemonics, so long as there is no conflict. The 'info registers' +command shows the canonical names. For example, on the SPARC, 'info +registers' displays the processor status register as '$psr' but you can +also refer to it as '$ps'; and on x86-based machines '$ps' is an alias +for the EFLAGS register. + + GDB always considers the contents of an ordinary register as an +integer when the register is examined in this way. Some machines have +special registers which can hold nothing but floating point; these +registers are considered to have floating point values. There is no way +to refer to the contents of an ordinary register as floating point value +(although you can _print_ it as a floating point value with 'print/f +$REGNAME'). + + Some registers have distinct "raw" and "virtual" data formats. This +means that the data format in which the register contents are saved by +the operating system is not the same one that your program normally +sees. For example, the registers of the 68881 floating point +coprocessor are always saved in "extended" (raw) format, but all C +programs expect to work with "double" (virtual) format. In such cases, +GDB normally works with the virtual format only (the format that makes +sense for your program), but the 'info registers' command prints the +data in both formats. + + Some machines have special registers whose contents can be +interpreted in several different ways. For example, modern x86-based +machines have SSE and MMX registers that can hold several values packed +together in several different formats. GDB refers to such registers in +'struct' notation: + + (gdb) print $xmm1 + $1 = { + v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044}, + v2_double = {9.92129282474342e-303, 2.7585945287983262e-313}, + v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", + v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0}, + v4_int32 = {0, 20657912, 11, 13}, + v2_int64 = {88725056443645952, 55834574859}, + uint128 = 0x0000000d0000000b013b36f800000000 + } + +To set values of such registers, you need to tell GDB which view of the +register you wish to change, as if you were assigning value to a +'struct' member: + + (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF + + Normally, register values are relative to the selected stack frame +(*note Selecting a Frame: Selection.). This means that you get the +value that the register would contain if all stack frames farther in +were exited and their saved registers restored. In order to see the +true contents of hardware registers, you must select the innermost frame +(with 'frame 0'). + + Usually ABIs reserve some registers as not needed to be saved by the +callee (a.k.a.: "caller-saved", "call-clobbered" or "volatile" +registers). It may therefore not be possible for GDB to know the value +a register had before the call (in other words, in the outer frame), if +the register value has since been changed by the callee. GDB tries to +deduce where the inner frame saved ("callee-saved") registers, from the +debug info, unwind info, or the machine code generated by your compiler. +If some register is not saved, and GDB knows the register is +"caller-saved" (via its own knowledge of the ABI, or because the +debug/unwind info explicitly says the register's value is undefined), +GDB displays '' as the register's value. With targets that +GDB has no knowledge of the register saving convention, if a register +was not saved by the callee, then its value and location in the outer +frame are assumed to be the same of the inner frame. This is usually +harmless, because if the register is call-clobbered, the caller either +does not care what is in the register after the call, or has code to +restore the value that it does care about. Note, however, that if you +change such a register in the outer frame, you may also be affecting the +inner frame. Also, the more "outer" the frame is you're looking at, the +more likely a call-clobbered register's value is to be wrong, in the +sense that it doesn't actually represent the value the register had just +before the call. + + ---------- Footnotes ---------- + + (1) This is a way of removing one word from the stack, on machines +where stacks grow downward in memory (most machines, nowadays). This +assumes that the innermost stack frame is selected; setting '$sp' is not +allowed when other stack frames are selected. To pop entire frames off +the stack, regardless of machine architecture, use 'return'; see *note +Returning from a Function: Returning. + + +File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data + +10.14 Floating Point Hardware +============================= + +Depending on the configuration, GDB may be able to give you more +information about the status of the floating point hardware. + +'info float' + Display hardware-dependent information about the floating point + unit. The exact contents and layout vary depending on the floating + point chip. Currently, 'info float' is supported on the ARM and + x86 machines. + + +File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data + +10.15 Vector Unit +================= + +Depending on the configuration, GDB may be able to give you more +information about the status of the vector unit. + +'info vector' + Display information about the vector unit. The exact contents and + layout vary depending on the hardware. + + +File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data + +10.16 Operating System Auxiliary Information +============================================ + +GDB provides interfaces to useful OS facilities that can help you debug +your program. + + Some operating systems supply an "auxiliary vector" to programs at +startup. This is akin to the arguments and environment that you specify +for a program, but contains a system-dependent variety of binary values +that tell system libraries important details about the hardware, +operating system, and process. Each value's purpose is identified by an +integer tag; the meanings are well-known but system-specific. Depending +on the configuration and operating system facilities, GDB may be able to +show you this information. For remote targets, this functionality may +further depend on the remote stub's support of the 'qXfer:auxv:read' +packet, see *note qXfer auxiliary vector read::. + +'info auxv' + Display the auxiliary vector of the inferior, which can be either a + live process or a core dump file. GDB prints each tag value + numerically, and also shows names and text descriptions for + recognized tags. Some values in the vector are numbers, some bit + masks, and some pointers to strings or other data. GDB displays + each value in the most appropriate form for a recognized tag, and + in hexadecimal for an unrecognized tag. + + On some targets, GDB can access operating system-specific information +and show it to you. The types of information available will differ +depending on the type of operating system running on the target. The +mechanism used to fetch the data is described in *note Operating System +Information::. For remote targets, this functionality depends on the +remote stub's support of the 'qXfer:osdata:read' packet, see *note qXfer +osdata read::. + +'info os INFOTYPE' + + Display OS information of the requested type. + + On GNU/Linux, the following values of INFOTYPE are valid: + + 'processes' + Display the list of processes on the target. For each + process, GDB prints the process identifier, the name of the + user, the command corresponding to the process, and the list + of processor cores that the process is currently running on. + (To understand what these properties mean, for this and the + following info types, please consult the general GNU/Linux + documentation.) + + 'procgroups' + Display the list of process groups on the target. For each + process, GDB prints the identifier of the process group that + it belongs to, the command corresponding to the process group + leader, the process identifier, and the command line of the + process. The list is sorted first by the process group + identifier, then by the process identifier, so that processes + belonging to the same process group are grouped together and + the process group leader is listed first. + + 'threads' + Display the list of threads running on the target. For each + thread, GDB prints the identifier of the process that the + thread belongs to, the command of the process, the thread + identifier, and the processor core that it is currently + running on. The main thread of a process is not listed. + + 'files' + Display the list of open file descriptors on the target. For + each file descriptor, GDB prints the identifier of the process + owning the descriptor, the command of the owning process, the + value of the descriptor, and the target of the descriptor. + + 'sockets' + Display the list of Internet-domain sockets on the target. + For each socket, GDB prints the address and port of the local + and remote endpoints, the current state of the connection, the + creator of the socket, the IP address family of the socket, + and the type of the connection. + + 'shm' + Display the list of all System V shared-memory regions on the + target. For each shared-memory region, GDB prints the region + key, the shared-memory identifier, the access permissions, the + size of the region, the process that created the region, the + process that last attached to or detached from the region, the + current number of live attaches to the region, and the times + at which the region was last attached to, detach from, and + changed. + + 'semaphores' + Display the list of all System V semaphore sets on the target. + For each semaphore set, GDB prints the semaphore set key, the + semaphore set identifier, the access permissions, the number + of semaphores in the set, the user and group of the owner and + creator of the semaphore set, and the times at which the + semaphore set was operated upon and changed. + + 'msg' + Display the list of all System V message queues on the target. + For each message queue, GDB prints the message queue key, the + message queue identifier, the access permissions, the current + number of bytes on the queue, the current number of messages + on the queue, the processes that last sent and received a + message on the queue, the user and group of the owner and + creator of the message queue, the times at which a message was + last sent and received on the queue, and the time at which the + message queue was last changed. + + 'modules' + Display the list of all loaded kernel modules on the target. + For each module, GDB prints the module name, the size of the + module in bytes, the number of times the module is used, the + dependencies of the module, the status of the module, and the + address of the loaded module in memory. + +'info os' + If INFOTYPE is omitted, then list the possible values for INFOTYPE + and the kind of OS information available for each INFOTYPE. If the + target does not return a list of possible types, this command will + report an error. + + +File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data + +10.17 Memory Region Attributes +============================== + +"Memory region attributes" allow you to describe special handling +required by regions of your target's memory. GDB uses attributes to +determine whether to allow certain types of memory accesses; whether to +use specific width accesses; and whether to cache target memory. By +default the description of memory regions is fetched from the target (if +the current target supports this), but the user can override the fetched +regions. + + Defined memory regions can be individually enabled and disabled. +When a memory region is disabled, GDB uses the default attributes when +accessing memory in that region. Similarly, if no memory regions have +been defined, GDB uses the default attributes when accessing all memory. + + When a memory region is defined, it is given a number to identify it; +to enable, disable, or remove a memory region, you specify that number. + +'mem LOWER UPPER ATTRIBUTES...' + Define a memory region bounded by LOWER and UPPER with attributes + ATTRIBUTES..., and add it to the list of regions monitored by GDB. + Note that UPPER == 0 is a special case: it is treated as the + target's maximum memory address. (0xffff on 16 bit targets, + 0xffffffff on 32 bit targets, etc.) + +'mem auto' + Discard any user changes to the memory regions and use + target-supplied regions, if available, or no regions if the target + does not support. + +'delete mem NUMS...' + Remove memory regions NUMS... from the list of regions monitored by + GDB. + +'disable mem NUMS...' + Disable monitoring of memory regions NUMS.... A disabled memory + region is not forgotten. It may be enabled again later. + +'enable mem NUMS...' + Enable monitoring of memory regions NUMS.... + +'info mem' + Print a table of all defined memory regions, with the following + columns for each region: + + _Memory Region Number_ + _Enabled or Disabled._ + Enabled memory regions are marked with 'y'. Disabled memory + regions are marked with 'n'. + + _Lo Address_ + The address defining the inclusive lower bound of the memory + region. + + _Hi Address_ + The address defining the exclusive upper bound of the memory + region. + + _Attributes_ + The list of attributes set for this memory region. + +10.17.1 Attributes +------------------ + +10.17.1.1 Memory Access Mode +............................ + +The access mode attributes set whether GDB may make read or write +accesses to a memory region. + + While these attributes prevent GDB from performing invalid memory +accesses, they do nothing to prevent the target system, I/O DMA, etc. +from accessing memory. + +'ro' + Memory is read only. +'wo' + Memory is write only. +'rw' + Memory is read/write. This is the default. + +10.17.1.2 Memory Access Size +............................ + +The access size attribute tells GDB to use specific sized accesses in +the memory region. Often memory mapped device registers require +specific sized accesses. If no access size attribute is specified, GDB +may use accesses of any size. + +'8' + Use 8 bit memory accesses. +'16' + Use 16 bit memory accesses. +'32' + Use 32 bit memory accesses. +'64' + Use 64 bit memory accesses. + +10.17.1.3 Data Cache +.................... + +The data cache attributes set whether GDB will cache target memory. +While this generally improves performance by reducing debug protocol +overhead, it can lead to incorrect results because GDB does not know +about volatile variables or memory mapped device registers. + +'cache' + Enable GDB to cache target memory. +'nocache' + Disable GDB from caching target memory. This is the default. + +10.17.2 Memory Access Checking +------------------------------ + +GDB can be instructed to refuse accesses to memory that is not +explicitly described. This can be useful if accessing such regions has +undesired effects for a specific target, or to provide better error +checking. The following commands control this behaviour. + +'set mem inaccessible-by-default [on|off]' + If 'on' is specified, make GDB treat memory not explicitly + described by the memory ranges as non-existent and refuse accesses + to such memory. The checks are only performed if there's at least + one memory range defined. If 'off' is specified, make GDB treat + the memory not explicitly described by the memory ranges as RAM. + The default value is 'on'. +'show mem inaccessible-by-default' + Show the current handling of accesses to unknown memory. + + +File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data + +10.18 Copy Between Memory and a File +==================================== + +You can use the commands 'dump', 'append', and 'restore' to copy data +between target memory and a file. The 'dump' and 'append' commands +write data to a file, and the 'restore' command reads data from a file +back into the inferior's memory. Files may be in binary, Motorola +S-record, Intel hex, or Tektronix Hex format; however, GDB can only +append to binary files. + +'dump [FORMAT] memory FILENAME START_ADDR END_ADDR' +'dump [FORMAT] value FILENAME EXPR' + Dump the contents of memory from START_ADDR to END_ADDR, or the + value of EXPR, to FILENAME in the given format. + + The FORMAT parameter may be any one of: + 'binary' + Raw binary form. + 'ihex' + Intel hex format. + 'srec' + Motorola S-record format. + 'tekhex' + Tektronix Hex format. + + GDB uses the same definitions of these formats as the GNU binary + utilities, like 'objdump' and 'objcopy'. If FORMAT is omitted, GDB + dumps the data in raw binary form. + +'append [binary] memory FILENAME START_ADDR END_ADDR' +'append [binary] value FILENAME EXPR' + Append the contents of memory from START_ADDR to END_ADDR, or the + value of EXPR, to the file FILENAME, in raw binary form. (GDB can + only append data to files in raw binary form.) + +'restore FILENAME [binary] BIAS START END' + Restore the contents of file FILENAME into memory. The 'restore' + command can automatically recognize any known BFD file format, + except for raw binary. To restore a raw binary file you must + specify the optional keyword 'binary' after the filename. + + If BIAS is non-zero, its value will be added to the addresses + contained in the file. Binary files always start at address zero, + so they will be restored at address BIAS. Other bfd files have a + built-in location; they will be restored at offset BIAS from that + location. + + If START and/or END are non-zero, then only data between file + offset START and file offset END will be restored. These offsets + are relative to the addresses in the file, before the BIAS argument + is applied. + + +File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data + +10.19 How to Produce a Core File from Your Program +================================================== + +A "core file" or "core dump" is a file that records the memory image of +a running process and its process status (register values etc.). Its +primary use is post-mortem debugging of a program that crashed while it +ran outside a debugger. A program that crashes automatically produces a +core file, unless this feature is disabled by the user. *Note Files::, +for information on invoking GDB in the post-mortem debugging mode. + + Occasionally, you may wish to produce a core file of the program you +are debugging in order to preserve a snapshot of its state. GDB has a +special command for that. + +'generate-core-file [FILE]' +'gcore [FILE]' + Produce a core dump of the inferior process. The optional argument + FILE specifies the file name where to put the core dump. If not + specified, the file name defaults to 'core.PID', where PID is the + inferior process ID. + + Note that this command is implemented only for some systems (as of + this writing, GNU/Linux, FreeBSD, Solaris, and S390). + + +File: gdb.info, Node: Character Sets, Next: Caching Target Data, Prev: Core File Generation, Up: Data + +10.20 Character Sets +==================== + +If the program you are debugging uses a different character set to +represent characters and strings than the one GDB uses itself, GDB can +automatically translate between the character sets for you. The +character set GDB uses we call the "host character set"; the one the +inferior program uses we call the "target character set". + + For example, if you are running GDB on a GNU/Linux system, which uses +the ISO Latin 1 character set, but you are using GDB's remote protocol +(*note Remote Debugging::) to debug a program running on an IBM +mainframe, which uses the EBCDIC character set, then the host character +set is Latin-1, and the target character set is EBCDIC. If you give GDB +the command 'set target-charset EBCDIC-US', then GDB translates between +EBCDIC and Latin 1 as you print character or string values, or use +character and string literals in expressions. + + GDB has no way to automatically recognize which character set the +inferior program uses; you must tell it, using the 'set target-charset' +command, described below. + + Here are the commands for controlling GDB's character set support: + +'set target-charset CHARSET' + Set the current target character set to CHARSET. To display the + list of supported target character sets, type + 'set target-charset '. + +'set host-charset CHARSET' + Set the current host character set to CHARSET. + + By default, GDB uses a host character set appropriate to the system + it is running on; you can override that default using the 'set + host-charset' command. On some systems, GDB cannot automatically + determine the appropriate host character set. In this case, GDB + uses 'UTF-8'. + + GDB can only use certain character sets as its host character set. + If you type 'set host-charset ', GDB will list the host + character sets it supports. + +'set charset CHARSET' + Set the current host and target character sets to CHARSET. As + above, if you type 'set charset ', GDB will list the + names of the character sets that can be used for both host and + target. + +'show charset' + Show the names of the current host and target character sets. + +'show host-charset' + Show the name of the current host character set. + +'show target-charset' + Show the name of the current target character set. + +'set target-wide-charset CHARSET' + Set the current target's wide character set to CHARSET. This is + the character set used by the target's 'wchar_t' type. To display + the list of supported wide character sets, type + 'set target-wide-charset '. + +'show target-wide-charset' + Show the name of the current target's wide character set. + + Here is an example of GDB's character set support in action. Assume +that the following source code has been placed in the file +'charset-test.c': + + #include + + char ascii_hello[] + = {72, 101, 108, 108, 111, 44, 32, 119, + 111, 114, 108, 100, 33, 10, 0}; + char ibm1047_hello[] + = {200, 133, 147, 147, 150, 107, 64, 166, + 150, 153, 147, 132, 90, 37, 0}; + + main () + { + printf ("Hello, world!\n"); + } + + In this program, 'ascii_hello' and 'ibm1047_hello' are arrays +containing the string 'Hello, world!' followed by a newline, encoded in +the ASCII and IBM1047 character sets. + + We compile the program, and invoke the debugger on it: + + $ gcc -g charset-test.c -o charset-test + $ gdb -nw charset-test + GNU gdb 2001-12-19-cvs + Copyright 2001 Free Software Foundation, Inc. + ... + (gdb) + + We can use the 'show charset' command to see what character sets GDB +is currently using to interpret and display characters and strings: + + (gdb) show charset + The current host and target character set is `ISO-8859-1'. + (gdb) + + For the sake of printing this manual, let's use ASCII as our initial +character set: + (gdb) set charset ASCII + (gdb) show charset + The current host and target character set is `ASCII'. + (gdb) + + Let's assume that ASCII is indeed the correct character set for our +host system -- in other words, let's assume that if GDB prints +characters using the ASCII character set, our terminal will display them +properly. Since our current target character set is also ASCII, the +contents of 'ascii_hello' print legibly: + + (gdb) print ascii_hello + $1 = 0x401698 "Hello, world!\n" + (gdb) print ascii_hello[0] + $2 = 72 'H' + (gdb) + + GDB uses the target character set for character and string literals +you use in expressions: + + (gdb) print '+' + $3 = 43 '+' + (gdb) + + The ASCII character set uses the number 43 to encode the '+' +character. + + GDB relies on the user to tell it which character set the target +program uses. If we print 'ibm1047_hello' while our target character +set is still ASCII, we get jibberish: + + (gdb) print ibm1047_hello + $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%" + (gdb) print ibm1047_hello[0] + $5 = 200 '\310' + (gdb) + + If we invoke the 'set target-charset' followed by , GDB +tells us the character sets it supports: + + (gdb) set target-charset + ASCII EBCDIC-US IBM1047 ISO-8859-1 + (gdb) set target-charset + + We can select IBM1047 as our target character set, and examine the +program's strings again. Now the ASCII string is wrong, but GDB +translates the contents of 'ibm1047_hello' from the target character +set, IBM1047, to the host character set, ASCII, and they display +correctly: + + (gdb) set target-charset IBM1047 + (gdb) show charset + The current host character set is `ASCII'. + The current target character set is `IBM1047'. + (gdb) print ascii_hello + $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" + (gdb) print ascii_hello[0] + $7 = 72 '\110' + (gdb) print ibm1047_hello + $8 = 0x4016a8 "Hello, world!\n" + (gdb) print ibm1047_hello[0] + $9 = 200 'H' + (gdb) + + As above, GDB uses the target character set for character and string +literals you use in expressions: + + (gdb) print '+' + $10 = 78 '+' + (gdb) + + The IBM1047 character set uses the number 78 to encode the '+' +character. + + +File: gdb.info, Node: Caching Target Data, Next: Searching Memory, Prev: Character Sets, Up: Data + +10.21 Caching Data of Targets +============================= + +GDB caches data exchanged between the debugger and a target. Each cache +is associated with the address space of the inferior. *Note Inferiors +and Programs::, about inferior and address space. Such caching +generally improves performance in remote debugging (*note Remote +Debugging::), because it reduces the overhead of the remote protocol by +bundling memory reads and writes into large chunks. Unfortunately, +simply caching everything would lead to incorrect results, since GDB +does not necessarily know anything about volatile values, memory-mapped +I/O addresses, etc. Furthermore, in non-stop mode (*note Non-Stop +Mode::) memory can be changed _while_ a gdb command is executing. +Therefore, by default, GDB only caches data known to be on the stack(1) +or in the code segment. Other regions of memory can be explicitly +marked as cacheable; *note Memory Region Attributes::. + +'set remotecache on' +'set remotecache off' + This option no longer does anything; it exists for compatibility + with old scripts. + +'show remotecache' + Show the current state of the obsolete remotecache flag. + +'set stack-cache on' +'set stack-cache off' + Enable or disable caching of stack accesses. When 'on', use + caching. By default, this option is 'on'. + +'show stack-cache' + Show the current state of data caching for memory accesses. + +'set code-cache on' +'set code-cache off' + Enable or disable caching of code segment accesses. When 'on', use + caching. By default, this option is 'on'. This improves + performance of disassembly in remote debugging. + +'show code-cache' + Show the current state of target memory cache for code segment + accesses. + +'info dcache [line]' + Print the information about the performance of data cache of the + current inferior's address space. The information displayed + includes the dcache width and depth, and for each cache line, its + number, address, and how many times it was referenced. This + command is useful for debugging the data cache operation. + + If a line number is specified, the contents of that line will be + printed in hex. + +'set dcache size SIZE' + Set maximum number of entries in dcache (dcache depth above). + +'set dcache line-size LINE-SIZE' + Set number of bytes each dcache entry caches (dcache width above). + Must be a power of 2. + +'show dcache size' + Show maximum number of dcache entries. *Note info dcache: Caching + Target Data. + +'show dcache line-size' + Show default size of dcache lines. + + ---------- Footnotes ---------- + + (1) In non-stop mode, it is moderately rare for a running thread to +modify the stack of a stopped thread in a way that would interfere with +a backtrace, and caching of stack reads provides a significant speed up +of remote backtraces. + + +File: gdb.info, Node: Searching Memory, Prev: Caching Target Data, Up: Data + +10.22 Search Memory +=================== + +Memory can be searched for a particular sequence of bytes with the +'find' command. + +'find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]' +'find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]' + Search memory for the sequence of bytes specified by VAL1, VAL2, + etc. The search begins at address START_ADDR and continues for + either LEN bytes or through to END_ADDR inclusive. + + S and N are optional parameters. They may be specified in either +order, apart or together. + +S, search query size + The size of each search query value. + + 'b' + bytes + 'h' + halfwords (two bytes) + 'w' + words (four bytes) + 'g' + giant words (eight bytes) + + All values are interpreted in the current language. This means, + for example, that if the current source language is C/C++ then + searching for the string "hello" includes the trailing '\0'. + + If the value size is not specified, it is taken from the value's + type in the current language. This is useful when one wants to + specify the search pattern as a mixture of types. Note that this + means, for example, that in the case of C-like languages a search + for an untyped 0x42 will search for '(int) 0x42' which is typically + four bytes. + +N, maximum number of finds + The maximum number of matches to print. The default is to print + all finds. + + You can use strings as search values. Quote them with double-quotes +('"'). The string value is copied into the search pattern byte by byte, +regardless of the endianness of the target and the size specification. + + The address of each match found is printed as well as a count of the +number of matches found. + + The address of the last value found is stored in convenience variable +'$_'. A count of the number of matches is stored in '$numfound'. + + For example, if stopped at the 'printf' in this function: + + void + hello () + { + static char hello[] = "hello-hello"; + static struct { char c; short s; int i; } + __attribute__ ((packed)) mixed + = { 'c', 0x1234, 0x87654321 }; + printf ("%s\n", hello); + } + +you get during debugging: + + (gdb) find &hello[0], +sizeof(hello), "hello" + 0x804956d + 1 pattern found + (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' + 0x8049567 + 0x804956d + 2 patterns found + (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' + 0x8049567 + 1 pattern found + (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 + 0x8049560 + 1 pattern found + (gdb) print $numfound + $1 = 1 + (gdb) print $_ + $2 = (void *) 0x8049560 + + +File: gdb.info, Node: Optimized Code, Next: Macros, Prev: Data, Up: Top + +11 Debugging Optimized Code +*************************** + +Almost all compilers support optimization. With optimization disabled, +the compiler generates assembly code that corresponds directly to your +source code, in a simplistic way. As the compiler applies more powerful +optimizations, the generated assembly code diverges from your original +source code. With help from debugging information generated by the +compiler, GDB can map from the running program back to constructs from +your original source. + + GDB is more accurate with optimization disabled. If you can +recompile without optimization, it is easier to follow the progress of +your program during debugging. But, there are many cases where you may +need to debug an optimized version. + + When you debug a program compiled with '-g -O', remember that the +optimizer has rearranged your code; the debugger shows you what is +really there. Do not be too surprised when the execution path does not +exactly match your source file! An extreme example: if you define a +variable, but never use it, GDB never sees that variable--because the +compiler optimizes it out of existence. + + Some things do not work as well with '-g -O' as with just '-g', +particularly on machines with instruction scheduling. If in doubt, +recompile with '-g' alone, and if this fixes the problem, please report +it to us as a bug (including a test case!). *Note Variables::, for more +information about debugging optimized code. + +* Menu: + +* Inline Functions:: How GDB presents inlining +* Tail Call Frames:: GDB analysis of jumps to functions + + +File: gdb.info, Node: Inline Functions, Next: Tail Call Frames, Up: Optimized Code + +11.1 Inline Functions +===================== + +"Inlining" is an optimization that inserts a copy of the function body +directly at each call site, instead of jumping to a shared routine. GDB +displays inlined functions just like non-inlined functions. They appear +in backtraces. You can view their arguments and local variables, step +into them with 'step', skip them with 'next', and escape from them with +'finish'. You can check whether a function was inlined by using the +'info frame' command. + + For GDB to support inlined functions, the compiler must record +information about inlining in the debug information -- GCC using the +DWARF 2 format does this, and several other compilers do also. GDB only +supports inlined functions when using DWARF 2. Versions of GCC before +4.1 do not emit two required attributes ('DW_AT_call_file' and +'DW_AT_call_line'); GDB does not display inlined function calls with +earlier versions of GCC. It instead displays the arguments and local +variables of inlined functions as local variables in the caller. + + The body of an inlined function is directly included at its call +site; unlike a non-inlined function, there are no instructions devoted +to the call. GDB still pretends that the call site and the start of the +inlined function are different instructions. Stepping to the call site +shows the call site, and then stepping again shows the first line of the +inlined function, even though no additional instructions are executed. + + This makes source-level debugging much clearer; you can see both the +context of the call and then the effect of the call. Only stepping by a +single instruction using 'stepi' or 'nexti' does not do this; single +instruction steps always show the inlined body. + + There are some ways that GDB does not pretend that inlined function +calls are the same as normal calls: + + * Setting breakpoints at the call site of an inlined function may not + work, because the call site does not contain any code. GDB may + incorrectly move the breakpoint to the next line of the enclosing + function, after the call. This limitation will be removed in a + future version of GDB; until then, set a breakpoint on an earlier + line or inside the inlined function instead. + + * GDB cannot locate the return value of inlined calls after using the + 'finish' command. This is a limitation of compiler-generated + debugging information; after 'finish', you can step to the next + line and print a variable where your program stored the return + value. + + +File: gdb.info, Node: Tail Call Frames, Prev: Inline Functions, Up: Optimized Code + +11.2 Tail Call Frames +===================== + +Function 'B' can call function 'C' in its very last statement. In +unoptimized compilation the call of 'C' is immediately followed by +return instruction at the end of 'B' code. Optimizing compiler may +replace the call and return in function 'B' into one jump to function +'C' instead. Such use of a jump instruction is called "tail call". + + During execution of function 'C', there will be no indication in the +function call stack frames that it was tail-called from 'B'. If +function 'A' regularly calls function 'B' which tail-calls function 'C', +then GDB will see 'A' as the caller of 'C'. However, in some cases GDB +can determine that 'C' was tail-called from 'B', and it will then create +fictitious call frame for that, with the return address set up as if 'B' +called 'C' normally. + + This functionality is currently supported only by DWARF 2 debugging +format and the compiler has to produce 'DW_TAG_GNU_call_site' tags. +With GCC, you need to specify '-O -g' during compilation, to get this +information. + + 'info frame' command (*note Frame Info::) will indicate the tail call +frame kind by text 'tail call frame' such as in this sample GDB output: + + (gdb) x/i $pc - 2 + 0x40066b : jmp 0x400640 + (gdb) info frame + Stack level 1, frame at 0x7fffffffda30: + rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 + tail call frame, caller of frame at 0x7fffffffda30 + source language c++. + Arglist at unknown address. + Locals at unknown address, Previous frame's sp is 0x7fffffffda30 + + The detection of all the possible code path executions can find them +ambiguous. There is no execution history stored (possible *note Reverse +Execution:: is never used for this purpose) and the last known caller +could have reached the known callee by multiple different jump +sequences. In such case GDB still tries to show at least all the +unambiguous top tail callers and all the unambiguous bottom tail calees, +if any. + +'set debug entry-values' + When set to on, enables printing of analysis messages for both + frame argument values at function entry and tail calls. It will + show all the possible valid tail calls code paths it has + considered. It will also print the intersection of them with the + final unambiguous (possibly partial or even empty) code path + result. + +'show debug entry-values' + Show the current state of analysis messages printing for both frame + argument values at function entry and tail calls. + + The analysis messages for tail calls can for example show why the +virtual tail call frame for function 'c' has not been recognized (due to +the indirect reference by variable 'x'): + + static void __attribute__((noinline, noclone)) c (void); + void (*x) (void) = c; + static void __attribute__((noinline, noclone)) a (void) { x++; } + static void __attribute__((noinline, noclone)) c (void) { a (); } + int main (void) { x (); return 0; } + + Breakpoint 1, DW_OP_GNU_entry_value resolving cannot find + DW_TAG_GNU_call_site 0x40039a in main + a () at t.c:3 + 3 static void __attribute__((noinline, noclone)) a (void) { x++; } + (gdb) bt + #0 a () at t.c:3 + #1 0x000000000040039a in main () at t.c:5 + + Another possibility is an ambiguous virtual tail call frames +resolution: + + int i; + static void __attribute__((noinline, noclone)) f (void) { i++; } + static void __attribute__((noinline, noclone)) e (void) { f (); } + static void __attribute__((noinline, noclone)) d (void) { f (); } + static void __attribute__((noinline, noclone)) c (void) { d (); } + static void __attribute__((noinline, noclone)) b (void) + { if (i) c (); else e (); } + static void __attribute__((noinline, noclone)) a (void) { b (); } + int main (void) { a (); return 0; } + + tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d) + tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e) + tailcall: reduced: 0x4004d2(a) | + (gdb) bt + #0 f () at t.c:2 + #1 0x00000000004004d2 in a () at t.c:8 + #2 0x0000000000400395 in main () at t.c:9 + + Frames #0 and #2 are real, #1 is a virtual tail call frame. The code +can have possible execution paths 'main->a->b->c->d->f' or +'main->a->b->e->f', GDB cannot find which one from the inferior state. + + 'initial:' state shows some random possible calling sequence GDB has +found. It then finds another possible calling sequcen - that one is +prefixed by 'compare:'. The non-ambiguous intersection of these two is +printed as the 'reduced:' calling sequence. That one could have many +futher 'compare:' and 'reduced:' statements as long as there remain any +non-ambiguous sequence entries. + + For the frame of function 'b' in both cases there are different +possible '$pc' values ('0x4004cc' or '0x4004ce'), therefore this frame +is also ambigous. The only non-ambiguous frame is the one for function +'a', therefore this one is displayed to the user while the ambiguous +frames are omitted. + + There can be also reasons why printing of frame argument values at +function entry may fail: + + int v; + static void __attribute__((noinline, noclone)) c (int i) { v++; } + static void __attribute__((noinline, noclone)) a (int i); + static void __attribute__((noinline, noclone)) b (int i) { a (i); } + static void __attribute__((noinline, noclone)) a (int i) + { if (i) b (i - 1); else c (0); } + int main (void) { a (5); return 0; } + + (gdb) bt + #0 c (i=i@entry=0) at t.c:2 + #1 0x0000000000400428 in a (DW_OP_GNU_entry_value resolving has found + function "a" at 0x400420 can call itself via tail calls + i=) at t.c:6 + #2 0x000000000040036e in main () at t.c:7 + + GDB cannot find out from the inferior state if and how many times did +function 'a' call itself (via function 'b') as these calls would be tail +calls. Such tail calls would modify thue 'i' variable, therefore GDB +cannot be sure the value it knows would be right - GDB prints +'' instead. + + +File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Optimized Code, Up: Top + +12 C Preprocessor Macros +************************ + +Some languages, such as C and C++, provide a way to define and invoke +"preprocessor macros" which expand into strings of tokens. GDB can +evaluate expressions containing macro invocations, show the result of +macro expansion, and show a macro's definition, including where it was +defined. + + You may need to compile your program specially to provide GDB with +information about preprocessor macros. Most compilers do not include +macros in their debugging information, even when you compile with the +'-g' flag. *Note Compilation::. + + A program may define a macro at one point, remove that definition +later, and then provide a different definition after that. Thus, at +different points in the program, a macro may have different definitions, +or have no definition at all. If there is a current stack frame, GDB +uses the macros in scope at that frame's source code line. Otherwise, +GDB uses the macros in scope at the current listing location; see *note +List::. + + Whenever GDB evaluates an expression, it always expands any macro +invocations present in the expression. GDB also provides the following +commands for working with macros explicitly. + +'macro expand EXPRESSION' +'macro exp EXPRESSION' + Show the results of expanding all preprocessor macro invocations in + EXPRESSION. Since GDB simply expands macros, but does not parse + the result, EXPRESSION need not be a valid expression; it can be + any string of tokens. + +'macro expand-once EXPRESSION' +'macro exp1 EXPRESSION' + (This command is not yet implemented.) Show the results of + expanding those preprocessor macro invocations that appear + explicitly in EXPRESSION. Macro invocations appearing in that + expansion are left unchanged. This command allows you to see the + effect of a particular macro more clearly, without being confused + by further expansions. Since GDB simply expands macros, but does + not parse the result, EXPRESSION need not be a valid expression; it + can be any string of tokens. + +'info macro [-a|-all] [--] MACRO' + Show the current definition or all definitions of the named MACRO, + and describe the source location or compiler command-line where + that definition was established. The optional double dash is to + signify the end of argument processing and the beginning of MACRO + for non C-like macros where the macro may begin with a hyphen. + +'info macros LINESPEC' + Show all macro definitions that are in effect at the location + specified by LINESPEC, and describe the source location or compiler + command-line where those definitions were established. + +'macro define MACRO REPLACEMENT-LIST' +'macro define MACRO(ARGLIST) REPLACEMENT-LIST' + Introduce a definition for a preprocessor macro named MACRO, + invocations of which are replaced by the tokens given in + REPLACEMENT-LIST. The first form of this command defines an + "object-like" macro, which takes no arguments; the second form + defines a "function-like" macro, which takes the arguments given in + ARGLIST. + + A definition introduced by this command is in scope in every + expression evaluated in GDB, until it is removed with the 'macro + undef' command, described below. The definition overrides all + definitions for MACRO present in the program being debugged, as + well as any previous user-supplied definition. + +'macro undef MACRO' + Remove any user-supplied definition for the macro named MACRO. + This command only affects definitions provided with the 'macro + define' command, described above; it cannot remove definitions + present in the program being debugged. + +'macro list' + List all the macros defined using the 'macro define' command. + + Here is a transcript showing the above commands in action. First, we +show our source files: + + $ cat sample.c + #include + #include "sample.h" + + #define M 42 + #define ADD(x) (M + x) + + main () + { + #define N 28 + printf ("Hello, world!\n"); + #undef N + printf ("We're so creative.\n"); + #define N 1729 + printf ("Goodbye, world!\n"); + } + $ cat sample.h + #define Q < + $ + + Now, we compile the program using the GNU C compiler, GCC. We pass +the '-gdwarf-2'(1) _and_ '-g3' flags to ensure the compiler includes +information about preprocessor macros in the debugging information. + + $ gcc -gdwarf-2 -g3 sample.c -o sample + $ + + Now, we start GDB on our sample program: + + $ gdb -nw sample + GNU gdb 2002-05-06-cvs + Copyright 2002 Free Software Foundation, Inc. + GDB is free software, ... + (gdb) + + We can expand macros and examine their definitions, even when the +program is not running. GDB uses the current listing position to decide +which macro definitions are in scope: + + (gdb) list main + 3 + 4 #define M 42 + 5 #define ADD(x) (M + x) + 6 + 7 main () + 8 { + 9 #define N 28 + 10 printf ("Hello, world!\n"); + 11 #undef N + 12 printf ("We're so creative.\n"); + (gdb) info macro ADD + Defined at /home/jimb/gdb/macros/play/sample.c:5 + #define ADD(x) (M + x) + (gdb) info macro Q + Defined at /home/jimb/gdb/macros/play/sample.h:1 + included at /home/jimb/gdb/macros/play/sample.c:2 + #define Q < + (gdb) macro expand ADD(1) + expands to: (42 + 1) + (gdb) macro expand-once ADD(1) + expands to: once (M + 1) + (gdb) + + In the example above, note that 'macro expand-once' expands only the +macro invocation explicit in the original text -- the invocation of +'ADD' -- but does not expand the invocation of the macro 'M', which was +introduced by 'ADD'. + + Once the program is running, GDB uses the macro definitions in force +at the source line of the current stack frame: + + (gdb) break main + Breakpoint 1 at 0x8048370: file sample.c, line 10. + (gdb) run + Starting program: /home/jimb/gdb/macros/play/sample + + Breakpoint 1, main () at sample.c:10 + 10 printf ("Hello, world!\n"); + (gdb) + + At line 10, the definition of the macro 'N' at line 9 is in force: + + (gdb) info macro N + Defined at /home/jimb/gdb/macros/play/sample.c:9 + #define N 28 + (gdb) macro expand N Q M + expands to: 28 < 42 + (gdb) print N Q M + $1 = 1 + (gdb) + + As we step over directives that remove 'N''s definition, and then +give it a new definition, GDB finds the definition (or lack thereof) in +force at each point: + + (gdb) next + Hello, world! + 12 printf ("We're so creative.\n"); + (gdb) info macro N + The symbol `N' has no definition as a C/C++ preprocessor macro + at /home/jimb/gdb/macros/play/sample.c:12 + (gdb) next + We're so creative. + 14 printf ("Goodbye, world!\n"); + (gdb) info macro N + Defined at /home/jimb/gdb/macros/play/sample.c:13 + #define N 1729 + (gdb) macro expand N Q M + expands to: 1729 < 42 + (gdb) print N Q M + $2 = 0 + (gdb) + + In addition to source files, macros can be defined on the compilation +command line using the '-DNAME=VALUE' syntax. For macros defined in +such a way, GDB displays the location of their definition as line zero +of the source file submitted to the compiler. + + (gdb) info macro __STDC__ + Defined at /home/jimb/gdb/macros/play/sample.c:0 + -D__STDC__=1 + (gdb) + + ---------- Footnotes ---------- + + (1) This is the minimum. Recent versions of GCC support '-gdwarf-3' +and '-gdwarf-4'; we recommend always choosing the most recent version of +DWARF. + + +File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top + +13 Tracepoints +************** + +In some applications, it is not feasible for the debugger to interrupt +the program's execution long enough for the developer to learn anything +helpful about its behavior. If the program's correctness depends on its +real-time behavior, delays introduced by a debugger might cause the +program to change its behavior drastically, or perhaps fail, even when +the code itself is correct. It is useful to be able to observe the +program's behavior without interrupting it. + + Using GDB's 'trace' and 'collect' commands, you can specify locations +in the program, called "tracepoints", and arbitrary expressions to +evaluate when those tracepoints are reached. Later, using the 'tfind' +command, you can examine the values those expressions had when the +program hit the tracepoints. The expressions may also denote objects in +memory--structures or arrays, for example--whose values GDB should +record; while visiting a particular tracepoint, you may inspect those +objects as if they were in memory at that moment. However, because GDB +records these values without interacting with you, it can do so quickly +and unobtrusively, hopefully not disturbing the program's behavior. + + The tracepoint facility is currently available only for remote +targets. *Note Targets::. In addition, your remote target must know +how to collect trace data. This functionality is implemented in the +remote stub; however, none of the stubs distributed with GDB support +tracepoints as of this writing. The format of the remote packets used +to implement tracepoints are described in *note Tracepoint Packets::. + + It is also possible to get trace data from a file, in a manner +reminiscent of corefiles; you specify the filename, and use 'tfind' to +search through the file. *Note Trace Files::, for more details. + + This chapter describes the tracepoint commands and features. + +* Menu: + +* Set Tracepoints:: +* Analyze Collected Data:: +* Tracepoint Variables:: +* Trace Files:: + + +File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints + +13.1 Commands to Set Tracepoints +================================ + +Before running such a "trace experiment", an arbitrary number of +tracepoints can be set. A tracepoint is actually a special type of +breakpoint (*note Set Breaks::), so you can manipulate it using standard +breakpoint commands. For instance, as with breakpoints, tracepoint +numbers are successive integers starting from one, and many of the +commands associated with tracepoints take the tracepoint number as their +argument, to identify which tracepoint to work on. + + For each tracepoint, you can specify, in advance, some arbitrary set +of data that you want the target to collect in the trace buffer when it +hits that tracepoint. The collected data can include registers, local +variables, or global data. Later, you can use GDB commands to examine +the values these data had at the time the tracepoint was hit. + + Tracepoints do not support every breakpoint feature. Ignore counts +on tracepoints have no effect, and tracepoints cannot run GDB commands +when they are hit. Tracepoints may not be thread-specific either. + + Some targets may support "fast tracepoints", which are inserted in a +different way (such as with a jump instead of a trap), that is faster +but possibly restricted in where they may be installed. + + Regular and fast tracepoints are dynamic tracing facilities, meaning +that they can be used to insert tracepoints at (almost) any location in +the target. Some targets may also support controlling "static +tracepoints" from GDB. With static tracing, a set of instrumentation +points, also known as "markers", are embedded in the target program, and +can be activated or deactivated by name or address. These are usually +placed at locations which facilitate investigating what the target is +actually doing. GDB's support for static tracing includes being able to +list instrumentation points, and attach them with GDB defined high level +tracepoints that expose the whole range of convenience of GDB's +tracepoints support. Namely, support for collecting registers values +and values of global or local (to the instrumentation point) variables; +tracepoint conditions and trace state variables. The act of installing +a GDB static tracepoint on an instrumentation point, or marker, is +referred to as "probing" a static tracepoint marker. + + 'gdbserver' supports tracepoints on some target systems. *Note +Tracepoints support in 'gdbserver': Server. + + This section describes commands to set tracepoints and associated +conditions and actions. + +* Menu: + +* Create and Delete Tracepoints:: +* Enable and Disable Tracepoints:: +* Tracepoint Passcounts:: +* Tracepoint Conditions:: +* Trace State Variables:: +* Tracepoint Actions:: +* Listing Tracepoints:: +* Listing Static Tracepoint Markers:: +* Starting and Stopping Trace Experiments:: +* Tracepoint Restrictions:: + + +File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints + +13.1.1 Create and Delete Tracepoints +------------------------------------ + +'trace LOCATION' + The 'trace' command is very similar to the 'break' command. Its + argument LOCATION can be a source line, a function name, or an + address in the target program. *Note Specify Location::. The + 'trace' command defines a tracepoint, which is a point in the + target program where the debugger will briefly stop, collect some + data, and then allow the program to continue. Setting a tracepoint + or changing its actions takes effect immediately if the remote stub + supports the 'InstallInTrace' feature (*note install tracepoint in + tracing::). If remote stub doesn't support the 'InstallInTrace' + feature, all these changes don't take effect until the next + 'tstart' command, and once a trace experiment is running, further + changes will not have any effect until the next trace experiment + starts. In addition, GDB supports "pending + tracepoints"--tracepoints whose address is not yet resolved. (This + is similar to pending breakpoints.) Pending tracepoints are not + downloaded to the target and not installed until they are resolved. + The resolution of pending tracepoints requires GDB support--when + debugging with the remote target, and GDB disconnects from the + remote stub (*note disconnected tracing::), pending tracepoints can + not be resolved (and downloaded to the remote stub) while GDB is + disconnected. + + Here are some examples of using the 'trace' command: + + (gdb) trace foo.c:121 // a source file and line number + + (gdb) trace +2 // 2 lines forward + + (gdb) trace my_function // first source line of function + + (gdb) trace *my_function // EXACT start address of function + + (gdb) trace *0x2117c4 // an address + + You can abbreviate 'trace' as 'tr'. + +'trace LOCATION if COND' + Set a tracepoint with condition COND; evaluate the expression COND + each time the tracepoint is reached, and collect data only if the + value is nonzero--that is, if COND evaluates as true. *Note + Tracepoint Conditions: Tracepoint Conditions, for more information + on tracepoint conditions. + +'ftrace LOCATION [ if COND ]' + The 'ftrace' command sets a fast tracepoint. For targets that + support them, fast tracepoints will use a more efficient but + possibly less general technique to trigger data collection, such as + a jump instruction instead of a trap, or some sort of hardware + support. It may not be possible to create a fast tracepoint at the + desired location, in which case the command will exit with an + explanatory message. + + GDB handles arguments to 'ftrace' exactly as for 'trace'. + + On 32-bit x86-architecture systems, fast tracepoints normally need + to be placed at an instruction that is 5 bytes or longer, but can + be placed at 4-byte instructions if the low 64K of memory of the + target program is available to install trampolines. Some Unix-type + systems, such as GNU/Linux, exclude low addresses from the + program's address space; but for instance with the Linux kernel it + is possible to let GDB use this area by doing a 'sysctl' command to + set the 'mmap_min_addr' kernel parameter, as in + + sudo sysctl -w vm.mmap_min_addr=32768 + + which sets the low address to 32K, which leaves plenty of room for + trampolines. The minimum address should be set to a page boundary. + +'strace LOCATION [ if COND ]' + The 'strace' command sets a static tracepoint. For targets that + support it, setting a static tracepoint probes a static + instrumentation point, or marker, found at LOCATION. It may not be + possible to set a static tracepoint at the desired location, in + which case the command will exit with an explanatory message. + + GDB handles arguments to 'strace' exactly as for 'trace', with the + addition that the user can also specify '-m MARKER' as LOCATION. + This probes the marker identified by the MARKER string identifier. + This identifier depends on the static tracepoint backend library + your program is using. You can find all the marker identifiers in + the 'ID' field of the 'info static-tracepoint-markers' command + output. *Note Listing Static Tracepoint Markers: Listing Static + Tracepoint Markers. For example, in the following small program + using the UST tracing engine: + + main () + { + trace_mark(ust, bar33, "str %s", "FOOBAZ"); + } + + the marker id is composed of joining the first two arguments to the + 'trace_mark' call with a slash, which translates to: + + (gdb) info static-tracepoint-markers + Cnt Enb ID Address What + 1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 + Data: "str %s" + [etc...] + + so you may probe the marker above with: + + (gdb) strace -m ust/bar33 + + Static tracepoints accept an extra collect action -- 'collect + $_sdata'. This collects arbitrary user data passed in the probe + point call to the tracing library. In the UST example above, + you'll see that the third argument to 'trace_mark' is a printf-like + format string. The user data is then the result of running that + formating string against the following arguments. Note that 'info + static-tracepoint-markers' command output lists that format string + in the 'Data:' field. + + You can inspect this data when analyzing the trace buffer, by + printing the $_sdata variable like any other variable available to + GDB. *Note Tracepoint Action Lists: Tracepoint Actions. + + The convenience variable '$tpnum' records the tracepoint number of + the most recently set tracepoint. + +'delete tracepoint [NUM]' + Permanently delete one or more tracepoints. With no argument, the + default is to delete all tracepoints. Note that the regular + 'delete' command can remove tracepoints also. + + Examples: + + (gdb) delete trace 1 2 3 // remove three tracepoints + + (gdb) delete trace // remove all tracepoints + + You can abbreviate this command as 'del tr'. + + +File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints + +13.1.2 Enable and Disable Tracepoints +------------------------------------- + +These commands are deprecated; they are equivalent to plain 'disable' +and 'enable'. + +'disable tracepoint [NUM]' + Disable tracepoint NUM, or all tracepoints if no argument NUM is + given. A disabled tracepoint will have no effect during a trace + experiment, but it is not forgotten. You can re-enable a disabled + tracepoint using the 'enable tracepoint' command. If the command + is issued during a trace experiment and the debug target has + support for disabling tracepoints during a trace experiment, then + the change will be effective immediately. Otherwise, it will be + applied to the next trace experiment. + +'enable tracepoint [NUM]' + Enable tracepoint NUM, or all tracepoints. If this command is + issued during a trace experiment and the debug target supports + enabling tracepoints during a trace experiment, then the enabled + tracepoints will become effective immediately. Otherwise, they + will become effective the next time a trace experiment is run. + + +File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Conditions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints + +13.1.3 Tracepoint Passcounts +---------------------------- + +'passcount [N [NUM]]' + Set the "passcount" of a tracepoint. The passcount is a way to + automatically stop a trace experiment. If a tracepoint's passcount + is N, then the trace experiment will be automatically stopped on + the N'th time that tracepoint is hit. If the tracepoint number NUM + is not specified, the 'passcount' command sets the passcount of the + most recently defined tracepoint. If no passcount is given, the + trace experiment will run until stopped explicitly by the user. + + Examples: + + (gdb) passcount 5 2 // Stop on the 5th execution of + // tracepoint 2 + + (gdb) passcount 12 // Stop on the 12th execution of the + // most recently defined tracepoint. + (gdb) trace foo + (gdb) pass 3 + (gdb) trace bar + (gdb) pass 2 + (gdb) trace baz + (gdb) pass 1 // Stop tracing when foo has been + // executed 3 times OR when bar has + // been executed 2 times + // OR when baz has been executed 1 time. + + +File: gdb.info, Node: Tracepoint Conditions, Next: Trace State Variables, Prev: Tracepoint Passcounts, Up: Set Tracepoints + +13.1.4 Tracepoint Conditions +---------------------------- + +The simplest sort of tracepoint collects data every time your program +reaches a specified place. You can also specify a "condition" for a +tracepoint. A condition is just a Boolean expression in your +programming language (*note Expressions: Expressions.). A tracepoint +with a condition evaluates the expression each time your program reaches +it, and data collection happens only if the condition is true. + + Tracepoint conditions can be specified when a tracepoint is set, by +using 'if' in the arguments to the 'trace' command. *Note Setting +Tracepoints: Create and Delete Tracepoints. They can also be set or +changed at any time with the 'condition' command, just as with +breakpoints. + + Unlike breakpoint conditions, GDB does not actually evaluate the +conditional expression itself. Instead, GDB encodes the expression into +an agent expression (*note Agent Expressions::) suitable for execution +on the target, independently of GDB. Global variables become raw memory +locations, locals become stack accesses, and so forth. + + For instance, suppose you have a function that is usually called +frequently, but should not be called after an error has occurred. You +could use the following tracepoint command to collect data about calls +of that function that happen while the error code is propagating through +the program; an unconditional tracepoint could end up collecting +thousands of useless trace frames that you would have to search through. + + (gdb) trace normal_operation if errcode > 0 + + +File: gdb.info, Node: Trace State Variables, Next: Tracepoint Actions, Prev: Tracepoint Conditions, Up: Set Tracepoints + +13.1.5 Trace State Variables +---------------------------- + +A "trace state variable" is a special type of variable that is created +and managed by target-side code. The syntax is the same as that for +GDB's convenience variables (a string prefixed with "$"), but they are +stored on the target. They must be created explicitly, using a +'tvariable' command. They are always 64-bit signed integers. + + Trace state variables are remembered by GDB, and downloaded to the +target along with tracepoint information when the trace experiment +starts. There are no intrinsic limits on the number of trace state +variables, beyond memory limitations of the target. + + Although trace state variables are managed by the target, you can use +them in print commands and expressions as if they were convenience +variables; GDB will get the current value from the target while the +trace experiment is running. Trace state variables share the same +namespace as other "$" variables, which means that you cannot have trace +state variables with names like '$23' or '$pc', nor can you have a trace +state variable and a convenience variable with the same name. + +'tvariable $NAME [ = EXPRESSION ]' + The 'tvariable' command creates a new trace state variable named + '$NAME', and optionally gives it an initial value of EXPRESSION. + EXPRESSION is evaluated when this command is entered; the result + will be converted to an integer if possible, otherwise GDB will + report an error. A subsequent 'tvariable' command specifying the + same name does not create a variable, but instead assigns the + supplied initial value to the existing variable of that name, + overwriting any previous initial value. The default initial value + is 0. + +'info tvariables' + List all the trace state variables along with their initial values. + Their current values may also be displayed, if the trace experiment + is currently running. + +'delete tvariable [ $NAME ... ]' + Delete the given trace state variables, or all of them if no + arguments are specified. + + +File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Trace State Variables, Up: Set Tracepoints + +13.1.6 Tracepoint Action Lists +------------------------------ + +'actions [NUM]' + This command will prompt for a list of actions to be taken when the + tracepoint is hit. If the tracepoint number NUM is not specified, + this command sets the actions for the one that was most recently + defined (so that you can define a tracepoint and then say 'actions' + without bothering about its number). You specify the actions + themselves on the following lines, one action at a time, and + terminate the actions list with a line containing just 'end'. So + far, the only defined actions are 'collect', 'teval', and + 'while-stepping'. + + 'actions' is actually equivalent to 'commands' (*note Breakpoint + Command Lists: Break Commands.), except that only the defined + actions are allowed; any other GDB command is rejected. + + To remove all actions from a tracepoint, type 'actions NUM' and + follow it immediately with 'end'. + + (gdb) collect DATA // collect some data + + (gdb) while-stepping 5 // single-step 5 times, collect data + + (gdb) end // signals the end of actions. + + In the following example, the action list begins with 'collect' + commands indicating the things to be collected when the tracepoint + is hit. Then, in order to single-step and collect additional data + following the tracepoint, a 'while-stepping' command is used, + followed by the list of things to be collected after each step in a + sequence of single steps. The 'while-stepping' command is + terminated by its own separate 'end' command. Lastly, the action + list is terminated by an 'end' command. + + (gdb) trace foo + (gdb) actions + Enter actions for tracepoint 1, one per line: + > collect bar,baz + > collect $regs + > while-stepping 12 + > collect $pc, arr[i] + > end + end + +'collect[/MODS] EXPR1, EXPR2, ...' + Collect values of the given expressions when the tracepoint is hit. + This command accepts a comma-separated list of any valid + expressions. In addition to global, static, or local variables, + the following special arguments are supported: + + '$regs' + Collect all registers. + + '$args' + Collect all function arguments. + + '$locals' + Collect all local variables. + + '$_ret' + Collect the return address. This is helpful if you want to + see more of a backtrace. + + '$_probe_argc' + Collects the number of arguments from the static probe at + which the tracepoint is located. *Note Static Probe Points::. + + '$_probe_argN' + N is an integer between 0 and 11. Collects the Nth argument + from the static probe at which the tracepoint is located. + *Note Static Probe Points::. + + '$_sdata' + Collect static tracepoint marker specific data. Only + available for static tracepoints. *Note Tracepoint Action + Lists: Tracepoint Actions. On the UST static tracepoints + library backend, an instrumentation point resembles a 'printf' + function call. The tracing library is able to collect user + specified data formatted to a character string using the + format provided by the programmer that instrumented the + program. Other backends have similar mechanisms. Here's an + example of a UST marker call: + + const char master_name[] = "$your_name"; + trace_mark(channel1, marker1, "hello %s", master_name) + + In this case, collecting '$_sdata' collects the string 'hello + $yourname'. When analyzing the trace buffer, you can inspect + '$_sdata' like any other variable available to GDB. + + You can give several consecutive 'collect' commands, each one with + a single argument, or one 'collect' command with several arguments + separated by commas; the effect is the same. + + The optional MODS changes the usual handling of the arguments. 's' + requests that pointers to chars be handled as strings, in + particular collecting the contents of the memory being pointed at, + up to the first zero. The upper bound is by default the value of + the 'print elements' variable; if 's' is followed by a decimal + number, that is the upper bound instead. So for instance + 'collect/s25 mystr' collects as many as 25 characters at 'mystr'. + + The command 'info scope' (*note info scope: Symbols.) is + particularly useful for figuring out what data to collect. + +'teval EXPR1, EXPR2, ...' + Evaluate the given expressions when the tracepoint is hit. This + command accepts a comma-separated list of expressions. The results + are discarded, so this is mainly useful for assigning values to + trace state variables (*note Trace State Variables::) without + adding those values to the trace buffer, as would be the case if + the 'collect' action were used. + +'while-stepping N' + Perform N single-step instruction traces after the tracepoint, + collecting new data after each step. The 'while-stepping' command + is followed by the list of what to collect while stepping (followed + by its own 'end' command): + + > while-stepping 12 + > collect $regs, myglobal + > end + > + + Note that '$pc' is not automatically collected by 'while-stepping'; + you need to explicitly collect that register if you need it. You + may abbreviate 'while-stepping' as 'ws' or 'stepping'. + +'set default-collect EXPR1, EXPR2, ...' + This variable is a list of expressions to collect at each + tracepoint hit. It is effectively an additional 'collect' action + prepended to every tracepoint action list. The expressions are + parsed individually for each tracepoint, so for instance a variable + named 'xyz' may be interpreted as a global for one tracepoint, and + a local for another, as appropriate to the tracepoint's location. + +'show default-collect' + Show the list of expressions that are collected by default at each + tracepoint hit. + + +File: gdb.info, Node: Listing Tracepoints, Next: Listing Static Tracepoint Markers, Prev: Tracepoint Actions, Up: Set Tracepoints + +13.1.7 Listing Tracepoints +-------------------------- + +'info tracepoints [NUM...]' + Display information about the tracepoint NUM. If you don't specify + a tracepoint number, displays information about all the tracepoints + defined so far. The format is similar to that used for 'info + breakpoints'; in fact, 'info tracepoints' is the same command, + simply restricting itself to tracepoints. + + A tracepoint's listing may include additional information specific + to tracing: + + * its passcount as given by the 'passcount N' command + + * the state about installed on target of each location + + (gdb) info trace + Num Type Disp Enb Address What + 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 + while-stepping 20 + collect globfoo, $regs + end + collect globfoo2 + end + pass count 1200 + 2 tracepoint keep y + collect $eip + 2.1 y 0x0804859c in func4 at change-loc.h:35 + installed on target + 2.2 y 0xb7ffc480 in func4 at change-loc.h:35 + installed on target + 2.3 y set_tracepoint + 3 tracepoint keep y 0x080485b1 in foo at change-loc.c:29 + not installed on target + (gdb) + + This command can be abbreviated 'info tp'. + + +File: gdb.info, Node: Listing Static Tracepoint Markers, Next: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints + +13.1.8 Listing Static Tracepoint Markers +---------------------------------------- + +'info static-tracepoint-markers' + Display information about all static tracepoint markers defined in + the program. + + For each marker, the following columns are printed: + + _Count_ + An incrementing counter, output to help readability. This is + not a stable identifier. + _ID_ + The marker ID, as reported by the target. + _Enabled or Disabled_ + Probed markers are tagged with 'y'. 'n' identifies marks that + are not enabled. + _Address_ + Where the marker is in your program, as a memory address. + _What_ + Where the marker is in the source for your program, as a file + and line number. If the debug information included in the + program does not allow GDB to locate the source of the marker, + this column will be left blank. + + In addition, the following information may be printed for each + marker: + + _Data_ + User data passed to the tracing library by the marker call. + In the UST backend, this is the format string passed as + argument to the marker call. + _Static tracepoints probing the marker_ + The list of static tracepoints attached to the marker. + + (gdb) info static-tracepoint-markers + Cnt ID Enb Address What + 1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 + Data: number1 %d number2 %d + Probed by static tracepoints: #2 + 2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 + Data: str %s + (gdb) + + +File: gdb.info, Node: Starting and Stopping Trace Experiments, Next: Tracepoint Restrictions, Prev: Listing Static Tracepoint Markers, Up: Set Tracepoints + +13.1.9 Starting and Stopping Trace Experiments +---------------------------------------------- + +'tstart' + This command starts the trace experiment, and begins collecting + data. It has the side effect of discarding all the data collected + in the trace buffer during the previous trace experiment. If any + arguments are supplied, they are taken as a note and stored with + the trace experiment's state. The notes may be arbitrary text, and + are especially useful with disconnected tracing in a multi-user + context; the notes can explain what the trace is doing, supply user + contact information, and so forth. + +'tstop' + This command stops the trace experiment. If any arguments are + supplied, they are recorded with the experiment as a note. This is + useful if you are stopping a trace started by someone else, for + instance if the trace is interfering with the system's behavior and + needs to be stopped quickly. + + *Note*: a trace experiment and data collection may stop + automatically if any tracepoint's passcount is reached (*note + Tracepoint Passcounts::), or if the trace buffer becomes full. + +'tstatus' + This command displays the status of the current trace data + collection. + + Here is an example of the commands we described so far: + + (gdb) trace gdb_c_test + (gdb) actions + Enter actions for tracepoint #1, one per line. + > collect $regs,$locals,$args + > while-stepping 11 + > collect $regs + > end + > end + (gdb) tstart + [time passes ...] + (gdb) tstop + + You can choose to continue running the trace experiment even if GDB +disconnects from the target, voluntarily or involuntarily. For commands +such as 'detach', the debugger will ask what you want to do with the +trace. But for unexpected terminations (GDB crash, network outage), it +would be unfortunate to lose hard-won trace data, so the variable +'disconnected-tracing' lets you decide whether the trace should continue +running without GDB. + +'set disconnected-tracing on' +'set disconnected-tracing off' + Choose whether a tracing run should continue to run if GDB has + disconnected from the target. Note that 'detach' or 'quit' will + ask you directly what to do about a running trace no matter what + this variable's setting, so the variable is mainly useful for + handling unexpected situations, such as loss of the network. + +'show disconnected-tracing' + Show the current choice for disconnected tracing. + + When you reconnect to the target, the trace experiment may or may not +still be running; it might have filled the trace buffer in the meantime, +or stopped for one of the other reasons. If it is running, it will +continue after reconnection. + + Upon reconnection, the target will upload information about the +tracepoints in effect. GDB will then compare that information to the +set of tracepoints currently defined, and attempt to match them up, +allowing for the possibility that the numbers may have changed due to +creation and deletion in the meantime. If one of the target's +tracepoints does not match any in GDB, the debugger will create a new +tracepoint, so that you have a number with which to specify that +tracepoint. This matching-up process is necessarily heuristic, and it +may result in useless tracepoints being created; you may simply delete +them if they are of no use. + + If your target agent supports a "circular trace buffer", then you can +run a trace experiment indefinitely without filling the trace buffer; +when space runs out, the agent deletes already-collected trace frames, +oldest first, until there is enough room to continue collecting. This +is especially useful if your tracepoints are being hit too often, and +your trace gets terminated prematurely because the buffer is full. To +ask for a circular trace buffer, simply set 'circular-trace-buffer' to +on. You can set this at any time, including during tracing; if the +agent can do it, it will change buffer handling on the fly, otherwise it +will not take effect until the next run. + +'set circular-trace-buffer on' +'set circular-trace-buffer off' + Choose whether a tracing run should use a linear or circular buffer + for trace data. A linear buffer will not lose any trace data, but + may fill up prematurely, while a circular buffer will discard old + trace data, but it will have always room for the latest tracepoint + hits. + +'show circular-trace-buffer' + Show the current choice for the trace buffer. Note that this may + not match the agent's current buffer handling, nor is it guaranteed + to match the setting that might have been in effect during a past + run, for instance if you are looking at frames from a trace file. + +'set trace-buffer-size N' +'set trace-buffer-size unlimited' + Request that the target use a trace buffer of N bytes. Not all + targets will honor the request; they may have a compiled-in size + for the trace buffer, or some other limitation. Set to a value of + 'unlimited' or '-1' to let the target use whatever size it likes. + This is also the default. + +'show trace-buffer-size' + Show the current requested size for the trace buffer. Note that + this will only match the actual size if the target supports + size-setting, and was able to handle the requested size. For + instance, if the target can only change buffer size between runs, + this variable will not reflect the change until the next run + starts. Use 'tstatus' to get a report of the actual buffer size. + +'set trace-user TEXT' + +'show trace-user' + +'set trace-notes TEXT' + Set the trace run's notes. + +'show trace-notes' + Show the trace run's notes. + +'set trace-stop-notes TEXT' + Set the trace run's stop notes. The handling of the note is as for + 'tstop' arguments; the set command is convenient way to fix a stop + note that is mistaken or incomplete. + +'show trace-stop-notes' + Show the trace run's stop notes. + + +File: gdb.info, Node: Tracepoint Restrictions, Prev: Starting and Stopping Trace Experiments, Up: Set Tracepoints + +13.1.10 Tracepoint Restrictions +------------------------------- + +There are a number of restrictions on the use of tracepoints. As +described above, tracepoint data gathering occurs on the target without +interaction from GDB. Thus the full capabilities of the debugger are +not available during data gathering, and then at data examination time, +you will be limited by only having what was collected. The following +items describe some common problems, but it is not exhaustive, and you +may run into additional difficulties not mentioned here. + + * Tracepoint expressions are intended to gather objects (lvalues). + Thus the full flexibility of GDB's expression evaluator is not + available. You cannot call functions, cast objects to aggregate + types, access convenience variables or modify values (except by + assignment to trace state variables). Some language features may + implicitly call functions (for instance Objective-C fields with + accessors), and therefore cannot be collected either. + + * Collection of local variables, either individually or in bulk with + '$locals' or '$args', during 'while-stepping' may behave + erratically. The stepping action may enter a new scope (for + instance by stepping into a function), or the location of the + variable may change (for instance it is loaded into a register). + The tracepoint data recorded uses the location information for the + variables that is correct for the tracepoint location. When the + tracepoint is created, it is not possible, in general, to determine + where the steps of a 'while-stepping' sequence will advance the + program--particularly if a conditional branch is stepped. + + * Collection of an incompletely-initialized or partially-destroyed + object may result in something that GDB cannot display, or displays + in a misleading way. + + * When GDB displays a pointer to character it automatically + dereferences the pointer to also display characters of the string + being pointed to. However, collecting the pointer during tracing + does not automatically collect the string. You need to explicitly + dereference the pointer and provide size information if you want to + collect not only the pointer, but the memory pointed to. For + example, '*ptr@50' can be used to collect the 50 element array + pointed to by 'ptr'. + + * It is not possible to collect a complete stack backtrace at a + tracepoint. Instead, you may collect the registers and a few + hundred bytes from the stack pointer with something like + '*(unsigned char *)$esp@300' (adjust to use the name of the actual + stack pointer register on your target architecture, and the amount + of stack you wish to capture). Then the 'backtrace' command will + show a partial backtrace when using a trace frame. The number of + stack frames that can be examined depends on the sizes of the + frames in the collected stack. Note that if you ask for a block so + large that it goes past the bottom of the stack, the target agent + may report an error trying to read from an invalid address. + + * If you do not collect registers at a tracepoint, GDB can infer that + the value of '$pc' must be the same as the address of the + tracepoint and use that when you are looking at a trace frame for + that tracepoint. However, this cannot work if the tracepoint has + multiple locations (for instance if it was set in a function that + was inlined), or if it has a 'while-stepping' loop. In those cases + GDB will warn you that it can't infer '$pc', and default it to + zero. + + +File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints + +13.2 Using the Collected Data +============================= + +After the tracepoint experiment ends, you use GDB commands for examining +the trace data. The basic idea is that each tracepoint collects a trace +"snapshot" every time it is hit and another snapshot every time it +single-steps. All these snapshots are consecutively numbered from zero +and go into a buffer, and you can examine them later. The way you +examine them is to "focus" on a specific trace snapshot. When the +remote stub is focused on a trace snapshot, it will respond to all GDB +requests for memory and registers by reading from the buffer which +belongs to that snapshot, rather than from _real_ memory or registers of +the program being debugged. This means that *all* GDB commands +('print', 'info registers', 'backtrace', etc.) will behave as if we +were currently debugging the program state as it was when the tracepoint +occurred. Any requests for data that are not in the buffer will fail. + +* Menu: + +* tfind:: How to select a trace snapshot +* tdump:: How to display all data for a snapshot +* save tracepoints:: How to save tracepoints for a future run + + +File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data + +13.2.1 'tfind N' +---------------- + +The basic command for selecting a trace snapshot from the buffer is +'tfind N', which finds trace snapshot number N, counting from zero. If +no argument N is given, the next snapshot is selected. + + Here are the various forms of using the 'tfind' command. + +'tfind start' + Find the first snapshot in the buffer. This is a synonym for + 'tfind 0' (since 0 is the number of the first snapshot). + +'tfind none' + Stop debugging trace snapshots, resume _live_ debugging. + +'tfind end' + Same as 'tfind none'. + +'tfind' + No argument means find the next trace snapshot. + +'tfind -' + Find the previous trace snapshot before the current one. This + permits retracing earlier steps. + +'tfind tracepoint NUM' + Find the next snapshot associated with tracepoint NUM. Search + proceeds forward from the last examined trace snapshot. If no + argument NUM is given, it means find the next snapshot collected + for the same tracepoint as the current snapshot. + +'tfind pc ADDR' + Find the next snapshot associated with the value ADDR of the + program counter. Search proceeds forward from the last examined + trace snapshot. If no argument ADDR is given, it means find the + next snapshot with the same value of PC as the current snapshot. + +'tfind outside ADDR1, ADDR2' + Find the next snapshot whose PC is outside the given range of + addresses (exclusive). + +'tfind range ADDR1, ADDR2' + Find the next snapshot whose PC is between ADDR1 and ADDR2 + (inclusive). + +'tfind line [FILE:]N' + Find the next snapshot associated with the source line N. If the + optional argument FILE is given, refer to line N in that source + file. Search proceeds forward from the last examined trace + snapshot. If no argument N is given, it means find the next line + other than the one currently being examined; thus saying 'tfind + line' repeatedly can appear to have the same effect as stepping + from line to line in a _live_ debugging session. + + The default arguments for the 'tfind' commands are specifically +designed to make it easy to scan through the trace buffer. For +instance, 'tfind' with no argument selects the next trace snapshot, and +'tfind -' with no argument selects the previous trace snapshot. So, by +giving one 'tfind' command, and then simply hitting repeatedly you +can examine all the trace snapshots in order. Or, by saying 'tfind -' +and then hitting repeatedly you can examine the snapshots in +reverse order. The 'tfind line' command with no argument selects the +snapshot for the next source line executed. The 'tfind pc' command with +no argument selects the next snapshot with the same program counter (PC) +as the current frame. The 'tfind tracepoint' command with no argument +selects the next trace snapshot collected by the same tracepoint as the +current one. + + In addition to letting you scan through the trace buffer manually, +these commands make it easy to construct GDB scripts that scan through +the trace buffer and print out whatever collected data you are +interested in. Thus, if we want to examine the PC, FP, and SP registers +from each trace frame in the buffer, we can say this: + + (gdb) tfind start + (gdb) while ($trace_frame != -1) + > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ + $trace_frame, $pc, $sp, $fp + > tfind + > end + + Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 + Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 + Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 + Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 + Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 + Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 + Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 + Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 + Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 + Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 + Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 + + Or, if we want to examine the variable 'X' at each source line in the +buffer: + + (gdb) tfind start + (gdb) while ($trace_frame != -1) + > printf "Frame %d, X == %d\n", $trace_frame, X + > tfind line + > end + + Frame 0, X = 1 + Frame 7, X = 2 + Frame 13, X = 255 + + +File: gdb.info, Node: tdump, Next: save tracepoints, Prev: tfind, Up: Analyze Collected Data + +13.2.2 'tdump' +-------------- + +This command takes no arguments. It prints all the data collected at +the current trace snapshot. + + (gdb) trace 444 + (gdb) actions + Enter actions for tracepoint #2, one per line: + > collect $regs, $locals, $args, gdb_long_test + > end + + (gdb) tstart + + (gdb) tfind line 444 + #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) + at gdb_test.c:444 + 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) + + (gdb) tdump + Data collected at tracepoint 2, trace frame 1: + d0 0xc4aa0085 -995491707 + d1 0x18 24 + d2 0x80 128 + d3 0x33 51 + d4 0x71aea3d 119204413 + d5 0x22 34 + d6 0xe0 224 + d7 0x380035 3670069 + a0 0x19e24a 1696330 + a1 0x3000668 50333288 + a2 0x100 256 + a3 0x322000 3284992 + a4 0x3000698 50333336 + a5 0x1ad3cc 1758156 + fp 0x30bf3c 0x30bf3c + sp 0x30bf34 0x30bf34 + ps 0x0 0 + pc 0x20b2c8 0x20b2c8 + fpcontrol 0x0 0 + fpstatus 0x0 0 + fpiaddr 0x0 0 + p = 0x20e5b4 "gdb-test" + p1 = (void *) 0x11 + p2 = (void *) 0x22 + p3 = (void *) 0x33 + p4 = (void *) 0x44 + p5 = (void *) 0x55 + p6 = (void *) 0x66 + gdb_long_test = 17 '\021' + + (gdb) + + 'tdump' works by scanning the tracepoint's current collection actions +and printing the value of each expression listed. So 'tdump' can fail, +if after a run, you change the tracepoint's actions to mention variables +that were not collected during the run. + + Also, for tracepoints with 'while-stepping' loops, 'tdump' uses the +collected value of '$pc' to distinguish between trace frames that were +collected at the tracepoint hit, and frames that were collected while +stepping. This allows it to correctly choose whether to display the +basic list of collections, or the collections from the body of the +while-stepping loop. However, if '$pc' was not collected, then 'tdump' +will always attempt to dump using the basic collection list, and may +fail if a while-stepping frame does not include all the same data that +is collected at the tracepoint hit. + + +File: gdb.info, Node: save tracepoints, Prev: tdump, Up: Analyze Collected Data + +13.2.3 'save tracepoints FILENAME' +---------------------------------- + +This command saves all current tracepoint definitions together with +their actions and passcounts, into a file 'FILENAME' suitable for use in +a later debugging session. To read the saved tracepoint definitions, +use the 'source' command (*note Command Files::). The 'save-tracepoints' +command is a deprecated alias for 'save tracepoints' + + +File: gdb.info, Node: Tracepoint Variables, Next: Trace Files, Prev: Analyze Collected Data, Up: Tracepoints + +13.3 Convenience Variables for Tracepoints +========================================== + +'(int) $trace_frame' + The current trace snapshot (a.k.a. "frame") number, or -1 if no + snapshot is selected. + +'(int) $tracepoint' + The tracepoint for the current trace snapshot. + +'(int) $trace_line' + The line number for the current trace snapshot. + +'(char []) $trace_file' + The source file for the current trace snapshot. + +'(char []) $trace_func' + The name of the function containing '$tracepoint'. + + Note: '$trace_file' is not suitable for use in 'printf', use 'output' +instead. + + Here's a simple example of using these convenience variables for +stepping through all the trace snapshots and printing some of their +data. Note that these are not the same as trace state variables, which +are managed by the target. + + (gdb) tfind start + + (gdb) while $trace_frame != -1 + > output $trace_file + > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint + > tfind + > end + + +File: gdb.info, Node: Trace Files, Prev: Tracepoint Variables, Up: Tracepoints + +13.4 Using Trace Files +====================== + +In some situations, the target running a trace experiment may no longer +be available; perhaps it crashed, or the hardware was needed for a +different activity. To handle these cases, you can arrange to dump the +trace data into a file, and later use that file as a source of trace +data, via the 'target tfile' command. + +'tsave [ -r ] FILENAME' +'tsave [-ctf] DIRNAME' + Save the trace data to FILENAME. By default, this command assumes + that FILENAME refers to the host filesystem, so if necessary GDB + will copy raw trace data up from the target and then save it. If + the target supports it, you can also supply the optional argument + '-r' ("remote") to direct the target to save the data directly into + FILENAME in its own filesystem, which may be more efficient if the + trace buffer is very large. (Note, however, that 'target tfile' + can only read from files accessible to the host.) By default, this + command will save trace frame in tfile format. You can supply the + optional argument '-ctf' to save date in CTF format. The "Common + Trace Format" (CTF) is proposed as a trace format that can be + shared by multiple debugging and tracing tools. Please go to + 'http://www.efficios.com/ctf' to get more information. + +'target tfile FILENAME' +'target ctf DIRNAME' + Use the file named FILENAME or directory named DIRNAME as a source + of trace data. Commands that examine data work as they do with a + live target, but it is not possible to run any new trace + experiments. 'tstatus' will report the state of the trace run at + the moment the data was saved, as well as the current trace frame + you are examining. FILENAME or DIRNAME must be on a filesystem + accessible to the host. + + (gdb) target ctf ctf.ctf + (gdb) tfind + Found trace frame 0, tracepoint 2 + 39 ++a; /* set tracepoint 1 here */ + (gdb) tdump + Data collected at tracepoint 2, trace frame 0: + i = 0 + a = 0 + b = 1 '\001' + c = {"123", "456", "789", "123", "456", "789"} + d = {{{a = 1, b = 2}, {a = 3, b = 4}}, {{a = 5, b = 6}, {a = 7, b = 8}}} + (gdb) p b + $1 = 1 + + +File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top + +14 Debugging Programs That Use Overlays +*************************************** + +If your program is too large to fit completely in your target system's +memory, you can sometimes use "overlays" to work around this problem. +GDB provides some support for debugging programs that use overlays. + +* Menu: + +* How Overlays Work:: A general explanation of overlays. +* Overlay Commands:: Managing overlays in GDB. +* Automatic Overlay Debugging:: GDB can find out which overlays are + mapped by asking the inferior. +* Overlay Sample Program:: A sample program using overlays. + + +File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays + +14.1 How Overlays Work +====================== + +Suppose you have a computer whose instruction address space is only 64 +kilobytes long, but which has much more memory which can be accessed by +other means: special instructions, segment registers, or memory +management hardware, for example. Suppose further that you want to +adapt a program which is larger than 64 kilobytes to run on this system. + + One solution is to identify modules of your program which are +relatively independent, and need not call each other directly; call +these modules "overlays". Separate the overlays from the main program, +and place their machine code in the larger memory. Place your main +program in instruction memory, but leave at least enough space there to +hold the largest overlay as well. + + Now, to call a function located in an overlay, you must first copy +that overlay's machine code from the large memory into the space set +aside for it in the instruction memory, and then jump to its entry point +there. + + Data Instruction Larger + Address Space Address Space Address Space + +-----------+ +-----------+ +-----------+ + | | | | | | + +-----------+ +-----------+ +-----------+<-- overlay 1 + | program | | main | .----| overlay 1 | load address + | variables | | program | | +-----------+ + | and heap | | | | | | + +-----------+ | | | +-----------+<-- overlay 2 + | | +-----------+ | | | load address + +-----------+ | | | .-| overlay 2 | + | | | | | | + mapped --->+-----------+ | | +-----------+ + address | | | | | | + | overlay | <-' | | | + | area | <---' +-----------+<-- overlay 3 + | | <---. | | load address + +-----------+ `--| overlay 3 | + | | | | + +-----------+ | | + +-----------+ + | | + +-----------+ + + A code overlay + + The diagram (*note A code overlay::) shows a system with separate +data and instruction address spaces. To map an overlay, the program +copies its code from the larger address space to the instruction address +space. Since the overlays shown here all use the same mapped address, +only one may be mapped at a time. For a system with a single address +space for data and instructions, the diagram would be similar, except +that the program variables and heap would share an address space with +the main program and the overlay area. + + An overlay loaded into instruction memory and ready for use is called +a "mapped" overlay; its "mapped address" is its address in the +instruction memory. An overlay not present (or only partially present) +in instruction memory is called "unmapped"; its "load address" is its +address in the larger memory. The mapped address is also called the +"virtual memory address", or "VMA"; the load address is also called the +"load memory address", or "LMA". + + Unfortunately, overlays are not a completely transparent way to adapt +a program to limited instruction memory. They introduce a new set of +global constraints you must keep in mind as you design your program: + + * Before calling or returning to a function in an overlay, your + program must make sure that overlay is actually mapped. Otherwise, + the call or return will transfer control to the right address, but + in the wrong overlay, and your program will probably crash. + + * If the process of mapping an overlay is expensive on your system, + you will need to choose your overlays carefully to minimize their + effect on your program's performance. + + * The executable file you load onto your system must contain each + overlay's instructions, appearing at the overlay's load address, + not its mapped address. However, each overlay's instructions must + be relocated and its symbols defined as if the overlay were at its + mapped address. You can use GNU linker scripts to specify + different load and relocation addresses for pieces of your program; + see *note (ld.info)Overlay Description::. + + * The procedure for loading executable files onto your system must be + able to load their contents into the larger address space as well + as the instruction and data spaces. + + The overlay system described above is rather simple, and could be +improved in many ways: + + * If your system has suitable bank switch registers or memory + management hardware, you could use those facilities to make an + overlay's load area contents simply appear at their mapped address + in instruction space. This would probably be faster than copying + the overlay to its mapped area in the usual way. + + * If your overlays are small enough, you could set aside more than + one overlay area, and have more than one overlay mapped at a time. + + * You can use overlays to manage data, as well as instructions. In + general, data overlays are even less transparent to your design + than code overlays: whereas code overlays only require care when + you call or return to functions, data overlays require care every + time you access the data. Also, if you change the contents of a + data overlay, you must copy its contents back out to its load + address before you can copy a different data overlay into the same + mapped area. + + +File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays + +14.2 Overlay Commands +===================== + +To use GDB's overlay support, each overlay in your program must +correspond to a separate section of the executable file. The section's +virtual memory address and load memory address must be the overlay's +mapped and load addresses. Identifying overlays with sections allows +GDB to determine the appropriate address of a function or variable, +depending on whether the overlay is mapped or not. + + GDB's overlay commands all start with the word 'overlay'; you can +abbreviate this as 'ov' or 'ovly'. The commands are: + +'overlay off' + Disable GDB's overlay support. When overlay support is disabled, + GDB assumes that all functions and variables are always present at + their mapped addresses. By default, GDB's overlay support is + disabled. + +'overlay manual' + Enable "manual" overlay debugging. In this mode, GDB relies on you + to tell it which overlays are mapped, and which are not, using the + 'overlay map-overlay' and 'overlay unmap-overlay' commands + described below. + +'overlay map-overlay OVERLAY' +'overlay map OVERLAY' + Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of + the object file section containing the overlay. When an overlay is + mapped, GDB assumes it can find the overlay's functions and + variables at their mapped addresses. GDB assumes that any other + overlays whose mapped ranges overlap that of OVERLAY are now + unmapped. + +'overlay unmap-overlay OVERLAY' +'overlay unmap OVERLAY' + Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the name + of the object file section containing the overlay. When an overlay + is unmapped, GDB assumes it can find the overlay's functions and + variables at their load addresses. + +'overlay auto' + Enable "automatic" overlay debugging. In this mode, GDB consults a + data structure the overlay manager maintains in the inferior to see + which overlays are mapped. For details, see *note Automatic + Overlay Debugging::. + +'overlay load-target' +'overlay load' + Re-read the overlay table from the inferior. Normally, GDB + re-reads the table GDB automatically each time the inferior stops, + so this command should only be necessary if you have changed the + overlay mapping yourself using GDB. This command is only useful + when using automatic overlay debugging. + +'overlay list-overlays' +'overlay list' + Display a list of the overlays currently mapped, along with their + mapped addresses, load addresses, and sizes. + + Normally, when GDB prints a code address, it includes the name of the +function the address falls in: + + (gdb) print main + $3 = {int ()} 0x11a0
+When overlay debugging is enabled, GDB recognizes code in unmapped +overlays, and prints the names of unmapped functions with asterisks +around them. For example, if 'foo' is a function in an unmapped +overlay, GDB prints it this way: + + (gdb) overlay list + No sections are mapped. + (gdb) print foo + $5 = {int (int)} 0x100000 <*foo*> +When 'foo''s overlay is mapped, GDB prints the function's name normally: + + (gdb) overlay list + Section .ov.foo.text, loaded at 0x100000 - 0x100034, + mapped at 0x1016 - 0x104a + (gdb) print foo + $6 = {int (int)} 0x1016 + + When overlay debugging is enabled, GDB can find the correct address +for functions and variables in an overlay, whether or not the overlay is +mapped. This allows most GDB commands, like 'break' and 'disassemble', +to work normally, even on unmapped code. However, GDB's breakpoint +support has some limitations: + + * You can set breakpoints in functions in unmapped overlays, as long + as GDB can write to the overlay at its load address. + * GDB can not set hardware or simulator-based breakpoints in unmapped + overlays. However, if you set a breakpoint at the end of your + overlay manager (and tell GDB which overlays are now mapped, if you + are using manual overlay management), GDB will re-set its + breakpoints properly. + + +File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays + +14.3 Automatic Overlay Debugging +================================ + +GDB can automatically track which overlays are mapped and which are not, +given some simple co-operation from the overlay manager in the inferior. +If you enable automatic overlay debugging with the 'overlay auto' +command (*note Overlay Commands::), GDB looks in the inferior's memory +for certain variables describing the current state of the overlays. + + Here are the variables your overlay manager must define to support +GDB's automatic overlay debugging: + +'_ovly_table': + This variable must be an array of the following structures: + + struct + { + /* The overlay's mapped address. */ + unsigned long vma; + + /* The size of the overlay, in bytes. */ + unsigned long size; + + /* The overlay's load address. */ + unsigned long lma; + + /* Non-zero if the overlay is currently mapped; + zero otherwise. */ + unsigned long mapped; + } + +'_novlys': + This variable must be a four-byte signed integer, holding the total + number of elements in '_ovly_table'. + + To decide whether a particular overlay is mapped or not, GDB looks +for an entry in '_ovly_table' whose 'vma' and 'lma' members equal the +VMA and LMA of the overlay's section in the executable file. When GDB +finds a matching entry, it consults the entry's 'mapped' member to +determine whether the overlay is currently mapped. + + In addition, your overlay manager may define a function called +'_ovly_debug_event'. If this function is defined, GDB will silently set +a breakpoint there. If the overlay manager then calls this function +whenever it has changed the overlay table, this will enable GDB to +accurately keep track of which overlays are in program memory, and +update any breakpoints that may be set in overlays. This will allow +breakpoints to work even if the overlays are kept in ROM or other +non-writable memory while they are not being executed. + + +File: gdb.info, Node: Overlay Sample Program, Prev: Automatic Overlay Debugging, Up: Overlays + +14.4 Overlay Sample Program +=========================== + +When linking a program which uses overlays, you must place the overlays +at their load addresses, while relocating them to run at their mapped +addresses. To do this, you must write a linker script (*note +(ld.info)Overlay Description::). Unfortunately, since linker scripts +are specific to a particular host system, target architecture, and +target memory layout, this manual cannot provide portable sample code +demonstrating GDB's overlay support. + + However, the GDB source distribution does contain an overlaid +program, with linker scripts for a few systems, as part of its test +suite. The program consists of the following files from +'gdb/testsuite/gdb.base': + +'overlays.c' + The main program file. +'ovlymgr.c' + A simple overlay manager, used by 'overlays.c'. +'foo.c' +'bar.c' +'baz.c' +'grbx.c' + Overlay modules, loaded and used by 'overlays.c'. +'d10v.ld' +'m32r.ld' + Linker scripts for linking the test program on the 'd10v-elf' and + 'm32r-elf' targets. + + You can build the test program using the 'd10v-elf' GCC +cross-compiler like this: + + $ d10v-elf-gcc -g -c overlays.c + $ d10v-elf-gcc -g -c ovlymgr.c + $ d10v-elf-gcc -g -c foo.c + $ d10v-elf-gcc -g -c bar.c + $ d10v-elf-gcc -g -c baz.c + $ d10v-elf-gcc -g -c grbx.c + $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ + baz.o grbx.o -Wl,-Td10v.ld -o overlays + + The build process is identical for any other architecture, except +that you must substitute the appropriate compiler and linker script for +the target system for 'd10v-elf-gcc' and 'd10v.ld'. + + +File: gdb.info, Node: Languages, Next: Symbols, Prev: Overlays, Up: Top + +15 Using GDB with Different Languages +************************************* + +Although programming languages generally have common aspects, they are +rarely expressed in the same manner. For instance, in ANSI C, +dereferencing a pointer 'p' is accomplished by '*p', but in Modula-2, it +is accomplished by 'p^'. Values can also be represented (and displayed) +differently. Hex numbers in C appear as '0x1ae', while in Modula-2 they +appear as '1AEH'. + + Language-specific information is built into GDB for some languages, +allowing you to express operations like the above in your program's +native language, and allowing GDB to output values in a manner +consistent with the syntax of your program's native language. The +language you use to build expressions is called the "working language". + +* Menu: + +* Setting:: Switching between source languages +* Show:: Displaying the language +* Checks:: Type and range checks +* Supported Languages:: Supported languages +* Unsupported Languages:: Unsupported languages + + +File: gdb.info, Node: Setting, Next: Show, Up: Languages + +15.1 Switching Between Source Languages +======================================= + +There are two ways to control the working language--either have GDB set +it automatically, or select it manually yourself. You can use the 'set +language' command for either purpose. On startup, GDB defaults to +setting the language automatically. The working language is used to +determine how expressions you type are interpreted, how values are +printed, etc. + + In addition to the working language, every source file that GDB knows +about has its own working language. For some object file formats, the +compiler might indicate which language a particular source file is in. +However, most of the time GDB infers the language from the name of the +file. The language of a source file controls whether C++ names are +demangled--this way 'backtrace' can show each frame appropriately for +its own language. There is no way to set the language of a source file +from within GDB, but you can set the language associated with a filename +extension. *Note Displaying the Language: Show. + + This is most commonly a problem when you use a program, such as +'cfront' or 'f2c', that generates C but is written in another language. +In that case, make the program use '#line' directives in its C output; +that way GDB will know the correct language of the source code of the +original program, and will display that source code, not the generated C +code. + +* Menu: + +* Filenames:: Filename extensions and languages. +* Manually:: Setting the working language manually +* Automatically:: Having GDB infer the source language + + +File: gdb.info, Node: Filenames, Next: Manually, Up: Setting + +15.1.1 List of Filename Extensions and Languages +------------------------------------------------ + +If a source file name ends in one of the following extensions, then GDB +infers that its language is the one indicated. + +'.ada' +'.ads' +'.adb' +'.a' + Ada source file. + +'.c' + C source file + +'.C' +'.cc' +'.cp' +'.cpp' +'.cxx' +'.c++' + C++ source file + +'.d' + D source file + +'.m' + Objective-C source file + +'.f' +'.F' + Fortran source file + +'.mod' + Modula-2 source file + +'.s' +'.S' + Assembler source file. This actually behaves almost like C, but + GDB does not skip over function prologues when stepping. + + In addition, you may set the language associated with a filename +extension. *Note Displaying the Language: Show. + + +File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting + +15.1.2 Setting the Working Language +----------------------------------- + +If you allow GDB to set the language automatically, expressions are +interpreted the same way in your debugging session and your program. + + If you wish, you may set the language manually. To do this, issue +the command 'set language LANG', where LANG is the name of a language, +such as 'c' or 'modula-2'. For a list of the supported languages, type +'set language'. + + Setting the language manually prevents GDB from updating the working +language automatically. This can lead to confusion if you try to debug +a program when the working language is not the same as the source +language, when an expression is acceptable to both languages--but means +different things. For instance, if the current source file were written +in C, and GDB was parsing Modula-2, a command such as: + + print a = b + c + +might not have the effect you intended. In C, this means to add 'b' and +'c' and place the result in 'a'. The result printed would be the value +of 'a'. In Modula-2, this means to compare 'a' to the result of 'b+c', +yielding a 'BOOLEAN' value. + + +File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting + +15.1.3 Having GDB Infer the Source Language +------------------------------------------- + +To have GDB set the working language automatically, use 'set language +local' or 'set language auto'. GDB then infers the working language. +That is, when your program stops in a frame (usually by encountering a +breakpoint), GDB sets the working language to the language recorded for +the function in that frame. If the language for a frame is unknown +(that is, if the function or block corresponding to the frame was +defined in a source file that does not have a recognized extension), the +current working language is not changed, and GDB issues a warning. + + This may not seem necessary for most programs, which are written +entirely in one source language. However, program modules and libraries +written in one source language can be used by a main program written in +a different source language. Using 'set language auto' in this case +frees you from having to set the working language manually. + + +File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages + +15.2 Displaying the Language +============================ + +The following commands help you find out which language is the working +language, and also what language source files were written in. + +'show language' + Display the current working language. This is the language you can + use with commands such as 'print' to build and compute expressions + that may involve variables in your program. + +'info frame' + Display the source language for this frame. This language becomes + the working language if you use an identifier from this frame. + *Note Information about a Frame: Frame Info, to identify the other + information listed here. + +'info source' + Display the source language of this source file. *Note Examining + the Symbol Table: Symbols, to identify the other information listed + here. + + In unusual circumstances, you may have source files with extensions +not in the standard list. You can then set the extension associated +with a language explicitly: + +'set extension-language EXT LANGUAGE' + Tell GDB that source files with extension EXT are to be assumed as + written in the source language LANGUAGE. + +'info extensions' + List all the filename extensions and the associated languages. + + +File: gdb.info, Node: Checks, Next: Supported Languages, Prev: Show, Up: Languages + +15.3 Type and Range Checking +============================ + +Some languages are designed to guard you against making seemingly common +errors through a series of compile- and run-time checks. These include +checking the type of arguments to functions and operators and making +sure mathematical overflows are caught at run time. Checks such as +these help to ensure a program's correctness once it has been compiled +by eliminating type mismatches and providing active checks for range +errors when your program is running. + + By default GDB checks for these errors according to the rules of the +current source language. Although GDB does not check the statements in +your program, it can check expressions entered directly into GDB for +evaluation via the 'print' command, for example. + +* Menu: + +* Type Checking:: An overview of type checking +* Range Checking:: An overview of range checking + + +File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks + +15.3.1 An Overview of Type Checking +----------------------------------- + +Some languages, such as C and C++, are strongly typed, meaning that the +arguments to operators and functions have to be of the correct type, +otherwise an error occurs. These checks prevent type mismatch errors +from ever causing any run-time problems. For example, + + int klass::my_method(char *b) { return b ? 1 : 2; } + + (gdb) print obj.my_method (0) + $1 = 2 +but + (gdb) print obj.my_method (0x1234) + Cannot resolve method klass::my_method to any overloaded instance + + The second example fails because in C++ the integer constant '0x1234' +is not type-compatible with the pointer parameter type. + + For the expressions you use in GDB commands, you can tell GDB to not +enforce strict type checking or to treat any mismatches as errors and +abandon the expression; When type checking is disabled, GDB successfully +evaluates expressions like the second example above. + + Even if type checking is off, there may be other reasons related to +type that prevent GDB from evaluating an expression. For instance, GDB +does not know how to add an 'int' and a 'struct foo'. These particular +type errors have nothing to do with the language in use and usually +arise from expressions which make little sense to evaluate anyway. + + GDB provides some additional commands for controlling type checking: + +'set check type on' +'set check type off' + Set strict type checking on or off. If any type mismatches occur + in evaluating an expression while type checking is on, GDB prints a + message and aborts evaluation of the expression. + +'show check type' + Show the current setting of type checking and whether GDB is + enforcing strict type checking rules. + + +File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks + +15.3.2 An Overview of Range Checking +------------------------------------ + +In some languages (such as Modula-2), it is an error to exceed the +bounds of a type; this is enforced with run-time checks. Such range +checking is meant to ensure program correctness by making sure +computations do not overflow, or indices on an array element access do +not exceed the bounds of the array. + + For expressions you use in GDB commands, you can tell GDB to treat +range errors in one of three ways: ignore them, always treat them as +errors and abandon the expression, or issue warnings but evaluate the +expression anyway. + + A range error can result from numerical overflow, from exceeding an +array index bound, or when you type a constant that is not a member of +any type. Some languages, however, do not treat overflows as an error. +In many implementations of C, mathematical overflow causes the result to +"wrap around" to lower values--for example, if M is the largest integer +value, and S is the smallest, then + + M + 1 => S + + This, too, is specific to individual languages, and in some cases +specific to individual compilers or machines. *Note Supported +Languages: Supported Languages, for further details on specific +languages. + + GDB provides some additional commands for controlling the range +checker: + +'set check range auto' + Set range checking on or off based on the current working language. + *Note Supported Languages: Supported Languages, for the default + settings for each language. + +'set check range on' +'set check range off' + Set range checking on or off, overriding the default setting for + the current working language. A warning is issued if the setting + does not match the language default. If a range error occurs and + range checking is on, then a message is printed and evaluation of + the expression is aborted. + +'set check range warn' + Output messages when the GDB range checker detects a range error, + but attempt to evaluate the expression anyway. Evaluating the + expression may still be impossible for other reasons, such as + accessing memory that the process does not own (a typical example + from many Unix systems). + +'show range' + Show the current setting of the range checker, and whether or not + it is being set automatically by GDB. + + +File: gdb.info, Node: Supported Languages, Next: Unsupported Languages, Prev: Checks, Up: Languages + +15.4 Supported Languages +======================== + +GDB supports C, C++, D, Go, Objective-C, Fortran, Java, OpenCL C, +Pascal, assembly, Modula-2, and Ada. Some GDB features may be used in +expressions regardless of the language you use: the GDB '@' and '::' +operators, and the '{type}addr' construct (*note Expressions: +Expressions.) can be used with the constructs of any supported language. + + The following sections detail to what degree each source language is +supported by GDB. These sections are not meant to be language tutorials +or references, but serve only as a reference guide to what the GDB +expression parser accepts, and what input and output formats should look +like for different languages. There are many good books written on each +of these languages; please look to these for a language reference or +tutorial. + +* Menu: + +* C:: C and C++ +* D:: D +* Go:: Go +* Objective-C:: Objective-C +* OpenCL C:: OpenCL C +* Fortran:: Fortran +* Pascal:: Pascal +* Modula-2:: Modula-2 +* Ada:: Ada + + +File: gdb.info, Node: C, Next: D, Up: Supported Languages + +15.4.1 C and C++ +---------------- + +Since C and C++ are so closely related, many features of GDB apply to +both languages. Whenever this is the case, we discuss those languages +together. + + The C++ debugging facilities are jointly implemented by the C++ +compiler and GDB. Therefore, to debug your C++ code effectively, you +must compile your C++ programs with a supported C++ compiler, such as +GNU 'g++', or the HP ANSI C++ compiler ('aCC'). + +* Menu: + +* C Operators:: C and C++ operators +* C Constants:: C and C++ constants +* C Plus Plus Expressions:: C++ expressions +* C Defaults:: Default settings for C and C++ +* C Checks:: C and C++ type and range checks +* Debugging C:: GDB and C +* Debugging C Plus Plus:: GDB features for C++ +* Decimal Floating Point:: Numbers in Decimal Floating Point format + + +File: gdb.info, Node: C Operators, Next: C Constants, Up: C + +15.4.1.1 C and C++ Operators +............................ + +Operators must be defined on values of specific types. For instance, +'+' is defined on numbers, but not on structures. Operators are often +defined on groups of types. + + For the purposes of C and C++, the following definitions hold: + + * _Integral types_ include 'int' with any of its storage-class + specifiers; 'char'; 'enum'; and, for C++, 'bool'. + + * _Floating-point types_ include 'float', 'double', and 'long double' + (if supported by the target platform). + + * _Pointer types_ include all types defined as '(TYPE *)'. + + * _Scalar types_ include all of the above. + +The following operators are supported. They are listed here in order of +increasing precedence: + +',' + The comma or sequencing operator. Expressions in a comma-separated + list are evaluated from left to right, with the result of the + entire expression being the last expression evaluated. + +'=' + Assignment. The value of an assignment expression is the value + assigned. Defined on scalar types. + +'OP=' + Used in an expression of the form 'A OP= B', and translated to + 'A = A OP B'. 'OP=' and '=' have the same precedence. OP is any + one of the operators '|', '^', '&', '<<', '>>', '+', '-', '*', '/', + '%'. + +'?:' + The ternary operator. 'A ? B : C' can be thought of as: if A then + B else C. A should be of an integral type. + +'||' + Logical OR. Defined on integral types. + +'&&' + Logical AND. Defined on integral types. + +'|' + Bitwise OR. Defined on integral types. + +'^' + Bitwise exclusive-OR. Defined on integral types. + +'&' + Bitwise AND. Defined on integral types. + +'==, !=' + Equality and inequality. Defined on scalar types. The value of + these expressions is 0 for false and non-zero for true. + +'<, >, <=, >=' + Less than, greater than, less than or equal, greater than or equal. + Defined on scalar types. The value of these expressions is 0 for + false and non-zero for true. + +'<<, >>' + left shift, and right shift. Defined on integral types. + +'@' + The GDB "artificial array" operator (*note Expressions: + Expressions.). + +'+, -' + Addition and subtraction. Defined on integral types, + floating-point types and pointer types. + +'*, /, %' + Multiplication, division, and modulus. Multiplication and division + are defined on integral and floating-point types. Modulus is + defined on integral types. + +'++, --' + Increment and decrement. When appearing before a variable, the + operation is performed before the variable is used in an + expression; when appearing after it, the variable's value is used + before the operation takes place. + +'*' + Pointer dereferencing. Defined on pointer types. Same precedence + as '++'. + +'&' + Address operator. Defined on variables. Same precedence as '++'. + + For debugging C++, GDB implements a use of '&' beyond what is + allowed in the C++ language itself: you can use '&(&REF)' to + examine the address where a C++ reference variable (declared with + '&REF') is stored. + +'-' + Negative. Defined on integral and floating-point types. Same + precedence as '++'. + +'!' + Logical negation. Defined on integral types. Same precedence as + '++'. + +'~' + Bitwise complement operator. Defined on integral types. Same + precedence as '++'. + +'., ->' + Structure member, and pointer-to-structure member. For + convenience, GDB regards the two as equivalent, choosing whether to + dereference a pointer based on the stored type information. + Defined on 'struct' and 'union' data. + +'.*, ->*' + Dereferences of pointers to members. + +'[]' + Array indexing. 'A[I]' is defined as '*(A+I)'. Same precedence as + '->'. + +'()' + Function parameter list. Same precedence as '->'. + +'::' + C++ scope resolution operator. Defined on 'struct', 'union', and + 'class' types. + +'::' + Doubled colons also represent the GDB scope operator (*note + Expressions: Expressions.). Same precedence as '::', above. + + If an operator is redefined in the user code, GDB usually attempts to +invoke the redefined version instead of using the operator's predefined +meaning. + + +File: gdb.info, Node: C Constants, Next: C Plus Plus Expressions, Prev: C Operators, Up: C + +15.4.1.2 C and C++ Constants +............................ + +GDB allows you to express the constants of C and C++ in the following +ways: + + * Integer constants are a sequence of digits. Octal constants are + specified by a leading '0' (i.e. zero), and hexadecimal constants + by a leading '0x' or '0X'. Constants may also end with a letter + 'l', specifying that the constant should be treated as a 'long' + value. + + * Floating point constants are a sequence of digits, followed by a + decimal point, followed by a sequence of digits, and optionally + followed by an exponent. An exponent is of the form: + 'e[[+]|-]NNN', where NNN is another sequence of digits. The '+' is + optional for positive exponents. A floating-point constant may + also end with a letter 'f' or 'F', specifying that the constant + should be treated as being of the 'float' (as opposed to the + default 'double') type; or with a letter 'l' or 'L', which + specifies a 'long double' constant. + + * Enumerated constants consist of enumerated identifiers, or their + integral equivalents. + + * Character constants are a single character surrounded by single + quotes ('''), or a number--the ordinal value of the corresponding + character (usually its ASCII value). Within quotes, the single + character may be represented by a letter or by "escape sequences", + which are of the form '\NNN', where NNN is the octal representation + of the character's ordinal value; or of the form '\X', where 'X' is + a predefined special character--for example, '\n' for newline. + + Wide character constants can be written by prefixing a character + constant with 'L', as in C. For example, 'L'x'' is the wide form of + 'x'. The target wide character set is used when computing the + value of this constant (*note Character Sets::). + + * String constants are a sequence of character constants surrounded + by double quotes ('"'). Any valid character constant (as described + above) may appear. Double quotes within the string must be + preceded by a backslash, so for instance '"a\"b'c"' is a string of + five characters. + + Wide string constants can be written by prefixing a string constant + with 'L', as in C. The target wide character set is used when + computing the value of this constant (*note Character Sets::). + + * Pointer constants are an integral value. You can also write + pointers to constants using the C operator '&'. + + * Array constants are comma-separated lists surrounded by braces '{' + and '}'; for example, '{1,2,3}' is a three-element array of + integers, '{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and + '{&"hi", &"there", &"fred"}' is a three-element array of pointers. + + +File: gdb.info, Node: C Plus Plus Expressions, Next: C Defaults, Prev: C Constants, Up: C + +15.4.1.3 C++ Expressions +........................ + +GDB expression handling can interpret most C++ expressions. + + _Warning:_ GDB can only debug C++ code if you use the proper + compiler and the proper debug format. Currently, GDB works best + when debugging C++ code that is compiled with the most recent + version of GCC possible. The DWARF debugging format is preferred; + GCC defaults to this on most popular platforms. Other compilers + and/or debug formats are likely to work badly or not at all when + using GDB to debug C++ code. *Note Compilation::. + + 1. Member function calls are allowed; you can use expressions like + + count = aml->GetOriginal(x, y) + + 2. While a member function is active (in the selected stack frame), + your expressions have the same namespace available as the member + function; that is, GDB allows implicit references to the class + instance pointer 'this' following the same rules as C++. 'using' + declarations in the current scope are also respected by GDB. + + 3. You can call overloaded functions; GDB resolves the function call + to the right definition, with some restrictions. GDB does not + perform overload resolution involving user-defined type + conversions, calls to constructors, or instantiations of templates + that do not exist in the program. It also cannot handle ellipsis + argument lists or default arguments. + + It does perform integral conversions and promotions, floating-point + promotions, arithmetic conversions, pointer conversions, + conversions of class objects to base classes, and standard + conversions such as those of functions or arrays to pointers; it + requires an exact match on the number of function arguments. + + Overload resolution is always performed, unless you have specified + 'set overload-resolution off'. *Note GDB Features for C++: + Debugging C Plus Plus. + + You must specify 'set overload-resolution off' in order to use an + explicit function signature to call an overloaded function, as in + p 'foo(char,int)'('x', 13) + + The GDB command-completion facility can simplify this; see *note + Command Completion: Completion. + + 4. GDB understands variables declared as C++ references; you can use + them in expressions just as you do in C++ source--they are + automatically dereferenced. + + In the parameter list shown when GDB displays a frame, the values + of reference variables are not displayed (unlike other variables); + this avoids clutter, since references are often used for large + structures. The _address_ of a reference variable is always shown, + unless you have specified 'set print address off'. + + 5. GDB supports the C++ name resolution operator '::'--your + expressions can use it just as expressions in your program do. + Since one scope may be defined in another, you can use '::' + repeatedly if necessary, for example in an expression like + 'SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by + reference to source files, in both C and C++ debugging (*note + Program Variables: Variables.). + + 6. GDB performs argument-dependent lookup, following the C++ + specification. + + +File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C Plus Plus Expressions, Up: C + +15.4.1.4 C and C++ Defaults +........................... + +If you allow GDB to set range checking automatically, it defaults to +'off' whenever the working language changes to C or C++. This happens +regardless of whether you or GDB selects the working language. + + If you allow GDB to set the language automatically, it recognizes +source files whose names end with '.c', '.C', or '.cc', etc, and when +GDB enters code compiled from one of these files, it sets the working +language to C or C++. *Note Having GDB Infer the Source Language: +Automatically, for further details. + + +File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C + +15.4.1.5 C and C++ Type and Range Checks +........................................ + +By default, when GDB parses C or C++ expressions, strict type checking +is used. However, if you turn type checking off, GDB will allow certain +non-standard conversions, such as promoting integer constants to +pointers. + + Range checking, if turned on, is done on mathematical operations. +Array indices are not checked, since they are often used to index a +pointer that is not itself an array. + + +File: gdb.info, Node: Debugging C, Next: Debugging C Plus Plus, Prev: C Checks, Up: C + +15.4.1.6 GDB and C +.................. + +The 'set print union' and 'show print union' commands apply to the +'union' type. When set to 'on', any 'union' that is inside a 'struct' +or 'class' is also printed. Otherwise, it appears as '{...}'. + + The '@' operator aids in the debugging of dynamic arrays, formed with +pointers and a memory allocation function. *Note Expressions: +Expressions. + + +File: gdb.info, Node: Debugging C Plus Plus, Next: Decimal Floating Point, Prev: Debugging C, Up: C + +15.4.1.7 GDB Features for C++ +............................. + +Some GDB commands are particularly useful with C++, and some are +designed specifically for use with C++. Here is a summary: + +'breakpoint menus' + When you want a breakpoint in a function whose name is overloaded, + GDB has the capability to display a menu of possible breakpoint + locations to help you specify which function definition you want. + *Note Ambiguous Expressions: Ambiguous Expressions. + +'rbreak REGEX' + Setting breakpoints using regular expressions is helpful for + setting breakpoints on overloaded functions that are not members of + any special classes. *Note Setting Breakpoints: Set Breaks. + +'catch throw' +'catch rethrow' +'catch catch' + Debug C++ exception handling using these commands. *Note Setting + Catchpoints: Set Catchpoints. + +'ptype TYPENAME' + Print inheritance relationships as well as other information for + type TYPENAME. *Note Examining the Symbol Table: Symbols. + +'info vtbl EXPRESSION.' + The 'info vtbl' command can be used to display the virtual method + tables of the object computed by EXPRESSION. This shows one entry + per virtual table; there may be multiple virtual tables when + multiple inheritance is in use. + +'set print demangle' +'show print demangle' +'set print asm-demangle' +'show print asm-demangle' + Control whether C++ symbols display in their source form, both when + displaying code as C++ source and when displaying disassemblies. + *Note Print Settings: Print Settings. + +'set print object' +'show print object' + Choose whether to print derived (actual) or declared types of + objects. *Note Print Settings: Print Settings. + +'set print vtbl' +'show print vtbl' + Control the format for printing virtual function tables. *Note + Print Settings: Print Settings. (The 'vtbl' commands do not work + on programs compiled with the HP ANSI C++ compiler ('aCC').) + +'set overload-resolution on' + Enable overload resolution for C++ expression evaluation. The + default is on. For overloaded functions, GDB evaluates the + arguments and searches for a function whose signature matches the + argument types, using the standard C++ conversion rules (see *note + C++ Expressions: C Plus Plus Expressions, for details). If it + cannot find a match, it emits a message. + +'set overload-resolution off' + Disable overload resolution for C++ expression evaluation. For + overloaded functions that are not class member functions, GDB + chooses the first function of the specified name that it finds in + the symbol table, whether or not its arguments are of the correct + type. For overloaded functions that are class member functions, + GDB searches for a function whose signature _exactly_ matches the + argument types. + +'show overload-resolution' + Show the current setting of overload resolution. + +'Overloaded symbol names' + You can specify a particular definition of an overloaded symbol, + using the same notation that is used to declare such symbols in + C++: type 'SYMBOL(TYPES)' rather than just SYMBOL. You can also + use the GDB command-line word completion facilities to list the + available choices, or to finish the type list for you. *Note + Command Completion: Completion, for details on how to do this. + + +File: gdb.info, Node: Decimal Floating Point, Prev: Debugging C Plus Plus, Up: C + +15.4.1.8 Decimal Floating Point format +...................................... + +GDB can examine, set and perform computations with numbers in decimal +floating point format, which in the C language correspond to the +'_Decimal32', '_Decimal64' and '_Decimal128' types as specified by the +extension to support decimal floating-point arithmetic. + + There are two encodings in use, depending on the architecture: BID +(Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed +Decimal) for PowerPC and S/390. GDB will use the appropriate encoding +for the configured target. + + Because of a limitation in 'libdecnumber', the library used by GDB to +manipulate decimal floating point numbers, it is not possible to convert +(using a cast, for example) integers wider than 32-bit to decimal float. + + In addition, in order to imitate GDB's behaviour with binary floating +point computations, error checking in decimal float operations ignores +underflow, overflow and divide by zero exceptions. + + In the PowerPC architecture, GDB provides a set of pseudo-registers +to inspect '_Decimal128' values stored in floating point registers. See +*note PowerPC: PowerPC. for more details. + + +File: gdb.info, Node: D, Next: Go, Prev: C, Up: Supported Languages + +15.4.2 D +-------- + +GDB can be used to debug programs written in D and compiled with GDC, +LDC or DMD compilers. Currently GDB supports only one D specific +feature -- dynamic arrays. + + +File: gdb.info, Node: Go, Next: Objective-C, Prev: D, Up: Supported Languages + +15.4.3 Go +--------- + +GDB can be used to debug programs written in Go and compiled with +'gccgo' or '6g' compilers. + + Here is a summary of the Go-specific features and restrictions: + +'The current Go package' + The name of the current package does not need to be specified when + specifying global variables and functions. + + For example, given the program: + + package main + var myglob = "Shall we?" + func main () { + // ... + } + + When stopped inside 'main' either of these work: + + (gdb) p myglob + (gdb) p main.myglob + +'Builtin Go types' + The 'string' type is recognized by GDB and is printed as a string. + +'Builtin Go functions' + The GDB expression parser recognizes the 'unsafe.Sizeof' function + and handles it internally. + +'Restrictions on Go expressions' + All Go operators are supported except '&^'. The Go '_' "blank + identifier" is not supported. Automatic dereferencing of pointers + is not supported. + + +File: gdb.info, Node: Objective-C, Next: OpenCL C, Prev: Go, Up: Supported Languages + +15.4.4 Objective-C +------------------ + +This section provides information about some commands and command +options that are useful for debugging Objective-C code. See also *note +info classes: Symbols, and *note info selectors: Symbols, for a few more +commands specific to Objective-C support. + +* Menu: + +* Method Names in Commands:: +* The Print Command with Objective-C:: + + +File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Up: Objective-C + +15.4.4.1 Method Names in Commands +................................. + +The following commands have been extended to accept Objective-C method +names as line specifications: + + * 'clear' + * 'break' + * 'info line' + * 'jump' + * 'list' + + A fully qualified Objective-C method name is specified as + + -[CLASS METHODNAME] + + where the minus sign is used to indicate an instance method and a +plus sign (not shown) is used to indicate a class method. The class +name CLASS and method name METHODNAME are enclosed in brackets, similar +to the way messages are specified in Objective-C source code. For +example, to set a breakpoint at the 'create' instance method of class +'Fruit' in the program currently being debugged, enter: + + break -[Fruit create] + + To list ten program lines around the 'initialize' class method, +enter: + + list +[NSText initialize] + + In the current version of GDB, the plus or minus sign is required. +In future versions of GDB, the plus or minus sign will be optional, but +you can use it to narrow the search. It is also possible to specify +just a method name: + + break create + + You must specify the complete method name, including any colons. If +your program's source files contain more than one 'create' method, +you'll be presented with a numbered list of classes that implement that +method. Indicate your choice by number, or type '0' to exit if none +apply. + + As another example, to clear a breakpoint established at the +'makeKeyAndOrderFront:' method of the 'NSWindow' class, enter: + + clear -[NSWindow makeKeyAndOrderFront:] + + +File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C + +15.4.4.2 The Print Command With Objective-C +........................................... + +The print command has also been extended to accept methods. For +example: + + print -[OBJECT hash] + +will tell GDB to send the 'hash' message to OBJECT and print the result. +Also, an additional command has been added, 'print-object' or 'po' for +short, which is meant to print the description of an object. However, +this command may only work with certain Objective-C libraries that have +a particular hook function, '_NSPrintForDebugger', defined. + + +File: gdb.info, Node: OpenCL C, Next: Fortran, Prev: Objective-C, Up: Supported Languages + +15.4.5 OpenCL C +--------------- + +This section provides information about GDBs OpenCL C support. + +* Menu: + +* OpenCL C Datatypes:: +* OpenCL C Expressions:: +* OpenCL C Operators:: + + +File: gdb.info, Node: OpenCL C Datatypes, Next: OpenCL C Expressions, Up: OpenCL C + +15.4.5.1 OpenCL C Datatypes +........................... + +GDB supports the builtin scalar and vector datatypes specified by OpenCL +1.1. In addition the half- and double-precision floating point data +types of the 'cl_khr_fp16' and 'cl_khr_fp64' OpenCL extensions are also +known to GDB. + + +File: gdb.info, Node: OpenCL C Expressions, Next: OpenCL C Operators, Prev: OpenCL C Datatypes, Up: OpenCL C + +15.4.5.2 OpenCL C Expressions +............................. + +GDB supports accesses to vector components including the access as +lvalue where possible. Since OpenCL C is based on C99 most C +expressions supported by GDB can be used as well. + + +File: gdb.info, Node: OpenCL C Operators, Prev: OpenCL C Expressions, Up: OpenCL C + +15.4.5.3 OpenCL C Operators +........................... + +GDB supports the operators specified by OpenCL 1.1 for scalar and vector +data types. + + +File: gdb.info, Node: Fortran, Next: Pascal, Prev: OpenCL C, Up: Supported Languages + +15.4.6 Fortran +-------------- + +GDB can be used to debug programs written in Fortran, but it currently +supports only the features of Fortran 77 language. + + Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers among +them) append an underscore to the names of variables and functions. +When you debug programs compiled by those compilers, you will need to +refer to variables and functions with a trailing underscore. + +* Menu: + +* Fortran Operators:: Fortran operators and expressions +* Fortran Defaults:: Default settings for Fortran +* Special Fortran Commands:: Special GDB commands for Fortran + + +File: gdb.info, Node: Fortran Operators, Next: Fortran Defaults, Up: Fortran + +15.4.6.1 Fortran Operators and Expressions +.......................................... + +Operators must be defined on values of specific types. For instance, +'+' is defined on numbers, but not on characters or other non- +arithmetic types. Operators are often defined on groups of types. + +'**' + The exponentiation operator. It raises the first operand to the + power of the second one. + +':' + The range operator. Normally used in the form of array(low:high) + to represent a section of array. + +'%' + The access component operator. Normally used to access elements in + derived types. Also suitable for unions. As unions aren't part of + regular Fortran, this can only happen when accessing a register + that uses a gdbarch-defined union type. + + +File: gdb.info, Node: Fortran Defaults, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran + +15.4.6.2 Fortran Defaults +......................... + +Fortran symbols are usually case-insensitive, so GDB by default uses +case-insensitive matches for Fortran symbols. You can change that with +the 'set case-insensitive' command, see *note Symbols::, for the +details. + + +File: gdb.info, Node: Special Fortran Commands, Prev: Fortran Defaults, Up: Fortran + +15.4.6.3 Special Fortran Commands +................................. + +GDB has some commands to support Fortran-specific features, such as +displaying common blocks. + +'info common [COMMON-NAME]' + This command prints the values contained in the Fortran 'COMMON' + block whose name is COMMON-NAME. With no argument, the names of + all 'COMMON' blocks visible at the current program location are + printed. + + +File: gdb.info, Node: Pascal, Next: Modula-2, Prev: Fortran, Up: Supported Languages + +15.4.7 Pascal +------------- + +Debugging Pascal programs which use sets, subranges, file variables, or +nested functions does not currently work. GDB does not support entering +expressions, printing values, or similar features using Pascal syntax. + + The Pascal-specific command 'set print pascal_static-members' +controls whether static members of Pascal objects are displayed. *Note +pascal_static-members: Print Settings. + + +File: gdb.info, Node: Modula-2, Next: Ada, Prev: Pascal, Up: Supported Languages + +15.4.8 Modula-2 +--------------- + +The extensions made to GDB to support Modula-2 only support output from +the GNU Modula-2 compiler (which is currently being developed). Other +Modula-2 compilers are not currently supported, and attempting to debug +executables produced by them is most likely to give an error as GDB +reads in the executable's symbol table. + +* Menu: + +* M2 Operators:: Built-in operators +* Built-In Func/Proc:: Built-in functions and procedures +* M2 Constants:: Modula-2 constants +* M2 Types:: Modula-2 types +* M2 Defaults:: Default settings for Modula-2 +* Deviations:: Deviations from standard Modula-2 +* M2 Checks:: Modula-2 type and range checks +* M2 Scope:: The scope operators '::' and '.' +* GDB/M2:: GDB and Modula-2 + + +File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 + +15.4.8.1 Operators +.................. + +Operators must be defined on values of specific types. For instance, +'+' is defined on numbers, but not on structures. Operators are often +defined on groups of types. For the purposes of Modula-2, the following +definitions hold: + + * _Integral types_ consist of 'INTEGER', 'CARDINAL', and their + subranges. + + * _Character types_ consist of 'CHAR' and its subranges. + + * _Floating-point types_ consist of 'REAL'. + + * _Pointer types_ consist of anything declared as 'POINTER TO TYPE'. + + * _Scalar types_ consist of all of the above. + + * _Set types_ consist of 'SET' and 'BITSET' types. + + * _Boolean types_ consist of 'BOOLEAN'. + +The following operators are supported, and appear in order of increasing +precedence: + +',' + Function argument or array index separator. + +':=' + Assignment. The value of VAR ':=' VALUE is VALUE. + +'<, >' + Less than, greater than on integral, floating-point, or enumerated + types. + +'<=, >=' + Less than or equal to, greater than or equal to on integral, + floating-point and enumerated types, or set inclusion on set types. + Same precedence as '<'. + +'=, <>, #' + Equality and two ways of expressing inequality, valid on scalar + types. Same precedence as '<'. In GDB scripts, only '<>' is + available for inequality, since '#' conflicts with the script + comment character. + +'IN' + Set membership. Defined on set types and the types of their + members. Same precedence as '<'. + +'OR' + Boolean disjunction. Defined on boolean types. + +'AND, &' + Boolean conjunction. Defined on boolean types. + +'@' + The GDB "artificial array" operator (*note Expressions: + Expressions.). + +'+, -' + Addition and subtraction on integral and floating-point types, or + union and difference on set types. + +'*' + Multiplication on integral and floating-point types, or set + intersection on set types. + +'/' + Division on floating-point types, or symmetric set difference on + set types. Same precedence as '*'. + +'DIV, MOD' + Integer division and remainder. Defined on integral types. Same + precedence as '*'. + +'-' + Negative. Defined on 'INTEGER' and 'REAL' data. + +'^' + Pointer dereferencing. Defined on pointer types. + +'NOT' + Boolean negation. Defined on boolean types. Same precedence as + '^'. + +'.' + 'RECORD' field selector. Defined on 'RECORD' data. Same + precedence as '^'. + +'[]' + Array indexing. Defined on 'ARRAY' data. Same precedence as '^'. + +'()' + Procedure argument list. Defined on 'PROCEDURE' objects. Same + precedence as '^'. + +'::, .' + GDB and Modula-2 scope operators. + + _Warning:_ Set expressions and their operations are not yet + supported, so GDB treats the use of the operator 'IN', or the use + of operators '+', '-', '*', '/', '=', , '<>', '#', '<=', and '>=' + on sets as an error. + + +File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 + +15.4.8.2 Built-in Functions and Procedures +.......................................... + +Modula-2 also makes available several built-in procedures and functions. +In describing these, the following metavariables are used: + +A + represents an 'ARRAY' variable. + +C + represents a 'CHAR' constant or variable. + +I + represents a variable or constant of integral type. + +M + represents an identifier that belongs to a set. Generally used in + the same function with the metavariable S. The type of S should be + 'SET OF MTYPE' (where MTYPE is the type of M). + +N + represents a variable or constant of integral or floating-point + type. + +R + represents a variable or constant of floating-point type. + +T + represents a type. + +V + represents a variable. + +X + represents a variable or constant of one of many types. See the + explanation of the function for details. + + All Modula-2 built-in procedures also return a result, described +below. + +'ABS(N)' + Returns the absolute value of N. + +'CAP(C)' + If C is a lower case letter, it returns its upper case equivalent, + otherwise it returns its argument. + +'CHR(I)' + Returns the character whose ordinal value is I. + +'DEC(V)' + Decrements the value in the variable V by one. Returns the new + value. + +'DEC(V,I)' + Decrements the value in the variable V by I. Returns the new + value. + +'EXCL(M,S)' + Removes the element M from the set S. Returns the new set. + +'FLOAT(I)' + Returns the floating point equivalent of the integer I. + +'HIGH(A)' + Returns the index of the last member of A. + +'INC(V)' + Increments the value in the variable V by one. Returns the new + value. + +'INC(V,I)' + Increments the value in the variable V by I. Returns the new + value. + +'INCL(M,S)' + Adds the element M to the set S if it is not already there. + Returns the new set. + +'MAX(T)' + Returns the maximum value of the type T. + +'MIN(T)' + Returns the minimum value of the type T. + +'ODD(I)' + Returns boolean TRUE if I is an odd number. + +'ORD(X)' + Returns the ordinal value of its argument. For example, the + ordinal value of a character is its ASCII value (on machines + supporting the ASCII character set). X must be of an ordered type, + which include integral, character and enumerated types. + +'SIZE(X)' + Returns the size of its argument. X can be a variable or a type. + +'TRUNC(R)' + Returns the integral part of R. + +'TSIZE(X)' + Returns the size of its argument. X can be a variable or a type. + +'VAL(T,I)' + Returns the member of the type T whose ordinal value is I. + + _Warning:_ Sets and their operations are not yet supported, so GDB + treats the use of procedures 'INCL' and 'EXCL' as an error. + + +File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2 + +15.4.8.3 Constants +.................. + +GDB allows you to express the constants of Modula-2 in the following +ways: + + * Integer constants are simply a sequence of digits. When used in an + expression, a constant is interpreted to be type-compatible with + the rest of the expression. Hexadecimal integers are specified by + a trailing 'H', and octal integers by a trailing 'B'. + + * Floating point constants appear as a sequence of digits, followed + by a decimal point and another sequence of digits. An optional + exponent can then be specified, in the form 'E[+|-]NNN', where + '[+|-]NNN' is the desired exponent. All of the digits of the + floating point constant must be valid decimal (base 10) digits. + + * Character constants consist of a single character enclosed by a + pair of like quotes, either single (''') or double ('"'). They may + also be expressed by their ordinal value (their ASCII value, + usually) followed by a 'C'. + + * String constants consist of a sequence of characters enclosed by a + pair of like quotes, either single (''') or double ('"'). Escape + sequences in the style of C are also allowed. *Note C and C++ + Constants: C Constants, for a brief explanation of escape + sequences. + + * Enumerated constants consist of an enumerated identifier. + + * Boolean constants consist of the identifiers 'TRUE' and 'FALSE'. + + * Pointer constants consist of integral values only. + + * Set constants are not yet supported. + + +File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2 + +15.4.8.4 Modula-2 Types +....................... + +Currently GDB can print the following data types in Modula-2 syntax: +array types, record types, set types, pointer types, procedure types, +enumerated types, subrange types and base types. You can also print the +contents of variables declared using these type. This section gives a +number of simple source code examples together with sample GDB sessions. + + The first example contains the following section of code: + + VAR + s: SET OF CHAR ; + r: [20..40] ; + +and you can request GDB to interrogate the type and value of 'r' and +'s'. + + (gdb) print s + {'A'..'C', 'Z'} + (gdb) ptype s + SET OF CHAR + (gdb) print r + 21 + (gdb) ptype r + [20..40] + +Likewise if your source code declares 's' as: + + VAR + s: SET ['A'..'Z'] ; + +then you may query the type of 's' by: + + (gdb) ptype s + type = SET ['A'..'Z'] + +Note that at present you cannot interactively manipulate set expressions +using the debugger. + + The following example shows how you might declare an array in +Modula-2 and how you can interact with GDB to print its type and +contents: + + VAR + s: ARRAY [-10..10] OF CHAR ; + + (gdb) ptype s + ARRAY [-10..10] OF CHAR + + Note that the array handling is not yet complete and although the +type is printed correctly, expression handling still assumes that all +arrays have a lower bound of zero and not '-10' as in the example above. + + Here are some more type related Modula-2 examples: + + TYPE + colour = (blue, red, yellow, green) ; + t = [blue..yellow] ; + VAR + s: t ; + BEGIN + s := blue ; + +The GDB interaction shows how you can query the data type and value of a +variable. + + (gdb) print s + $1 = blue + (gdb) ptype t + type = [blue..yellow] + +In this example a Modula-2 array is declared and its contents displayed. +Observe that the contents are written in the same way as their 'C' +counterparts. + + VAR + s: ARRAY [1..5] OF CARDINAL ; + BEGIN + s[1] := 1 ; + + (gdb) print s + $1 = {1, 0, 0, 0, 0} + (gdb) ptype s + type = ARRAY [1..5] OF CARDINAL + + The Modula-2 language interface to GDB also understands pointer types +as shown in this example: + + VAR + s: POINTER TO ARRAY [1..5] OF CARDINAL ; + BEGIN + NEW(s) ; + s^[1] := 1 ; + +and you can request that GDB describes the type of 's'. + + (gdb) ptype s + type = POINTER TO ARRAY [1..5] OF CARDINAL + + GDB handles compound types as we can see in this example. Here we +combine array types, record types, pointer types and subrange types: + + TYPE + foo = RECORD + f1: CARDINAL ; + f2: CHAR ; + f3: myarray ; + END ; + + myarray = ARRAY myrange OF CARDINAL ; + myrange = [-2..2] ; + VAR + s: POINTER TO ARRAY myrange OF foo ; + +and you can ask GDB to describe the type of 's' as shown below. + + (gdb) ptype s + type = POINTER TO ARRAY [-2..2] OF foo = RECORD + f1 : CARDINAL; + f2 : CHAR; + f3 : ARRAY [-2..2] OF CARDINAL; + END + + +File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2 + +15.4.8.5 Modula-2 Defaults +.......................... + +If type and range checking are set automatically by GDB, they both +default to 'on' whenever the working language changes to Modula-2. This +happens regardless of whether you or GDB selected the working language. + + If you allow GDB to set the language automatically, then entering +code compiled from a file whose name ends with '.mod' sets the working +language to Modula-2. *Note Having GDB Infer the Source Language: +Automatically, for further details. + + +File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 + +15.4.8.6 Deviations from Standard Modula-2 +.......................................... + +A few changes have been made to make Modula-2 programs easier to debug. +This is done primarily via loosening its type strictness: + + * Unlike in standard Modula-2, pointer constants can be formed by + integers. This allows you to modify pointer variables during + debugging. (In standard Modula-2, the actual address contained in + a pointer variable is hidden from you; it can only be modified + through direct assignment to another pointer variable or expression + that returned a pointer.) + + * C escape sequences can be used in strings and characters to + represent non-printable characters. GDB prints out strings with + these escape sequences embedded. Single non-printable characters + are printed using the 'CHR(NNN)' format. + + * The assignment operator (':=') returns the value of its right-hand + argument. + + * All built-in procedures both modify _and_ return their argument. + + +File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 + +15.4.8.7 Modula-2 Type and Range Checks +....................................... + + _Warning:_ in this release, GDB does not yet perform type or range + checking. + + GDB considers two Modula-2 variables type equivalent if: + + * They are of types that have been declared equivalent via a 'TYPE T1 + = T2' statement + + * They have been declared on the same line. (Note: This is true of + the GNU Modula-2 compiler, but it may not be true of other + compilers.) + + As long as type checking is enabled, any attempt to combine variables +whose types are not equivalent is an error. + + Range checking is done on all mathematical operations, assignment, +array index bounds, and all built-in functions and procedures. + + +File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 + +15.4.8.8 The Scope Operators '::' and '.' +......................................... + +There are a few subtle differences between the Modula-2 scope operator +('.') and the GDB scope operator ('::'). The two have similar syntax: + + + MODULE . ID + SCOPE :: ID + +where SCOPE is the name of a module or a procedure, MODULE the name of a +module, and ID is any declared identifier within your program, except +another module. + + Using the '::' operator makes GDB search the scope specified by SCOPE +for the identifier ID. If it is not found in the specified scope, then +GDB searches all scopes enclosing the one specified by SCOPE. + + Using the '.' operator makes GDB search the current scope for the +identifier specified by ID that was imported from the definition module +specified by MODULE. With this operator, it is an error if the +identifier ID was not imported from definition module MODULE, or if ID +is not an identifier in MODULE. + + +File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 + +15.4.8.9 GDB and Modula-2 +......................... + +Some GDB commands have little use when debugging Modula-2 programs. +Five subcommands of 'set print' and 'show print' apply specifically to C +and C++: 'vtbl', 'demangle', 'asm-demangle', 'object', and 'union'. The +first four apply to C++, and the last to the C 'union' type, which has +no direct analogue in Modula-2. + + The '@' operator (*note Expressions: Expressions.), while available +with any language, is not useful with Modula-2. Its intent is to aid +the debugging of "dynamic arrays", which cannot be created in Modula-2 +as they can in C or C++. However, because an address can be specified +by an integral constant, the construct '{TYPE}ADREXP' is still useful. + + In GDB scripts, the Modula-2 inequality operator '#' is interpreted +as the beginning of a comment. Use '<>' instead. + + +File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages + +15.4.9 Ada +---------- + +The extensions made to GDB for Ada only support output from the GNU Ada +(GNAT) compiler. Other Ada compilers are not currently supported, and +attempting to debug executables produced by them is most likely to be +difficult. + +* Menu: + +* Ada Mode Intro:: General remarks on the Ada syntax + and semantics supported by Ada mode + in GDB. +* Omissions from Ada:: Restrictions on the Ada expression syntax. +* Additions to Ada:: Extensions of the Ada expression syntax. +* Stopping Before Main Program:: Debugging the program during elaboration. +* Ada Exceptions:: Ada Exceptions +* Ada Tasks:: Listing and setting breakpoints in tasks. +* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files +* Ravenscar Profile:: Tasking Support when using the Ravenscar + Profile +* Ada Glitches:: Known peculiarities of Ada mode. + + +File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada + +15.4.9.1 Introduction +..................... + +The Ada mode of GDB supports a fairly large subset of Ada expression +syntax, with some extensions. The philosophy behind the design of this +subset is + + * That GDB should provide basic literals and access to operations for + arithmetic, dereferencing, field selection, indexing, and + subprogram calls, leaving more sophisticated computations to + subprograms written into the program (which therefore may be called + from GDB). + + * That type safety and strict adherence to Ada language restrictions + are not particularly important to the GDB user. + + * That brevity is important to the GDB user. + + Thus, for brevity, the debugger acts as if all names declared in +user-written packages are directly visible, even if they are not visible +according to Ada rules, thus making it unnecessary to fully qualify most +names with their packages, regardless of context. Where this causes +ambiguity, GDB asks the user's intent. + + The debugger will start in Ada mode if it detects an Ada main +program. As for other languages, it will enter Ada mode when stopped in +a program that was translated from an Ada source file. + + While in Ada mode, you may use '--' for comments. This is useful +mostly for documenting command files. The standard GDB comment ('#') +still works at the beginning of a line in Ada mode, but not in the +middle (to allow based literals). + + The debugger supports limited overloading. Given a subprogram call +in which the function symbol has multiple definitions, it will use the +number of actual parameters and some information about their types to +attempt to narrow the set of definitions. It also makes very limited +use of context, preferring procedures to functions in the context of the +'call' command, and functions to procedures elsewhere. + + +File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada + +15.4.9.2 Omissions from Ada +........................... + +Here are the notable omissions from the subset: + + * Only a subset of the attributes are supported: + + - 'First, 'Last, and 'Length on array objects (not on types and + subtypes). + + - 'Min and 'Max. + + - 'Pos and 'Val. + + - 'Tag. + + - 'Range on array objects (not subtypes), but only as the right + operand of the membership ('in') operator. + + - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT + extension). + + - 'Address. + + * The names in 'Characters.Latin_1' are not available and + concatenation is not implemented. Thus, escape characters in + strings are not currently available. + + * Equality tests ('=' and '/=') on arrays test for bitwise equality + of representations. They will generally work correctly for strings + and arrays whose elements have integer or enumeration types. They + may not work correctly for arrays whose element types have + user-defined equality, for arrays of real values (in particular, + IEEE-conformant floating point, because of negative zeroes and + NaNs), and for arrays whose elements contain unused bits with + indeterminate values. + + * The other component-by-component array operations ('and', 'or', + 'xor', 'not', and relational tests other than equality) are not + implemented. + + * There is limited support for array and record aggregates. They are + permitted only on the right sides of assignments, as in these + examples: + + (gdb) set An_Array := (1, 2, 3, 4, 5, 6) + (gdb) set An_Array := (1, others => 0) + (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) + (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) + (gdb) set A_Record := (1, "Peter", True); + (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True) + + Changing a discriminant's value by assigning an aggregate has an + undefined effect if that discriminant is used within the record. + However, you can first modify discriminants by directly assigning + to them (which normally would not be allowed in Ada), and then + performing an aggregate assignment. For example, given a variable + 'A_Rec' declared to have a type such as: + + type Rec (Len : Small_Integer := 0) is record + Id : Integer; + Vals : IntArray (1 .. Len); + end record; + + you can assign a value with a different size of 'Vals' with two + assignments: + + (gdb) set A_Rec.Len := 4 + (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) + + As this example also illustrates, GDB is very loose about the usual + rules concerning aggregates. You may leave out some of the + components of an array or record aggregate (such as the 'Len' + component in the assignment to 'A_Rec' above); they will retain + their original values upon assignment. You may freely use dynamic + values as indices in component associations. You may even use + overlapping or redundant component associations, although which + component values are assigned in such cases is not defined. + + * Calls to dispatching subprograms are not implemented. + + * The overloading algorithm is much more limited (i.e., less + selective) than that of real Ada. It makes only limited use of the + context in which a subexpression appears to resolve its meaning, + and it is much looser in its rules for allowing type matches. As a + result, some function calls will be ambiguous, and the user will be + asked to choose the proper resolution. + + * The 'new' operator is not implemented. + + * Entry calls are not implemented. + + * Aside from printing, arithmetic operations on the native VAX + floating-point formats are not supported. + + * It is not possible to slice a packed array. + + * The names 'True' and 'False', when not part of a qualified name, + are interpreted as if implicitly prefixed by 'Standard', regardless + of context. Should your program redefine these names in a package + or procedure (at best a dubious practice), you will have to use + fully qualified names to access their new definitions. + + +File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada + +15.4.9.3 Additions to Ada +......................... + +As it does for other languages, GDB makes certain generic extensions to +Ada (*note Expressions::): + + * If the expression E is a variable residing in memory (typically a + local variable or array element) and N is a positive integer, then + 'E@N' displays the values of E and the N-1 adjacent variables + following it in memory as an array. In Ada, this operator is + generally not necessary, since its prime use is in displaying parts + of an array, and slicing will usually do this in Ada. However, + there are occasional uses when debugging programs in which certain + debugging information has been optimized away. + + * 'B::VAR' means "the variable named VAR that appears in function or + file B." When B is a file name, you must typically surround it in + single quotes. + + * The expression '{TYPE} ADDR' means "the variable of type TYPE that + appears at address ADDR." + + * A name starting with '$' is a convenience variable (*note + Convenience Vars::) or a machine register (*note Registers::). + + In addition, GDB provides a few other shortcuts and outright +additions specific to Ada: + + * The assignment statement is allowed as an expression, returning its + right-hand operand as its value. Thus, you may enter + + (gdb) set x := y + 3 + (gdb) print A(tmp := y + 1) + + * The semicolon is allowed as an "operator," returning as its value + the value of its right-hand operand. This allows, for example, + complex conditional breaks: + + (gdb) break f + (gdb) condition 1 (report(i); k += 1; A(k) > 100) + + * Rather than use catenation and symbolic character names to + introduce special characters into strings, one may instead use a + special bracket notation, which is also used to print strings. A + sequence of characters of the form '["XX"]' within a string or + character literal denotes the (single) character whose numeric + encoding is XX in hexadecimal. The sequence of characters '["""]' + also denotes a single quotation mark in strings. For example, + "One line.["0a"]Next line.["0a"]" + contains an ASCII newline character ('Ada.Characters.Latin_1.LF') + after each period. + + * The subtype used as a prefix for the attributes 'Pos, 'Min, and + 'Max is optional (and is ignored in any case). For example, it is + valid to write + + (gdb) print 'max(x, y) + + * When printing arrays, GDB uses positional notation when the array + has a lower bound of 1, and uses a modified named notation + otherwise. For example, a one-dimensional array of three integers + with a lower bound of 3 might print as + + (3 => 10, 17, 1) + + That is, in contrast to valid Ada, only the first component has a + '=>' clause. + + * You may abbreviate attributes in expressions with any unique, + multi-character subsequence of their names (an exact match gets + preference). For example, you may use a'len, a'gth, or a'lh in + place of a'length. + + * Since Ada is case-insensitive, the debugger normally maps + identifiers you type to lower case. The GNAT compiler uses + upper-case characters for some of its internal identifiers, which + are normally of no interest to users. For the rare occasions when + you actually have to look at them, enclose them in angle brackets + to avoid the lower-case mapping. For example, + (gdb) print [0] + + * Printing an object of class-wide type or dereferencing an + access-to-class-wide value will display all the components of the + object's specific type (as indicated by its run-time tag). + Likewise, component selection on such a value will operate on the + specific type of the object. + + +File: gdb.info, Node: Stopping Before Main Program, Next: Ada Exceptions, Prev: Additions to Ada, Up: Ada + +15.4.9.4 Stopping at the Very Beginning +....................................... + +It is sometimes necessary to debug the program during elaboration, and +before reaching the main procedure. As defined in the Ada Reference +Manual, the elaboration code is invoked from a procedure called +'adainit'. To run your program up to the beginning of elaboration, +simply use the following two commands: 'tbreak adainit' and 'run'. + + +File: gdb.info, Node: Ada Exceptions, Next: Ada Tasks, Prev: Stopping Before Main Program, Up: Ada + +15.4.9.5 Ada Exceptions +....................... + +A command is provided to list all Ada exceptions: + +'info exceptions' +'info exceptions REGEXP' + The 'info exceptions' command allows you to list all Ada exceptions + defined within the program being debugged, as well as their + addresses. With a regular expression, REGEXP, as argument, only + those exceptions whose names match REGEXP are listed. + + Below is a small example, showing how the command can be used, first +without argument, and next with a regular expression passed as an +argument. + + (gdb) info exceptions + All defined Ada exceptions: + constraint_error: 0x613da0 + program_error: 0x613d20 + storage_error: 0x613ce0 + tasking_error: 0x613ca0 + const.aint_global_e: 0x613b00 + (gdb) info exceptions const.aint + All Ada exceptions matching regular expression "const.aint": + constraint_error: 0x613da0 + const.aint_global_e: 0x613b00 + + It is also possible to ask GDB to stop your program's execution when +an exception is raised. For more details, see *note Set Catchpoints::. + + +File: gdb.info, Node: Ada Tasks, Next: Ada Tasks and Core Files, Prev: Ada Exceptions, Up: Ada + +15.4.9.6 Extensions for Ada Tasks +................................. + +Support for Ada tasks is analogous to that for threads (*note +Threads::). GDB provides the following task-related commands: + +'info tasks' + This command shows a list of current Ada tasks, as in the following + example: + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8088000 0 15 Child Activation Wait main_task + 2 80a4000 1 15 Accept Statement b + 3 809a800 1 15 Child Activation Wait a + * 4 80ae800 3 15 Runnable c + + In this listing, the asterisk before the last task indicates it to + be the task currently being inspected. + + ID + Represents GDB's internal task number. + + TID + The Ada task ID. + + P-ID + The parent's task ID (GDB's internal task number). + + Pri + The base priority of the task. + + State + Current state of the task. + + 'Unactivated' + The task has been created but has not been activated. It + cannot be executing. + + 'Runnable' + The task is not blocked for any reason known to Ada. (It + may be waiting for a mutex, though.) It is conceptually + "executing" in normal mode. + + 'Terminated' + The task is terminated, in the sense of ARM 9.3 (5). Any + dependents that were waiting on terminate alternatives + have been awakened and have terminated themselves. + + 'Child Activation Wait' + The task is waiting for created tasks to complete + activation. + + 'Accept Statement' + The task is waiting on an accept or selective wait + statement. + + 'Waiting on entry call' + The task is waiting on an entry call. + + 'Async Select Wait' + The task is waiting to start the abortable part of an + asynchronous select statement. + + 'Delay Sleep' + The task is waiting on a select statement with only a + delay alternative open. + + 'Child Termination Wait' + The task is sleeping having completed a master within + itself, and is waiting for the tasks dependent on that + master to become terminated or waiting on a terminate + Phase. + + 'Wait Child in Term Alt' + The task is sleeping waiting for tasks on terminate + alternatives to finish terminating. + + 'Accepting RV with TASKNO' + The task is accepting a rendez-vous with the task TASKNO. + + Name + Name of the task in the program. + +'info task TASKNO' + This command shows detailled informations on the specified task, as + in the following example: + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8077880 0 15 Child Activation Wait main_task + * 2 807c468 1 15 Runnable task_1 + (gdb) info task 2 + Ada Task: 0x807c468 + Name: task_1 + Thread: 0x807f378 + Parent: 1 (main_task) + Base Priority: 15 + State: Runnable + +'task' + This command prints the ID of the current task. + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8077870 0 15 Child Activation Wait main_task + * 2 807c458 1 15 Runnable t + (gdb) task + [Current task is 2] + +'task TASKNO' + This command is like the 'thread THREADNO' command (*note + Threads::). It switches the context of debugging from the current + task to the given task. + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8077870 0 15 Child Activation Wait main_task + * 2 807c458 1 15 Runnable t + (gdb) task 1 + [Switching to task 1] + #0 0x8067726 in pthread_cond_wait () + (gdb) bt + #0 0x8067726 in pthread_cond_wait () + #1 0x8056714 in system.os_interface.pthread_cond_wait () + #2 0x805cb63 in system.task_primitives.operations.sleep () + #3 0x806153e in system.tasking.stages.activate_tasks () + #4 0x804aacc in un () at un.adb:5 + +'break LINESPEC task TASKNO' +'break LINESPEC task TASKNO if ...' + These commands are like the 'break ... thread ...' command (*note + Thread Stops::). LINESPEC specifies source lines, as described in + *note Specify Location::. + + Use the qualifier 'task TASKNO' with a breakpoint command to + specify that you only want GDB to stop the program when a + particular Ada task reaches this breakpoint. TASKNO is one of the + numeric task identifiers assigned by GDB, shown in the first column + of the 'info tasks' display. + + If you do not specify 'task TASKNO' when you set a breakpoint, the + breakpoint applies to _all_ tasks of your program. + + You can use the 'task' qualifier on conditional breakpoints as + well; in this case, place 'task TASKNO' before the breakpoint + condition (before the 'if'). + + For example, + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 140022020 0 15 Child Activation Wait main_task + 2 140045060 1 15 Accept/Select Wait t2 + 3 140044840 1 15 Runnable t1 + * 4 140056040 1 15 Runnable t3 + (gdb) b 15 task 2 + Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. + (gdb) cont + Continuing. + task # 1 running + task # 2 running + + Breakpoint 5, test_task_debug () at test_task_debug.adb:15 + 15 flush; + (gdb) info tasks + ID TID P-ID Pri State Name + 1 140022020 0 15 Child Activation Wait main_task + * 2 140045060 1 15 Runnable t2 + 3 140044840 1 15 Runnable t1 + 4 140056040 1 15 Delay Sleep t3 + + +File: gdb.info, Node: Ada Tasks and Core Files, Next: Ravenscar Profile, Prev: Ada Tasks, Up: Ada + +15.4.9.7 Tasking Support when Debugging Core Files +.................................................. + +When inspecting a core file, as opposed to debugging a live program, +tasking support may be limited or even unavailable, depending on the +platform being used. For instance, on x86-linux, the list of tasks is +available, but task switching is not supported. On Tru64, however, task +switching will work as usual. + + On certain platforms, including Tru64, the debugger needs to perform +some memory writes in order to provide Ada tasking support. When +inspecting a core file, this means that the core file must be opened +with read-write privileges, using the command '"set write on"' (*note +Patching::). Under these circumstances, you should make a backup copy +of the core file before inspecting it with GDB. + + +File: gdb.info, Node: Ravenscar Profile, Next: Ada Glitches, Prev: Ada Tasks and Core Files, Up: Ada + +15.4.9.8 Tasking Support when using the Ravenscar Profile +......................................................... + +The "Ravenscar Profile" is a subset of the Ada tasking features, +specifically designed for systems with safety-critical real-time +requirements. + +'set ravenscar task-switching on' + Allows task switching when debugging a program that uses the + Ravenscar Profile. This is the default. + +'set ravenscar task-switching off' + Turn off task switching when debugging a program that uses the + Ravenscar Profile. This is mostly intended to disable the code + that adds support for the Ravenscar Profile, in case a bug in + either GDB or in the Ravenscar runtime is preventing GDB from + working properly. To be effective, this command should be run + before the program is started. + +'show ravenscar task-switching' + Show whether it is possible to switch from task to task in a + program using the Ravenscar Profile. + + +File: gdb.info, Node: Ada Glitches, Prev: Ravenscar Profile, Up: Ada + +15.4.9.9 Known Peculiarities of Ada Mode +........................................ + +Besides the omissions listed previously (*note Omissions from Ada::), we +know of several problems with and limitations of Ada mode in GDB, some +of which will be fixed with planned future releases of the debugger and +the GNU Ada compiler. + + * Static constants that the compiler chooses not to materialize as + objects in storage are invisible to the debugger. + + * Named parameter associations in function argument lists are ignored + (the argument lists are treated as positional). + + * Many useful library packages are currently invisible to the + debugger. + + * Fixed-point arithmetic, conversions, input, and output is carried + out using floating-point arithmetic, and may give results that only + approximate those on the host machine. + + * The GNAT compiler never generates the prefix 'Standard' for any of + the standard symbols defined by the Ada language. GDB knows about + this: it will strip the prefix from names when you use it, and will + never look for a name you have so qualified among local symbols, + nor match against symbols in other packages or subprograms. If you + have defined entities anywhere in your program other than + parameters and local variables whose simple names match names in + 'Standard', GNAT's lack of qualification here can cause confusion. + When this happens, you can usually resolve the confusion by + qualifying the problematic names with package 'Standard' + explicitly. + + Older versions of the compiler sometimes generate erroneous debugging +information, resulting in the debugger incorrectly printing the value of +affected entities. In some cases, the debugger is able to work around +an issue automatically. In other cases, the debugger is able to work +around the issue, but the work-around has to be specifically enabled. + +'set ada trust-PAD-over-XVS on' + Configure GDB to strictly follow the GNAT encoding when computing + the value of Ada entities, particularly when 'PAD' and 'PAD___XVS' + types are involved (see 'ada/exp_dbug.ads' in the GCC sources for a + complete description of the encoding used by the GNAT compiler). + This is the default. + +'set ada trust-PAD-over-XVS off' + This is related to the encoding using by the GNAT compiler. If GDB + sometimes prints the wrong value for certain entities, changing + 'ada trust-PAD-over-XVS' to 'off' activates a work-around which may + fix the issue. It is always safe to set 'ada trust-PAD-over-XVS' + to 'off', but this incurs a slight performance penalty, so it is + recommended to leave this setting to 'on' unless necessary. + + +File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages + +15.5 Unsupported Languages +========================== + +In addition to the other fully-supported programming languages, GDB also +provides a pseudo-language, called 'minimal'. It does not represent a +real programming language, but provides a set of capabilities close to +what the C or assembly languages provide. This should allow most simple +operations to be performed while debugging an application that uses a +language currently not supported by GDB. + + If the language is set to 'auto', GDB will automatically select this +language if the current frame corresponds to an unsupported language. + + +File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top + +16 Examining the Symbol Table +***************************** + +The commands described in this chapter allow you to inquire about the +symbols (names of variables, functions and types) defined in your +program. This information is inherent in the text of your program and +does not change as your program executes. GDB finds it in your +program's symbol table, in the file indicated when you started GDB +(*note Choosing Files: File Options.), or by one of the file-management +commands (*note Commands to Specify Files: Files.). + + Occasionally, you may need to refer to symbols that contain unusual +characters, which GDB ordinarily treats as word delimiters. The most +frequent case is in referring to static variables in other source files +(*note Program Variables: Variables.). File names are recorded in +object files as debugging symbols, but GDB would ordinarily parse a +typical file name, like 'foo.c', as the three words 'foo' '.' 'c'. To +allow GDB to recognize 'foo.c' as a single symbol, enclose it in single +quotes; for example, + + p 'foo.c'::x + +looks up the value of 'x' in the scope of the file 'foo.c'. + +'set case-sensitive on' +'set case-sensitive off' +'set case-sensitive auto' + Normally, when GDB looks up symbols, it matches their names with + case sensitivity determined by the current source language. + Occasionally, you may wish to control that. The command 'set + case-sensitive' lets you do that by specifying 'on' for + case-sensitive matches or 'off' for case-insensitive ones. If you + specify 'auto', case sensitivity is reset to the default suitable + for the source language. The default is case-sensitive matches for + all languages except for Fortran, for which the default is + case-insensitive matches. + +'show case-sensitive' + This command shows the current setting of case sensitivity for + symbols lookups. + +'set print type methods' +'set print type methods on' +'set print type methods off' + Normally, when GDB prints a class, it displays any methods declared + in that class. You can control this behavior either by passing the + appropriate flag to 'ptype', or using 'set print type methods'. + Specifying 'on' will cause GDB to display the methods; this is the + default. Specifying 'off' will cause GDB to omit the methods. + +'show print type methods' + This command shows the current setting of method display when + printing classes. + +'set print type typedefs' +'set print type typedefs on' +'set print type typedefs off' + + Normally, when GDB prints a class, it displays any typedefs defined + in that class. You can control this behavior either by passing the + appropriate flag to 'ptype', or using 'set print type typedefs'. + Specifying 'on' will cause GDB to display the typedef definitions; + this is the default. Specifying 'off' will cause GDB to omit the + typedef definitions. Note that this controls whether the typedef + definition itself is printed, not whether typedef names are + substituted when printing other types. + +'show print type typedefs' + This command shows the current setting of typedef display when + printing classes. + +'info address SYMBOL' + Describe where the data for SYMBOL is stored. For a register + variable, this says which register it is kept in. For a + non-register local variable, this prints the stack-frame offset at + which the variable is always stored. + + Note the contrast with 'print &SYMBOL', which does not work at all + for a register variable, and for a stack local variable prints the + exact address of the current instantiation of the variable. + +'info symbol ADDR' + Print the name of a symbol which is stored at the address ADDR. If + no symbol is stored exactly at ADDR, GDB prints the nearest symbol + and an offset from it: + + (gdb) info symbol 0x54320 + _initialize_vx + 396 in section .text + + This is the opposite of the 'info address' command. You can use it + to find out the name of a variable or a function given its address. + + For dynamically linked executables, the name of executable or + shared library containing the symbol is also printed: + + (gdb) info symbol 0x400225 + _start + 5 in section .text of /tmp/a.out + (gdb) info symbol 0x2aaaac2811cf + __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 + +'whatis[/FLAGS] [ARG]' + Print the data type of ARG, which can be either an expression or a + name of a data type. With no argument, print the data type of '$', + the last value in the value history. + + If ARG is an expression (*note Expressions: Expressions.), it is + not actually evaluated, and any side-effecting operations (such as + assignments or function calls) inside it do not take place. + + If ARG is a variable or an expression, 'whatis' prints its literal + type as it is used in the source code. If the type was defined + using a 'typedef', 'whatis' will _not_ print the data type + underlying the 'typedef'. If the type of the variable or the + expression is a compound data type, such as 'struct' or 'class', + 'whatis' never prints their fields or methods. It just prints the + 'struct'/'class' name (a.k.a. its "tag"). If you want to see the + members of such a compound data type, use 'ptype'. + + If ARG is a type name that was defined using 'typedef', 'whatis' + "unrolls" only one level of that 'typedef'. Unrolling means that + 'whatis' will show the underlying type used in the 'typedef' + declaration of ARG. However, if that underlying type is also a + 'typedef', 'whatis' will not unroll it. + + For C code, the type names may also have the form 'class + CLASS-NAME', 'struct STRUCT-TAG', 'union UNION-TAG' or 'enum + ENUM-TAG'. + + FLAGS can be used to modify how the type is displayed. Available + flags are: + + 'r' + Display in "raw" form. Normally, GDB substitutes template + parameters and typedefs defined in a class when printing the + class' members. The '/r' flag disables this. + + 'm' + Do not print methods defined in the class. + + 'M' + Print methods defined in the class. This is the default, but + the flag exists in case you change the default with 'set print + type methods'. + + 't' + Do not print typedefs defined in the class. Note that this + controls whether the typedef definition itself is printed, not + whether typedef names are substituted when printing other + types. + + 'T' + Print typedefs defined in the class. This is the default, but + the flag exists in case you change the default with 'set print + type typedefs'. + +'ptype[/FLAGS] [ARG]' + 'ptype' accepts the same arguments as 'whatis', but prints a + detailed description of the type, instead of just the name of the + type. *Note Expressions: Expressions. + + Contrary to 'whatis', 'ptype' always unrolls any 'typedef's in its + argument declaration, whether the argument is a variable, + expression, or a data type. This means that 'ptype' of a variable + or an expression will not print literally its type as present in + the source code--use 'whatis' for that. 'typedef's at the pointer + or reference targets are also unrolled. Only 'typedef's of fields, + methods and inner 'class typedef's of 'struct's, 'class'es and + 'union's are not unrolled even with 'ptype'. + + For example, for this variable declaration: + + typedef double real_t; + struct complex { real_t real; double imag; }; + typedef struct complex complex_t; + complex_t var; + real_t *real_pointer_var; + + the two commands give this output: + + (gdb) whatis var + type = complex_t + (gdb) ptype var + type = struct complex { + real_t real; + double imag; + } + (gdb) whatis complex_t + type = struct complex + (gdb) whatis struct complex + type = struct complex + (gdb) ptype struct complex + type = struct complex { + real_t real; + double imag; + } + (gdb) whatis real_pointer_var + type = real_t * + (gdb) ptype real_pointer_var + type = double * + + As with 'whatis', using 'ptype' without an argument refers to the + type of '$', the last value in the value history. + + Sometimes, programs use opaque data types or incomplete + specifications of complex data structure. If the debug information + included in the program does not allow GDB to display a full + declaration of the data type, it will say ''. For + example, given these declarations: + + struct foo; + struct foo *fooptr; + + but no definition for 'struct foo' itself, GDB will say: + + (gdb) ptype foo + $1 = + + "Incomplete type" is C terminology for data types that are not + completely specified. + +'info types REGEXP' +'info types' + Print a brief description of all types whose names match the + regular expression REGEXP (or all types in your program, if you + supply no argument). Each complete typename is matched as though + it were a complete line; thus, 'i type value' gives information on + all types in your program whose names include the string 'value', + but 'i type ^value$' gives information only on types whose complete + name is 'value'. + + This command differs from 'ptype' in two ways: first, like + 'whatis', it does not print a detailed description; second, it + lists all source files where a type is defined. + +'info type-printers' + Versions of GDB that ship with Python scripting enabled may have + "type printers" available. When using 'ptype' or 'whatis', these + printers are consulted when the name of a type is needed. *Note + Type Printing API::, for more information on writing type printers. + + 'info type-printers' displays all the available type printers. + +'enable type-printer NAME...' +'disable type-printer NAME...' + These commands can be used to enable or disable type printers. + +'info scope LOCATION' + List all the variables local to a particular scope. This command + accepts a LOCATION argument--a function name, a source line, or an + address preceded by a '*', and prints all the variables local to + the scope defined by that location. (*Note Specify Location::, for + details about supported forms of LOCATION.) For example: + + (gdb) info scope command_line_handler + Scope for command_line_handler: + Symbol rl is an argument at stack/frame offset 8, length 4. + Symbol linebuffer is in static storage at address 0x150a18, length 4. + Symbol linelength is in static storage at address 0x150a1c, length 4. + Symbol p is a local variable in register $esi, length 4. + Symbol p1 is a local variable in register $ebx, length 4. + Symbol nline is a local variable in register $edx, length 4. + Symbol repeat is a local variable at frame offset -8, length 4. + + This command is especially useful for determining what data to + collect during a "trace experiment", see *note collect: Tracepoint + Actions. + +'info source' + Show information about the current source file--that is, the source + file for the function containing the current point of execution: + * the name of the source file, and the directory containing it, + * the directory it was compiled in, + * its length, in lines, + * which programming language it is written in, + * whether the executable includes debugging information for that + file, and if so, what format the information is in (e.g., + STABS, Dwarf 2, etc.), and + * whether the debugging information includes information about + preprocessor macros. + +'info sources' + Print the names of all source files in your program for which there + is debugging information, organized into two lists: files whose + symbols have already been read, and files whose symbols will be + read when needed. + +'info functions' + Print the names and data types of all defined functions. + +'info functions REGEXP' + Print the names and data types of all defined functions whose names + contain a match for regular expression REGEXP. Thus, 'info fun + step' finds all functions whose names include 'step'; 'info fun + ^step' finds those whose names start with 'step'. If a function + name contains characters that conflict with the regular expression + language (e.g. 'operator*()'), they may be quoted with a backslash. + +'info variables' + Print the names and data types of all variables that are defined + outside of functions (i.e. excluding local variables). + +'info variables REGEXP' + Print the names and data types of all variables (except for local + variables) whose names contain a match for regular expression + REGEXP. + +'info classes' +'info classes REGEXP' + Display all Objective-C classes in your program, or (with the + REGEXP argument) all those matching a particular regular + expression. + +'info selectors' +'info selectors REGEXP' + Display all Objective-C selectors in your program, or (with the + REGEXP argument) all those matching a particular regular + expression. + +'set opaque-type-resolution on' + Tell GDB to resolve opaque types. An opaque type is a type + declared as a pointer to a 'struct', 'class', or 'union'--for + example, 'struct MyType *'--that is used in one source file + although the full declaration of 'struct MyType' is in another + source file. The default is on. + + A change in the setting of this subcommand will not take effect + until the next time symbols for a file are loaded. + +'set opaque-type-resolution off' + Tell GDB not to resolve opaque types. In this case, the type is + printed as follows: + {} + +'show opaque-type-resolution' + Show whether opaque types are resolved or not. + +'maint print symbols FILENAME' +'maint print psymbols FILENAME' +'maint print msymbols FILENAME' + Write a dump of debugging symbol data into the file FILENAME. + These commands are used to debug the GDB symbol-reading code. Only + symbols with debugging data are included. If you use 'maint print + symbols', GDB includes all the symbols for which it has already + collected full details: that is, FILENAME reflects symbols for only + those files whose symbols GDB has read. You can use the command + 'info sources' to find out which files these are. If you use + 'maint print psymbols' instead, the dump shows information about + symbols that GDB only knows partially--that is, symbols defined in + files that GDB has skimmed, but not yet read completely. Finally, + 'maint print msymbols' dumps just the minimal symbol information + required for each object file from which GDB has read some symbols. + *Note Commands to Specify Files: Files, for a discussion of how GDB + reads symbols (in the description of 'symbol-file'). + +'maint info symtabs [ REGEXP ]' +'maint info psymtabs [ REGEXP ]' + + List the 'struct symtab' or 'struct partial_symtab' structures + whose names match REGEXP. If REGEXP is not given, list them all. + The output includes expressions which you can copy into a GDB + debugging this one to examine a particular structure in more + detail. For example: + + (gdb) maint info psymtabs dwarf2read + { objfile /home/gnu/build/gdb/gdb + ((struct objfile *) 0x82e69d0) + { psymtab /home/gnu/src/gdb/dwarf2read.c + ((struct partial_symtab *) 0x8474b10) + readin no + fullname (null) + text addresses 0x814d3c8 -- 0x8158074 + globals (* (struct partial_symbol **) 0x8507a08 @ 9) + statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) + dependencies (none) + } + } + (gdb) maint info symtabs + (gdb) + We see that there is one partial symbol table whose filename + contains the string 'dwarf2read', belonging to the 'gdb' + executable; and we see that GDB has not read in any symtabs yet at + all. If we set a breakpoint on a function, that will cause GDB to + read the symtab for the compilation unit containing that function: + + (gdb) break dwarf2_psymtab_to_symtab + Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, + line 1574. + (gdb) maint info symtabs + { objfile /home/gnu/build/gdb/gdb + ((struct objfile *) 0x82e69d0) + { symtab /home/gnu/src/gdb/dwarf2read.c + ((struct symtab *) 0x86c1f38) + dirname (null) + fullname (null) + blockvector ((struct blockvector *) 0x86c1bd0) (primary) + linetable ((struct linetable *) 0x8370fa0) + debugformat DWARF 2 + } + } + (gdb) + + +File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top + +17 Altering Execution +********************* + +Once you think you have found an error in your program, you might want +to find out for certain whether correcting the apparent error would lead +to correct results in the rest of the run. You can find the answer by +experiment, using the GDB features for altering execution of the +program. + + For example, you can store new values into variables or memory +locations, give your program a signal, restart it at a different +address, or even return prematurely from a function. + +* Menu: + +* Assignment:: Assignment to variables +* Jumping:: Continuing at a different address +* Signaling:: Giving your program a signal +* Returning:: Returning from a function +* Calling:: Calling your program's functions +* Patching:: Patching your program + + +File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering + +17.1 Assignment to Variables +============================ + +To alter the value of a variable, evaluate an assignment expression. +*Note Expressions: Expressions. For example, + + print x=4 + +stores the value 4 into the variable 'x', and then prints the value of +the assignment expression (which is 4). *Note Using GDB with Different +Languages: Languages, for more information on operators in supported +languages. + + If you are not interested in seeing the value of the assignment, use +the 'set' command instead of the 'print' command. 'set' is really the +same as 'print' except that the expression's value is not printed and is +not put in the value history (*note Value History: Value History.). The +expression is evaluated only for its effects. + + If the beginning of the argument string of the 'set' command appears +identical to a 'set' subcommand, use the 'set variable' command instead +of just 'set'. This command is identical to 'set' except for its lack +of subcommands. For example, if your program has a variable 'width', +you get an error if you try to set a new value with just 'set width=13', +because GDB has the command 'set width': + + (gdb) whatis width + type = double + (gdb) p width + $4 = 13 + (gdb) set width=47 + Invalid syntax in expression. + +The invalid expression, of course, is '=47'. In order to actually set +the program's variable 'width', use + + (gdb) set var width=47 + + Because the 'set' command has many subcommands that can conflict with +the names of program variables, it is a good idea to use the 'set +variable' command instead of just 'set'. For example, if your program +has a variable 'g', you run into problems if you try to set a new value +with just 'set g=4', because GDB has the command 'set gnutarget', +abbreviated 'set g': + + (gdb) whatis g + type = double + (gdb) p g + $1 = 1 + (gdb) set g=4 + (gdb) p g + $2 = 1 + (gdb) r + The program being debugged has been started already. + Start it from the beginning? (y or n) y + Starting program: /home/smith/cc_progs/a.out + "/home/smith/cc_progs/a.out": can't open to read symbols: + Invalid bfd target. + (gdb) show g + The current BFD target is "=4". + +The program variable 'g' did not change, and you silently set the +'gnutarget' to an invalid value. In order to set the variable 'g', use + + (gdb) set var g=4 + + GDB allows more implicit conversions in assignments than C; you can +freely store an integer value into a pointer variable or vice versa, and +you can convert any structure to any other structure that is the same +length or shorter. + + To store values into arbitrary places in memory, use the '{...}' +construct to generate a value of specified type at a specified address +(*note Expressions: Expressions.). For example, '{int}0x83040' refers +to memory location '0x83040' as an integer (which implies a certain size +and representation in memory), and + + set {int}0x83040 = 4 + +stores the value 4 into that memory location. + + +File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering + +17.2 Continuing at a Different Address +====================================== + +Ordinarily, when you continue your program, you do so at the place where +it stopped, with the 'continue' command. You can instead continue at an +address of your own choosing, with the following commands: + +'jump LINESPEC' +'j LINESPEC' +'jump LOCATION' +'j LOCATION' + Resume execution at line LINESPEC or at address given by LOCATION. + Execution stops again immediately if there is a breakpoint there. + *Note Specify Location::, for a description of the different forms + of LINESPEC and LOCATION. It is common practice to use the + 'tbreak' command in conjunction with 'jump'. *Note Setting + Breakpoints: Set Breaks. + + The 'jump' command does not change the current stack frame, or the + stack pointer, or the contents of any memory location or any + register other than the program counter. If line LINESPEC is in a + different function from the one currently executing, the results + may be bizarre if the two functions expect different patterns of + arguments or of local variables. For this reason, the 'jump' + command requests confirmation if the specified line is not in the + function currently executing. However, even bizarre results are + predictable if you are well acquainted with the machine-language + code of your program. + + On many systems, you can get much the same effect as the 'jump' +command by storing a new value into the register '$pc'. The difference +is that this does not start your program running; it only changes the +address of where it _will_ run when you continue. For example, + + set $pc = 0x485 + +makes the next 'continue' command or stepping command execute at address +'0x485', rather than at the address where your program stopped. *Note +Continuing and Stepping: Continuing and Stepping. + + The most common occasion to use the 'jump' command is to back +up--perhaps with more breakpoints set--over a portion of a program that +has already executed, in order to examine its execution in more detail. + + +File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering + +17.3 Giving your Program a Signal +================================= + +'signal SIGNAL' + Resume execution where your program stopped, but immediately give + it the signal SIGNAL. SIGNAL can be the name or the number of a + signal. For example, on many systems 'signal 2' and 'signal + SIGINT' are both ways of sending an interrupt signal. + + Alternatively, if SIGNAL is zero, continue execution without giving + a signal. This is useful when your program stopped on account of a + signal and would ordinarily see the signal when resumed with the + 'continue' command; 'signal 0' causes it to resume without a + signal. + + 'signal' does not repeat when you press a second time after + executing the command. + + Invoking the 'signal' command is not the same as invoking the 'kill' +utility from the shell. Sending a signal with 'kill' causes GDB to +decide what to do with the signal depending on the signal handling +tables (*note Signals::). The 'signal' command passes the signal +directly to your program. + + +File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering + +17.4 Returning from a Function +============================== + +'return' +'return EXPRESSION' + You can cancel execution of a function call with the 'return' + command. If you give an EXPRESSION argument, its value is used as + the function's return value. + + When you use 'return', GDB discards the selected stack frame (and all +frames within it). You can think of this as making the discarded frame +return prematurely. If you wish to specify a value to be returned, give +that value as the argument to 'return'. + + This pops the selected stack frame (*note Selecting a Frame: +Selection.), and any other frames inside of it, leaving its caller as +the innermost remaining frame. That frame becomes selected. The +specified value is stored in the registers used for returning values of +functions. + + The 'return' command does not resume execution; it leaves the program +stopped in the state that would exist if the function had just returned. +In contrast, the 'finish' command (*note Continuing and Stepping: +Continuing and Stepping.) resumes execution until the selected stack +frame returns naturally. + + GDB needs to know how the EXPRESSION argument should be set for the +inferior. The concrete registers assignment depends on the OS ABI and +the type being returned by the selected stack frame. For example it is +common for OS ABI to return floating point values in FPU registers while +integer values in CPU registers. Still some ABIs return even floating +point values in CPU registers. Larger integer widths (such as 'long +long int') also have specific placement rules. GDB already knows the OS +ABI from its current target so it needs to find out also the type being +returned to make the assignment into the right register(s). + + Normally, the selected stack frame has debug info. GDB will always +use the debug info instead of the implicit type of EXPRESSION when the +debug info is available. For example, if you type 'return -1', and the +function in the current stack frame is declared to return a 'long long +int', GDB transparently converts the implicit 'int' value of -1 into a +'long long int': + + Breakpoint 1, func () at gdb.base/return-nodebug.c:29 + 29 return 31; + (gdb) return -1 + Make func return now? (y or n) y + #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 + 43 printf ("result=%lld\n", func ()); + (gdb) + + However, if the selected stack frame does not have a debug info, +e.g., if the function was compiled without debug info, GDB has to find +out the type to return from user. Specifying a different type by +mistake may set the value in different inferior registers than the +caller code expects. For example, typing 'return -1' with its implicit +type 'int' would set only a part of a 'long long int' result for a debug +info less function (on 32-bit architectures). Therefore the user is +required to specify the return type by an appropriate cast explicitly: + + Breakpoint 2, 0x0040050b in func () + (gdb) return -1 + Return value type not available for selected stack frame. + Please use an explicit cast of the value to return. + (gdb) return (long long int) -1 + Make selected stack frame return now? (y or n) y + #0 0x00400526 in main () + (gdb) + + +File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering + +17.5 Calling Program Functions +============================== + +'print EXPR' + Evaluate the expression EXPR and display the resulting value. EXPR + may include calls to functions in the program being debugged. + +'call EXPR' + Evaluate the expression EXPR without displaying 'void' returned + values. + + You can use this variant of the 'print' command if you want to + execute a function from your program that does not return anything + (a.k.a. "a void function"), but without cluttering the output with + 'void' returned values that GDB will otherwise print. If the + result is not void, it is printed and saved in the value history. + + It is possible for the function you call via the 'print' or 'call' +command to generate a signal (e.g., if there's a bug in the function, or +if you passed it incorrect arguments). What happens in that case is +controlled by the 'set unwindonsignal' command. + + Similarly, with a C++ program it is possible for the function you +call via the 'print' or 'call' command to generate an exception that is +not handled due to the constraints of the dummy frame. In this case, +any exception that is raised in the frame, but has an out-of-frame +exception handler will not be found. GDB builds a dummy-frame for the +inferior function call, and the unwinder cannot seek for exception +handlers outside of this dummy-frame. What happens in that case is +controlled by the 'set unwind-on-terminating-exception' command. + +'set unwindonsignal' + Set unwinding of the stack if a signal is received while in a + function that GDB called in the program being debugged. If set to + on, GDB unwinds the stack it created for the call and restores the + context to what it was before the call. If set to off (the + default), GDB stops in the frame where the signal was received. + +'show unwindonsignal' + Show the current setting of stack unwinding in the functions called + by GDB. + +'set unwind-on-terminating-exception' + Set unwinding of the stack if a C++ exception is raised, but left + unhandled while in a function that GDB called in the program being + debugged. If set to on (the default), GDB unwinds the stack it + created for the call and restores the context to what it was before + the call. If set to off, GDB the exception is delivered to the + default C++ exception handler and the inferior terminated. + +'show unwind-on-terminating-exception' + Show the current setting of stack unwinding in the functions called + by GDB. + + Sometimes, a function you wish to call is actually a "weak alias" for +another function. In such case, GDB might not pick up the type +information, including the types of the function arguments, which causes +GDB to call the inferior function incorrectly. As a result, the called +function will function erroneously and may even crash. A solution to +that is to use the name of the aliased function instead. + + +File: gdb.info, Node: Patching, Prev: Calling, Up: Altering + +17.6 Patching Programs +====================== + +By default, GDB opens the file containing your program's executable code +(or the corefile) read-only. This prevents accidental alterations to +machine code; but it also prevents you from intentionally patching your +program's binary. + + If you'd like to be able to patch the binary, you can specify that +explicitly with the 'set write' command. For example, you might want to +turn on internal debugging flags, or even to make emergency repairs. + +'set write on' +'set write off' + If you specify 'set write on', GDB opens executable and core files + for both reading and writing; if you specify 'set write off' (the + default), GDB opens them read-only. + + If you have already loaded a file, you must load it again (using + the 'exec-file' or 'core-file' command) after changing 'set write', + for your new setting to take effect. + +'show write' + Display whether executable files and core files are opened for + writing as well as reading. + + +File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top + +18 GDB Files +************ + +GDB needs to know the file name of the program to be debugged, both in +order to read its symbol table and in order to start your program. To +debug a core dump of a previous run, you must also tell GDB the name of +the core dump file. + +* Menu: + +* Files:: Commands to specify files +* Separate Debug Files:: Debugging information in separate files +* MiniDebugInfo:: Debugging information in a special section +* Index Files:: Index files speed up GDB +* Symbol Errors:: Errors reading symbol files +* Data Files:: GDB data files + + +File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files + +18.1 Commands to Specify Files +============================== + +You may want to specify executable and core dump file names. The usual +way to do this is at start-up time, using the arguments to GDB's +start-up commands (*note Getting In and Out of GDB: Invocation.). + + Occasionally it is necessary to change to a different file during a +GDB session. Or you may run GDB and forget to specify a file you want +to use. Or you are debugging a remote target via 'gdbserver' (*note +file: Server.). In these situations the GDB commands to specify new +files are useful. + +'file FILENAME' + Use FILENAME as the program to be debugged. It is read for its + symbols and for the contents of pure memory. It is also the + program executed when you use the 'run' command. If you do not + specify a directory and the file is not found in the GDB working + directory, GDB uses the environment variable 'PATH' as a list of + directories to search, just as the shell does when looking for a + program to run. You can change the value of this variable, for + both GDB and your program, using the 'path' command. + + You can load unlinked object '.o' files into GDB using the 'file' + command. You will not be able to "run" an object file, but you can + disassemble functions and inspect variables. Also, if the + underlying BFD functionality supports it, you could use 'gdb + -write' to patch object files using this technique. Note that GDB + can neither interpret nor modify relocations in this case, so + branches and some initialized variables will appear to go to the + wrong place. But this feature is still handy from time to time. + +'file' + 'file' with no argument makes GDB discard any information it has on + both executable file and the symbol table. + +'exec-file [ FILENAME ]' + Specify that the program to be run (but not the symbol table) is + found in FILENAME. GDB searches the environment variable 'PATH' if + necessary to locate your program. Omitting FILENAME means to + discard information on the executable file. + +'symbol-file [ FILENAME ]' + Read symbol table information from file FILENAME. 'PATH' is + searched when necessary. Use the 'file' command to get both symbol + table and program to run from the same file. + + 'symbol-file' with no argument clears out GDB information on your + program's symbol table. + + The 'symbol-file' command causes GDB to forget the contents of some + breakpoints and auto-display expressions. This is because they may + contain pointers to the internal data recording symbols and data + types, which are part of the old symbol table data being discarded + inside GDB. + + 'symbol-file' does not repeat if you press again after + executing it once. + + When GDB is configured for a particular environment, it understands + debugging information in whatever format is the standard generated + for that environment; you may use either a GNU compiler, or other + compilers that adhere to the local conventions. Best results are + usually obtained from GNU compilers; for example, using 'GCC' you + can generate debugging information for optimized code. + + For most kinds of object files, with the exception of old SVR3 + systems using COFF, the 'symbol-file' command does not normally + read the symbol table in full right away. Instead, it scans the + symbol table quickly to find which source files and which symbols + are present. The details are read later, one source file at a + time, as they are needed. + + The purpose of this two-stage reading strategy is to make GDB start + up faster. For the most part, it is invisible except for + occasional pauses while the symbol table details for a particular + source file are being read. (The 'set verbose' command can turn + these pauses into messages if desired. *Note Optional Warnings and + Messages: Messages/Warnings.) + + We have not implemented the two-stage strategy for COFF yet. When + the symbol table is stored in COFF format, 'symbol-file' reads the + symbol table data in full right away. Note that "stabs-in-COFF" + still does the two-stage strategy, since the debug info is actually + in stabs format. + +'symbol-file [ -readnow ] FILENAME' +'file [ -readnow ] FILENAME' + You can override the GDB two-stage strategy for reading symbol + tables by using the '-readnow' option with any of the commands that + load symbol table information, if you want to be sure GDB has the + entire symbol table available. + +'core-file [FILENAME]' +'core' + Specify the whereabouts of a core dump file to be used as the + "contents of memory". Traditionally, core files contain only some + parts of the address space of the process that generated them; GDB + can access the executable file itself for other parts. + + 'core-file' with no argument specifies that no core file is to be + used. + + Note that the core file is ignored when your program is actually + running under GDB. So, if you have been running your program and + you wish to debug a core file instead, you must kill the subprocess + in which the program is running. To do this, use the 'kill' + command (*note Killing the Child Process: Kill Process.). + +'add-symbol-file FILENAME ADDRESS' +'add-symbol-file FILENAME ADDRESS [ -readnow ]' +'add-symbol-file FILENAME ADDRESS -s SECTION ADDRESS ...' + The 'add-symbol-file' command reads additional symbol table + information from the file FILENAME. You would use this command + when FILENAME has been dynamically loaded (by some other means) + into the program that is running. ADDRESS should be the memory + address at which the file has been loaded; GDB cannot figure this + out for itself. You can additionally specify an arbitrary number + of '-s SECTION ADDRESS' pairs, to give an explicit section name and + base address for that section. You can specify any ADDRESS as an + expression. + + The symbol table of the file FILENAME is added to the symbol table + originally read with the 'symbol-file' command. You can use the + 'add-symbol-file' command any number of times; the new symbol data + thus read is kept in addition to the old. + + Changes can be reverted using the command 'remove-symbol-file'. + + Although FILENAME is typically a shared library file, an executable + file, or some other object file which has been fully relocated for + loading into a process, you can also load symbolic information from + relocatable '.o' files, as long as: + + * the file's symbolic information refers only to linker symbols + defined in that file, not to symbols defined by other object + files, + * every section the file's symbolic information refers to has + actually been loaded into the inferior, as it appears in the + file, and + * you can determine the address at which every section was + loaded, and provide these to the 'add-symbol-file' command. + + Some embedded operating systems, like Sun Chorus and VxWorks, can + load relocatable files into an already running program; such + systems typically make the requirements above easy to meet. + However, it's important to recognize that many native systems use + complex link procedures ('.linkonce' section factoring and C++ + constructor table assembly, for example) that make the requirements + difficult to meet. In general, one cannot assume that using + 'add-symbol-file' to read a relocatable object file's symbolic + information will have the same effect as linking the relocatable + object file into the program in the normal way. + + 'add-symbol-file' does not repeat if you press after using + it. + +'remove-symbol-file FILENAME' +'remove-symbol-file -a ADDRESS' + Remove a symbol file added via the 'add-symbol-file' command. The + file to remove can be identified by its FILENAME or by an ADDRESS + that lies within the boundaries of this symbol file in memory. + Example: + + (gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480 + add symbol table from file "/home/user/gdb/mylib.so" at + .text_addr = 0x7ffff7ff9480 + (y or n) y + Reading symbols from /home/user/gdb/mylib.so...done. + (gdb) remove-symbol-file -a 0x7ffff7ff9480 + Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y + (gdb) + + 'remove-symbol-file' does not repeat if you press after using + it. + +'add-symbol-file-from-memory ADDRESS' + Load symbols from the given ADDRESS in a dynamically loaded object + file whose image is mapped directly into the inferior's memory. + For example, the Linux kernel maps a 'syscall DSO' into each + process's address space; this DSO provides kernel-specific code for + some system calls. The argument can be any expression whose + evaluation yields the address of the file's shared object file + header. For this command to work, you must have used 'symbol-file' + or 'exec-file' commands in advance. + +'add-shared-symbol-files LIBRARY-FILE' +'assf LIBRARY-FILE' + The 'add-shared-symbol-files' command can currently be used only in + the Cygwin build of GDB on MS-Windows OS, where it is an alias for + the 'dll-symbols' command (*note Cygwin Native::). GDB + automatically looks for shared libraries, however if GDB does not + find yours, you can invoke 'add-shared-symbol-files'. It takes one + argument: the shared library's file name. 'assf' is a shorthand + alias for 'add-shared-symbol-files'. + +'section SECTION ADDR' + The 'section' command changes the base address of the named SECTION + of the exec file to ADDR. This can be used if the exec file does + not contain section addresses, (such as in the 'a.out' format), or + when the addresses specified in the file itself are wrong. Each + section must be changed separately. The 'info files' command, + described below, lists all the sections and their addresses. + +'info files' +'info target' + 'info files' and 'info target' are synonymous; both print the + current target (*note Specifying a Debugging Target: Targets.), + including the names of the executable and core dump files currently + in use by GDB, and the files from which symbols were loaded. The + command 'help target' lists all possible targets rather than + current ones. + +'maint info sections' + Another command that can give you extra information about program + sections is 'maint info sections'. In addition to the section + information displayed by 'info files', this command displays the + flags and file offset of each section in the executable and core + dump files. In addition, 'maint info sections' provides the + following command options (which may be arbitrarily combined): + + 'ALLOBJ' + Display sections for all loaded object files, including shared + libraries. + 'SECTIONS' + Display info only for named SECTIONS. + 'SECTION-FLAGS' + Display info only for sections for which SECTION-FLAGS are + true. The section flags that GDB currently knows about are: + 'ALLOC' + Section will have space allocated in the process when + loaded. Set for all sections except those containing + debug information. + 'LOAD' + Section will be loaded from the file into the child + process memory. Set for pre-initialized code and data, + clear for '.bss' sections. + 'RELOC' + Section needs to be relocated before loading. + 'READONLY' + Section cannot be modified by the child process. + 'CODE' + Section contains executable code only. + 'DATA' + Section contains data only (no executable code). + 'ROM' + Section will reside in ROM. + 'CONSTRUCTOR' + Section contains data for constructor/destructor lists. + 'HAS_CONTENTS' + Section is not empty. + 'NEVER_LOAD' + An instruction to the linker to not output the section. + 'COFF_SHARED_LIBRARY' + A notification to the linker that the section contains + COFF shared library information. + 'IS_COMMON' + Section contains common symbols. +'set trust-readonly-sections on' + Tell GDB that readonly sections in your object file really are + read-only (i.e. that their contents will not change). In that + case, GDB can fetch values from these sections out of the object + file, rather than from the target program. For some targets + (notably embedded ones), this can be a significant enhancement to + debugging performance. + + The default is off. + +'set trust-readonly-sections off' + Tell GDB not to trust readonly sections. This means that the + contents of the section might change while the program is running, + and must therefore be fetched from the target when needed. + +'show trust-readonly-sections' + Show the current setting of trusting readonly sections. + + All file-specifying commands allow both absolute and relative file +names as arguments. GDB always converts the file name to an absolute +file name and remembers it that way. + + GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and IBM +RS/6000 AIX shared libraries. + + On MS-Windows GDB must be linked with the Expat library to support +shared libraries. *Note Expat::. + + GDB automatically loads symbol definitions from shared libraries when +you use the 'run' command, or when you examine a core file. (Before you +issue the 'run' command, GDB does not understand references to a +function in a shared library, however--unless you are debugging a core +file). + + On HP-UX, if the program loads a library explicitly, GDB +automatically loads the symbols at the time of the 'shl_load' call. + + There are times, however, when you may wish to not automatically load +symbol definitions from shared libraries, such as when they are +particularly large or there are many of them. + + To control the automatic loading of shared library symbols, use the +commands: + +'set auto-solib-add MODE' + If MODE is 'on', symbols from all shared object libraries will be + loaded automatically when the inferior begins execution, you attach + to an independently started inferior, or when the dynamic linker + informs GDB that a new library has been loaded. If MODE is 'off', + symbols must be loaded manually, using the 'sharedlibrary' command. + The default value is 'on'. + + If your program uses lots of shared libraries with debug info that + takes large amounts of memory, you can decrease the GDB memory + footprint by preventing it from automatically loading the symbols + from shared libraries. To that end, type 'set auto-solib-add off' + before running the inferior, then load each library whose debug + symbols you do need with 'sharedlibrary REGEXP', where REGEXP is a + regular expression that matches the libraries whose symbols you + want to be loaded. + +'show auto-solib-add' + Display the current autoloading mode. + + To explicitly load shared library symbols, use the 'sharedlibrary' +command: + +'info share REGEX' +'info sharedlibrary REGEX' + Print the names of the shared libraries which are currently loaded + that match REGEX. If REGEX is omitted then print all shared + libraries that are loaded. + +'sharedlibrary REGEX' +'share REGEX' + Load shared object library symbols for files matching a Unix + regular expression. As with files loaded automatically, it only + loads shared libraries required by your program for a core file or + after typing 'run'. If REGEX is omitted all shared libraries + required by your program are loaded. + +'nosharedlibrary' + Unload all shared object library symbols. This discards all + symbols that have been loaded from all shared libraries. Symbols + from shared libraries that were loaded by explicit user requests + are not discarded. + + Sometimes you may wish that GDB stops and gives you control when any +of shared library events happen. The best way to do this is to use +'catch load' and 'catch unload' (*note Set Catchpoints::). + + GDB also supports the the 'set stop-on-solib-events' command for +this. This command exists for historical reasons. It is less useful +than setting a catchpoint, because it does not allow for conditions or +commands as a catchpoint does. + +'set stop-on-solib-events' + This command controls whether GDB should give you control when the + dynamic linker notifies it about some shared library event. The + most common event of interest is loading or unloading of a new + shared library. + +'show stop-on-solib-events' + Show whether GDB stops and gives you control when shared library + events happen. + + Shared libraries are also supported in many cross or remote debugging +configurations. GDB needs to have access to the target's libraries; +this can be accomplished either by providing copies of the libraries on +the host system, or by asking GDB to automatically retrieve the +libraries from the target. If copies of the target libraries are +provided, they need to be the same as the target libraries, although the +copies on the target can be stripped as long as the copies on the host +are not. + + For remote debugging, you need to tell GDB where the target libraries +are, so that it can load the correct copies--otherwise, it may try to +load the host's libraries. GDB has two variables to specify the search +directories for target libraries. + +'set sysroot PATH' + Use PATH as the system root for the program being debugged. Any + absolute shared library paths will be prefixed with PATH; many + runtime loaders store the absolute paths to the shared library in + the target program's memory. If you use 'set sysroot' to find + shared libraries, they need to be laid out in the same way that + they are on the target, with e.g. a '/lib' and '/usr/lib' hierarchy + under PATH. + + If PATH starts with the sequence 'remote:', GDB will retrieve the + target libraries from the remote system. This is only supported + when using a remote target that supports the 'remote get' command + (*note Sending files to a remote system: File Transfer.). The part + of PATH following the initial 'remote:' (if present) is used as + system root prefix on the remote file system. (1) + + For targets with an MS-DOS based filesystem, such as MS-Windows and + SymbianOS, GDB tries prefixing a few variants of the target + absolute file name with PATH. But first, on Unix hosts, GDB + converts all backslash directory separators into forward slashes, + because the backslash is not a directory separator on Unix: + + c:\foo\bar.dll => c:/foo/bar.dll + + Then, GDB attempts prefixing the target file name with PATH, and + looks for the resulting file name in the host file system: + + c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll + + If that does not find the shared library, GDB tries removing the + ':' character from the drive spec, both for convenience, and, for + the case of the host file system not supporting file names with + colons: + + c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll + + This makes it possible to have a system root that mirrors a target + with more than one drive. E.g., you may want to setup your local + copies of the target system shared libraries like so (note 'c' vs + 'z'): + + /path/to/sysroot/c/sys/bin/foo.dll + /path/to/sysroot/c/sys/bin/bar.dll + /path/to/sysroot/z/sys/bin/bar.dll + + and point the system root at '/path/to/sysroot', so that GDB can + find the correct copies of both 'c:\sys\bin\foo.dll', and + 'z:\sys\bin\bar.dll'. + + If that still does not find the shared library, GDB tries removing + the whole drive spec from the target file name: + + c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll + + This last lookup makes it possible to not care about the drive + name, if you don't want or need to. + + The 'set solib-absolute-prefix' command is an alias for 'set + sysroot'. + + You can set the default system root by using the configure-time + '--with-sysroot' option. If the system root is inside GDB's + configured binary prefix (set with '--prefix' or '--exec-prefix'), + then the default system root will be updated automatically if the + installed GDB is moved to a new location. + +'show sysroot' + Display the current shared library prefix. + +'set solib-search-path PATH' + If this variable is set, PATH is a colon-separated list of + directories to search for shared libraries. 'solib-search-path' is + used after 'sysroot' fails to locate the library, or if the path to + the library is relative instead of absolute. If you want to use + 'solib-search-path' instead of 'sysroot', be sure to set 'sysroot' + to a nonexistent directory to prevent GDB from finding your host's + libraries. 'sysroot' is preferred; setting it to a nonexistent + directory may interfere with automatic loading of shared library + symbols. + +'show solib-search-path' + Display the current shared library search path. + +'set target-file-system-kind KIND' + Set assumed file system kind for target reported file names. + + Shared library file names as reported by the target system may not + make sense as is on the system GDB is running on. For example, + when remote debugging a target that has MS-DOS based file system + semantics, from a Unix host, the target may be reporting to GDB a + list of loaded shared libraries with file names such as + 'c:\Windows\kernel32.dll'. On Unix hosts, there's no concept of + drive letters, so the 'c:\' prefix is not normally understood as + indicating an absolute file name, and neither is the backslash + normally considered a directory separator character. In that case, + the native file system would interpret this whole absolute file + name as a relative file name with no directory components. This + would make it impossible to point GDB at a copy of the remote + target's shared libraries on the host using 'set sysroot', and + impractical with 'set solib-search-path'. Setting + 'target-file-system-kind' to 'dos-based' tells GDB to interpret + such file names similarly to how the target would, and to map them + to file names valid on GDB's native file system semantics. The + value of KIND can be '"auto"', in addition to one of the supported + file system kinds. In that case, GDB tries to determine the + appropriate file system variant based on the current target's + operating system (*note Configuring the Current ABI: ABI.). The + supported file system settings are: + + 'unix' + Instruct GDB to assume the target file system is of Unix kind. + Only file names starting the forward slash ('/') character are + considered absolute, and the directory separator character is + also the forward slash. + + 'dos-based' + Instruct GDB to assume the target file system is DOS based. + File names starting with either a forward slash, or a drive + letter followed by a colon (e.g., 'c:'), are considered + absolute, and both the slash ('/') and the backslash ('\\') + characters are considered directory separators. + + 'auto' + Instruct GDB to use the file system kind associated with the + target operating system (*note Configuring the Current ABI: + ABI.). This is the default. + + When processing file names provided by the user, GDB frequently needs +to compare them to the file names recorded in the program's debug info. +Normally, GDB compares just the "base names" of the files as strings, +which is reasonably fast even for very large programs. (The base name +of a file is the last portion of its name, after stripping all the +leading directories.) This shortcut in comparison is based upon the +assumption that files cannot have more than one base name. This is +usually true, but references to files that use symlinks or similar +filesystem facilities violate that assumption. If your program records +files using such facilities, or if you provide file names to GDB using +symlinks etc., you can set 'basenames-may-differ' to 'true' to instruct +GDB to completely canonicalize each pair of file names it needs to +compare. This will make file-name comparisons accurate, but at a price +of a significant slowdown. + +'set basenames-may-differ' + Set whether a source file may have multiple base names. + +'show basenames-may-differ' + Show whether a source file may have multiple base names. + + ---------- Footnotes ---------- + + (1) If you want to specify a local system root using a directory that +happens to be named 'remote:', you need to use some equivalent variant +of the name like './remote:'. + + +File: gdb.info, Node: Separate Debug Files, Next: MiniDebugInfo, Prev: Files, Up: GDB Files + +18.2 Debugging Information in Separate Files +============================================ + +GDB allows you to put a program's debugging information in a file +separate from the executable itself, in a way that allows GDB to find +and load the debugging information automatically. Since debugging +information can be very large--sometimes larger than the executable code +itself--some systems distribute debugging information for their +executables in separate files, which users can install only when they +need to debug a problem. + + GDB supports two ways of specifying the separate debug info file: + + * The executable contains a "debug link" that specifies the name of + the separate debug info file. The separate debug file's name is + usually 'EXECUTABLE.debug', where EXECUTABLE is the name of the + corresponding executable file without leading directories (e.g., + 'ls.debug' for '/usr/bin/ls'). In addition, the debug link + specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for the + debug file, which GDB uses to validate that the executable and the + debug file came from the same build. + + * The executable contains a "build ID", a unique bit string that is + also present in the corresponding debug info file. (This is + supported only on some operating systems, notably those which use + the ELF format for binary files and the GNU Binutils.) For more + details about this feature, see the description of the '--build-id' + command-line option in *note Command Line Options: + (ld.info)Options. The debug info file's name is not specified + explicitly by the build ID, but can be computed from the build ID, + see below. + + Depending on the way the debug info file is specified, GDB uses two +different methods of looking for the debug file: + + * For the "debug link" method, GDB looks up the named file in the + directory of the executable file, then in a subdirectory of that + directory named '.debug', and finally under each one of the global + debug directories, in a subdirectory whose name is identical to the + leading directories of the executable's absolute file name. + + * For the "build ID" method, GDB looks in the '.build-id' + subdirectory of each one of the global debug directories for a file + named 'NN/NNNNNNNN.debug', where NN are the first 2 hex characters + of the build ID bit string, and NNNNNNNN are the rest of the bit + string. (Real build ID strings are 32 or more hex characters, not + 10.) + + So, for example, suppose you ask GDB to debug '/usr/bin/ls', which +has a debug link that specifies the file 'ls.debug', and a build ID +whose value in hex is 'abcdef1234'. If the list of the global debug +directories includes '/usr/lib/debug', then GDB will look for the +following debug information files, in the indicated order: + + - '/usr/lib/debug/.build-id/ab/cdef1234.debug' + - '/usr/bin/ls.debug' + - '/usr/bin/.debug/ls.debug' + - '/usr/lib/debug/usr/bin/ls.debug'. + + Global debugging info directories default to what is set by GDB +configure option '--with-separate-debug-dir'. During GDB run you can +also set the global debugging info directories, and view the list GDB is +currently using. + +'set debug-file-directory DIRECTORIES' + Set the directories which GDB searches for separate debugging + information files to DIRECTORY. Multiple path components can be + set concatenating them by a path separator. + +'show debug-file-directory' + Show the directories GDB searches for separate debugging + information files. + + A debug link is a special section of the executable file named +'.gnu_debuglink'. The section must contain: + + * A filename, with any leading directory components removed, followed + by a zero byte, + * zero to three bytes of padding, as needed to reach the next + four-byte boundary within the section, and + * a four-byte CRC checksum, stored in the same endianness used for + the executable file itself. The checksum is computed on the + debugging information file's full contents by the function given + below, passing zero as the CRC argument. + + Any executable file format can carry a debug link, as long as it can +contain a section named '.gnu_debuglink' with the contents described +above. + + The build ID is a special section in the executable file (and in +other ELF binary files that GDB may consider). This section is often +named '.note.gnu.build-id', but that name is not mandatory. It contains +unique identification for the built files--the ID remains the same +across multiple builds of the same build tree. The default algorithm +SHA1 produces 160 bits (40 hexadecimal characters) of the content for +the build ID string. The same section with an identical value is +present in the original built binary with symbols, in its stripped +variant, and in the separate debugging information file. + + The debugging information file itself should be an ordinary +executable, containing a full set of linker symbols, sections, and +debugging information. The sections of the debugging information file +should have the same names, addresses, and sizes as the original file, +but they need not contain any data--much like a '.bss' section in an +ordinary executable. + + The GNU binary utilities (Binutils) package includes the 'objcopy' +utility that can produce the separated executable / debugging +information file pairs using the following commands: + + objcopy --only-keep-debug foo foo.debug + strip -g foo + +These commands remove the debugging information from the executable file +'foo' and place it in the file 'foo.debug'. You can use the first, +second or both methods to link the two files: + + * The debug link method needs the following additional command to + also leave behind a debug link in 'foo': + + objcopy --add-gnu-debuglink=foo.debug foo + + Ulrich Drepper's 'elfutils' package, starting with version 0.53, + contains a version of the 'strip' command such that the command + 'strip foo -f foo.debug' has the same functionality as the two + 'objcopy' commands and the 'ln -s' command above, together. + + * Build ID gets embedded into the main executable using 'ld + --build-id' or the GCC counterpart 'gcc -Wl,--build-id'. Build ID + support plus compatibility fixes for debug files separation are + present in GNU binary utilities (Binutils) package since version + 2.18. + + The CRC used in '.gnu_debuglink' is the CRC-32 defined in IEEE 802.3 +using the polynomial: + + x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11} + + x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1 + + The function is computed byte at a time, taking the least significant +bit of each byte first. The initial pattern '0xffffffff' is used, to +ensure leading zeros affect the CRC and the final result is inverted to +ensure trailing zeros also affect the CRC. + + _Note:_ This is the same CRC polynomial as used in handling the +"Remote Serial Protocol" 'qCRC' packet (*note GDB Remote Serial +Protocol: Remote Protocol.). However in the case of the Remote Serial +Protocol, the CRC is computed _most_ significant bit first, and the +result is not inverted, so trailing zeros have no effect on the CRC +value. + + To complete the description, we show below the code of the function +which produces the CRC used in '.gnu_debuglink'. Inverting the +initially supplied 'crc' argument means that an initial call to this +function passing in zero will start computing the CRC using +'0xffffffff'. + + unsigned long + gnu_debuglink_crc32 (unsigned long crc, + unsigned char *buf, size_t len) + { + static const unsigned long crc32_table[256] = + { + 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, + 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, + 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, + 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, + 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, + 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, + 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, + 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, + 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, + 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, + 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, + 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, + 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, + 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, + 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, + 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, + 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, + 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, + 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, + 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, + 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, + 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, + 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, + 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, + 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, + 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, + 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, + 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, + 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, + 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, + 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, + 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, + 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, + 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, + 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, + 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, + 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, + 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, + 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, + 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, + 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, + 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, + 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, + 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, + 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, + 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, + 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, + 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, + 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, + 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, + 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, + 0x2d02ef8d + }; + unsigned char *end; + + crc = ~crc & 0xffffffff; + for (end = buf + len; buf < end; ++buf) + crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); + return ~crc & 0xffffffff; + } + +This computation does not apply to the "build ID" method. + + +File: gdb.info, Node: MiniDebugInfo, Next: Index Files, Prev: Separate Debug Files, Up: GDB Files + +18.3 Debugging information in a special section +=============================================== + +Some systems ship pre-built executables and libraries that have a +special '.gnu_debugdata' section. This feature is called +"MiniDebugInfo". This section holds an LZMA-compressed object and is +used to supply extra symbols for backtraces. + + The intent of this section is to provide extra minimal debugging +information for use in simple backtraces. It is not intended to be a +replacement for full separate debugging information (*note Separate +Debug Files::). The example below shows the intended use; however, GDB +does not currently put restrictions on what sort of debugging +information might be included in the section. + + GDB has support for this extension. If the section exists, then it +is used provided that no other source of debugging information can be +found, and that GDB was configured with LZMA support. + + This section can be easily created using 'objcopy' and other standard +utilities: + + # Extract the dynamic symbols from the main binary, there is no need + # to also have these in the normal symbol table. + nm -D BINARY --format=posix --defined-only \ + | awk '{ print $1 }' | sort > dynsyms + + # Extract all the text (i.e. function) symbols from the debuginfo. + # (Note that we actually also accept "D" symbols, for the benefit + # of platforms like PowerPC64 that use function descriptors.) + nm BINARY --format=posix --defined-only \ + | awk '{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 }' \ + | sort > funcsyms + + # Keep all the function symbols not already in the dynamic symbol + # table. + comm -13 dynsyms funcsyms > keep_symbols + + # Separate full debug info into debug binary. + objcopy --only-keep-debug BINARY debug + + # Copy the full debuginfo, keeping only a minimal set of symbols and + # removing some unnecessary sections. + objcopy -S --remove-section .gdb_index --remove-section .comment \ + --keep-symbols=keep_symbols debug mini_debuginfo + + # Drop the full debug info from the original binary. + strip --strip-all -R .comment BINARY + + # Inject the compressed data into the .gnu_debugdata section of the + # original binary. + xz mini_debuginfo + objcopy --add-section .gnu_debugdata=mini_debuginfo.xz BINARY + + +File: gdb.info, Node: Index Files, Next: Symbol Errors, Prev: MiniDebugInfo, Up: GDB Files + +18.4 Index Files Speed Up GDB +============================= + +When GDB finds a symbol file, it scans the symbols in the file in order +to construct an internal symbol table. This lets most GDB operations +work quickly--at the cost of a delay early on. For large programs, this +delay can be quite lengthy, so GDB provides a way to build an index, +which speeds up startup. + + The index is stored as a section in the symbol file. GDB can write +the index to a file, then you can put it into the symbol file using +'objcopy'. + + To create an index file, use the 'save gdb-index' command: + +'save gdb-index DIRECTORY' + Create an index file for each symbol file currently known by GDB. + Each file is named after its corresponding symbol file, with + '.gdb-index' appended, and is written into the given DIRECTORY. + + Once you have created an index file you can merge it into your symbol +file, here named 'symfile', using 'objcopy': + + $ objcopy --add-section .gdb_index=symfile.gdb-index \ + --set-section-flags .gdb_index=readonly symfile symfile + + GDB will normally ignore older versions of '.gdb_index' sections that +have been deprecated. Usually they are deprecated because they are +missing a new feature or have performance issues. To tell GDB to use a +deprecated index section anyway specify 'set +use-deprecated-index-sections on'. The default is 'off'. This can +speed up startup, but may result in some functionality being lost. +*Note Index Section Format::. + + _Warning:_ Setting 'use-deprecated-index-sections' to 'on' must be +done before gdb reads the file. The following will not work: + + $ gdb -ex "set use-deprecated-index-sections on" + + Instead you must do, for example, + + $ gdb -iex "set use-deprecated-index-sections on" + + There are currently some limitation on indices. They only work when +for DWARF debugging information, not stabs. And, they do not currently +work for programs using Ada. + + +File: gdb.info, Node: Symbol Errors, Next: Data Files, Prev: Index Files, Up: GDB Files + +18.5 Errors Reading Symbol Files +================================ + +While reading a symbol file, GDB occasionally encounters problems, such +as symbol types it does not recognize, or known bugs in compiler output. +By default, GDB does not notify you of such problems, since they are +relatively common and primarily of interest to people debugging +compilers. If you are interested in seeing information about +ill-constructed symbol tables, you can either ask GDB to print only one +message about each such type of problem, no matter how many times the +problem occurs; or you can ask GDB to print more messages, to see how +many times the problems occur, with the 'set complaints' command (*note +Optional Warnings and Messages: Messages/Warnings.). + + The messages currently printed, and their meanings, include: + +'inner block not inside outer block in SYMBOL' + + The symbol information shows where symbol scopes begin and end + (such as at the start of a function or a block of statements). + This error indicates that an inner scope block is not fully + contained in its outer scope blocks. + + GDB circumvents the problem by treating the inner block as if it + had the same scope as the outer block. In the error message, + SYMBOL may be shown as "'(don't know)'" if the outer block is not a + function. + +'block at ADDRESS out of order' + + The symbol information for symbol scope blocks should occur in + order of increasing addresses. This error indicates that it does + not do so. + + GDB does not circumvent this problem, and has trouble locating + symbols in the source file whose symbols it is reading. (You can + often determine what source file is affected by specifying 'set + verbose on'. *Note Optional Warnings and Messages: + Messages/Warnings.) + +'bad block start address patched' + + The symbol information for a symbol scope block has a start address + smaller than the address of the preceding source line. This is + known to occur in the SunOS 4.1.1 (and earlier) C compiler. + + GDB circumvents the problem by treating the symbol scope block as + starting on the previous source line. + +'bad string table offset in symbol N' + + Symbol number N contains a pointer into the string table which is + larger than the size of the string table. + + GDB circumvents the problem by considering the symbol to have the + name 'foo', which may cause other problems if many symbols end up + with this name. + +'unknown symbol type 0xNN' + + The symbol information contains new data types that GDB does not + yet know how to read. '0xNN' is the symbol type of the + uncomprehended information, in hexadecimal. + + GDB circumvents the error by ignoring this symbol information. + This usually allows you to debug your program, though certain + symbols are not accessible. If you encounter such a problem and + feel like debugging it, you can debug 'gdb' with itself, breakpoint + on 'complain', then go up to the function 'read_dbx_symtab' and + examine '*bufp' to see the symbol. + +'stub type has NULL name' + + GDB could not find the full definition for a struct or class. + +'const/volatile indicator missing (ok if using g++ v1.x), got...' + The symbol information for a C++ member function is missing some + information that recent versions of the compiler should have output + for it. + +'info mismatch between compiler and debugger' + + GDB could not parse a type specification output by the compiler. + + +File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files + +18.6 GDB Data Files +=================== + +GDB will sometimes read an auxiliary data file. These files are kept in +a directory known as the "data directory". + + You can set the data directory's name, and view the name GDB is +currently using. + +'set data-directory DIRECTORY' + Set the directory which GDB searches for auxiliary data files to + DIRECTORY. + +'show data-directory' + Show the directory GDB searches for auxiliary data files. + + You can set the default data directory by using the configure-time +'--with-gdb-datadir' option. If the data directory is inside GDB's +configured binary prefix (set with '--prefix' or '--exec-prefix'), then +the default data directory will be updated automatically if the +installed GDB is moved to a new location. + + The data directory may also be specified with the '--data-directory' +command line option. *Note Mode Options::. + + +File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top + +19 Specifying a Debugging Target +******************************** + +A "target" is the execution environment occupied by your program. + + Often, GDB runs in the same host environment as your program; in that +case, the debugging target is specified as a side effect when you use +the 'file' or 'core' commands. When you need more flexibility--for +example, running GDB on a physically separate host, or controlling a +standalone system over a serial port or a realtime system over a TCP/IP +connection--you can use the 'target' command to specify one of the +target types configured for GDB (*note Commands for Managing Targets: +Target Commands.). + + It is possible to build GDB for several different "target +architectures". When GDB is built like that, you can choose one of the +available architectures with the 'set architecture' command. + +'set architecture ARCH' + This command sets the current target architecture to ARCH. The + value of ARCH can be '"auto"', in addition to one of the supported + architectures. + +'show architecture' + Show the current target architecture. + +'set processor' +'processor' + These are alias commands for, respectively, 'set architecture' and + 'show architecture'. + +* Menu: + +* Active Targets:: Active targets +* Target Commands:: Commands for managing targets +* Byte Order:: Choosing target byte order + + +File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets + +19.1 Active Targets +=================== + +There are multiple classes of targets such as: processes, executable +files or recording sessions. Core files belong to the process class, +making core file and process mutually exclusive. Otherwise, GDB can +work concurrently on multiple active targets, one in each class. This +allows you to (for example) start a process and inspect its activity, +while still having access to the executable file after the process +finishes. Or if you start process recording (*note Reverse Execution::) +and 'reverse-step' there, you are presented a virtual layer of the +recording target, while the process target remains stopped at the +chronologically last point of the process execution. + + Use the 'core-file' and 'exec-file' commands to select a new core +file or executable target (*note Commands to Specify Files: Files.). To +specify as a target a process that is already running, use the 'attach' +command (*note Debugging an Already-running Process: Attach.). + + +File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets + +19.2 Commands for Managing Targets +================================== + +'target TYPE PARAMETERS' + Connects the GDB host environment to a target machine or process. + A target is typically a protocol for talking to debugging + facilities. You use the argument TYPE to specify the type or + protocol of the target machine. + + Further PARAMETERS are interpreted by the target protocol, but + typically include things like device names or host names to connect + with, process numbers, and baud rates. + + The 'target' command does not repeat if you press again after + executing the command. + +'help target' + Displays the names of all targets available. To display targets + currently selected, use either 'info target' or 'info files' (*note + Commands to Specify Files: Files.). + +'help target NAME' + Describe a particular target, including any parameters necessary to + select it. + +'set gnutarget ARGS' + GDB uses its own library BFD to read your files. GDB knows whether + it is reading an "executable", a "core", or a ".o" file; however, + you can specify the file format with the 'set gnutarget' command. + Unlike most 'target' commands, with 'gnutarget' the 'target' refers + to a program, not a machine. + + _Warning:_ To specify a file format with 'set gnutarget', you + must know the actual BFD name. + + *Note Commands to Specify Files: Files. + +'show gnutarget' + Use the 'show gnutarget' command to display what file format + 'gnutarget' is set to read. If you have not set 'gnutarget', GDB + will determine the file format for each file automatically, and + 'show gnutarget' displays 'The current BFD target is "auto"'. + + Here are some common targets (available, or not, depending on the GDB +configuration): + +'target exec PROGRAM' + An executable file. 'target exec PROGRAM' is the same as + 'exec-file PROGRAM'. + +'target core FILENAME' + A core dump file. 'target core FILENAME' is the same as 'core-file + FILENAME'. + +'target remote MEDIUM' + A remote system connected to GDB via a serial line or network + connection. This command tells GDB to use its own remote protocol + over MEDIUM for debugging. *Note Remote Debugging::. + + For example, if you have a board connected to '/dev/ttya' on the + machine running GDB, you could say: + + target remote /dev/ttya + + 'target remote' supports the 'load' command. This is only useful + if you have some other way of getting the stub to the target + system, and you can put it somewhere in memory where it won't get + clobbered by the download. + +'target sim [SIMARGS] ...' + Builtin CPU simulator. GDB includes simulators for most + architectures. In general, + target sim + load + run + works; however, you cannot assume that a specific memory map, + device drivers, or even basic I/O is available, although some + simulators do provide these. For info about any processor-specific + simulator details, see the appropriate section in *note Embedded + Processors: Embedded Processors. + + Different targets are available on different configurations of GDB; +your configuration may have more or fewer targets. + + Many remote targets require you to download the executable's code +once you've successfully established a connection. You may wish to +control various aspects of this process. + +'set hash' + This command controls whether a hash mark '#' is displayed while + downloading a file to the remote monitor. If on, a hash mark is + displayed after each S-record is successfully downloaded to the + monitor. + +'show hash' + Show the current status of displaying the hash mark. + +'set debug monitor' + Enable or disable display of communications messages between GDB + and the remote monitor. + +'show debug monitor' + Show the current status of displaying communications between GDB + and the remote monitor. + +'load FILENAME' + Depending on what remote debugging facilities are configured into + GDB, the 'load' command may be available. Where it exists, it is + meant to make FILENAME (an executable) available for debugging on + the remote system--by downloading, or dynamic linking, for example. + 'load' also records the FILENAME symbol table in GDB, like the + 'add-symbol-file' command. + + If your GDB does not have a 'load' command, attempting to execute + it gets the error message "'You can't do that when your target is + ...'" + + The file is loaded at whatever address is specified in the + executable. For some object file formats, you can specify the load + address when you link the program; for other formats, like a.out, + the object file format specifies a fixed address. + + Depending on the remote side capabilities, GDB may be able to load + programs into flash memory. + + 'load' does not repeat if you press again after using it. + + +File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets + +19.3 Choosing Target Byte Order +=============================== + +Some types of processors, such as the MIPS, PowerPC, and Renesas SH, +offer the ability to run either big-endian or little-endian byte orders. +Usually the executable or symbol will include a bit to designate the +endian-ness, and you will not need to worry about which to use. +However, you may still find it useful to adjust GDB's idea of processor +endian-ness manually. + +'set endian big' + Instruct GDB to assume the target is big-endian. + +'set endian little' + Instruct GDB to assume the target is little-endian. + +'set endian auto' + Instruct GDB to use the byte order associated with the executable. + +'show endian' + Display GDB's current idea of the target byte order. + + Note that these commands merely adjust interpretation of symbolic +data on the host, and that they have absolutely no effect on the target +system. + + +File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top + +20 Debugging Remote Programs +**************************** + +If you are trying to debug a program running on a machine that cannot +run GDB in the usual way, it is often useful to use remote debugging. +For example, you might use remote debugging on an operating system +kernel, or on a small system which does not have a general purpose +operating system powerful enough to run a full-featured debugger. + + Some configurations of GDB have special serial or TCP/IP interfaces +to make this work with particular debugging targets. In addition, GDB +comes with a generic serial protocol (specific to GDB, but not specific +to any particular target system) which you can use if you write the +remote stubs--the code that runs on the remote system to communicate +with GDB. + + Other remote targets may be available in your configuration of GDB; +use 'help target' to list them. + +* Menu: + +* Connecting:: Connecting to a remote target +* File Transfer:: Sending files to a remote system +* Server:: Using the gdbserver program +* Remote Configuration:: Remote configuration +* Remote Stub:: Implementing a remote stub + + +File: gdb.info, Node: Connecting, Next: File Transfer, Up: Remote Debugging + +20.1 Connecting to a Remote Target +================================== + +On the GDB host machine, you will need an unstripped copy of your +program, since GDB needs symbol and debugging information. Start up GDB +as usual, using the name of the local copy of your program as the first +argument. + + GDB can communicate with the target over a serial line, or over an IP +network using TCP or UDP. In each case, GDB uses the same protocol for +debugging your program; only the medium carrying the debugging packets +varies. The 'target remote' command establishes a connection to the +target. Its arguments indicate which medium to use: + +'target remote SERIAL-DEVICE' + Use SERIAL-DEVICE to communicate with the target. For example, to + use a serial line connected to the device named '/dev/ttyb': + + target remote /dev/ttyb + + If you're using a serial line, you may want to give GDB the + '--baud' option, or use the 'set serial baud' command (*note set + serial baud: Remote Configuration.) before the 'target' command. + +'target remote HOST:PORT' +'target remote tcp:HOST:PORT' + Debug using a TCP connection to PORT on HOST. The HOST may be + either a host name or a numeric IP address; PORT must be a decimal + number. The HOST could be the target machine itself, if it is + directly connected to the net, or it might be a terminal server + which in turn has a serial line to the target. + + For example, to connect to port 2828 on a terminal server named + 'manyfarms': + + target remote manyfarms:2828 + + If your remote target is actually running on the same machine as + your debugger session (e.g. a simulator for your target running on + the same host), you can omit the hostname. For example, to connect + to port 1234 on your local machine: + + target remote :1234 + + Note that the colon is still required here. + +'target remote udp:HOST:PORT' + Debug using UDP packets to PORT on HOST. For example, to connect + to UDP port 2828 on a terminal server named 'manyfarms': + + target remote udp:manyfarms:2828 + + When using a UDP connection for remote debugging, you should keep + in mind that the 'U' stands for "Unreliable". UDP can silently + drop packets on busy or unreliable networks, which will cause havoc + with your debugging session. + +'target remote | COMMAND' + Run COMMAND in the background and communicate with it using a pipe. + The COMMAND is a shell command, to be parsed and expanded by the + system's command shell, '/bin/sh'; it should expect remote protocol + packets on its standard input, and send replies on its standard + output. You could use this to run a stand-alone simulator that + speaks the remote debugging protocol, to make net connections using + programs like 'ssh', or for other similar tricks. + + If COMMAND closes its standard output (perhaps by exiting), GDB + will try to send it a 'SIGTERM' signal. (If the program has + already exited, this will have no effect.) + + Once the connection has been established, you can use all the usual +commands to examine and change data. The remote program is already +running; you can use 'step' and 'continue', and you do not need to use +'run'. + + Whenever GDB is waiting for the remote program, if you type the +interrupt character (often 'Ctrl-c'), GDB attempts to stop the program. +This may or may not succeed, depending in part on the hardware and the +serial drivers the remote system uses. If you type the interrupt +character once again, GDB displays this prompt: + + Interrupted while waiting for the program. + Give up (and stop debugging it)? (y or n) + + If you type 'y', GDB abandons the remote debugging session. (If you +decide you want to try again later, you can use 'target remote' again to +connect once more.) If you type 'n', GDB goes back to waiting. + +'detach' + When you have finished debugging the remote program, you can use + the 'detach' command to release it from GDB control. Detaching + from the target normally resumes its execution, but the results + will depend on your particular remote stub. After the 'detach' + command, GDB is free to connect to another target. + +'disconnect' + The 'disconnect' command behaves like 'detach', except that the + target is generally not resumed. It will wait for GDB (this + instance or another one) to connect and continue debugging. After + the 'disconnect' command, GDB is again free to connect to another + target. + +'monitor CMD' + This command allows you to send arbitrary commands directly to the + remote monitor. Since GDB doesn't care about the commands it sends + like this, this command is the way to extend GDB--you can add new + commands that only the external monitor will understand and + implement. + + +File: gdb.info, Node: File Transfer, Next: Server, Prev: Connecting, Up: Remote Debugging + +20.2 Sending files to a remote system +===================================== + +Some remote targets offer the ability to transfer files over the same +connection used to communicate with GDB. This is convenient for targets +accessible through other means, e.g. GNU/Linux systems running +'gdbserver' over a network interface. For other targets, e.g. embedded +devices with only a single serial port, this may be the only way to +upload or download files. + + Not all remote targets support these commands. + +'remote put HOSTFILE TARGETFILE' + Copy file HOSTFILE from the host system (the machine running GDB) + to TARGETFILE on the target system. + +'remote get TARGETFILE HOSTFILE' + Copy file TARGETFILE from the target system to HOSTFILE on the host + system. + +'remote delete TARGETFILE' + Delete TARGETFILE from the target system. + + +File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer, Up: Remote Debugging + +20.3 Using the 'gdbserver' Program +================================== + +'gdbserver' is a control program for Unix-like systems, which allows you +to connect your program with a remote GDB via 'target remote'--but +without linking in the usual debugging stub. + + 'gdbserver' is not a complete replacement for the debugging stubs, +because it requires essentially the same operating-system facilities +that GDB itself does. In fact, a system that can run 'gdbserver' to +connect to a remote GDB could also run GDB locally! 'gdbserver' is +sometimes useful nevertheless, because it is a much smaller program than +GDB itself. It is also easier to port than all of GDB, so you may be +able to get started more quickly on a new system by using 'gdbserver'. +Finally, if you develop code for real-time systems, you may find that +the tradeoffs involved in real-time operation make it more convenient to +do as much development work as possible on another system, for example +by cross-compiling. You can use 'gdbserver' to make a similar choice +for debugging. + + GDB and 'gdbserver' communicate via either a serial line or a TCP +connection, using the standard GDB remote serial protocol. + + _Warning:_ 'gdbserver' does not have any built-in security. Do not + run 'gdbserver' connected to any public network; a GDB connection + to 'gdbserver' provides access to the target system with the same + privileges as the user running 'gdbserver'. + +20.3.1 Running 'gdbserver' +-------------------------- + +Run 'gdbserver' on the target system. You need a copy of the program +you want to debug, including any libraries it requires. 'gdbserver' +does not need your program's symbol table, so you can strip the program +if necessary to save space. GDB on the host system does all the symbol +handling. + + To use the server, you must tell it how to communicate with GDB; the +name of your program; and the arguments for your program. The usual +syntax is: + + target> gdbserver COMM PROGRAM [ ARGS ... ] + + COMM is either a device name (to use a serial line), or a TCP +hostname and portnumber, or '-' or 'stdio' to use stdin/stdout of +'gdbserver'. For example, to debug Emacs with the argument 'foo.txt' +and communicate with GDB over the serial port '/dev/com1': + + target> gdbserver /dev/com1 emacs foo.txt + + 'gdbserver' waits passively for the host GDB to communicate with it. + + To use a TCP connection instead of a serial line: + + target> gdbserver host:2345 emacs foo.txt + + The only difference from the previous example is the first argument, +specifying that you are communicating with the host GDB via TCP. The +'host:2345' argument means that 'gdbserver' is to expect a TCP +connection from machine 'host' to local TCP port 2345. (Currently, the +'host' part is ignored.) You can choose any number you want for the +port number as long as it does not conflict with any TCP ports already +in use on the target system (for example, '23' is reserved for +'telnet').(1) You must use the same port number with the host GDB +'target remote' command. + + The 'stdio' connection is useful when starting 'gdbserver' with ssh: + + (gdb) target remote | ssh -T hostname gdbserver - hello + + The '-T' option to ssh is provided because we don't need a remote +pty, and we don't want escape-character handling. Ssh does this by +default when a command is provided, the flag is provided to make it +explicit. You could elide it if you want to. + + Programs started with stdio-connected gdbserver have '/dev/null' for +'stdin', and 'stdout','stderr' are sent back to gdb for display through +a pipe connected to gdbserver. Both 'stdout' and 'stderr' use the same +pipe. + +20.3.1.1 Attaching to a Running Program +....................................... + +On some targets, 'gdbserver' can also attach to running programs. This +is accomplished via the '--attach' argument. The syntax is: + + target> gdbserver --attach COMM PID + + PID is the process ID of a currently running process. It isn't +necessary to point 'gdbserver' at a binary for the running process. + + You can debug processes by name instead of process ID if your target +has the 'pidof' utility: + + target> gdbserver --attach COMM `pidof PROGRAM` + + In case more than one copy of PROGRAM is running, or PROGRAM has +multiple threads, most versions of 'pidof' support the '-s' option to +only return the first process ID. + +20.3.1.2 Multi-Process Mode for 'gdbserver' +........................................... + +When you connect to 'gdbserver' using 'target remote', 'gdbserver' +debugs the specified program only once. When the program exits, or you +detach from it, GDB closes the connection and 'gdbserver' exits. + + If you connect using 'target extended-remote', 'gdbserver' enters +multi-process mode. When the debugged program exits, or you detach from +it, GDB stays connected to 'gdbserver' even though no program is +running. The 'run' and 'attach' commands instruct 'gdbserver' to run or +attach to a new program. The 'run' command uses 'set remote exec-file' +(*note set remote exec-file::) to select the program to run. Command +line arguments are supported, except for wildcard expansion and I/O +redirection (*note Arguments::). + + To start 'gdbserver' without supplying an initial command to run or +process ID to attach, use the '--multi' command line option. Then you +can connect using 'target extended-remote' and start the program you +want to debug. + + In multi-process mode 'gdbserver' does not automatically exit unless +you use the option '--once'. You can terminate it by using 'monitor +exit' (*note Monitor Commands for gdbserver::). Note that the +conditions under which 'gdbserver' terminates depend on how GDB connects +to it ('target remote' or 'target extended-remote'). The '--multi' +option to 'gdbserver' has no influence on that. + +20.3.1.3 TCP port allocation lifecycle of 'gdbserver' +..................................................... + +This section applies only when 'gdbserver' is run to listen on a TCP +port. + + 'gdbserver' normally terminates after all of its debugged processes +have terminated in 'target remote' mode. On the other hand, for 'target +extended-remote', 'gdbserver' stays running even with no processes left. +GDB normally terminates the spawned debugged process on its exit, which +normally also terminates 'gdbserver' in the 'target remote' mode. +Therefore, when the connection drops unexpectedly, and GDB cannot ask +'gdbserver' to kill its debugged processes, 'gdbserver' stays running +even in the 'target remote' mode. + + When 'gdbserver' stays running, GDB can connect to it again later. +Such reconnecting is useful for features like *note disconnected +tracing::. For completeness, at most one GDB can be connected at a +time. + + By default, 'gdbserver' keeps the listening TCP port open, so that +subsequent connections are possible. However, if you start 'gdbserver' +with the '--once' option, it will stop listening for any further +connection attempts after connecting to the first GDB session. This +means no further connections to 'gdbserver' will be possible after the +first one. It also means 'gdbserver' will terminate after the first +connection with remote GDB has closed, even for unexpectedly closed +connections and even in the 'target extended-remote' mode. The '--once' +option allows reusing the same port number for connecting to multiple +instances of 'gdbserver' running on the same host, since each instance +closes its port after the first connection. + +20.3.1.4 Other Command-Line Arguments for 'gdbserver' +..................................................... + +The '--debug' option tells 'gdbserver' to display extra status +information about the debugging process. The '--remote-debug' option +tells 'gdbserver' to display remote protocol debug output. These +options are intended for 'gdbserver' development and for bug reports to +the developers. + + The '--wrapper' option specifies a wrapper to launch programs for +debugging. The option should be followed by the name of the wrapper, +then any command-line arguments to pass to the wrapper, then '--' +indicating the end of the wrapper arguments. + + 'gdbserver' runs the specified wrapper program with a combined +command line including the wrapper arguments, then the name of the +program to debug, then any arguments to the program. The wrapper runs +until it executes your program, and then GDB gains control. + + You can use any program that eventually calls 'execve' with its +arguments as a wrapper. Several standard Unix utilities do this, e.g. +'env' and 'nohup'. Any Unix shell script ending with 'exec "$@"' will +also work. + + For example, you can use 'env' to pass an environment variable to the +debugged program, without setting the variable in 'gdbserver''s +environment: + + $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog + +20.3.2 Connecting to 'gdbserver' +-------------------------------- + +Run GDB on the host system. + + First make sure you have the necessary symbol files. Load symbols +for your application using the 'file' command before you connect. Use +'set sysroot' to locate target libraries (unless your GDB was compiled +with the correct sysroot using '--with-sysroot'). + + The symbol file and target libraries must exactly match the +executable and libraries on the target, with one exception: the files on +the host system should not be stripped, even if the files on the target +system are. Mismatched or missing files will lead to confusing results +during debugging. On GNU/Linux targets, mismatched or missing files may +also prevent 'gdbserver' from debugging multi-threaded programs. + + Connect to your target (*note Connecting to a Remote Target: +Connecting.). For TCP connections, you must start up 'gdbserver' prior +to using the 'target remote' command. Otherwise you may get an error +whose text depends on the host system, but which usually looks something +like 'Connection refused'. Don't use the 'load' command in GDB when +using 'gdbserver', since the program is already on the target. + +20.3.3 Monitor Commands for 'gdbserver' +--------------------------------------- + +During a GDB session using 'gdbserver', you can use the 'monitor' +command to send special requests to 'gdbserver'. Here are the available +commands. + +'monitor help' + List the available monitor commands. + +'monitor set debug 0' +'monitor set debug 1' + Disable or enable general debugging messages. + +'monitor set remote-debug 0' +'monitor set remote-debug 1' + Disable or enable specific debugging messages associated with the + remote protocol (*note Remote Protocol::). + +'monitor set libthread-db-search-path [PATH]' + When this command is issued, PATH is a colon-separated list of + directories to search for 'libthread_db' (*note set + libthread-db-search-path: Threads.). If you omit PATH, + 'libthread-db-search-path' will be reset to its default value. + + The special entry '$pdir' for 'libthread-db-search-path' is not + supported in 'gdbserver'. + +'monitor exit' + Tell gdbserver to exit immediately. This command should be + followed by 'disconnect' to close the debugging session. + 'gdbserver' will detach from any attached processes and kill any + processes it created. Use 'monitor exit' to terminate 'gdbserver' + at the end of a multi-process mode debug session. + +20.3.4 Tracepoints support in 'gdbserver' +----------------------------------------- + +On some targets, 'gdbserver' supports tracepoints, fast tracepoints and +static tracepoints. + + For fast or static tracepoints to work, a special library called the +"in-process agent" (IPA), must be loaded in the inferior process. This +library is built and distributed as an integral part of 'gdbserver'. In +addition, support for static tracepoints requires building the +in-process agent library with static tracepoints support. At present, +the UST (LTTng Userspace Tracer, ) tracing engine +is supported. This support is automatically available if UST +development headers are found in the standard include path when +'gdbserver' is built, or if 'gdbserver' was explicitly configured using +'--with-ust' to point at such headers. You can explicitly disable the +support using '--with-ust=no'. + + There are several ways to load the in-process agent in your program: + +'Specifying it as dependency at link time' + + You can link your program dynamically with the in-process agent + library. On most systems, this is accomplished by adding + '-linproctrace' to the link command. + +'Using the system's preloading mechanisms' + + You can force loading the in-process agent at startup time by using + your system's support for preloading shared libraries. Many Unixes + support the concept of preloading user defined libraries. In most + cases, you do that by specifying 'LD_PRELOAD=libinproctrace.so' in + the environment. See also the description of 'gdbserver''s + '--wrapper' command line option. + +'Using GDB to force loading the agent at run time' + + On some systems, you can force the inferior to load a shared + library, by calling a dynamic loader function in the inferior that + takes care of dynamically looking up and loading a shared library. + On most Unix systems, the function is 'dlopen'. You'll use the + 'call' command for that. For example: + + (gdb) call dlopen ("libinproctrace.so", ...) + + Note that on most Unix systems, for the 'dlopen' function to be + available, the program needs to be linked with '-ldl'. + + On systems that have a userspace dynamic loader, like most Unix +systems, when you connect to 'gdbserver' using 'target remote', you'll +find that the program is stopped at the dynamic loader's entry point, +and no shared library has been loaded in the program's address space +yet, including the in-process agent. In that case, before being able to +use any of the fast or static tracepoints features, you need to let the +loader run and load the shared libraries. The simplest way to do that +is to run the program to the main procedure. E.g., if debugging a C or +C++ program, start 'gdbserver' like so: + + $ gdbserver :9999 myprogram + + Start GDB and connect to 'gdbserver' like so, and run to main: + + $ gdb myprogram + (gdb) target remote myhost:9999 + 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 + (gdb) b main + (gdb) continue + + The in-process tracing agent library should now be loaded into the +process; you can confirm it with the 'info sharedlibrary' command, which +will list 'libinproctrace.so' as loaded in the process. You are now +ready to install fast tracepoints, list static tracepoint markers, probe +static tracepoints markers, and start tracing. + + ---------- Footnotes ---------- + + (1) If you choose a port number that conflicts with another service, +'gdbserver' prints an error message and exits. + + +File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server, Up: Remote Debugging + +20.4 Remote Configuration +========================= + +This section documents the configuration options available when +debugging remote programs. For the options related to the File I/O +extensions of the remote protocol, see *note system-call-allowed: +system. + +'set remoteaddresssize BITS' + Set the maximum size of address in a memory packet to the specified + number of bits. GDB will mask off the address bits above that + number, when it passes addresses to the remote target. The default + value is the number of bits in the target's address. + +'show remoteaddresssize' + Show the current value of remote address size in bits. + +'set serial baud N' + Set the baud rate for the remote serial I/O to N baud. The value + is used to set the speed of the serial port used for debugging + remote targets. + +'show serial baud' + Show the current speed of the remote connection. + +'set remotebreak' + If set to on, GDB sends a 'BREAK' signal to the remote when you + type 'Ctrl-c' to interrupt the program running on the remote. If + set to off, GDB sends the 'Ctrl-C' character instead. The default + is off, since most remote systems expect to see 'Ctrl-C' as the + interrupt signal. + +'show remotebreak' + Show whether GDB sends 'BREAK' or 'Ctrl-C' to interrupt the remote + program. + +'set remoteflow on' +'set remoteflow off' + Enable or disable hardware flow control ('RTS'/'CTS') on the serial + port used to communicate to the remote target. + +'show remoteflow' + Show the current setting of hardware flow control. + +'set remotelogbase BASE' + Set the base (a.k.a. radix) of logging serial protocol + communications to BASE. Supported values of BASE are: 'ascii', + 'octal', and 'hex'. The default is 'ascii'. + +'show remotelogbase' + Show the current setting of the radix for logging remote serial + protocol. + +'set remotelogfile FILE' + Record remote serial communications on the named FILE. The default + is not to record at all. + +'show remotelogfile.' + Show the current setting of the file name on which to record the + serial communications. + +'set remotetimeout NUM' + Set the timeout limit to wait for the remote target to respond to + NUM seconds. The default is 2 seconds. + +'show remotetimeout' + Show the current number of seconds to wait for the remote target + responses. + +'set remote hardware-watchpoint-limit LIMIT' +'set remote hardware-breakpoint-limit LIMIT' + Restrict GDB to using LIMIT remote hardware breakpoint or + watchpoints. A limit of -1, the default, is treated as unlimited. + +'set remote hardware-watchpoint-length-limit LIMIT' + Restrict GDB to using LIMIT bytes for the maximum length of a + remote hardware watchpoint. A limit of -1, the default, is treated + as unlimited. + +'show remote hardware-watchpoint-length-limit' + Show the current limit (in bytes) of the maximum length of a remote + hardware watchpoint. + +'set remote exec-file FILENAME' +'show remote exec-file' + Select the file used for 'run' with 'target extended-remote'. This + should be set to a filename valid on the target system. If it is + not set, the target will use a default filename (e.g. the last + program run). + +'set remote interrupt-sequence' + Allow the user to select one of 'Ctrl-C', a 'BREAK' or 'BREAK-g' as + the sequence to the remote target in order to interrupt the + execution. 'Ctrl-C' is a default. Some system prefers 'BREAK' + which is high level of serial line for some certain time. Linux + kernel prefers 'BREAK-g', a.k.a Magic SysRq g. It is 'BREAK' + signal followed by character 'g'. + +'show interrupt-sequence' + Show which of 'Ctrl-C', 'BREAK' or 'BREAK-g' is sent by GDB to + interrupt the remote program. 'BREAK-g' is BREAK signal followed + by 'g' and also known as Magic SysRq g. + +'set remote interrupt-on-connect' + Specify whether interrupt-sequence is sent to remote target when + GDB connects to it. This is mostly needed when you debug Linux + kernel. Linux kernel expects 'BREAK' followed by 'g' which is + known as Magic SysRq g in order to connect GDB. + +'show interrupt-on-connect' + Show whether interrupt-sequence is sent to remote target when GDB + connects to it. + +'set tcp auto-retry on' + Enable auto-retry for remote TCP connections. This is useful if + the remote debugging agent is launched in parallel with GDB; there + is a race condition because the agent may not become ready to + accept the connection before GDB attempts to connect. When + auto-retry is enabled, if the initial attempt to connect fails, GDB + reattempts to establish the connection using the timeout specified + by 'set tcp connect-timeout'. + +'set tcp auto-retry off' + Do not auto-retry failed TCP connections. + +'show tcp auto-retry' + Show the current auto-retry setting. + +'set tcp connect-timeout SECONDS' +'set tcp connect-timeout unlimited' + Set the timeout for establishing a TCP connection to the remote + target to SECONDS. The timeout affects both polling to retry + failed connections (enabled by 'set tcp auto-retry on') and waiting + for connections that are merely slow to complete, and represents an + approximate cumulative value. If SECONDS is 'unlimited', there is + no timeout and GDB will keep attempting to establish a connection + forever, unless interrupted with 'Ctrl-c'. The default is 15 + seconds. + +'show tcp connect-timeout' + Show the current connection timeout setting. + + The GDB remote protocol autodetects the packets supported by your +debugging stub. If you need to override the autodetection, you can use +these commands to enable or disable individual packets. Each packet can +be set to 'on' (the remote target supports this packet), 'off' (the +remote target does not support this packet), or 'auto' (detect remote +target support for this packet). They all default to 'auto'. For more +information about each packet, see *note Remote Protocol::. + + During normal use, you should not have to use any of these commands. +If you do, that may be a bug in your remote debugging stub, or a bug in +GDB. You may want to report the problem to the GDB developers. + + For each packet NAME, the command to enable or disable the packet is +'set remote NAME-packet'. The available settings are: + +Command Name Remote Packet Related Features + +'fetch-register' 'p' 'info registers' + +'set-register' 'P' 'set' + +'binary-download' 'X' 'load', 'set' + +'read-aux-vector' 'qXfer:auxv:read' 'info auxv' + +'symbol-lookup' 'qSymbol' Detecting + multiple threads + +'attach' 'vAttach' 'attach' + +'verbose-resume' 'vCont' Stepping or + resuming + multiple threads + +'run' 'vRun' 'run' + +'software-breakpoint''Z0' 'break' + +'hardware-breakpoint''Z1' 'hbreak' + +'write-watchpoint' 'Z2' 'watch' + +'read-watchpoint' 'Z3' 'rwatch' + +'access-watchpoint' 'Z4' 'awatch' + +'target-features' 'qXfer:features:read' 'set + architecture' + +'library-info' 'qXfer:libraries:read' 'info + sharedlibrary' + +'memory-map' 'qXfer:memory-map:read' 'info mem' + +'read-sdata-object' 'qXfer:sdata:read' 'print $_sdata' + +'read-spu-object' 'qXfer:spu:read' 'info spu' + +'write-spu-object' 'qXfer:spu:write' 'info spu' + +'read-siginfo-object''qXfer:siginfo:read' 'print + $_siginfo' + +'write-siginfo-object''qXfer:siginfo:write' 'set $_siginfo' + +'threads' 'qXfer:threads:read' 'info threads' + +'get-thread-local- 'qGetTLSAddr' Displaying +storage-address' '__thread' + variables + +'get-thread-information-block-address''qGetTIBAddr'Display + MS-Windows + Thread + Information + Block. + +'search-memory' 'qSearch:memory' 'find' + +'supported-packets' 'qSupported' Remote + communications + parameters + +'pass-signals' 'QPassSignals' 'handle SIGNAL' + +'program-signals' 'QProgramSignals' 'handle SIGNAL' + +'hostio-close-packet''vFile:close' 'remote get', + 'remote put' + +'hostio-open-packet' 'vFile:open' 'remote get', + 'remote put' + +'hostio-pread-packet''vFile:pread' 'remote get', + 'remote put' + +'hostio-pwrite-packet''vFile:pwrite' 'remote get', + 'remote put' + +'hostio-unlink-packet''vFile:unlink' 'remote delete' + +'hostio-readlink-packet''vFile:readlink' Host I/O + +'noack-packet' 'QStartNoAckMode' Packet + acknowledgment + +'osdata' 'qXfer:osdata:read' 'info os' + +'query-attached' 'qAttached' Querying remote + process attach + state. + +'trace-buffer-size' 'QTBuffer:size' 'set + trace-buffer-size' + +'trace-status' 'qTStatus' 'tstatus' + +'traceframe-info' 'qXfer:traceframe-info:read'Traceframe info + +'install-in-trace' 'InstallInTrace' Install + tracepoint in + tracing + +'disable-randomization''QDisableRandomization''set + disable-randomization' + +'conditional-breakpoints-packet''Z0 and Z1' 'Support for + target-side + breakpoint + condition + evaluation' + + +File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging + +20.5 Implementing a Remote Stub +=============================== + +The stub files provided with GDB implement the target side of the +communication protocol, and the GDB side is implemented in the GDB +source file 'remote.c'. Normally, you can simply allow these +subroutines to communicate, and ignore the details. (If you're +implementing your own stub file, you can still ignore the details: start +with one of the existing stub files. 'sparc-stub.c' is the best +organized, and therefore the easiest to read.) + + To debug a program running on another machine (the debugging "target" +machine), you must first arrange for all the usual prerequisites for the +program to run by itself. For example, for a C program, you need: + + 1. A startup routine to set up the C runtime environment; these + usually have a name like 'crt0'. The startup routine may be + supplied by your hardware supplier, or you may have to write your + own. + + 2. A C subroutine library to support your program's subroutine calls, + notably managing input and output. + + 3. A way of getting your program to the other machine--for example, a + download program. These are often supplied by the hardware + manufacturer, but you may have to write your own from hardware + documentation. + + The next step is to arrange for your program to use a serial port to +communicate with the machine where GDB is running (the "host" machine). +In general terms, the scheme looks like this: + +_On the host,_ + GDB already understands how to use this protocol; when everything + else is set up, you can simply use the 'target remote' command + (*note Specifying a Debugging Target: Targets.). + +_On the target,_ + you must link with your program a few special-purpose subroutines + that implement the GDB remote serial protocol. The file containing + these subroutines is called a "debugging stub". + + On certain remote targets, you can use an auxiliary program + 'gdbserver' instead of linking a stub into your program. *Note + Using the 'gdbserver' Program: Server, for details. + + The debugging stub is specific to the architecture of the remote +machine; for example, use 'sparc-stub.c' to debug programs on SPARC +boards. + + These working remote stubs are distributed with GDB: + +'i386-stub.c' + For Intel 386 and compatible architectures. + +'m68k-stub.c' + For Motorola 680x0 architectures. + +'sh-stub.c' + For Renesas SH architectures. + +'sparc-stub.c' + For SPARC architectures. + +'sparcl-stub.c' + For Fujitsu SPARCLITE architectures. + + The 'README' file in the GDB distribution may list other recently +added stubs. + +* Menu: + +* Stub Contents:: What the stub can do for you +* Bootstrapping:: What you must do for the stub +* Debug Session:: Putting it all together + + +File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub + +20.5.1 What the Stub Can Do for You +----------------------------------- + +The debugging stub for your architecture supplies these three +subroutines: + +'set_debug_traps' + This routine arranges for 'handle_exception' to run when your + program stops. You must call this subroutine explicitly in your + program's startup code. + +'handle_exception' + This is the central workhorse, but your program never calls it + explicitly--the setup code arranges for 'handle_exception' to run + when a trap is triggered. + + 'handle_exception' takes control when your program stops during + execution (for example, on a breakpoint), and mediates + communications with GDB on the host machine. This is where the + communications protocol is implemented; 'handle_exception' acts as + the GDB representative on the target machine. It begins by sending + summary information on the state of your program, then continues to + execute, retrieving and transmitting any information GDB needs, + until you execute a GDB command that makes your program resume; at + that point, 'handle_exception' returns control to your own code on + the target machine. + +'breakpoint' + Use this auxiliary subroutine to make your program contain a + breakpoint. Depending on the particular situation, this may be the + only way for GDB to get control. For instance, if your target + machine has some sort of interrupt button, you won't need to call + this; pressing the interrupt button transfers control to + 'handle_exception'--in effect, to GDB. On some machines, simply + receiving characters on the serial port may also trigger a trap; + again, in that situation, you don't need to call 'breakpoint' from + your own program--simply running 'target remote' from the host GDB + session gets control. + + Call 'breakpoint' if none of these is true, or if you simply want + to make certain your program stops at a predetermined point for the + start of your debugging session. + + +File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Stub + +20.5.2 What You Must Do for the Stub +------------------------------------ + +The debugging stubs that come with GDB are set up for a particular chip +architecture, but they have no information about the rest of your +debugging target machine. + + First of all you need to tell the stub how to communicate with the +serial port. + +'int getDebugChar()' + Write this subroutine to read a single character from the serial + port. It may be identical to 'getchar' for your target system; a + different name is used to allow you to distinguish the two if you + wish. + +'void putDebugChar(int)' + Write this subroutine to write a single character to the serial + port. It may be identical to 'putchar' for your target system; a + different name is used to allow you to distinguish the two if you + wish. + + If you want GDB to be able to stop your program while it is running, +you need to use an interrupt-driven serial driver, and arrange for it to +stop when it receives a '^C' ('\003', the control-C character). That is +the character which GDB uses to tell the remote system to stop. + + Getting the debugging target to return the proper status to GDB +probably requires changes to the standard stub; one quick and dirty way +is to just execute a breakpoint instruction (the "dirty" part is that +GDB reports a 'SIGTRAP' instead of a 'SIGINT'). + + Other routines you need to supply are: + +'void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' + Write this function to install EXCEPTION_ADDRESS in the exception + handling tables. You need to do this because the stub does not + have any way of knowing what the exception handling tables on your + target system are like (for example, the processor's table might be + in ROM, containing entries which point to a table in RAM). + EXCEPTION_NUMBER is the exception number which should be changed; + its meaning is architecture-dependent (for example, different + numbers might represent divide by zero, misaligned access, etc). + When this exception occurs, control should be transferred directly + to EXCEPTION_ADDRESS, and the processor state (stack, registers, + and so on) should be just as it is when a processor exception + occurs. So if you want to use a jump instruction to reach + EXCEPTION_ADDRESS, it should be a simple jump, not a jump to + subroutine. + + For the 386, EXCEPTION_ADDRESS should be installed as an interrupt + gate so that interrupts are masked while the handler runs. The + gate should be at privilege level 0 (the most privileged level). + The SPARC and 68k stubs are able to mask interrupts themselves + without help from 'exceptionHandler'. + +'void flush_i_cache()' + On SPARC and SPARCLITE only, write this subroutine to flush the + instruction cache, if any, on your target machine. If there is no + instruction cache, this subroutine may be a no-op. + + On target machines that have instruction caches, GDB requires this + function to make certain that the state of your program is stable. + +You must also make sure this library routine is available: + +'void *memset(void *, int, int)' + This is the standard library function 'memset' that sets an area of + memory to a known value. If you have one of the free versions of + 'libc.a', 'memset' can be found there; otherwise, you must either + obtain it from your hardware manufacturer, or write your own. + + If you do not use the GNU C compiler, you may need other standard +library subroutines as well; this varies from one stub to another, but +in general the stubs are likely to use any of the common library +subroutines which 'GCC' generates as inline code. + + +File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: Remote Stub + +20.5.3 Putting it All Together +------------------------------ + +In summary, when your program is ready to debug, you must follow these +steps. + + 1. Make sure you have defined the supporting low-level routines (*note + What You Must Do for the Stub: Bootstrapping.): + 'getDebugChar', 'putDebugChar', + 'flush_i_cache', 'memset', 'exceptionHandler'. + + 2. Insert these lines in your program's startup code, before the main + procedure is called: + + set_debug_traps(); + breakpoint(); + + On some machines, when a breakpoint trap is raised, the hardware + automatically makes the PC point to the instruction after the + breakpoint. If your machine doesn't do that, you may need to + adjust 'handle_exception' to arrange for it to return to the + instruction after the breakpoint on this first invocation, so that + your program doesn't keep hitting the initial breakpoint instead of + making progress. + + 3. For the 680x0 stub only, you need to provide a variable called + 'exceptionHook'. Normally you just use: + + void (*exceptionHook)() = 0; + + but if before calling 'set_debug_traps', you set it to point to a + function in your program, that function is called when 'GDB' + continues after stopping on a trap (for example, bus error). The + function indicated by 'exceptionHook' is called with one parameter: + an 'int' which is the exception number. + + 4. Compile and link together: your program, the GDB debugging stub for + your target architecture, and the supporting subroutines. + + 5. Make sure you have a serial connection between your target machine + and the GDB host, and identify the serial port on the host. + + 6. Download your program to your target machine (or get it there by + whatever means the manufacturer provides), and start it. + + 7. Start GDB on the host, and connect to the target (*note Connecting + to a Remote Target: Connecting.). + + +File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top + +21 Configuration-Specific Information +************************************* + +While nearly all GDB commands are available for all native and cross +versions of the debugger, there are some exceptions. This chapter +describes things that are only available in certain configurations. + + There are three major categories of configurations: native +configurations, where the host and target are the same, embedded +operating system configurations, which are usually the same for several +different processor architectures, and bare embedded processors, which +are quite different from each other. + +* Menu: + +* Native:: +* Embedded OS:: +* Embedded Processors:: +* Architectures:: + + +File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations + +21.1 Native +=========== + +This section describes details specific to particular native +configurations. + +* Menu: + +* HP-UX:: HP-UX +* BSD libkvm Interface:: Debugging BSD kernel memory images +* SVR4 Process Information:: SVR4 process information +* DJGPP Native:: Features specific to the DJGPP port +* Cygwin Native:: Features specific to the Cygwin port +* Hurd Native:: Features specific to GNU Hurd +* Darwin:: Features specific to Darwin + + +File: gdb.info, Node: HP-UX, Next: BSD libkvm Interface, Up: Native + +21.1.1 HP-UX +------------ + +On HP-UX systems, if you refer to a function or variable name that +begins with a dollar sign, GDB searches for a user or system name first, +before it searches for a convenience variable. + + +File: gdb.info, Node: BSD libkvm Interface, Next: SVR4 Process Information, Prev: HP-UX, Up: Native + +21.1.2 BSD libkvm Interface +--------------------------- + +BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory +interface that provides a uniform interface for accessing kernel virtual +memory images, including live systems and crash dumps. GDB uses this +interface to allow you to debug live kernels and kernel crash dumps on +many native BSD configurations. This is implemented as a special 'kvm' +debugging target. For debugging a live system, load the currently +running kernel into GDB and connect to the 'kvm' target: + + (gdb) target kvm + + For debugging crash dumps, provide the file name of the crash dump as +an argument: + + (gdb) target kvm /var/crash/bsd.0 + + Once connected to the 'kvm' target, the following commands are +available: + +'kvm pcb' + Set current context from the "Process Control Block" (PCB) address. + +'kvm proc' + Set current context from proc address. This command isn't + available on modern FreeBSD systems. + + +File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native + +21.1.3 SVR4 Process Information +------------------------------- + +Many versions of SVR4 and compatible systems provide a facility called +'/proc' that can be used to examine the image of a running process using +file-system subroutines. + + If GDB is configured for an operating system with this facility, the +command 'info proc' is available to report information about the process +running your program, or about any process running on your system. This +includes, as of this writing, GNU/Linux, OSF/1 (Digital Unix), Solaris, +and Irix, but not HP-UX, for example. + + This command may also work on core files that were created on a +system that has the '/proc' facility. + +'info proc' +'info proc PROCESS-ID' + Summarize available information about any running process. If a + process ID is specified by PROCESS-ID, display information about + that process; otherwise display information about the program being + debugged. The summary includes the debugged process ID, the + command line used to invoke it, its current working directory, and + its executable file's absolute file name. + + On some systems, PROCESS-ID can be of the form '[PID]/TID' which + specifies a certain thread ID within a process. If the optional + PID part is missing, it means a thread from the process being + debugged (the leading '/' still needs to be present, or else GDB + will interpret the number as a process ID rather than a thread ID). + +'info proc cmdline' + Show the original command line of the process. This command is + specific to GNU/Linux. + +'info proc cwd' + Show the current working directory of the process. This command is + specific to GNU/Linux. + +'info proc exe' + Show the name of executable of the process. This command is + specific to GNU/Linux. + +'info proc mappings' + Report the memory address space ranges accessible in the program, + with information on whether the process has read, write, or execute + access rights to each range. On GNU/Linux systems, each memory + range includes the object file which is mapped to that range, + instead of the memory access rights to that range. + +'info proc stat' +'info proc status' + These subcommands are specific to GNU/Linux systems. They show the + process-related information, including the user ID and group ID; + how many threads are there in the process; its virtual memory + usage; the signals that are pending, blocked, and ignored; its TTY; + its consumption of system and user time; its stack size; its 'nice' + value; etc. For more information, see the 'proc' man page (type + 'man 5 proc' from your shell prompt). + +'info proc all' + Show all the information about the process described under all of + the above 'info proc' subcommands. + +'set procfs-trace' + This command enables and disables tracing of 'procfs' API calls. + +'show procfs-trace' + Show the current state of 'procfs' API call tracing. + +'set procfs-file FILE' + Tell GDB to write 'procfs' API trace to the named FILE. GDB + appends the trace info to the previous contents of the file. The + default is to display the trace on the standard output. + +'show procfs-file' + Show the file to which 'procfs' API trace is written. + +'proc-trace-entry' +'proc-trace-exit' +'proc-untrace-entry' +'proc-untrace-exit' + These commands enable and disable tracing of entries into and exits + from the 'syscall' interface. + +'info pidlist' + For QNX Neutrino only, this command displays the list of all the + processes and all the threads within each process. + +'info meminfo' + For QNX Neutrino only, this command displays the list of all + mapinfos. + + +File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native + +21.1.4 Features for Debugging DJGPP Programs +-------------------------------------------- + +DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows. +DJGPP programs are 32-bit protected-mode programs that use the "DPMI" +(DOS Protected-Mode Interface) API to run on top of real-mode DOS +systems and their emulations. + + GDB supports native debugging of DJGPP programs, and defines a few +commands specific to the DJGPP port. This subsection describes those +commands. + +'info dos' + This is a prefix of DJGPP-specific commands which print information + about the target system and important OS structures. + +'info dos sysinfo' + This command displays assorted information about the underlying + platform: the CPU type and features, the OS version and flavor, the + DPMI version, and the available conventional and DPMI memory. + +'info dos gdt' +'info dos ldt' +'info dos idt' + These 3 commands display entries from, respectively, Global, Local, + and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor + tables are data structures which store a descriptor for each + segment that is currently in use. The segment's selector is an + index into a descriptor table; the table entry for that index holds + the descriptor's base address and limit, and its attributes and + access rights. + + A typical DJGPP program uses 3 segments: a code segment, a data + segment (used for both data and the stack), and a DOS segment + (which allows access to DOS/BIOS data structures and absolute + addresses in conventional memory). However, the DPMI host will + usually define additional segments in order to support the DPMI + environment. + + These commands allow to display entries from the descriptor tables. + Without an argument, all entries from the specified table are + displayed. An argument, which should be an integer expression, + means display a single entry whose index is given by the argument. + For example, here's a convenient way to display information about + the debugged program's data segment: + + (gdb) info dos ldt $ds + 0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up) + + This comes in handy when you want to see whether a pointer is + outside the data segment's limit (i.e. "garbled"). + +'info dos pde' +'info dos pte' + These two commands display entries from, respectively, the Page + Directory and the Page Tables. Page Directories and Page Tables + are data structures which control how virtual memory addresses are + mapped into physical addresses. A Page Table includes an entry for + every page of memory that is mapped into the program's address + space; there may be several Page Tables, each one holding up to + 4096 entries. A Page Directory has up to 4096 entries, one each + for every Page Table that is currently in use. + + Without an argument, 'info dos pde' displays the entire Page + Directory, and 'info dos pte' displays all the entries in all of + the Page Tables. An argument, an integer expression, given to the + 'info dos pde' command means display only that entry from the Page + Directory table. An argument given to the 'info dos pte' command + means display entries from a single Page Table, the one pointed to + by the specified entry in the Page Directory. + + These commands are useful when your program uses "DMA" (Direct + Memory Access), which needs physical addresses to program the DMA + controller. + + These commands are supported only with some DPMI servers. + +'info dos address-pte ADDR' + This command displays the Page Table entry for a specified linear + address. The argument ADDR is a linear address which should + already have the appropriate segment's base address added to it, + because this command accepts addresses which may belong to _any_ + segment. For example, here's how to display the Page Table entry + for the page where a variable 'i' is stored: + + (gdb) info dos address-pte __djgpp_base_address + (char *)&i + Page Table entry for address 0x11a00d30: + Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30 + + This says that 'i' is stored at offset '0xd30' from the page whose + physical base address is '0x02698000', and shows all the attributes + of that page. + + Note that you must cast the addresses of variables to a 'char *', + since otherwise the value of '__djgpp_base_address', the base + address of all variables and functions in a DJGPP program, will be + added using the rules of C pointer arithmetics: if 'i' is declared + an 'int', GDB will add 4 times the value of '__djgpp_base_address' + to the address of 'i'. + + Here's another example, it displays the Page Table entry for the + transfer buffer: + + (gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3) + Page Table entry for address 0x29110: + Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110 + + (The '+ 3' offset is because the transfer buffer's address is the + 3rd member of the '_go32_info_block' structure.) The output + clearly shows that this DPMI server maps the addresses in + conventional memory 1:1, i.e. the physical ('0x00029000' + '0x110') + and linear ('0x29110') addresses are identical. + + This command is supported only with some DPMI servers. + + In addition to native debugging, the DJGPP port supports remote +debugging via a serial data link. The following commands are specific +to remote serial debugging in the DJGPP port of GDB. + +'set com1base ADDR' + This command sets the base I/O port address of the 'COM1' serial + port. + +'set com1irq IRQ' + This command sets the "Interrupt Request" ('IRQ') line to use for + the 'COM1' serial port. + + There are similar commands 'set com2base', 'set com3irq', etc. for + setting the port address and the 'IRQ' lines for the other 3 COM + ports. + + The related commands 'show com1base', 'show com1irq' etc. display + the current settings of the base address and the 'IRQ' lines used + by the COM ports. + +'info serial' + This command prints the status of the 4 DOS serial ports. For each + port, it prints whether it's active or not, its I/O base address + and IRQ number, whether it uses a 16550-style FIFO, its baudrate, + and the counts of various errors encountered so far. + + +File: gdb.info, Node: Cygwin Native, Next: Hurd Native, Prev: DJGPP Native, Up: Native + +21.1.5 Features for Debugging MS Windows PE Executables +------------------------------------------------------- + +GDB supports native debugging of MS Windows programs, including DLLs +with and without symbolic debugging information. + + MS-Windows programs that call 'SetConsoleMode' to switch off the +special meaning of the 'Ctrl-C' keystroke cannot be interrupted by +typing 'C-c'. For this reason, GDB on MS-Windows supports 'C-' +as an alternative interrupt key sequence, which can be used to interrupt +the debuggee even if it ignores 'C-c'. + + There are various additional Cygwin-specific commands, described in +this section. Working with DLLs that have no debugging symbols is +described in *note Non-debug DLL Symbols::. + +'info w32' + This is a prefix of MS Windows-specific commands which print + information about the target system and important OS structures. + +'info w32 selector' + This command displays information returned by the Win32 API + 'GetThreadSelectorEntry' function. It takes an optional argument + that is evaluated to a long value to give the information about + this given selector. Without argument, this command displays + information about the six segment registers. + +'info w32 thread-information-block' + This command displays thread specific information stored in the + Thread Information Block (readable on the X86 CPU family using + '$fs' selector for 32-bit programs and '$gs' for 64-bit programs). + +'info dll' + This is a Cygwin-specific alias of 'info shared'. + +'dll-symbols' + This command loads symbols from a dll similarly to add-sym command + but without the need to specify a base address. + +'set cygwin-exceptions MODE' + If MODE is 'on', GDB will break on exceptions that happen inside + the Cygwin DLL. If MODE is 'off', GDB will delay recognition of + exceptions, and may ignore some exceptions which seem to be caused + by internal Cygwin DLL "bookkeeping". This option is meant + primarily for debugging the Cygwin DLL itself; the default value is + 'off' to avoid annoying GDB users with false 'SIGSEGV' signals. + +'show cygwin-exceptions' + Displays whether GDB will break on exceptions that happen inside + the Cygwin DLL itself. + +'set new-console MODE' + If MODE is 'on' the debuggee will be started in a new console on + next start. If MODE is 'off', the debuggee will be started in the + same console as the debugger. + +'show new-console' + Displays whether a new console is used when the debuggee is + started. + +'set new-group MODE' + This boolean value controls whether the debuggee should start a new + group or stay in the same group as the debugger. This affects the + way the Windows OS handles 'Ctrl-C'. + +'show new-group' + Displays current value of new-group boolean. + +'set debugevents' + This boolean value adds debug output concerning kernel events + related to the debuggee seen by the debugger. This includes events + that signal thread and process creation and exit, DLL loading and + unloading, console interrupts, and debugging messages produced by + the Windows 'OutputDebugString' API call. + +'set debugexec' + This boolean value adds debug output concerning execute events + (such as resume thread) seen by the debugger. + +'set debugexceptions' + This boolean value adds debug output concerning exceptions in the + debuggee seen by the debugger. + +'set debugmemory' + This boolean value adds debug output concerning debuggee memory + reads and writes by the debugger. + +'set shell' + This boolean values specifies whether the debuggee is called via a + shell or directly (default value is on). + +'show shell' + Displays if the debuggee will be started with a shell. + +* Menu: + +* Non-debug DLL Symbols:: Support for DLLs without debugging symbols + + +File: gdb.info, Node: Non-debug DLL Symbols, Up: Cygwin Native + +21.1.5.1 Support for DLLs without Debugging Symbols +................................................... + +Very often on windows, some of the DLLs that your program relies on do +not include symbolic debugging information (for example, +'kernel32.dll'). When GDB doesn't recognize any debugging symbols in a +DLL, it relies on the minimal amount of symbolic information contained +in the DLL's export table. This section describes working with such +symbols, known internally to GDB as "minimal symbols". + + Note that before the debugged program has started execution, no DLLs +will have been loaded. The easiest way around this problem is simply to +start the program -- either by setting a breakpoint or letting the +program run once to completion. It is also possible to force GDB to +load a particular DLL before starting the executable -- see the shared +library information in *note Files::, or the 'dll-symbols' command in +*note Cygwin Native::. Currently, explicitly loading symbols from a DLL +with no debugging information will cause the symbol names to be +duplicated in GDB's lookup table, which may adversely affect symbol +lookup performance. + +21.1.5.2 DLL Name Prefixes +.......................... + +In keeping with the naming conventions used by the Microsoft debugging +tools, DLL export symbols are made available with a prefix based on the +DLL name, for instance 'KERNEL32!CreateFileA'. The plain name is also +entered into the symbol table, so 'CreateFileA' is often sufficient. In +some cases there will be name clashes within a program (particularly if +the executable itself includes full debugging symbols) necessitating the +use of the fully qualified name when referring to the contents of the +DLL. Use single-quotes around the name to avoid the exclamation mark +("!") being interpreted as a language operator. + + Note that the internal name of the DLL may be all upper-case, even +though the file name of the DLL is lower-case, or vice-versa. Since +symbols within GDB are _case-sensitive_ this may cause some confusion. +If in doubt, try the 'info functions' and 'info variables' commands or +even 'maint print msymbols' (*note Symbols::). Here's an example: + + (gdb) info function CreateFileA + All functions matching regular expression "CreateFileA": + + Non-debugging symbols: + 0x77e885f4 CreateFileA + 0x77e885f4 KERNEL32!CreateFileA + + (gdb) info function ! + All functions matching regular expression "!": + + Non-debugging symbols: + 0x6100114c cygwin1!__assert + 0x61004034 cygwin1!_dll_crt0@0 + 0x61004240 cygwin1!dll_crt0(per_process *) + [etc...] + +21.1.5.3 Working with Minimal Symbols +..................................... + +Symbols extracted from a DLL's export table do not contain very much +type information. All that GDB can do is guess whether a symbol refers +to a function or variable depending on the linker section that contains +the symbol. Also note that the actual contents of the memory contained +in a DLL are not available unless the program is running. This means +that you cannot examine the contents of a variable or disassemble a +function within a DLL without a running program. + + Variables are generally treated as pointers and dereferenced +automatically. For this reason, it is often necessary to prefix a +variable name with the address-of operator ("&") and provide explicit +type information in the command. Here's an example of the type of +problem: + + (gdb) print 'cygwin1!__argv' + $1 = 268572168 + + (gdb) x 'cygwin1!__argv' + 0x10021610: "\230y\"" + + And two possible solutions: + + (gdb) print ((char **)'cygwin1!__argv')[0] + $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" + + (gdb) x/2x &'cygwin1!__argv' + 0x610c0aa8 : 0x10021608 0x00000000 + (gdb) x/x 0x10021608 + 0x10021608: 0x0022fd98 + (gdb) x/s 0x0022fd98 + 0x22fd98: "/cygdrive/c/mydirectory/myprogram" + + Setting a break point within a DLL is possible even before the +program starts execution. However, under these circumstances, GDB can't +examine the initial instructions of the function in order to skip the +function's frame set-up code. You can work around this by using "*&" to +set the breakpoint at a raw memory address: + + (gdb) break *&'python22!PyOS_Readline' + Breakpoint 1 at 0x1e04eff0 + + The author of these extensions is not entirely convinced that setting +a break point within a shared DLL like 'kernel32.dll' is completely +safe. + + +File: gdb.info, Node: Hurd Native, Next: Darwin, Prev: Cygwin Native, Up: Native + +21.1.6 Commands Specific to GNU Hurd Systems +-------------------------------------------- + +This subsection describes GDB commands specific to the GNU Hurd native +debugging. + +'set signals' +'set sigs' + This command toggles the state of inferior signal interception by + GDB. Mach exceptions, such as breakpoint traps, are not affected + by this command. 'sigs' is a shorthand alias for 'signals'. + +'show signals' +'show sigs' + Show the current state of intercepting inferior's signals. + +'set signal-thread' +'set sigthread' + This command tells GDB which thread is the 'libc' signal thread. + That thread is run when a signal is delivered to a running process. + 'set sigthread' is the shorthand alias of 'set signal-thread'. + +'show signal-thread' +'show sigthread' + These two commands show which thread will run when the inferior is + delivered a signal. + +'set stopped' + This commands tells GDB that the inferior process is stopped, as + with the 'SIGSTOP' signal. The stopped process can be continued by + delivering a signal to it. + +'show stopped' + This command shows whether GDB thinks the debuggee is stopped. + +'set exceptions' + Use this command to turn off trapping of exceptions in the + inferior. When exception trapping is off, neither breakpoints nor + single-stepping will work. To restore the default, set exception + trapping on. + +'show exceptions' + Show the current state of trapping exceptions in the inferior. + +'set task pause' + This command toggles task suspension when GDB has control. Setting + it to on takes effect immediately, and the task is suspended + whenever GDB gets control. Setting it to off will take effect the + next time the inferior is continued. If this option is set to off, + you can use 'set thread default pause on' or 'set thread pause on' + (see below) to pause individual threads. + +'show task pause' + Show the current state of task suspension. + +'set task detach-suspend-count' + This command sets the suspend count the task will be left with when + GDB detaches from it. + +'show task detach-suspend-count' + Show the suspend count the task will be left with when detaching. + +'set task exception-port' +'set task excp' + This command sets the task exception port to which GDB will forward + exceptions. The argument should be the value of the "send rights" + of the task. 'set task excp' is a shorthand alias. + +'set noninvasive' + This command switches GDB to a mode that is the least invasive as + far as interfering with the inferior is concerned. This is the + same as using 'set task pause', 'set exceptions', and 'set signals' + to values opposite to the defaults. + +'info send-rights' +'info receive-rights' +'info port-rights' +'info port-sets' +'info dead-names' +'info ports' +'info psets' + These commands display information about, respectively, send + rights, receive rights, port rights, port sets, and dead names of a + task. There are also shorthand aliases: 'info ports' for 'info + port-rights' and 'info psets' for 'info port-sets'. + +'set thread pause' + This command toggles current thread suspension when GDB has + control. Setting it to on takes effect immediately, and the + current thread is suspended whenever GDB gets control. Setting it + to off will take effect the next time the inferior is continued. + Normally, this command has no effect, since when GDB has control, + the whole task is suspended. However, if you used 'set task pause + off' (see above), this command comes in handy to suspend only the + current thread. + +'show thread pause' + This command shows the state of current thread suspension. + +'set thread run' + This command sets whether the current thread is allowed to run. + +'show thread run' + Show whether the current thread is allowed to run. + +'set thread detach-suspend-count' + This command sets the suspend count GDB will leave on a thread when + detaching. This number is relative to the suspend count found by + GDB when it notices the thread; use 'set thread + takeover-suspend-count' to force it to an absolute value. + +'show thread detach-suspend-count' + Show the suspend count GDB will leave on the thread when detaching. + +'set thread exception-port' +'set thread excp' + Set the thread exception port to which to forward exceptions. This + overrides the port set by 'set task exception-port' (see above). + 'set thread excp' is the shorthand alias. + +'set thread takeover-suspend-count' + Normally, GDB's thread suspend counts are relative to the value GDB + finds when it notices each thread. This command changes the + suspend counts to be absolute instead. + +'set thread default' +'show thread default' + Each of the above 'set thread' commands has a 'set thread default' + counterpart (e.g., 'set thread default pause', 'set thread default + exception-port', etc.). The 'thread default' variety of commands + sets the default thread properties for all threads; you can then + change the properties of individual threads with the non-default + commands. + + +File: gdb.info, Node: Darwin, Prev: Hurd Native, Up: Native + +21.1.7 Darwin +------------- + +GDB provides the following commands specific to the Darwin target: + +'set debug darwin NUM' + When set to a non zero value, enables debugging messages specific + to the Darwin support. Higher values produce more verbose output. + +'show debug darwin' + Show the current state of Darwin messages. + +'set debug mach-o NUM' + When set to a non zero value, enables debugging messages while GDB + is reading Darwin object files. ("Mach-O" is the file format used + on Darwin for object and executable files.) Higher values produce + more verbose output. This is a command to diagnose problems + internal to GDB and should not be needed in normal usage. + +'show debug mach-o' + Show the current state of Mach-O file messages. + +'set mach-exceptions on' +'set mach-exceptions off' + On Darwin, faults are first reported as a Mach exception and are + then mapped to a Posix signal. Use this command to turn on + trapping of Mach exceptions in the inferior. This might be + sometimes useful to better understand the cause of a fault. The + default is off. + +'show mach-exceptions' + Show the current state of exceptions trapping. + + +File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations + +21.2 Embedded Operating Systems +=============================== + +This section describes configurations involving the debugging of +embedded operating systems that are available for several different +architectures. + +* Menu: + +* VxWorks:: Using GDB with VxWorks + + GDB includes the ability to debug programs running on various +real-time operating systems. + + +File: gdb.info, Node: VxWorks, Up: Embedded OS + +21.2.1 Using GDB with VxWorks +----------------------------- + +'target vxworks MACHINENAME' + A VxWorks system, attached via TCP/IP. The argument MACHINENAME is + the target system's machine name or IP address. + + On VxWorks, 'load' links FILENAME dynamically on the current target +system as well as adding its symbols in GDB. + + GDB enables developers to spawn and debug tasks running on networked +VxWorks targets from a Unix host. Already-running tasks spawned from +the VxWorks shell can also be debugged. GDB uses code that runs on both +the Unix host and on the VxWorks target. The program 'gdb' is installed +and executed on the Unix host. (It may be installed with the name +'vxgdb', to distinguish it from a GDB for debugging programs on the host +itself.) + +'VxWorks-timeout ARGS' + All VxWorks-based targets now support the option 'vxworks-timeout'. + This option is set by the user, and ARGS represents the number of + seconds GDB waits for responses to rpc's. You might use this if + your VxWorks target is a slow software simulator or is on the far + side of a thin network line. + + The following information on connecting to VxWorks was current when +this manual was produced; newer releases of VxWorks may use revised +procedures. + + To use GDB with VxWorks, you must rebuild your VxWorks kernel to +include the remote debugging interface routines in the VxWorks library +'rdb.a'. To do this, define 'INCLUDE_RDB' in the VxWorks configuration +file 'configAll.h' and rebuild your VxWorks kernel. The resulting +kernel contains 'rdb.a', and spawns the source debugging task 'tRdbTask' +when VxWorks is booted. For more information on configuring and +remaking VxWorks, see the manufacturer's manual. + + Once you have included 'rdb.a' in your VxWorks system image and set +your Unix execution search path to find GDB, you are ready to run GDB. +From your Unix host, run 'gdb' (or 'vxgdb', depending on your +installation). + + GDB comes up showing the prompt: + + (vxgdb) + +* Menu: + +* VxWorks Connection:: Connecting to VxWorks +* VxWorks Download:: VxWorks download +* VxWorks Attach:: Running tasks + + +File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks + +21.2.1.1 Connecting to VxWorks +.............................. + +The GDB command 'target' lets you connect to a VxWorks target on the +network. To connect to a target whose host name is "'tt'", type: + + (vxgdb) target vxworks tt + + GDB displays messages like these: + + Attaching remote machine across net... + Connected to tt. + + GDB then attempts to read the symbol tables of any object modules +loaded into the VxWorks target since it was last booted. GDB locates +these files by searching the directories listed in the command search +path (*note Your Program's Environment: Environment.); if it fails to +find an object file, it displays a message such as: + + prog.o: No such file or directory. + + When this happens, add the appropriate directory to the search path +with the GDB command 'path', and execute the 'target' command again. + + +File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks + +21.2.1.2 VxWorks Download +......................... + +If you have connected to the VxWorks target and you want to debug an +object that has not yet been loaded, you can use the GDB 'load' command +to download a file from Unix to VxWorks incrementally. The object file +given as an argument to the 'load' command is actually opened twice: +first by the VxWorks target in order to download the code, then by GDB +in order to read the symbol table. This can lead to problems if the +current working directories on the two systems differ. If both systems +have NFS mounted the same filesystems, you can avoid these problems by +using absolute paths. Otherwise, it is simplest to set the working +directory on both systems to the directory in which the object file +resides, and then to reference the file by its name, without any path. +For instance, a program 'prog.o' may reside in 'VXPATH/vw/demo/rdb' in +VxWorks and in 'HOSTPATH/vw/demo/rdb' on the host. To load this +program, type this on VxWorks: + + -> cd "VXPATH/vw/demo/rdb" + +Then, in GDB, type: + + (vxgdb) cd HOSTPATH/vw/demo/rdb + (vxgdb) load prog.o + + GDB displays a response similar to this: + + Reading symbol data from wherever/vw/demo/rdb/prog.o... done. + + You can also use the 'load' command to reload an object module after +editing and recompiling the corresponding source file. Note that this +makes GDB delete all currently-defined breakpoints, auto-displays, and +convenience variables, and to clear the value history. (This is +necessary in order to preserve the integrity of debugger's data +structures that reference the target system's symbol table.) + + +File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks + +21.2.1.3 Running Tasks +...................... + +You can also attach to an existing task using the 'attach' command as +follows: + + (vxgdb) attach TASK + +where TASK is the VxWorks hexadecimal task ID. The task can be running +or suspended when you attach to it. Running tasks are suspended at the +time of attachment. + + +File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations + +21.3 Embedded Processors +======================== + +This section goes into details specific to particular embedded +configurations. + + Whenever a specific embedded processor has a simulator, GDB allows to +send an arbitrary command to the simulator. + +'sim COMMAND' + Send an arbitrary COMMAND string to the simulator. Consult the + documentation for the specific simulator in use for information + about acceptable commands. + +* Menu: + +* ARM:: ARM RDI +* M32R/D:: Renesas M32R/D +* M68K:: Motorola M68K +* MicroBlaze:: Xilinx MicroBlaze +* MIPS Embedded:: MIPS Embedded +* PowerPC Embedded:: PowerPC Embedded +* PA:: HP PA Embedded +* Sparclet:: Tsqware Sparclet +* Sparclite:: Fujitsu Sparclite +* Z8000:: Zilog Z8000 +* AVR:: Atmel AVR +* CRIS:: CRIS +* Super-H:: Renesas Super-H + + +File: gdb.info, Node: ARM, Next: M32R/D, Up: Embedded Processors + +21.3.1 ARM +---------- + +'target rdi DEV' + ARM Angel monitor, via RDI library interface to ADP protocol. You + may use this target to communicate with both boards running the + Angel monitor, or with the EmbeddedICE JTAG debug device. + +'target rdp DEV' + ARM Demon monitor. + + GDB provides the following ARM-specific commands: + +'set arm disassembler' + This commands selects from a list of disassembly styles. The + '"std"' style is the standard style. + +'show arm disassembler' + Show the current disassembly style. + +'set arm apcs32' + This command toggles ARM operation mode between 32-bit and 26-bit. + +'show arm apcs32' + Display the current usage of the ARM 32-bit mode. + +'set arm fpu FPUTYPE' + This command sets the ARM floating-point unit (FPU) type. The + argument FPUTYPE can be one of these: + + 'auto' + Determine the FPU type by querying the OS ABI. + 'softfpa' + Software FPU, with mixed-endian doubles on little-endian ARM + processors. + 'fpa' + GCC-compiled FPA co-processor. + 'softvfp' + Software FPU with pure-endian doubles. + 'vfp' + VFP co-processor. + +'show arm fpu' + Show the current type of the FPU. + +'set arm abi' + This command forces GDB to use the specified ABI. + +'show arm abi' + Show the currently used ABI. + +'set arm fallback-mode (arm|thumb|auto)' + GDB uses the symbol table, when available, to determine whether + instructions are ARM or Thumb. This command controls GDB's default + behavior when the symbol table is not available. The default is + 'auto', which causes GDB to use the current execution mode (from + the 'T' bit in the 'CPSR' register). + +'show arm fallback-mode' + Show the current fallback instruction mode. + +'set arm force-mode (arm|thumb|auto)' + This command overrides use of the symbol table to determine whether + instructions are ARM or Thumb. The default is 'auto', which causes + GDB to use the symbol table and then the setting of 'set arm + fallback-mode'. + +'show arm force-mode' + Show the current forced instruction mode. + +'set debug arm' + Toggle whether to display ARM-specific debugging messages from the + ARM target support subsystem. + +'show debug arm' + Show whether ARM-specific debugging messages are enabled. + + The following commands are available when an ARM target is debugged +using the RDI interface: + +'rdilogfile [FILE]' + Set the filename for the ADP (Angel Debugger Protocol) packet log. + With an argument, sets the log file to the specified FILE. With no + argument, show the current log file name. The default log file is + 'rdi.log'. + +'rdilogenable [ARG]' + Control logging of ADP packets. With an argument of 1 or '"yes"' + enables logging, with an argument 0 or '"no"' disables it. With no + arguments displays the current setting. When logging is enabled, + ADP packets exchanged between GDB and the RDI target device are + logged to a file. + +'set rdiromatzero' + Tell GDB whether the target has ROM at address 0. If on, vector + catching is disabled, so that zero address can be used. If off + (the default), vector catching is enabled. For this command to + take effect, it needs to be invoked prior to the 'target rdi' + command. + +'show rdiromatzero' + Show the current setting of ROM at zero address. + +'set rdiheartbeat' + Enable or disable RDI heartbeat packets. It is not recommended to + turn on this option, since it confuses ARM and EPI JTAG interface, + as well as the Angel monitor. + +'show rdiheartbeat' + Show the setting of RDI heartbeat packets. + +'target sim [SIMARGS] ...' + The GDB ARM simulator accepts the following optional arguments. + + '--swi-support=TYPE' + Tell the simulator which SWI interfaces to support. TYPE may + be a comma separated list of the following values. The + default value is 'all'. + + 'none' + 'demon' + 'angel' + 'redboot' + 'all' + + +File: gdb.info, Node: M32R/D, Next: M68K, Prev: ARM, Up: Embedded Processors + +21.3.2 Renesas M32R/D and M32R/SDI +---------------------------------- + +'target m32r DEV' + Renesas M32R/D ROM monitor. + +'target m32rsdi DEV' + Renesas M32R SDI server, connected via parallel port to the board. + + The following GDB commands are specific to the M32R monitor: + +'set download-path PATH' + Set the default path for finding downloadable SREC files. + +'show download-path' + Show the default path for downloadable SREC files. + +'set board-address ADDR' + Set the IP address for the M32R-EVA target board. + +'show board-address' + Show the current IP address of the target board. + +'set server-address ADDR' + Set the IP address for the download server, which is the GDB's host + machine. + +'show server-address' + Display the IP address of the download server. + +'upload [FILE]' + Upload the specified SREC FILE via the monitor's Ethernet upload + capability. If no FILE argument is given, the current executable + file is uploaded. + +'tload [FILE]' + Test the 'upload' command. + + The following commands are available for M32R/SDI: + +'sdireset' + This command resets the SDI connection. + +'sdistatus' + This command shows the SDI connection status. + +'debug_chaos' + Instructs the remote that M32R/Chaos debugging is to be used. + +'use_debug_dma' + Instructs the remote to use the DEBUG_DMA method of accessing + memory. + +'use_mon_code' + Instructs the remote to use the MON_CODE method of accessing + memory. + +'use_ib_break' + Instructs the remote to set breakpoints by IB break. + +'use_dbt_break' + Instructs the remote to set breakpoints by DBT. + + +File: gdb.info, Node: M68K, Next: MicroBlaze, Prev: M32R/D, Up: Embedded Processors + +21.3.3 M68k +----------- + +The Motorola m68k configuration includes ColdFire support, and a target +command for the following ROM monitor. + +'target dbug DEV' + dBUG ROM monitor for Motorola ColdFire. + + +File: gdb.info, Node: MicroBlaze, Next: MIPS Embedded, Prev: M68K, Up: Embedded Processors + +21.3.4 MicroBlaze +----------------- + +The MicroBlaze is a soft-core processor supported on various Xilinx +FPGAs, such as Spartan or Virtex series. Boards with these processors +usually have JTAG ports which connect to a host system running the +Xilinx Embedded Development Kit (EDK) or Software Development Kit (SDK). +This host system is used to download the configuration bitstream to the +target FPGA. The Xilinx Microprocessor Debugger (XMD) program +communicates with the target board using the JTAG interface and presents +a 'gdbserver' interface to the board. By default 'xmd' uses port +'1234'. (While it is possible to change this default port, it requires +the use of undocumented 'xmd' commands. Contact Xilinx support if you +need to do this.) + + Use these GDB commands to connect to the MicroBlaze target processor. + +'target remote :1234' + Use this command to connect to the target if you are running GDB on + the same system as 'xmd'. + +'target remote XMD-HOST:1234' + Use this command to connect to the target if it is connected to + 'xmd' running on a different system named XMD-HOST. + +'load' + Use this command to download a program to the MicroBlaze target. + +'set debug microblaze N' + Enable MicroBlaze-specific debugging messages if non-zero. + +'show debug microblaze N' + Show MicroBlaze-specific debugging level. + + +File: gdb.info, Node: MIPS Embedded, Next: PowerPC Embedded, Prev: MicroBlaze, Up: Embedded Processors + +21.3.5 MIPS Embedded +-------------------- + +GDB can use the MIPS remote debugging protocol to talk to a MIPS board +attached to a serial line. This is available when you configure GDB +with '--target=mips-elf'. + + Use these GDB commands to specify the connection to your target +board: + +'target mips PORT' + To run a program on the board, start up 'gdb' with the name of your + program as the argument. To connect to the board, use the command + 'target mips PORT', where PORT is the name of the serial port + connected to the board. If the program has not already been + downloaded to the board, you may use the 'load' command to download + it. You can then use all the usual GDB commands. + + For example, this sequence connects to the target board through a + serial port, and loads and runs a program called PROG through the + debugger: + + host$ gdb PROG + GDB is free software and ... + (gdb) target mips /dev/ttyb + (gdb) load PROG + (gdb) run + +'target mips HOSTNAME:PORTNUMBER' + On some GDB host configurations, you can specify a TCP connection + (for instance, to a serial line managed by a terminal concentrator) + instead of a serial port, using the syntax 'HOSTNAME:PORTNUMBER'. + +'target pmon PORT' + PMON ROM monitor. + +'target ddb PORT' + NEC's DDB variant of PMON for Vr4300. + +'target lsi PORT' + LSI variant of PMON. + +'target r3900 DEV' + Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. + +'target array DEV' + Array Tech LSI33K RAID controller board. + +GDB also supports these special commands for MIPS targets: + +'set mipsfpu double' +'set mipsfpu single' +'set mipsfpu none' +'set mipsfpu auto' +'show mipsfpu' + If your target board does not support the MIPS floating point + coprocessor, you should use the command 'set mipsfpu none' (if you + need this, you may wish to put the command in your GDB init file). + This tells GDB how to find the return value of functions which + return floating point values. It also allows GDB to avoid saving + the floating point registers when calling functions on the board. + If you are using a floating point coprocessor with only single + precision floating point support, as on the R4650 processor, use + the command 'set mipsfpu single'. The default double precision + floating point coprocessor may be selected using 'set mipsfpu + double'. + + In previous versions the only choices were double precision or no + floating point, so 'set mipsfpu on' will select double precision + and 'set mipsfpu off' will select no floating point. + + As usual, you can inquire about the 'mipsfpu' variable with 'show + mipsfpu'. + +'set timeout SECONDS' +'set retransmit-timeout SECONDS' +'show timeout' +'show retransmit-timeout' + You can control the timeout used while waiting for a packet, in the + MIPS remote protocol, with the 'set timeout SECONDS' command. The + default is 5 seconds. Similarly, you can control the timeout used + while waiting for an acknowledgment of a packet with the 'set + retransmit-timeout SECONDS' command. The default is 3 seconds. + You can inspect both values with 'show timeout' and 'show + retransmit-timeout'. (These commands are _only_ available when GDB + is configured for '--target=mips-elf'.) + + The timeout set by 'set timeout' does not apply when GDB is waiting + for your program to stop. In that case, GDB waits forever because + it has no way of knowing how long the program is going to run + before stopping. + +'set syn-garbage-limit NUM' + Limit the maximum number of characters GDB should ignore when it + tries to synchronize with the remote target. The default is 10 + characters. Setting the limit to -1 means there's no limit. + +'show syn-garbage-limit' + Show the current limit on the number of characters to ignore when + trying to synchronize with the remote system. + +'set monitor-prompt PROMPT' + Tell GDB to expect the specified PROMPT string from the remote + monitor. The default depends on the target: + pmon target + 'PMON' + ddb target + 'NEC010' + lsi target + 'PMON>' + +'show monitor-prompt' + Show the current strings GDB expects as the prompt from the remote + monitor. + +'set monitor-warnings' + Enable or disable monitor warnings about hardware breakpoints. + This has effect only for the 'lsi' target. When on, GDB will + display warning messages whose codes are returned by the 'lsi' PMON + monitor for breakpoint commands. + +'show monitor-warnings' + Show the current setting of printing monitor warnings. + +'pmon COMMAND' + This command allows sending an arbitrary COMMAND string to the + monitor. The monitor must be in debug mode for this to work. + + +File: gdb.info, Node: PowerPC Embedded, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors + +21.3.6 PowerPC Embedded +----------------------- + +GDB supports using the DVC (Data Value Compare) register to implement in +hardware simple hardware watchpoint conditions of the form: + + (gdb) watch ADDRESS|VARIABLE \ + if ADDRESS|VARIABLE == CONSTANT EXPRESSION + + The DVC register will be automatically used when GDB detects such +pattern in a condition expression, and the created watchpoint uses one +debug register (either the 'exact-watchpoints' option is on and the +variable is scalar, or the variable has a length of one byte). This +feature is available in native GDB running on a Linux kernel version +2.6.34 or newer. + + When running on PowerPC embedded processors, GDB automatically uses +ranged hardware watchpoints, unless the 'exact-watchpoints' option is +on, in which case watchpoints using only one debug register are created +when watching variables of scalar types. + + You can create an artificial array to watch an arbitrary memory +region using one of the following commands (*note Expressions::): + + (gdb) watch *((char *) ADDRESS)@LENGTH + (gdb) watch {char[LENGTH]} ADDRESS + + PowerPC embedded processors support masked watchpoints. See the +discussion about the 'mask' argument in *note Set Watchpoints::. + + PowerPC embedded processors support hardware accelerated "ranged +breakpoints". A ranged breakpoint stops execution of the inferior +whenever it executes an instruction at any address within the range it +specifies. To set a ranged breakpoint in GDB, use the 'break-range' +command. + + GDB provides the following PowerPC-specific commands: + +'break-range START-LOCATION, END-LOCATION' + Set a breakpoint for an address range. START-LOCATION and + END-LOCATION can specify a function name, a line number, an offset + of lines from the current line or from the start location, or an + address of an instruction (see *note Specify Location::, for a list + of all the possible ways to specify a LOCATION.) The breakpoint + will stop execution of the inferior whenever it executes an + instruction at any address within the specified range, (including + START-LOCATION and END-LOCATION.) + +'set powerpc soft-float' +'show powerpc soft-float' + Force GDB to use (or not use) a software floating point calling + convention. By default, GDB selects the calling convention based + on the selected architecture and the provided executable file. + +'set powerpc vector-abi' +'show powerpc vector-abi' + Force GDB to use the specified calling convention for vector + arguments and return values. The valid options are 'auto'; + 'generic', to avoid vector registers even if they are present; + 'altivec', to use AltiVec registers; and 'spe' to use SPE + registers. By default, GDB selects the calling convention based on + the selected architecture and the provided executable file. + +'set powerpc exact-watchpoints' +'show powerpc exact-watchpoints' + Allow GDB to use only one debug register when watching a variable + of scalar type, thus assuming that the variable is accessed through + the address of its first byte. + +'target dink32 DEV' + DINK32 ROM monitor. + +'target ppcbug DEV' +'target ppcbug1 DEV' + PPCBUG ROM monitor for PowerPC. + +'target sds DEV' + SDS monitor, running on a PowerPC board (such as Motorola's ADS). + + The following commands specific to the SDS protocol are supported by +GDB: + +'set sdstimeout NSEC' + Set the timeout for SDS protocol reads to be NSEC seconds. The + default is 2 seconds. + +'show sdstimeout' + Show the current value of the SDS timeout. + +'sds COMMAND' + Send the specified COMMAND string to the SDS monitor. + + +File: gdb.info, Node: PA, Next: Sparclet, Prev: PowerPC Embedded, Up: Embedded Processors + +21.3.7 HP PA Embedded +--------------------- + +'target op50n DEV' + OP50N monitor, running on an OKI HPPA board. + +'target w89k DEV' + W89K monitor, running on a Winbond HPPA board. + + +File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PA, Up: Embedded Processors + +21.3.8 Tsqware Sparclet +----------------------- + +GDB enables developers to debug tasks running on Sparclet targets from a +Unix host. GDB uses code that runs on both the Unix host and on the +Sparclet target. The program 'gdb' is installed and executed on the +Unix host. + +'remotetimeout ARGS' + GDB supports the option 'remotetimeout'. This option is set by the + user, and ARGS represents the number of seconds GDB waits for + responses. + + When compiling for debugging, include the options '-g' to get debug +information and '-Ttext' to relocate the program to where you wish to +load it on the target. You may also want to add the options '-n' or +'-N' in order to reduce the size of the sections. Example: + + sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N + + You can use 'objdump' to verify that the addresses are what you +intended: + + sparclet-aout-objdump --headers --syms prog + + Once you have set your Unix execution search path to find GDB, you +are ready to run GDB. From your Unix host, run 'gdb' (or +'sparclet-aout-gdb', depending on your installation). + + GDB comes up showing the prompt: + + (gdbslet) + +* Menu: + +* Sparclet File:: Setting the file to debug +* Sparclet Connection:: Connecting to Sparclet +* Sparclet Download:: Sparclet download +* Sparclet Execution:: Running and debugging + + +File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet + +21.3.8.1 Setting File to Debug +.............................. + +The GDB command 'file' lets you choose with program to debug. + + (gdbslet) file prog + + GDB then attempts to read the symbol table of 'prog'. GDB locates +the file by searching the directories listed in the command search path. +If the file was compiled with debug information (option '-g'), source +files will be searched as well. GDB locates the source files by +searching the directories listed in the directory search path (*note +Your Program's Environment: Environment.). If it fails to find a file, +it displays a message such as: + + prog: No such file or directory. + + When this happens, add the appropriate directories to the search +paths with the GDB commands 'path' and 'dir', and execute the 'target' +command again. + + +File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet + +21.3.8.2 Connecting to Sparclet +............................... + +The GDB command 'target' lets you connect to a Sparclet target. To +connect to a target on serial port "'ttya'", type: + + (gdbslet) target sparclet /dev/ttya + Remote target sparclet connected to /dev/ttya + main () at ../prog.c:3 + + GDB displays messages like these: + + Connected to ttya. + + +File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet + +21.3.8.3 Sparclet Download +.......................... + +Once connected to the Sparclet target, you can use the GDB 'load' +command to download the file from the host to the target. The file name +and load offset should be given as arguments to the 'load' command. +Since the file format is aout, the program must be loaded to the +starting address. You can use 'objdump' to find out what this value is. +The load offset is an offset which is added to the VMA (virtual memory +address) of each of the file's sections. For instance, if the program +'prog' was linked to text address 0x1201000, with data at 0x12010160 and +bss at 0x12010170, in GDB, type: + + (gdbslet) load prog 0x12010000 + Loading section .text, size 0xdb0 vma 0x12010000 + + If the code is loaded at a different address then what the program +was linked to, you may need to use the 'section' and 'add-symbol-file' +commands to tell GDB where to map the symbol table. + + +File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet + +21.3.8.4 Running and Debugging +.............................. + +You can now begin debugging the task using GDB's execution control +commands, 'b', 'step', 'run', etc. See the GDB manual for the list of +commands. + + (gdbslet) b main + Breakpoint 1 at 0x12010000: file prog.c, line 3. + (gdbslet) run + Starting program: prog + Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 + 3 char *symarg = 0; + (gdbslet) step + 4 char *execarg = "hello!"; + (gdbslet) + + +File: gdb.info, Node: Sparclite, Next: Z8000, Prev: Sparclet, Up: Embedded Processors + +21.3.9 Fujitsu Sparclite +------------------------ + +'target sparclite DEV' + Fujitsu sparclite boards, used only for the purpose of loading. + You must use an additional command to debug the program. For + example: target remote DEV using GDB standard remote protocol. + + +File: gdb.info, Node: Z8000, Next: AVR, Prev: Sparclite, Up: Embedded Processors + +21.3.10 Zilog Z8000 +------------------- + +When configured for debugging Zilog Z8000 targets, GDB includes a Z8000 +simulator. + + For the Z8000 family, 'target sim' simulates either the Z8002 (the +unsegmented variant of the Z8000 architecture) or the Z8001 (the +segmented variant). The simulator recognizes which architecture is +appropriate by inspecting the object code. + +'target sim ARGS' + Debug programs on a simulated CPU. If the simulator supports setup + options, specify them via ARGS. + +After specifying this target, you can debug programs for the simulated +CPU in the same style as programs for your host computer; use the 'file' +command to load a new program image, the 'run' command to run your +program, and so on. + + As well as making available all the usual machine registers (*note +Registers: Registers.), the Z8000 simulator provides three additional +items of information as specially named registers: + +'cycles' + Counts clock-ticks in the simulator. + +'insts' + Counts instructions run in the simulator. + +'time' + Execution time in 60ths of a second. + + You can refer to these values in GDB expressions with the usual +conventions; for example, 'b fputc if $cycles>5000' sets a conditional +breakpoint that suspends only after at least 5000 simulated clock ticks. + + +File: gdb.info, Node: AVR, Next: CRIS, Prev: Z8000, Up: Embedded Processors + +21.3.11 Atmel AVR +----------------- + +When configured for debugging the Atmel AVR, GDB supports the following +AVR-specific commands: + +'info io_registers' + This command displays information about the AVR I/O registers. For + each register, GDB prints its number and value. + + +File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors + +21.3.12 CRIS +------------ + +When configured for debugging CRIS, GDB provides the following +CRIS-specific commands: + +'set cris-version VER' + Set the current CRIS version to VER, either '10' or '32'. The CRIS + version affects register names and sizes. This command is useful + in case autodetection of the CRIS version fails. + +'show cris-version' + Show the current CRIS version. + +'set cris-dwarf2-cfi' + Set the usage of DWARF-2 CFI for CRIS debugging. The default is + 'on'. Change to 'off' when using 'gcc-cris' whose version is below + 'R59'. + +'show cris-dwarf2-cfi' + Show the current state of using DWARF-2 CFI. + +'set cris-mode MODE' + Set the current CRIS mode to MODE. It should only be changed when + debugging in guru mode, in which case it should be set to 'guru' + (the default is 'normal'). + +'show cris-mode' + Show the current CRIS mode. + + +File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors + +21.3.13 Renesas Super-H +----------------------- + +For the Renesas Super-H processor, GDB provides these commands: + +'set sh calling-convention CONVENTION' + Set the calling-convention used when calling functions from GDB. + Allowed values are 'gcc', which is the default setting, and + 'renesas'. With the 'gcc' setting, functions are called using the + GCC calling convention. If the DWARF-2 information of the called + function specifies that the function follows the Renesas calling + convention, the function is called using the Renesas calling + convention. If the calling convention is set to 'renesas', the + Renesas calling convention is always used, regardless of the + DWARF-2 information. This can be used to override the default of + 'gcc' if debug information is missing, or the compiler does not + emit the DWARF-2 calling convention entry for a function. + +'show sh calling-convention' + Show the current calling convention setting. + + +File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations + +21.4 Architectures +================== + +This section describes characteristics of architectures that affect all +uses of GDB with the architecture, both native and cross. + +* Menu: + +* AArch64:: +* i386:: +* Alpha:: +* MIPS:: +* HPPA:: HP PA architecture +* SPU:: Cell Broadband Engine SPU architecture +* PowerPC:: +* Nios II:: + + +File: gdb.info, Node: AArch64, Next: i386, Up: Architectures + +21.4.1 AArch64 +-------------- + +When GDB is debugging the AArch64 architecture, it provides the +following special commands: + +'set debug aarch64' + This command determines whether AArch64 architecture-specific + debugging messages are to be displayed. + +'show debug aarch64' + Show whether AArch64 debugging messages are displayed. + + +File: gdb.info, Node: i386, Next: Alpha, Prev: AArch64, Up: Architectures + +21.4.2 x86 Architecture-specific Issues +--------------------------------------- + +'set struct-convention MODE' + Set the convention used by the inferior to return 'struct's and + 'union's from functions to MODE. Possible values of MODE are + '"pcc"', '"reg"', and '"default"' (the default). '"default"' or + '"pcc"' means that 'struct's are returned on the stack, while + '"reg"' means that a 'struct' or a 'union' whose size is 1, 2, 4, + or 8 bytes will be returned in a register. + +'show struct-convention' + Show the current setting of the convention to return 'struct's from + functions. + +21.4.2.1 Intel(R) "Memory Protection Extensions" (MPX). +....................................................... + +Memory Protection Extension (MPX) adds the bound registers 'BND0' (1) +through 'BND3'. Bound registers store a pair of 64-bit values which are +the lower bound and upper bound. Bounds are effective addresses or +memory locations. The upper bounds are architecturally represented in +1's complement form. A bound having lower bound = 0, and upper bound = +0 (1's complement of all bits set) will allow access to the entire +address space. + + 'BND0' through 'BND3' are represented in GDB as 'bnd0raw' through +'bnd3raw'. Pseudo registers 'bnd0' through 'bnd3' display the upper +bound performing the complement of one operation on the upper bound +value, i.e. when upper bound in 'bnd0raw' is 0 in the GDB 'bnd0' it will +be '0xfff...'. In this sense it can also be noted that the upper bounds +are inclusive. + + As an example, assume that the register BND0 holds bounds for a +pointer having access allowed for the range between 0x32 and 0x71. The +values present on bnd0raw and bnd registers are presented as follows: + + bnd0raw = {0x32, 0xffffffff8e} + bnd0 = {lbound = 0x32, ubound = 0x71} : size 64 + + This way the raw value can be accessed via bnd0raw...bnd3raw. Any +change on bnd0...bnd3 or bnd0raw...bnd3raw is reflect on its +counterpart. When the bnd0...bnd3 registers are displayed via Python, +the display includes the memory size, in bits, accessible to the +pointer. + + ---------- Footnotes ---------- + + (1) The register named with capital letters represent the +architecture registers. + + +File: gdb.info, Node: Alpha, Next: MIPS, Prev: i386, Up: Architectures + +21.4.3 Alpha +------------ + +See the following section. + + +File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures + +21.4.4 MIPS +----------- + +Alpha- and MIPS-based computers use an unusual stack frame, which +sometimes requires GDB to search backward in the object code to find the +beginning of a function. + + To improve response time (especially for embedded applications, where +GDB may be restricted to a slow serial line for this search) you may +want to limit the size of this search, using one of these commands: + +'set heuristic-fence-post LIMIT' + Restrict GDB to examining at most LIMIT bytes in its search for the + beginning of a function. A value of 0 (the default) means there is + no limit. However, except for 0, the larger the limit the more + bytes 'heuristic-fence-post' must search and therefore the longer + it takes to run. You should only need to use this command when + debugging a stripped executable. + +'show heuristic-fence-post' + Display the current limit. + +These commands are available _only_ when GDB is configured for debugging +programs on Alpha or MIPS processors. + + Several MIPS-specific commands are available when debugging MIPS +programs: + +'set mips abi ARG' + Tell GDB which MIPS ABI is used by the inferior. Possible values + of ARG are: + + 'auto' + The default ABI associated with the current binary (this is + the default). + 'o32' + 'o64' + 'n32' + 'n64' + 'eabi32' + 'eabi64' + +'show mips abi' + Show the MIPS ABI used by GDB to debug the inferior. + +'set mips compression ARG' + Tell GDB which MIPS compressed ISA (Instruction Set Architecture) + encoding is used by the inferior. GDB uses this for code + disassembly and other internal interpretation purposes. This + setting is only referred to when no executable has been associated + with the debugging session or the executable does not provide + information about the encoding it uses. Otherwise this setting is + automatically updated from information provided by the executable. + + Possible values of ARG are 'mips16' and 'micromips'. The default + compressed ISA encoding is 'mips16', as executables containing + MIPS16 code frequently are not identified as such. + + This setting is "sticky"; that is, it retains its value across + debugging sessions until reset either explicitly with this command + or implicitly from an executable. + + The compiler and/or assembler typically add symbol table + annotations to identify functions compiled for the MIPS16 or + microMIPS ISAs. If these function-scope annotations are present, + GDB uses them in preference to the global compressed ISA encoding + setting. + +'show mips compression' + Show the MIPS compressed ISA encoding used by GDB to debug the + inferior. + +'set mipsfpu' +'show mipsfpu' + *Note set mipsfpu: MIPS Embedded. + +'set mips mask-address ARG' + This command determines whether the most-significant 32 bits of + 64-bit MIPS addresses are masked off. The argument ARG can be + 'on', 'off', or 'auto'. The latter is the default setting, which + lets GDB determine the correct value. + +'show mips mask-address' + Show whether the upper 32 bits of MIPS addresses are masked off or + not. + +'set remote-mips64-transfers-32bit-regs' + This command controls compatibility with 64-bit MIPS targets that + transfer data in 32-bit quantities. If you have an old MIPS 64 + target that transfers 32 bits for some registers, like SR and FSR, + and 64 bits for other registers, set this option to 'on'. + +'show remote-mips64-transfers-32bit-regs' + Show the current setting of compatibility with older MIPS 64 + targets. + +'set debug mips' + This command turns on and off debugging messages for the + MIPS-specific target code in GDB. + +'show debug mips' + Show the current setting of MIPS debugging messages. + + +File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures + +21.4.5 HPPA +----------- + +When GDB is debugging the HP PA architecture, it provides the following +special commands: + +'set debug hppa' + This command determines whether HPPA architecture-specific + debugging messages are to be displayed. + +'show debug hppa' + Show whether HPPA debugging messages are displayed. + +'maint print unwind ADDRESS' + This command displays the contents of the unwind table entry at the + given ADDRESS. + + +File: gdb.info, Node: SPU, Next: PowerPC, Prev: HPPA, Up: Architectures + +21.4.6 Cell Broadband Engine SPU architecture +--------------------------------------------- + +When GDB is debugging the Cell Broadband Engine SPU architecture, it +provides the following special commands: + +'info spu event' + Display SPU event facility status. Shows current event mask and + pending event status. + +'info spu signal' + Display SPU signal notification facility status. Shows pending + signal-control word and signal notification mode of both signal + notification channels. + +'info spu mailbox' + Display SPU mailbox facility status. Shows all pending entries, in + order of processing, in each of the SPU Write Outbound, SPU Write + Outbound Interrupt, and SPU Read Inbound mailboxes. + +'info spu dma' + Display MFC DMA status. Shows all pending commands in the MFC DMA + queue. For each entry, opcode, tag, class IDs, effective and local + store addresses and transfer size are shown. + +'info spu proxydma' + Display MFC Proxy-DMA status. Shows all pending commands in the + MFC Proxy-DMA queue. For each entry, opcode, tag, class IDs, + effective and local store addresses and transfer size are shown. + + When GDB is debugging a combined PowerPC/SPU application on the Cell +Broadband Engine, it provides in addition the following special +commands: + +'set spu stop-on-load ARG' + Set whether to stop for new SPE threads. When set to 'on', GDB + will give control to the user when a new SPE thread enters its + 'main' function. The default is 'off'. + +'show spu stop-on-load' + Show whether to stop for new SPE threads. + +'set spu auto-flush-cache ARG' + Set whether to automatically flush the software-managed cache. + When set to 'on', GDB will automatically cause the SPE + software-managed cache to be flushed whenever SPE execution stops. + This provides a consistent view of PowerPC memory that is accessed + via the cache. If an application does not use the software-managed + cache, this option has no effect. + +'show spu auto-flush-cache' + Show whether to automatically flush the software-managed cache. + + +File: gdb.info, Node: PowerPC, Next: Nios II, Prev: SPU, Up: Architectures + +21.4.7 PowerPC +-------------- + +When GDB is debugging the PowerPC architecture, it provides a set of +pseudo-registers to enable inspection of 128-bit wide Decimal Floating +Point numbers stored in the floating point registers. These values must +be stored in two consecutive registers, always starting at an even +register like 'f0' or 'f2'. + + The pseudo-registers go from '$dl0' through '$dl15', and are formed +by joining the even/odd register pairs 'f0' and 'f1' for '$dl0', 'f2' +and 'f3' for '$dl1' and so on. + + For POWER7 processors, GDB provides a set of pseudo-registers, the +64-bit wide Extended Floating Point Registers ('f32' through 'f63'). + + +File: gdb.info, Node: Nios II, Prev: PowerPC, Up: Architectures + +21.4.8 Nios II +-------------- + +When GDB is debugging the Nios II architecture, it provides the +following special commands: + +'set debug nios2' + This command turns on and off debugging messages for the Nios II + target code in GDB. + +'show debug nios2' + Show the current setting of Nios II debugging messages. + + +File: gdb.info, Node: Controlling GDB, Next: Extending GDB, Prev: Configurations, Up: Top + +22 Controlling GDB +****************** + +You can alter the way GDB interacts with you by using the 'set' command. +For commands controlling how GDB displays data, see *note Print +Settings: Print Settings. Other settings are described here. + +* Menu: + +* Prompt:: Prompt +* Editing:: Command editing +* Command History:: Command history +* Screen Size:: Screen size +* Numbers:: Numbers +* ABI:: Configuring the current ABI +* Auto-loading:: Automatically loading associated files +* Messages/Warnings:: Optional warnings and messages +* Debugging Output:: Optional messages about internal happenings +* Other Misc Settings:: Other Miscellaneous Settings + + +File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB + +22.1 Prompt +=========== + +GDB indicates its readiness to read a command by printing a string +called the "prompt". This string is normally '(gdb)'. You can change +the prompt string with the 'set prompt' command. For instance, when +debugging GDB with GDB, it is useful to change the prompt in one of the +GDB sessions so that you can always tell which one you are talking to. + + _Note:_ 'set prompt' does not add a space for you after the prompt +you set. This allows you to set a prompt which ends in a space or a +prompt that does not. + +'set prompt NEWPROMPT' + Directs GDB to use NEWPROMPT as its prompt string henceforth. + +'show prompt' + Prints a line of the form: 'Gdb's prompt is: YOUR-PROMPT' + + Versions of GDB that ship with Python scripting enabled have prompt +extensions. The commands for interacting with these extensions are: + +'set extended-prompt PROMPT' + Set an extended prompt that allows for substitutions. *Note + gdb.prompt::, for a list of escape sequences that can be used for + substitution. Any escape sequences specified as part of the prompt + string are replaced with the corresponding strings each time the + prompt is displayed. + + For example: + + set extended-prompt Current working directory: \w (gdb) + + Note that when an extended-prompt is set, it takes control of the + PROMPT_HOOK hook. *Note prompt_hook::, for further information. + +'show extended-prompt' + Prints the extended prompt. Any escape sequences specified as part + of the prompt string with 'set extended-prompt', are replaced with + the corresponding strings each time the prompt is displayed. + + +File: gdb.info, Node: Editing, Next: Command History, Prev: Prompt, Up: Controlling GDB + +22.2 Command Editing +==================== + +GDB reads its input commands via the "Readline" interface. This GNU +library provides consistent behavior for programs which provide a +command line interface to the user. Advantages are GNU Emacs-style or +"vi"-style inline editing of commands, 'csh'-like history substitution, +and a storage and recall of command history across debugging sessions. + + You may control the behavior of command line editing in GDB with the +command 'set'. + +'set editing' +'set editing on' + Enable command line editing (enabled by default). + +'set editing off' + Disable command line editing. + +'show editing' + Show whether command line editing is enabled. + + *Note Command Line Editing::, for more details about the Readline +interface. Users unfamiliar with GNU Emacs or 'vi' are encouraged to +read that chapter. + + +File: gdb.info, Node: Command History, Next: Screen Size, Prev: Editing, Up: Controlling GDB + +22.3 Command History +==================== + +GDB can keep track of the commands you type during your debugging +sessions, so that you can be certain of precisely what happened. Use +these commands to manage the GDB command history facility. + + GDB uses the GNU History library, a part of the Readline package, to +provide the history facility. *Note Using History Interactively::, for +the detailed description of the History library. + + To issue a command to GDB without affecting certain aspects of the +state which is seen by users, prefix it with 'server ' (*note Server +Prefix::). This means that this command will not affect the command +history, nor will it affect GDB's notion of which command to repeat if + is pressed on a line by itself. + + The server prefix does not affect the recording of values into the +value history; to print a value without recording it into the value +history, use the 'output' command instead of the 'print' command. + + Here is the description of GDB commands related to command history. + +'set history filename FNAME' + Set the name of the GDB command history file to FNAME. This is the + file where GDB reads an initial command history list, and where it + writes the command history from this session when it exits. You + can access this list through history expansion or through the + history command editing characters listed below. This file + defaults to the value of the environment variable 'GDBHISTFILE', or + to './.gdb_history' ('./_gdb_history' on MS-DOS) if this variable + is not set. + +'set history save' +'set history save on' + Record command history in a file, whose name may be specified with + the 'set history filename' command. By default, this option is + disabled. + +'set history save off' + Stop recording command history in a file. + +'set history size SIZE' +'set history size unlimited' + Set the number of commands which GDB keeps in its history list. + This defaults to the value of the environment variable 'HISTSIZE', + or to 256 if this variable is not set. If SIZE is 'unlimited', the + number of commands GDB keeps in the history list is unlimited. + + History expansion assigns special meaning to the character '!'. +*Note Event Designators::, for more details. + + Since '!' is also the logical not operator in C, history expansion is +off by default. If you decide to enable history expansion with the 'set +history expansion on' command, you may sometimes need to follow '!' +(when it is used as logical not, in an expression) with a space or a tab +to prevent it from being expanded. The readline history facilities do +not attempt substitution on the strings '!=' and '!(', even when history +expansion is enabled. + + The commands to control history expansion are: + +'set history expansion on' +'set history expansion' + Enable history expansion. History expansion is off by default. + +'set history expansion off' + Disable history expansion. + +'show history' +'show history filename' +'show history save' +'show history size' +'show history expansion' + These commands display the state of the GDB history parameters. + 'show history' by itself displays all four states. + +'show commands' + Display the last ten commands in the command history. + +'show commands N' + Print ten commands centered on command number N. + +'show commands +' + Print ten commands just after the commands last printed. + + +File: gdb.info, Node: Screen Size, Next: Numbers, Prev: Command History, Up: Controlling GDB + +22.4 Screen Size +================ + +Certain commands to GDB may produce large amounts of information output +to the screen. To help you read all of it, GDB pauses and asks you for +input at the end of each page of output. Type when you want to +continue the output, or 'q' to discard the remaining output. Also, the +screen width setting determines when to wrap lines of output. Depending +on what is being printed, GDB tries to break the line at a readable +place, rather than simply letting it overflow onto the following line. + + Normally GDB knows the size of the screen from the terminal driver +software. For example, on Unix GDB uses the termcap data base together +with the value of the 'TERM' environment variable and the 'stty rows' +and 'stty cols' settings. If this is not correct, you can override it +with the 'set height' and 'set width' commands: + +'set height LPP' +'set height unlimited' +'show height' +'set width CPL' +'set width unlimited' +'show width' + These 'set' commands specify a screen height of LPP lines and a + screen width of CPL characters. The associated 'show' commands + display the current settings. + + If you specify a height of either 'unlimited' or zero lines, GDB + does not pause during output no matter how long the output is. + This is useful if output is to a file or to an editor buffer. + + Likewise, you can specify 'set width unlimited' or 'set width 0' to + prevent GDB from wrapping its output. + +'set pagination on' +'set pagination off' + Turn the output pagination on or off; the default is on. Turning + pagination off is the alternative to 'set height unlimited'. Note + that running GDB with the '--batch' option (*note -batch: Mode + Options.) also automatically disables pagination. + +'show pagination' + Show the current pagination mode. + + +File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB + +22.5 Numbers +============ + +You can always enter numbers in octal, decimal, or hexadecimal in GDB by +the usual conventions: octal numbers begin with '0', decimal numbers end +with '.', and hexadecimal numbers begin with '0x'. Numbers that neither +begin with '0' or '0x', nor end with a '.' are, by default, entered in +base 10; likewise, the default display for numbers--when no particular +format is specified--is base 10. You can change the default base for +both input and output with the commands described below. + +'set input-radix BASE' + Set the default base for numeric input. Supported choices for BASE + are decimal 8, 10, or 16. BASE must itself be specified either + unambiguously or using the current input radix; for example, any of + + set input-radix 012 + set input-radix 10. + set input-radix 0xa + + sets the input base to decimal. On the other hand, 'set + input-radix 10' leaves the input radix unchanged, no matter what it + was, since '10', being without any leading or trailing signs of its + base, is interpreted in the current radix. Thus, if the current + radix is 16, '10' is interpreted in hex, i.e. as 16 decimal, which + doesn't change the radix. + +'set output-radix BASE' + Set the default base for numeric display. Supported choices for + BASE are decimal 8, 10, or 16. BASE must itself be specified + either unambiguously or using the current input radix. + +'show input-radix' + Display the current default base for numeric input. + +'show output-radix' + Display the current default base for numeric display. + +'set radix [BASE]' +'show radix' + These commands set and show the default base for both input and + output of numbers. 'set radix' sets the radix of input and output + to the same base; without an argument, it resets the radix back to + its default value of 10. + + +File: gdb.info, Node: ABI, Next: Auto-loading, Prev: Numbers, Up: Controlling GDB + +22.6 Configuring the Current ABI +================================ + +GDB can determine the "ABI" (Application Binary Interface) of your +application automatically. However, sometimes you need to override its +conclusions. Use these commands to manage GDB's view of the current +ABI. + + One GDB configuration can debug binaries for multiple operating +system targets, either via remote debugging or native emulation. GDB +will autodetect the "OS ABI" (Operating System ABI) in use, but you can +override its conclusion using the 'set osabi' command. One example +where this is useful is in debugging of binaries which use an alternate +C library (e.g. UCLIBC for GNU/Linux) which does not have the same +identifying marks that the standard C library for your platform +provides. + + When GDB is debugging the AArch64 architecture, it provides a +"Newlib" OS ABI. This is useful for handling 'setjmp' and 'longjmp' when +debugging binaries that use the NEWLIB C library. The "Newlib" OS ABI +can be selected by 'set osabi Newlib'. + +'show osabi' + Show the OS ABI currently in use. + +'set osabi' + With no argument, show the list of registered available OS ABI's. + +'set osabi ABI' + Set the current OS ABI to ABI. + + Generally, the way that an argument of type 'float' is passed to a +function depends on whether the function is prototyped. For a +prototyped (i.e. ANSI/ISO style) function, 'float' arguments are passed +unchanged, according to the architecture's convention for 'float'. For +unprototyped (i.e. K&R style) functions, 'float' arguments are first +promoted to type 'double' and then passed. + + Unfortunately, some forms of debug information do not reliably +indicate whether a function is prototyped. If GDB calls a function that +is not marked as prototyped, it consults 'set coerce-float-to-double'. + +'set coerce-float-to-double' +'set coerce-float-to-double on' + Arguments of type 'float' will be promoted to 'double' when passed + to an unprototyped function. This is the default setting. + +'set coerce-float-to-double off' + Arguments of type 'float' will be passed directly to unprototyped + functions. + +'show coerce-float-to-double' + Show the current setting of promoting 'float' to 'double'. + + GDB needs to know the ABI used for your program's C++ objects. The +correct C++ ABI depends on which C++ compiler was used to build your +application. GDB only fully supports programs with a single C++ ABI; if +your program contains code using multiple C++ ABI's or if GDB can not +identify your program's ABI correctly, you can tell GDB which ABI to +use. Currently supported ABI's include "gnu-v2", for 'g++' versions +before 3.0, "gnu-v3", for 'g++' versions 3.0 and later, and "hpaCC" for +the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or +"gnu-v3" ABI's as well. The default setting is "auto". + +'show cp-abi' + Show the C++ ABI currently in use. + +'set cp-abi' + With no argument, show the list of supported C++ ABI's. + +'set cp-abi ABI' +'set cp-abi auto' + Set the current C++ ABI to ABI, or return to automatic detection. + + +File: gdb.info, Node: Auto-loading, Next: Messages/Warnings, Prev: ABI, Up: Controlling GDB + +22.7 Automatically loading associated files +=========================================== + +GDB sometimes reads files with commands and settings automatically, +without being explicitly told so by the user. We call this feature +"auto-loading". While auto-loading is useful for automatically adapting +GDB to the needs of your project, it can sometimes produce unexpected +results or introduce security risks (e.g., if the file comes from +untrusted sources). + +* Menu: + +* Init File in the Current Directory:: 'set/show/info auto-load local-gdbinit' +* libthread_db.so.1 file:: 'set/show/info auto-load libthread-db' + +* Auto-loading safe path:: 'set/show/info auto-load safe-path' +* Auto-loading verbose mode:: 'set/show debug auto-load' + + There are various kinds of files GDB can automatically load. In +addition to these files, GDB supports auto-loading code written in +various extension languages. *Note Auto-loading extensions::. + + Note that loading of these associated files (including the local +'.gdbinit' file) requires accordingly configured 'auto-load safe-path' +(*note Auto-loading safe path::). + + For these reasons, GDB includes commands and options to let you +control when to auto-load files and which files should be auto-loaded. + +'set auto-load off' + Globally disable loading of all auto-loaded files. You may want to + use this command with the '-iex' option (*note Option + -init-eval-command::) such as: + $ gdb -iex "set auto-load off" untrusted-executable corefile + + Be aware that system init file (*note System-wide configuration::) + and init files from your home directory (*note Home Directory Init + File::) still get read (as they come from generally trusted + directories). To prevent GDB from auto-loading even those init + files, use the '-nx' option (*note Mode Options::), in addition to + 'set auto-load no'. + +'show auto-load' + Show whether auto-loading of each specific 'auto-load' file(s) is + enabled or disabled. + + (gdb) show auto-load + gdb-scripts: Auto-loading of canned sequences of commands scripts is on. + libthread-db: Auto-loading of inferior specific libthread_db is on. + local-gdbinit: Auto-loading of .gdbinit script from current directory + is on. + python-scripts: Auto-loading of Python scripts is on. + safe-path: List of directories from which it is safe to auto-load files + is $debugdir:$datadir/auto-load. + scripts-directory: List of directories from which to load auto-loaded scripts + is $debugdir:$datadir/auto-load. + +'info auto-load' + Print whether each specific 'auto-load' file(s) have been + auto-loaded or not. + + (gdb) info auto-load + gdb-scripts: + Loaded Script + Yes /home/user/gdb/gdb-gdb.gdb + libthread-db: No auto-loaded libthread-db. + local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been + loaded. + python-scripts: + Loaded Script + Yes /home/user/gdb/gdb-gdb.py + + These are GDB control commands for the auto-loading: + +*Note set auto-load off::. Disable auto-loading globally. +*Note show auto-load::. Show setting of all kinds of + files. +*Note info auto-load::. Show state of all kinds of files. +*Note set auto-load gdb-scripts::. Control for GDB command scripts. +*Note show auto-load Show setting of GDB command +gdb-scripts::. scripts. +*Note info auto-load Show state of GDB command scripts. +gdb-scripts::. +*Note set auto-load Control for GDB Python scripts. +python-scripts::. +*Note show auto-load Show setting of GDB Python +python-scripts::. scripts. +*Note info auto-load Show state of GDB Python scripts. +python-scripts::. +*Note set auto-load Control for GDB auto-loaded +scripts-directory::. scripts location. +*Note show auto-load Show GDB auto-loaded scripts +scripts-directory::. location. +*Note set auto-load Control for init file in the +local-gdbinit::. current directory. +*Note show auto-load Show setting of init file in the +local-gdbinit::. current directory. +*Note info auto-load Show state of init file in the +local-gdbinit::. current directory. +*Note set auto-load Control for thread debugging +libthread-db::. library. +*Note show auto-load Show setting of thread debugging +libthread-db::. library. +*Note info auto-load Show state of thread debugging +libthread-db::. library. +*Note set auto-load safe-path::. Control directories trusted for + automatic loading. +*Note show auto-load safe-path::. Show directories trusted for + automatic loading. +*Note add-auto-load-safe-path::. Add directory trusted for + automatic loading. + + +File: gdb.info, Node: Init File in the Current Directory, Next: libthread_db.so.1 file, Up: Auto-loading + +22.7.1 Automatically loading init file in the current directory +--------------------------------------------------------------- + +By default, GDB reads and executes the canned sequences of commands from +init file (if any) in the current working directory, see *note Init File +in the Current Directory during Startup::. + + Note that loading of this local '.gdbinit' file also requires +accordingly configured 'auto-load safe-path' (*note Auto-loading safe +path::). + +'set auto-load local-gdbinit [on|off]' + Enable or disable the auto-loading of canned sequences of commands + (*note Sequences::) found in init file in the current directory. + +'show auto-load local-gdbinit' + Show whether auto-loading of canned sequences of commands from init + file in the current directory is enabled or disabled. + +'info auto-load local-gdbinit' + Print whether canned sequences of commands from init file in the + current directory have been auto-loaded. + + +File: gdb.info, Node: libthread_db.so.1 file, Next: Auto-loading safe path, Prev: Init File in the Current Directory, Up: Auto-loading + +22.7.2 Automatically loading thread debugging library +----------------------------------------------------- + +This feature is currently present only on GNU/Linux native hosts. + + GDB reads in some cases thread debugging library from places specific +to the inferior (*note set libthread-db-search-path::). + + The special 'libthread-db-search-path' entry '$sdir' is processed +without checking this 'set auto-load libthread-db' switch as system +libraries have to be trusted in general. In all other cases of +'libthread-db-search-path' entries GDB checks first if 'set auto-load +libthread-db' is enabled before trying to open such thread debugging +library. + + Note that loading of this debugging library also requires accordingly +configured 'auto-load safe-path' (*note Auto-loading safe path::). + +'set auto-load libthread-db [on|off]' + Enable or disable the auto-loading of inferior specific thread + debugging library. + +'show auto-load libthread-db' + Show whether auto-loading of inferior specific thread debugging + library is enabled or disabled. + +'info auto-load libthread-db' + Print the list of all loaded inferior specific thread debugging + libraries and for each such library print list of inferior PIDs + using it. + + +File: gdb.info, Node: Auto-loading safe path, Next: Auto-loading verbose mode, Prev: libthread_db.so.1 file, Up: Auto-loading + +22.7.3 Security restriction for auto-loading +-------------------------------------------- + +As the files of inferior can come from untrusted source (such as +submitted by an application user) GDB does not always load any files +automatically. GDB provides the 'set auto-load safe-path' setting to +list directories trusted for loading files not explicitly requested by +user. Each directory can also be a shell wildcard pattern. + + If the path is not set properly you will see a warning and the file +will not get loaded: + + $ ./gdb -q ./gdb + Reading symbols from /home/user/gdb/gdb...done. + warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been + declined by your `auto-load safe-path' set + to "$debugdir:$datadir/auto-load". + warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been + declined by your `auto-load safe-path' set + to "$debugdir:$datadir/auto-load". + +To instruct GDB to go ahead and use the init files anyway, invoke GDB +like this: + + $ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb + + The list of trusted directories is controlled by the following +commands: + +'set auto-load safe-path [DIRECTORIES]' + Set the list of directories (and their subdirectories) trusted for + automatic loading and execution of scripts. You can also enter a + specific trusted file. Each directory can also be a shell wildcard + pattern; wildcards do not match directory separator - see + 'FNM_PATHNAME' for system function 'fnmatch' (*note fnmatch: + (libc)Wildcard Matching.). If you omit DIRECTORIES, 'auto-load + safe-path' will be reset to its default value as specified during + GDB compilation. + + The list of directories uses path separator (':' on GNU and Unix + systems, ';' on MS-Windows and MS-DOS) to separate directories, + similarly to the 'PATH' environment variable. + +'show auto-load safe-path' + Show the list of directories trusted for automatic loading and + execution of scripts. + +'add-auto-load-safe-path' + Add an entry (or list of entries) the list of directories trusted + for automatic loading and execution of scripts. Multiple entries + may be delimited by the host platform path separator in use. + + This variable defaults to what '--with-auto-load-dir' has been +configured to (*note with-auto-load-dir::). '$debugdir' and '$datadir' +substitution applies the same as for *note set auto-load +scripts-directory::. The default 'set auto-load safe-path' value can be +also overriden by GDB configuration option '--with-auto-load-safe-path'. + + Setting this variable to '/' disables this security protection, +corresponding GDB configuration option is +'--without-auto-load-safe-path'. This variable is supposed to be set to +the system directories writable by the system superuser only. Users can +add their source directories in init files in their home directories +(*note Home Directory Init File::). See also deprecated init file in +the current directory (*note Init File in the Current Directory during +Startup::). + + To force GDB to load the files it declined to load in the previous +example, you could use one of the following ways: + +'~/.gdbinit': 'add-auto-load-safe-path ~/src/gdb' + Specify this trusted directory (or a file) as additional component + of the list. You have to specify also any existing directories + displayed by by 'show auto-load safe-path' (such as '/usr:/bin' in + this example). + +'gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" ...' + Specify this directory as in the previous case but just for a + single GDB session. + +'gdb -iex "set auto-load safe-path /" ...' + Disable auto-loading safety for a single GDB session. This assumes + all the files you debug during this GDB session will come from + trusted sources. + +'./configure --without-auto-load-safe-path' + During compilation of GDB you may disable any auto-loading safety. + This assumes all the files you will ever debug with this GDB come + from trusted sources. + + On the other hand you can also explicitly forbid automatic files +loading which also suppresses any such warning messages: + +'gdb -iex "set auto-load no" ...' + You can use GDB command-line option for a single GDB session. + +'~/.gdbinit': 'set auto-load no' + Disable auto-loading globally for the user (*note Home Directory + Init File::). While it is improbable, you could also use system + init file instead (*note System-wide configuration::). + + This setting applies to the file names as entered by user. If no +entry matches GDB tries as a last resort to also resolve all the file +names into their canonical form (typically resolving symbolic links) and +compare the entries again. GDB already canonicalizes most of the +filenames on its own before starting the comparison so a canonical form +of directories is recommended to be entered. + + +File: gdb.info, Node: Auto-loading verbose mode, Prev: Auto-loading safe path, Up: Auto-loading + +22.7.4 Displaying files tried for auto-load +------------------------------------------- + +For better visibility of all the file locations where you can place +scripts to be auto-loaded with inferior -- or to protect yourself +against accidental execution of untrusted scripts -- GDB provides a +feature for printing all the files attempted to be loaded. Both +existing and non-existing files may be printed. + + For example the list of directories from which it is safe to +auto-load files (*note Auto-loading safe path::) applies also to +canonicalized filenames which may not be too obvious while setting it +up. + + (gdb) set debug auto-load on + (gdb) file ~/src/t/true + auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" + for objfile "/tmp/true". + auto-load: Updating directories of "/usr:/opt". + auto-load: Using directory "/usr". + auto-load: Using directory "/opt". + warning: File "/tmp/true-gdb.gdb" auto-loading has been declined + by your `auto-load safe-path' set to "/usr:/opt". + +'set debug auto-load [on|off]' + Set whether to print the filenames attempted to be auto-loaded. + +'show debug auto-load' + Show whether printing of the filenames attempted to be auto-loaded + is turned on or off. + + +File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: Auto-loading, Up: Controlling GDB + +22.8 Optional Warnings and Messages +=================================== + +By default, GDB is silent about its inner workings. If you are running +on a slow machine, you may want to use the 'set verbose' command. This +makes GDB tell you when it does a lengthy internal operation, so you +will not think it has crashed. + + Currently, the messages controlled by 'set verbose' are those which +announce that the symbol table for a source file is being read; see +'symbol-file' in *note Commands to Specify Files: Files. + +'set verbose on' + Enables GDB output of certain informational messages. + +'set verbose off' + Disables GDB output of certain informational messages. + +'show verbose' + Displays whether 'set verbose' is on or off. + + By default, if GDB encounters bugs in the symbol table of an object +file, it is silent; but if you are debugging a compiler, you may find +this information useful (*note Errors Reading Symbol Files: Symbol +Errors.). + +'set complaints LIMIT' + Permits GDB to output LIMIT complaints about each type of unusual + symbols before becoming silent about the problem. Set LIMIT to + zero to suppress all complaints; set it to a large number to + prevent complaints from being suppressed. + +'show complaints' + Displays how many symbol complaints GDB is permitted to produce. + + By default, GDB is cautious, and asks what sometimes seems to be a +lot of stupid questions to confirm certain commands. For example, if +you try to run a program which is already running: + + (gdb) run + The program being debugged has been started already. + Start it from the beginning? (y or n) + + If you are willing to unflinchingly face the consequences of your own +commands, you can disable this "feature": + +'set confirm off' + Disables confirmation requests. Note that running GDB with the + '--batch' option (*note -batch: Mode Options.) also automatically + disables confirmation requests. + +'set confirm on' + Enables confirmation requests (the default). + +'show confirm' + Displays state of confirmation requests. + + If you need to debug user-defined commands or sourced files you may +find it useful to enable "command tracing". In this mode each command +will be printed as it is executed, prefixed with one or more '+' +symbols, the quantity denoting the call depth of each command. + +'set trace-commands on' + Enable command tracing. +'set trace-commands off' + Disable command tracing. +'show trace-commands' + Display the current state of command tracing. + + +File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Messages/Warnings, Up: Controlling GDB + +22.9 Optional Messages about Internal Happenings +================================================ + +GDB has commands that enable optional debugging messages from various +GDB subsystems; normally these commands are of interest to GDB +maintainers, or when reporting a bug. This section documents those +commands. + +'set exec-done-display' + Turns on or off the notification of asynchronous commands' + completion. When on, GDB will print a message when an asynchronous + command finishes its execution. The default is off. +'show exec-done-display' + Displays the current setting of asynchronous command completion + notification. +'set debug aarch64' + Turns on or off display of debugging messages related to ARM + AArch64. The default is off. +'show debug aarch64' + Displays the current state of displaying debugging messages related + to ARM AArch64. +'set debug arch' + Turns on or off display of gdbarch debugging info. The default is + off +'show debug arch' + Displays the current state of displaying gdbarch debugging info. +'set debug aix-solib' + Control display of debugging messages from the AIX shared library + support module. The default is off. +'show debug aix-thread' + Show the current state of displaying AIX shared library debugging + messages. +'set debug aix-thread' + Display debugging messages about inner workings of the AIX thread + module. +'show debug aix-thread' + Show the current state of AIX thread debugging info display. +'set debug check-physname' + Check the results of the "physname" computation. When reading + DWARF debugging information for C++, GDB attempts to compute each + entity's name. GDB can do this computation in two different ways, + depending on exactly what information is present. When enabled, + this setting causes GDB to compute the names both ways and display + any discrepancies. +'show debug check-physname' + Show the current state of "physname" checking. +'set debug coff-pe-read' + Control display of debugging messages related to reading of COFF/PE + exported symbols. The default is off. +'show debug coff-pe-read' + Displays the current state of displaying debugging messages related + to reading of COFF/PE exported symbols. +'set debug dwarf2-die' + Dump DWARF2 DIEs after they are read in. The value is the number + of nesting levels to print. A value of zero turns off the display. +'show debug dwarf2-die' + Show the current state of DWARF2 DIE debugging. +'set debug dwarf2-read' + Turns on or off display of debugging messages related to reading + DWARF debug info. The default is 0 (off). A value of 1 provides + basic information. A value greater than 1 provides more verbose + information. +'show debug dwarf2-read' + Show the current state of DWARF2 reader debugging. +'set debug displaced' + Turns on or off display of GDB debugging info for the displaced + stepping support. The default is off. +'show debug displaced' + Displays the current state of displaying GDB debugging info related + to displaced stepping. +'set debug event' + Turns on or off display of GDB event debugging info. The default + is off. +'show debug event' + Displays the current state of displaying GDB event debugging info. +'set debug expression' + Turns on or off display of debugging info about GDB expression + parsing. The default is off. +'show debug expression' + Displays the current state of displaying debugging info about GDB + expression parsing. +'set debug frame' + Turns on or off display of GDB frame debugging info. The default + is off. +'show debug frame' + Displays the current state of displaying GDB frame debugging info. +'set debug gnu-nat' + Turns on or off debugging messages from the GNU/Hurd debug support. +'show debug gnu-nat' + Show the current state of GNU/Hurd debugging messages. +'set debug infrun' + Turns on or off display of GDB debugging info for running the + inferior. The default is off. 'infrun.c' contains GDB's runtime + state machine used for implementing operations such as + single-stepping the inferior. +'show debug infrun' + Displays the current state of GDB inferior debugging. +'set debug jit' + Turns on or off debugging messages from JIT debug support. +'show debug jit' + Displays the current state of GDB JIT debugging. +'set debug lin-lwp' + Turns on or off debugging messages from the Linux LWP debug + support. +'show debug lin-lwp' + Show the current state of Linux LWP debugging messages. +'set debug mach-o' + Control display of debugging messages related to Mach-O symbols + processing. The default is off. +'show debug mach-o' + Displays the current state of displaying debugging messages related + to reading of COFF/PE exported symbols. +'set debug notification' + Turns on or off debugging messages about remote async notification. + The default is off. +'show debug notification' + Displays the current state of remote async notification debugging + messages. +'set debug observer' + Turns on or off display of GDB observer debugging. This includes + info such as the notification of observable events. +'show debug observer' + Displays the current state of observer debugging. +'set debug overload' + Turns on or off display of GDB C++ overload debugging info. This + includes info such as ranking of functions, etc. The default is + off. +'show debug overload' + Displays the current state of displaying GDB C++ overload debugging + info. +'set debug parser' + Turns on or off the display of expression parser debugging output. + Internally, this sets the 'yydebug' variable in the expression + parser. *Note Tracing Your Parser: (bison)Tracing, for details. + The default is off. +'show debug parser' + Show the current state of expression parser debugging. +'set debug remote' + Turns on or off display of reports on all packets sent back and + forth across the serial line to the remote machine. The info is + printed on the GDB standard output stream. The default is off. +'show debug remote' + Displays the state of display of remote packets. +'set debug serial' + Turns on or off display of GDB serial debugging info. The default + is off. +'show debug serial' + Displays the current state of displaying GDB serial debugging info. +'set debug solib-frv' + Turns on or off debugging messages for FR-V shared-library code. +'show debug solib-frv' + Display the current state of FR-V shared-library code debugging + messages. +'set debug symfile' + Turns on or off display of debugging messages related to symbol + file functions. The default is off. *Note Files::. +'show debug symfile' + Show the current state of symbol file debugging messages. +'set debug symtab-create' + Turns on or off display of debugging messages related to symbol + table creation. The default is 0 (off). A value of 1 provides + basic information. A value greater than 1 provides more verbose + information. +'show debug symtab-create' + Show the current state of symbol table creation debugging. +'set debug target' + Turns on or off display of GDB target debugging info. This info + includes what is going on at the target level of GDB, as it + happens. The default is 0. Set it to 1 to track events, and to 2 + to also track the value of large memory transfers. Changes to this + flag do not take effect until the next time you connect to a target + or use the 'run' command. +'show debug target' + Displays the current state of displaying GDB target debugging info. +'set debug timestamp' + Turns on or off display of timestamps with GDB debugging info. + When enabled, seconds and microseconds are displayed before each + debugging message. +'show debug timestamp' + Displays the current state of displaying timestamps with GDB + debugging info. +'set debugvarobj' + Turns on or off display of GDB variable object debugging info. The + default is off. +'show debugvarobj' + Displays the current state of displaying GDB variable object + debugging info. +'set debug xml' + Turns on or off debugging messages for built-in XML parsers. +'show debug xml' + Displays the current state of XML debugging messages. + + +File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Controlling GDB + +22.10 Other Miscellaneous Settings +================================== + +'set interactive-mode' + If 'on', forces GDB to assume that GDB was started in a terminal. + In practice, this means that GDB should wait for the user to answer + queries generated by commands entered at the command prompt. If + 'off', forces GDB to operate in the opposite mode, and it uses the + default answers to all queries. If 'auto' (the default), GDB tries + to determine whether its standard input is a terminal, and works in + interactive-mode if it is, non-interactively otherwise. + + In the vast majority of cases, the debugger should be able to guess + correctly which mode should be used. But this setting can be + useful in certain specific cases, such as running a MinGW GDB + inside a cygwin window. + +'show interactive-mode' + Displays whether the debugger is operating in interactive mode or + not. + + +File: gdb.info, Node: Extending GDB, Next: Interpreters, Prev: Controlling GDB, Up: Top + +23 Extending GDB +**************** + +GDB provides several mechanisms for extension. GDB also provides the +ability to automatically load extensions when it reads a file for +debugging. This allows the user to automatically customize GDB for the +program being debugged. + +* Menu: + +* Sequences:: Canned Sequences of GDB Commands +* Python:: Extending GDB using Python +* Auto-loading extensions:: Automatically loading extensions +* Aliases:: Creating new spellings of existing commands + + To facilitate the use of extension languages, GDB is capable of +evaluating the contents of a file. When doing so, GDB can recognize +which extension language is being used by looking at the filename +extension. Files with an unrecognized filename extension are always +treated as a GDB Command Files. *Note Command files: Command Files. + + You can control how GDB evaluates these files with the following +setting: + +'set script-extension off' + All scripts are always evaluated as GDB Command Files. + +'set script-extension soft' + The debugger determines the scripting language based on filename + extension. If this scripting language is supported, GDB evaluates + the script using that language. Otherwise, it evaluates the file + as a GDB Command File. + +'set script-extension strict' + The debugger determines the scripting language based on filename + extension, and evaluates the script using that language. If the + language is not supported, then the evaluation fails. + +'show script-extension' + Display the current value of the 'script-extension' option. + + +File: gdb.info, Node: Sequences, Next: Python, Up: Extending GDB + +23.1 Canned Sequences of Commands +================================= + +Aside from breakpoint commands (*note Breakpoint Command Lists: Break +Commands.), GDB provides two ways to store sequences of commands for +execution as a unit: user-defined commands and command files. + +* Menu: + +* Define:: How to define your own commands +* Hooks:: Hooks for user-defined commands +* Command Files:: How to write scripts of commands to be stored in a file +* Output:: Commands for controlled output +* Auto-loading sequences:: Controlling auto-loaded command files + + +File: gdb.info, Node: Define, Next: Hooks, Up: Sequences + +23.1.1 User-defined Commands +---------------------------- + +A "user-defined command" is a sequence of GDB commands to which you +assign a new name as a command. This is done with the 'define' command. +User commands may accept up to 10 arguments separated by whitespace. +Arguments are accessed within the user command via '$arg0...$arg9'. A +trivial example: + + define adder + print $arg0 + $arg1 + $arg2 + end + +To execute the command use: + + adder 1 2 3 + +This defines the command 'adder', which prints the sum of its three +arguments. Note the arguments are text substitutions, so they may +reference variables, use complex expressions, or even perform inferior +functions calls. + + In addition, '$argc' may be used to find out how many arguments have +been passed. This expands to a number in the range 0...10. + + define adder + if $argc == 2 + print $arg0 + $arg1 + end + if $argc == 3 + print $arg0 + $arg1 + $arg2 + end + end + +'define COMMANDNAME' + Define a command named COMMANDNAME. If there is already a command + by that name, you are asked to confirm that you want to redefine + it. COMMANDNAME may be a bare command name consisting of letters, + numbers, dashes, and underscores. It may also start with any + predefined prefix command. For example, 'define target my-target' + creates a user-defined 'target my-target' command. + + The definition of the command is made up of other GDB command + lines, which are given following the 'define' command. The end of + these commands is marked by a line containing 'end'. + +'document COMMANDNAME' + Document the user-defined command COMMANDNAME, so that it can be + accessed by 'help'. The command COMMANDNAME must already be + defined. This command reads lines of documentation just as + 'define' reads the lines of the command definition, ending with + 'end'. After the 'document' command is finished, 'help' on command + COMMANDNAME displays the documentation you have written. + + You may use the 'document' command again to change the + documentation of a command. Redefining the command with 'define' + does not change the documentation. + +'dont-repeat' + Used inside a user-defined command, this tells GDB that this + command should not be repeated when the user hits (*note + repeat last command: Command Syntax.). + +'help user-defined' + List all user-defined commands and all python commands defined in + class COMAND_USER. The first line of the documentation or docstring + is included (if any). + +'show user' +'show user COMMANDNAME' + Display the GDB commands used to define COMMANDNAME (but not its + documentation). If no COMMANDNAME is given, display the + definitions for all user-defined commands. This does not work for + user-defined python commands. + +'show max-user-call-depth' +'set max-user-call-depth' + The value of 'max-user-call-depth' controls how many recursion + levels are allowed in user-defined commands before GDB suspects an + infinite recursion and aborts the command. This does not apply to + user-defined python commands. + + In addition to the above commands, user-defined commands frequently +use control flow commands, described in *note Command Files::. + + When user-defined commands are executed, the commands of the +definition are not printed. An error in any command stops execution of +the user-defined command. + + If used interactively, commands that would ask for confirmation +proceed without asking when used inside a user-defined command. Many +GDB commands that normally print messages to say what they are doing +omit the messages when used in a user-defined command. + + +File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences + +23.1.2 User-defined Command Hooks +--------------------------------- + +You may define "hooks", which are a special kind of user-defined +command. Whenever you run the command 'foo', if the user-defined +command 'hook-foo' exists, it is executed (with no arguments) before +that command. + + A hook may also be defined which is run after the command you +executed. Whenever you run the command 'foo', if the user-defined +command 'hookpost-foo' exists, it is executed (with no arguments) after +that command. Post-execution hooks may exist simultaneously with +pre-execution hooks, for the same command. + + It is valid for a hook to call the command which it hooks. If this +occurs, the hook is not re-executed, thereby avoiding infinite +recursion. + + In addition, a pseudo-command, 'stop' exists. Defining ('hook-stop') +makes the associated commands execute every time execution stops in your +program: before breakpoint commands are run, displays are printed, or +the stack frame is printed. + + For example, to ignore 'SIGALRM' signals while single-stepping, but +treat them normally during normal execution, you could define: + + define hook-stop + handle SIGALRM nopass + end + + define hook-run + handle SIGALRM pass + end + + define hook-continue + handle SIGALRM pass + end + + As a further example, to hook at the beginning and end of the 'echo' +command, and to add extra text to the beginning and end of the message, +you could define: + + define hook-echo + echo <<<--- + end + + define hookpost-echo + echo --->>>\n + end + + (gdb) echo Hello World + <<<---Hello World--->>> + (gdb) + + You can define a hook for any single-word command in GDB, but not for +command aliases; you should define a hook for the basic command name, +e.g. 'backtrace' rather than 'bt'. You can hook a multi-word command by +adding 'hook-' or 'hookpost-' to the last word of the command, e.g. +'define target hook-remote' to add a hook to 'target remote'. + + If an error occurs during the execution of your hook, execution of +GDB commands stops and GDB issues a prompt (before the command that you +actually typed had a chance to run). + + If you try to define a hook which does not match any known command, +you get a warning from the 'define' command. + + +File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences + +23.1.3 Command Files +-------------------- + +A command file for GDB is a text file made of lines that are GDB +commands. Comments (lines starting with '#') may also be included. An +empty line in a command file does nothing; it does not mean to repeat +the last command, as it would from the terminal. + + You can request the execution of a command file with the 'source' +command. Note that the 'source' command is also used to evaluate +scripts that are not Command Files. The exact behavior can be +configured using the 'script-extension' setting. *Note Extending GDB: +Extending GDB. + +'source [-s] [-v] FILENAME' + Execute the command file FILENAME. + + The lines in a command file are generally executed sequentially, +unless the order of execution is changed by one of the _flow-control +commands_ described below. The commands are not printed as they are +executed. An error in any command terminates execution of the command +file and control is returned to the console. + + GDB first searches for FILENAME in the current directory. If the +file is not found there, and FILENAME does not specify a directory, then +GDB also looks for the file on the source search path (specified with +the 'directory' command); except that '$cdir' is not searched because +the compilation directory is not relevant to scripts. + + If '-s' is specified, then GDB searches for FILENAME on the search +path even if FILENAME specifies a directory. The search is done by +appending FILENAME to each element of the search path. So, for example, +if FILENAME is 'mylib/myscript' and the search path contains +'/home/user' then GDB will look for the script +'/home/user/mylib/myscript'. The search is also done if FILENAME is an +absolute path. For example, if FILENAME is '/tmp/myscript' and the +search path contains '/home/user' then GDB will look for the script +'/home/user/tmp/myscript'. For DOS-like systems, if FILENAME contains a +drive specification, it is stripped before concatenation. For example, +if FILENAME is 'd:myscript' and the search path contains 'c:/tmp' then +GDB will look for the script 'c:/tmp/myscript'. + + If '-v', for verbose mode, is given then GDB displays each command as +it is executed. The option must be given before FILENAME, and is +interpreted as part of the filename anywhere else. + + Commands that would ask for confirmation if used interactively +proceed without asking when used in a command file. Many GDB commands +that normally print messages to say what they are doing omit the +messages when called from command files. + + GDB also accepts command input from standard input. In this mode, +normal output goes to standard output and error output goes to standard +error. Errors in a command file supplied on standard input do not +terminate execution of the command file--execution continues with the +next command. + + gdb < cmds > log 2>&1 + + (The syntax above will vary depending on the shell used.) This +example will execute commands from the file 'cmds'. All output and +errors would be directed to 'log'. + + Since commands stored on command files tend to be more general than +commands typed interactively, they frequently need to deal with +complicated situations, such as different or unexpected values of +variables and symbols, changes in how the program being debugged is +built, etc. GDB provides a set of flow-control commands to deal with +these complexities. Using these commands, you can write complex scripts +that loop over data structures, execute commands conditionally, etc. + +'if' +'else' + This command allows to include in your script conditionally + executed commands. The 'if' command takes a single argument, which + is an expression to evaluate. It is followed by a series of + commands that are executed only if the expression is true (its + value is nonzero). There can then optionally be an 'else' line, + followed by a series of commands that are only executed if the + expression was false. The end of the list is marked by a line + containing 'end'. + +'while' + This command allows to write loops. Its syntax is similar to 'if': + the command takes a single argument, which is an expression to + evaluate, and must be followed by the commands to execute, one per + line, terminated by an 'end'. These commands are called the "body" + of the loop. The commands in the body of 'while' are executed + repeatedly as long as the expression evaluates to true. + +'loop_break' + This command exits the 'while' loop in whose body it is included. + Execution of the script continues after that 'while's 'end' line. + +'loop_continue' + This command skips the execution of the rest of the body of + commands in the 'while' loop in whose body it is included. + Execution branches to the beginning of the 'while' loop, where it + evaluates the controlling expression. + +'end' + Terminate the block of commands that are the body of 'if', 'else', + or 'while' flow-control commands. + + +File: gdb.info, Node: Output, Next: Auto-loading sequences, Prev: Command Files, Up: Sequences + +23.1.4 Commands for Controlled Output +------------------------------------- + +During the execution of a command file or a user-defined command, normal +GDB output is suppressed; the only output that appears is what is +explicitly printed by the commands in the definition. This section +describes three commands useful for generating exactly the output you +want. + +'echo TEXT' + Print TEXT. Nonprinting characters can be included in TEXT using C + escape sequences, such as '\n' to print a newline. *No newline is + printed unless you specify one.* In addition to the standard C + escape sequences, a backslash followed by a space stands for a + space. This is useful for displaying a string with spaces at the + beginning or the end, since leading and trailing spaces are + otherwise trimmed from all arguments. To print ' and foo = ', use + the command 'echo \ and foo = \ '. + + A backslash at the end of TEXT can be used, as in C, to continue + the command onto subsequent lines. For example, + + echo This is some text\n\ + which is continued\n\ + onto several lines.\n + + produces the same output as + + echo This is some text\n + echo which is continued\n + echo onto several lines.\n + +'output EXPRESSION' + Print the value of EXPRESSION and nothing but that value: no + newlines, no '$NN = '. The value is not entered in the value + history either. *Note Expressions: Expressions, for more + information on expressions. + +'output/FMT EXPRESSION' + Print the value of EXPRESSION in format FMT. You can use the same + formats as for 'print'. *Note Output Formats: Output Formats, for + more information. + +'printf TEMPLATE, EXPRESSIONS...' + Print the values of one or more EXPRESSIONS under the control of + the string TEMPLATE. To print several values, make EXPRESSIONS be + a comma-separated list of individual expressions, which may be + either numbers or pointers. Their values are printed as specified + by TEMPLATE, exactly as a C program would do by executing the code + below: + + printf (TEMPLATE, EXPRESSIONS...); + + As in 'C' 'printf', ordinary characters in TEMPLATE are printed + verbatim, while "conversion specification" introduced by the '%' + character cause subsequent EXPRESSIONS to be evaluated, their + values converted and formatted according to type and style + information encoded in the conversion specifications, and then + printed. + + For example, you can print two values in hex like this: + + printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo + + 'printf' supports all the standard 'C' conversion specifications, + including the flags and modifiers between the '%' character and the + conversion letter, with the following exceptions: + + * The argument-ordering modifiers, such as '2$', are not + supported. + + * The modifier '*' is not supported for specifying precision or + width. + + * The ''' flag (for separation of digits into groups according + to 'LC_NUMERIC'') is not supported. + + * The type modifiers 'hh', 'j', 't', and 'z' are not supported. + + * The conversion letter 'n' (as in '%n') is not supported. + + * The conversion letters 'a' and 'A' are not supported. + + Note that the 'll' type modifier is supported only if the + underlying 'C' implementation used to build GDB supports the 'long + long int' type, and the 'L' type modifier is supported only if + 'long double' type is available. + + As in 'C', 'printf' supports simple backslash-escape sequences, + such as '\n', '\t', '\\', '\"', '\a', and '\f', that consist of + backslash followed by a single character. Octal and hexadecimal + escape sequences are not supported. + + Additionally, 'printf' supports conversion specifications for DFP + ("Decimal Floating Point") types using the following length + modifiers together with a floating point specifier. letters: + + * 'H' for printing 'Decimal32' types. + + * 'D' for printing 'Decimal64' types. + + * 'DD' for printing 'Decimal128' types. + + If the underlying 'C' implementation used to build GDB has support + for the three length modifiers for DFP types, other modifiers such + as width and precision will also be available for GDB to use. + + In case there is no such 'C' support, no additional modifiers will + be available and the value will be printed in the standard way. + + Here's an example of printing DFP types using the above conversion + letters: + printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl + +'eval TEMPLATE, EXPRESSIONS...' + Convert the values of one or more EXPRESSIONS under the control of + the string TEMPLATE to a command line, and call it. + + +File: gdb.info, Node: Auto-loading sequences, Prev: Output, Up: Sequences + +23.1.5 Controlling auto-loading native GDB scripts +-------------------------------------------------- + +When a new object file is read (for example, due to the 'file' command, +or because the inferior has loaded a shared library), GDB will look for +the command file 'OBJFILE-gdb.gdb'. *Note Auto-loading extensions::. + + Auto-loading can be enabled or disabled, and the list of auto-loaded +scripts can be printed. + +'set auto-load gdb-scripts [on|off]' + Enable or disable the auto-loading of canned sequences of commands + scripts. + +'show auto-load gdb-scripts' + Show whether auto-loading of canned sequences of commands scripts + is enabled or disabled. + +'info auto-load gdb-scripts [REGEXP]' + Print the list of all canned sequences of commands scripts that GDB + auto-loaded. + + If REGEXP is supplied only canned sequences of commands scripts with +matching names are printed. + + +File: gdb.info, Node: Python, Next: Auto-loading extensions, Prev: Sequences, Up: Extending GDB + +23.2 Extending GDB using Python +=============================== + +You can extend GDB using the Python programming language +(http://www.python.org/). This feature is available only if GDB was +configured using '--with-python'. + + Python scripts used by GDB should be installed in +'DATA-DIRECTORY/python', where DATA-DIRECTORY is the data directory as +determined at GDB startup (*note Data Files::). This directory, known +as the "python directory", is automatically added to the Python Search +Path in order to allow the Python interpreter to locate all scripts +installed at this location. + + Additionally, GDB commands and convenience functions which are +written in Python and are located in the +'DATA-DIRECTORY/python/gdb/command' or +'DATA-DIRECTORY/python/gdb/function' directories are automatically +imported when GDB starts. + +* Menu: + +* Python Commands:: Accessing Python from GDB. +* Python API:: Accessing GDB from Python. +* Python Auto-loading:: Automatically loading Python code. +* Python modules:: Python modules provided by GDB. + + +File: gdb.info, Node: Python Commands, Next: Python API, Up: Python + +23.2.1 Python Commands +---------------------- + +GDB provides two commands for accessing the Python interpreter, and one +related setting: + +'python-interactive [COMMAND]' +'pi [COMMAND]' + Without an argument, the 'python-interactive' command can be used + to start an interactive Python prompt. To return to GDB, type the + 'EOF' character (e.g., 'Ctrl-D' on an empty prompt). + + Alternatively, a single-line Python command can be given as an + argument and evaluated. If the command is an expression, the + result will be printed; otherwise, nothing will be printed. For + example: + + (gdb) python-interactive 2 + 3 + 5 + +'python [COMMAND]' +'py [COMMAND]' + The 'python' command can be used to evaluate Python code. + + If given an argument, the 'python' command will evaluate the + argument as a Python command. For example: + + (gdb) python print 23 + 23 + + If you do not provide an argument to 'python', it will act as a + multi-line command, like 'define'. In this case, the Python script + is made up of subsequent command lines, given after the 'python' + command. This command list is terminated using a line containing + 'end'. For example: + + (gdb) python + Type python script + End with a line saying just "end". + >print 23 + >end + 23 + +'set python print-stack' + By default, GDB will print only the message component of a Python + exception when an error occurs in a Python script. This can be + controlled using 'set python print-stack': if 'full', then full + Python stack printing is enabled; if 'none', then Python stack and + message printing is disabled; if 'message', the default, only the + message component of the error is printed. + + It is also possible to execute a Python script from the GDB +interpreter: + +'source script-name' + The script name must end with '.py' and GDB must be configured to + recognize the script language based on filename extension using the + 'script-extension' setting. *Note Extending GDB: Extending GDB. + +'python execfile ("script-name")' + This method is based on the 'execfile' Python built-in function, + and thus is always available. + + +File: gdb.info, Node: Python API, Next: Python Auto-loading, Prev: Python Commands, Up: Python + +23.2.2 Python API +----------------- + +You can get quick online help for GDB's Python API by issuing the +command 'python help (gdb)'. + + Functions and methods which have two or more optional arguments allow +them to be specified using keyword syntax. This allows passing some +optional arguments while skipping others. Example: +'gdb.some_function ('foo', bar = 1, baz = 2)'. + +* Menu: + +* Basic Python:: Basic Python Functions. +* Exception Handling:: How Python exceptions are translated. +* Values From Inferior:: Python representation of values. +* Types In Python:: Python representation of types. +* Pretty Printing API:: Pretty-printing values. +* Selecting Pretty-Printers:: How GDB chooses a pretty-printer. +* Writing a Pretty-Printer:: Writing a Pretty-Printer. +* Type Printing API:: Pretty-printing types. +* Frame Filter API:: Filtering Frames. +* Frame Decorator API:: Decorating Frames. +* Writing a Frame Filter:: Writing a Frame Filter. +* Inferiors In Python:: Python representation of inferiors (processes) +* Events In Python:: Listening for events from GDB. +* Threads In Python:: Accessing inferior threads from Python. +* Commands In Python:: Implementing new commands in Python. +* Parameters In Python:: Adding new GDB parameters. +* Functions In Python:: Writing new convenience functions. +* Progspaces In Python:: Program spaces. +* Objfiles In Python:: Object files. +* Frames In Python:: Accessing inferior stack frames from Python. +* Blocks In Python:: Accessing blocks from Python. +* Symbols In Python:: Python representation of symbols. +* Symbol Tables In Python:: Python representation of symbol tables. +* Line Tables In Python:: Python representation of line tables. +* Breakpoints In Python:: Manipulating breakpoints using Python. +* Finish Breakpoints in Python:: Setting Breakpoints on function return + using Python. +* Lazy Strings In Python:: Python representation of lazy strings. +* Architectures In Python:: Python representation of architectures. + + +File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API + +23.2.2.1 Basic Python +..................... + +At startup, GDB overrides Python's 'sys.stdout' and 'sys.stderr' to +print using GDB's output-paging streams. A Python program which outputs +to one of these streams may have its output interrupted by the user +(*note Screen Size::). In this situation, a Python 'KeyboardInterrupt' +exception is thrown. + + Some care must be taken when writing Python code to run in GDB. Two +things worth noting in particular: + + * GDB install handlers for 'SIGCHLD' and 'SIGINT'. Python code must + not override these, or even change the options using 'sigaction'. + If your program changes the handling of these signals, GDB will + most likely stop working correctly. Note that it is unfortunately + common for GUI toolkits to install a 'SIGCHLD' handler. + + * GDB takes care to mark its internal file descriptors as + close-on-exec. However, this cannot be done in a thread-safe way + on all platforms. Your Python programs should be aware of this and + should both create new file descriptors with the close-on-exec flag + set and arrange to close unneeded file descriptors before starting + a child process. + + GDB introduces a new Python module, named 'gdb'. All methods and +classes added by GDB are placed in this module. GDB automatically +'import's the 'gdb' module for use in all scripts evaluated by the +'python' command. + + -- Variable: gdb.PYTHONDIR + A string containing the python directory (*note Python::). + + -- Function: gdb.execute (command [, from_tty [, to_string]]) + Evaluate COMMAND, a string, as a GDB CLI command. If a GDB + exception happens while COMMAND runs, it is translated as described + in *note Exception Handling: Exception Handling. + + FROM_TTY specifies whether GDB ought to consider this command as + having originated from the user invoking it interactively. It must + be a boolean value. If omitted, it defaults to 'False'. + + By default, any output produced by COMMAND is sent to GDB's + standard output. If the TO_STRING parameter is 'True', then output + will be collected by 'gdb.execute' and returned as a string. The + default is 'False', in which case the return value is 'None'. If + TO_STRING is 'True', the GDB virtual terminal will be temporarily + set to unlimited width and height, and its pagination will be + disabled; *note Screen Size::. + + -- Function: gdb.breakpoints () + Return a sequence holding all of GDB's breakpoints. *Note + Breakpoints In Python::, for more information. + + -- Function: gdb.parameter (parameter) + Return the value of a GDB parameter. PARAMETER is a string naming + the parameter to look up; PARAMETER may contain spaces if the + parameter has a multi-part name. For example, 'print object' is a + valid parameter name. + + If the named parameter does not exist, this function throws a + 'gdb.error' (*note Exception Handling::). Otherwise, the + parameter's value is converted to a Python value of the appropriate + type, and returned. + + -- Function: gdb.history (number) + Return a value from GDB's value history (*note Value History::). + NUMBER indicates which history element to return. If NUMBER is + negative, then GDB will take its absolute value and count backward + from the last element (i.e., the most recent element) to find the + value to return. If NUMBER is zero, then GDB will return the most + recent element. If the element specified by NUMBER doesn't exist + in the value history, a 'gdb.error' exception will be raised. + + If no exception is raised, the return value is always an instance + of 'gdb.Value' (*note Values From Inferior::). + + -- Function: gdb.parse_and_eval (expression) + Parse EXPRESSION as an expression in the current language, evaluate + it, and return the result as a 'gdb.Value'. EXPRESSION must be a + string. + + This function can be useful when implementing a new command (*note + Commands In Python::), as it provides a way to parse the command's + argument as an expression. It is also useful simply to compute + values, for example, it is the only way to get the value of a + convenience variable (*note Convenience Vars::) as a 'gdb.Value'. + + -- Function: gdb.find_pc_line (pc) + Return the 'gdb.Symtab_and_line' object corresponding to the PC + value. *Note Symbol Tables In Python::. If an invalid value of PC + is passed as an argument, then the 'symtab' and 'line' attributes + of the returned 'gdb.Symtab_and_line' object will be 'None' and 0 + respectively. + + -- Function: gdb.post_event (event) + Put EVENT, a callable object taking no arguments, into GDB's + internal event queue. This callable will be invoked at some later + point, during GDB's event processing. Events posted using + 'post_event' will be run in the order in which they were posted; + however, there is no way to know when they will be processed + relative to other events inside GDB. + + GDB is not thread-safe. If your Python program uses multiple + threads, you must be careful to only call GDB-specific functions in + the main GDB thread. 'post_event' ensures this. For example: + + (gdb) python + >import threading + > + >class Writer(): + > def __init__(self, message): + > self.message = message; + > def __call__(self): + > gdb.write(self.message) + > + >class MyThread1 (threading.Thread): + > def run (self): + > gdb.post_event(Writer("Hello ")) + > + >class MyThread2 (threading.Thread): + > def run (self): + > gdb.post_event(Writer("World\n")) + > + >MyThread1().start() + >MyThread2().start() + >end + (gdb) Hello World + + -- Function: gdb.write (string [, stream]) + Print a string to GDB's paginated output stream. The optional + STREAM determines the stream to print to. The default stream is + GDB's standard output stream. Possible stream values are: + + 'gdb.STDOUT' + GDB's standard output stream. + + 'gdb.STDERR' + GDB's standard error stream. + + 'gdb.STDLOG' + GDB's log stream (*note Logging Output::). + + Writing to 'sys.stdout' or 'sys.stderr' will automatically call + this function and will automatically direct the output to the + relevant stream. + + -- Function: gdb.flush () + Flush the buffer of a GDB paginated stream so that the contents are + displayed immediately. GDB will flush the contents of a stream + automatically when it encounters a newline in the buffer. The + optional STREAM determines the stream to flush. The default stream + is GDB's standard output stream. Possible stream values are: + + 'gdb.STDOUT' + GDB's standard output stream. + + 'gdb.STDERR' + GDB's standard error stream. + + 'gdb.STDLOG' + GDB's log stream (*note Logging Output::). + + Flushing 'sys.stdout' or 'sys.stderr' will automatically call this + function for the relevant stream. + + -- Function: gdb.target_charset () + Return the name of the current target character set (*note + Character Sets::). This differs from + 'gdb.parameter('target-charset')' in that 'auto' is never returned. + + -- Function: gdb.target_wide_charset () + Return the name of the current target wide character set (*note + Character Sets::). This differs from + 'gdb.parameter('target-wide-charset')' in that 'auto' is never + returned. + + -- Function: gdb.solib_name (address) + Return the name of the shared library holding the given ADDRESS as + a string, or 'None'. + + -- Function: gdb.decode_line [expression] + Return locations of the line specified by EXPRESSION, or of the + current line if no argument was given. This function returns a + Python tuple containing two elements. The first element contains a + string holding any unparsed section of EXPRESSION (or 'None' if the + expression has been fully parsed). The second element contains + either 'None' or another tuple that contains all the locations that + match the expression represented as 'gdb.Symtab_and_line' objects + (*note Symbol Tables In Python::). If EXPRESSION is provided, it + is decoded the way that GDB's inbuilt 'break' or 'edit' commands do + (*note Specify Location::). + + -- Function: gdb.prompt_hook (current_prompt) + + If PROMPT_HOOK is callable, GDB will call the method assigned to + this operation before a prompt is displayed by GDB. + + The parameter 'current_prompt' contains the current GDB prompt. + This method must return a Python string, or 'None'. If a string is + returned, the GDB prompt will be set to that string. If 'None' is + returned, GDB will continue to use the current prompt. + + Some prompts cannot be substituted in GDB. Secondary prompts such + as those used by readline for command input, and annotation related + prompts are prohibited from being changed. + + +File: gdb.info, Node: Exception Handling, Next: Values From Inferior, Prev: Basic Python, Up: Python API + +23.2.2.2 Exception Handling +........................... + +When executing the 'python' command, Python exceptions uncaught within +the Python code are translated to calls to GDB error-reporting +mechanism. If the command that called 'python' does not handle the +error, GDB will terminate it and print an error message containing the +Python exception name, the associated value, and the Python call stack +backtrace at the point where the exception was raised. Example: + + (gdb) python print foo + Traceback (most recent call last): + File "", line 1, in + NameError: name 'foo' is not defined + + GDB errors that happen in GDB commands invoked by Python code are +converted to Python exceptions. The type of the Python exception +depends on the error. + +'gdb.error' + This is the base class for most exceptions generated by GDB. It is + derived from 'RuntimeError', for compatibility with earlier + versions of GDB. + + If an error occurring in GDB does not fit into some more specific + category, then the generated exception will have this type. + +'gdb.MemoryError' + This is a subclass of 'gdb.error' which is thrown when an operation + tried to access invalid memory in the inferior. + +'KeyboardInterrupt' + User interrupt (via 'C-c' or by typing 'q' at a pagination prompt) + is translated to a Python 'KeyboardInterrupt' exception. + + In all cases, your exception handler will see the GDB error message +as its value and the Python call stack backtrace at the Python statement +closest to where the GDB error occured as the traceback. + + When implementing GDB commands in Python via 'gdb.Command', it is +useful to be able to throw an exception that doesn't cause a traceback +to be printed. For example, the user may have invoked the command +incorrectly. Use the 'gdb.GdbError' exception to handle this case. +Example: + + (gdb) python + >class HelloWorld (gdb.Command): + > """Greet the whole world.""" + > def __init__ (self): + > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) + > def invoke (self, args, from_tty): + > argv = gdb.string_to_argv (args) + > if len (argv) != 0: + > raise gdb.GdbError ("hello-world takes no arguments") + > print "Hello, World!" + >HelloWorld () + >end + (gdb) hello-world 42 + hello-world takes no arguments + + +File: gdb.info, Node: Values From Inferior, Next: Types In Python, Prev: Exception Handling, Up: Python API + +23.2.2.3 Values From Inferior +............................. + +GDB provides values it obtains from the inferior program in an object of +type 'gdb.Value'. GDB uses this object for its internal bookkeeping of +the inferior's values, and for fetching values when necessary. + + Inferior values that are simple scalars can be used directly in +Python expressions that are valid for the value's data type. Here's an +example for an integer or floating-point value 'some_val': + + bar = some_val + 2 + +As result of this, 'bar' will also be a 'gdb.Value' object whose values +are of the same type as those of 'some_val'. + + Inferior values that are structures or instances of some class can be +accessed using the Python "dictionary syntax". For example, if +'some_val' is a 'gdb.Value' instance holding a structure, you can access +its 'foo' element with: + + bar = some_val['foo'] + + Again, 'bar' will also be a 'gdb.Value' object. Structure elements +can also be accessed by using 'gdb.Field' objects as subscripts (*note +Types In Python::, for more information on 'gdb.Field' objects). For +example, if 'foo_field' is a 'gdb.Field' object corresponding to element +'foo' of the above structure, then 'bar' can also be accessed as +follows: + + bar = some_val[foo_field] + + A 'gdb.Value' that represents a function can be executed via inferior +function call. Any arguments provided to the call must match the +function's prototype, and must be provided in the order specified by +that prototype. + + For example, 'some_val' is a 'gdb.Value' instance representing a +function that takes two integers as arguments. To execute this +function, call it like so: + + result = some_val (10,20) + + Any values returned from a function call will be stored as a +'gdb.Value'. + + The following attributes are provided: + + -- Variable: Value.address + If this object is addressable, this read-only attribute holds a + 'gdb.Value' object representing the address. Otherwise, this + attribute holds 'None'. + + -- Variable: Value.is_optimized_out + This read-only boolean attribute is true if the compiler optimized + out this value, thus it is not available for fetching from the + inferior. + + -- Variable: Value.type + The type of this 'gdb.Value'. The value of this attribute is a + 'gdb.Type' object (*note Types In Python::). + + -- Variable: Value.dynamic_type + The dynamic type of this 'gdb.Value'. This uses C++ run-time type + information (RTTI) to determine the dynamic type of the value. If + this value is of class type, it will return the class in which the + value is embedded, if any. If this value is of pointer or + reference to a class type, it will compute the dynamic type of the + referenced object, and return a pointer or reference to that type, + respectively. In all other cases, it will return the value's + static type. + + Note that this feature will only work when debugging a C++ program + that includes RTTI for the object in question. Otherwise, it will + just return the static type of the value as in 'ptype foo' (*note + ptype: Symbols.). + + -- Variable: Value.is_lazy + The value of this read-only boolean attribute is 'True' if this + 'gdb.Value' has not yet been fetched from the inferior. GDB does + not fetch values until necessary, for efficiency. For example: + + myval = gdb.parse_and_eval ('somevar') + + The value of 'somevar' is not fetched at this time. It will be + fetched when the value is needed, or when the 'fetch_lazy' method + is invoked. + + The following methods are provided: + + -- Function: Value.__init__ (VAL) + Many Python values can be converted directly to a 'gdb.Value' via + this object initializer. Specifically: + + Python boolean + A Python boolean is converted to the boolean type from the + current language. + + Python integer + A Python integer is converted to the C 'long' type for the + current architecture. + + Python long + A Python long is converted to the C 'long long' type for the + current architecture. + + Python float + A Python float is converted to the C 'double' type for the + current architecture. + + Python string + A Python string is converted to a target string, using the + current target encoding. + + 'gdb.Value' + If 'val' is a 'gdb.Value', then a copy of the value is made. + + 'gdb.LazyString' + If 'val' is a 'gdb.LazyString' (*note Lazy Strings In + Python::), then the lazy string's 'value' method is called, + and its result is used. + + -- Function: Value.cast (type) + Return a new instance of 'gdb.Value' that is the result of casting + this instance to the type described by TYPE, which must be a + 'gdb.Type' object. If the cast cannot be performed for some + reason, this method throws an exception. + + -- Function: Value.dereference () + For pointer data types, this method returns a new 'gdb.Value' + object whose contents is the object pointed to by the pointer. For + example, if 'foo' is a C pointer to an 'int', declared in your C + program as + + int *foo; + + then you can use the corresponding 'gdb.Value' to access what 'foo' + points to like this: + + bar = foo.dereference () + + The result 'bar' will be a 'gdb.Value' object holding the value + pointed to by 'foo'. + + A similar function 'Value.referenced_value' exists which also + returns 'gdb.Value' objects corresonding to the values pointed to + by pointer values (and additionally, values referenced by reference + values). However, the behavior of 'Value.dereference' differs from + 'Value.referenced_value' by the fact that the behavior of + 'Value.dereference' is identical to applying the C unary operator + '*' on a given value. For example, consider a reference to a + pointer 'ptrref', declared in your C++ program as + + typedef int *intptr; + ... + int val = 10; + intptr ptr = &val; + intptr &ptrref = ptr; + + Though 'ptrref' is a reference value, one can apply the method + 'Value.dereference' to the 'gdb.Value' object corresponding to it + and obtain a 'gdb.Value' which is identical to that corresponding + to 'val'. However, if you apply the method + 'Value.referenced_value', the result would be a 'gdb.Value' object + identical to that corresponding to 'ptr'. + + py_ptrref = gdb.parse_and_eval ("ptrref") + py_val = py_ptrref.dereference () + py_ptr = py_ptrref.referenced_value () + + The 'gdb.Value' object 'py_val' is identical to that corresponding + to 'val', and 'py_ptr' is identical to that corresponding to 'ptr'. + In general, 'Value.dereference' can be applied whenever the C unary + operator '*' can be applied to the corresponding C value. For + those cases where applying both 'Value.dereference' and + 'Value.referenced_value' is allowed, the results obtained need not + be identical (as we have seen in the above example). The results + are however identical when applied on 'gdb.Value' objects + corresponding to pointers ('gdb.Value' objects with type code + 'TYPE_CODE_PTR') in a C/C++ program. + + -- Function: Value.referenced_value () + For pointer or reference data types, this method returns a new + 'gdb.Value' object corresponding to the value referenced by the + pointer/reference value. For pointer data types, + 'Value.dereference' and 'Value.referenced_value' produce identical + results. The difference between these methods is that + 'Value.dereference' cannot get the values referenced by reference + values. For example, consider a reference to an 'int', declared in + your C++ program as + + int val = 10; + int &ref = val; + + then applying 'Value.dereference' to the 'gdb.Value' object + corresponding to 'ref' will result in an error, while applying + 'Value.referenced_value' will result in a 'gdb.Value' object + identical to that corresponding to 'val'. + + py_ref = gdb.parse_and_eval ("ref") + er_ref = py_ref.dereference () # Results in error + py_val = py_ref.referenced_value () # Returns the referenced value + + The 'gdb.Value' object 'py_val' is identical to that corresponding + to 'val'. + + -- Function: Value.dynamic_cast (type) + Like 'Value.cast', but works as if the C++ 'dynamic_cast' operator + were used. Consult a C++ reference for details. + + -- Function: Value.reinterpret_cast (type) + Like 'Value.cast', but works as if the C++ 'reinterpret_cast' + operator were used. Consult a C++ reference for details. + + -- Function: Value.string ([encoding[, errors[, length]]]) + If this 'gdb.Value' represents a string, then this method converts + the contents to a Python string. Otherwise, this method will throw + an exception. + + Strings are recognized in a language-specific way; whether a given + 'gdb.Value' represents a string is determined by the current + language. + + For C-like languages, a value is a string if it is a pointer to or + an array of characters or ints. The string is assumed to be + terminated by a zero of the appropriate width. However if the + optional length argument is given, the string will be converted to + that given length, ignoring any embedded zeros that the string may + contain. + + If the optional ENCODING argument is given, it must be a string + naming the encoding of the string in the 'gdb.Value', such as + '"ascii"', '"iso-8859-6"' or '"utf-8"'. It accepts the same + encodings as the corresponding argument to Python's 'string.decode' + method, and the Python codec machinery will be used to convert the + string. If ENCODING is not given, or if ENCODING is the empty + string, then either the 'target-charset' (*note Character Sets::) + will be used, or a language-specific encoding will be used, if the + current language is able to supply one. + + The optional ERRORS argument is the same as the corresponding + argument to Python's 'string.decode' method. + + If the optional LENGTH argument is given, the string will be + fetched and converted to the given length. + + -- Function: Value.lazy_string ([encoding [, length]]) + If this 'gdb.Value' represents a string, then this method converts + the contents to a 'gdb.LazyString' (*note Lazy Strings In + Python::). Otherwise, this method will throw an exception. + + If the optional ENCODING argument is given, it must be a string + naming the encoding of the 'gdb.LazyString'. Some examples are: + 'ascii', 'iso-8859-6' or 'utf-8'. If the ENCODING argument is an + encoding that GDB does recognize, GDB will raise an error. + + When a lazy string is printed, the GDB encoding machinery is used + to convert the string during printing. If the optional ENCODING + argument is not provided, or is an empty string, GDB will + automatically select the encoding most suitable for the string + type. For further information on encoding in GDB please see *note + Character Sets::. + + If the optional LENGTH argument is given, the string will be + fetched and encoded to the length of characters specified. If the + LENGTH argument is not provided, the string will be fetched and + encoded until a null of appropriate width is found. + + -- Function: Value.fetch_lazy () + If the 'gdb.Value' object is currently a lazy value + ('gdb.Value.is_lazy' is 'True'), then the value is fetched from the + inferior. Any errors that occur in the process will produce a + Python exception. + + If the 'gdb.Value' object is not a lazy value, this method has no + effect. + + This method does not return a value. + + +File: gdb.info, Node: Types In Python, Next: Pretty Printing API, Prev: Values From Inferior, Up: Python API + +23.2.2.4 Types In Python +........................ + +GDB represents types from the inferior using the class 'gdb.Type'. + + The following type-related functions are available in the 'gdb' +module: + + -- Function: gdb.lookup_type (name [, block]) + This function looks up a type by name. NAME is the name of the + type to look up. It must be a string. + + If BLOCK is given, then NAME is looked up in that scope. + Otherwise, it is searched for globally. + + Ordinarily, this function will return an instance of 'gdb.Type'. + If the named type cannot be found, it will throw an exception. + + If the type is a structure or class type, or an enum type, the fields +of that type can be accessed using the Python "dictionary syntax". For +example, if 'some_type' is a 'gdb.Type' instance holding a structure +type, you can access its 'foo' field with: + + bar = some_type['foo'] + + 'bar' will be a 'gdb.Field' object; see below under the description +of the 'Type.fields' method for a description of the 'gdb.Field' class. + + An instance of 'Type' has the following attributes: + + -- Variable: Type.code + The type code for this type. The type code will be one of the + 'TYPE_CODE_' constants defined below. + + -- Variable: Type.name + The name of this type. If this type has no name, then 'None' is + returned. + + -- Variable: Type.sizeof + The size of this type, in target 'char' units. Usually, a target's + 'char' type will be an 8-bit byte. However, on some unusual + platforms, this type may have a different size. + + -- Variable: Type.tag + The tag name for this type. The tag name is the name after + 'struct', 'union', or 'enum' in C and C++; not all languages have + this concept. If this type has no tag name, then 'None' is + returned. + + The following methods are provided: + + -- Function: Type.fields () + For structure and union types, this method returns the fields. + Range types have two fields, the minimum and maximum values. Enum + types have one field per enum constant. Function and method types + have one field per parameter. The base types of C++ classes are + also represented as fields. If the type has no fields, or does not + fit into one of these categories, an empty sequence will be + returned. + + Each field is a 'gdb.Field' object, with some pre-defined + attributes: + 'bitpos' + This attribute is not available for 'enum' or 'static' (as in + C++ or Java) fields. The value is the position, counting in + bits, from the start of the containing type. + + 'enumval' + This attribute is only available for 'enum' fields, and its + value is the enumeration member's integer representation. + + 'name' + The name of the field, or 'None' for anonymous fields. + + 'artificial' + This is 'True' if the field is artificial, usually meaning + that it was provided by the compiler and not the user. This + attribute is always provided, and is 'False' if the field is + not artificial. + + 'is_base_class' + This is 'True' if the field represents a base class of a C++ + structure. This attribute is always provided, and is 'False' + if the field is not a base class of the type that is the + argument of 'fields', or if that type was not a C++ class. + + 'bitsize' + If the field is packed, or is a bitfield, then this will have + a non-zero value, which is the size of the field in bits. + Otherwise, this will be zero; in this case the field's size is + given by its type. + + 'type' + The type of the field. This is usually an instance of 'Type', + but it can be 'None' in some situations. + + 'parent_type' + The type which contains this field. This is an instance of + 'gdb.Type'. + + -- Function: Type.array (N1 [, N2]) + Return a new 'gdb.Type' object which represents an array of this + type. If one argument is given, it is the inclusive upper bound of + the array; in this case the lower bound is zero. If two arguments + are given, the first argument is the lower bound of the array, and + the second argument is the upper bound of the array. An array's + length must not be negative, but the bounds can be. + + -- Function: Type.vector (N1 [, N2]) + Return a new 'gdb.Type' object which represents a vector of this + type. If one argument is given, it is the inclusive upper bound of + the vector; in this case the lower bound is zero. If two arguments + are given, the first argument is the lower bound of the vector, and + the second argument is the upper bound of the vector. A vector's + length must not be negative, but the bounds can be. + + The difference between an 'array' and a 'vector' is that arrays + behave like in C: when used in expressions they decay to a pointer + to the first element whereas vectors are treated as first class + values. + + -- Function: Type.const () + Return a new 'gdb.Type' object which represents a 'const'-qualified + variant of this type. + + -- Function: Type.volatile () + Return a new 'gdb.Type' object which represents a + 'volatile'-qualified variant of this type. + + -- Function: Type.unqualified () + Return a new 'gdb.Type' object which represents an unqualified + variant of this type. That is, the result is neither 'const' nor + 'volatile'. + + -- Function: Type.range () + Return a Python 'Tuple' object that contains two elements: the low + bound of the argument type and the high bound of that type. If the + type does not have a range, GDB will raise a 'gdb.error' exception + (*note Exception Handling::). + + -- Function: Type.reference () + Return a new 'gdb.Type' object which represents a reference to this + type. + + -- Function: Type.pointer () + Return a new 'gdb.Type' object which represents a pointer to this + type. + + -- Function: Type.strip_typedefs () + Return a new 'gdb.Type' that represents the real type, after + removing all layers of typedefs. + + -- Function: Type.target () + Return a new 'gdb.Type' object which represents the target type of + this type. + + For a pointer type, the target type is the type of the pointed-to + object. For an array type (meaning C-like arrays), the target type + is the type of the elements of the array. For a function or method + type, the target type is the type of the return value. For a + complex type, the target type is the type of the elements. For a + typedef, the target type is the aliased type. + + If the type does not have a target, this method will throw an + exception. + + -- Function: Type.template_argument (n [, block]) + If this 'gdb.Type' is an instantiation of a template, this will + return a new 'gdb.Type' which represents the type of the Nth + template argument. + + If this 'gdb.Type' is not a template type, this will throw an + exception. Ordinarily, only C++ code will have template types. + + If BLOCK is given, then NAME is looked up in that scope. + Otherwise, it is searched for globally. + + Each type has a code, which indicates what category this type falls +into. The available type categories are represented by constants +defined in the 'gdb' module: + +'gdb.TYPE_CODE_PTR' + The type is a pointer. + +'gdb.TYPE_CODE_ARRAY' + The type is an array. + +'gdb.TYPE_CODE_STRUCT' + The type is a structure. + +'gdb.TYPE_CODE_UNION' + The type is a union. + +'gdb.TYPE_CODE_ENUM' + The type is an enum. + +'gdb.TYPE_CODE_FLAGS' + A bit flags type, used for things such as status registers. + +'gdb.TYPE_CODE_FUNC' + The type is a function. + +'gdb.TYPE_CODE_INT' + The type is an integer type. + +'gdb.TYPE_CODE_FLT' + A floating point type. + +'gdb.TYPE_CODE_VOID' + The special type 'void'. + +'gdb.TYPE_CODE_SET' + A Pascal set type. + +'gdb.TYPE_CODE_RANGE' + A range type, that is, an integer type with bounds. + +'gdb.TYPE_CODE_STRING' + A string type. Note that this is only used for certain languages + with language-defined string types; C strings are not represented + this way. + +'gdb.TYPE_CODE_BITSTRING' + A string of bits. It is deprecated. + +'gdb.TYPE_CODE_ERROR' + An unknown or erroneous type. + +'gdb.TYPE_CODE_METHOD' + A method type, as found in C++ or Java. + +'gdb.TYPE_CODE_METHODPTR' + A pointer-to-member-function. + +'gdb.TYPE_CODE_MEMBERPTR' + A pointer-to-member. + +'gdb.TYPE_CODE_REF' + A reference type. + +'gdb.TYPE_CODE_CHAR' + A character type. + +'gdb.TYPE_CODE_BOOL' + A boolean type. + +'gdb.TYPE_CODE_COMPLEX' + A complex float type. + +'gdb.TYPE_CODE_TYPEDEF' + A typedef to some other type. + +'gdb.TYPE_CODE_NAMESPACE' + A C++ namespace. + +'gdb.TYPE_CODE_DECFLOAT' + A decimal floating point type. + +'gdb.TYPE_CODE_INTERNAL_FUNCTION' + A function internal to GDB. This is the type used to represent + convenience functions. + + Further support for types is provided in the 'gdb.types' Python +module (*note gdb.types::). + + +File: gdb.info, Node: Pretty Printing API, Next: Selecting Pretty-Printers, Prev: Types In Python, Up: Python API + +23.2.2.5 Pretty Printing API +............................ + +An example output is provided (*note Pretty Printing::). + + A pretty-printer is just an object that holds a value and implements +a specific interface, defined here. + + -- Function: pretty_printer.children (self) + GDB will call this method on a pretty-printer to compute the + children of the pretty-printer's value. + + This method must return an object conforming to the Python iterator + protocol. Each item returned by the iterator must be a tuple + holding two elements. The first element is the "name" of the + child; the second element is the child's value. The value can be + any Python object which is convertible to a GDB value. + + This method is optional. If it does not exist, GDB will act as + though the value has no children. + + -- Function: pretty_printer.display_hint (self) + The CLI may call this method and use its result to change the + formatting of a value. The result will also be supplied to an MI + consumer as a 'displayhint' attribute of the variable being + printed. + + This method is optional. If it does exist, this method must return + a string. + + Some display hints are predefined by GDB: + + 'array' + Indicate that the object being printed is "array-like". The + CLI uses this to respect parameters such as 'set print + elements' and 'set print array'. + + 'map' + Indicate that the object being printed is "map-like", and that + the children of this value can be assumed to alternate between + keys and values. + + 'string' + Indicate that the object being printed is "string-like". If + the printer's 'to_string' method returns a Python string of + some kind, then GDB will call its internal language-specific + string-printing function to format the string. For the CLI + this means adding quotation marks, possibly escaping some + characters, respecting 'set print elements', and the like. + + -- Function: pretty_printer.to_string (self) + GDB will call this method to display the string representation of + the value passed to the object's constructor. + + When printing from the CLI, if the 'to_string' method exists, then + GDB will prepend its result to the values returned by 'children'. + Exactly how this formatting is done is dependent on the display + hint, and may change as more hints are added. Also, depending on + the print settings (*note Print Settings::), the CLI may print just + the result of 'to_string' in a stack trace, omitting the result of + 'children'. + + If this method returns a string, it is printed verbatim. + + Otherwise, if this method returns an instance of 'gdb.Value', then + GDB prints this value. This may result in a call to another + pretty-printer. + + If instead the method returns a Python value which is convertible + to a 'gdb.Value', then GDB performs the conversion and prints the + resulting value. Again, this may result in a call to another + pretty-printer. Python scalars (integers, floats, and booleans) + and strings are convertible to 'gdb.Value'; other types are not. + + Finally, if this method returns 'None' then no further operations + are peformed in this method and nothing is printed. + + If the result is not one of these types, an exception is raised. + + GDB provides a function which can be used to look up the default +pretty-printer for a 'gdb.Value': + + -- Function: gdb.default_visualizer (value) + This function takes a 'gdb.Value' object as an argument. If a + pretty-printer for this value exists, then it is returned. If no + such printer exists, then this returns 'None'. + + +File: gdb.info, Node: Selecting Pretty-Printers, Next: Writing a Pretty-Printer, Prev: Pretty Printing API, Up: Python API + +23.2.2.6 Selecting Pretty-Printers +.................................. + +The Python list 'gdb.pretty_printers' contains an array of functions or +callable objects that have been registered via addition as a +pretty-printer. Printers in this list are called 'global' printers, +they're available when debugging all inferiors. Each 'gdb.Progspace' +contains a 'pretty_printers' attribute. Each 'gdb.Objfile' also +contains a 'pretty_printers' attribute. + + Each function on these lists is passed a single 'gdb.Value' argument +and should return a pretty-printer object conforming to the interface +definition above (*note Pretty Printing API::). If a function cannot +create a pretty-printer for the value, it should return 'None'. + + GDB first checks the 'pretty_printers' attribute of each +'gdb.Objfile' in the current program space and iteratively calls each +enabled lookup routine in the list for that 'gdb.Objfile' until it +receives a pretty-printer object. If no pretty-printer is found in the +objfile lists, GDB then searches the pretty-printer list of the current +program space, calling each enabled function until an object is +returned. After these lists have been exhausted, it tries the global +'gdb.pretty_printers' list, again calling each enabled function until an +object is returned. + + The order in which the objfiles are searched is not specified. For a +given list, functions are always invoked from the head of the list, and +iterated over sequentially until the end of the list, or a printer +object is returned. + + For various reasons a pretty-printer may not work. For example, the +underlying data structure may have changed and the pretty-printer is out +of date. + + The consequences of a broken pretty-printer are severe enough that +GDB provides support for enabling and disabling individual printers. +For example, if 'print frame-arguments' is on, a backtrace can become +highly illegible if any argument is printed with a broken printer. + + Pretty-printers are enabled and disabled by attaching an 'enabled' +attribute to the registered function or callable object. If this +attribute is present and its value is 'False', the printer is disabled, +otherwise the printer is enabled. + + +File: gdb.info, Node: Writing a Pretty-Printer, Next: Type Printing API, Prev: Selecting Pretty-Printers, Up: Python API + +23.2.2.7 Writing a Pretty-Printer +................................. + +A pretty-printer consists of two parts: a lookup function to detect if +the type is supported, and the printer itself. + + Here is an example showing how a 'std::string' printer might be +written. *Note Pretty Printing API::, for details on the API this class +must provide. + + class StdStringPrinter(object): + "Print a std::string" + + def __init__(self, val): + self.val = val + + def to_string(self): + return self.val['_M_dataplus']['_M_p'] + + def display_hint(self): + return 'string' + + And here is an example showing how a lookup function for the printer +example above might be written. + + def str_lookup_function(val): + lookup_tag = val.type.tag + if lookup_tag == None: + return None + regex = re.compile("^std::basic_string$") + if regex.match(lookup_tag): + return StdStringPrinter(val) + return None + + The example lookup function extracts the value's type, and attempts +to match it to a type that it can pretty-print. If it is a type the +printer can pretty-print, it will return a printer object. If not, it +returns 'None'. + + We recommend that you put your core pretty-printers into a Python +package. If your pretty-printers are for use with a library, we further +recommend embedding a version number into the package name. This +practice will enable GDB to load multiple versions of your +pretty-printers at the same time, because they will have different +names. + + You should write auto-loaded code (*note Python Auto-loading::) such +that it can be evaluated multiple times without changing its meaning. +An ideal auto-load file will consist solely of 'import's of your printer +modules, followed by a call to a register pretty-printers with the +current objfile. + + Taken as a whole, this approach will scale nicely to multiple +inferiors, each potentially using a different library version. +Embedding a version number in the Python package name will ensure that +GDB is able to load both sets of printers simultaneously. Then, because +the search for pretty-printers is done by objfile, and because your +auto-loaded code took care to register your library's printers with a +specific objfile, GDB will find the correct printers for the specific +version of the library used by each inferior. + + To continue the 'std::string' example (*note Pretty Printing API::), +this code might appear in 'gdb.libstdcxx.v6': + + def register_printers(objfile): + objfile.pretty_printers.append(str_lookup_function) + +And then the corresponding contents of the auto-load file would be: + + import gdb.libstdcxx.v6 + gdb.libstdcxx.v6.register_printers(gdb.current_objfile()) + + The previous example illustrates a basic pretty-printer. There are a +few things that can be improved on. The printer doesn't have a name, +making it hard to identify in a list of installed printers. The lookup +function has a name, but lookup functions can have arbitrary, even +identical, names. + + Second, the printer only handles one type, whereas a library +typically has several types. One could install a lookup function for +each desired type in the library, but one could also have a single +lookup function recognize several types. The latter is the conventional +way this is handled. If a pretty-printer can handle multiple data +types, then its "subprinters" are the printers for the individual data +types. + + The 'gdb.printing' module provides a formal way of solving these +problems (*note gdb.printing::). Here is another example that handles +multiple types. + + These are the types we are going to pretty-print: + + struct foo { int a, b; }; + struct bar { struct foo x, y; }; + + Here are the printers: + + class fooPrinter: + """Print a foo object.""" + + def __init__(self, val): + self.val = val + + def to_string(self): + return ("a=<" + str(self.val["a"]) + + "> b=<" + str(self.val["b"]) + ">") + + class barPrinter: + """Print a bar object.""" + + def __init__(self, val): + self.val = val + + def to_string(self): + return ("x=<" + str(self.val["x"]) + + "> y=<" + str(self.val["y"]) + ">") + + This example doesn't need a lookup function, that is handled by the +'gdb.printing' module. Instead a function is provided to build up the +object that handles the lookup. + + import gdb.printing + + def build_pretty_printer(): + pp = gdb.printing.RegexpCollectionPrettyPrinter( + "my_library") + pp.add_printer('foo', '^foo$', fooPrinter) + pp.add_printer('bar', '^bar$', barPrinter) + return pp + + And here is the autoload support: + + import gdb.printing + import my_library + gdb.printing.register_pretty_printer( + gdb.current_objfile(), + my_library.build_pretty_printer()) + + Finally, when this printer is loaded into GDB, here is the +corresponding output of 'info pretty-printer': + + (gdb) info pretty-printer + my_library.so: + my_library + foo + bar + + +File: gdb.info, Node: Type Printing API, Next: Frame Filter API, Prev: Writing a Pretty-Printer, Up: Python API + +23.2.2.8 Type Printing API +.......................... + +GDB provides a way for Python code to customize type display. This is +mainly useful for substituting canonical typedef names for types. + + A "type printer" is just a Python object conforming to a certain +protocol. A simple base class implementing the protocol is provided; +see *note gdb.types::. A type printer must supply at least: + + -- Instance Variable of type_printer: enabled + A boolean which is True if the printer is enabled, and False + otherwise. This is manipulated by the 'enable type-printer' and + 'disable type-printer' commands. + + -- Instance Variable of type_printer: name + The name of the type printer. This must be a string. This is used + by the 'enable type-printer' and 'disable type-printer' commands. + + -- Method on type_printer: instantiate (self) + This is called by GDB at the start of type-printing. It is only + called if the type printer is enabled. This method must return a + new object that supplies a 'recognize' method, as described below. + + When displaying a type, say via the 'ptype' command, GDB will compute +a list of type recognizers. This is done by iterating first over the +per-objfile type printers (*note Objfiles In Python::), followed by the +per-progspace type printers (*note Progspaces In Python::), and finally +the global type printers. + + GDB will call the 'instantiate' method of each enabled type printer. +If this method returns 'None', then the result is ignored; otherwise, it +is appended to the list of recognizers. + + Then, when GDB is going to display a type name, it iterates over the +list of recognizers. For each one, it calls the recognition function, +stopping if the function returns a non-'None' value. The recognition +function is defined as: + + -- Method on type_recognizer: recognize (self, type) + If TYPE is not recognized, return 'None'. Otherwise, return a + string which is to be printed as the name of TYPE. TYPE will be an + instance of 'gdb.Type' (*note Types In Python::). + + GDB uses this two-pass approach so that type printers can efficiently +cache information without holding on to it too long. For example, it +can be convenient to look up type information in a type printer and hold +it for a recognizer's lifetime; if a single pass were done then type +printers would have to make use of the event system in order to avoid +holding information that could become stale as the inferior changed. + + +File: gdb.info, Node: Frame Filter API, Next: Frame Decorator API, Prev: Type Printing API, Up: Python API + +23.2.2.9 Filtering Frames. +.......................... + +Frame filters are Python objects that manipulate the visibility of a +frame or frames when a backtrace (*note Backtrace::) is printed by GDB. + + Only commands that print a backtrace, or, in the case of GDB/MI +commands (*note GDB/MI::), those that return a collection of frames are +affected. The commands that work with frame filters are: + + 'backtrace' (*note The backtrace command: backtrace-command.), +'-stack-list-frames' (*note The -stack-list-frames command: +-stack-list-frames.), '-stack-list-variables' (*note The +-stack-list-variables command: -stack-list-variables.), +'-stack-list-arguments' *note The -stack-list-arguments command: +-stack-list-arguments.) and '-stack-list-locals' (*note The +-stack-list-locals command: -stack-list-locals.). + + A frame filter works by taking an iterator as an argument, applying +actions to the contents of that iterator, and returning another iterator +(or, possibly, the same iterator it was provided in the case where the +filter does not perform any operations). Typically, frame filters +utilize tools such as the Python's 'itertools' module to work with and +create new iterators from the source iterator. Regardless of how a +filter chooses to apply actions, it must not alter the underlying GDB +frame or frames, or attempt to alter the call-stack within GDB. This +preserves data integrity within GDB. Frame filters are executed on a +priority basis and care should be taken that some frame filters may have +been executed before, and that some frame filters will be executed +after. + + An important consideration when designing frame filters, and well +worth reflecting upon, is that frame filters should avoid unwinding the +call stack if possible. Some stacks can run very deep, into the tens of +thousands in some cases. To search every frame when a frame filter +executes may be too expensive at that step. The frame filter cannot +know how many frames it has to iterate over, and it may have to iterate +through them all. This ends up duplicating effort as GDB performs this +iteration when it prints the frames. If the filter can defer unwinding +frames until frame decorators are executed, after the last filter has +executed, it should. *Note Frame Decorator API::, for more information +on decorators. Also, there are examples for both frame decorators and +filters in later chapters. *Note Writing a Frame Filter::, for more +information. + + The Python dictionary 'gdb.frame_filters' contains key/object +pairings that comprise a frame filter. Frame filters in this dictionary +are called 'global' frame filters, and they are available when debugging +all inferiors. These frame filters must register with the dictionary +directly. In addition to the 'global' dictionary, there are other +dictionaries that are loaded with different inferiors via auto-loading +(*note Python Auto-loading::). The two other areas where frame filter +dictionaries can be found are: 'gdb.Progspace' which contains a +'frame_filters' dictionary attribute, and each 'gdb.Objfile' object +which also contains a 'frame_filters' dictionary attribute. + + When a command is executed from GDB that is compatible with frame +filters, GDB combines the 'global', 'gdb.Progspace' and all +'gdb.Objfile' dictionaries currently loaded. All of the 'gdb.Objfile' +dictionaries are combined, as several frames, and thus several object +files, might be in use. GDB then prunes any frame filter whose +'enabled' attribute is 'False'. This pruned list is then sorted +according to the 'priority' attribute in each filter. + + Once the dictionaries are combined, pruned and sorted, GDB creates an +iterator which wraps each frame in the call stack in a 'FrameDecorator' +object, and calls each filter in order. The output from the previous +filter will always be the input to the next filter, and so on. + + Frame filters have a mandatory interface which each frame filter must +implement, defined here: + + -- Function: FrameFilter.filter (iterator) + GDB will call this method on a frame filter when it has reached the + order in the priority list for that filter. + + For example, if there are four frame filters: + + Name Priority + + Filter1 5 + Filter2 10 + Filter3 100 + Filter4 1 + + The order that the frame filters will be called is: + + Filter3 -> Filter2 -> Filter1 -> Filter4 + + Note that the output from 'Filter3' is passed to the input of + 'Filter2', and so on. + + This 'filter' method is passed a Python iterator. This iterator + contains a sequence of frame decorators that wrap each 'gdb.Frame', + or a frame decorator that wraps another frame decorator. The first + filter that is executed in the sequence of frame filters will + receive an iterator entirely comprised of default 'FrameDecorator' + objects. However, after each frame filter is executed, the + previous frame filter may have wrapped some or all of the frame + decorators with their own frame decorator. As frame decorators + must also conform to a mandatory interface, these decorators can be + assumed to act in a uniform manner (*note Frame Decorator API::). + + This method must return an object conforming to the Python iterator + protocol. Each item in the iterator must be an object conforming + to the frame decorator interface. If a frame filter does not wish + to perform any operations on this iterator, it should return that + iterator untouched. + + This method is not optional. If it does not exist, GDB will raise + and print an error. + + -- Variable: FrameFilter.name + The 'name' attribute must be Python string which contains the name + of the filter displayed by GDB (*note Frame Filter Management::). + This attribute may contain any combination of letters or numbers. + Care should be taken to ensure that it is unique. This attribute + is mandatory. + + -- Variable: FrameFilter.enabled + The 'enabled' attribute must be Python boolean. This attribute + indicates to GDB whether the frame filter is enabled, and should be + considered when frame filters are executed. If 'enabled' is + 'True', then the frame filter will be executed when any of the + backtrace commands detailed earlier in this chapter are executed. + If 'enabled' is 'False', then the frame filter will not be + executed. This attribute is mandatory. + + -- Variable: FrameFilter.priority + The 'priority' attribute must be Python integer. This attribute + controls the order of execution in relation to other frame filters. + There are no imposed limits on the range of 'priority' other than + it must be a valid integer. The higher the 'priority' attribute, + the sooner the frame filter will be executed in relation to other + frame filters. Although 'priority' can be negative, it is + recommended practice to assume zero is the lowest priority that a + frame filter can be assigned. Frame filters that have the same + priority are executed in unsorted order in that priority slot. + This attribute is mandatory. + + +File: gdb.info, Node: Frame Decorator API, Next: Writing a Frame Filter, Prev: Frame Filter API, Up: Python API + +23.2.2.10 Decorating Frames. +............................ + +Frame decorators are sister objects to frame filters (*note Frame Filter +API::). Frame decorators are applied by a frame filter and can only be +used in conjunction with frame filters. + + The purpose of a frame decorator is to customize the printed content +of each 'gdb.Frame' in commands where frame filters are executed. This +concept is called decorating a frame. Frame decorators decorate a +'gdb.Frame' with Python code contained within each API call. This +separates the actual data contained in a 'gdb.Frame' from the decorated +data produced by a frame decorator. This abstraction is necessary to +maintain integrity of the data contained in each 'gdb.Frame'. + + Frame decorators have a mandatory interface, defined below. + + GDB already contains a frame decorator called 'FrameDecorator'. This +contains substantial amounts of boilerplate code to decorate the content +of a 'gdb.Frame'. It is recommended that other frame decorators inherit +and extend this object, and only to override the methods needed. + + -- Function: FrameDecorator.elided (self) + + The 'elided' method groups frames together in a hierarchical + system. An example would be an interpreter, where multiple + low-level frames make up a single call in the interpreted language. + In this example, the frame filter would elide the low-level frames + and present a single high-level frame, representing the call in the + interpreted language, to the user. + + The 'elided' function must return an iterable and this iterable + must contain the frames that are being elided wrapped in a suitable + frame decorator. If no frames are being elided this function may + return an empty iterable, or 'None'. Elided frames are indented + from normal frames in a 'CLI' backtrace, or in the case of + 'GDB/MI', are placed in the 'children' field of the eliding frame. + + It is the frame filter's task to also filter out the elided frames + from the source iterator. This will avoid printing the frame + twice. + + -- Function: FrameDecorator.function (self) + + This method returns the name of the function in the frame that is + to be printed. + + This method must return a Python string describing the function, or + 'None'. + + If this function returns 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.address (self) + + This method returns the address of the frame that is to be printed. + + This method must return a Python numeric integer type of sufficient + size to describe the address of the frame, or 'None'. + + If this function returns a 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.filename (self) + + This method returns the filename and path associated with this + frame. + + This method must return a Python string containing the filename and + the path to the object file backing the frame, or 'None'. + + If this function returns a 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.line (self): + + This method returns the line number associated with the current + position within the function addressed by this frame. + + This method must return a Python integer type, or 'None'. + + If this function returns a 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.frame_args (self) + + This method must return an iterable, or 'None'. Returning an empty + iterable, or 'None' means frame arguments will not be printed for + this frame. This iterable must contain objects that implement two + methods, described here. + + This object must implement a 'argument' method which takes a single + 'self' parameter and must return a 'gdb.Symbol' (*note Symbols In + Python::), or a Python string. The object must also implement a + 'value' method which takes a single 'self' parameter and must + return a 'gdb.Value' (*note Values From Inferior::), a Python + value, or 'None'. If the 'value' method returns 'None', and the + 'argument' method returns a 'gdb.Symbol', GDB will look-up and + print the value of the 'gdb.Symbol' automatically. + + A brief example: + + class SymValueWrapper(): + + def __init__(self, symbol, value): + self.sym = symbol + self.val = value + + def value(self): + return self.val + + def symbol(self): + return self.sym + + class SomeFrameDecorator() + ... + ... + def frame_args(self): + args = [] + try: + block = self.inferior_frame.block() + except: + return None + + # Iterate over all symbols in a block. Only add + # symbols that are arguments. + for sym in block: + if not sym.is_argument: + continue + args.append(SymValueWrapper(sym,None)) + + # Add example synthetic argument. + args.append(SymValueWrapper(``foo'', 42)) + + return args + + -- Function: FrameDecorator.frame_locals (self) + + This method must return an iterable or 'None'. Returning an empty + iterable, or 'None' means frame local arguments will not be printed + for this frame. + + The object interface, the description of the various strategies for + reading frame locals, and the example are largely similar to those + described in the 'frame_args' function, (*note The frame filter + frame_args function: frame_args.). Below is a modified example: + + class SomeFrameDecorator() + ... + ... + def frame_locals(self): + vars = [] + try: + block = self.inferior_frame.block() + except: + return None + + # Iterate over all symbols in a block. Add all + # symbols, except arguments. + for sym in block: + if sym.is_argument: + continue + vars.append(SymValueWrapper(sym,None)) + + # Add an example of a synthetic local variable. + vars.append(SymValueWrapper(``bar'', 99)) + + return vars + + -- Function: FrameDecorator.inferior_frame (self): + + This method must return the underlying 'gdb.Frame' that this frame + decorator is decorating. GDB requires the underlying frame for + internal frame information to determine how to print certain values + when printing a frame. + + +File: gdb.info, Node: Writing a Frame Filter, Next: Inferiors In Python, Prev: Frame Decorator API, Up: Python API + +23.2.2.11 Writing a Frame Filter +................................ + +There are three basic elements that a frame filter must implement: it +must correctly implement the documented interface (*note Frame Filter +API::), it must register itself with GDB, and finally, it must decide if +it is to work on the data provided by GDB. In all cases, whether it +works on the iterator or not, each frame filter must return an iterator. +A bare-bones frame filter follows the pattern in the following example. + + import gdb + + class FrameFilter(): + + def __init__(self): + # Frame filter attribute creation. + # + # 'name' is the name of the filter that GDB will display. + # + # 'priority' is the priority of the filter relative to other + # filters. + # + # 'enabled' is a boolean that indicates whether this filter is + # enabled and should be executed. + + self.name = "Foo" + self.priority = 100 + self.enabled = True + + # Register this frame filter with the global frame_filters + # dictionary. + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + # Just return the iterator. + return frame_iter + + The frame filter in the example above implements the three +requirements for all frame filters. It implements the API, self +registers, and makes a decision on the iterator (in this case, it just +returns the iterator untouched). + + The first step is attribute creation and assignment, and as shown in +the comments the filter assigns the following attributes: 'name', +'priority' and whether the filter should be enabled with the 'enabled' +attribute. + + The second step is registering the frame filter with the dictionary +or dictionaries that the frame filter has interest in. As shown in the +comments, this filter just registers itself with the global dictionary +'gdb.frame_filters'. As noted earlier, 'gdb.frame_filters' is a +dictionary that is initialized in the 'gdb' module when GDB starts. +What dictionary a filter registers with is an important consideration. +Generally, if a filter is specific to a set of code, it should be +registered either in the 'objfile' or 'progspace' dictionaries as they +are specific to the program currently loaded in GDB. The global +dictionary is always present in GDB and is never unloaded. Any filters +registered with the global dictionary will exist until GDB exits. To +avoid filters that may conflict, it is generally better to register +frame filters against the dictionaries that more closely align with the +usage of the filter currently in question. *Note Python Auto-loading::, +for further information on auto-loading Python scripts. + + GDB takes a hands-off approach to frame filter registration, +therefore it is the frame filter's responsibility to ensure registration +has occurred, and that any exceptions are handled appropriately. In +particular, you may wish to handle exceptions relating to Python +dictionary key uniqueness. It is mandatory that the dictionary key is +the same as frame filter's 'name' attribute. When a user manages frame +filters (*note Frame Filter Management::), the names GDB will display +are those contained in the 'name' attribute. + + The final step of this example is the implementation of the 'filter' +method. As shown in the example comments, we define the 'filter' method +and note that the method must take an iterator, and also must return an +iterator. In this bare-bones example, the frame filter is not very +useful as it just returns the iterator untouched. However this is a +valid operation for frame filters that have the 'enabled' attribute set, +but decide not to operate on any frames. + + In the next example, the frame filter operates on all frames and +utilizes a frame decorator to perform some work on the frames. *Note +Frame Decorator API::, for further information on the frame decorator +interface. + + This example works on inlined frames. It highlights frames which are +inlined by tagging them with an "[inlined]" tag. By applying a frame +decorator to all frames with the Python 'itertools imap' method, the +example defers actions to the frame decorator. Frame decorators are +only processed when GDB prints the backtrace. + + This introduces a new decision making topic: whether to perform +decision making operations at the filtering step, or at the printing +step. In this example's approach, it does not perform any filtering +decisions at the filtering step beyond mapping a frame decorator to each +frame. This allows the actual decision making to be performed when each +frame is printed. This is an important consideration, and well worth +reflecting upon when designing a frame filter. An issue that frame +filters should avoid is unwinding the stack if possible. Some stacks +can run very deep, into the tens of thousands in some cases. To search +every frame to determine if it is inlined ahead of time may be too +expensive at the filtering step. The frame filter cannot know how many +frames it has to iterate over, and it would have to iterate through them +all. This ends up duplicating effort as GDB performs this iteration +when it prints the frames. + + In this example decision making can be deferred to the printing step. +As each frame is printed, the frame decorator can examine each frame in +turn when GDB iterates. From a performance viewpoint, this is the most +appropriate decision to make as it avoids duplicating the effort that +the printing step would undertake anyway. Also, if there are many frame +filters unwinding the stack during filtering, it can substantially delay +the printing of the backtrace which will result in large memory usage, +and a poor user experience. + + class InlineFilter(): + + def __init__(self): + self.name = "InlinedFrameFilter" + self.priority = 100 + self.enabled = True + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + frame_iter = itertools.imap(InlinedFrameDecorator, + frame_iter) + return frame_iter + + This frame filter is somewhat similar to the earlier example, except +that the 'filter' method applies a frame decorator object called +'InlinedFrameDecorator' to each element in the iterator. The 'imap' +Python method is light-weight. It does not proactively iterate over the +iterator, but rather creates a new iterator which wraps the existing +one. + + Below is the frame decorator for this example. + + class InlinedFrameDecorator(FrameDecorator): + + def __init__(self, fobj): + super(InlinedFrameDecorator, self).__init__(fobj) + + def function(self): + frame = fobj.inferior_frame() + name = str(frame.name()) + + if frame.type() == gdb.INLINE_FRAME: + name = name + " [inlined]" + + return name + + This frame decorator only defines and overrides the 'function' +method. It lets the supplied 'FrameDecorator', which is shipped with +GDB, perform the other work associated with printing this frame. + + The combination of these two objects create this output from a +backtrace: + + #0 0x004004e0 in bar () at inline.c:11 + #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21 + #2 0x00400566 in main () at inline.c:31 + + So in the case of this example, a frame decorator is applied to all +frames, regardless of whether they may be inlined or not. As GDB +iterates over the iterator produced by the frame filters, GDB executes +each frame decorator which then makes a decision on what to print in the +'function' callback. Using a strategy like this is a way to defer +decisions on the frame content to printing time. + +Eliding Frames +-------------- + +It might be that the above example is not desirable for representing +inlined frames, and a hierarchical approach may be preferred. If we +want to hierarchically represent frames, the 'elided' frame decorator +interface might be preferable. + + This example approaches the issue with the 'elided' method. This +example is quite long, but very simplistic. It is out-of-scope for this +section to write a complete example that comprehensively covers all +approaches of finding and printing inlined frames. However, this +example illustrates the approach an author might use. + + This example comprises of three sections. + + class InlineFrameFilter(): + + def __init__(self): + self.name = "InlinedFrameFilter" + self.priority = 100 + self.enabled = True + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + return ElidingInlineIterator(frame_iter) + + This frame filter is very similar to the other examples. The only +difference is this frame filter is wrapping the iterator provided to it +('frame_iter') with a custom iterator called 'ElidingInlineIterator'. +This again defers actions to when GDB prints the backtrace, as the +iterator is not traversed until printing. + + The iterator for this example is as follows. It is in this section +of the example where decisions are made on the content of the backtrace. + + class ElidingInlineIterator: + def __init__(self, ii): + self.input_iterator = ii + + def __iter__(self): + return self + + def next(self): + frame = next(self.input_iterator) + + if frame.inferior_frame().type() != gdb.INLINE_FRAME: + return frame + + try: + eliding_frame = next(self.input_iterator) + except StopIteration: + return frame + return ElidingFrameDecorator(eliding_frame, [frame]) + + This iterator implements the Python iterator protocol. When the +'next' function is called (when GDB prints each frame), the iterator +checks if this frame decorator, 'frame', is wrapping an inlined frame. +If it is not, it returns the existing frame decorator untouched. If it +is wrapping an inlined frame, it assumes that the inlined frame was +contained within the next oldest frame, 'eliding_frame', which it +fetches. It then creates and returns a frame decorator, +'ElidingFrameDecorator', which contains both the elided frame, and the +eliding frame. + + class ElidingInlineDecorator(FrameDecorator): + + def __init__(self, frame, elided_frames): + super(ElidingInlineDecorator, self).__init__(frame) + self.frame = frame + self.elided_frames = elided_frames + + def elided(self): + return iter(self.elided_frames) + + This frame decorator overrides one function and returns the inlined +frame in the 'elided' method. As before it lets 'FrameDecorator' do the +rest of the work involved in printing this frame. This produces the +following output. + + #0 0x004004e0 in bar () at inline.c:11 + #2 0x00400529 in main () at inline.c:25 + #1 0x00400529 in max (b=6, a=12) at inline.c:15 + + In that output, 'max' which has been inlined into 'main' is printed +hierarchically. Another approach would be to combine the 'function' +method, and the 'elided' method to both print a marker in the inlined +frame, and also show the hierarchical relationship. + + +File: gdb.info, Node: Inferiors In Python, Next: Events In Python, Prev: Writing a Frame Filter, Up: Python API + +23.2.2.12 Inferiors In Python +............................. + +Programs which are being run under GDB are called inferiors (*note +Inferiors and Programs::). Python scripts can access information about +and manipulate inferiors controlled by GDB via objects of the +'gdb.Inferior' class. + + The following inferior-related functions are available in the 'gdb' +module: + + -- Function: gdb.inferiors () + Return a tuple containing all inferior objects. + + -- Function: gdb.selected_inferior () + Return an object representing the current inferior. + + A 'gdb.Inferior' object has the following attributes: + + -- Variable: Inferior.num + ID of inferior, as assigned by GDB. + + -- Variable: Inferior.pid + Process ID of the inferior, as assigned by the underlying operating + system. + + -- Variable: Inferior.was_attached + Boolean signaling whether the inferior was created using 'attach', + or started by GDB itself. + + A 'gdb.Inferior' object has the following methods: + + -- Function: Inferior.is_valid () + Returns 'True' if the 'gdb.Inferior' object is valid, 'False' if + not. A 'gdb.Inferior' object will become invalid if the inferior + no longer exists within GDB. All other 'gdb.Inferior' methods will + throw an exception if it is invalid at the time the method is + called. + + -- Function: Inferior.threads () + This method returns a tuple holding all the threads which are valid + when it is called. If there are no valid threads, the method will + return an empty tuple. + + -- Function: Inferior.read_memory (address, length) + Read LENGTH bytes of memory from the inferior, starting at ADDRESS. + Returns a buffer object, which behaves much like an array or a + string. It can be modified and given to the + 'Inferior.write_memory' function. In 'Python' 3, the return value + is a 'memoryview' object. + + -- Function: Inferior.write_memory (address, buffer [, length]) + Write the contents of BUFFER to the inferior, starting at ADDRESS. + The BUFFER parameter must be a Python object which supports the + buffer protocol, i.e., a string, an array or the object returned + from 'Inferior.read_memory'. If given, LENGTH determines the + number of bytes from BUFFER to be written. + + -- Function: Inferior.search_memory (address, length, pattern) + Search a region of the inferior memory starting at ADDRESS with the + given LENGTH using the search pattern supplied in PATTERN. The + PATTERN parameter must be a Python object which supports the buffer + protocol, i.e., a string, an array or the object returned from + 'gdb.read_memory'. Returns a Python 'Long' containing the address + where the pattern was found, or 'None' if the pattern could not be + found. + + +File: gdb.info, Node: Events In Python, Next: Threads In Python, Prev: Inferiors In Python, Up: Python API + +23.2.2.13 Events In Python +.......................... + +GDB provides a general event facility so that Python code can be +notified of various state changes, particularly changes that occur in +the inferior. + + An "event" is just an object that describes some state change. The +type of the object and its attributes will vary depending on the details +of the change. All the existing events are described below. + + In order to be notified of an event, you must register an event +handler with an "event registry". An event registry is an object in the +'gdb.events' module which dispatches particular events. A registry +provides methods to register and unregister event handlers: + + -- Function: EventRegistry.connect (object) + Add the given callable OBJECT to the registry. This object will be + called when an event corresponding to this registry occurs. + + -- Function: EventRegistry.disconnect (object) + Remove the given OBJECT from the registry. Once removed, the + object will no longer receive notifications of events. + + Here is an example: + + def exit_handler (event): + print "event type: exit" + print "exit code: %d" % (event.exit_code) + + gdb.events.exited.connect (exit_handler) + + In the above example we connect our handler 'exit_handler' to the +registry 'events.exited'. Once connected, 'exit_handler' gets called +when the inferior exits. The argument "event" in this example is of +type 'gdb.ExitedEvent'. As you can see in the example the 'ExitedEvent' +object has an attribute which indicates the exit code of the inferior. + + The following is a listing of the event registries that are available +and details of the events they emit: + +'events.cont' + Emits 'gdb.ThreadEvent'. + + Some events can be thread specific when GDB is running in non-stop + mode. When represented in Python, these events all extend + 'gdb.ThreadEvent'. Note, this event is not emitted directly; + instead, events which are emitted by this or other modules might + extend this event. Examples of these events are + 'gdb.BreakpointEvent' and 'gdb.ContinueEvent'. + + -- Variable: ThreadEvent.inferior_thread + In non-stop mode this attribute will be set to the specific + thread which was involved in the emitted event. Otherwise, it + will be set to 'None'. + + Emits 'gdb.ContinueEvent' which extends 'gdb.ThreadEvent'. + + This event indicates that the inferior has been continued after a + stop. For inherited attribute refer to 'gdb.ThreadEvent' above. + +'events.exited' + Emits 'events.ExitedEvent' which indicates that the inferior has + exited. 'events.ExitedEvent' has two attributes: + -- Variable: ExitedEvent.exit_code + An integer representing the exit code, if available, which the + inferior has returned. (The exit code could be unavailable + if, for example, GDB detaches from the inferior.) If the exit + code is unavailable, the attribute does not exist. + -- Variable: ExitedEvent inferior + A reference to the inferior which triggered the 'exited' + event. + +'events.stop' + Emits 'gdb.StopEvent' which extends 'gdb.ThreadEvent'. + + Indicates that the inferior has stopped. All events emitted by + this registry extend StopEvent. As a child of 'gdb.ThreadEvent', + 'gdb.StopEvent' will indicate the stopped thread when GDB is + running in non-stop mode. Refer to 'gdb.ThreadEvent' above for + more details. + + Emits 'gdb.SignalEvent' which extends 'gdb.StopEvent'. + + This event indicates that the inferior or one of its threads has + received as signal. 'gdb.SignalEvent' has the following + attributes: + + -- Variable: SignalEvent.stop_signal + A string representing the signal received by the inferior. A + list of possible signal values can be obtained by running the + command 'info signals' in the GDB command prompt. + + Also emits 'gdb.BreakpointEvent' which extends 'gdb.StopEvent'. + + 'gdb.BreakpointEvent' event indicates that one or more breakpoints + have been hit, and has the following attributes: + + -- Variable: BreakpointEvent.breakpoints + A sequence containing references to all the breakpoints (type + 'gdb.Breakpoint') that were hit. *Note Breakpoints In + Python::, for details of the 'gdb.Breakpoint' object. + -- Variable: BreakpointEvent.breakpoint + A reference to the first breakpoint that was hit. This + function is maintained for backward compatibility and is now + deprecated in favor of the 'gdb.BreakpointEvent.breakpoints' + attribute. + +'events.new_objfile' + Emits 'gdb.NewObjFileEvent' which indicates that a new object file + has been loaded by GDB. 'gdb.NewObjFileEvent' has one attribute: + + -- Variable: NewObjFileEvent.new_objfile + A reference to the object file ('gdb.Objfile') which has been + loaded. *Note Objfiles In Python::, for details of the + 'gdb.Objfile' object. + + +File: gdb.info, Node: Threads In Python, Next: Commands In Python, Prev: Events In Python, Up: Python API + +23.2.2.14 Threads In Python +........................... + +Python scripts can access information about, and manipulate inferior +threads controlled by GDB, via objects of the 'gdb.InferiorThread' +class. + + The following thread-related functions are available in the 'gdb' +module: + + -- Function: gdb.selected_thread () + This function returns the thread object for the selected thread. + If there is no selected thread, this will return 'None'. + + A 'gdb.InferiorThread' object has the following attributes: + + -- Variable: InferiorThread.name + The name of the thread. If the user specified a name using 'thread + name', then this returns that name. Otherwise, if an OS-supplied + name is available, then it is returned. Otherwise, this returns + 'None'. + + This attribute can be assigned to. The new value must be a string + object, which sets the new name, or 'None', which removes any + user-specified thread name. + + -- Variable: InferiorThread.num + ID of the thread, as assigned by GDB. + + -- Variable: InferiorThread.ptid + ID of the thread, as assigned by the operating system. This + attribute is a tuple containing three integers. The first is the + Process ID (PID); the second is the Lightweight Process ID (LWPID), + and the third is the Thread ID (TID). Either the LWPID or TID may + be 0, which indicates that the operating system does not use that + identifier. + + A 'gdb.InferiorThread' object has the following methods: + + -- Function: InferiorThread.is_valid () + Returns 'True' if the 'gdb.InferiorThread' object is valid, 'False' + if not. A 'gdb.InferiorThread' object will become invalid if the + thread exits, or the inferior that the thread belongs is deleted. + All other 'gdb.InferiorThread' methods will throw an exception if + it is invalid at the time the method is called. + + -- Function: InferiorThread.switch () + This changes GDB's currently selected thread to the one represented + by this object. + + -- Function: InferiorThread.is_stopped () + Return a Boolean indicating whether the thread is stopped. + + -- Function: InferiorThread.is_running () + Return a Boolean indicating whether the thread is running. + + -- Function: InferiorThread.is_exited () + Return a Boolean indicating whether the thread is exited. + + +File: gdb.info, Node: Commands In Python, Next: Parameters In Python, Prev: Threads In Python, Up: Python API + +23.2.2.15 Commands In Python +............................ + +You can implement new GDB CLI commands in Python. A CLI command is +implemented using an instance of the 'gdb.Command' class, most commonly +using a subclass. + + -- Function: Command.__init__ (name, COMMAND_CLASS [, COMPLETER_CLASS + [, PREFIX]]) + The object initializer for 'Command' registers the new command with + GDB. This initializer is normally invoked from the subclass' own + '__init__' method. + + NAME is the name of the command. If NAME consists of multiple + words, then the initial words are looked for as prefix commands. + In this case, if one of the prefix commands does not exist, an + exception is raised. + + There is no support for multi-line commands. + + COMMAND_CLASS should be one of the 'COMMAND_' constants defined + below. This argument tells GDB how to categorize the new command + in the help system. + + COMPLETER_CLASS is an optional argument. If given, it should be + one of the 'COMPLETE_' constants defined below. This argument + tells GDB how to perform completion for this command. If not + given, GDB will attempt to complete using the object's 'complete' + method (see below); if no such method is found, an error will occur + when completion is attempted. + + PREFIX is an optional argument. If 'True', then the new command is + a prefix command; sub-commands of this command may be registered. + + The help text for the new command is taken from the Python + documentation string for the command's class, if there is one. If + no documentation string is provided, the default value "This + command is not documented." is used. + + -- Function: Command.dont_repeat () + By default, a GDB command is repeated when the user enters a blank + line at the command prompt. A command can suppress this behavior + by invoking the 'dont_repeat' method. This is similar to the user + command 'dont-repeat', see *note dont-repeat: Define. + + -- Function: Command.invoke (argument, from_tty) + This method is called by GDB when this command is invoked. + + ARGUMENT is a string. It is the argument to the command, after + leading and trailing whitespace has been stripped. + + FROM_TTY is a boolean argument. When true, this means that the + command was entered by the user at the terminal; when false it + means that the command came from elsewhere. + + If this method throws an exception, it is turned into a GDB 'error' + call. Otherwise, the return value is ignored. + + To break ARGUMENT up into an argv-like string use + 'gdb.string_to_argv'. This function behaves identically to GDB's + internal argument lexer 'buildargv'. It is recommended to use this + for consistency. Arguments are separated by spaces and may be + quoted. Example: + + print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") + ['1', '2 "3', '4 "5', "6 '7"] + + -- Function: Command.complete (text, word) + This method is called by GDB when the user attempts completion on + this command. All forms of completion are handled by this method, + that is, the and key bindings (*note Completion::), and + the 'complete' command (*note complete: Help.). + + The arguments TEXT and WORD are both strings. TEXT holds the + complete command line up to the cursor's location. WORD holds the + last word of the command line; this is computed using a + word-breaking heuristic. + + The 'complete' method can return several values: + * If the return value is a sequence, the contents of the + sequence are used as the completions. It is up to 'complete' + to ensure that the contents actually do complete the word. A + zero-length sequence is allowed, it means that there were no + completions available. Only string elements of the sequence + are used; other elements in the sequence are ignored. + + * If the return value is one of the 'COMPLETE_' constants + defined below, then the corresponding GDB-internal completion + function is invoked, and its result is used. + + * All other results are treated as though there were no + available completions. + + When a new command is registered, it must be declared as a member of +some general class of commands. This is used to classify top-level +commands in the on-line help system; note that prefix commands are not +listed under their own category but rather that of their top-level +command. The available classifications are represented by constants +defined in the 'gdb' module: + +'gdb.COMMAND_NONE' + The command does not belong to any particular class. A command in + this category will not be displayed in any of the help categories. + +'gdb.COMMAND_RUNNING' + The command is related to running the inferior. For example, + 'start', 'step', and 'continue' are in this category. Type 'help + running' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_DATA' + The command is related to data or variables. For example, 'call', + 'find', and 'print' are in this category. Type 'help data' at the + GDB prompt to see a list of commands in this category. + +'gdb.COMMAND_STACK' + The command has to do with manipulation of the stack. For example, + 'backtrace', 'frame', and 'return' are in this category. Type + 'help stack' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_FILES' + This class is used for file-related commands. For example, 'file', + 'list' and 'section' are in this category. Type 'help files' at + the GDB prompt to see a list of commands in this category. + +'gdb.COMMAND_SUPPORT' + This should be used for "support facilities", generally meaning + things that are useful to the user when interacting with GDB, but + not related to the state of the inferior. For example, 'help', + 'make', and 'shell' are in this category. Type 'help support' at + the GDB prompt to see a list of commands in this category. + +'gdb.COMMAND_STATUS' + The command is an 'info'-related command, that is, related to the + state of GDB itself. For example, 'info', 'macro', and 'show' are + in this category. Type 'help status' at the GDB prompt to see a + list of commands in this category. + +'gdb.COMMAND_BREAKPOINTS' + The command has to do with breakpoints. For example, 'break', + 'clear', and 'delete' are in this category. Type 'help + breakpoints' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_TRACEPOINTS' + The command has to do with tracepoints. For example, 'trace', + 'actions', and 'tfind' are in this category. Type 'help + tracepoints' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_USER' + The command is a general purpose command for the user, and + typically does not fit in one of the other categories. Type 'help + user-defined' at the GDB prompt to see a list of commands in this + category, as well as the list of gdb macros (*note Sequences::). + +'gdb.COMMAND_OBSCURE' + The command is only used in unusual circumstances, or is not of + general interest to users. For example, 'checkpoint', 'fork', and + 'stop' are in this category. Type 'help obscure' at the GDB prompt + to see a list of commands in this category. + +'gdb.COMMAND_MAINTENANCE' + The command is only useful to GDB maintainers. The 'maintenance' + and 'flushregs' commands are in this category. Type 'help + internals' at the GDB prompt to see a list of commands in this + category. + + A new command can use a predefined completion function, either by +specifying it via an argument at initialization, or by returning it from +the 'complete' method. These predefined completion constants are all +defined in the 'gdb' module: + +'gdb.COMPLETE_NONE' + This constant means that no completion should be done. + +'gdb.COMPLETE_FILENAME' + This constant means that filename completion should be performed. + +'gdb.COMPLETE_LOCATION' + This constant means that location completion should be done. *Note + Specify Location::. + +'gdb.COMPLETE_COMMAND' + This constant means that completion should examine GDB command + names. + +'gdb.COMPLETE_SYMBOL' + This constant means that completion should be done using symbol + names as the source. + +'gdb.COMPLETE_EXPRESSION' + This constant means that completion should be done on expressions. + Often this means completing on symbol names, but some language + parsers also have support for completing on field names. + + The following code snippet shows how a trivial CLI command can be +implemented in Python: + + class HelloWorld (gdb.Command): + """Greet the whole world.""" + + def __init__ (self): + super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) + + def invoke (self, arg, from_tty): + print "Hello, World!" + + HelloWorld () + + The last line instantiates the class, and is necessary to trigger the +registration of the command with GDB. Depending on how the Python code +is read into GDB, you may need to import the 'gdb' module explicitly. + + +File: gdb.info, Node: Parameters In Python, Next: Functions In Python, Prev: Commands In Python, Up: Python API + +23.2.2.16 Parameters In Python +.............................. + +You can implement new GDB parameters using Python. A new parameter is +implemented as an instance of the 'gdb.Parameter' class. + + Parameters are exposed to the user via the 'set' and 'show' commands. +*Note Help::. + + There are many parameters that already exist and can be set in GDB. +Two examples are: 'set follow fork' and 'set charset'. Setting these +parameters influences certain behavior in GDB. Similarly, you can +define parameters that can be used to influence behavior in custom +Python scripts and commands. + + -- Function: Parameter.__init__ (name, COMMAND-CLASS, PARAMETER-CLASS + [, ENUM-SEQUENCE]) + The object initializer for 'Parameter' registers the new parameter + with GDB. This initializer is normally invoked from the subclass' + own '__init__' method. + + NAME is the name of the new parameter. If NAME consists of + multiple words, then the initial words are looked for as prefix + parameters. An example of this can be illustrated with the 'set + print' set of parameters. If NAME is 'print foo', then 'print' + will be searched as the prefix parameter. In this case the + parameter can subsequently be accessed in GDB as 'set print foo'. + + If NAME consists of multiple words, and no prefix parameter group + can be found, an exception is raised. + + COMMAND-CLASS should be one of the 'COMMAND_' constants (*note + Commands In Python::). This argument tells GDB how to categorize + the new parameter in the help system. + + PARAMETER-CLASS should be one of the 'PARAM_' constants defined + below. This argument tells GDB the type of the new parameter; this + information is used for input validation and completion. + + If PARAMETER-CLASS is 'PARAM_ENUM', then ENUM-SEQUENCE must be a + sequence of strings. These strings represent the possible values + for the parameter. + + If PARAMETER-CLASS is not 'PARAM_ENUM', then the presence of a + fourth argument will cause an exception to be thrown. + + The help text for the new parameter is taken from the Python + documentation string for the parameter's class, if there is one. + If there is no documentation string, a default value is used. + + -- Variable: Parameter.set_doc + If this attribute exists, and is a string, then its value is used + as the help text for this parameter's 'set' command. The value is + examined when 'Parameter.__init__' is invoked; subsequent changes + have no effect. + + -- Variable: Parameter.show_doc + If this attribute exists, and is a string, then its value is used + as the help text for this parameter's 'show' command. The value is + examined when 'Parameter.__init__' is invoked; subsequent changes + have no effect. + + -- Variable: Parameter.value + The 'value' attribute holds the underlying value of the parameter. + It can be read and assigned to just as any other attribute. GDB + does validation when assignments are made. + + There are two methods that should be implemented in any 'Parameter' +class. These are: + + -- Function: Parameter.get_set_string (self) + GDB will call this method when a PARAMETER's value has been changed + via the 'set' API (for example, 'set foo off'). The 'value' + attribute has already been populated with the new value and may be + used in output. This method must return a string. + + -- Function: Parameter.get_show_string (self, svalue) + GDB will call this method when a PARAMETER's 'show' API has been + invoked (for example, 'show foo'). The argument 'svalue' receives + the string representation of the current value. This method must + return a string. + + When a new parameter is defined, its type must be specified. The +available types are represented by constants defined in the 'gdb' +module: + +'gdb.PARAM_BOOLEAN' + The value is a plain boolean. The Python boolean values, 'True' + and 'False' are the only valid values. + +'gdb.PARAM_AUTO_BOOLEAN' + The value has three possible states: true, false, and 'auto'. In + Python, true and false are represented using boolean constants, and + 'auto' is represented using 'None'. + +'gdb.PARAM_UINTEGER' + The value is an unsigned integer. The value of 0 should be + interpreted to mean "unlimited". + +'gdb.PARAM_INTEGER' + The value is a signed integer. The value of 0 should be + interpreted to mean "unlimited". + +'gdb.PARAM_STRING' + The value is a string. When the user modifies the string, any + escape sequences, such as '\t', '\f', and octal escapes, are + translated into corresponding characters and encoded into the + current host charset. + +'gdb.PARAM_STRING_NOESCAPE' + The value is a string. When the user modifies the string, escapes + are passed through untranslated. + +'gdb.PARAM_OPTIONAL_FILENAME' + The value is a either a filename (a string), or 'None'. + +'gdb.PARAM_FILENAME' + The value is a filename. This is just like + 'PARAM_STRING_NOESCAPE', but uses file names for completion. + +'gdb.PARAM_ZINTEGER' + The value is an integer. This is like 'PARAM_INTEGER', except 0 is + interpreted as itself. + +'gdb.PARAM_ENUM' + The value is a string, which must be one of a collection string + constants provided when the parameter is created. + + +File: gdb.info, Node: Functions In Python, Next: Progspaces In Python, Prev: Parameters In Python, Up: Python API + +23.2.2.17 Writing new convenience functions +........................................... + +You can implement new convenience functions (*note Convenience Vars::) +in Python. A convenience function is an instance of a subclass of the +class 'gdb.Function'. + + -- Function: Function.__init__ (name) + The initializer for 'Function' registers the new function with GDB. + The argument NAME is the name of the function, a string. The + function will be visible to the user as a convenience variable of + type 'internal function', whose name is the same as the given NAME. + + The documentation for the new function is taken from the + documentation string for the new class. + + -- Function: Function.invoke (*ARGS) + When a convenience function is evaluated, its arguments are + converted to instances of 'gdb.Value', and then the function's + 'invoke' method is called. Note that GDB does not predetermine the + arity of convenience functions. Instead, all available arguments + are passed to 'invoke', following the standard Python calling + convention. In particular, a convenience function can have default + values for parameters without ill effect. + + The return value of this method is used as its value in the + enclosing expression. If an ordinary Python value is returned, it + is converted to a 'gdb.Value' following the usual rules. + + The following code snippet shows how a trivial convenience function +can be implemented in Python: + + class Greet (gdb.Function): + """Return string to greet someone. + Takes a name as argument.""" + + def __init__ (self): + super (Greet, self).__init__ ("greet") + + def invoke (self, name): + return "Hello, %s!" % name.string () + + Greet () + + The last line instantiates the class, and is necessary to trigger the +registration of the function with GDB. Depending on how the Python code +is read into GDB, you may need to import the 'gdb' module explicitly. + + Now you can use the function in an expression: + + (gdb) print $greet("Bob") + $1 = "Hello, Bob!" + + +File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API + +23.2.2.18 Program Spaces In Python +.................................. + +A program space, or "progspace", represents a symbolic view of an +address space. It consists of all of the objfiles of the program. +*Note Objfiles In Python::. *Note program spaces: Inferiors and +Programs, for more details about program spaces. + + The following progspace-related functions are available in the 'gdb' +module: + + -- Function: gdb.current_progspace () + This function returns the program space of the currently selected + inferior. *Note Inferiors and Programs::. + + -- Function: gdb.progspaces () + Return a sequence of all the progspaces currently known to GDB. + + Each progspace is represented by an instance of the 'gdb.Progspace' +class. + + -- Variable: Progspace.filename + The file name of the progspace as a string. + + -- Variable: Progspace.pretty_printers + The 'pretty_printers' attribute is a list of functions. It is used + to look up pretty-printers. A 'Value' is passed to each function + in order; if the function returns 'None', then the search + continues. Otherwise, the return value should be an object which + is used to format the value. *Note Pretty Printing API::, for more + information. + + -- Variable: Progspace.type_printers + The 'type_printers' attribute is a list of type printer objects. + *Note Type Printing API::, for more information. + + -- Variable: Progspace.frame_filters + The 'frame_filters' attribute is a dictionary of frame filter + objects. *Note Frame Filter API::, for more information. + + +File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API + +23.2.2.19 Objfiles In Python +............................ + +GDB loads symbols for an inferior from various symbol-containing files +(*note Files::). These include the primary executable file, any shared +libraries used by the inferior, and any separate debug info files (*note +Separate Debug Files::). GDB calls these symbol-containing files +"objfiles". + + The following objfile-related functions are available in the 'gdb' +module: + + -- Function: gdb.current_objfile () + When auto-loading a Python script (*note Python Auto-loading::), + GDB sets the "current objfile" to the corresponding objfile. This + function returns the current objfile. If there is no current + objfile, this function returns 'None'. + + -- Function: gdb.objfiles () + Return a sequence of all the objfiles current known to GDB. *Note + Objfiles In Python::. + + Each objfile is represented by an instance of the 'gdb.Objfile' +class. + + -- Variable: Objfile.filename + The file name of the objfile as a string. + + -- Variable: Objfile.pretty_printers + The 'pretty_printers' attribute is a list of functions. It is used + to look up pretty-printers. A 'Value' is passed to each function + in order; if the function returns 'None', then the search + continues. Otherwise, the return value should be an object which + is used to format the value. *Note Pretty Printing API::, for more + information. + + -- Variable: Objfile.type_printers + The 'type_printers' attribute is a list of type printer objects. + *Note Type Printing API::, for more information. + + -- Variable: Objfile.frame_filters + The 'frame_filters' attribute is a dictionary of frame filter + objects. *Note Frame Filter API::, for more information. + + A 'gdb.Objfile' object has the following methods: + + -- Function: Objfile.is_valid () + Returns 'True' if the 'gdb.Objfile' object is valid, 'False' if + not. A 'gdb.Objfile' object can become invalid if the object file + it refers to is not loaded in GDB any longer. All other + 'gdb.Objfile' methods will throw an exception if it is invalid at + the time the method is called. + + +File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API + +23.2.2.20 Accessing inferior stack frames from Python. +...................................................... + +When the debugged program stops, GDB is able to analyze its call stack +(*note Stack frames: Frames.). The 'gdb.Frame' class represents a frame +in the stack. A 'gdb.Frame' object is only valid while its +corresponding frame exists in the inferior's stack. If you try to use +an invalid frame object, GDB will throw a 'gdb.error' exception (*note +Exception Handling::). + + Two 'gdb.Frame' objects can be compared for equality with the '==' +operator, like: + + (gdb) python print gdb.newest_frame() == gdb.selected_frame () + True + + The following frame-related functions are available in the 'gdb' +module: + + -- Function: gdb.selected_frame () + Return the selected frame object. (*note Selecting a Frame: + Selection.). + + -- Function: gdb.newest_frame () + Return the newest frame object for the selected thread. + + -- Function: gdb.frame_stop_reason_string (reason) + Return a string explaining the reason why GDB stopped unwinding + frames, as expressed by the given REASON code (an integer, see the + 'unwind_stop_reason' method further down in this section). + + A 'gdb.Frame' object has the following methods: + + -- Function: Frame.is_valid () + Returns true if the 'gdb.Frame' object is valid, false if not. A + frame object can become invalid if the frame it refers to doesn't + exist anymore in the inferior. All 'gdb.Frame' methods will throw + an exception if it is invalid at the time the method is called. + + -- Function: Frame.name () + Returns the function name of the frame, or 'None' if it can't be + obtained. + + -- Function: Frame.architecture () + Returns the 'gdb.Architecture' object corresponding to the frame's + architecture. *Note Architectures In Python::. + + -- Function: Frame.type () + Returns the type of the frame. The value can be one of: + 'gdb.NORMAL_FRAME' + An ordinary stack frame. + + 'gdb.DUMMY_FRAME' + A fake stack frame that was created by GDB when performing an + inferior function call. + + 'gdb.INLINE_FRAME' + A frame representing an inlined function. The function was + inlined into a 'gdb.NORMAL_FRAME' that is older than this one. + + 'gdb.TAILCALL_FRAME' + A frame representing a tail call. *Note Tail Call Frames::. + + 'gdb.SIGTRAMP_FRAME' + A signal trampoline frame. This is the frame created by the + OS when it calls into a signal handler. + + 'gdb.ARCH_FRAME' + A fake stack frame representing a cross-architecture call. + + 'gdb.SENTINEL_FRAME' + This is like 'gdb.NORMAL_FRAME', but it is only used for the + newest frame. + + -- Function: Frame.unwind_stop_reason () + Return an integer representing the reason why it's not possible to + find more frames toward the outermost frame. Use + 'gdb.frame_stop_reason_string' to convert the value returned by + this function to a string. The value can be one of: + + 'gdb.FRAME_UNWIND_NO_REASON' + No particular reason (older frames should be available). + + 'gdb.FRAME_UNWIND_NULL_ID' + The previous frame's analyzer returns an invalid result. This + is no longer used by GDB, and is kept only for backward + compatibility. + + 'gdb.FRAME_UNWIND_OUTERMOST' + This frame is the outermost. + + 'gdb.FRAME_UNWIND_UNAVAILABLE' + Cannot unwind further, because that would require knowing the + values of registers or memory that have not been collected. + + 'gdb.FRAME_UNWIND_INNER_ID' + This frame ID looks like it ought to belong to a NEXT frame, + but we got it for a PREV frame. Normally, this is a sign of + unwinder failure. It could also indicate stack corruption. + + 'gdb.FRAME_UNWIND_SAME_ID' + This frame has the same ID as the previous one. That means + that unwinding further would almost certainly give us another + frame with exactly the same ID, so break the chain. Normally, + this is a sign of unwinder failure. It could also indicate + stack corruption. + + 'gdb.FRAME_UNWIND_NO_SAVED_PC' + The frame unwinder did not find any saved PC, but we needed + one to unwind further. + + 'gdb.FRAME_UNWIND_FIRST_ERROR' + Any stop reason greater or equal to this value indicates some + kind of error. This special value facilitates writing code + that tests for errors in unwinding in a way that will work + correctly even if the list of the other values is modified in + future GDB versions. Using it, you could write: + reason = gdb.selected_frame().unwind_stop_reason () + reason_str = gdb.frame_stop_reason_string (reason) + if reason >= gdb.FRAME_UNWIND_FIRST_ERROR: + print "An error occured: %s" % reason_str + + -- Function: Frame.pc () + Returns the frame's resume address. + + -- Function: Frame.block () + Return the frame's code block. *Note Blocks In Python::. + + -- Function: Frame.function () + Return the symbol for the function corresponding to this frame. + *Note Symbols In Python::. + + -- Function: Frame.older () + Return the frame that called this frame. + + -- Function: Frame.newer () + Return the frame called by this frame. + + -- Function: Frame.find_sal () + Return the frame's symtab and line object. *Note Symbol Tables In + Python::. + + -- Function: Frame.read_var (variable [, block]) + Return the value of VARIABLE in this frame. If the optional + argument BLOCK is provided, search for the variable from that + block; otherwise start at the frame's current block (which is + determined by the frame's current program counter). VARIABLE must + be a string or a 'gdb.Symbol' object. BLOCK must be a 'gdb.Block' + object. + + -- Function: Frame.select () + Set this frame to be the selected frame. *Note Examining the + Stack: Stack. + + +File: gdb.info, Node: Blocks In Python, Next: Symbols In Python, Prev: Frames In Python, Up: Python API + +23.2.2.21 Accessing blocks from Python. +....................................... + +In GDB, symbols are stored in blocks. A block corresponds roughly to a +scope in the source code. Blocks are organized hierarchically, and are +represented individually in Python as a 'gdb.Block'. Blocks rely on +debugging information being available. + + A frame has a block. Please see *note Frames In Python::, for a more +in-depth discussion of frames. + + The outermost block is known as the "global block". The global block +typically holds public global variables and functions. + + The block nested just inside the global block is the "static block". +The static block typically holds file-scoped variables and functions. + + GDB provides a method to get a block's superblock, but there is +currently no way to examine the sub-blocks of a block, or to iterate +over all the blocks in a symbol table (*note Symbol Tables In Python::). + + Here is a short example that should help explain blocks: + + /* This is in the global block. */ + int global; + + /* This is in the static block. */ + static int file_scope; + + /* 'function' is in the global block, and 'argument' is + in a block nested inside of 'function'. */ + int function (int argument) + { + /* 'local' is in a block inside 'function'. It may or may + not be in the same block as 'argument'. */ + int local; + + { + /* 'inner' is in a block whose superblock is the one holding + 'local'. */ + int inner; + + /* If this call is expanded by the compiler, you may see + a nested block here whose function is 'inline_function' + and whose superblock is the one holding 'inner'. */ + inline_function (); + } + } + + A 'gdb.Block' is iterable. The iterator returns the symbols (*note +Symbols In Python::) local to the block. Python programs should not +assume that a specific block object will always contain a given symbol, +since changes in GDB features and infrastructure may cause symbols move +across blocks in a symbol table. + + The following block-related functions are available in the 'gdb' +module: + + -- Function: gdb.block_for_pc (pc) + Return the innermost 'gdb.Block' containing the given PC value. If + the block cannot be found for the PC value specified, the function + will return 'None'. + + A 'gdb.Block' object has the following methods: + + -- Function: Block.is_valid () + Returns 'True' if the 'gdb.Block' object is valid, 'False' if not. + A block object can become invalid if the block it refers to doesn't + exist anymore in the inferior. All other 'gdb.Block' methods will + throw an exception if it is invalid at the time the method is + called. The block's validity is also checked during iteration over + symbols of the block. + + A 'gdb.Block' object has the following attributes: + + -- Variable: Block.start + The start address of the block. This attribute is not writable. + + -- Variable: Block.end + The end address of the block. This attribute is not writable. + + -- Variable: Block.function + The name of the block represented as a 'gdb.Symbol'. If the block + is not named, then this attribute holds 'None'. This attribute is + not writable. + + For ordinary function blocks, the superblock is the static block. + However, you should note that it is possible for a function block + to have a superblock that is not the static block - for instance + this happens for an inlined function. + + -- Variable: Block.superblock + The block containing this block. If this parent block does not + exist, this attribute holds 'None'. This attribute is not + writable. + + -- Variable: Block.global_block + The global block associated with this block. This attribute is not + writable. + + -- Variable: Block.static_block + The static block associated with this block. This attribute is not + writable. + + -- Variable: Block.is_global + 'True' if the 'gdb.Block' object is a global block, 'False' if not. + This attribute is not writable. + + -- Variable: Block.is_static + 'True' if the 'gdb.Block' object is a static block, 'False' if not. + This attribute is not writable. + + +File: gdb.info, Node: Symbols In Python, Next: Symbol Tables In Python, Prev: Blocks In Python, Up: Python API + +23.2.2.22 Python representation of Symbols. +........................................... + +GDB represents every variable, function and type as an entry in a symbol +table. *Note Examining the Symbol Table: Symbols. Similarly, Python +represents these symbols in GDB with the 'gdb.Symbol' object. + + The following symbol-related functions are available in the 'gdb' +module: + + -- Function: gdb.lookup_symbol (name [, block [, domain]]) + This function searches for a symbol by name. The search scope can + be restricted to the parameters defined in the optional domain and + block arguments. + + NAME is the name of the symbol. It must be a string. The optional + BLOCK argument restricts the search to symbols visible in that + BLOCK. The BLOCK argument must be a 'gdb.Block' object. If + omitted, the block for the current frame is used. The optional + DOMAIN argument restricts the search to the domain type. The + DOMAIN argument must be a domain constant defined in the 'gdb' + module and described later in this chapter. + + The result is a tuple of two elements. The first element is a + 'gdb.Symbol' object or 'None' if the symbol is not found. If the + symbol is found, the second element is 'True' if the symbol is a + field of a method's object (e.g., 'this' in C++), otherwise it is + 'False'. If the symbol is not found, the second element is + 'False'. + + -- Function: gdb.lookup_global_symbol (name [, domain]) + This function searches for a global symbol by name. The search + scope can be restricted to by the domain argument. + + NAME is the name of the symbol. It must be a string. The optional + DOMAIN argument restricts the search to the domain type. The + DOMAIN argument must be a domain constant defined in the 'gdb' + module and described later in this chapter. + + The result is a 'gdb.Symbol' object or 'None' if the symbol is not + found. + + A 'gdb.Symbol' object has the following attributes: + + -- Variable: Symbol.type + The type of the symbol or 'None' if no type is recorded. This + attribute is represented as a 'gdb.Type' object. *Note Types In + Python::. This attribute is not writable. + + -- Variable: Symbol.symtab + The symbol table in which the symbol appears. This attribute is + represented as a 'gdb.Symtab' object. *Note Symbol Tables In + Python::. This attribute is not writable. + + -- Variable: Symbol.line + The line number in the source code at which the symbol was defined. + This is an integer. + + -- Variable: Symbol.name + The name of the symbol as a string. This attribute is not + writable. + + -- Variable: Symbol.linkage_name + The name of the symbol, as used by the linker (i.e., may be + mangled). This attribute is not writable. + + -- Variable: Symbol.print_name + The name of the symbol in a form suitable for output. This is + either 'name' or 'linkage_name', depending on whether the user + asked GDB to display demangled or mangled names. + + -- Variable: Symbol.addr_class + The address class of the symbol. This classifies how to find the + value of a symbol. Each address class is a constant defined in the + 'gdb' module and described later in this chapter. + + -- Variable: Symbol.needs_frame + This is 'True' if evaluating this symbol's value requires a frame + (*note Frames In Python::) and 'False' otherwise. Typically, local + variables will require a frame, but other symbols will not. + + -- Variable: Symbol.is_argument + 'True' if the symbol is an argument of a function. + + -- Variable: Symbol.is_constant + 'True' if the symbol is a constant. + + -- Variable: Symbol.is_function + 'True' if the symbol is a function or a method. + + -- Variable: Symbol.is_variable + 'True' if the symbol is a variable. + + A 'gdb.Symbol' object has the following methods: + + -- Function: Symbol.is_valid () + Returns 'True' if the 'gdb.Symbol' object is valid, 'False' if not. + A 'gdb.Symbol' object can become invalid if the symbol it refers to + does not exist in GDB any longer. All other 'gdb.Symbol' methods + will throw an exception if it is invalid at the time the method is + called. + + -- Function: Symbol.value ([frame]) + Compute the value of the symbol, as a 'gdb.Value'. For functions, + this computes the address of the function, cast to the appropriate + type. If the symbol requires a frame in order to compute its + value, then FRAME must be given. If FRAME is not given, or if + FRAME is invalid, then this method will throw an exception. + + The available domain categories in 'gdb.Symbol' are represented as +constants in the 'gdb' module: + +'gdb.SYMBOL_UNDEF_DOMAIN' + This is used when a domain has not been discovered or none of the + following domains apply. This usually indicates an error either in + the symbol information or in GDB's handling of symbols. +'gdb.SYMBOL_VAR_DOMAIN' + This domain contains variables, function names, typedef names and + enum type values. +'gdb.SYMBOL_STRUCT_DOMAIN' + This domain holds struct, union and enum type names. +'gdb.SYMBOL_LABEL_DOMAIN' + This domain contains names of labels (for gotos). +'gdb.SYMBOL_VARIABLES_DOMAIN' + This domain holds a subset of the 'SYMBOLS_VAR_DOMAIN'; it contains + everything minus functions and types. +'gdb.SYMBOL_FUNCTION_DOMAIN' + This domain contains all functions. +'gdb.SYMBOL_TYPES_DOMAIN' + This domain contains all types. + + The available address class categories in 'gdb.Symbol' are +represented as constants in the 'gdb' module: + +'gdb.SYMBOL_LOC_UNDEF' + If this is returned by address class, it indicates an error either + in the symbol information or in GDB's handling of symbols. +'gdb.SYMBOL_LOC_CONST' + Value is constant int. +'gdb.SYMBOL_LOC_STATIC' + Value is at a fixed address. +'gdb.SYMBOL_LOC_REGISTER' + Value is in a register. +'gdb.SYMBOL_LOC_ARG' + Value is an argument. This value is at the offset stored within + the symbol inside the frame's argument list. +'gdb.SYMBOL_LOC_REF_ARG' + Value address is stored in the frame's argument list. Just like + 'LOC_ARG' except that the value's address is stored at the offset, + not the value itself. +'gdb.SYMBOL_LOC_REGPARM_ADDR' + Value is a specified register. Just like 'LOC_REGISTER' except the + register holds the address of the argument instead of the argument + itself. +'gdb.SYMBOL_LOC_LOCAL' + Value is a local variable. +'gdb.SYMBOL_LOC_TYPEDEF' + Value not used. Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all + have this class. +'gdb.SYMBOL_LOC_BLOCK' + Value is a block. +'gdb.SYMBOL_LOC_CONST_BYTES' + Value is a byte-sequence. +'gdb.SYMBOL_LOC_UNRESOLVED' + Value is at a fixed address, but the address of the variable has to + be determined from the minimal symbol table whenever the variable + is referenced. +'gdb.SYMBOL_LOC_OPTIMIZED_OUT' + The value does not actually exist in the program. +'gdb.SYMBOL_LOC_COMPUTED' + The value's address is a computed location. + + +File: gdb.info, Node: Symbol Tables In Python, Next: Line Tables In Python, Prev: Symbols In Python, Up: Python API + +23.2.2.23 Symbol table representation in Python. +................................................ + +Access to symbol table data maintained by GDB on the inferior is exposed +to Python via two objects: 'gdb.Symtab_and_line' and 'gdb.Symtab'. +Symbol table and line data for a frame is returned from the 'find_sal' +method in 'gdb.Frame' object. *Note Frames In Python::. + + For more information on GDB's symbol table management, see *note +Examining the Symbol Table: Symbols, for more information. + + A 'gdb.Symtab_and_line' object has the following attributes: + + -- Variable: Symtab_and_line.symtab + The symbol table object ('gdb.Symtab') for this frame. This + attribute is not writable. + + -- Variable: Symtab_and_line.pc + Indicates the start of the address range occupied by code for the + current source line. This attribute is not writable. + + -- Variable: Symtab_and_line.last + Indicates the end of the address range occupied by code for the + current source line. This attribute is not writable. + + -- Variable: Symtab_and_line.line + Indicates the current line number for this object. This attribute + is not writable. + + A 'gdb.Symtab_and_line' object has the following methods: + + -- Function: Symtab_and_line.is_valid () + Returns 'True' if the 'gdb.Symtab_and_line' object is valid, + 'False' if not. A 'gdb.Symtab_and_line' object can become invalid + if the Symbol table and line object it refers to does not exist in + GDB any longer. All other 'gdb.Symtab_and_line' methods will throw + an exception if it is invalid at the time the method is called. + + A 'gdb.Symtab' object has the following attributes: + + -- Variable: Symtab.filename + The symbol table's source filename. This attribute is not + writable. + + -- Variable: Symtab.objfile + The symbol table's backing object file. *Note Objfiles In + Python::. This attribute is not writable. + + A 'gdb.Symtab' object has the following methods: + + -- Function: Symtab.is_valid () + Returns 'True' if the 'gdb.Symtab' object is valid, 'False' if not. + A 'gdb.Symtab' object can become invalid if the symbol table it + refers to does not exist in GDB any longer. All other 'gdb.Symtab' + methods will throw an exception if it is invalid at the time the + method is called. + + -- Function: Symtab.fullname () + Return the symbol table's source absolute file name. + + -- Function: Symtab.global_block () + Return the global block of the underlying symbol table. *Note + Blocks In Python::. + + -- Function: Symtab.static_block () + Return the static block of the underlying symbol table. *Note + Blocks In Python::. + + -- Function: Symtab.linetable () + Return the line table associated with the symbol table. *Note Line + Tables In Python::. + + +File: gdb.info, Node: Line Tables In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API + +23.2.2.24 Manipulating line tables using Python +............................................... + +Python code can request and inspect line table information from a symbol +table that is loaded in GDB. A line table is a mapping of source lines +to their executable locations in memory. To acquire the line table +information for a particular symbol table, use the 'linetable' function +(*note Symbol Tables In Python::). + + A 'gdb.LineTable' is iterable. The iterator returns 'LineTableEntry' +objects that correspond to the source line and address for each line +table entry. 'LineTableEntry' objects have the following attributes: + + -- Variable: LineTableEntry.line + The source line number for this line table entry. This number + corresponds to the actual line of source. This attribute is not + writable. + + -- Variable: LineTableEntry.pc + The address that is associated with the line table entry where the + executable code for that source line resides in memory. This + attribute is not writable. + + As there can be multiple addresses for a single source line, you may +receive multiple 'LineTableEntry' objects with matching 'line' +attributes, but with different 'pc' attributes. The iterator is sorted +in ascending 'pc' order. Here is a small example illustrating iterating +over a line table. + + symtab = gdb.selected_frame().find_sal().symtab + linetable = symtab.linetable() + for line in linetable: + print "Line: "+str(line.line)+" Address: "+hex(line.pc) + + This will have the following output: + + Line: 33 Address: 0x4005c8L + Line: 37 Address: 0x4005caL + Line: 39 Address: 0x4005d2L + Line: 40 Address: 0x4005f8L + Line: 42 Address: 0x4005ffL + Line: 44 Address: 0x400608L + Line: 42 Address: 0x40060cL + Line: 45 Address: 0x400615L + + In addition to being able to iterate over a 'LineTable', it also has +the following direct access methods: + + -- Function: LineTable.line (line) + Return a Python 'Tuple' of 'LineTableEntry' objects for any entries + in the line table for the given LINE. LINE refers to the source + code line. If there are no entries for that source code LINE, the + Python 'None' is returned. + + -- Function: LineTable.has_line (line) + Return a Python 'Boolean' indicating whether there is an entry in + the line table for this source line. Return 'True' if an entry is + found, or 'False' if not. + + -- Function: LineTable.source_lines () + Return a Python 'List' of the source line numbers in the symbol + table. Only lines with executable code locations are returned. + The contents of the 'List' will just be the source line entries + represented as Python 'Long' values. + + +File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Python, Prev: Line Tables In Python, Up: Python API + +23.2.2.25 Manipulating breakpoints using Python +............................................... + +Python code can manipulate breakpoints via the 'gdb.Breakpoint' class. + + -- Function: Breakpoint.__init__ (spec [, type [, wp_class [,internal + [,temporary]]]]) + Create a new breakpoint. SPEC is a string naming the location of + the breakpoint, or an expression that defines a watchpoint. The + contents can be any location recognized by the 'break' command, or + in the case of a watchpoint, by the 'watch' command. The optional + TYPE denotes the breakpoint to create from the types defined later + in this chapter. This argument can be either: 'gdb.BP_BREAKPOINT' + or 'gdb.BP_WATCHPOINT'. TYPE defaults to 'gdb.BP_BREAKPOINT'. The + optional INTERNAL argument allows the breakpoint to become + invisible to the user. The breakpoint will neither be reported + when created, nor will it be listed in the output from 'info + breakpoints' (but will be listed with the 'maint info breakpoints' + command). The optional TEMPORARY argument makes the breakpoint a + temporary breakpoint. Temporary breakpoints are deleted after they + have been hit. Any further access to the Python breakpoint after + it has been hit will result in a runtime error (as that breakpoint + has now been automatically deleted). The optional WP_CLASS + argument defines the class of watchpoint to create, if TYPE is + 'gdb.BP_WATCHPOINT'. If a watchpoint class is not provided, it is + assumed to be a 'gdb.WP_WRITE' class. + + -- Function: Breakpoint.stop (self) + The 'gdb.Breakpoint' class can be sub-classed and, in particular, + you may choose to implement the 'stop' method. If this method is + defined in a sub-class of 'gdb.Breakpoint', it will be called when + the inferior reaches any location of a breakpoint which + instantiates that sub-class. If the method returns 'True', the + inferior will be stopped at the location of the breakpoint, + otherwise the inferior will continue. + + If there are multiple breakpoints at the same location with a + 'stop' method, each one will be called regardless of the return + status of the previous. This ensures that all 'stop' methods have + a chance to execute at that location. In this scenario if one of + the methods returns 'True' but the others return 'False', the + inferior will still be stopped. + + You should not alter the execution state of the inferior (i.e., + step, next, etc.), alter the current frame context (i.e., change + the current active frame), or alter, add or delete any breakpoint. + As a general rule, you should not alter any data within GDB or the + inferior at this time. + + Example 'stop' implementation: + + class MyBreakpoint (gdb.Breakpoint): + def stop (self): + inf_val = gdb.parse_and_eval("foo") + if inf_val == 3: + return True + return False + + The available watchpoint types represented by constants are defined +in the 'gdb' module: + +'gdb.WP_READ' + Read only watchpoint. + +'gdb.WP_WRITE' + Write only watchpoint. + +'gdb.WP_ACCESS' + Read/Write watchpoint. + + -- Function: Breakpoint.is_valid () + Return 'True' if this 'Breakpoint' object is valid, 'False' + otherwise. A 'Breakpoint' object can become invalid if the user + deletes the breakpoint. In this case, the object still exists, but + the underlying breakpoint does not. In the cases of watchpoint + scope, the watchpoint remains valid even if execution of the + inferior leaves the scope of that watchpoint. + + -- Function: Breakpoint.delete + Permanently deletes the GDB breakpoint. This also invalidates the + Python 'Breakpoint' object. Any further access to this object's + attributes or methods will raise an error. + + -- Variable: Breakpoint.enabled + This attribute is 'True' if the breakpoint is enabled, and 'False' + otherwise. This attribute is writable. + + -- Variable: Breakpoint.silent + This attribute is 'True' if the breakpoint is silent, and 'False' + otherwise. This attribute is writable. + + Note that a breakpoint can also be silent if it has commands and + the first command is 'silent'. This is not reported by the + 'silent' attribute. + + -- Variable: Breakpoint.thread + If the breakpoint is thread-specific, this attribute holds the + thread id. If the breakpoint is not thread-specific, this + attribute is 'None'. This attribute is writable. + + -- Variable: Breakpoint.task + If the breakpoint is Ada task-specific, this attribute holds the + Ada task id. If the breakpoint is not task-specific (or the + underlying language is not Ada), this attribute is 'None'. This + attribute is writable. + + -- Variable: Breakpoint.ignore_count + This attribute holds the ignore count for the breakpoint, an + integer. This attribute is writable. + + -- Variable: Breakpoint.number + This attribute holds the breakpoint's number -- the identifier used + by the user to manipulate the breakpoint. This attribute is not + writable. + + -- Variable: Breakpoint.type + This attribute holds the breakpoint's type -- the identifier used + to determine the actual breakpoint type or use-case. This + attribute is not writable. + + -- Variable: Breakpoint.visible + This attribute tells whether the breakpoint is visible to the user + when set, or when the 'info breakpoints' command is run. This + attribute is not writable. + + -- Variable: Breakpoint.temporary + This attribute indicates whether the breakpoint was created as a + temporary breakpoint. Temporary breakpoints are automatically + deleted after that breakpoint has been hit. Access to this + attribute, and all other attributes and functions other than the + 'is_valid' function, will result in an error after the breakpoint + has been hit (as it has been automatically deleted). This + attribute is not writable. + + The available types are represented by constants defined in the 'gdb' +module: + +'gdb.BP_BREAKPOINT' + Normal code breakpoint. + +'gdb.BP_WATCHPOINT' + Watchpoint breakpoint. + +'gdb.BP_HARDWARE_WATCHPOINT' + Hardware assisted watchpoint. + +'gdb.BP_READ_WATCHPOINT' + Hardware assisted read watchpoint. + +'gdb.BP_ACCESS_WATCHPOINT' + Hardware assisted access watchpoint. + + -- Variable: Breakpoint.hit_count + This attribute holds the hit count for the breakpoint, an integer. + This attribute is writable, but currently it can only be set to + zero. + + -- Variable: Breakpoint.location + This attribute holds the location of the breakpoint, as specified + by the user. It is a string. If the breakpoint does not have a + location (that is, it is a watchpoint) the attribute's value is + 'None'. This attribute is not writable. + + -- Variable: Breakpoint.expression + This attribute holds a breakpoint expression, as specified by the + user. It is a string. If the breakpoint does not have an + expression (the breakpoint is not a watchpoint) the attribute's + value is 'None'. This attribute is not writable. + + -- Variable: Breakpoint.condition + This attribute holds the condition of the breakpoint, as specified + by the user. It is a string. If there is no condition, this + attribute's value is 'None'. This attribute is writable. + + -- Variable: Breakpoint.commands + This attribute holds the commands attached to the breakpoint. If + there are commands, this attribute's value is a string holding all + the commands, separated by newlines. If there are no commands, + this attribute is 'None'. This attribute is not writable. + + +File: gdb.info, Node: Finish Breakpoints in Python, Next: Lazy Strings In Python, Prev: Breakpoints In Python, Up: Python API + +23.2.2.26 Finish Breakpoints +............................ + +A finish breakpoint is a temporary breakpoint set at the return address +of a frame, based on the 'finish' command. 'gdb.FinishBreakpoint' +extends 'gdb.Breakpoint'. The underlying breakpoint will be disabled +and deleted when the execution will run out of the breakpoint scope +(i.e. 'Breakpoint.stop' or 'FinishBreakpoint.out_of_scope' triggered). +Finish breakpoints are thread specific and must be create with the right +thread selected. + + -- Function: FinishBreakpoint.__init__ ([frame] [, internal]) + Create a finish breakpoint at the return address of the 'gdb.Frame' + object FRAME. If FRAME is not provided, this defaults to the + newest frame. The optional INTERNAL argument allows the breakpoint + to become invisible to the user. *Note Breakpoints In Python::, + for further details about this argument. + + -- Function: FinishBreakpoint.out_of_scope (self) + In some circumstances (e.g. 'longjmp', C++ exceptions, GDB 'return' + command, ...), a function may not properly terminate, and thus + never hit the finish breakpoint. When GDB notices such a + situation, the 'out_of_scope' callback will be triggered. + + You may want to sub-class 'gdb.FinishBreakpoint' and override this + method: + + class MyFinishBreakpoint (gdb.FinishBreakpoint) + def stop (self): + print "normal finish" + return True + + def out_of_scope (): + print "abnormal finish" + + -- Variable: FinishBreakpoint.return_value + When GDB is stopped at a finish breakpoint and the frame used to + build the 'gdb.FinishBreakpoint' object had debug symbols, this + attribute will contain a 'gdb.Value' object corresponding to the + return value of the function. The value will be 'None' if the + function return type is 'void' or if the return value was not + computable. This attribute is not writable. + + +File: gdb.info, Node: Lazy Strings In Python, Next: Architectures In Python, Prev: Finish Breakpoints in Python, Up: Python API + +23.2.2.27 Python representation of lazy strings. +................................................ + +A "lazy string" is a string whose contents is not retrieved or encoded +until it is needed. + + A 'gdb.LazyString' is represented in GDB as an 'address' that points +to a region of memory, an 'encoding' that will be used to encode that +region of memory, and a 'length' to delimit the region of memory that +represents the string. The difference between a 'gdb.LazyString' and a +string wrapped within a 'gdb.Value' is that a 'gdb.LazyString' will be +treated differently by GDB when printing. A 'gdb.LazyString' is +retrieved and encoded during printing, while a 'gdb.Value' wrapping a +string is immediately retrieved and encoded on creation. + + A 'gdb.LazyString' object has the following functions: + + -- Function: LazyString.value () + Convert the 'gdb.LazyString' to a 'gdb.Value'. This value will + point to the string in memory, but will lose all the delayed + retrieval, encoding and handling that GDB applies to a + 'gdb.LazyString'. + + -- Variable: LazyString.address + This attribute holds the address of the string. This attribute is + not writable. + + -- Variable: LazyString.length + This attribute holds the length of the string in characters. If + the length is -1, then the string will be fetched and encoded up to + the first null of appropriate width. This attribute is not + writable. + + -- Variable: LazyString.encoding + This attribute holds the encoding that will be applied to the + string when the string is printed by GDB. If the encoding is not + set, or contains an empty string, then GDB will select the most + appropriate encoding when the string is printed. This attribute is + not writable. + + -- Variable: LazyString.type + This attribute holds the type that is represented by the lazy + string's type. For a lazy string this will always be a pointer + type. To resolve this to the lazy string's character type, use the + type's 'target' method. *Note Types In Python::. This attribute + is not writable. + + +File: gdb.info, Node: Architectures In Python, Prev: Lazy Strings In Python, Up: Python API + +23.2.2.28 Python representation of architectures +................................................ + +GDB uses architecture specific parameters and artifacts in a number of +its various computations. An architecture is represented by an instance +of the 'gdb.Architecture' class. + + A 'gdb.Architecture' class has the following methods: + + -- Function: Architecture.name () + Return the name (string value) of the architecture. + + -- Function: Architecture.disassemble (START_PC [, END_PC [, COUNT]]) + Return a list of disassembled instructions starting from the memory + address START_PC. The optional arguments END_PC and COUNT + determine the number of instructions in the returned list. If both + the optional arguments END_PC and COUNT are specified, then a list + of at most COUNT disassembled instructions whose start address + falls in the closed memory address interval from START_PC to END_PC + are returned. If END_PC is not specified, but COUNT is specified, + then COUNT number of instructions starting from the address + START_PC are returned. If COUNT is not specified but END_PC is + specified, then all instructions whose start address falls in the + closed memory address interval from START_PC to END_PC are + returned. If neither END_PC nor COUNT are specified, then a single + instruction at START_PC is returned. For all of these cases, each + element of the returned list is a Python 'dict' with the following + string keys: + + 'addr' + The value corresponding to this key is a Python long integer + capturing the memory address of the instruction. + + 'asm' + The value corresponding to this key is a string value which + represents the instruction with assembly language mnemonics. + The assembly language flavor used is the same as that + specified by the current CLI variable 'disassembly-flavor'. + *Note Machine Code::. + + 'length' + The value corresponding to this key is the length (integer + value) of the instruction in bytes. + + +File: gdb.info, Node: Python Auto-loading, Next: Python modules, Prev: Python API, Up: Python + +23.2.3 Python Auto-loading +-------------------------- + +When a new object file is read (for example, due to the 'file' command, +or because the inferior has loaded a shared library), GDB will look for +Python support scripts in several ways: 'OBJFILE-gdb.py' and +'.debug_gdb_scripts' section. *Note Auto-loading extensions::. + + The auto-loading feature is useful for supplying application-specific +debugging commands and scripts. + + Auto-loading can be enabled or disabled, and the list of auto-loaded +scripts can be printed. + +'set auto-load python-scripts [on|off]' + Enable or disable the auto-loading of Python scripts. + +'show auto-load python-scripts' + Show whether auto-loading of Python scripts is enabled or disabled. + +'info auto-load python-scripts [REGEXP]' + Print the list of all Python scripts that GDB auto-loaded. + + Also printed is the list of Python scripts that were mentioned in + the '.debug_gdb_scripts' section and were not found (*note + dotdebug_gdb_scripts section::). This is useful because their + names are not printed when GDB tries to load them and fails. There + may be many of them, and printing an error message for each one is + problematic. + + If REGEXP is supplied only Python scripts with matching names are + printed. + + Example: + + (gdb) info auto-load python-scripts + Loaded Script + Yes py-section-script.py + full name: /tmp/py-section-script.py + No my-foo-pretty-printers.py + + When reading an auto-loaded file, GDB sets the "current objfile". +This is available via the 'gdb.current_objfile' function (*note Objfiles +In Python::). This can be useful for registering objfile-specific +pretty-printers and frame-filters. + + +File: gdb.info, Node: Python modules, Prev: Python Auto-loading, Up: Python + +23.2.4 Python modules +--------------------- + +GDB comes with several modules to assist writing Python code. + +* Menu: + +* gdb.printing:: Building and registering pretty-printers. +* gdb.types:: Utilities for working with types. +* gdb.prompt:: Utilities for prompt value substitution. + + +File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules + +23.2.4.1 gdb.printing +..................... + +This module provides a collection of utilities for working with +pretty-printers. + +'PrettyPrinter (NAME, SUBPRINTERS=None)' + This class specifies the API that makes 'info pretty-printer', + 'enable pretty-printer' and 'disable pretty-printer' work. + Pretty-printers should generally inherit from this class. + +'SubPrettyPrinter (NAME)' + For printers that handle multiple types, this class specifies the + corresponding API for the subprinters. + +'RegexpCollectionPrettyPrinter (NAME)' + Utility class for handling multiple printers, all recognized via + regular expressions. *Note Writing a Pretty-Printer::, for an + example. + +'FlagEnumerationPrinter (NAME)' + A pretty-printer which handles printing of 'enum' values. Unlike + GDB's built-in 'enum' printing, this printer attempts to work + properly when there is some overlap between the enumeration + constants. NAME is the name of the printer and also the name of + the 'enum' type to look up. + +'register_pretty_printer (OBJ, PRINTER, REPLACE=False)' + Register PRINTER with the pretty-printer list of OBJ. If REPLACE + is 'True' then any existing copy of the printer is replaced. + Otherwise a 'RuntimeError' exception is raised if a printer with + the same name already exists. + + +File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: Python modules + +23.2.4.2 gdb.types +.................. + +This module provides a collection of utilities for working with +'gdb.Type' objects. + +'get_basic_type (TYPE)' + Return TYPE with const and volatile qualifiers stripped, and with + typedefs and C++ references converted to the underlying type. + + C++ example: + + typedef const int const_int; + const_int foo (3); + const_int& foo_ref (foo); + int main () { return 0; } + + Then in gdb: + + (gdb) start + (gdb) python import gdb.types + (gdb) python foo_ref = gdb.parse_and_eval("foo_ref") + (gdb) python print gdb.types.get_basic_type(foo_ref.type) + int + +'has_field (TYPE, FIELD)' + Return 'True' if TYPE, assumed to be a type with fields (e.g., a + structure or union), has field FIELD. + +'make_enum_dict (ENUM_TYPE)' + Return a Python 'dictionary' type produced from ENUM_TYPE. + +'deep_items (TYPE)' + Returns a Python iterator similar to the standard + 'gdb.Type.iteritems' method, except that the iterator returned by + 'deep_items' will recursively traverse anonymous struct or union + fields. For example: + + struct A + { + int a; + union { + int b0; + int b1; + }; + }; + + Then in GDB: + (gdb) python import gdb.types + (gdb) python struct_a = gdb.lookup_type("struct A") + (gdb) python print struct_a.keys () + {['a', '']} + (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)] + {['a', 'b0', 'b1']} + +'get_type_recognizers ()' + Return a list of the enabled type recognizers for the current + context. This is called by GDB during the type-printing process + (*note Type Printing API::). + +'apply_type_recognizers (recognizers, type_obj)' + Apply the type recognizers, RECOGNIZERS, to the type object + TYPE_OBJ. If any recognizer returns a string, return that string. + Otherwise, return 'None'. This is called by GDB during the + type-printing process (*note Type Printing API::). + +'register_type_printer (locus, printer)' + This is a convenience function to register a type printer. PRINTER + is the type printer to register. It must implement the type + printer protocol. LOCUS is either a 'gdb.Objfile', in which case + the printer is registered with that objfile; a 'gdb.Progspace', in + which case the printer is registered with that progspace; or + 'None', in which case the printer is registered globally. + +'TypePrinter' + This is a base class that implements the type printer protocol. + Type printers are encouraged, but not required, to derive from this + class. It defines a constructor: + + -- Method on TypePrinter: __init__ (self, name) + Initialize the type printer with the given name. The new + printer starts in the enabled state. + + +File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules + +23.2.4.3 gdb.prompt +................... + +This module provides a method for prompt value-substitution. + +'substitute_prompt (STRING)' + Return STRING with escape sequences substituted by values. Some + escape sequences take arguments. You can specify arguments inside + "{}" immediately following the escape sequence. + + The escape sequences you can pass to this function are: + + '\\' + Substitute a backslash. + '\e' + Substitute an ESC character. + '\f' + Substitute the selected frame; an argument names a frame + parameter. + '\n' + Substitute a newline. + '\p' + Substitute a parameter's value; the argument names the + parameter. + '\r' + Substitute a carriage return. + '\t' + Substitute the selected thread; an argument names a thread + parameter. + '\v' + Substitute the version of GDB. + '\w' + Substitute the current working directory. + '\[' + Begin a sequence of non-printing characters. These sequences + are typically used with the ESC character, and are not counted + in the string length. Example: "\[\e[0;34m\](gdb)\[\e[0m\]" + will return a blue-colored "(gdb)" prompt where the length is + five. + '\]' + End a sequence of non-printing characters. + + For example: + + substitute_prompt (``frame: \f, + print arguments: \p{print frame-arguments}'') + +will return the string: + + "frame: main, print arguments: scalars" + + +File: gdb.info, Node: Auto-loading extensions, Next: Aliases, Prev: Python, Up: Extending GDB + +23.3 Auto-loading extensions +============================ + +GDB provides two mechanisms for automatically loading extensions when a +new object file is read (for example, due to the 'file' command, or +because the inferior has loaded a shared library): 'OBJFILE-gdb.EXT' and +the '.debug_gdb_scripts' section of modern file formats like ELF. + +* Menu: + +* objfile-gdb.ext file: objfile-gdbdotext file. The 'OBJFILE-gdb.EXT' file +* .debug_gdb_scripts section: dotdebug_gdb_scripts section. The '.debug_gdb_scripts' section +* Which flavor to choose?:: + + The auto-loading feature is useful for supplying application-specific +debugging commands and features. + + Auto-loading can be enabled or disabled, and the list of auto-loaded +scripts can be printed. See the 'auto-loading' section of each +extension language for more information. For GDB command files see +*note Auto-loading sequences::. For Python files see *note Python +Auto-loading::. + + Note that loading of this script file also requires accordingly +configured 'auto-load safe-path' (*note Auto-loading safe path::). + + +File: gdb.info, Node: objfile-gdbdotext file, Next: dotdebug_gdb_scripts section, Up: Auto-loading extensions + +23.3.1 The 'OBJFILE-gdb.EXT' file +--------------------------------- + +When a new object file is read, GDB looks for a file named +'OBJFILE-gdb.EXT' (we call it SCRIPT-NAME below), where OBJFILE is the +object file's name and where EXT is the file extension for the extension +language: + +'OBJFILE-gdb.gdb' + GDB's own command language +'OBJFILE-gdb.py' + Python + + SCRIPT-NAME is formed by ensuring that the file name of OBJFILE is +absolute, following all symlinks, and resolving '.' and '..' components, +and appending the '-gdb.EXT' suffix. If this file exists and is +readable, GDB will evaluate it as a script in the specified extension +language. + + If this file does not exist, then GDB will look for SCRIPT-NAME file +in all of the directories as specified below. + + Note that loading of these files requires an accordingly configured +'auto-load safe-path' (*note Auto-loading safe path::). + + For object files using '.exe' suffix GDB tries to load first the +scripts normally according to its '.exe' filename. But if no scripts +are found GDB also tries script filenames matching the object file +without its '.exe' suffix. This '.exe' stripping is case insensitive +and it is attempted on any platform. This makes the script filenames +compatible between Unix and MS-Windows hosts. + +'set auto-load scripts-directory [DIRECTORIES]' + Control GDB auto-loaded scripts location. Multiple directory + entries may be delimited by the host platform path separator in use + (':' on Unix, ';' on MS-Windows and MS-DOS). + + Each entry here needs to be covered also by the security setting + 'set auto-load safe-path' (*note set auto-load safe-path::). + + This variable defaults to '$debugdir:$datadir/auto-load'. The + default 'set auto-load safe-path' value can be also overriden by + GDB configuration option '--with-auto-load-dir'. + + Any reference to '$debugdir' will get replaced by + DEBUG-FILE-DIRECTORY value (*note Separate Debug Files::) and any + reference to '$datadir' will get replaced by DATA-DIRECTORY which + is determined at GDB startup (*note Data Files::). '$debugdir' and + '$datadir' must be placed as a directory component -- either alone + or delimited by '/' or '\' directory separators, depending on the + host platform. + + The list of directories uses path separator (':' on GNU and Unix + systems, ';' on MS-Windows and MS-DOS) to separate directories, + similarly to the 'PATH' environment variable. + +'show auto-load scripts-directory' + Show GDB auto-loaded scripts location. + + GDB does not track which files it has already auto-loaded this way. +GDB will load the associated script every time the corresponding OBJFILE +is opened. So your '-gdb.EXT' file should be careful to avoid errors if +it is evaluated more than once. + + +File: gdb.info, Node: dotdebug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdbdotext file, Up: Auto-loading extensions + +23.3.2 The '.debug_gdb_scripts' section +--------------------------------------- + +For systems using file formats like ELF and COFF, when GDB loads a new +object file it will look for a special section named +'.debug_gdb_scripts'. If this section exists, its contents is a list of +NUL-terminated names of scripts to load. Each entry begins with a +non-NULL prefix byte that specifies the kind of entry, typically the +extension language. + + GDB will look for each specified script file first in the current +directory and then along the source search path (*note Specifying Source +Directories: Source Path.), except that '$cdir' is not searched, since +the compilation directory is not relevant to scripts. + + Entries can be placed in section '.debug_gdb_scripts' with, for +example, this GCC macro for Python scripts. + + /* Note: The "MS" section flags are to remove duplicates. */ + #define DEFINE_GDB_PY_SCRIPT(script_name) \ + asm("\ + .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\ + .byte 1 /* Python */\n\ + .asciz \"" script_name "\"\n\ + .popsection \n\ + "); + +Then one can reference the macro in a header or source file like this: + + DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py") + + The script name may include directories if desired. + + Note that loading of this script file also requires accordingly +configured 'auto-load safe-path' (*note Auto-loading safe path::). + + If the macro invocation is put in a header, any application or +library using this header will get a reference to the specified script, +and with the use of '"MS"' attributes on the section, the linker will +remove duplicates. + + +File: gdb.info, Node: Which flavor to choose?, Prev: dotdebug_gdb_scripts section, Up: Auto-loading extensions + +23.3.3 Which flavor to choose? +------------------------------ + +Given the multiple ways of auto-loading extensions, it might not always +be clear which one to choose. This section provides some guidance. + +Benefits of the '-gdb.EXT' way: + + * Can be used with file formats that don't support multiple sections. + + * Ease of finding scripts for public libraries. + + Scripts specified in the '.debug_gdb_scripts' section are searched + for in the source search path. For publicly installed libraries, + e.g., 'libstdc++', there typically isn't a source directory in + which to find the script. + + * Doesn't require source code additions. + +Benefits of the '.debug_gdb_scripts' way: + + * Works with static linking. + + Scripts for libraries done the '-gdb.EXT' way require an objfile to + trigger their loading. When an application is statically linked + the only objfile available is the executable, and it is cumbersome + to attach all the scripts from all the input libraries to the + executable's '-gdb.EXT' script. + + * Works with classes that are entirely inlined. + + Some classes can be entirely inlined, and thus there may not be an + associated shared library to attach a '-gdb.EXT' script to. + + * Scripts needn't be copied out of the source tree. + + In some circumstances, apps can be built out of large collections + of internal libraries, and the build infrastructure necessary to + install the '-gdb.EXT' scripts in a place where GDB can find them + is cumbersome. It may be easier to specify the scripts in the + '.debug_gdb_scripts' section as relative paths, and add a path to + the top of the source tree to the source search path. + + +File: gdb.info, Node: Aliases, Prev: Auto-loading extensions, Up: Extending GDB + +23.4 Creating new spellings of existing commands +================================================ + +It is often useful to define alternate spellings of existing commands. +For example, if a new GDB command defined in Python has a long name to +type, it is handy to have an abbreviated version of it that involves +less typing. + + GDB itself uses aliases. For example 's' is an alias of the 'step' +command even though it is otherwise an ambiguous abbreviation of other +commands like 'set' and 'show'. + + Aliases are also used to provide shortened or more common versions of +multi-word commands. For example, GDB provides the 'tty' alias of the +'set inferior-tty' command. + + You can define a new alias with the 'alias' command. + +'alias [-a] [--] ALIAS = COMMAND' + + ALIAS specifies the name of the new alias. Each word of ALIAS must +consist of letters, numbers, dashes and underscores. + + COMMAND specifies the name of an existing command that is being +aliased. + + The '-a' option specifies that the new alias is an abbreviation of +the command. Abbreviations are not shown in command lists displayed by +the 'help' command. + + The '--' option specifies the end of options, and is useful when +ALIAS begins with a dash. + + Here is a simple example showing how to make an abbreviation of a +command so that there is less to type. Suppose you were tired of typing +'disas', the current shortest unambiguous abbreviation of the +'disassemble' command and you wanted an even shorter version named 'di'. +The following will accomplish this. + + (gdb) alias -a di = disas + + Note that aliases are different from user-defined commands. With a +user-defined command, you also need to write documentation for it with +the 'document' command. An alias automatically picks up the +documentation of the existing command. + + Here is an example where we make 'elms' an abbreviation of 'elements' +in the 'set print elements' command. This is to show that you can make +an abbreviation of any part of a command. + + (gdb) alias -a set print elms = set print elements + (gdb) alias -a show print elms = show print elements + (gdb) set p elms 20 + (gdb) show p elms + Limit on string chars or array elements to print is 200. + + Note that if you are defining an alias of a 'set' command, and you +want to have an alias for the corresponding 'show' command, then you +need to define the latter separately. + + Unambiguously abbreviated commands are allowed in COMMAND and ALIAS, +just as they are normally. + + (gdb) alias -a set pr elms = set p ele + + Finally, here is an example showing the creation of a one word alias +for a more complex command. This creates alias 'spe' of the command +'set print elements'. + + (gdb) alias spe = set print elements + (gdb) spe 20 + + +File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top + +24 Command Interpreters +*********************** + +GDB supports multiple command interpreters, and some command +infrastructure to allow users or user interface writers to switch +between interpreters or run commands in other interpreters. + + GDB currently supports two command interpreters, the console +interpreter (sometimes called the command-line interpreter or CLI) and +the machine interface interpreter (or GDB/MI). This manual describes +both of these interfaces in great detail. + + By default, GDB will start with the console interpreter. However, +the user may choose to start GDB with another interpreter by specifying +the '-i' or '--interpreter' startup options. Defined interpreters +include: + +'console' + The traditional console or command-line interpreter. This is the + most often used interpreter with GDB. With no interpreter + specified at runtime, GDB will use this interpreter. + +'mi' + The newest GDB/MI interface (currently 'mi2'). Used primarily by + programs wishing to use GDB as a backend for a debugger GUI or an + IDE. For more information, see *note The GDB/MI Interface: GDB/MI. + +'mi2' + The current GDB/MI interface. + +'mi1' + The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. + + The interpreter being used by GDB may not be dynamically switched at +runtime. Although possible, this could lead to a very precarious +situation. Consider an IDE using GDB/MI. If a user enters the command +"interpreter-set console" in a console view, GDB would switch to using +the console interpreter, rendering the IDE inoperable! + + Although you may only choose a single interpreter at startup, you may +execute commands in any interpreter from the current interpreter using +the appropriate command. If you are running the console interpreter, +simply use the 'interpreter-exec' command: + + interpreter-exec mi "-data-list-register-names" + + GDB/MI has a similar command, although it is only available in +versions of GDB which support GDB/MI version 2 (or greater). + + +File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top + +25 GDB Text User Interface +************************** + +* Menu: + +* TUI Overview:: TUI overview +* TUI Keys:: TUI key bindings +* TUI Single Key Mode:: TUI single key mode +* TUI Commands:: TUI-specific commands +* TUI Configuration:: TUI configuration variables + +The GDB Text User Interface (TUI) is a terminal interface which uses the +'curses' library to show the source file, the assembly output, the +program registers and GDB commands in separate text windows. The TUI +mode is supported only on platforms where a suitable version of the +'curses' library is available. + + The TUI mode is enabled by default when you invoke GDB as 'gdb -tui'. +You can also switch in and out of TUI mode while GDB runs by using +various TUI commands and key bindings, such as 'C-x C-a'. *Note TUI Key +Bindings: TUI Keys. + + +File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI + +25.1 TUI Overview +================= + +In TUI mode, GDB can display several text windows: + +_command_ + This window is the GDB command window with the GDB prompt and the + GDB output. The GDB input is still managed using readline. + +_source_ + The source window shows the source file of the program. The + current line and active breakpoints are displayed in this window. + +_assembly_ + The assembly window shows the disassembly output of the program. + +_register_ + This window shows the processor registers. Registers are + highlighted when their values change. + + The source and assembly windows show the current program position by +highlighting the current line and marking it with a '>' marker. +Breakpoints are indicated with two markers. The first marker indicates +the breakpoint type: + +'B' + Breakpoint which was hit at least once. + +'b' + Breakpoint which was never hit. + +'H' + Hardware breakpoint which was hit at least once. + +'h' + Hardware breakpoint which was never hit. + + The second marker indicates whether the breakpoint is enabled or not: + +'+' + Breakpoint is enabled. + +'-' + Breakpoint is disabled. + + The source, assembly and register windows are updated when the +current thread changes, when the frame changes, or when the program +counter changes. + + These windows are not all visible at the same time. The command +window is always visible. The others can be arranged in several +layouts: + + * source only, + + * assembly only, + + * source and assembly, + + * source and registers, or + + * assembly and registers. + + A status line above the command window shows the following +information: + +_target_ + Indicates the current GDB target. (*note Specifying a Debugging + Target: Targets.). + +_process_ + Gives the current process or thread number. When no process is + being debugged, this field is set to 'No process'. + +_function_ + Gives the current function name for the selected frame. The name + is demangled if demangling is turned on (*note Print Settings::). + When there is no symbol corresponding to the current program + counter, the string '??' is displayed. + +_line_ + Indicates the current line number for the selected frame. When the + current line number is not known, the string '??' is displayed. + +_pc_ + Indicates the current program counter address. + + +File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI + +25.2 TUI Key Bindings +===================== + +The TUI installs several key bindings in the readline keymaps (*note +Command Line Editing::). The following key bindings are installed for +both TUI mode and the GDB standard mode. + +'C-x C-a' +'C-x a' +'C-x A' + Enter or leave the TUI mode. When leaving the TUI mode, the curses + window management stops and GDB operates using its standard mode, + writing on the terminal directly. When reentering the TUI mode, + control is given back to the curses windows. The screen is then + refreshed. + +'C-x 1' + Use a TUI layout with only one window. The layout will either be + 'source' or 'assembly'. When the TUI mode is not active, it will + switch to the TUI mode. + + Think of this key binding as the Emacs 'C-x 1' binding. + +'C-x 2' + Use a TUI layout with at least two windows. When the current + layout already has two windows, the next layout with two windows is + used. When a new layout is chosen, one window will always be + common to the previous layout and the new one. + + Think of it as the Emacs 'C-x 2' binding. + +'C-x o' + Change the active window. The TUI associates several key bindings + (like scrolling and arrow keys) with the active window. This + command gives the focus to the next TUI window. + + Think of it as the Emacs 'C-x o' binding. + +'C-x s' + Switch in and out of the TUI SingleKey mode that binds single keys + to GDB commands (*note TUI Single Key Mode::). + + The following key bindings only work in the TUI mode: + + + Scroll the active window one page up. + + + Scroll the active window one page down. + + + Scroll the active window one line up. + + + Scroll the active window one line down. + + + Scroll the active window one column left. + + + Scroll the active window one column right. + +'C-L' + Refresh the screen. + + Because the arrow keys scroll the active window in the TUI mode, they +are not available for their normal use by readline unless the command +window has the focus. When another window is active, you must use other +readline key bindings such as 'C-p', 'C-n', 'C-b' and 'C-f' to control +the command window. + + +File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI + +25.3 TUI Single Key Mode +======================== + +The TUI also provides a "SingleKey" mode, which binds several frequently +used GDB commands to single keys. Type 'C-x s' to switch into this +mode, where the following key bindings are used: + +'c' + continue + +'d' + down + +'f' + finish + +'n' + next + +'q' + exit the SingleKey mode. + +'r' + run + +'s' + step + +'u' + up + +'v' + info locals + +'w' + where + + Other keys temporarily switch to the GDB command prompt. The key +that was pressed is inserted in the editing buffer so that it is +possible to type most GDB commands without interaction with the TUI +SingleKey mode. Once the command is entered the TUI SingleKey mode is +restored. The only way to permanently leave this mode is by typing 'q' +or 'C-x s'. + + +File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI + +25.4 TUI-specific Commands +========================== + +The TUI has specific commands to control the text windows. These +commands are always available, even when GDB is not in the TUI mode. +When GDB is in the standard mode, most of these commands will +automatically switch to the TUI mode. + + Note that if GDB's 'stdout' is not connected to a terminal, or GDB +has been started with the machine interface interpreter (*note The +GDB/MI Interface: GDB/MI.), most of these commands will fail with an +error, because it would not be possible or desirable to enable curses +window management. + +'info win' + List and give the size of all displayed windows. + +'layout next' + Display the next layout. + +'layout prev' + Display the previous layout. + +'layout src' + Display the source window only. + +'layout asm' + Display the assembly window only. + +'layout split' + Display the source and assembly window. + +'layout regs' + Display the register window together with the source or assembly + window. + +'focus next' + Make the next window active for scrolling. + +'focus prev' + Make the previous window active for scrolling. + +'focus src' + Make the source window active for scrolling. + +'focus asm' + Make the assembly window active for scrolling. + +'focus regs' + Make the register window active for scrolling. + +'focus cmd' + Make the command window active for scrolling. + +'refresh' + Refresh the screen. This is similar to typing 'C-L'. + +'tui reg float' + Show the floating point registers in the register window. + +'tui reg general' + Show the general registers in the register window. + +'tui reg next' + Show the next register group. The list of register groups as well + as their order is target specific. The predefined register groups + are the following: 'general', 'float', 'system', 'vector', 'all', + 'save', 'restore'. + +'tui reg system' + Show the system registers in the register window. + +'update' + Update the source window and the current execution point. + +'winheight NAME +COUNT' +'winheight NAME -COUNT' + Change the height of the window NAME by COUNT lines. Positive + counts increase the height, while negative counts decrease it. + +'tabset NCHARS' + Set the width of tab stops to be NCHARS characters. + + +File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI + +25.5 TUI Configuration Variables +================================ + +Several configuration variables control the appearance of TUI windows. + +'set tui border-kind KIND' + Select the border appearance for the source, assembly and register + windows. The possible values are the following: + 'space' + Use a space character to draw the border. + + 'ascii' + Use ASCII characters '+', '-' and '|' to draw the border. + + 'acs' + Use the Alternate Character Set to draw the border. The + border is drawn using character line graphics if the terminal + supports them. + +'set tui border-mode MODE' +'set tui active-border-mode MODE' + Select the display attributes for the borders of the inactive + windows or the active window. The MODE can be one of the + following: + 'normal' + Use normal attributes to display the border. + + 'standout' + Use standout mode. + + 'reverse' + Use reverse video mode. + + 'half' + Use half bright mode. + + 'half-standout' + Use half bright and standout mode. + + 'bold' + Use extra bright or bold mode. + + 'bold-standout' + Use extra bright or bold and standout mode. + + +File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top + +26 Using GDB under GNU Emacs +**************************** + +A special interface allows you to use GNU Emacs to view (and edit) the +source files for the program you are debugging with GDB. + + To use this interface, use the command 'M-x gdb' in Emacs. Give the +executable file you want to debug as an argument. This command starts +GDB as a subprocess of Emacs, with input and output through a newly +created Emacs buffer. + + Running GDB under Emacs can be just like running GDB normally except +for two things: + + * All "terminal" input and output goes through an Emacs buffer, + called the GUD buffer. + + This applies both to GDB commands and their output, and to the + input and output done by the program you are debugging. + + This is useful because it means that you can copy the text of + previous commands and input them again; you can even use parts of + the output in this way. + + All the facilities of Emacs' Shell mode are available for + interacting with your program. In particular, you can send signals + the usual way--for example, 'C-c C-c' for an interrupt, 'C-c C-z' + for a stop. + + * GDB displays source code through Emacs. + + Each time GDB displays a stack frame, Emacs automatically finds the + source file for that frame and puts an arrow ('=>') at the left + margin of the current line. Emacs uses a separate buffer for + source display, and splits the screen to show both your GDB session + and the source. + + Explicit GDB 'list' or search commands still produce output as + usual, but you probably have no reason to use them from Emacs. + + We call this "text command mode". Emacs 22.1, and later, also uses a +graphical mode, enabled by default, which provides further buffers that +can control the execution and describe the state of your program. *Note +(Emacs)GDB Graphical Interface::. + + If you specify an absolute file name when prompted for the 'M-x gdb' +argument, then Emacs sets your current working directory to where your +program resides. If you only specify the file name, then Emacs sets +your current working directory to the directory associated with the +previous buffer. In this case, GDB may find your program by searching +your environment's 'PATH' variable, but on some operating systems it +might not find the source. So, although the GDB input and output +session proceeds normally, the auxiliary buffer does not display the +current source and line of execution. + + The initial working directory of GDB is printed on the top line of +the GUD buffer and this serves as a default for the commands that +specify files for GDB to operate on. *Note Commands to Specify Files: +Files. + + By default, 'M-x gdb' calls the program called 'gdb'. If you need to +call GDB by a different name (for example, if you keep several +configurations around, with different names) you can customize the Emacs +variable 'gud-gdb-command-name' to run the one you want. + + In the GUD buffer, you can use these special Emacs commands in +addition to the standard Shell mode commands: + +'C-h m' + Describe the features of Emacs' GUD Mode. + +'C-c C-s' + Execute to another source line, like the GDB 'step' command; also + update the display window to show the current file and location. + +'C-c C-n' + Execute to next source line in this function, skipping all function + calls, like the GDB 'next' command. Then update the display window + to show the current file and location. + +'C-c C-i' + Execute one instruction, like the GDB 'stepi' command; update + display window accordingly. + +'C-c C-f' + Execute until exit from the selected stack frame, like the GDB + 'finish' command. + +'C-c C-r' + Continue execution of your program, like the GDB 'continue' + command. + +'C-c <' + Go up the number of frames indicated by the numeric argument (*note + Numeric Arguments: (Emacs)Arguments.), like the GDB 'up' command. + +'C-c >' + Go down the number of frames indicated by the numeric argument, + like the GDB 'down' command. + + In any source file, the Emacs command 'C-x ' ('gud-break') tells +GDB to set a breakpoint on the source line point is on. + + In text command mode, if you type 'M-x speedbar', Emacs displays a +separate frame which shows a backtrace when the GUD buffer is current. +Move point to any frame in the stack and type to make it become +the current frame and display the associated source in the source +buffer. Alternatively, click 'Mouse-2' to make the selected frame +become the current one. In graphical mode, the speedbar displays watch +expressions. + + If you accidentally delete the source-display buffer, an easy way to +get it back is to type the command 'f' in the GDB buffer, to request a +frame display; when you run under Emacs, this recreates the source +buffer if necessary to show you the context of the current frame. + + The source files displayed in Emacs are in ordinary Emacs buffers +which are visiting the source files in the usual way. You can edit the +files with these buffers if you wish; but keep in mind that GDB +communicates with Emacs in terms of line numbers. If you add or delete +lines from the text, the line numbers that GDB knows cease to correspond +properly with the code. + + A more detailed description of Emacs' interaction with GDB is given +in the Emacs manual (*note (Emacs)Debuggers::). + + +File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top + +27 The GDB/MI Interface +*********************** + +Function and Purpose +==================== + +GDB/MI is a line based machine oriented text interface to GDB and is +activated by specifying using the '--interpreter' command line option +(*note Mode Options::). It is specifically intended to support the +development of systems which use the debugger as just one small +component of a larger system. + + This chapter is a specification of the GDB/MI interface. It is +written in the form of a reference manual. + + Note that GDB/MI is still under construction, so some of the features +described below are incomplete and subject to change (*note GDB/MI +Development and Front Ends: GDB/MI Development and Front Ends.). + +Notation and Terminology +======================== + +This chapter uses the following notation: + + * '|' separates two alternatives. + + * '[ SOMETHING ]' indicates that SOMETHING is optional: it may or may + not be given. + + * '( GROUP )*' means that GROUP inside the parentheses may repeat + zero or more times. + + * '( GROUP )+' means that GROUP inside the parentheses may repeat one + or more times. + + * '"STRING"' means a literal STRING. + +* Menu: + +* GDB/MI General Design:: +* GDB/MI Command Syntax:: +* GDB/MI Compatibility with CLI:: +* GDB/MI Development and Front Ends:: +* GDB/MI Output Records:: +* GDB/MI Simple Examples:: +* GDB/MI Command Description Format:: +* GDB/MI Breakpoint Commands:: +* GDB/MI Catchpoint Commands:: +* GDB/MI Program Context:: +* GDB/MI Thread Commands:: +* GDB/MI Ada Tasking Commands:: +* GDB/MI Program Execution:: +* GDB/MI Stack Manipulation:: +* GDB/MI Variable Objects:: +* GDB/MI Data Manipulation:: +* GDB/MI Tracepoint Commands:: +* GDB/MI Symbol Query:: +* GDB/MI File Commands:: +* GDB/MI Target Manipulation:: +* GDB/MI File Transfer Commands:: +* GDB/MI Ada Exceptions Commands:: +* GDB/MI Support Commands:: +* GDB/MI Miscellaneous Commands:: + + +File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI + +27.1 GDB/MI General Design +========================== + +Interaction of a GDB/MI frontend with GDB involves three parts--commands +sent to GDB, responses to those commands and notifications. Each +command results in exactly one response, indicating either successful +completion of the command, or an error. For the commands that do not +resume the target, the response contains the requested information. For +the commands that resume the target, the response only indicates whether +the target was successfully resumed. Notifications is the mechanism for +reporting changes in the state of the target, or in GDB state, that +cannot conveniently be associated with a command and reported as part of +that command response. + + The important examples of notifications are: + + * Exec notifications. These are used to report changes in target + state--when a target is resumed, or stopped. It would not be + feasible to include this information in response of resuming + commands, because one resume commands can result in multiple events + in different threads. Also, quite some time may pass before any + event happens in the target, while a frontend needs to know whether + the resuming command itself was successfully executed. + + * Console output, and status notifications. Console output + notifications are used to report output of CLI commands, as well as + diagnostics for other commands. Status notifications are used to + report the progress of a long-running operation. Naturally, + including this information in command response would mean no output + is produced until the command is finished, which is undesirable. + + * General notifications. Commands may have various side effects on + the GDB or target state beyond their official purpose. For + example, a command may change the selected thread. Although such + changes can be included in command response, using notification + allows for more orthogonal frontend design. + + There's no guarantee that whenever an MI command reports an error, +GDB or the target are in any specific state, and especially, the state +is not reverted to the state before the MI command was processed. +Therefore, whenever an MI command results in an error, we recommend that +the frontend refreshes all the information shown in the user interface. + +* Menu: + +* Context management:: +* Asynchronous and non-stop modes:: +* Thread groups:: + + +File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design + +27.1.1 Context management +------------------------- + +27.1.1.1 Threads and Frames +........................... + +In most cases when GDB accesses the target, this access is done in +context of a specific thread and frame (*note Frames::). Often, even +when accessing global data, the target requires that a thread be +specified. The CLI interface maintains the selected thread and frame, +and supplies them to target on each command. This is convenient, +because a command line user would not want to specify that information +explicitly on each command, and because user interacts with GDB via a +single terminal, so no confusion is possible as to what thread and frame +are the current ones. + + In the case of MI, the concept of selected thread and frame is less +useful. First, a frontend can easily remember this information itself. +Second, a graphical frontend can have more than one window, each one +used for debugging a different thread, and the frontend might want to +access additional threads for internal purposes. This increases the +risk that by relying on implicitly selected thread, the frontend may be +operating on a wrong one. Therefore, each MI command should explicitly +specify which thread and frame to operate on. To make it possible, each +MI command accepts the '--thread' and '--frame' options, the value to +each is GDB identifier for thread and frame to operate on. + + Usually, each top-level window in a frontend allows the user to +select a thread and a frame, and remembers the user selection for +further operations. However, in some cases GDB may suggest that the +current thread be changed. For example, when stopping on a breakpoint +it is reasonable to switch to the thread where breakpoint is hit. For +another example, if the user issues the CLI 'thread' command via the +frontend, it is desirable to change the frontend's selected thread to +the one specified by user. GDB communicates the suggestion to change +current thread using the '=thread-selected' notification. No such +notification is available for the selected frame at the moment. + + Note that historically, MI shares the selected thread with CLI, so +frontends used the '-thread-select' to execute commands in the right +context. However, getting this to work right is cumbersome. The +simplest way is for frontend to emit '-thread-select' command before +every command. This doubles the number of commands that need to be +sent. The alternative approach is to suppress '-thread-select' if the +selected thread in GDB is supposed to be identical to the thread the +frontend wants to operate on. However, getting this optimization right +can be tricky. In particular, if the frontend sends several commands to +GDB, and one of the commands changes the selected thread, then the +behaviour of subsequent commands will change. So, a frontend should +either wait for response from such problematic commands, or explicitly +add '-thread-select' for all subsequent commands. No frontend is known +to do this exactly right, so it is suggested to just always pass the +'--thread' and '--frame' options. + +27.1.1.2 Language +................. + +The execution of several commands depends on which language is selected. +By default, the current language (*note show language::) is used. But +for commands known to be language-sensitive, it is recommended to use +the '--language' option. This option takes one argument, which is the +name of the language to use while executing the command. For instance: + + -data-evaluate-expression --language c "sizeof (void*)" + ^done,value="4" + (gdb) + + The valid language names are the same names accepted by the 'set +language' command (*note Manually::), excluding 'auto', 'local' or +'unknown'. + + +File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design + +27.1.2 Asynchronous command execution and non-stop mode +------------------------------------------------------- + +On some targets, GDB is capable of processing MI commands even while the +target is running. This is called "asynchronous command execution" +(*note Background Execution::). The frontend may specify a preferrence +for asynchronous execution using the '-gdb-set target-async 1' command, +which should be emitted before either running the executable or +attaching to the target. After the frontend has started the executable +or attached to the target, it can find if asynchronous execution is +enabled using the '-list-target-features' command. + + Even if GDB can accept a command while target is running, many +commands that access the target do not work when the target is running. +Therefore, asynchronous command execution is most useful when combined +with non-stop mode (*note Non-Stop Mode::). Then, it is possible to +examine the state of one thread, while other threads are running. + + When a given thread is running, MI commands that try to access the +target in the context of that thread may not work, or may work only on +some targets. In particular, commands that try to operate on thread's +stack will not work, on any target. Commands that read memory, or +modify breakpoints, may work or not work, depending on the target. Note +that even commands that operate on global state, such as 'print', 'set', +and breakpoint commands, still access the target in the context of a +specific thread, so frontend should try to find a stopped thread and +perform the operation on that thread (using the '--thread' option). + + Which commands will work in the context of a running thread is highly +target dependent. However, the two commands '-exec-interrupt', to stop +a thread, and '-thread-info', to find the state of a thread, will always +work. + + +File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design + +27.1.3 Thread groups +-------------------- + +GDB may be used to debug several processes at the same time. On some +platfroms, GDB may support debugging of several hardware systems, each +one having several cores with several different processes running on +each core. This section describes the MI mechanism to support such +debugging scenarios. + + The key observation is that regardless of the structure of the +target, MI can have a global list of threads, because most commands that +accept the '--thread' option do not need to know what process that +thread belongs to. Therefore, it is not necessary to introduce neither +additional '--process' option, nor an notion of the current process in +the MI interface. The only strictly new feature that is required is the +ability to find how the threads are grouped into processes. + + To allow the user to discover such grouping, and to support arbitrary +hierarchy of machines/cores/processes, MI introduces the concept of a +"thread group". Thread group is a collection of threads and other +thread groups. A thread group always has a string identifier, a type, +and may have additional attributes specific to the type. A new command, +'-list-thread-groups', returns the list of top-level thread groups, +which correspond to processes that GDB is debugging at the moment. By +passing an identifier of a thread group to the '-list-thread-groups' +command, it is possible to obtain the members of specific thread group. + + To allow the user to easily discover processes, and other objects, he +wishes to debug, a concept of "available thread group" is introduced. +Available thread group is an thread group that GDB is not debugging, but +that can be attached to, using the '-target-attach' command. The list +of available top-level thread groups can be obtained using +'-list-thread-groups --available'. In general, the content of a thread +group may be only retrieved only after attaching to that thread group. + + Thread groups are related to inferiors (*note Inferiors and +Programs::). Each inferior corresponds to a thread group of a special +type 'process', and some additional operations are permitted on such +thread groups. + + +File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI + +27.2 GDB/MI Command Syntax +========================== + +* Menu: + +* GDB/MI Input Syntax:: +* GDB/MI Output Syntax:: + + +File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax + +27.2.1 GDB/MI Input Syntax +-------------------------- + +'COMMAND ==>' + 'CLI-COMMAND | MI-COMMAND' + +'CLI-COMMAND ==>' + '[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB + CLI command. + +'MI-COMMAND ==>' + '[ TOKEN ] "-" OPERATION ( " " OPTION )* [ " --" ] ( " " PARAMETER + )* NL' + +'TOKEN ==>' + "any sequence of digits" + +'OPTION ==>' + '"-" PARAMETER [ " " PARAMETER ]' + +'PARAMETER ==>' + 'NON-BLANK-SEQUENCE | C-STRING' + +'OPERATION ==>' + _any of the operations described in this chapter_ + +'NON-BLANK-SEQUENCE ==>' + _anything, provided it doesn't contain special characters such as + "-", NL, """ and of course " "_ + +'C-STRING ==>' + '""" SEVEN-BIT-ISO-C-STRING-CONTENT """' + +'NL ==>' + 'CR | CR-LF' + +Notes: + + * The CLI commands are still handled by the MI interpreter; their + output is described below. + + * The 'TOKEN', when present, is passed back when the command + finishes. + + * Some MI commands accept optional arguments as part of the parameter + list. Each option is identified by a leading '-' (dash) and may be + followed by an optional argument parameter. Options occur first in + the parameter list and can be delimited from normal parameters + using '--' (this is useful when some parameters begin with a dash). + + Pragmatics: + + * We want easy access to the existing CLI syntax (for debugging). + + * We want it to be easy to spot a MI operation. + + +File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax + +27.2.2 GDB/MI Output Syntax +--------------------------- + +The output from GDB/MI consists of zero or more out-of-band records +followed, optionally, by a single result record. This result record is +for the most recent command. The sequence of output records is +terminated by '(gdb)'. + + If an input command was prefixed with a 'TOKEN' then the +corresponding output for that command will also be prefixed by that same +TOKEN. + +'OUTPUT ==>' + '( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' + +'RESULT-RECORD ==>' + ' [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' + +'OUT-OF-BAND-RECORD ==>' + 'ASYNC-RECORD | STREAM-RECORD' + +'ASYNC-RECORD ==>' + 'EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' + +'EXEC-ASYNC-OUTPUT ==>' + '[ TOKEN ] "*" ASYNC-OUTPUT' + +'STATUS-ASYNC-OUTPUT ==>' + '[ TOKEN ] "+" ASYNC-OUTPUT' + +'NOTIFY-ASYNC-OUTPUT ==>' + '[ TOKEN ] "=" ASYNC-OUTPUT' + +'ASYNC-OUTPUT ==>' + 'ASYNC-CLASS ( "," RESULT )* NL' + +'RESULT-CLASS ==>' + '"done" | "running" | "connected" | "error" | "exit"' + +'ASYNC-CLASS ==>' + '"stopped" | OTHERS' (where OTHERS will be added depending on the + needs--this is still in development). + +'RESULT ==>' + ' VARIABLE "=" VALUE' + +'VARIABLE ==>' + ' STRING ' + +'VALUE ==>' + ' CONST | TUPLE | LIST ' + +'CONST ==>' + 'C-STRING' + +'TUPLE ==>' + ' "{}" | "{" RESULT ( "," RESULT )* "}" ' + +'LIST ==>' + ' "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* + "]" ' + +'STREAM-RECORD ==>' + 'CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' + +'CONSOLE-STREAM-OUTPUT ==>' + '"~" C-STRING' + +'TARGET-STREAM-OUTPUT ==>' + '"@" C-STRING' + +'LOG-STREAM-OUTPUT ==>' + '"&" C-STRING' + +'NL ==>' + 'CR | CR-LF' + +'TOKEN ==>' + _any sequence of digits_. + +Notes: + + * All output sequences end in a single line containing a period. + + * The 'TOKEN' is from the corresponding request. Note that for all + async output, while the token is allowed by the grammar and may be + output by future versions of GDB for select async output messages, + it is generally omitted. Frontends should treat all async output + as reporting general changes in the state of the target and there + should be no need to associate async output to any prior command. + + * STATUS-ASYNC-OUTPUT contains on-going status information about the + progress of a slow operation. It can be discarded. All status + output is prefixed by '+'. + + * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target + (stopped, started, disappeared). All async output is prefixed by + '*'. + + * NOTIFY-ASYNC-OUTPUT contains supplementary information that the + client should handle (e.g., a new breakpoint information). All + notify output is prefixed by '='. + + * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in + the console. It is the textual response to a CLI command. All the + console output is prefixed by '~'. + + * TARGET-STREAM-OUTPUT is the output produced by the target program. + All the target output is prefixed by '@'. + + * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for + instance messages that should be displayed as part of an error log. + All the log output is prefixed by '&'. + + * New GDB/MI commands should only output LISTS containing VALUES. + + *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details +about the various output records. + + +File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI + +27.3 GDB/MI Compatibility with CLI +================================== + +For the developers convenience CLI commands can be entered directly, but +there may be some unexpected behaviour. For example, commands that +query the user will behave as if the user replied yes, breakpoint +command lists are not executed and some CLI commands, such as 'if', +'when' and 'define', prompt for further input with '>', which is not +valid MI output. + + This feature may be removed at some stage in the future and it is +recommended that front ends use the '-interpreter-exec' command (*note +-interpreter-exec::). + + +File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI + +27.4 GDB/MI Development and Front Ends +====================================== + +The application which takes the MI output and presents the state of the +program being debugged to the user is called a "front end". + + Although GDB/MI is still incomplete, it is currently being used by a +variety of front ends to GDB. This makes it difficult to introduce new +functionality without breaking existing usage. This section tries to +minimize the problems by describing how the protocol might change. + + Some changes in MI need not break a carefully designed front end, and +for these the MI version will remain unchanged. The following is a list +of changes that may occur within one level, so front ends should parse +MI output in a way that can handle them: + + * New MI commands may be added. + + * New fields may be added to the output of any MI command. + + * The range of values for fields with specified values, e.g., + 'in_scope' (*note -var-update::) may be extended. + + If the changes are likely to break front ends, the MI version level +will be increased by one. This will allow the front end to parse the +output according to the MI version. Apart from mi0, new versions of GDB +will not support old versions of MI and it will be the responsibility of +the front end to work with the new one. + + The best way to avoid unexpected changes in MI that might break your +front end is to make your project known to GDB developers and follow +development on and . + + +File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI + +27.5 GDB/MI Output Records +========================== + +* Menu: + +* GDB/MI Result Records:: +* GDB/MI Stream Records:: +* GDB/MI Async Records:: +* GDB/MI Breakpoint Information:: +* GDB/MI Frame Information:: +* GDB/MI Thread Information:: +* GDB/MI Ada Exception Information:: + + +File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records + +27.5.1 GDB/MI Result Records +---------------------------- + +In addition to a number of out-of-band notifications, the response to a +GDB/MI command includes one of the following result indications: + +'"^done" [ "," RESULTS ]' + The synchronous operation was successful, 'RESULTS' are the return + values. + +'"^running"' + This result record is equivalent to '^done'. Historically, it was + output instead of '^done' if the command has resumed the target. + This behaviour is maintained for backward compatibility, but all + frontends should treat '^done' and '^running' identically and rely + on the '*running' output record to determine which threads are + resumed. + +'"^connected"' + GDB has connected to a remote target. + +'"^error" "," "msg=" C-STRING [ "," "code=" C-STRING ]' + The operation failed. The 'msg=C-STRING' variable contains the + corresponding error message. + + If present, the 'code=C-STRING' variable provides an error code on + which consumers can rely on to detect the corresponding error + condition. At present, only one error code is defined: + + '"undefined-command"' + Indicates that the command causing the error does not exist. + +'"^exit"' + GDB has terminated. + + +File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records + +27.5.2 GDB/MI Stream Records +---------------------------- + +GDB internally maintains a number of output streams: the console, the +target, and the log. The output intended for each of these streams is +funneled through the GDB/MI interface using "stream records". + + Each stream record begins with a unique "prefix character" which +identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output +Syntax.). In addition to the prefix, each stream record contains a +'STRING-OUTPUT'. This is either raw text (with an implicit new line) or +a quoted C string (which does not contain an implicit newline). + +'"~" STRING-OUTPUT' + The console output stream contains text that should be displayed in + the CLI console window. It contains the textual responses to CLI + commands. + +'"@" STRING-OUTPUT' + The target output stream contains any textual output from the + running target. This is only present when GDB's event loop is + truly asynchronous, which is currently only the case for remote + targets. + +'"&" STRING-OUTPUT' + The log stream contains debugging messages being produced by GDB's + internals. + + +File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Breakpoint Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records + +27.5.3 GDB/MI Async Records +--------------------------- + +"Async" records are used to notify the GDB/MI client of additional +changes that have occurred. Those changes can either be a consequence +of GDB/MI commands (e.g., a breakpoint modified) or a result of target +activity (e.g., target stopped). + + The following is the list of possible async records: + +'*running,thread-id="THREAD"' + The target is now running. The THREAD field tells which specific + thread is now running, and can be 'all' if all threads are running. + The frontend should assume that no interaction with a running + thread is possible after this notification is produced. The + frontend should not assume that this notification is output only + once for any command. GDB may emit this notification several + times, either for different threads, because it cannot resume all + threads together, or even for a single thread, if the thread must + be stepped though some code before letting it run freely. + +'*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"' + The target has stopped. The REASON field can have one of the + following values: + + 'breakpoint-hit' + A breakpoint was reached. + 'watchpoint-trigger' + A watchpoint was triggered. + 'read-watchpoint-trigger' + A read watchpoint was triggered. + 'access-watchpoint-trigger' + An access watchpoint was triggered. + 'function-finished' + An -exec-finish or similar CLI command was accomplished. + 'location-reached' + An -exec-until or similar CLI command was accomplished. + 'watchpoint-scope' + A watchpoint has gone out of scope. + 'end-stepping-range' + An -exec-next, -exec-next-instruction, -exec-step, + -exec-step-instruction or similar CLI command was + accomplished. + 'exited-signalled' + The inferior exited because of a signal. + 'exited' + The inferior exited. + 'exited-normally' + The inferior exited normally. + 'signal-received' + A signal was received by the inferior. + 'solib-event' + The inferior has stopped due to a library being loaded or + unloaded. This can happen when 'stop-on-solib-events' (*note + Files::) is set or when a 'catch load' or 'catch unload' + catchpoint is in use (*note Set Catchpoints::). + 'fork' + The inferior has forked. This is reported when 'catch fork' + (*note Set Catchpoints::) has been used. + 'vfork' + The inferior has vforked. This is reported in when 'catch + vfork' (*note Set Catchpoints::) has been used. + 'syscall-entry' + The inferior entered a system call. This is reported when + 'catch syscall' (*note Set Catchpoints::) has been used. + 'syscall-entry' + The inferior returned from a system call. This is reported + when 'catch syscall' (*note Set Catchpoints::) has been used. + 'exec' + The inferior called 'exec'. This is reported when 'catch + exec' (*note Set Catchpoints::) has been used. + + The ID field identifies the thread that directly caused the stop - + for example by hitting a breakpoint. Depending on whether all-stop + mode is in effect (*note All-Stop Mode::), GDB may either stop all + threads, or only the thread that directly triggered the stop. If + all threads are stopped, the STOPPED field will have the value of + '"all"'. Otherwise, the value of the STOPPED field will be a list + of thread identifiers. Presently, this list will always include a + single thread, but frontend should be prepared to see several + threads in the list. The CORE field reports the processor core on + which the stop event has happened. This field may be absent if + such information is not available. + +'=thread-group-added,id="ID"' +'=thread-group-removed,id="ID"' + A thread group was either added or removed. The ID field contains + the GDB identifier of the thread group. When a thread group is + added, it generally might not be associated with a running process. + When a thread group is removed, its id becomes invalid and cannot + be used in any way. + +'=thread-group-started,id="ID",pid="PID"' + A thread group became associated with a running program, either + because the program was just started or the thread group was + attached to a program. The ID field contains the GDB identifier of + the thread group. The PID field contains process identifier, + specific to the operating system. + +'=thread-group-exited,id="ID"[,exit-code="CODE"]' + A thread group is no longer associated with a running program, + either because the program has exited, or because it was detached + from. The ID field contains the GDB identifier of the thread + group. CODE is the exit code of the inferior; it exists only when + the inferior exited with some code. + +'=thread-created,id="ID",group-id="GID"' +'=thread-exited,id="ID",group-id="GID"' + A thread either was created, or has exited. The ID field contains + the GDB identifier of the thread. The GID field identifies the + thread group this thread belongs to. + +'=thread-selected,id="ID"' + Informs that the selected thread was changed as result of the last + command. This notification is not emitted as result of + '-thread-select' command but is emitted whenever an MI command that + is not documented to change the selected thread actually changes + it. In particular, invoking, directly or indirectly (via + user-defined command), the CLI 'thread' command, will generate this + notification. + + We suggest that in response to this notification, front ends + highlight the selected thread and cause subsequent commands to + apply to that thread. + +'=library-loaded,...' + Reports that a new library file was loaded by the program. This + notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and + SYMBOLS-LOADED. The ID field is an opaque identifier of the + library. For remote debugging case, TARGET-NAME and HOST-NAME + fields give the name of the library file on the target, and on the + host respectively. For native debugging, both those fields have + the same value. The SYMBOLS-LOADED field is emitted only for + backward compatibility and should not be relied on to convey any + useful information. The THREAD-GROUP field, if present, specifies + the id of the thread group in whose context the library was loaded. + If the field is absent, it means the library was loaded in the + context of all present thread groups. + +'=library-unloaded,...' + Reports that a library was unloaded by the program. This + notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the + same meaning as for the '=library-loaded' notification. The + THREAD-GROUP field, if present, specifies the id of the thread + group in whose context the library was unloaded. If the field is + absent, it means the library was unloaded in the context of all + present thread groups. + +'=traceframe-changed,num=TFNUM,tracepoint=TPNUM' +'=traceframe-changed,end' + Reports that the trace frame was changed and its new number is + TFNUM. The number of the tracepoint associated with this trace + frame is TPNUM. + +'=tsv-created,name=NAME,initial=INITIAL' + Reports that the new trace state variable NAME is created with + initial value INITIAL. + +'=tsv-deleted,name=NAME' +'=tsv-deleted' + Reports that the trace state variable NAME is deleted or all trace + state variables are deleted. + +'=tsv-modified,name=NAME,initial=INITIAL[,current=CURRENT]' + Reports that the trace state variable NAME is modified with the + initial value INITIAL. The current value CURRENT of trace state + variable is optional and is reported if the current value of trace + state variable is known. + +'=breakpoint-created,bkpt={...}' +'=breakpoint-modified,bkpt={...}' +'=breakpoint-deleted,id=NUMBER' + Reports that a breakpoint was created, modified, or deleted, + respectively. Only user-visible breakpoints are reported to the MI + user. + + The BKPT argument is of the same form as returned by the various + breakpoint commands; *Note GDB/MI Breakpoint Commands::. The + NUMBER is the ordinal number of the breakpoint. + + Note that if a breakpoint is emitted in the result record of a + command, then it will not also be emitted in an async record. + +'=record-started,thread-group="ID"' +'=record-stopped,thread-group="ID"' + Execution log recording was either started or stopped on an + inferior. The ID is the GDB identifier of the thread group + corresponding to the affected inferior. + +'=cmd-param-changed,param=PARAM,value=VALUE' + Reports that a parameter of the command 'set PARAM' is changed to + VALUE. In the multi-word 'set' command, the PARAM is the whole + parameter list to 'set' command. For example, In command 'set + check type on', PARAM is 'check type' and VALUE is 'on'. + +'=memory-changed,thread-group=ID,addr=ADDR,len=LEN[,type="code"]' + Reports that bytes from ADDR to DATA + LEN were written in an + inferior. The ID is the identifier of the thread group + corresponding to the affected inferior. The optional 'type="code"' + part is reported if the memory written to holds executable code. + + +File: gdb.info, Node: GDB/MI Breakpoint Information, Next: GDB/MI Frame Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records + +27.5.4 GDB/MI Breakpoint Information +------------------------------------ + +When GDB reports information about a breakpoint, a tracepoint, a +watchpoint, or a catchpoint, it uses a tuple with the following fields: + +'number' + The breakpoint number. For a breakpoint that represents one + location of a multi-location breakpoint, this will be a dotted + pair, like '1.2'. + +'type' + The type of the breakpoint. For ordinary breakpoints this will be + 'breakpoint', but many values are possible. + +'catch-type' + If the type of the breakpoint is 'catchpoint', then this indicates + the exact type of catchpoint. + +'disp' + This is the breakpoint disposition--either 'del', meaning that the + breakpoint will be deleted at the next stop, or 'keep', meaning + that the breakpoint will not be deleted. + +'enabled' + This indicates whether the breakpoint is enabled, in which case the + value is 'y', or disabled, in which case the value is 'n'. Note + that this is not the same as the field 'enable'. + +'addr' + The address of the breakpoint. This may be a hexidecimal number, + giving the address; or the string '', for a pending + breakpoint; or the string '', for a breakpoint with + multiple locations. This field will not be present if no address + can be determined. For example, a watchpoint does not have an + address. + +'func' + If known, the function in which the breakpoint appears. If not + known, this field is not present. + +'filename' + The name of the source file which contains this function, if known. + If not known, this field is not present. + +'fullname' + The full file name of the source file which contains this function, + if known. If not known, this field is not present. + +'line' + The line number at which this breakpoint appears, if known. If not + known, this field is not present. + +'at' + If the source file is not known, this field may be provided. If + provided, this holds the address of the breakpoint, possibly + followed by a symbol name. + +'pending' + If this breakpoint is pending, this field is present and holds the + text used to set the breakpoint, as entered by the user. + +'evaluated-by' + Where this breakpoint's condition is evaluated, either 'host' or + 'target'. + +'thread' + If this is a thread-specific breakpoint, then this identifies the + thread in which the breakpoint can trigger. + +'task' + If this breakpoint is restricted to a particular Ada task, then + this field will hold the task identifier. + +'cond' + If the breakpoint is conditional, this is the condition expression. + +'ignore' + The ignore count of the breakpoint. + +'enable' + The enable count of the breakpoint. + +'traceframe-usage' + FIXME. + +'static-tracepoint-marker-string-id' + For a static tracepoint, the name of the static tracepoint marker. + +'mask' + For a masked watchpoint, this is the mask. + +'pass' + A tracepoint's pass count. + +'original-location' + The location of the breakpoint as originally specified by the user. + This field is optional. + +'times' + The number of times the breakpoint has been hit. + +'installed' + This field is only given for tracepoints. This is either 'y', + meaning that the tracepoint is installed, or 'n', meaning that it + is not. + +'what' + Some extra data, the exact contents of which are type-dependent. + + For example, here is what the output of '-break-insert' (*note GDB/MI +Breakpoint Commands::) might be: + + -> -break-insert main + <- ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x08048564",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], + times="0"} + <- (gdb) + + +File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Breakpoint Information, Up: GDB/MI Output Records + +27.5.5 GDB/MI Frame Information +------------------------------- + +Response from many MI commands includes an information about stack +frame. This information is a tuple that may have the following fields: + +'level' + The level of the stack frame. The innermost frame has the level of + zero. This field is always present. + +'func' + The name of the function corresponding to the frame. This field + may be absent if GDB is unable to determine the function name. + +'addr' + The code address for the frame. This field is always present. + +'file' + The name of the source files that correspond to the frame's code + address. This field may be absent. + +'line' + The source line corresponding to the frames' code address. This + field may be absent. + +'from' + The name of the binary file (either executable or shared library) + the corresponds to the frame's code address. This field may be + absent. + + +File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records + +27.5.6 GDB/MI Thread Information +-------------------------------- + +Whenever GDB has to report an information about a thread, it uses a +tuple with the following fields: + +'id' + The numeric id assigned to the thread by GDB. This field is always + present. + +'target-id' + Target-specific string identifying the thread. This field is + always present. + +'details' + Additional information about the thread provided by the target. It + is supposed to be human-readable and not interpreted by the + frontend. This field is optional. + +'state' + Either 'stopped' or 'running', depending on whether the thread is + presently running. This field is always present. + +'core' + The value of this field is an integer number of the processor core + the thread was last seen on. This field is optional. + + +File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records + +27.5.7 GDB/MI Ada Exception Information +--------------------------------------- + +Whenever a '*stopped' record is emitted because the program stopped +after hitting an exception catchpoint (*note Set Catchpoints::), GDB +provides the name of the exception that was raised via the +'exception-name' field. + + +File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI + +27.6 Simple Examples of GDB/MI Interaction +========================================== + +This subsection presents several simple examples of interaction using +the GDB/MI interface. In these examples, '->' means that the following +line is passed to GDB/MI as input, while '<-' means the output received +from GDB/MI. + + Note the line breaks shown in the examples are here only for +readability, they don't appear in the real output. + +Setting a Breakpoint +-------------------- + +Setting a breakpoint generates synchronous output which contains +detailed information of the breakpoint. + + -> -break-insert main + <- ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x08048564",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], + times="0"} + <- (gdb) + +Program Execution +----------------- + +Program execution generates asynchronous records and MI gives the reason +that execution stopped. + + -> -exec-run + <- ^running + <- (gdb) + <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", + frame={addr="0x08048564",func="main", + args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}], + file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"} + <- (gdb) + -> -exec-continue + <- ^running + <- (gdb) + <- *stopped,reason="exited-normally" + <- (gdb) + +Quitting GDB +------------ + +Quitting GDB just prints the result class '^exit'. + + -> (gdb) + <- -gdb-exit + <- ^exit + + Please note that '^exit' is printed immediately, but it might take +some time for GDB to actually exit. During that time, GDB performs +necessary cleanups, including killing programs being debugged or +disconnecting from debug hardware, so the frontend should wait till GDB +exits and should only forcibly kill GDB if it fails to exit in +reasonable time. + +A Bad Command +------------- + +Here's what happens if you pass a non-existent command: + + -> -rubbish + <- ^error,msg="Undefined MI command: rubbish" + <- (gdb) + + +File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI + +27.7 GDB/MI Command Description Format +====================================== + +The remaining sections describe blocks of commands. Each block of +commands is laid out in a fashion similar to this section. + +Motivation +---------- + +The motivation for this collection of commands. + +Introduction +------------ + +A brief introduction to this collection of commands as a whole. + +Commands +-------- + +For each command in the block, the following is described: + +Synopsis +........ + + -command ARGS... + +Result +...... + +GDB Command +........... + +The corresponding GDB CLI command(s), if any. + +Example +....... + +Example(s) formatted for readability. Some of the described commands +have not been implemented yet and these are labeled N.A. (not +available). + + +File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Catchpoint Commands, Prev: GDB/MI Command Description Format, Up: GDB/MI + +27.8 GDB/MI Breakpoint Commands +=============================== + +This section documents GDB/MI commands for manipulating breakpoints. + +The '-break-after' Command +-------------------------- + +Synopsis +........ + + -break-after NUMBER COUNT + + The breakpoint number NUMBER is not in effect until it has been hit +COUNT times. To see how this is reflected in the output of the +'-break-list' command, see the description of the '-break-list' command +below. + +GDB Command +........... + +The corresponding GDB command is 'ignore'. + +Example +....... + + (gdb) + -break-insert main + ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x000100d0",func="main",file="hello.c", + fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], + times="0"} + (gdb) + -break-after 1 3 + ~ + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",thread-groups=["i1"],times="0",ignore="3"}]} + (gdb) + +The '-break-commands' Command +----------------------------- + +Synopsis +........ + + -break-commands NUMBER [ COMMAND1 ... COMMANDN ] + + Specifies the CLI commands that should be executed when breakpoint +NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands. +If no command is specified, any previously-set commands are cleared. +*Note Break Commands::. Typical use of this functionality is tracing a +program, that is, printing of values of some variables whenever +breakpoint is hit and then continuing. + +GDB Command +........... + +The corresponding GDB command is 'commands'. + +Example +....... + + (gdb) + -break-insert main + ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x000100d0",func="main",file="hello.c", + fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], + times="0"} + (gdb) + -break-commands 1 "print v" "continue" + ^done + (gdb) + +The '-break-condition' Command +------------------------------ + +Synopsis +........ + + -break-condition NUMBER EXPR + + Breakpoint NUMBER will stop the program only if the condition in EXPR +is true. The condition becomes part of the '-break-list' output (see +the description of the '-break-list' command below). + +GDB Command +........... + +The corresponding GDB command is 'condition'. + +Example +....... + + (gdb) + -break-condition 1 1 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"}]} + (gdb) + +The '-break-delete' Command +--------------------------- + +Synopsis +........ + + -break-delete ( BREAKPOINT )+ + + Delete the breakpoint(s) whose number(s) are specified in the +argument list. This is obviously reflected in the breakpoint list. + +GDB Command +........... + +The corresponding GDB command is 'delete'. + +Example +....... + + (gdb) + -break-delete 1 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="0",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[]} + (gdb) + +The '-break-disable' Command +---------------------------- + +Synopsis +........ + + -break-disable ( BREAKPOINT )+ + + Disable the named BREAKPOINT(s). The field 'enabled' in the break +list is now set to 'n' for the named BREAKPOINT(s). + +GDB Command +........... + +The corresponding GDB command is 'disable'. + +Example +....... + + (gdb) + -break-disable 2 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",thread-groups=["i1"],times="0"}]} + (gdb) + +The '-break-enable' Command +--------------------------- + +Synopsis +........ + + -break-enable ( BREAKPOINT )+ + + Enable (previously disabled) BREAKPOINT(s). + +GDB Command +........... + +The corresponding GDB command is 'enable'. + +Example +....... + + (gdb) + -break-enable 2 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",thread-groups=["i1"],times="0"}]} + (gdb) + +The '-break-info' Command +------------------------- + +Synopsis +........ + + -break-info BREAKPOINT + + Get information about a single breakpoint. + + The result is a table of breakpoints. *Note GDB/MI Breakpoint +Information::, for details on the format of each breakpoint in the +table. + +GDB Command +........... + +The corresponding GDB command is 'info break BREAKPOINT'. + +Example +....... + +N.A. + +The '-break-insert' Command +--------------------------- + +Synopsis +........ + + -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] + [ -c CONDITION ] [ -i IGNORE-COUNT ] + [ -p THREAD-ID ] [ LOCATION ] + +If specified, LOCATION, can be one of: + + * function + * filename:linenum + * filename:function + * *address + + The possible optional parameters of this command are: + +'-t' + Insert a temporary breakpoint. +'-h' + Insert a hardware breakpoint. +'-f' + If LOCATION cannot be parsed (for example if it refers to unknown + files or functions), create a pending breakpoint. Without this + flag, GDB will report an error, and won't create a breakpoint, if + LOCATION cannot be parsed. +'-d' + Create a disabled breakpoint. +'-a' + Create a tracepoint. *Note Tracepoints::. When this parameter is + used together with '-h', a fast tracepoint is created. +'-c CONDITION' + Make the breakpoint conditional on CONDITION. +'-i IGNORE-COUNT' + Initialize the IGNORE-COUNT. +'-p THREAD-ID' + Restrict the breakpoint to the specified THREAD-ID. + +Result +...... + +*Note GDB/MI Breakpoint Information::, for details on the format of the +resulting breakpoint. + + Note: this format is open to change. + +GDB Command +........... + +The corresponding GDB commands are 'break', 'tbreak', 'hbreak', and +'thbreak'. + +Example +....... + + (gdb) + -break-insert main + ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", + fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"], + times="0"} + (gdb) + -break-insert -t foo + ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", + fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"], + times="0"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x0001072c", func="main",file="recursive2.c", + fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"], + times="0"}, + bkpt={number="2",type="breakpoint",disp="del",enabled="y", + addr="0x00010774",func="foo",file="recursive2.c", + fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"], + times="0"}]} + (gdb) + +The '-dprintf-insert' Command +----------------------------- + +Synopsis +........ + + -dprintf-insert [ -t ] [ -f ] [ -d ] + [ -c CONDITION ] [ -i IGNORE-COUNT ] + [ -p THREAD-ID ] [ LOCATION ] [ FORMAT ] + [ ARGUMENT ] + +If specified, LOCATION, can be one of: + + * FUNCTION + * FILENAME:LINENUM + * FILENAME:function + * *ADDRESS + + The possible optional parameters of this command are: + +'-t' + Insert a temporary breakpoint. +'-f' + If LOCATION cannot be parsed (for example, if it refers to unknown + files or functions), create a pending breakpoint. Without this + flag, GDB will report an error, and won't create a breakpoint, if + LOCATION cannot be parsed. +'-d' + Create a disabled breakpoint. +'-c CONDITION' + Make the breakpoint conditional on CONDITION. +'-i IGNORE-COUNT' + Set the ignore count of the breakpoint (*note ignore count: + Conditions.) to IGNORE-COUNT. +'-p THREAD-ID' + Restrict the breakpoint to the specified THREAD-ID. + +Result +...... + +*Note GDB/MI Breakpoint Information::, for details on the format of the +resulting breakpoint. + +GDB Command +........... + +The corresponding GDB command is 'dprintf'. + +Example +....... + + (gdb) + 4-dprintf-insert foo "At foo entry\n" + 4^done,bkpt={number="1",type="dprintf",disp="keep",enabled="y", + addr="0x000000000040061b",func="foo",file="mi-dprintf.c", + fullname="mi-dprintf.c",line="25",thread-groups=["i1"], + times="0",script={"printf \"At foo entry\\n\"","continue"}, + original-location="foo"} + (gdb) + 5-dprintf-insert 26 "arg=%d, g=%d\n" arg g + 5^done,bkpt={number="2",type="dprintf",disp="keep",enabled="y", + addr="0x000000000040062a",func="foo",file="mi-dprintf.c", + fullname="mi-dprintf.c",line="26",thread-groups=["i1"], + times="0",script={"printf \"arg=%d, g=%d\\n\", arg, g","continue"}, + original-location="mi-dprintf.c:26"} + (gdb) + +The '-break-list' Command +------------------------- + +Synopsis +........ + + -break-list + + Displays the list of inserted breakpoints, showing the following +fields: + +'Number' + number of the breakpoint +'Type' + type of the breakpoint: 'breakpoint' or 'watchpoint' +'Disposition' + should the breakpoint be deleted or disabled when it is hit: 'keep' + or 'nokeep' +'Enabled' + is the breakpoint enabled or no: 'y' or 'n' +'Address' + memory location at which the breakpoint is set +'What' + logical location of the breakpoint, expressed by function name, + file name, line number +'Thread-groups' + list of thread groups to which this breakpoint applies +'Times' + number of times the breakpoint has been hit + + If there are no breakpoints or watchpoints, the 'BreakpointTable' +'body' field is an empty list. + +GDB Command +........... + +The corresponding GDB command is 'info break'. + +Example +....... + + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"], + times="0"}, + bkpt={number="2",type="breakpoint",disp="keep",enabled="y", + addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", + line="13",thread-groups=["i1"],times="0"}]} + (gdb) + + Here's an example of the result when there are no breakpoints: + + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="0",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[]} + (gdb) + +The '-break-passcount' Command +------------------------------ + +Synopsis +........ + + -break-passcount TRACEPOINT-NUMBER PASSCOUNT + + Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If +the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint, +error is emitted. This corresponds to CLI command 'passcount'. + +The '-break-watch' Command +-------------------------- + +Synopsis +........ + + -break-watch [ -a | -r ] + + Create a watchpoint. With the '-a' option it will create an "access" +watchpoint, i.e., a watchpoint that triggers either on a read from or on +a write to the memory location. With the '-r' option, the watchpoint +created is a "read" watchpoint, i.e., it will trigger only when the +memory location is accessed for reading. Without either of the options, +the watchpoint created is a regular watchpoint, i.e., it will trigger +when the memory location is accessed for writing. *Note Setting +Watchpoints: Set Watchpoints. + + Note that '-break-list' will report a single list of watchpoints and +breakpoints inserted. + +GDB Command +........... + +The corresponding GDB commands are 'watch', 'awatch', and 'rwatch'. + +Example +....... + +Setting a watchpoint on a variable in the 'main' function: + + (gdb) + -break-watch x + ^done,wpt={number="2",exp="x"} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"}, + value={old="-268439212",new="55"}, + frame={func="main",args=[],file="recursive2.c", + fullname="/home/foo/bar/recursive2.c",line="5"} + (gdb) + + Setting a watchpoint on a variable local to a function. GDB will +stop the program execution twice: first for the variable changing value, +then for the watchpoint going out of scope. + + (gdb) + -break-watch C + ^done,wpt={number="5",exp="C"} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-trigger", + wpt={number="5",exp="C"},value={old="-276895068",new="3"}, + frame={func="callee4",args=[], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-scope",wpnum="5", + frame={func="callee3",args=[{name="strarg", + value="0x11940 \"A string argument.\""}], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} + (gdb) + + Listing breakpoints and watchpoints, at different points in the +program execution. Note that once the watchpoint goes out of scope, it +is deleted. + + (gdb) + -break-watch C + ^done,wpt={number="2",exp="C"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"], + times="1"}, + bkpt={number="2",type="watchpoint",disp="keep", + enabled="y",addr="",what="C",thread-groups=["i1"],times="0"}]} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"}, + value={old="-276895068",new="3"}, + frame={func="callee4",args=[], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"], + times="1"}, + bkpt={number="2",type="watchpoint",disp="keep", + enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"}]} + (gdb) + -exec-continue + ^running + ^done,reason="watchpoint-scope",wpnum="2", + frame={func="callee3",args=[{name="strarg", + value="0x11940 \"A string argument.\""}], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", + thread-groups=["i1"],times="1"}]} + (gdb) + + +File: gdb.info, Node: GDB/MI Catchpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI + +27.9 GDB/MI Catchpoint Commands +=============================== + +This section documents GDB/MI commands for manipulating catchpoints. + +* Menu: + +* Shared Library GDB/MI Catchpoint Commands:: +* Ada Exception GDB/MI Catchpoint Commands:: + + +File: gdb.info, Node: Shared Library GDB/MI Catchpoint Commands, Next: Ada Exception GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands + +27.9.1 Shared Library GDB/MI Catchpoints +---------------------------------------- + +The '-catch-load' Command +------------------------- + +Synopsis +........ + + -catch-load [ -t ] [ -d ] REGEXP + + Add a catchpoint for library load events. If the '-t' option is +used, the catchpoint is a temporary one (*note Setting Breakpoints: Set +Breaks.). If the '-d' option is used, the catchpoint is created in a +disabled state. The 'regexp' argument is a regular expression used to +match the name of the loaded library. + +GDB Command +........... + +The corresponding GDB command is 'catch load'. + +Example +....... + + -catch-load -t foo.so + ^done,bkpt={number="1",type="catchpoint",disp="del",enabled="y", + what="load of library matching foo.so",catch-type="load",times="0"} + (gdb) + +The '-catch-unload' Command +--------------------------- + +Synopsis +........ + + -catch-unload [ -t ] [ -d ] REGEXP + + Add a catchpoint for library unload events. If the '-t' option is +used, the catchpoint is a temporary one (*note Setting Breakpoints: Set +Breaks.). If the '-d' option is used, the catchpoint is created in a +disabled state. The 'regexp' argument is a regular expression used to +match the name of the unloaded library. + +GDB Command +........... + +The corresponding GDB command is 'catch unload'. + +Example +....... + + -catch-unload -d bar.so + ^done,bkpt={number="2",type="catchpoint",disp="keep",enabled="n", + what="load of library matching bar.so",catch-type="unload",times="0"} + (gdb) + + +File: gdb.info, Node: Ada Exception GDB/MI Catchpoint Commands, Prev: Shared Library GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands + +27.9.2 Ada Exception GDB/MI Catchpoints +--------------------------------------- + +The following GDB/MI commands can be used to create catchpoints that +stop the execution when Ada exceptions are being raised. + +The '-catch-assert' Command +--------------------------- + +Synopsis +........ + + -catch-assert [ -c CONDITION] [ -d ] [ -t ] + + Add a catchpoint for failed Ada assertions. + + The possible optional parameters for this command are: + +'-c CONDITION' + Make the catchpoint conditional on CONDITION. +'-d' + Create a disabled catchpoint. +'-t' + Create a temporary catchpoint. + +GDB Command +........... + +The corresponding GDB command is 'catch assert'. + +Example +....... + + -catch-assert + ^done,bkptno="5",bkpt={number="5",type="breakpoint",disp="keep", + enabled="y",addr="0x0000000000404888",what="failed Ada assertions", + thread-groups=["i1"],times="0", + original-location="__gnat_debug_raise_assert_failure"} + (gdb) + +The '-catch-exception' Command +------------------------------ + +Synopsis +........ + + -catch-exception [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ] + [ -t ] [ -u ] + + Add a catchpoint stopping when Ada exceptions are raised. By +default, the command stops the program when any Ada exception gets +raised. But it is also possible, by using some of the optional +parameters described below, to create more selective catchpoints. + + The possible optional parameters for this command are: + +'-c CONDITION' + Make the catchpoint conditional on CONDITION. +'-d' + Create a disabled catchpoint. +'-e EXCEPTION-NAME' + Only stop when EXCEPTION-NAME is raised. This option cannot be + used combined with '-u'. +'-t' + Create a temporary catchpoint. +'-u' + Stop only when an unhandled exception gets raised. This option + cannot be used combined with '-e'. + +GDB Command +........... + +The corresponding GDB commands are 'catch exception' and 'catch +exception unhandled'. + +Example +....... + + -catch-exception -e Program_Error + ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep", + enabled="y",addr="0x0000000000404874", + what="`Program_Error' Ada exception", thread-groups=["i1"], + times="0",original-location="__gnat_debug_raise_exception"} + (gdb) + + +File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Catchpoint Commands, Up: GDB/MI + +27.10 GDB/MI Program Context +============================ + +The '-exec-arguments' Command +----------------------------- + +Synopsis +........ + + -exec-arguments ARGS + + Set the inferior program arguments, to be used in the next +'-exec-run'. + +GDB Command +........... + +The corresponding GDB command is 'set args'. + +Example +....... + + (gdb) + -exec-arguments -v word + ^done + (gdb) + +The '-environment-cd' Command +----------------------------- + +Synopsis +........ + + -environment-cd PATHDIR + + Set GDB's working directory. + +GDB Command +........... + +The corresponding GDB command is 'cd'. + +Example +....... + + (gdb) + -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb + ^done + (gdb) + +The '-environment-directory' Command +------------------------------------ + +Synopsis +........ + + -environment-directory [ -r ] [ PATHDIR ]+ + + Add directories PATHDIR to beginning of search path for source files. +If the '-r' option is used, the search path is reset to the default +search path. If directories PATHDIR are supplied in addition to the +'-r' option, the search path is first reset and then addition occurs as +normal. Multiple directories may be specified, separated by blanks. +Specifying multiple directories in a single command results in the +directories added to the beginning of the search path in the same order +they were presented in the command. If blanks are needed as part of a +directory name, double-quotes should be used around the name. In the +command output, the path will show up separated by the system +directory-separator character. The directory-separator character must +not be used in any directory name. If no directories are specified, the +current search path is displayed. + +GDB Command +........... + +The corresponding GDB command is 'dir'. + +Example +....... + + (gdb) + -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb + ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" + (gdb) + -environment-directory "" + ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" + (gdb) + -environment-directory -r /home/jjohnstn/src/gdb /usr/src + ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" + (gdb) + -environment-directory -r + ^done,source-path="$cdir:$cwd" + (gdb) + +The '-environment-path' Command +------------------------------- + +Synopsis +........ + + -environment-path [ -r ] [ PATHDIR ]+ + + Add directories PATHDIR to beginning of search path for object files. +If the '-r' option is used, the search path is reset to the original +search path that existed at gdb start-up. If directories PATHDIR are +supplied in addition to the '-r' option, the search path is first reset +and then addition occurs as normal. Multiple directories may be +specified, separated by blanks. Specifying multiple directories in a +single command results in the directories added to the beginning of the +search path in the same order they were presented in the command. If +blanks are needed as part of a directory name, double-quotes should be +used around the name. In the command output, the path will show up +separated by the system directory-separator character. The +directory-separator character must not be used in any directory name. +If no directories are specified, the current path is displayed. + +GDB Command +........... + +The corresponding GDB command is 'path'. + +Example +....... + + (gdb) + -environment-path + ^done,path="/usr/bin" + (gdb) + -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin + ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" + (gdb) + -environment-path -r /usr/local/bin + ^done,path="/usr/local/bin:/usr/bin" + (gdb) + +The '-environment-pwd' Command +------------------------------ + +Synopsis +........ + + -environment-pwd + + Show the current working directory. + +GDB Command +........... + +The corresponding GDB command is 'pwd'. + +Example +....... + + (gdb) + -environment-pwd + ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" + (gdb) + + +File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Ada Tasking Commands, Prev: GDB/MI Program Context, Up: GDB/MI + +27.11 GDB/MI Thread Commands +============================ + +The '-thread-info' Command +-------------------------- + +Synopsis +........ + + -thread-info [ THREAD-ID ] + + Reports information about either a specific thread, if the THREAD-ID +parameter is present, or about all threads. When printing information +about all threads, also reports the current thread. + +GDB Command +........... + +The 'info thread' command prints the same information about all threads. + +Result +...... + +The result is a list of threads. The following attributes are defined +for a given thread: + +'current' + This field exists only for the current thread. It has the value + '*'. + +'id' + The identifier that GDB uses to refer to the thread. + +'target-id' + The identifier that the target uses to refer to the thread. + +'details' + Extra information about the thread, in a target-specific format. + This field is optional. + +'name' + The name of the thread. If the user specified a name using the + 'thread name' command, then this name is given. Otherwise, if GDB + can extract the thread name from the target, then that name is + given. If GDB cannot find the thread name, then this field is + omitted. + +'frame' + The stack frame currently executing in the thread. + +'state' + The thread's state. The 'state' field may have the following + values: + + 'stopped' + The thread is stopped. Frame information is available for + stopped threads. + + 'running' + The thread is running. There's no frame information for + running threads. + +'core' + If GDB can find the CPU core on which this thread is running, then + this field is the core identifier. This field is optional. + +Example +....... + + -thread-info + ^done,threads=[ + {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", + frame={level="0",addr="0xffffe410",func="__kernel_vsyscall", + args=[]},state="running"}, + {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", + frame={level="0",addr="0x0804891f",func="foo", + args=[{name="i",value="10"}], + file="/tmp/a.c",fullname="/tmp/a.c",line="158"}, + state="running"}], + current-thread-id="1" + (gdb) + +The '-thread-list-ids' Command +------------------------------ + +Synopsis +........ + + -thread-list-ids + + Produces a list of the currently known GDB thread ids. At the end of +the list it also prints the total number of such threads. + + This command is retained for historical reasons, the '-thread-info' +command should be used instead. + +GDB Command +........... + +Part of 'info threads' supplies the same information. + +Example +....... + + (gdb) + -thread-list-ids + ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, + current-thread-id="1",number-of-threads="3" + (gdb) + +The '-thread-select' Command +---------------------------- + +Synopsis +........ + + -thread-select THREADNUM + + Make THREADNUM the current thread. It prints the number of the new +current thread, and the topmost frame for that thread. + + This command is deprecated in favor of explicitly using the +'--thread' option to each command. + +GDB Command +........... + +The corresponding GDB command is 'thread'. + +Example +....... + + (gdb) + -exec-next + ^running + (gdb) + *stopped,reason="end-stepping-range",thread-id="2",line="187", + file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" + (gdb) + -thread-list-ids + ^done, + thread-ids={thread-id="3",thread-id="2",thread-id="1"}, + number-of-threads="3" + (gdb) + -thread-select 3 + ^done,new-thread-id="3", + frame={level="0",func="vprintf", + args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, + {name="arg",value="0x2"}],file="vprintf.c",line="31"} + (gdb) + + +File: gdb.info, Node: GDB/MI Ada Tasking Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Thread Commands, Up: GDB/MI + +27.12 GDB/MI Ada Tasking Commands +================================= + +The '-ada-task-info' Command +---------------------------- + +Synopsis +........ + + -ada-task-info [ TASK-ID ] + + Reports information about either a specific Ada task, if the TASK-ID +parameter is present, or about all Ada tasks. + +GDB Command +........... + +The 'info tasks' command prints the same information about all Ada tasks +(*note Ada Tasks::). + +Result +...... + +The result is a table of Ada tasks. The following columns are defined +for each Ada task: + +'current' + This field exists only for the current thread. It has the value + '*'. + +'id' + The identifier that GDB uses to refer to the Ada task. + +'task-id' + The identifier that the target uses to refer to the Ada task. + +'thread-id' + The identifier of the thread corresponding to the Ada task. + + This field should always exist, as Ada tasks are always implemented + on top of a thread. But if GDB cannot find this corresponding + thread for any reason, the field is omitted. + +'parent-id' + This field exists only when the task was created by another task. + In this case, it provides the ID of the parent task. + +'priority' + The base priority of the task. + +'state' + The current state of the task. For a detailed description of the + possible states, see *note Ada Tasks::. + +'name' + The name of the task. + +Example +....... + + -ada-task-info + ^done,tasks={nr_rows="3",nr_cols="8", + hdr=[{width="1",alignment="-1",col_name="current",colhdr=""}, + {width="3",alignment="1",col_name="id",colhdr="ID"}, + {width="9",alignment="1",col_name="task-id",colhdr="TID"}, + {width="4",alignment="1",col_name="thread-id",colhdr=""}, + {width="4",alignment="1",col_name="parent-id",colhdr="P-ID"}, + {width="3",alignment="1",col_name="priority",colhdr="Pri"}, + {width="22",alignment="-1",col_name="state",colhdr="State"}, + {width="1",alignment="2",col_name="name",colhdr="Name"}], + body=[{current="*",id="1",task-id=" 644010",thread-id="1",priority="48", + state="Child Termination Wait",name="main_task"}]} + (gdb) + + +File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Ada Tasking Commands, Up: GDB/MI + +27.13 GDB/MI Program Execution +============================== + +These are the asynchronous commands which generate the out-of-band +record '*stopped'. Currently GDB only really executes asynchronously +with remote targets and this interaction is mimicked in other cases. + +The '-exec-continue' Command +---------------------------- + +Synopsis +........ + + -exec-continue [--reverse] [--all|--thread-group N] + + Resumes the execution of the inferior program, which will continue to +execute until it reaches a debugger stop event. If the '--reverse' +option is specified, execution resumes in reverse until it reaches a +stop event. Stop events may include + * breakpoints or watchpoints + * signals or exceptions + * the end of the process (or its beginning under '--reverse') + * the end or beginning of a replay log if one is being used. + In all-stop mode (*note All-Stop Mode::), may resume only one thread, +or all threads, depending on the value of the 'scheduler-locking' +variable. If '--all' is specified, all threads (in all inferiors) will +be resumed. The '--all' option is ignored in all-stop mode. If the +'--thread-group' options is specified, then all threads in that thread +group are resumed. + +GDB Command +........... + +The corresponding GDB corresponding is 'continue'. + +Example +....... + + -exec-continue + ^running + (gdb) + @Hello world + *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={ + func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", + line="13"} + (gdb) + +The '-exec-finish' Command +-------------------------- + +Synopsis +........ + + -exec-finish [--reverse] + + Resumes the execution of the inferior program until the current +function is exited. Displays the results returned by the function. If +the '--reverse' option is specified, resumes the reverse execution of +the inferior program until the point where current function was called. + +GDB Command +........... + +The corresponding GDB command is 'finish'. + +Example +....... + +Function returning 'void'. + + -exec-finish + ^running + (gdb) + @hello from foo + *stopped,reason="function-finished",frame={func="main",args=[], + file="hello.c",fullname="/home/foo/bar/hello.c",line="7"} + (gdb) + + Function returning other than 'void'. The name of the internal GDB +variable storing the result is printed, together with the value itself. + + -exec-finish + ^running + (gdb) + *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", + args=[{name="a",value="1"],{name="b",value="9"}}, + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + gdb-result-var="$1",return-value="0" + (gdb) + +The '-exec-interrupt' Command +----------------------------- + +Synopsis +........ + + -exec-interrupt [--all|--thread-group N] + + Interrupts the background execution of the target. Note how the +token associated with the stop message is the one for the execution +command that has been interrupted. The token for the interrupt itself +only appears in the '^done' output. If the user is trying to interrupt +a non-running program, an error message will be printed. + + Note that when asynchronous execution is enabled, this command is +asynchronous just like other execution commands. That is, first the +'^done' response will be printed, and the target stop will be reported +after that using the '*stopped' notification. + + In non-stop mode, only the context thread is interrupted by default. +All threads (in all inferiors) will be interrupted if the '--all' option +is specified. If the '--thread-group' option is specified, all threads +in that group will be interrupted. + +GDB Command +........... + +The corresponding GDB command is 'interrupt'. + +Example +....... + + (gdb) + 111-exec-continue + 111^running + + (gdb) + 222-exec-interrupt + 222^done + (gdb) + 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", + frame={addr="0x00010140",func="foo",args=[],file="try.c", + fullname="/home/foo/bar/try.c",line="13"} + (gdb) + + (gdb) + -exec-interrupt + ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." + (gdb) + +The '-exec-jump' Command +------------------------ + +Synopsis +........ + + -exec-jump LOCATION + + Resumes execution of the inferior program at the location specified +by parameter. *Note Specify Location::, for a description of the +different forms of LOCATION. + +GDB Command +........... + +The corresponding GDB command is 'jump'. + +Example +....... + + -exec-jump foo.c:10 + *running,thread-id="all" + ^running + +The '-exec-next' Command +------------------------ + +Synopsis +........ + + -exec-next [--reverse] + + Resumes execution of the inferior program, stopping when the +beginning of the next source line is reached. + + If the '--reverse' option is specified, resumes reverse execution of +the inferior program, stopping at the beginning of the previous source +line. If you issue this command on the first line of a function, it +will take you back to the caller of that function, to the source line +where the function was called. + +GDB Command +........... + +The corresponding GDB command is 'next'. + +Example +....... + + -exec-next + ^running + (gdb) + *stopped,reason="end-stepping-range",line="8",file="hello.c" + (gdb) + +The '-exec-next-instruction' Command +------------------------------------ + +Synopsis +........ + + -exec-next-instruction [--reverse] + + Executes one machine instruction. If the instruction is a function +call, continues until the function returns. If the program stops at an +instruction in the middle of a source line, the address will be printed +as well. + + If the '--reverse' option is specified, resumes reverse execution of +the inferior program, stopping at the previous instruction. If the +previously executed instruction was a return from another function, it +will continue to execute in reverse until the call to that function +(from the current stack frame) is reached. + +GDB Command +........... + +The corresponding GDB command is 'nexti'. + +Example +....... + + (gdb) + -exec-next-instruction + ^running + + (gdb) + *stopped,reason="end-stepping-range", + addr="0x000100d4",line="5",file="hello.c" + (gdb) + +The '-exec-return' Command +-------------------------- + +Synopsis +........ + + -exec-return + + Makes current function return immediately. Doesn't execute the +inferior. Displays the new current frame. + +GDB Command +........... + +The corresponding GDB command is 'return'. + +Example +....... + + (gdb) + 200-break-insert callee4 + 200^done,bkpt={number="1",addr="0x00010734", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} + (gdb) + 000-exec-run + 000^running + (gdb) + 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", + frame={func="callee4",args=[], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"} + (gdb) + 205-break-delete + 205^done + (gdb) + 111-exec-return + 111^done,frame={level="0",func="callee3", + args=[{name="strarg", + value="0x11940 \"A string argument.\""}], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} + (gdb) + +The '-exec-run' Command +----------------------- + +Synopsis +........ + + -exec-run [ --all | --thread-group N ] [ --start ] + + Starts execution of the inferior from the beginning. The inferior +executes until either a breakpoint is encountered or the program exits. +In the latter case the output will include an exit code, if the program +has exited exceptionally. + + When neither the '--all' nor the '--thread-group' option is +specified, the current inferior is started. If the '--thread-group' +option is specified, it should refer to a thread group of type +'process', and that thread group will be started. If the '--all' option +is specified, then all inferiors will be started. + + Using the '--start' option instructs the debugger to stop the +execution at the start of the inferior's main subprogram, following the +same behavior as the 'start' command (*note Starting::). + +GDB Command +........... + +The corresponding GDB command is 'run'. + +Examples +........ + + (gdb) + -break-insert main + ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} + (gdb) + -exec-run + ^running + (gdb) + *stopped,reason="breakpoint-hit",disp="keep",bkptno="1", + frame={func="main",args=[],file="recursive2.c", + fullname="/home/foo/bar/recursive2.c",line="4"} + (gdb) + +Program exited normally: + + (gdb) + -exec-run + ^running + (gdb) + x = 55 + *stopped,reason="exited-normally" + (gdb) + +Program exited exceptionally: + + (gdb) + -exec-run + ^running + (gdb) + x = 55 + *stopped,reason="exited",exit-code="01" + (gdb) + + Another way the program can terminate is if it receives a signal such +as 'SIGINT'. In this case, GDB/MI displays this: + + (gdb) + *stopped,reason="exited-signalled",signal-name="SIGINT", + signal-meaning="Interrupt" + +The '-exec-step' Command +------------------------ + +Synopsis +........ + + -exec-step [--reverse] + + Resumes execution of the inferior program, stopping when the +beginning of the next source line is reached, if the next source line is +not a function call. If it is, stop at the first instruction of the +called function. If the '--reverse' option is specified, resumes +reverse execution of the inferior program, stopping at the beginning of +the previously executed source line. + +GDB Command +........... + +The corresponding GDB command is 'step'. + +Example +....... + +Stepping into a function: + + -exec-step + ^running + (gdb) + *stopped,reason="end-stepping-range", + frame={func="foo",args=[{name="a",value="10"}, + {name="b",value="0"}],file="recursive2.c", + fullname="/home/foo/bar/recursive2.c",line="11"} + (gdb) + + Regular stepping: + + -exec-step + ^running + (gdb) + *stopped,reason="end-stepping-range",line="14",file="recursive2.c" + (gdb) + +The '-exec-step-instruction' Command +------------------------------------ + +Synopsis +........ + + -exec-step-instruction [--reverse] + + Resumes the inferior which executes one machine instruction. If the +'--reverse' option is specified, resumes reverse execution of the +inferior program, stopping at the previously executed instruction. The +output, once GDB has stopped, will vary depending on whether we have +stopped in the middle of a source line or not. In the former case, the +address at which the program stopped will be printed as well. + +GDB Command +........... + +The corresponding GDB command is 'stepi'. + +Example +....... + + (gdb) + -exec-step-instruction + ^running + + (gdb) + *stopped,reason="end-stepping-range", + frame={func="foo",args=[],file="try.c", + fullname="/home/foo/bar/try.c",line="10"} + (gdb) + -exec-step-instruction + ^running + + (gdb) + *stopped,reason="end-stepping-range", + frame={addr="0x000100f4",func="foo",args=[],file="try.c", + fullname="/home/foo/bar/try.c",line="10"} + (gdb) + +The '-exec-until' Command +------------------------- + +Synopsis +........ + + -exec-until [ LOCATION ] + + Executes the inferior until the LOCATION specified in the argument is +reached. If there is no argument, the inferior executes until a source +line greater than the current one is reached. The reason for stopping +in this case will be 'location-reached'. + +GDB Command +........... + +The corresponding GDB command is 'until'. + +Example +....... + + (gdb) + -exec-until recursive2.c:6 + ^running + (gdb) + x = 55 + *stopped,reason="location-reached",frame={func="main",args=[], + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"} + (gdb) + + +File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI + +27.14 GDB/MI Stack Manipulation Commands +======================================== + +The '-enable-frame-filters' Command +----------------------------------- + + -enable-frame-filters + + GDB allows Python-based frame filters to affect the output of the MI +commands relating to stack traces. As there is no way to implement this +in a fully backward-compatible way, a front end must request that this +functionality be enabled. + + Once enabled, this feature cannot be disabled. + + Note that if Python support has not been compiled into GDB, this +command will still succeed (and do nothing). + +The '-stack-info-frame' Command +------------------------------- + +Synopsis +........ + + -stack-info-frame + + Get info on the selected frame. + +GDB Command +........... + +The corresponding GDB command is 'info frame' or 'frame' (without +arguments). + +Example +....... + + (gdb) + -stack-info-frame + ^done,frame={level="1",addr="0x0001076c",func="callee3", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"} + (gdb) + +The '-stack-info-depth' Command +------------------------------- + +Synopsis +........ + + -stack-info-depth [ MAX-DEPTH ] + + Return the depth of the stack. If the integer argument MAX-DEPTH is +specified, do not count beyond MAX-DEPTH frames. + +GDB Command +........... + +There's no equivalent GDB command. + +Example +....... + +For a stack with frame levels 0 through 11: + + (gdb) + -stack-info-depth + ^done,depth="12" + (gdb) + -stack-info-depth 4 + ^done,depth="4" + (gdb) + -stack-info-depth 12 + ^done,depth="12" + (gdb) + -stack-info-depth 11 + ^done,depth="11" + (gdb) + -stack-info-depth 13 + ^done,depth="12" + (gdb) + +The '-stack-list-arguments' Command +----------------------------------- + +Synopsis +........ + + -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES + [ LOW-FRAME HIGH-FRAME ] + + Display a list of the arguments for the frames between LOW-FRAME and +HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, +list the arguments for the whole call stack. If the two arguments are +equal, show the single frame at the corresponding level. It is an error +if LOW-FRAME is larger than the actual number of frames. On the other +hand, HIGH-FRAME may be larger than the actual number of frames, in +which case only existing frames will be returned. + + If PRINT-VALUES is 0 or '--no-values', print only the names of the +variables; if it is 1 or '--all-values', print also their values; and if +it is 2 or '--simple-values', print the name, type and value for simple +data types, and the name and type for arrays, structures and unions. If +the option '--no-frame-filters' is supplied, then Python frame filters +will not be executed. + + If the '--skip-unavailable' option is specified, arguments that are +not available are not listed. Partially available arguments are still +displayed, however. + + Use of this command to obtain arguments in a single frame is +deprecated in favor of the '-stack-list-variables' command. + +GDB Command +........... + +GDB does not have an equivalent command. 'gdbtk' has a 'gdb_get_args' +command which partially overlaps with the functionality of +'-stack-list-arguments'. + +Example +....... + + (gdb) + -stack-list-frames + ^done, + stack=[ + frame={level="0",addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, + frame={level="1",addr="0x0001076c",func="callee3", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, + frame={level="2",addr="0x0001078c",func="callee2", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, + frame={level="3",addr="0x000107b4",func="callee1", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, + frame={level="4",addr="0x000107e0",func="main", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] + (gdb) + -stack-list-arguments 0 + ^done, + stack-args=[ + frame={level="0",args=[]}, + frame={level="1",args=[name="strarg"]}, + frame={level="2",args=[name="intarg",name="strarg"]}, + frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, + frame={level="4",args=[]}] + (gdb) + -stack-list-arguments 1 + ^done, + stack-args=[ + frame={level="0",args=[]}, + frame={level="1", + args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, + frame={level="2",args=[ + {name="intarg",value="2"}, + {name="strarg",value="0x11940 \"A string argument.\""}]}, + {frame={level="3",args=[ + {name="intarg",value="2"}, + {name="strarg",value="0x11940 \"A string argument.\""}, + {name="fltarg",value="3.5"}]}, + frame={level="4",args=[]}] + (gdb) + -stack-list-arguments 0 2 2 + ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] + (gdb) + -stack-list-arguments 1 2 2 + ^done,stack-args=[frame={level="2", + args=[{name="intarg",value="2"}, + {name="strarg",value="0x11940 \"A string argument.\""}]}] + (gdb) + +The '-stack-list-frames' Command +-------------------------------- + +Synopsis +........ + + -stack-list-frames [ --no-frame-filters LOW-FRAME HIGH-FRAME ] + + List the frames currently on the stack. For each frame it displays +the following info: + +'LEVEL' + The frame number, 0 being the topmost frame, i.e., the innermost + function. +'ADDR' + The '$pc' value for that frame. +'FUNC' + Function name. +'FILE' + File name of the source file where the function lives. +'FULLNAME' + The full file name of the source file where the function lives. +'LINE' + Line number corresponding to the '$pc'. +'FROM' + The shared library where this function is defined. This is only + given if the frame's function is not known. + + If invoked without arguments, this command prints a backtrace for the +whole stack. If given two integer arguments, it shows the frames whose +levels are between the two arguments (inclusive). If the two arguments +are equal, it shows the single frame at the corresponding level. It is +an error if LOW-FRAME is larger than the actual number of frames. On +the other hand, HIGH-FRAME may be larger than the actual number of +frames, in which case only existing frames will be returned. If the +option '--no-frame-filters' is supplied, then Python frame filters will +not be executed. + +GDB Command +........... + +The corresponding GDB commands are 'backtrace' and 'where'. + +Example +....... + +Full stack backtrace: + + (gdb) + -stack-list-frames + ^done,stack= + [frame={level="0",addr="0x0001076c",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"}, + frame={level="1",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="2",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="4",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="5",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="6",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="7",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="8",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="9",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="10",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="11",addr="0x00010738",func="main", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}] + (gdb) + + Show frames between LOW_FRAME and HIGH_FRAME: + + (gdb) + -stack-list-frames 3 5 + ^done,stack= + [frame={level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="4",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="5",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] + (gdb) + + Show a single frame: + + (gdb) + -stack-list-frames 3 3 + ^done,stack= + [frame={level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] + (gdb) + +The '-stack-list-locals' Command +-------------------------------- + +Synopsis +........ + + -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES + + Display the local variable names for the selected frame. If +PRINT-VALUES is 0 or '--no-values', print only the names of the +variables; if it is 1 or '--all-values', print also their values; and if +it is 2 or '--simple-values', print the name, type and value for simple +data types, and the name and type for arrays, structures and unions. In +this last case, a frontend can immediately display the value of simple +data types and create variable objects for other data types when the +user wishes to explore their values in more detail. If the option +'--no-frame-filters' is supplied, then Python frame filters will not be +executed. + + If the '--skip-unavailable' option is specified, local variables that +are not available are not listed. Partially available local variables +are still displayed, however. + + This command is deprecated in favor of the '-stack-list-variables' +command. + +GDB Command +........... + +'info locals' in GDB, 'gdb_get_locals' in 'gdbtk'. + +Example +....... + + (gdb) + -stack-list-locals 0 + ^done,locals=[name="A",name="B",name="C"] + (gdb) + -stack-list-locals --all-values + ^done,locals=[{name="A",value="1"},{name="B",value="2"}, + {name="C",value="{1, 2, 3}"}] + -stack-list-locals --simple-values + ^done,locals=[{name="A",type="int",value="1"}, + {name="B",type="int",value="2"},{name="C",type="int [3]"}] + (gdb) + +The '-stack-list-variables' Command +----------------------------------- + +Synopsis +........ + + -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES + + Display the names of local variables and function arguments for the +selected frame. If PRINT-VALUES is 0 or '--no-values', print only the +names of the variables; if it is 1 or '--all-values', print also their +values; and if it is 2 or '--simple-values', print the name, type and +value for simple data types, and the name and type for arrays, +structures and unions. If the option '--no-frame-filters' is supplied, +then Python frame filters will not be executed. + + If the '--skip-unavailable' option is specified, local variables and +arguments that are not available are not listed. Partially available +arguments and local variables are still displayed, however. + +Example +....... + + (gdb) + -stack-list-variables --thread 1 --frame 0 --all-values + ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}] + (gdb) + +The '-stack-select-frame' Command +--------------------------------- + +Synopsis +........ + + -stack-select-frame FRAMENUM + + Change the selected frame. Select a different frame FRAMENUM on the +stack. + + This command in deprecated in favor of passing the '--frame' option +to every command. + +GDB Command +........... + +The corresponding GDB commands are 'frame', 'up', 'down', +'select-frame', 'up-silent', and 'down-silent'. + +Example +....... + + (gdb) + -stack-select-frame 2 + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI + +27.15 GDB/MI Variable Objects +============================= + +Introduction to Variable Objects +-------------------------------- + +Variable objects are "object-oriented" MI interface for examining and +changing values of expressions. Unlike some other MI interfaces that +work with expressions, variable objects are specifically designed for +simple and efficient presentation in the frontend. A variable object is +identified by string name. When a variable object is created, the +frontend specifies the expression for that variable object. The +expression can be a simple variable, or it can be an arbitrary complex +expression, and can even involve CPU registers. After creating a +variable object, the frontend can invoke other variable object +operations--for example to obtain or change the value of a variable +object, or to change display format. + + Variable objects have hierarchical tree structure. Any variable +object that corresponds to a composite type, such as structure in C, has +a number of child variable objects, for example corresponding to each +element of a structure. A child variable object can itself have +children, recursively. Recursion ends when we reach leaf variable +objects, which always have built-in types. Child variable objects are +created only by explicit request, so if a frontend is not interested in +the children of a particular variable object, no child will be created. + + For a leaf variable object it is possible to obtain its value as a +string, or set the value from a string. String value can be also +obtained for a non-leaf variable object, but it's generally a string +that only indicates the type of the object, and does not list its +contents. Assignment to a non-leaf variable object is not allowed. + + A frontend does not need to read the values of all variable objects +each time the program stops. Instead, MI provides an update command +that lists all variable objects whose values has changed since the last +update operation. This considerably reduces the amount of data that +must be transferred to the frontend. As noted above, children variable +objects are created on demand, and only leaf variable objects have a +real value. As result, gdb will read target memory only for leaf +variables that frontend has created. + + The automatic update is not always desirable. For example, a +frontend might want to keep a value of some expression for future +reference, and never update it. For another example, fetching memory is +relatively slow for embedded targets, so a frontend might want to +disable automatic update for the variables that are either not visible +on the screen, or "closed". This is possible using so called "frozen +variable objects". Such variable objects are never implicitly updated. + + Variable objects can be either "fixed" or "floating". For the fixed +variable object, the expression is parsed when the variable object is +created, including associating identifiers to specific variables. The +meaning of expression never changes. For a floating variable object the +values of variables whose names appear in the expressions are +re-evaluated every time in the context of the current frame. Consider +this example: + + void do_work(...) + { + struct work_state state; + + if (...) + do_work(...); + } + + If a fixed variable object for the 'state' variable is created in +this function, and we enter the recursive call, the variable object will +report the value of 'state' in the top-level 'do_work' invocation. On +the other hand, a floating variable object will report the value of +'state' in the current frame. + + If an expression specified when creating a fixed variable object +refers to a local variable, the variable object becomes bound to the +thread and frame in which the variable object is created. When such +variable object is updated, GDB makes sure that the thread/frame +combination the variable object is bound to still exists, and +re-evaluates the variable object in context of that thread/frame. + + The following is the complete set of GDB/MI operations defined to +access this functionality: + +*Operation* *Description* + +'-enable-pretty-printing' enable Python-based pretty-printing +'-var-create' create a variable object +'-var-delete' delete the variable object and/or its + children +'-var-set-format' set the display format of this variable +'-var-show-format' show the display format of this variable +'-var-info-num-children' tells how many children this object has +'-var-list-children' return a list of the object's children +'-var-info-type' show the type of this variable object +'-var-info-expression' print parent-relative expression that + this variable object represents +'-var-info-path-expression' print full expression that this variable + object represents +'-var-show-attributes' is this variable editable? does it exist + here? +'-var-evaluate-expression' get the value of this variable +'-var-assign' set the value of this variable +'-var-update' update the variable and its children +'-var-set-frozen' set frozeness attribute +'-var-set-update-range' set range of children to display on + update + + In the next subsection we describe each operation in detail and +suggest how it can be used. + +Description And Use of Operations on Variable Objects +----------------------------------------------------- + +The '-enable-pretty-printing' Command +------------------------------------- + + -enable-pretty-printing + + GDB allows Python-based visualizers to affect the output of the MI +variable object commands. However, because there was no way to +implement this in a fully backward-compatible way, a front end must +request that this functionality be enabled. + + Once enabled, this feature cannot be disabled. + + Note that if Python support has not been compiled into GDB, this +command will still succeed (and do nothing). + + This feature is currently (as of GDB 7.0) experimental, and may work +differently in future versions of GDB. + +The '-var-create' Command +------------------------- + +Synopsis +........ + + -var-create {NAME | "-"} + {FRAME-ADDR | "*" | "@"} EXPRESSION + + This operation creates a variable object, which allows the monitoring +of a variable, the result of an expression, a memory cell or a CPU +register. + + The NAME parameter is the string by which the object can be +referenced. It must be unique. If '-' is specified, the varobj system +will generate a string "varNNNNNN" automatically. It will be unique +provided that one does not specify NAME of that format. The command +fails if a duplicate name is found. + + The frame under which the expression should be evaluated can be +specified by FRAME-ADDR. A '*' indicates that the current frame should +be used. A '@' indicates that a floating variable object must be +created. + + EXPRESSION is any expression valid on the current language set (must +not begin with a '*'), or one of the following: + + * '*ADDR', where ADDR is the address of a memory cell + + * '*ADDR-ADDR' -- a memory address range (TBD) + + * '$REGNAME' -- a CPU register name + + A varobj's contents may be provided by a Python-based pretty-printer. +In this case the varobj is known as a "dynamic varobj". Dynamic varobjs +have slightly different semantics in some cases. If the +'-enable-pretty-printing' command is not sent, then GDB will never +create a dynamic varobj. This ensures backward compatibility for +existing clients. + +Result +...... + +This operation returns attributes of the newly-created varobj. These +are: + +'name' + The name of the varobj. + +'numchild' + The number of children of the varobj. This number is not + necessarily reliable for a dynamic varobj. Instead, you must + examine the 'has_more' attribute. + +'value' + The varobj's scalar value. For a varobj whose type is some sort of + aggregate (e.g., a 'struct'), or for a dynamic varobj, this value + will not be interesting. + +'type' + The varobj's type. This is a string representation of the type, as + would be printed by the GDB CLI. If 'print object' (*note set print + object: Print Settings.) is set to 'on', the _actual_ (derived) + type of the object is shown rather than the _declared_ one. + +'thread-id' + If a variable object is bound to a specific thread, then this is + the thread's identifier. + +'has_more' + For a dynamic varobj, this indicates whether there appear to be any + children available. For a non-dynamic varobj, this will be 0. + +'dynamic' + This attribute will be present and have the value '1' if the varobj + is a dynamic varobj. If the varobj is not a dynamic varobj, then + this attribute will not be present. + +'displayhint' + A dynamic varobj can supply a display hint to the front end. The + value comes directly from the Python pretty-printer object's + 'display_hint' method. *Note Pretty Printing API::. + + Typical output will look like this: + + name="NAME",numchild="N",type="TYPE",thread-id="M", + has_more="HAS_MORE" + +The '-var-delete' Command +------------------------- + +Synopsis +........ + + -var-delete [ -c ] NAME + + Deletes a previously created variable object and all of its children. +With the '-c' option, just deletes the children. + + Returns an error if the object NAME is not found. + +The '-var-set-format' Command +----------------------------- + +Synopsis +........ + + -var-set-format NAME FORMAT-SPEC + + Sets the output format for the value of the object NAME to be +FORMAT-SPEC. + + The syntax for the FORMAT-SPEC is as follows: + + FORMAT-SPEC ==> + {binary | decimal | hexadecimal | octal | natural} + + The natural format is the default format choosen automatically based +on the variable type (like decimal for an 'int', hex for pointers, +etc.). + + For a variable with children, the format is set only on the variable +itself, and the children are not affected. + +The '-var-show-format' Command +------------------------------ + +Synopsis +........ + + -var-show-format NAME + + Returns the format used to display the value of the object NAME. + + FORMAT ==> + FORMAT-SPEC + +The '-var-info-num-children' Command +------------------------------------ + +Synopsis +........ + + -var-info-num-children NAME + + Returns the number of children of a variable object NAME: + + numchild=N + + Note that this number is not completely reliable for a dynamic +varobj. It will return the current number of children, but more +children may be available. + +The '-var-list-children' Command +-------------------------------- + +Synopsis +........ + + -var-list-children [PRINT-VALUES] NAME [FROM TO] + + Return a list of the children of the specified variable object and +create variable objects for them, if they do not already exist. With a +single argument or if PRINT-VALUES has a value of 0 or '--no-values', +print only the names of the variables; if PRINT-VALUES is 1 or +'--all-values', also print their values; and if it is 2 or +'--simple-values' print the name and value for simple data types and +just the name for arrays, structures and unions. + + FROM and TO, if specified, indicate the range of children to report. +If FROM or TO is less than zero, the range is reset and all children +will be reported. Otherwise, children starting at FROM (zero-based) and +up to and excluding TO will be reported. + + If a child range is requested, it will only affect the current call +to '-var-list-children', but not future calls to '-var-update'. For +this, you must instead use '-var-set-update-range'. The intent of this +approach is to enable a front end to implement any update approach it +likes; for example, scrolling a view may cause the front end to request +more children with '-var-list-children', and then the front end could +call '-var-set-update-range' with a different range to ensure that +future updates are restricted to just the visible items. + + For each child the following results are returned: + +NAME + Name of the variable object created for this child. + +EXP + The expression to be shown to the user by the front end to + designate this child. For example this may be the name of a + structure member. + + For a dynamic varobj, this value cannot be used to form an + expression. There is no way to do this at all with a dynamic + varobj. + + For C/C++ structures there are several pseudo children returned to + designate access qualifiers. For these pseudo children EXP is + 'public', 'private', or 'protected'. In this case the type and + value are not present. + + A dynamic varobj will not report the access qualifying + pseudo-children, regardless of the language. This information is + not available at all with a dynamic varobj. + +NUMCHILD + Number of children this child has. For a dynamic varobj, this will + be 0. + +TYPE + The type of the child. If 'print object' (*note set print object: + Print Settings.) is set to 'on', the _actual_ (derived) type of the + object is shown rather than the _declared_ one. + +VALUE + If values were requested, this is the value. + +THREAD-ID + If this variable object is associated with a thread, this is the + thread id. Otherwise this result is not present. + +FROZEN + If the variable object is frozen, this variable will be present + with a value of 1. + +DISPLAYHINT + A dynamic varobj can supply a display hint to the front end. The + value comes directly from the Python pretty-printer object's + 'display_hint' method. *Note Pretty Printing API::. + +DYNAMIC + This attribute will be present and have the value '1' if the varobj + is a dynamic varobj. If the varobj is not a dynamic varobj, then + this attribute will not be present. + + The result may have its own attributes: + +'displayhint' + A dynamic varobj can supply a display hint to the front end. The + value comes directly from the Python pretty-printer object's + 'display_hint' method. *Note Pretty Printing API::. + +'has_more' + This is an integer attribute which is nonzero if there are children + remaining after the end of the selected range. + +Example +....... + + (gdb) + -var-list-children n + ^done,numchild=N,children=[child={name=NAME,exp=EXP, + numchild=N,type=TYPE},(repeats N times)] + (gdb) + -var-list-children --all-values n + ^done,numchild=N,children=[child={name=NAME,exp=EXP, + numchild=N,value=VALUE,type=TYPE},(repeats N times)] + +The '-var-info-type' Command +---------------------------- + +Synopsis +........ + + -var-info-type NAME + + Returns the type of the specified variable NAME. The type is +returned as a string in the same format as it is output by the GDB CLI: + + type=TYPENAME + +The '-var-info-expression' Command +---------------------------------- + +Synopsis +........ + + -var-info-expression NAME + + Returns a string that is suitable for presenting this variable object +in user interface. The string is generally not valid expression in the +current language, and cannot be evaluated. + + For example, if 'a' is an array, and variable object 'A' was created +for 'a', then we'll get this output: + + (gdb) -var-info-expression A.1 + ^done,lang="C",exp="1" + +Here, the value of 'lang' is the language name, which can be found in +*note Supported Languages::. + + Note that the output of the '-var-list-children' command also +includes those expressions, so the '-var-info-expression' command is of +limited use. + +The '-var-info-path-expression' Command +--------------------------------------- + +Synopsis +........ + + -var-info-path-expression NAME + + Returns an expression that can be evaluated in the current context +and will yield the same value that a variable object has. Compare this +with the '-var-info-expression' command, which result can be used only +for UI presentation. Typical use of the '-var-info-path-expression' +command is creating a watchpoint from a variable object. + + This command is currently not valid for children of a dynamic varobj, +and will give an error when invoked on one. + + For example, suppose 'C' is a C++ class, derived from class 'Base', +and that the 'Base' class has a member called 'm_size'. Assume a +variable 'c' is has the type of 'C' and a variable object 'C' was +created for variable 'c'. Then, we'll get this output: + (gdb) -var-info-path-expression C.Base.public.m_size + ^done,path_expr=((Base)c).m_size) + +The '-var-show-attributes' Command +---------------------------------- + +Synopsis +........ + + -var-show-attributes NAME + + List attributes of the specified variable object NAME: + + status=ATTR [ ( ,ATTR )* ] + +where ATTR is '{ { editable | noneditable } | TBD }'. + +The '-var-evaluate-expression' Command +-------------------------------------- + +Synopsis +........ + + -var-evaluate-expression [-f FORMAT-SPEC] NAME + + Evaluates the expression that is represented by the specified +variable object and returns its value as a string. The format of the +string can be specified with the '-f' option. The possible values of +this option are the same as for '-var-set-format' (*note +-var-set-format::). If the '-f' option is not specified, the current +display format will be used. The current display format can be changed +using the '-var-set-format' command. + + value=VALUE + + Note that one must invoke '-var-list-children' for a variable before +the value of a child variable can be evaluated. + +The '-var-assign' Command +------------------------- + +Synopsis +........ + + -var-assign NAME EXPRESSION + + Assigns the value of EXPRESSION to the variable object specified by +NAME. The object must be 'editable'. If the variable's value is +altered by the assign, the variable will show up in any subsequent +'-var-update' list. + +Example +....... + + (gdb) + -var-assign var1 3 + ^done,value="3" + (gdb) + -var-update * + ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] + (gdb) + +The '-var-update' Command +------------------------- + +Synopsis +........ + + -var-update [PRINT-VALUES] {NAME | "*"} + + Reevaluate the expressions corresponding to the variable object NAME +and all its direct and indirect children, and return the list of +variable objects whose values have changed; NAME must be a root variable +object. Here, "changed" means that the result of +'-var-evaluate-expression' before and after the '-var-update' is +different. If '*' is used as the variable object names, all existing +variable objects are updated, except for frozen ones (*note +-var-set-frozen::). The option PRINT-VALUES determines whether both +names and values, or just names are printed. The possible values of +this option are the same as for '-var-list-children' (*note +-var-list-children::). It is recommended to use the '--all-values' +option, to reduce the number of MI commands needed on each program stop. + + With the '*' parameter, if a variable object is bound to a currently +running thread, it will not be updated, without any diagnostic. + + If '-var-set-update-range' was previously used on a varobj, then only +the selected range of children will be reported. + + '-var-update' reports all the changed varobjs in a tuple named +'changelist'. + + Each item in the change list is itself a tuple holding: + +'name' + The name of the varobj. + +'value' + If values were requested for this update, then this field will be + present and will hold the value of the varobj. + +'in_scope' + This field is a string which may take one of three values: + + '"true"' + The variable object's current value is valid. + + '"false"' + The variable object does not currently hold a valid value but + it may hold one in the future if its associated expression + comes back into scope. + + '"invalid"' + The variable object no longer holds a valid value. This can + occur when the executable file being debugged has changed, + either through recompilation or by using the GDB 'file' + command. The front end should normally choose to delete these + variable objects. + + In the future new values may be added to this list so the front + should be prepared for this possibility. *Note GDB/MI Development + and Front Ends: GDB/MI Development and Front Ends. + +'type_changed' + This is only present if the varobj is still valid. If the type + changed, then this will be the string 'true'; otherwise it will be + 'false'. + + When a varobj's type changes, its children are also likely to have + become incorrect. Therefore, the varobj's children are + automatically deleted when this attribute is 'true'. Also, the + varobj's update range, when set using the '-var-set-update-range' + command, is unset. + +'new_type' + If the varobj's type changed, then this field will be present and + will hold the new type. + +'new_num_children' + For a dynamic varobj, if the number of children changed, or if the + type changed, this will be the new number of children. + + The 'numchild' field in other varobj responses is generally not + valid for a dynamic varobj - it will show the number of children + that GDB knows about, but because dynamic varobjs lazily + instantiate their children, this will not reflect the number of + children which may be available. + + The 'new_num_children' attribute only reports changes to the number + of children known by GDB. This is the only way to detect whether + an update has removed children (which necessarily can only happen + at the end of the update range). + +'displayhint' + The display hint, if any. + +'has_more' + This is an integer value, which will be 1 if there are more + children available outside the varobj's update range. + +'dynamic' + This attribute will be present and have the value '1' if the varobj + is a dynamic varobj. If the varobj is not a dynamic varobj, then + this attribute will not be present. + +'new_children' + If new children were added to a dynamic varobj within the selected + update range (as set by '-var-set-update-range'), then they will be + listed in this attribute. + +Example +....... + + (gdb) + -var-assign var1 3 + ^done,value="3" + (gdb) + -var-update --all-values var1 + ^done,changelist=[{name="var1",value="3",in_scope="true", + type_changed="false"}] + (gdb) + +The '-var-set-frozen' Command +----------------------------- + +Synopsis +........ + + -var-set-frozen NAME FLAG + + Set the frozenness flag on the variable object NAME. The FLAG +parameter should be either '1' to make the variable frozen or '0' to +make it unfrozen. If a variable object is frozen, then neither itself, +nor any of its children, are implicitly updated by '-var-update' of a +parent variable or by '-var-update *'. Only '-var-update' of the +variable itself will update its value and values of its children. After +a variable object is unfrozen, it is implicitly updated by all +subsequent '-var-update' operations. Unfreezing a variable does not +update it, only subsequent '-var-update' does. + +Example +....... + + (gdb) + -var-set-frozen V 1 + ^done + (gdb) + +The '-var-set-update-range' command +----------------------------------- + +Synopsis +........ + + -var-set-update-range NAME FROM TO + + Set the range of children to be returned by future invocations of +'-var-update'. + + FROM and TO indicate the range of children to report. If FROM or TO +is less than zero, the range is reset and all children will be reported. +Otherwise, children starting at FROM (zero-based) and up to and +excluding TO will be reported. + +Example +....... + + (gdb) + -var-set-update-range V 1 2 + ^done + +The '-var-set-visualizer' command +--------------------------------- + +Synopsis +........ + + -var-set-visualizer NAME VISUALIZER + + Set a visualizer for the variable object NAME. + + VISUALIZER is the visualizer to use. The special value 'None' means +to disable any visualizer in use. + + If not 'None', VISUALIZER must be a Python expression. This +expression must evaluate to a callable object which accepts a single +argument. GDB will call this object with the value of the varobj NAME +as an argument (this is done so that the same Python pretty-printing +code can be used for both the CLI and MI). When called, this object must +return an object which conforms to the pretty-printing interface (*note +Pretty Printing API::). + + The pre-defined function 'gdb.default_visualizer' may be used to +select a visualizer by following the built-in process (*note Selecting +Pretty-Printers::). This is done automatically when a varobj is +created, and so ordinarily is not needed. + + This feature is only available if Python support is enabled. The MI +command '-list-features' (*note GDB/MI Support Commands::) can be used +to check this. + +Example +....... + +Resetting the visualizer: + + (gdb) + -var-set-visualizer V None + ^done + + Reselecting the default (type-based) visualizer: + + (gdb) + -var-set-visualizer V gdb.default_visualizer + ^done + + Suppose 'SomeClass' is a visualizer class. A lambda expression can +be used to instantiate this class for a varobj: + + (gdb) + -var-set-visualizer V "lambda val: SomeClass()" + ^done + + +File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI + +27.16 GDB/MI Data Manipulation +============================== + +This section describes the GDB/MI commands that manipulate data: examine +memory and registers, evaluate expressions, etc. + +The '-data-disassemble' Command +------------------------------- + +Synopsis +........ + + -data-disassemble + [ -s START-ADDR -e END-ADDR ] + | [ -f FILENAME -l LINENUM [ -n LINES ] ] + -- MODE + +Where: + +'START-ADDR' + is the beginning address (or '$pc') +'END-ADDR' + is the end address +'FILENAME' + is the name of the file to disassemble +'LINENUM' + is the line number to disassemble around +'LINES' + is the number of disassembly lines to be produced. If it is -1, + the whole function will be disassembled, in case no END-ADDR is + specified. If END-ADDR is specified as a non-zero value, and LINES + is lower than the number of disassembly lines between START-ADDR + and END-ADDR, only LINES lines are displayed; if LINES is higher + than the number of lines between START-ADDR and END-ADDR, only the + lines up to END-ADDR are displayed. +'MODE' + is either 0 (meaning only disassembly), 1 (meaning mixed source and + disassembly), 2 (meaning disassembly with raw opcodes), or 3 + (meaning mixed source and disassembly with raw opcodes). + +Result +...... + +The result of the '-data-disassemble' command will be a list named +'asm_insns', the contents of this list depend on the MODE used with the +'-data-disassemble' command. + + For modes 0 and 2 the 'asm_insns' list contains tuples with the +following fields: + +'address' + The address at which this instruction was disassembled. + +'func-name' + The name of the function this instruction is within. + +'offset' + The decimal offset in bytes from the start of 'func-name'. + +'inst' + The text disassembly for this 'address'. + +'opcodes' + This field is only present for mode 2. This contains the raw + opcode bytes for the 'inst' field. + + For modes 1 and 3 the 'asm_insns' list contains tuples named +'src_and_asm_line', each of which has the following fields: + +'line' + The line number within 'file'. + +'file' + The file name from the compilation unit. This might be an absolute + file name or a relative file name depending on the compile command + used. + +'fullname' + Absolute file name of 'file'. It is converted to a canonical form + using the source file search path (*note Specifying Source + Directories: Source Path.) and after resolving all the symbolic + links. + + If the source file is not found this field will contain the path as + present in the debug information. + +'line_asm_insn' + This is a list of tuples containing the disassembly for 'line' in + 'file'. The fields of each tuple are the same as for + '-data-disassemble' in MODE 0 and 2, so 'address', 'func-name', + 'offset', 'inst', and optionally 'opcodes'. + + Note that whatever included in the 'inst' field, is not manipulated +directly by GDB/MI, i.e., it is not possible to adjust its format. + +GDB Command +........... + +The corresponding GDB command is 'disassemble'. + +Example +....... + +Disassemble from the current value of '$pc' to '$pc + 20': + + (gdb) + -data-disassemble -s $pc -e "$pc + 20" -- 0 + ^done, + asm_insns=[ + {address="0x000107c0",func-name="main",offset="4", + inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}, + {address="0x000107c8",func-name="main",offset="12", + inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, + {address="0x000107cc",func-name="main",offset="16", + inst="sethi %hi(0x11800), %o2"}, + {address="0x000107d0",func-name="main",offset="20", + inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] + (gdb) + + Disassemble the whole 'main' function. Line 32 is part of 'main'. + + -data-disassemble -f basics.c -l 32 -- 0 + ^done,asm_insns=[ + {address="0x000107bc",func-name="main",offset="0", + inst="save %sp, -112, %sp"}, + {address="0x000107c0",func-name="main",offset="4", + inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}, + [...] + {address="0x0001081c",func-name="main",offset="96",inst="ret "}, + {address="0x00010820",func-name="main",offset="100",inst="restore "}] + (gdb) + + Disassemble 3 instructions from the start of 'main': + + (gdb) + -data-disassemble -f basics.c -l 32 -n 3 -- 0 + ^done,asm_insns=[ + {address="0x000107bc",func-name="main",offset="0", + inst="save %sp, -112, %sp"}, + {address="0x000107c0",func-name="main",offset="4", + inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}] + (gdb) + + Disassemble 3 instructions from the start of 'main' in mixed mode: + + (gdb) + -data-disassemble -f basics.c -l 32 -n 3 -- 1 + ^done,asm_insns=[ + src_and_asm_line={line="31", + file="../../../src/gdb/testsuite/gdb.mi/basics.c", + fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", + line_asm_insn=[{address="0x000107bc", + func-name="main",offset="0",inst="save %sp, -112, %sp"}]}, + src_and_asm_line={line="32", + file="../../../src/gdb/testsuite/gdb.mi/basics.c", + fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", + line_asm_insn=[{address="0x000107c0", + func-name="main",offset="4",inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}]}] + (gdb) + +The '-data-evaluate-expression' Command +--------------------------------------- + +Synopsis +........ + + -data-evaluate-expression EXPR + + Evaluate EXPR as an expression. The expression could contain an +inferior function call. The function call will execute synchronously. +If the expression contains spaces, it must be enclosed in double quotes. + +GDB Command +........... + +The corresponding GDB commands are 'print', 'output', and 'call'. In +'gdbtk' only, there's a corresponding 'gdb_eval' command. + +Example +....... + +In the following example, the numbers that precede the commands are the +"tokens" described in *note GDB/MI Command Syntax: GDB/MI Command +Syntax. Notice how GDB/MI returns the same tokens in its output. + + 211-data-evaluate-expression A + 211^done,value="1" + (gdb) + 311-data-evaluate-expression &A + 311^done,value="0xefffeb7c" + (gdb) + 411-data-evaluate-expression A+3 + 411^done,value="4" + (gdb) + 511-data-evaluate-expression "A + 3" + 511^done,value="4" + (gdb) + +The '-data-list-changed-registers' Command +------------------------------------------ + +Synopsis +........ + + -data-list-changed-registers + + Display a list of the registers that have changed. + +GDB Command +........... + +GDB doesn't have a direct analog for this command; 'gdbtk' has the +corresponding command 'gdb_changed_register_list'. + +Example +....... + +On a PPC MBX board: + + (gdb) + -exec-continue + ^running + + (gdb) + *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={ + func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", + line="5"} + (gdb) + -data-list-changed-registers + ^done,changed-registers=["0","1","2","4","5","6","7","8","9", + "10","11","13","14","15","16","17","18","19","20","21","22","23", + "24","25","26","27","28","30","31","64","65","66","67","69"] + (gdb) + +The '-data-list-register-names' Command +--------------------------------------- + +Synopsis +........ + + -data-list-register-names [ ( REGNO )+ ] + + Show a list of register names for the current target. If no +arguments are given, it shows a list of the names of all the registers. +If integer numbers are given as arguments, it will print a list of the +names of the registers corresponding to the arguments. To ensure +consistency between a register name and its number, the output list may +include empty register names. + +GDB Command +........... + +GDB does not have a command which corresponds to +'-data-list-register-names'. In 'gdbtk' there is a corresponding +command 'gdb_regnames'. + +Example +....... + +For the PPC MBX board: + (gdb) + -data-list-register-names + ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", + "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", + "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", + "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", + "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", + "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", + "", "pc","ps","cr","lr","ctr","xer"] + (gdb) + -data-list-register-names 1 2 3 + ^done,register-names=["r1","r2","r3"] + (gdb) + +The '-data-list-register-values' Command +---------------------------------------- + +Synopsis +........ + + -data-list-register-values + [ --skip-unavailable ] FMT [ ( REGNO )*] + + Display the registers' contents. FMT is the format according to +which the registers' contents are to be returned, followed by an +optional list of numbers specifying the registers to display. A missing +list of numbers indicates that the contents of all the registers must be +returned. The '--skip-unavailable' option indicates that only the +available registers are to be returned. + + Allowed formats for FMT are: + +'x' + Hexadecimal +'o' + Octal +'t' + Binary +'d' + Decimal +'r' + Raw +'N' + Natural + +GDB Command +........... + +The corresponding GDB commands are 'info reg', 'info all-reg', and (in +'gdbtk') 'gdb_fetch_registers'. + +Example +....... + +For a PPC MBX board (note: line breaks are for readability only, they +don't appear in the actual output): + + (gdb) + -data-list-register-values r 64 65 + ^done,register-values=[{number="64",value="0xfe00a300"}, + {number="65",value="0x00029002"}] + (gdb) + -data-list-register-values x + ^done,register-values=[{number="0",value="0xfe0043c8"}, + {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, + {number="3",value="0x0"},{number="4",value="0xa"}, + {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, + {number="7",value="0xfe011e98"},{number="8",value="0x2"}, + {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, + {number="11",value="0x1"},{number="12",value="0x0"}, + {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, + {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, + {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, + {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, + {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, + {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, + {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, + {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, + {number="29",value="0x0"},{number="30",value="0xfe010000"}, + {number="31",value="0x0"},{number="32",value="0x0"}, + {number="33",value="0x0"},{number="34",value="0x0"}, + {number="35",value="0x0"},{number="36",value="0x0"}, + {number="37",value="0x0"},{number="38",value="0x0"}, + {number="39",value="0x0"},{number="40",value="0x0"}, + {number="41",value="0x0"},{number="42",value="0x0"}, + {number="43",value="0x0"},{number="44",value="0x0"}, + {number="45",value="0x0"},{number="46",value="0x0"}, + {number="47",value="0x0"},{number="48",value="0x0"}, + {number="49",value="0x0"},{number="50",value="0x0"}, + {number="51",value="0x0"},{number="52",value="0x0"}, + {number="53",value="0x0"},{number="54",value="0x0"}, + {number="55",value="0x0"},{number="56",value="0x0"}, + {number="57",value="0x0"},{number="58",value="0x0"}, + {number="59",value="0x0"},{number="60",value="0x0"}, + {number="61",value="0x0"},{number="62",value="0x0"}, + {number="63",value="0x0"},{number="64",value="0xfe00a300"}, + {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, + {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, + {number="69",value="0x20002b03"}] + (gdb) + +The '-data-read-memory' Command +------------------------------- + +This command is deprecated, use '-data-read-memory-bytes' instead. + +Synopsis +........ + + -data-read-memory [ -o BYTE-OFFSET ] + ADDRESS WORD-FORMAT WORD-SIZE + NR-ROWS NR-COLS [ ASCHAR ] + +where: + +'ADDRESS' + An expression specifying the address of the first memory word to be + read. Complex expressions containing embedded white space should + be quoted using the C convention. + +'WORD-FORMAT' + The format to be used to print the memory words. The notation is + the same as for GDB's 'print' command (*note Output Formats: Output + Formats.). + +'WORD-SIZE' + The size of each memory word in bytes. + +'NR-ROWS' + The number of rows in the output table. + +'NR-COLS' + The number of columns in the output table. + +'ASCHAR' + If present, indicates that each row should include an ASCII dump. + The value of ASCHAR is used as a padding character when a byte is + not a member of the printable ASCII character set (printable ASCII + characters are those whose code is between 32 and 126, + inclusively). + +'BYTE-OFFSET' + An offset to add to the ADDRESS before fetching memory. + + This command displays memory contents as a table of NR-ROWS by +NR-COLS words, each word being WORD-SIZE bytes. In total, 'NR-ROWS * +NR-COLS * WORD-SIZE' bytes are read (returned as 'total-bytes'). Should +less than the requested number of bytes be returned by the target, the +missing words are identified using 'N/A'. The number of bytes read from +the target is returned in 'nr-bytes' and the starting address used to +read memory in 'addr'. + + The address of the next/previous row or page is available in +'next-row' and 'prev-row', 'next-page' and 'prev-page'. + +GDB Command +........... + +The corresponding GDB command is 'x'. 'gdbtk' has 'gdb_get_mem' memory +read command. + +Example +....... + +Read six bytes of memory starting at 'bytes+6' but then offset by '-6' +bytes. Format as three rows of two columns. One byte per word. +Display each word in hex. + + (gdb) + 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 + 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", + next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", + prev-page="0x0000138a",memory=[ + {addr="0x00001390",data=["0x00","0x01"]}, + {addr="0x00001392",data=["0x02","0x03"]}, + {addr="0x00001394",data=["0x04","0x05"]}] + (gdb) + + Read two bytes of memory starting at address 'shorts + 64' and +display as a single word formatted in decimal. + + (gdb) + 5-data-read-memory shorts+64 d 2 1 1 + 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", + next-row="0x00001512",prev-row="0x0000150e", + next-page="0x00001512",prev-page="0x0000150e",memory=[ + {addr="0x00001510",data=["128"]}] + (gdb) + + Read thirty two bytes of memory starting at 'bytes+16' and format as +eight rows of four columns. Include a string encoding with 'x' used as +the non-printable character. + + (gdb) + 4-data-read-memory bytes+16 x 1 8 4 x + 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", + next-row="0x000013c0",prev-row="0x0000139c", + next-page="0x000013c0",prev-page="0x00001380",memory=[ + {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, + {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, + {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, + {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, + {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, + {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, + {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, + {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] + (gdb) + +The '-data-read-memory-bytes' Command +------------------------------------- + +Synopsis +........ + + -data-read-memory-bytes [ -o BYTE-OFFSET ] + ADDRESS COUNT + +where: + +'ADDRESS' + An expression specifying the address of the first memory word to be + read. Complex expressions containing embedded white space should + be quoted using the C convention. + +'COUNT' + The number of bytes to read. This should be an integer literal. + +'BYTE-OFFSET' + The offsets in bytes relative to ADDRESS at which to start reading. + This should be an integer literal. This option is provided so that + a frontend is not required to first evaluate address and then + perform address arithmetics itself. + + This command attempts to read all accessible memory regions in the +specified range. First, all regions marked as unreadable in the memory +map (if one is defined) will be skipped. *Note Memory Region +Attributes::. Second, GDB will attempt to read the remaining regions. +For each one, if reading full region results in an errors, GDB will try +to read a subset of the region. + + In general, every single byte in the region may be readable or not, +and the only way to read every readable byte is to try a read at every +address, which is not practical. Therefore, GDB will attempt to read +all accessible bytes at either beginning or the end of the region, using +a binary division scheme. This heuristic works well for reading accross +a memory map boundary. Note that if a region has a readable range that +is neither at the beginning or the end, GDB will not read it. + + The result record (*note GDB/MI Result Records::) that is output of +the command includes a field named 'memory' whose content is a list of +tuples. Each tuple represent a successfully read memory block and has +the following fields: + +'begin' + The start address of the memory block, as hexadecimal literal. + +'end' + The end address of the memory block, as hexadecimal literal. + +'offset' + The offset of the memory block, as hexadecimal literal, relative to + the start address passed to '-data-read-memory-bytes'. + +'contents' + The contents of the memory block, in hex. + +GDB Command +........... + +The corresponding GDB command is 'x'. + +Example +....... + + (gdb) + -data-read-memory-bytes &a 10 + ^done,memory=[{begin="0xbffff154",offset="0x00000000", + end="0xbffff15e", + contents="01000000020000000300"}] + (gdb) + +The '-data-write-memory-bytes' Command +-------------------------------------- + +Synopsis +........ + + -data-write-memory-bytes ADDRESS CONTENTS + -data-write-memory-bytes ADDRESS CONTENTS [COUNT] + +where: + +'ADDRESS' + An expression specifying the address of the first memory word to be + read. Complex expressions containing embedded white space should + be quoted using the C convention. + +'CONTENTS' + The hex-encoded bytes to write. + +'COUNT' + Optional argument indicating the number of bytes to be written. If + COUNT is greater than CONTENTS' length, GDB will repeatedly write + CONTENTS until it fills COUNT bytes. + +GDB Command +........... + +There's no corresponding GDB command. + +Example +....... + + (gdb) + -data-write-memory-bytes &a "aabbccdd" + ^done + (gdb) + + (gdb) + -data-write-memory-bytes &a "aabbccdd" 16e + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI + +27.17 GDB/MI Tracepoint Commands +================================ + +The commands defined in this section implement MI support for +tracepoints. For detailed introduction, see *note Tracepoints::. + +The '-trace-find' Command +------------------------- + +Synopsis +........ + + -trace-find MODE [PARAMETERS...] + + Find a trace frame using criteria defined by MODE and PARAMETERS. +The following table lists permissible modes and their parameters. For +details of operation, see *note tfind::. + +'none' + No parameters are required. Stops examining trace frames. + +'frame-number' + An integer is required as parameter. Selects tracepoint frame with + that index. + +'tracepoint-number' + An integer is required as parameter. Finds next trace frame that + corresponds to tracepoint with the specified number. + +'pc' + An address is required as parameter. Finds next trace frame that + corresponds to any tracepoint at the specified address. + +'pc-inside-range' + Two addresses are required as parameters. Finds next trace frame + that corresponds to a tracepoint at an address inside the specified + range. Both bounds are considered to be inside the range. + +'pc-outside-range' + Two addresses are required as parameters. Finds next trace frame + that corresponds to a tracepoint at an address outside the + specified range. Both bounds are considered to be inside the + range. + +'line' + Line specification is required as parameter. *Note Specify + Location::. Finds next trace frame that corresponds to a + tracepoint at the specified location. + + If 'none' was passed as MODE, the response does not have fields. +Otherwise, the response may have the following fields: + +'found' + This field has either '0' or '1' as the value, depending on whether + a matching tracepoint was found. + +'traceframe' + The index of the found traceframe. This field is present iff the + 'found' field has value of '1'. + +'tracepoint' + The index of the found tracepoint. This field is present iff the + 'found' field has value of '1'. + +'frame' + The information about the frame corresponding to the found trace + frame. This field is present only if a trace frame was found. + *Note GDB/MI Frame Information::, for description of this field. + +GDB Command +........... + +The corresponding GDB command is 'tfind'. + +-trace-define-variable +---------------------- + +Synopsis +........ + + -trace-define-variable NAME [ VALUE ] + + Create trace variable NAME if it does not exist. If VALUE is +specified, sets the initial value of the specified trace variable to +that value. Note that the NAME should start with the '$' character. + +GDB Command +........... + +The corresponding GDB command is 'tvariable'. + +The '-trace-frame-collected' Command +------------------------------------ + +Synopsis +........ + + -trace-frame-collected + [--var-print-values VAR_PVAL] + [--comp-print-values COMP_PVAL] + [--registers-format REGFORMAT] + [--memory-contents] + + This command returns the set of collected objects, register names, +trace state variable names, memory ranges and computed expressions that +have been collected at a particular trace frame. The optional +parameters to the command affect the output format in different ways. +See the output description table below for more details. + + The reported names can be used in the normal manner to create varobjs +and inspect the objects themselves. The items returned by this command +are categorized so that it is clear which is a variable, which is a +register, which is a trace state variable, which is a memory range and +which is a computed expression. + + For instance, if the actions were + collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2 + collect *(int*)0xaf02bef0@40 + +the object collected in its entirety would be 'myVar'. The object +'myArray' would be partially collected, because only the element at +index 'myIndex' would be collected. The remaining objects would be +computed expressions. + + An example output would be: + + (gdb) + -trace-frame-collected + ^done, + explicit-variables=[{name="myVar",value="1"}], + computed-expressions=[{name="myArray[myIndex]",value="0"}, + {name="myObj.field",value="0"}, + {name="myPtr->field",value="1"}, + {name="myCount + 2",value="3"}, + {name="$tvar1 + 1",value="43970027"}], + registers=[{number="0",value="0x7fe2c6e79ec8"}, + {number="1",value="0x0"}, + {number="2",value="0x4"}, + ... + {number="125",value="0x0"}], + tvars=[{name="$tvar1",current="43970026"}], + memory=[{address="0x0000000000602264",length="4"}, + {address="0x0000000000615bc0",length="4"}] + (gdb) + + Where: + +'explicit-variables' + The set of objects that have been collected in their entirety (as + opposed to collecting just a few elements of an array or a few + struct members). For each object, its name and value are printed. + The '--var-print-values' option affects how or whether the value + field is output. If VAR_PVAL is 0, then print only the names; if + it is 1, print also their values; and if it is 2, print the name, + type and value for simple data types, and the name and type for + arrays, structures and unions. + +'computed-expressions' + The set of computed expressions that have been collected at the + current trace frame. The '--comp-print-values' option affects this + set like the '--var-print-values' option affects the + 'explicit-variables' set. See above. + +'registers' + The registers that have been collected at the current trace frame. + For each register collected, the name and current value are + returned. The value is formatted according to the + '--registers-format' option. See the '-data-list-register-values' + command for a list of the allowed formats. The default is 'x'. + +'tvars' + The trace state variables that have been collected at the current + trace frame. For each trace state variable collected, the name and + current value are returned. + +'memory' + The set of memory ranges that have been collected at the current + trace frame. Its content is a list of tuples. Each tuple + represents a collected memory range and has the following fields: + + 'address' + The start address of the memory range, as hexadecimal literal. + + 'length' + The length of the memory range, as decimal literal. + + 'contents' + The contents of the memory block, in hex. This field is only + present if the '--memory-contents' option is specified. + +GDB Command +........... + +There is no corresponding GDB command. + +Example +....... + +-trace-list-variables +--------------------- + +Synopsis +........ + + -trace-list-variables + + Return a table of all defined trace variables. Each element of the +table has the following fields: + +'name' + The name of the trace variable. This field is always present. + +'initial' + The initial value. This is a 64-bit signed integer. This field is + always present. + +'current' + The value the trace variable has at the moment. This is a 64-bit + signed integer. This field is absent iff current value is not + defined, for example if the trace was never run, or is presently + running. + +GDB Command +........... + +The corresponding GDB command is 'tvariables'. + +Example +....... + + (gdb) + -trace-list-variables + ^done,trace-variables={nr_rows="1",nr_cols="3", + hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"}, + {width="11",alignment="-1",col_name="initial",colhdr="Initial"}, + {width="11",alignment="-1",col_name="current",colhdr="Current"}], + body=[variable={name="$trace_timestamp",initial="0"} + variable={name="$foo",initial="10",current="15"}]} + (gdb) + +-trace-save +----------- + +Synopsis +........ + + -trace-save [-r ] FILENAME + + Saves the collected trace data to FILENAME. Without the '-r' option, +the data is downloaded from the target and saved in a local file. With +the '-r' option the target is asked to perform the save. + +GDB Command +........... + +The corresponding GDB command is 'tsave'. + +-trace-start +------------ + +Synopsis +........ + + -trace-start + + Starts a tracing experiments. The result of this command does not +have any fields. + +GDB Command +........... + +The corresponding GDB command is 'tstart'. + +-trace-status +------------- + +Synopsis +........ + + -trace-status + + Obtains the status of a tracing experiment. The result may include +the following fields: + +'supported' + May have a value of either '0', when no tracing operations are + supported, '1', when all tracing operations are supported, or + 'file' when examining trace file. In the latter case, examining of + trace frame is possible but new tracing experiement cannot be + started. This field is always present. + +'running' + May have a value of either '0' or '1' depending on whether tracing + experiement is in progress on target. This field is present if + 'supported' field is not '0'. + +'stop-reason' + Report the reason why the tracing was stopped last time. This + field may be absent iff tracing was never stopped on target yet. + The value of 'request' means the tracing was stopped as result of + the '-trace-stop' command. The value of 'overflow' means the + tracing buffer is full. The value of 'disconnection' means tracing + was automatically stopped when GDB has disconnected. The value of + 'passcount' means tracing was stopped when a tracepoint was passed + a maximal number of times for that tracepoint. This field is + present if 'supported' field is not '0'. + +'stopping-tracepoint' + The number of tracepoint whose passcount as exceeded. This field + is present iff the 'stop-reason' field has the value of + 'passcount'. + +'frames' +'frames-created' + The 'frames' field is a count of the total number of trace frames + in the trace buffer, while 'frames-created' is the total created + during the run, including ones that were discarded, such as when a + circular trace buffer filled up. Both fields are optional. + +'buffer-size' +'buffer-free' + These fields tell the current size of the tracing buffer and the + remaining space. These fields are optional. + +'circular' + The value of the circular trace buffer flag. '1' means that the + trace buffer is circular and old trace frames will be discarded if + necessary to make room, '0' means that the trace buffer is linear + and may fill up. + +'disconnected' + The value of the disconnected tracing flag. '1' means that tracing + will continue after GDB disconnects, '0' means that the trace run + will stop. + +'trace-file' + The filename of the trace file being examined. This field is + optional, and only present when examining a trace file. + +GDB Command +........... + +The corresponding GDB command is 'tstatus'. + +-trace-stop +----------- + +Synopsis +........ + + -trace-stop + + Stops a tracing experiment. The result of this command has the same +fields as '-trace-status', except that the 'supported' and 'running' +fields are not output. + +GDB Command +........... + +The corresponding GDB command is 'tstop'. + + +File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI + +27.18 GDB/MI Symbol Query Commands +================================== + +The '-symbol-list-lines' Command +-------------------------------- + +Synopsis +........ + + -symbol-list-lines FILENAME + + Print the list of lines that contain code and their associated +program addresses for the given source filename. The entries are sorted +in ascending PC order. + +GDB Command +........... + +There is no corresponding GDB command. + +Example +....... + + (gdb) + -symbol-list-lines basics.c + ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] + (gdb) + + +File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI + +27.19 GDB/MI File Commands +========================== + +This section describes the GDB/MI commands to specify executable file +names and to read in and obtain symbol table information. + +The '-file-exec-and-symbols' Command +------------------------------------ + +Synopsis +........ + + -file-exec-and-symbols FILE + + Specify the executable file to be debugged. This file is the one +from which the symbol table is also read. If no file is specified, the +command clears the executable and symbol information. If breakpoints +are set when using this command with no arguments, GDB will produce +error messages. Otherwise, no output is produced, except a completion +notification. + +GDB Command +........... + +The corresponding GDB command is 'file'. + +Example +....... + + (gdb) + -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx + ^done + (gdb) + +The '-file-exec-file' Command +----------------------------- + +Synopsis +........ + + -file-exec-file FILE + + Specify the executable file to be debugged. Unlike +'-file-exec-and-symbols', the symbol table is _not_ read from this file. +If used without argument, GDB clears the information about the +executable file. No output is produced, except a completion +notification. + +GDB Command +........... + +The corresponding GDB command is 'exec-file'. + +Example +....... + + (gdb) + -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx + ^done + (gdb) + +The '-file-list-exec-source-file' Command +----------------------------------------- + +Synopsis +........ + + -file-list-exec-source-file + + List the line number, the current source file, and the absolute path +to the current source file for the current executable. The macro +information field has a value of '1' or '0' depending on whether or not +the file includes preprocessor macro information. + +GDB Command +........... + +The GDB equivalent is 'info source' + +Example +....... + + (gdb) + 123-file-list-exec-source-file + 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" + (gdb) + +The '-file-list-exec-source-files' Command +------------------------------------------ + +Synopsis +........ + + -file-list-exec-source-files + + List the source files for the current executable. + + It will always output both the filename and fullname (absolute file +name) of a source file. + +GDB Command +........... + +The GDB equivalent is 'info sources'. 'gdbtk' has an analogous command +'gdb_listfiles'. + +Example +....... + + (gdb) + -file-list-exec-source-files + ^done,files=[ + {file=foo.c,fullname=/home/foo.c}, + {file=/home/bar.c,fullname=/home/bar.c}, + {file=gdb_could_not_find_fullpath.c}] + (gdb) + +The '-file-symbol-file' Command +------------------------------- + +Synopsis +........ + + -file-symbol-file FILE + + Read symbol table info from the specified FILE argument. When used +without arguments, clears GDB's symbol table info. No output is +produced, except for a completion notification. + +GDB Command +........... + +The corresponding GDB command is 'symbol-file'. + +Example +....... + + (gdb) + -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI + +27.20 GDB/MI Target Manipulation Commands +========================================= + +The '-target-attach' Command +---------------------------- + +Synopsis +........ + + -target-attach PID | GID | FILE + + Attach to a process PID or a file FILE outside of GDB, or a thread +group GID. If attaching to a thread group, the id previously returned +by '-list-thread-groups --available' must be used. + +GDB Command +........... + +The corresponding GDB command is 'attach'. + +Example +....... + + (gdb) + -target-attach 34 + =thread-created,id="1" + *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]} + ^done + (gdb) + +The '-target-detach' Command +---------------------------- + +Synopsis +........ + + -target-detach [ PID | GID ] + + Detach from the remote target which normally resumes its execution. +If either PID or GID is specified, detaches from either the specified +process, or specified thread group. There's no output. + +GDB Command +........... + +The corresponding GDB command is 'detach'. + +Example +....... + + (gdb) + -target-detach + ^done + (gdb) + +The '-target-disconnect' Command +-------------------------------- + +Synopsis +........ + + -target-disconnect + + Disconnect from the remote target. There's no output and the target +is generally not resumed. + +GDB Command +........... + +The corresponding GDB command is 'disconnect'. + +Example +....... + + (gdb) + -target-disconnect + ^done + (gdb) + +The '-target-download' Command +------------------------------ + +Synopsis +........ + + -target-download + + Loads the executable onto the remote target. It prints out an update +message every half second, which includes the fields: + +'section' + The name of the section. +'section-sent' + The size of what has been sent so far for that section. +'section-size' + The size of the section. +'total-sent' + The total size of what was sent so far (the current and the + previous sections). +'total-size' + The size of the overall executable to download. + +Each message is sent as status record (*note GDB/MI Output Syntax: +GDB/MI Output Syntax.). + + In addition, it prints the name and size of the sections, as they are +downloaded. These messages include the following fields: + +'section' + The name of the section. +'section-size' + The size of the section. +'total-size' + The size of the overall executable to download. + +At the end, a summary is printed. + +GDB Command +........... + +The corresponding GDB command is 'load'. + +Example +....... + +Note: each status message appears on a single line. Here the messages +have been broken down so that they can fit onto a page. + + (gdb) + -target-download + +download,{section=".text",section-size="6668",total-size="9880"} + +download,{section=".text",section-sent="512",section-size="6668", + total-sent="512",total-size="9880"} + +download,{section=".text",section-sent="1024",section-size="6668", + total-sent="1024",total-size="9880"} + +download,{section=".text",section-sent="1536",section-size="6668", + total-sent="1536",total-size="9880"} + +download,{section=".text",section-sent="2048",section-size="6668", + total-sent="2048",total-size="9880"} + +download,{section=".text",section-sent="2560",section-size="6668", + total-sent="2560",total-size="9880"} + +download,{section=".text",section-sent="3072",section-size="6668", + total-sent="3072",total-size="9880"} + +download,{section=".text",section-sent="3584",section-size="6668", + total-sent="3584",total-size="9880"} + +download,{section=".text",section-sent="4096",section-size="6668", + total-sent="4096",total-size="9880"} + +download,{section=".text",section-sent="4608",section-size="6668", + total-sent="4608",total-size="9880"} + +download,{section=".text",section-sent="5120",section-size="6668", + total-sent="5120",total-size="9880"} + +download,{section=".text",section-sent="5632",section-size="6668", + total-sent="5632",total-size="9880"} + +download,{section=".text",section-sent="6144",section-size="6668", + total-sent="6144",total-size="9880"} + +download,{section=".text",section-sent="6656",section-size="6668", + total-sent="6656",total-size="9880"} + +download,{section=".init",section-size="28",total-size="9880"} + +download,{section=".fini",section-size="28",total-size="9880"} + +download,{section=".data",section-size="3156",total-size="9880"} + +download,{section=".data",section-sent="512",section-size="3156", + total-sent="7236",total-size="9880"} + +download,{section=".data",section-sent="1024",section-size="3156", + total-sent="7748",total-size="9880"} + +download,{section=".data",section-sent="1536",section-size="3156", + total-sent="8260",total-size="9880"} + +download,{section=".data",section-sent="2048",section-size="3156", + total-sent="8772",total-size="9880"} + +download,{section=".data",section-sent="2560",section-size="3156", + total-sent="9284",total-size="9880"} + +download,{section=".data",section-sent="3072",section-size="3156", + total-sent="9796",total-size="9880"} + ^done,address="0x10004",load-size="9880",transfer-rate="6586", + write-rate="429" + (gdb) + +GDB Command +........... + +No equivalent. + +Example +....... + +N.A. + +The '-target-select' Command +---------------------------- + +Synopsis +........ + + -target-select TYPE PARAMETERS ... + + Connect GDB to the remote target. This command takes two args: + +'TYPE' + The type of target, for instance 'remote', etc. +'PARAMETERS' + Device names, host names and the like. *Note Commands for Managing + Targets: Target Commands, for more details. + + The output is a connection notification, followed by the address at +which the target program is, in the following form: + + ^connected,addr="ADDRESS",func="FUNCTION NAME", + args=[ARG LIST] + +GDB Command +........... + +The corresponding GDB command is 'target'. + +Example +....... + + (gdb) + -target-select remote /dev/ttya + ^connected,addr="0xfe00a300",func="??",args=[] + (gdb) + + +File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Ada Exceptions Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI + +27.21 GDB/MI File Transfer Commands +=================================== + +The '-target-file-put' Command +------------------------------ + +Synopsis +........ + + -target-file-put HOSTFILE TARGETFILE + + Copy file HOSTFILE from the host system (the machine running GDB) to +TARGETFILE on the target system. + +GDB Command +........... + +The corresponding GDB command is 'remote put'. + +Example +....... + + (gdb) + -target-file-put localfile remotefile + ^done + (gdb) + +The '-target-file-get' Command +------------------------------ + +Synopsis +........ + + -target-file-get TARGETFILE HOSTFILE + + Copy file TARGETFILE from the target system to HOSTFILE on the host +system. + +GDB Command +........... + +The corresponding GDB command is 'remote get'. + +Example +....... + + (gdb) + -target-file-get remotefile localfile + ^done + (gdb) + +The '-target-file-delete' Command +--------------------------------- + +Synopsis +........ + + -target-file-delete TARGETFILE + + Delete TARGETFILE from the target system. + +GDB Command +........... + +The corresponding GDB command is 'remote delete'. + +Example +....... + + (gdb) + -target-file-delete remotefile + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Ada Exceptions Commands, Next: GDB/MI Support Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI + +27.22 Ada Exceptions GDB/MI Commands +==================================== + +The '-info-ada-exceptions' Command +---------------------------------- + +Synopsis +........ + + -info-ada-exceptions [ REGEXP] + + List all Ada exceptions defined within the program being debugged. +With a regular expression REGEXP, only those exceptions whose names +match REGEXP are listed. + +GDB Command +........... + +The corresponding GDB command is 'info exceptions'. + +Result +...... + +The result is a table of Ada exceptions. The following columns are +defined for each exception: + +'name' + The name of the exception. + +'address' + The address of the exception. + +Example +....... + + -info-ada-exceptions aint + ^done,ada-exceptions={nr_rows="2",nr_cols="2", + hdr=[{width="1",alignment="-1",col_name="name",colhdr="Name"}, + {width="1",alignment="-1",col_name="address",colhdr="Address"}], + body=[{name="constraint_error",address="0x0000000000613da0"}, + {name="const.aint_global_e",address="0x0000000000613b00"}]} + +Catching Ada Exceptions +----------------------- + +The commands describing how to ask GDB to stop when a program raises an +exception are described at *note Ada Exception GDB/MI Catchpoint +Commands::. + + +File: gdb.info, Node: GDB/MI Support Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Ada Exceptions Commands, Up: GDB/MI + +27.23 GDB/MI Support Commands +============================= + +Since new commands and features get regularly added to GDB/MI, some +commands are available to help front-ends query the debugger about +support for these capabilities. Similarly, it is also possible to query +GDB about target support of certain features. + +The '-info-gdb-mi-command' Command +---------------------------------- + +Synopsis +........ + + -info-gdb-mi-command CMD_NAME + + Query support for the GDB/MI command named CMD_NAME. + + Note that the dash ('-') starting all GDB/MI commands is technically +not part of the command name (*note GDB/MI Input Syntax::), and thus +should be omitted in CMD_NAME. However, for ease of use, this command +also accepts the form with the leading dash. + +GDB Command +........... + +There is no corresponding GDB command. + +Result +...... + +The result is a tuple. There is currently only one field: + +'exists' + This field is equal to '"true"' if the GDB/MI command exists, + '"false"' otherwise. + +Example +....... + +Here is an example where the GDB/MI command does not exist: + + -info-gdb-mi-command unsupported-command + ^done,command={exists="false"} + +And here is an example where the GDB/MI command is known to the +debugger: + + -info-gdb-mi-command symbol-list-lines + ^done,command={exists="true"} + +The '-list-features' Command +---------------------------- + +Returns a list of particular features of the MI protocol that this +version of gdb implements. A feature can be a command, or a new field +in an output of some command, or even an important bugfix. While a +frontend can sometimes detect presence of a feature at runtime, it is +easier to perform detection at debugger startup. + + The command returns a list of strings, with each string naming an +available feature. Each returned string is just a name, it does not +have any internal structure. The list of possible feature names is +given below. + + Example output: + + (gdb) -list-features + ^done,result=["feature1","feature2"] + + The current list of features is: + +'frozen-varobjs' + Indicates support for the '-var-set-frozen' command, as well as + possible presense of the 'frozen' field in the output of + '-varobj-create'. +'pending-breakpoints' + Indicates support for the '-f' option to the '-break-insert' + command. +'python' + Indicates Python scripting support, Python-based pretty-printing + commands, and possible presence of the 'display_hint' field in the + output of '-var-list-children' +'thread-info' + Indicates support for the '-thread-info' command. +'data-read-memory-bytes' + Indicates support for the '-data-read-memory-bytes' and the + '-data-write-memory-bytes' commands. +'breakpoint-notifications' + Indicates that changes to breakpoints and breakpoints created via + the CLI will be announced via async records. +'ada-task-info' + Indicates support for the '-ada-task-info' command. +'language-option' + Indicates that all GDB/MI commands accept the '--language' option + (*note Context management::). +'info-gdb-mi-command' + Indicates support for the '-info-gdb-mi-command' command. +'undefined-command-error-code' + Indicates support for the "undefined-command" error code in error + result records, produced when trying to execute an undefined GDB/MI + command (*note GDB/MI Result Records::). +'exec-run-start-option' + Indicates that the '-exec-run' command supports the '--start' + option (*note GDB/MI Program Execution::). + +The '-list-target-features' Command +----------------------------------- + +Returns a list of particular features that are supported by the target. +Those features affect the permitted MI commands, but unlike the features +reported by the '-list-features' command, the features depend on which +target GDB is using at the moment. Whenever a target can change, due to +commands such as '-target-select', '-target-attach' or '-exec-run', the +list of target features may change, and the frontend should obtain it +again. Example output: + + (gdb) -list-target-features + ^done,result=["async"] + + The current list of features is: + +'async' + Indicates that the target is capable of asynchronous command + execution, which means that GDB will accept further commands while + the target is running. + +'reverse' + Indicates that the target is capable of reverse execution. *Note + Reverse Execution::, for more information. + + +File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI Support Commands, Up: GDB/MI + +27.24 Miscellaneous GDB/MI Commands +=================================== + +The '-gdb-exit' Command +----------------------- + +Synopsis +........ + + -gdb-exit + + Exit GDB immediately. + +GDB Command +........... + +Approximately corresponds to 'quit'. + +Example +....... + + (gdb) + -gdb-exit + ^exit + +The '-gdb-set' Command +---------------------- + +Synopsis +........ + + -gdb-set + + Set an internal GDB variable. + +GDB Command +........... + +The corresponding GDB command is 'set'. + +Example +....... + + (gdb) + -gdb-set $foo=3 + ^done + (gdb) + +The '-gdb-show' Command +----------------------- + +Synopsis +........ + + -gdb-show + + Show the current value of a GDB variable. + +GDB Command +........... + +The corresponding GDB command is 'show'. + +Example +....... + + (gdb) + -gdb-show annotate + ^done,value="0" + (gdb) + +The '-gdb-version' Command +-------------------------- + +Synopsis +........ + + -gdb-version + + Show version information for GDB. Used mostly in testing. + +GDB Command +........... + +The GDB equivalent is 'show version'. GDB by default shows this +information when you start an interactive session. + +Example +....... + + (gdb) + -gdb-version + ~GNU gdb 5.2.1 + ~Copyright 2000 Free Software Foundation, Inc. + ~GDB is free software, covered by the GNU General Public License, and + ~you are welcome to change it and/or distribute copies of it under + ~ certain conditions. + ~Type "show copying" to see the conditions. + ~There is absolutely no warranty for GDB. Type "show warranty" for + ~ details. + ~This GDB was configured as + "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". + ^done + (gdb) + +The '-list-thread-groups' Command +--------------------------------- + +Synopsis +-------- + + -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ] + + Lists thread groups (*note Thread groups::). When a single thread +group is passed as the argument, lists the children of that group. When +several thread group are passed, lists information about those thread +groups. Without any parameters, lists information about all top-level +thread groups. + + Normally, thread groups that are being debugged are reported. With +the '--available' option, GDB reports thread groups available on the +target. + + The output of this command may have either a 'threads' result or a +'groups' result. The 'thread' result has a list of tuples as value, +with each tuple describing a thread (*note GDB/MI Thread Information::). +The 'groups' result has a list of tuples as value, each tuple describing +a thread group. If top-level groups are requested (that is, no +parameter is passed), or when several groups are passed, the output +always has a 'groups' result. The format of the 'group' result is +described below. + + To reduce the number of roundtrips it's possible to list thread +groups together with their children, by passing the '--recurse' option +and the recursion depth. Presently, only recursion depth of 1 is +permitted. If this option is present, then every reported thread group +will also include its children, either as 'group' or 'threads' field. + + In general, any combination of option and parameters is permitted, +with the following caveats: + + * When a single thread group is passed, the output will typically be + the 'threads' result. Because threads may not contain anything, + the 'recurse' option will be ignored. + + * When the '--available' option is passed, limited information may be + available. In particular, the list of threads of a process might + be inaccessible. Further, specifying specific thread groups might + not give any performance advantage over listing all thread groups. + The frontend should assume that '-list-thread-groups --available' + is always an expensive operation and cache the results. + + The 'groups' result is a list of tuples, where each tuple may have +the following fields: + +'id' + Identifier of the thread group. This field is always present. The + identifier is an opaque string; frontends should not try to convert + it to an integer, even though it might look like one. + +'type' + The type of the thread group. At present, only 'process' is a + valid type. + +'pid' + The target-specific process identifier. This field is only present + for thread groups of type 'process' and only if the process exists. + +'num_children' + The number of children this thread group has. This field may be + absent for an available thread group. + +'threads' + This field has a list of tuples as value, each tuple describing a + thread. It may be present if the '--recurse' option is specified, + and it's actually possible to obtain the threads. + +'cores' + This field is a list of integers, each identifying a core that one + thread of the group is running on. This field may be absent if + such information is not available. + +'executable' + The name of the executable file that corresponds to this thread + group. The field is only present for thread groups of type + 'process', and only if there is a corresponding executable file. + +Example +------- + + gdb + -list-thread-groups + ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}] + -list-thread-groups 17 + ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", + frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, + {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", + frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], + file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]] + -list-thread-groups --available + ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}] + -list-thread-groups --available --recurse 1 + ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], + threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, + {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..] + -list-thread-groups --available --recurse 1 17 18 + ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], + threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, + {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...] + +The '-info-os' Command +---------------------- + +Synopsis +........ + + -info-os [ TYPE ] + + If no argument is supplied, the command returns a table of available +operating-system-specific information types. If one of these types is +supplied as an argument TYPE, then the command returns a table of data +of that type. + + The types of information available depend on the target operating +system. + +GDB Command +........... + +The corresponding GDB command is 'info os'. + +Example +....... + +When run on a GNU/Linux system, the output will look something like +this: + + gdb + -info-os + ^done,OSDataTable={nr_rows="9",nr_cols="3", + hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"}, + {width="10",alignment="-1",col_name="col1",colhdr="Description"}, + {width="10",alignment="-1",col_name="col2",colhdr="Title"}], + body=[item={col0="processes",col1="Listing of all processes", + col2="Processes"}, + item={col0="procgroups",col1="Listing of all process groups", + col2="Process groups"}, + item={col0="threads",col1="Listing of all threads", + col2="Threads"}, + item={col0="files",col1="Listing of all file descriptors", + col2="File descriptors"}, + item={col0="sockets",col1="Listing of all internet-domain sockets", + col2="Sockets"}, + item={col0="shm",col1="Listing of all shared-memory regions", + col2="Shared-memory regions"}, + item={col0="semaphores",col1="Listing of all semaphores", + col2="Semaphores"}, + item={col0="msg",col1="Listing of all message queues", + col2="Message queues"}, + item={col0="modules",col1="Listing of all loaded kernel modules", + col2="Kernel modules"}]} + gdb + -info-os processes + ^done,OSDataTable={nr_rows="190",nr_cols="4", + hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"}, + {width="10",alignment="-1",col_name="col1",colhdr="user"}, + {width="10",alignment="-1",col_name="col2",colhdr="command"}, + {width="10",alignment="-1",col_name="col3",colhdr="cores"}], + body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"}, + item={col0="2",col1="root",col2="[kthreadd]",col3="1"}, + item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"}, + ... + item={col0="26446",col1="stan",col2="bash",col3="0"}, + item={col0="28152",col1="stan",col2="bash",col3="1"}]} + (gdb) + + (Note that the MI output here includes a '"Title"' column that does +not appear in command-line 'info os'; this column is useful for MI +clients that want to enumerate the types of data, such as in a popup +menu, but is needless clutter on the command line, and 'info os' omits +it.) + +The '-add-inferior' Command +--------------------------- + +Synopsis +-------- + + -add-inferior + + Creates a new inferior (*note Inferiors and Programs::). The created +inferior is not associated with any executable. Such association may be +established with the '-file-exec-and-symbols' command (*note GDB/MI File +Commands::). The command response has a single field, 'inferior', whose +value is the identifier of the thread group corresponding to the new +inferior. + +Example +------- + + gdb + -add-inferior + ^done,inferior="i3" + +The '-interpreter-exec' Command +------------------------------- + +Synopsis +-------- + + -interpreter-exec INTERPRETER COMMAND + + Execute the specified COMMAND in the given INTERPRETER. + +GDB Command +----------- + +The corresponding GDB command is 'interpreter-exec'. + +Example +------- + + (gdb) + -interpreter-exec console "break main" + &"During symbol reading, couldn't parse type; debugger out of date?.\n" + &"During symbol reading, bad structure-type format.\n" + ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" + ^done + (gdb) + +The '-inferior-tty-set' Command +------------------------------- + +Synopsis +-------- + + -inferior-tty-set /dev/pts/1 + + Set terminal for future runs of the program being debugged. + +GDB Command +----------- + +The corresponding GDB command is 'set inferior-tty' /dev/pts/1. + +Example +------- + + (gdb) + -inferior-tty-set /dev/pts/1 + ^done + (gdb) + +The '-inferior-tty-show' Command +-------------------------------- + +Synopsis +-------- + + -inferior-tty-show + + Show terminal for future runs of program being debugged. + +GDB Command +----------- + +The corresponding GDB command is 'show inferior-tty'. + +Example +------- + + (gdb) + -inferior-tty-set /dev/pts/1 + ^done + (gdb) + -inferior-tty-show + ^done,inferior_tty_terminal="/dev/pts/1" + (gdb) + +The '-enable-timings' Command +----------------------------- + +Synopsis +-------- + + -enable-timings [yes | no] + + Toggle the printing of the wallclock, user and system times for an MI +command as a field in its output. This command is to help frontend +developers optimize the performance of their code. No argument is +equivalent to 'yes'. + +GDB Command +----------- + +No equivalent. + +Example +------- + + (gdb) + -enable-timings + ^done + (gdb) + -break-insert main + ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x080484ed",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"], + times="0"}, + time={wallclock="0.05185",user="0.00800",system="0.00000"} + (gdb) + -enable-timings no + ^done + (gdb) + -exec-run + ^running + (gdb) + *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", + frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"}, + {name="argv",value="0xbfb60364"}],file="myprog.c", + fullname="/home/nickrob/myprog.c",line="73"} + (gdb) + + +File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top + +28 GDB Annotations +****************** + +This chapter describes annotations in GDB. Annotations were designed to +interface GDB to graphical user interfaces or other similar programs +which want to interact with GDB at a relatively high level. + + The annotation mechanism has largely been superseded by GDB/MI (*note +GDB/MI::). + +* Menu: + +* Annotations Overview:: What annotations are; the general syntax. +* Server Prefix:: Issuing a command without affecting user state. +* Prompting:: Annotations marking GDB's need for input. +* Errors:: Annotations for error messages. +* Invalidation:: Some annotations describe things now invalid. +* Annotations for Running:: + Whether the program is running, how it stopped, etc. +* Source Annotations:: Annotations describing source code. + + +File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations + +28.1 What is an Annotation? +=========================== + +Annotations start with a newline character, two 'control-z' characters, +and the name of the annotation. If there is no additional information +associated with this annotation, the name of the annotation is followed +immediately by a newline. If there is additional information, the name +of the annotation is followed by a space, the additional information, +and a newline. The additional information cannot contain newline +characters. + + Any output not beginning with a newline and two 'control-z' +characters denotes literal output from GDB. Currently there is no need +for GDB to output a newline followed by two 'control-z' characters, but +if there was such a need, the annotations could be extended with an +'escape' annotation which means those three characters as output. + + The annotation LEVEL, which is specified using the '--annotate' +command line option (*note Mode Options::), controls how much +information GDB prints together with its prompt, values of expressions, +source lines, and other types of output. Level 0 is for no annotations, +level 1 is for use when GDB is run as a subprocess of GNU Emacs, level 3 +is the maximum annotation suitable for programs that control GDB, and +level 2 annotations have been made obsolete (*note Limitations of the +Annotation Interface: (annotate)Limitations.). + +'set annotate LEVEL' + The GDB command 'set annotate' sets the level of annotations to the + specified LEVEL. + +'show annotate' + Show the current annotation level. + + This chapter describes level 3 annotations. + + A simple example of starting up GDB with annotations is: + + $ gdb --annotate=3 + GNU gdb 6.0 + Copyright 2003 Free Software Foundation, Inc. + GDB is free software, covered by the GNU General Public License, + and you are welcome to change it and/or distribute copies of it + under certain conditions. + Type "show copying" to see the conditions. + There is absolutely no warranty for GDB. Type "show warranty" + for details. + This GDB was configured as "i386-pc-linux-gnu" + + ^Z^Zpre-prompt + (gdb) + ^Z^Zprompt + quit + + ^Z^Zpost-prompt + $ + + Here 'quit' is input to GDB; the rest is output from GDB. The three +lines beginning '^Z^Z' (where '^Z' denotes a 'control-z' character) are +annotations; the rest is output from GDB. + + +File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations + +28.2 The Server Prefix +====================== + +If you prefix a command with 'server ' then it will not affect the +command history, nor will it affect GDB's notion of which command to +repeat if is pressed on a line by itself. This means that +commands can be run behind a user's back by a front-end in a transparent +manner. + + The 'server ' prefix does not affect the recording of values into the +value history; to print a value without recording it into the value +history, use the 'output' command instead of the 'print' command. + + Using this prefix also disables confirmation requests (*note +confirmation requests::). + + +File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations + +28.3 Annotation for GDB Input +============================= + +When GDB prompts for input, it annotates this fact so it is possible to +know when to send output, when the output from a given command is over, +etc. + + Different kinds of input each have a different "input type". Each +input type has three annotations: a 'pre-' annotation, which denotes the +beginning of any prompt which is being output, a plain annotation, which +denotes the end of the prompt, and then a 'post-' annotation which +denotes the end of any echo which may (or may not) be associated with +the input. For example, the 'prompt' input type features the following +annotations: + + ^Z^Zpre-prompt + ^Z^Zprompt + ^Z^Zpost-prompt + + The input types are + +'prompt' + When GDB is prompting for a command (the main GDB prompt). + +'commands' + When GDB prompts for a set of commands, like in the 'commands' + command. The annotations are repeated for each command which is + input. + +'overload-choice' + When GDB wants the user to select between various overloaded + functions. + +'query' + When GDB wants the user to confirm a potentially dangerous + operation. + +'prompt-for-continue' + When GDB is asking the user to press return to continue. Note: + Don't expect this to work well; instead use 'set height 0' to + disable prompting. This is because the counting of lines is buggy + in the presence of annotations. + + +File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations + +28.4 Errors +=========== + + ^Z^Zquit + + This annotation occurs right before GDB responds to an interrupt. + + ^Z^Zerror + + This annotation occurs right before GDB responds to an error. + + Quit and error annotations indicate that any annotations which GDB +was in the middle of may end abruptly. For example, if a +'value-history-begin' annotation is followed by a 'error', one cannot +expect to receive the matching 'value-history-end'. One cannot expect +not to receive it either, however; an error annotation does not +necessarily mean that GDB is immediately returning all the way to the +top level. + + A quit or error annotation may be preceded by + + ^Z^Zerror-begin + + Any output between that and the quit or error annotation is the error +message. + + Warning messages are not yet annotated. + + +File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations + +28.5 Invalidation Notices +========================= + +The following annotations say that certain pieces of state may have +changed. + +'^Z^Zframes-invalid' + + The frames (for example, output from the 'backtrace' command) may + have changed. + +'^Z^Zbreakpoints-invalid' + + The breakpoints may have changed. For example, the user just added + or deleted a breakpoint. + + +File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations + +28.6 Running the Program +======================== + +When the program starts executing due to a GDB command such as 'step' or +'continue', + + ^Z^Zstarting + + is output. When the program stops, + + ^Z^Zstopped + + is output. Before the 'stopped' annotation, a variety of annotations +describe how the program stopped. + +'^Z^Zexited EXIT-STATUS' + The program exited, and EXIT-STATUS is the exit status (zero for + successful exit, otherwise nonzero). + +'^Z^Zsignalled' + The program exited with a signal. After the '^Z^Zsignalled', the + annotation continues: + + INTRO-TEXT + ^Z^Zsignal-name + NAME + ^Z^Zsignal-name-end + MIDDLE-TEXT + ^Z^Zsignal-string + STRING + ^Z^Zsignal-string-end + END-TEXT + + where NAME is the name of the signal, such as 'SIGILL' or + 'SIGSEGV', and STRING is the explanation of the signal, such as + 'Illegal Instruction' or 'Segmentation fault'. INTRO-TEXT, + MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no + particular format. + +'^Z^Zsignal' + The syntax of this annotation is just like 'signalled', but GDB is + just saying that the program received the signal, not that it was + terminated with it. + +'^Z^Zbreakpoint NUMBER' + The program hit breakpoint number NUMBER. + +'^Z^Zwatchpoint NUMBER' + The program hit watchpoint number NUMBER. + + +File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations + +28.7 Displaying Source +====================== + +The following annotation is used instead of displaying source code: + + ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR + + where FILENAME is an absolute file name indicating which source file, +LINE is the line number within that file (where 1 is the first line in +the file), CHARACTER is the character position within the file (where 0 +is the first character in the file) (for most debug formats this will +necessarily point to the beginning of a line), MIDDLE is 'middle' if +ADDR is in the middle of the line, or 'beg' if ADDR is at the beginning +of the line, and ADDR is the address in the target program associated +with the source which is being displayed. ADDR is in the form '0x' +followed by one or more lowercase hex digits (note that this does not +depend on the language). + + +File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Annotations, Up: Top + +29 JIT Compilation Interface +**************************** + +This chapter documents GDB's "just-in-time" (JIT) compilation interface. +A JIT compiler is a program or library that generates native executable +code at runtime and executes it, usually in order to achieve good +performance while maintaining platform independence. + + Programs that use JIT compilation are normally difficult to debug +because portions of their code are generated at runtime, instead of +being loaded from object files, which is where GDB normally finds the +program's symbols and debug information. In order to debug programs +that use JIT compilation, GDB has an interface that allows the program +to register in-memory symbol files with GDB at runtime. + + If you are using GDB to debug a program that uses this interface, +then it should work transparently so long as you have not stripped the +binary. If you are developing a JIT compiler, then the interface is +documented in the rest of this chapter. At this time, the only known +client of this interface is the LLVM JIT. + + Broadly speaking, the JIT interface mirrors the dynamic loader +interface. The JIT compiler communicates with GDB by writing data into +a global variable and calling a fuction at a well-known symbol. When +GDB attaches, it reads a linked list of symbol files from the global +variable to find existing code, and puts a breakpoint in the function so +that it can find out about additional code. + +* Menu: + +* Declarations:: Relevant C struct declarations +* Registering Code:: Steps to register code +* Unregistering Code:: Steps to unregister code +* Custom Debug Info:: Emit debug information in a custom format + + +File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface + +29.1 JIT Declarations +===================== + +These are the relevant struct declarations that a C program should +include to implement the interface: + + typedef enum + { + JIT_NOACTION = 0, + JIT_REGISTER_FN, + JIT_UNREGISTER_FN + } jit_actions_t; + + struct jit_code_entry + { + struct jit_code_entry *next_entry; + struct jit_code_entry *prev_entry; + const char *symfile_addr; + uint64_t symfile_size; + }; + + struct jit_descriptor + { + uint32_t version; + /* This type should be jit_actions_t, but we use uint32_t + to be explicit about the bitwidth. */ + uint32_t action_flag; + struct jit_code_entry *relevant_entry; + struct jit_code_entry *first_entry; + }; + + /* GDB puts a breakpoint in this function. */ + void __attribute__((noinline)) __jit_debug_register_code() { }; + + /* Make sure to specify the version statically, because the + debugger may check the version before we can set it. */ + struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 }; + + If the JIT is multi-threaded, then it is important that the JIT +synchronize any modifications to this global data properly, which can +easily be done by putting a global mutex around modifications to these +structures. + + +File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface + +29.2 Registering Code +===================== + +To register code with GDB, the JIT should follow this protocol: + + * Generate an object file in memory with symbols and other desired + debug information. The file must include the virtual addresses of + the sections. + + * Create a code entry for the file, which gives the start and size of + the symbol file. + + * Add it to the linked list in the JIT descriptor. + + * Point the relevant_entry field of the descriptor at the entry. + + * Set 'action_flag' to 'JIT_REGISTER' and call + '__jit_debug_register_code'. + + When GDB is attached and the breakpoint fires, GDB uses the +'relevant_entry' pointer so it doesn't have to walk the list looking for +new code. However, the linked list must still be maintained in order to +allow GDB to attach to a running process and still find the symbol +files. + + +File: gdb.info, Node: Unregistering Code, Next: Custom Debug Info, Prev: Registering Code, Up: JIT Interface + +29.3 Unregistering Code +======================= + +If code is freed, then the JIT should use the following protocol: + + * Remove the code entry corresponding to the code from the linked + list. + + * Point the 'relevant_entry' field of the descriptor at the code + entry. + + * Set 'action_flag' to 'JIT_UNREGISTER' and call + '__jit_debug_register_code'. + + If the JIT frees or recompiles code without unregistering it, then +GDB and the JIT will leak the memory used for the associated symbol +files. + + +File: gdb.info, Node: Custom Debug Info, Prev: Unregistering Code, Up: JIT Interface + +29.4 Custom Debug Info +====================== + +Generating debug information in platform-native file formats (like ELF +or COFF) may be an overkill for JIT compilers; especially if all the +debug info is used for is displaying a meaningful backtrace. The issue +can be resolved by having the JIT writers decide on a debug info format +and also provide a reader that parses the debug info generated by the +JIT compiler. This section gives a brief overview on writing such a +parser. More specific details can be found in the source file +'gdb/jit-reader.in', which is also installed as a header at +'INCLUDEDIR/gdb/jit-reader.h' for easy inclusion. + + The reader is implemented as a shared object (so this functionality +is not available on platforms which don't allow loading shared objects +at runtime). Two GDB commands, 'jit-reader-load' and +'jit-reader-unload' are provided, to be used to load and unload the +readers from a preconfigured directory. Once loaded, the shared object +is used the parse the debug information emitted by the JIT compiler. + +* Menu: + +* Using JIT Debug Info Readers:: How to use supplied readers correctly +* Writing JIT Debug Info Readers:: Creating a debug-info reader + + +File: gdb.info, Node: Using JIT Debug Info Readers, Next: Writing JIT Debug Info Readers, Up: Custom Debug Info + +29.4.1 Using JIT Debug Info Readers +----------------------------------- + +Readers can be loaded and unloaded using the 'jit-reader-load' and +'jit-reader-unload' commands. + +'jit-reader-load READER' + Load the JIT reader named READER. READER is a shared object + specified as either an absolute or a relative file name. In the + latter case, GDB will try to load the reader from a pre-configured + directory, usually 'LIBDIR/gdb/' on a UNIX system (here LIBDIR is + the system library directory, often '/usr/local/lib'). + + Only one reader can be active at a time; trying to load a second + reader when one is already loaded will result in GDB reporting an + error. A new JIT reader can be loaded by first unloading the + current one using 'jit-reader-unload' and then invoking + 'jit-reader-load'. + +'jit-reader-unload' + Unload the currently loaded JIT reader. + + +File: gdb.info, Node: Writing JIT Debug Info Readers, Prev: Using JIT Debug Info Readers, Up: Custom Debug Info + +29.4.2 Writing JIT Debug Info Readers +------------------------------------- + +As mentioned, a reader is essentially a shared object conforming to a +certain ABI. This ABI is described in 'jit-reader.h'. + + 'jit-reader.h' defines the structures, macros and functions required +to write a reader. It is installed (along with GDB), in +'INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory. + + Readers need to be released under a GPL compatible license. A reader +can be declared as released under such a license by placing the macro +'GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file. + + The entry point for readers is the symbol 'gdb_init_reader', which is +expected to be a function with the prototype + + extern struct gdb_reader_funcs *gdb_init_reader (void); + + 'struct gdb_reader_funcs' contains a set of pointers to callback +functions. These functions are executed to read the debug info +generated by the JIT compiler ('read'), to unwind stack frames +('unwind') and to create canonical frame IDs ('get_Frame_id'). It also +has a callback that is called when the reader is being unloaded +('destroy'). The struct looks like this + + struct gdb_reader_funcs + { + /* Must be set to GDB_READER_INTERFACE_VERSION. */ + int reader_version; + + /* For use by the reader. */ + void *priv_data; + + gdb_read_debug_info *read; + gdb_unwind_frame *unwind; + gdb_get_frame_id *get_frame_id; + gdb_destroy_reader *destroy; + }; + + The callbacks are provided with another set of callbacks by GDB to do +their job. For 'read', these callbacks are passed in a 'struct +gdb_symbol_callbacks' and for 'unwind' and 'get_frame_id', in a 'struct +gdb_unwind_callbacks'. 'struct gdb_symbol_callbacks' has callbacks to +create new object files and new symbol tables inside those object files. +'struct gdb_unwind_callbacks' has callbacks to read registers off the +current frame and to write out the values of the registers in the +previous frame. Both have a callback ('target_read') to read bytes off +the target's address space. + + +File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface, Up: Top + +30 In-Process Agent +******************* + +The traditional debugging model is conceptually low-speed, but works +fine, because most bugs can be reproduced in debugging-mode execution. +However, as multi-core or many-core processors are becoming mainstream, +and multi-threaded programs become more and more popular, there should +be more and more bugs that only manifest themselves at normal-mode +execution, for example, thread races, because debugger's interference +with the program's timing may conceal the bugs. On the other hand, in +some applications, it is not feasible for the debugger to interrupt the +program's execution long enough for the developer to learn anything +helpful about its behavior. If the program's correctness depends on its +real-time behavior, delays introduced by a debugger might cause the +program to fail, even when the code itself is correct. It is useful to +be able to observe the program's behavior without interrupting it. + + Therefore, traditional debugging model is too intrusive to reproduce +some bugs. In order to reduce the interference with the program, we can +reduce the number of operations performed by debugger. The "In-Process +Agent", a shared library, is running within the same process with +inferior, and is able to perform some debugging operations itself. As a +result, debugger is only involved when necessary, and performance of +debugging can be improved accordingly. Note that interference with +program can be reduced but can't be removed completely, because the +in-process agent will still stop or slow down the program. + + The in-process agent can interpret and execute Agent Expressions +(*note Agent Expressions::) during performing debugging operations. The +agent expressions can be used for different purposes, such as collecting +data in tracepoints, and condition evaluation in breakpoints. + + You can control whether the in-process agent is used as an aid for +debugging with the following commands: + +'set agent on' + Causes the in-process agent to perform some operations on behalf of + the debugger. Just which operations requested by the user will be + done by the in-process agent depends on the its capabilities. For + example, if you request to evaluate breakpoint conditions in the + in-process agent, and the in-process agent has such capability as + well, then breakpoint conditions will be evaluated in the + in-process agent. + +'set agent off' + Disables execution of debugging operations by the in-process agent. + All of the operations will be performed by GDB. + +'show agent' + Display the current setting of execution of debugging operations by + the in-process agent. + +* Menu: + +* In-Process Agent Protocol:: + + +File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent + +30.1 In-Process Agent Protocol +============================== + +The in-process agent is able to communicate with both GDB and GDBserver +(*note In-Process Agent::). This section documents the protocol used +for communications between GDB or GDBserver and the IPA. In general, GDB +or GDBserver sends commands (*note IPA Protocol Commands::) and data to +in-process agent, and then in-process agent replies back with the return +result of the command, or some other information. The data sent to +in-process agent is composed of primitive data types, such as 4-byte or +8-byte type, and composite types, which are called objects (*note IPA +Protocol Objects::). + +* Menu: + +* IPA Protocol Objects:: +* IPA Protocol Commands:: + + +File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up: In-Process Agent Protocol + +30.1.1 IPA Protocol Objects +--------------------------- + +The commands sent to and results received from agent may contain some +complex data types called "objects". + + The in-process agent is running on the same machine with GDB or +GDBserver, so it doesn't have to handle as much differences between two +ends as remote protocol (*note Remote Protocol::) tries to handle. +However, there are still some differences of two ends in two processes: + + 1. word size. On some 64-bit machines, GDB or GDBserver can be + compiled as a 64-bit executable, while in-process agent is a 32-bit + one. + 2. ABI. Some machines may have multiple types of ABI, GDB or GDBserver + is compiled with one, and in-process agent is compiled with the + other one. + + Here are the IPA Protocol Objects: + + 1. agent expression object. It represents an agent expression (*note + Agent Expressions::). + 2. tracepoint action object. It represents a tracepoint action (*note + Tracepoint Action Lists: Tracepoint Actions.) to collect registers, + memory, static trace data and to evaluate expression. + 3. tracepoint object. It represents a tracepoint (*note + Tracepoints::). + + The following table describes important attributes of each IPA +protocol object: + +Name Size Description +--------------------------------------------------------------------------- +_agent expression +object_ +length 4 length of bytes code +byte code LENGTH contents of byte code +_tracepoint action +for collecting +memory_ +'M' 1 type of tracepoint action +addr 8 if BASEREG is '-1', ADDR is the + address of the lowest byte to + collect, otherwise ADDR is the + offset of BASEREG for memory + collecting. +len 8 length of memory for collecting +basereg 4 the register number containing the + starting memory address for + collecting. +_tracepoint action +for collecting +registers_ +'R' 1 type of tracepoint action +_tracepoint action +for collecting +static trace data_ +'L' 1 type of tracepoint action +_tracepoint action +for expression +evaluation_ +'X' 1 type of tracepoint action +agent expression length of *note agent expression object:: +_tracepoint object_ +number 4 number of tracepoint +address 8 address of tracepoint inserted on +type 4 type of tracepoint +enabled 1 enable or disable of tracepoint +step_count 8 step +pass_count 8 pass +numactions 4 number of tracepoint actions +hit count 8 hit count +trace frame usage 8 trace frame usage +compiled_cond 8 compiled condition +orig_size 8 orig size +condition 4 if zero if condition is NULL, + condition is otherwise is *note agent + NULL expression object:: + otherwise + length of + *note agent + expression + object:: +actions variable numactions number of *note + tracepoint action object:: + + +File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up: In-Process Agent Protocol + +30.1.2 IPA Protocol Commands +---------------------------- + +The spaces in each command are delimiters to ease reading this commands +specification. They don't exist in real commands. + +'FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD' + Installs a new fast tracepoint described by TRACEPOINT_OBJECT + (*note tracepoint object::). GDB_JUMP_PAD_HEAD, 8-byte long, is + the head of "jumppad", which is used to jump to data collection + routine in IPA finally. + + Replies: + 'OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP' + TARGET_ADDRESS is address of tracepoint in the inferior. + GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of + TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. FJUMP + contains a sequence of instructions jump to jumppad entry. + FJUMP_SIZE, 4-byte long, is the size of FJUMP. + 'E NN' + for an error + +'close' + Closes the in-process agent. This command is sent when GDB or + GDBserver is about to kill inferiors. + +'qTfSTM' + *Note qTfSTM::. +'qTsSTM' + *Note qTsSTM::. +'qTSTMat' + *Note qTSTMat::. +'probe_marker_at:ADDRESS' + Asks in-process agent to probe the marker at ADDRESS. + + Replies: + 'E NN' + for an error +'unprobe_marker_at:ADDRESS' + Asks in-process agent to unprobe the marker at ADDRESS. + + +File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process Agent, Up: Top + +31 Reporting Bugs in GDB +************************ + +Your bug reports play an essential role in making GDB reliable. + + Reporting a bug may help you by bringing a solution to your problem, +or it may not. But in any case the principal function of a bug report +is to help the entire community by making the next version of GDB work +better. Bug reports are your contribution to the maintenance of GDB. + + In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +* Menu: + +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs + + +File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs + +31.1 Have You Found a Bug? +========================== + +If you are not sure whether you have found a bug, here are some +guidelines: + + * If the debugger gets a fatal signal, for any input whatever, that + is a GDB bug. Reliable debuggers never crash. + + * If GDB produces an error message for valid input, that is a bug. + (Note that if you're cross debugging, the problem may also be + somewhere in the connection to the target.) + + * If GDB does not produce an error message for invalid input, that is + a bug. However, you should note that your idea of "invalid input" + might be our idea of "an extension" or "support for traditional + practice". + + * If you are an experienced user of debugging tools, your suggestions + for improvement of GDB are welcome in any case. + + +File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs + +31.2 How to Report Bugs +======================= + +A number of companies and individuals offer support for GNU products. +If you obtained GDB from a support organization, we recommend you +contact that organization first. + + You can find contact information for many support companies and +individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. + + In any event, we also recommend that you submit bug reports for GDB. +The preferred method is to submit them directly using GDB's Bugs web +page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the e-mail +gateway can be used. + + *Do not send bug reports to 'info-gdb', or to 'help-gdb', or to any +newsgroups.* Most users of GDB do not want to receive bug reports. +Those that do have arranged to receive 'bug-gdb'. + + The mailing list 'bug-gdb' has a newsgroup 'gnu.gdb.bug' which serves +as a repeater. The mailing list and the newsgroup carry exactly the +same messages. Often people think of posting bug reports to the +newsgroup instead of mailing them. This appears to work, but it has one +problem which can be crucial: a newsgroup posting often lacks a mail +path back to the sender. Thus, if we need to ask for more information, +we may be unable to reach you. For this reason, it is better to send +bug reports to the mailing list. + + The fundamental principle of reporting bugs usefully is this: *report +all the facts*. If you are not sure whether to state a fact or leave it +out, state it! + + Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of the variable you use in an example does not +matter. Well, probably it does not, but one cannot be sure. Perhaps +the bug is a stray memory reference which happens to fetch from the +location where that name is stored in memory; perhaps, if the name were +different, the contents of that location would fool the debugger into +doing the right thing despite the bug. Play it safe and give a +specific, complete example. That is the easiest thing for you to do, +and the most helpful. + + Keep in mind that the purpose of a bug report is to enable us to fix +the bug. It may be that the bug has been reported previously, but +neither you nor we can know that unless your bug report is complete and +self-contained. + + Sometimes people give a few sketchy facts and ask, "Does this ring a +bell?" Those bug reports are useless, and we urge everyone to _refuse +to respond to them_ except to chide the sender to report bugs properly. + + To enable us to fix the bug, you should include all these things: + + * The version of GDB. GDB announces it if you start with no + arguments; you can also print it at any time using 'show version'. + + Without this, we will not know whether there is any point in + looking for the bug in the current version of GDB. + + * The type of machine you are using, and the operating system name + and version number. + + * The details of the GDB build-time configuration. GDB shows these + details if you invoke it with the '--configuration' command-line + option, or if you type 'show configuration' at GDB's prompt. + + * What compiler (and its version) was used to compile GDB--e.g. + "gcc-2.8.1". + + * What compiler (and its version) was used to compile the program you + are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP C + Compiler". For GCC, you can say 'gcc --version' to get this + information; for other compilers, see the documentation for those + compilers. + + * The command arguments you gave the compiler to compile your example + and observe the bug. For example, did you use '-O'? To guarantee + you will not omit something important, list them all. A copy of + the Makefile (or the output from make) is sufficient. + + If we were to try to guess the arguments, we would probably guess + wrong and then we might not encounter the bug. + + * A complete input script, and all necessary source files, that will + reproduce the bug. + + * A description of what behavior you observe that you believe is + incorrect. For example, "It gets a fatal signal." + + Of course, if the bug is that GDB gets a fatal signal, then we will + certainly notice it. But if the bug is incorrect output, we might + not notice unless it is glaringly wrong. You might as well not + give us a chance to make a mistake. + + Even if the problem you experience is a fatal signal, you should + still say so explicitly. Suppose something strange is going on, + such as, your copy of GDB is out of synch, or you have encountered + a bug in the C library on your system. (This has happened!) Your + copy might crash and ours would not. If you told us to expect a + crash, then when ours fails to crash, we would know that the bug + was not happening for us. If you had not told us to expect a + crash, then we would not be able to draw any conclusion from our + observations. + + To collect all this information, you can use a session recording + program such as 'script', which is available on many Unix systems. + Just run your GDB session inside 'script' and then include the + 'typescript' file with your bug report. + + Another way to record a GDB session is to run GDB inside Emacs and + then save the entire buffer to a file. + + * If you wish to suggest changes to the GDB source, send us context + diffs. If you even discuss something in the GDB source, refer to + it by context, not by line number. + + The line numbers in our development sources will not match those in + your sources. Your line numbers would convey no useful information + to us. + + Here are some things that are not necessary: + + * A description of the envelope of the bug. + + Often people who encounter a bug spend a lot of time investigating + which changes to the input file will make the bug go away and which + changes will not affect it. + + This is often time consuming and not very useful, because the way + we will find the bug is by running a single example under the + debugger with breakpoints, not by pure deduction from a series of + examples. We recommend that you save your time for something else. + + Of course, if you can find a simpler example to report _instead_ of + the original one, that is a convenience for us. Errors in the + output will be easier to spot, running under the debugger will take + less time, and so on. + + However, simplification is not vital; if you do not want to do + this, report the bug anyway and send us the entire test case you + used. + + * A patch for the bug. + + A patch for the bug does help us if it is a good one. But do not + omit the necessary information, such as the test case, on the + assumption that a patch is all we need. We might see problems with + your patch and decide to fix the problem another way, or we might + not understand it at all. + + Sometimes with a program as complicated as GDB it is very hard to + construct an example that will make the program follow a certain + path through the code. If you do not send us the example, we will + not be able to construct one, so we will not be able to verify that + the bug is fixed. + + And if we cannot understand what bug you are trying to fix, or why + your patch should be an improvement, we will not install it. A + test case will help us to understand. + + * A guess about what the bug is or what it depends on. + + Such guesses are usually wrong. Even we cannot guess right about + such things without first using the debugger to find the facts. + + +File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top + +32 Command Line Editing +*********************** + +This chapter describes the basic features of the GNU command line +editing interface. + +* Menu: + +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Init File:: Customizing Readline from a user's view. +* Bindable Readline Commands:: A description of most of the Readline commands + available for binding +* Readline vi Mode:: A short description of how to make Readline + behave like the vi editor. + + +File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing + +32.1 Introduction to Line Editing +================================= + +The following paragraphs describe the notation used to represent +keystrokes. + + The text 'C-k' is read as 'Control-K' and describes the character +produced when the key is pressed while the Control key is depressed. + + The text 'M-k' is read as 'Meta-K' and describes the character +produced when the Meta key (if you have one) is depressed, and the +key is pressed. The Meta key is labeled on many keyboards. On +keyboards with two keys labeled (usually to either side of the +space bar), the on the left side is generally set to work as a +Meta key. The key on the right may also be configured to work as +a Meta key or may be configured as some other modifier, such as a +Compose key for typing accented characters. + + If you do not have a Meta or key, or another key working as a +Meta key, the identical keystroke can be generated by typing +_first_, and then typing . Either process is known as "metafying" +the key. + + The text 'M-C-k' is read as 'Meta-Control-k' and describes the +character produced by "metafying" 'C-k'. + + In addition, several keys have their own names. Specifically, , +, , , , and all stand for themselves when seen +in this text, or in an init file (*note Readline Init File::). If your +keyboard lacks a key, typing will produce the desired +character. The key may be labeled or on some +keyboards. + + +File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing + +32.2 Readline Interaction +========================= + +Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press . You do not have to be at the end of +the line to press ; the entire line is accepted regardless of the +location of the cursor within the line. + +* Menu: + +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. +* Searching:: Searching through previous lines. + + +File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction + +32.2.1 Readline Bare Essentials +------------------------------- + +In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use your erase +character to back up and delete the mistyped character. + + Sometimes you may mistype a character, and not notice the error until +you have typed several other characters. In that case, you can type +'C-b' to move the cursor to the left, and then correct your mistake. +Afterwards, you can move the cursor to the right with 'C-f'. + + When you add text in the middle of a line, you will notice that +characters to the right of the cursor are 'pushed over' to make room for +the text that you have inserted. Likewise, when you delete text behind +the cursor, characters to the right of the cursor are 'pulled back' to +fill in the blank space created by the removal of the text. A list of +the bare essentials for editing the text of an input line follows. + +'C-b' + Move back one character. +'C-f' + Move forward one character. + or + Delete the character to the left of the cursor. +'C-d' + Delete the character underneath the cursor. +Printing characters + Insert the character into the line at the cursor. +'C-_' or 'C-x C-u' + Undo the last editing command. You can undo all the way back to an + empty line. + +(Depending on your configuration, the key be set to delete +the character to the left of the cursor and the key set to delete +the character underneath the cursor, like 'C-d', rather than the +character to the left of the cursor.) + + +File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction + +32.2.2 Readline Movement Commands +--------------------------------- + +The above table describes the most basic keystrokes that you need in +order to do editing of the input line. For your convenience, many other +commands have been added in addition to 'C-b', 'C-f', 'C-d', and . +Here are some commands for moving more rapidly about the line. + +'C-a' + Move to the start of the line. +'C-e' + Move to the end of the line. +'M-f' + Move forward a word, where a word is composed of letters and + digits. +'M-b' + Move backward a word. +'C-l' + Clear the screen, reprinting the current line at the top. + + Notice how 'C-f' moves forward a character, while 'M-f' moves forward +a word. It is a loose convention that control keystrokes operate on +characters while meta keystrokes operate on words. + + +File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction + +32.2.3 Readline Killing Commands +-------------------------------- + +"Killing" text means to delete the text from the line, but to save it +away for later use, usually by "yanking" (re-inserting) it back into the +line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.) + + If the description for a command says that it 'kills' text, then you +can be sure that you can get the text back in a different (or the same) +place later. + + When you use a kill command, the text is saved in a "kill-ring". Any +number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill ring is not line +specific; the text that you killed on a previously typed line is +available to be yanked back later, when you are typing another line. + + Here is the list of commands for killing text. + +'C-k' + Kill the text from the current cursor position to the end of the + line. + +'M-d' + Kill from the cursor to the end of the current word, or, if between + words, to the end of the next word. Word boundaries are the same + as those used by 'M-f'. + +'M-' + Kill from the cursor the start of the current word, or, if between + words, to the start of the previous word. Word boundaries are the + same as those used by 'M-b'. + +'C-w' + Kill from the cursor to the previous whitespace. This is different + than 'M-' because the word boundaries differ. + + Here is how to "yank" the text back into the line. Yanking means to +copy the most-recently-killed text from the kill buffer. + +'C-y' + Yank the most recently killed text back into the buffer at the + cursor. + +'M-y' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is 'C-y' or 'M-y'. + + +File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction + +32.2.4 Readline Arguments +------------------------- + +You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the sign of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type 'M-- C-k'. + + The general way to pass numeric arguments to a command is to type +meta digits before the command. If the first 'digit' typed is a minus +sign ('-'), then the sign of the argument will be negative. Once you +have typed one meta digit to get the argument started, you can type the +remainder of the digits, and then the command. For example, to give the +'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will +delete the next ten characters on the input line. + + +File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction + +32.2.5 Searching for Commands in the History +-------------------------------------------- + +Readline provides commands for searching through the command history for +lines containing a specified string. There are two search modes: +"incremental" and "non-incremental". + + Incremental searches begin before the user has finished typing the +search string. As each character of the search string is typed, +Readline displays the next entry from the history matching the string +typed so far. An incremental search requires only as many characters as +needed to find the desired history entry. To search backward in the +history for a particular string, type 'C-r'. Typing 'C-s' searches +forward through the history. The characters present in the value of the +'isearch-terminators' variable are used to terminate an incremental +search. If that variable has not been assigned a value, the and +'C-J' characters will terminate an incremental search. 'C-g' will abort +an incremental search and restore the original line. When the search is +terminated, the history entry containing the search string becomes the +current line. + + To find other matching entries in the history list, type 'C-r' or +'C-s' as appropriate. This will search backward or forward in the +history for the next entry matching the search string typed so far. Any +other key sequence bound to a Readline command will terminate the search +and execute that command. For instance, a will terminate the +search and accept the line, thereby executing the command from the +history list. A movement command will terminate the search, make the +last line found the current line, and begin editing. + + Readline remembers the last incremental search string. If two 'C-r's +are typed without any intervening characters defining a new search +string, any remembered search string is used. + + Non-incremental searches read the entire search string before +starting to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. + + +File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing + +32.3 Readline Init File +======================= + +Although the Readline library comes with a set of Emacs-like keybindings +installed by default, it is possible to use a different set of +keybindings. Any user can customize programs that use Readline by +putting commands in an "inputrc" file, conventionally in his home +directory. The name of this file is taken from the value of the +environment variable 'INPUTRC'. If that variable is unset, the default +is '~/.inputrc'. If that file does not exist or cannot be read, the +ultimate default is '/etc/inputrc'. + + When a program which uses the Readline library starts up, the init +file is read, and the key bindings are set. + + In addition, the 'C-x C-r' command re-reads this init file, thus +incorporating any changes that you might have made to it. + +* Menu: + +* Readline Init File Syntax:: Syntax for the commands in the inputrc file. + +* Conditional Init Constructs:: Conditional key bindings in the inputrc file. + +* Sample Init File:: An example inputrc file. + + +File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File + +32.3.1 Readline Init File Syntax +-------------------------------- + +There are only a few basic constructs allowed in the Readline init file. +Blank lines are ignored. Lines beginning with a '#' are comments. +Lines beginning with a '$' indicate conditional constructs (*note +Conditional Init Constructs::). Other lines denote variable settings +and key bindings. + +Variable Settings + You can modify the run-time behavior of Readline by altering the + values of variables in Readline using the 'set' command within the + init file. The syntax is simple: + + set VARIABLE VALUE + + Here, for example, is how to change from the default Emacs-like key + binding to use 'vi' line editing commands: + + set editing-mode vi + + Variable names and values, where appropriate, are recognized + without regard to case. Unrecognized variable names are ignored. + + Boolean variables (those that can be set to on or off) are set to + on if the value is null or empty, ON (case-insensitive), or 1. Any + other value results in the variable being set to off. + + A great deal of run-time behavior is changeable with the following + variables. + + 'bell-style' + Controls what happens when Readline wants to ring the terminal + bell. If set to 'none', Readline never rings the bell. If + set to 'visible', Readline uses a visible bell if one is + available. If set to 'audible' (the default), Readline + attempts to ring the terminal's bell. + + 'bind-tty-special-chars' + If set to 'on', Readline attempts to bind the control + characters treated specially by the kernel's terminal driver + to their Readline equivalents. + + 'comment-begin' + The string to insert at the beginning of the line when the + 'insert-comment' command is executed. The default value is + '"#"'. + + 'completion-display-width' + The number of screen columns used to display possible matches + when performing completion. The value is ignored if it is + less than 0 or greater than the terminal screen width. A + value of 0 will cause matches to be displayed one per line. + The default value is -1. + + 'completion-ignore-case' + If set to 'on', Readline performs filename matching and + completion in a case-insensitive fashion. The default value + is 'off'. + + 'completion-map-case' + If set to 'on', and COMPLETION-IGNORE-CASE is enabled, + Readline treats hyphens ('-') and underscores ('_') as + equivalent when performing case-insensitive filename matching + and completion. + + 'completion-prefix-display-length' + The length in characters of the common prefix of a list of + possible completions that is displayed without modification. + When set to a value greater than zero, common prefixes longer + than this value are replaced with an ellipsis when displaying + possible completions. + + 'completion-query-items' + The number of possible completions that determines when the + user is asked whether the list of possibilities should be + displayed. If the number of possible completions is greater + than this value, Readline will ask the user whether or not he + wishes to view them; otherwise, they are simply listed. This + variable must be set to an integer value greater than or equal + to 0. A negative value means Readline should never ask. The + default limit is '100'. + + 'convert-meta' + If set to 'on', Readline will convert characters with the + eighth bit set to an ASCII key sequence by stripping the + eighth bit and prefixing an character, converting them + to a meta-prefixed key sequence. The default value is 'on'. + + 'disable-completion' + If set to 'On', Readline will inhibit word completion. + Completion characters will be inserted into the line as if + they had been mapped to 'self-insert'. The default is 'off'. + + 'editing-mode' + The 'editing-mode' variable controls which default set of key + bindings is used. By default, Readline starts up in Emacs + editing mode, where the keystrokes are most similar to Emacs. + This variable can be set to either 'emacs' or 'vi'. + + 'echo-control-characters' + When set to 'on', on operating systems that indicate they + support it, readline echoes a character corresponding to a + signal generated from the keyboard. The default is 'on'. + + 'enable-keypad' + When set to 'on', Readline will try to enable the application + keypad when it is called. Some systems need this to enable + the arrow keys. The default is 'off'. + + 'enable-meta-key' + When set to 'on', Readline will try to enable any meta + modifier key the terminal claims to support when it is called. + On many terminals, the meta key is used to send eight-bit + characters. The default is 'on'. + + 'expand-tilde' + If set to 'on', tilde expansion is performed when Readline + attempts word completion. The default is 'off'. + + 'history-preserve-point' + If set to 'on', the history code attempts to place the point + (the current cursor position) at the same location on each + history line retrieved with 'previous-history' or + 'next-history'. The default is 'off'. + + 'history-size' + Set the maximum number of history entries saved in the history + list. If set to zero, the number of entries in the history + list is not limited. + + 'horizontal-scroll-mode' + This variable can be set to either 'on' or 'off'. Setting it + to 'on' means that the text of the lines being edited will + scroll horizontally on a single screen line when they are + longer than the width of the screen, instead of wrapping onto + a new screen line. By default, this variable is set to 'off'. + + 'input-meta' + If set to 'on', Readline will enable eight-bit input (it will + not clear the eighth bit in the characters it reads), + regardless of what the terminal claims it can support. The + default value is 'off'. The name 'meta-flag' is a synonym for + this variable. + + 'isearch-terminators' + The string of characters that should terminate an incremental + search without subsequently executing the character as a + command (*note Searching::). If this variable has not been + given a value, the characters and 'C-J' will terminate + an incremental search. + + 'keymap' + Sets Readline's idea of the current keymap for key binding + commands. Acceptable 'keymap' names are 'emacs', + 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', + 'vi-command', and 'vi-insert'. 'vi' is equivalent to + 'vi-command'; 'emacs' is equivalent to 'emacs-standard'. The + default value is 'emacs'. The value of the 'editing-mode' + variable also affects the default keymap. + + 'mark-directories' + If set to 'on', completed directory names have a slash + appended. The default is 'on'. + + 'mark-modified-lines' + This variable, when set to 'on', causes Readline to display an + asterisk ('*') at the start of history lines which have been + modified. This variable is 'off' by default. + + 'mark-symlinked-directories' + If set to 'on', completed names which are symbolic links to + directories have a slash appended (subject to the value of + 'mark-directories'). The default is 'off'. + + 'match-hidden-files' + This variable, when set to 'on', causes Readline to match + files whose names begin with a '.' (hidden files) when + performing filename completion. If set to 'off', the leading + '.' must be supplied by the user in the filename to be + completed. This variable is 'on' by default. + + 'menu-complete-display-prefix' + If set to 'on', menu completion displays the common prefix of + the list of possible completions (which may be empty) before + cycling through the list. The default is 'off'. + + 'output-meta' + If set to 'on', Readline will display characters with the + eighth bit set directly rather than as a meta-prefixed escape + sequence. The default is 'off'. + + 'page-completions' + If set to 'on', Readline uses an internal 'more'-like pager to + display a screenful of possible completions at a time. This + variable is 'on' by default. + + 'print-completions-horizontally' + If set to 'on', Readline will display completions with matches + sorted horizontally in alphabetical order, rather than down + the screen. The default is 'off'. + + 'revert-all-at-newline' + If set to 'on', Readline will undo all changes to history + lines before returning when 'accept-line' is executed. By + default, history lines may be modified and retain individual + undo lists across calls to 'readline'. The default is 'off'. + + 'show-all-if-ambiguous' + This alters the default behavior of the completion functions. + If set to 'on', words which have more than one possible + completion cause the matches to be listed immediately instead + of ringing the bell. The default value is 'off'. + + 'show-all-if-unmodified' + This alters the default behavior of the completion functions + in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to + 'on', words which have more than one possible completion + without any possible partial completion (the possible + completions don't share a common prefix) cause the matches to + be listed immediately instead of ringing the bell. The + default value is 'off'. + + 'skip-completed-text' + If set to 'on', this alters the default completion behavior + when inserting a single match into the line. It's only active + when performing completion in the middle of a word. If + enabled, readline does not insert characters from the + completion that match characters after point in the word being + completed, so portions of the word following the cursor are + not duplicated. For instance, if this is enabled, attempting + completion when the cursor is after the 'e' in 'Makefile' will + result in 'Makefile' rather than 'Makefilefile', assuming + there is a single possible completion. The default value is + 'off'. + + 'visible-stats' + If set to 'on', a character denoting a file's type is appended + to the filename when listing possible completions. The + default is 'off'. + +Key Bindings + The syntax for controlling key bindings in the init file is simple. + First you need to find the name of the command that you want to + change. The following sections contain tables of the command name, + the default keybinding, if any, and a short description of what the + command does. + + Once you know the name of the command, simply place on a line in + the init file the name of the key you wish to bind the command to, + a colon, and then the name of the command. There can be no space + between the key name and the colon - that will be interpreted as + part of the key name. The name of the key can be expressed in + different ways, depending on what you find most comfortable. + + In addition to command names, readline allows keys to be bound to a + string that is inserted when the key is pressed (a MACRO). + + KEYNAME: FUNCTION-NAME or MACRO + KEYNAME is the name of a key spelled out in English. For + example: + Control-u: universal-argument + Meta-Rubout: backward-kill-word + Control-o: "> output" + + In the above example, 'C-u' is bound to the function + 'universal-argument', 'M-DEL' is bound to the function + 'backward-kill-word', and 'C-o' is bound to run the macro + expressed on the right hand side (that is, to insert the text + '> output' into the line). + + A number of symbolic character names are recognized while + processing this key binding syntax: DEL, ESC, ESCAPE, LFD, + NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. + + "KEYSEQ": FUNCTION-NAME or MACRO + KEYSEQ differs from KEYNAME above in that strings denoting an + entire key sequence can be specified, by placing the key + sequence in double quotes. Some GNU Emacs style key escapes + can be used, as in the following example, but the special + character names are not recognized. + + "\C-u": universal-argument + "\C-x\C-r": re-read-init-file + "\e[11~": "Function Key 1" + + In the above example, 'C-u' is again bound to the function + 'universal-argument' (just as it was in the first example), + ''C-x' 'C-r'' is bound to the function 're-read-init-file', + and ' <[> <1> <1> <~>' is bound to insert the text + 'Function Key 1'. + + The following GNU Emacs style escape sequences are available when + specifying key sequences: + + '\C-' + control prefix + '\M-' + meta prefix + '\e' + an escape character + '\\' + backslash + '\"' + <">, a double quotation mark + '\'' + <'>, a single quote or apostrophe + + In addition to the GNU Emacs style escape sequences, a second set + of backslash escapes is available: + + '\a' + alert (bell) + '\b' + backspace + '\d' + delete + '\f' + form feed + '\n' + newline + '\r' + carriage return + '\t' + horizontal tab + '\v' + vertical tab + '\NNN' + the eight-bit character whose value is the octal value NNN + (one to three digits) + '\xHH' + the eight-bit character whose value is the hexadecimal value + HH (one or two hex digits) + + When entering the text of a macro, single or double quotes must be + used to indicate a macro definition. Unquoted text is assumed to + be a function name. In the macro body, the backslash escapes + described above are expanded. Backslash will quote any other + character in the macro text, including '"' and '''. For example, + the following binding will make ''C-x' \' insert a single '\' into + the line: + "\C-x\\": "\\" + + +File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File + +32.3.2 Conditional Init Constructs +---------------------------------- + +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key bindings and +variable settings to be performed as the result of tests. There are +four parser directives used. + +'$if' + The '$if' construct allows bindings to be made based on the editing + mode, the terminal being used, or the application using Readline. + The text of the test extends to the end of the line; no characters + are required to isolate it. + + 'mode' + The 'mode=' form of the '$if' directive is used to test + whether Readline is in 'emacs' or 'vi' mode. This may be used + in conjunction with the 'set keymap' command, for instance, to + set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps + only if Readline is starting out in 'emacs' mode. + + 'term' + The 'term=' form may be used to include terminal-specific key + bindings, perhaps to bind the key sequences output by the + terminal's function keys. The word on the right side of the + '=' is tested against both the full name of the terminal and + the portion of the terminal name before the first '-'. This + allows 'sun' to match both 'sun' and 'sun-cmd', for instance. + + 'application' + The APPLICATION construct is used to include + application-specific settings. Each program using the + Readline library sets the APPLICATION NAME, and you can test + for a particular value. This could be used to bind key + sequences to functions useful for a specific program. For + instance, the following command adds a key sequence that + quotes the current or previous word in Bash: + $if Bash + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + $endif + +'$endif' + This command, as seen in the previous example, terminates an '$if' + command. + +'$else' + Commands in this branch of the '$if' directive are executed if the + test fails. + +'$include' + This directive takes a single filename as an argument and reads + commands and bindings from that file. For example, the following + directive reads from '/etc/inputrc': + $include /etc/inputrc + + +File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File + +32.3.3 Sample Init File +----------------------- + +Here is an example of an INPUTRC file. This illustrates key binding, +variable assignment, and conditional syntax. + + # This file controls the behaviour of line input editing for + # programs that use the GNU Readline library. Existing + # programs include FTP, Bash, and GDB. + # + # You can re-read the inputrc file with C-x C-r. + # Lines beginning with '#' are comments. + # + # First, include any systemwide bindings and variable + # assignments from /etc/Inputrc + $include /etc/Inputrc + + # + # Set various bindings for emacs mode. + + set editing-mode emacs + + $if mode=emacs + + Meta-Control-h: backward-kill-word Text after the function name is ignored + + # + # Arrow keys in keypad mode + # + #"\M-OD": backward-char + #"\M-OC": forward-char + #"\M-OA": previous-history + #"\M-OB": next-history + # + # Arrow keys in ANSI mode + # + "\M-[D": backward-char + "\M-[C": forward-char + "\M-[A": previous-history + "\M-[B": next-history + # + # Arrow keys in 8 bit keypad mode + # + #"\M-\C-OD": backward-char + #"\M-\C-OC": forward-char + #"\M-\C-OA": previous-history + #"\M-\C-OB": next-history + # + # Arrow keys in 8 bit ANSI mode + # + #"\M-\C-[D": backward-char + #"\M-\C-[C": forward-char + #"\M-\C-[A": previous-history + #"\M-\C-[B": next-history + + C-q: quoted-insert + + $endif + + # An old-style binding. This happens to be the default. + TAB: complete + + # Macros that are convenient for shell interaction + $if Bash + # edit the path + "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" + # prepare to type a quoted word -- + # insert open and close double quotes + # and move to just after the open quote + "\C-x\"": "\"\"\C-b" + # insert a backslash (testing backslash escapes + # in sequences and macros) + "\C-x\\": "\\" + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + # Add a binding to refresh the line, which is unbound + "\C-xr": redraw-current-line + # Edit variable on current line. + "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" + $endif + + # use a visible bell if one is available + set bell-style visible + + # don't strip characters to 7 bits when reading + set input-meta on + + # allow iso-latin1 characters to be inserted rather + # than converted to prefix-meta sequences + set convert-meta off + + # display characters with the eighth bit set directly + # rather than as meta-prefixed characters + set output-meta on + + # if there are more than 150 possible completions for + # a word, ask the user if he wants to see all of them + set completion-query-items 150 + + # For FTP + $if Ftp + "\C-xg": "get \M-?" + "\C-xt": "put \M-?" + "\M-.": yank-last-arg + $endif + + +File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing + +32.4 Bindable Readline Commands +=============================== + +* Menu: + +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Keyboard Macros:: Saving and re-executing typed characters +* Miscellaneous Commands:: Other miscellaneous commands. + +This section describes Readline commands that may be bound to key +sequences. Command names without an accompanying key sequence are +unbound by default. + + In the following descriptions, "point" refers to the current cursor +position, and "mark" refers to a cursor position saved by the 'set-mark' +command. The text between the point and mark is referred to as the +"region". + + +File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands + +32.4.1 Commands For Moving +-------------------------- + +'beginning-of-line (C-a)' + Move to the start of the current line. + +'end-of-line (C-e)' + Move to the end of the line. + +'forward-char (C-f)' + Move forward a character. + +'backward-char (C-b)' + Move back a character. + +'forward-word (M-f)' + Move forward to the end of the next word. Words are composed of + letters and digits. + +'backward-word (M-b)' + Move back to the start of the current or previous word. Words are + composed of letters and digits. + +'clear-screen (C-l)' + Clear the screen and redraw the current line, leaving the current + line at the top of the screen. + +'redraw-current-line ()' + Refresh the current line. By default, this is unbound. + + +File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands + +32.4.2 Commands For Manipulating The History +-------------------------------------------- + +'accept-line (Newline or Return)' + Accept the line regardless of where the cursor is. If this line is + non-empty, it may be added to the history list for future recall + with 'add_history()'. If this line is a modified history line, the + history line is restored to its original state. + +'previous-history (C-p)' + Move 'back' through the history list, fetching the previous + command. + +'next-history (C-n)' + Move 'forward' through the history list, fetching the next command. + +'beginning-of-history (M-<)' + Move to the first line in the history. + +'end-of-history (M->)' + Move to the end of the input history, i.e., the line currently + being entered. + +'reverse-search-history (C-r)' + Search backward starting at the current line and moving 'up' + through the history as necessary. This is an incremental search. + +'forward-search-history (C-s)' + Search forward starting at the current line and moving 'down' + through the the history as necessary. This is an incremental + search. + +'non-incremental-reverse-search-history (M-p)' + Search backward starting at the current line and moving 'up' + through the history as necessary using a non-incremental search for + a string supplied by the user. + +'non-incremental-forward-search-history (M-n)' + Search forward starting at the current line and moving 'down' + through the the history as necessary using a non-incremental search + for a string supplied by the user. + +'history-search-forward ()' + Search forward through the history for the string of characters + between the start of the current line and the point. This is a + non-incremental search. By default, this command is unbound. + +'history-search-backward ()' + Search backward through the history for the string of characters + between the start of the current line and the point. This is a + non-incremental search. By default, this command is unbound. + +'yank-nth-arg (M-C-y)' + Insert the first argument to the previous command (usually the + second word on the previous line) at point. With an argument N, + insert the Nth word from the previous command (the words in the + previous command begin with word 0). A negative argument inserts + the Nth word from the end of the previous command. Once the + argument N is computed, the argument is extracted as if the '!N' + history expansion had been specified. + +'yank-last-arg (M-. or M-_)' + Insert last argument to the previous command (the last word of the + previous history entry). With a numeric argument, behave exactly + like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back + through the history list, inserting the last word (or the word + specified by the argument to the first call) of each line in turn. + Any numeric argument supplied to these successive calls determines + the direction to move through the history. A negative argument + switches the direction through the history (back or forward). The + history expansion facilities are used to extract the last argument, + as if the '!$' history expansion had been specified. + + +File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands + +32.4.3 Commands For Changing Text +--------------------------------- + +'delete-char (C-d)' + Delete the character at point. If point is at the beginning of the + line, there are no characters in the line, and the last character + typed was not bound to 'delete-char', then return EOF. + +'backward-delete-char (Rubout)' + Delete the character behind the cursor. A numeric argument means + to kill the characters instead of deleting them. + +'forward-backward-delete-char ()' + Delete the character under the cursor, unless the cursor is at the + end of the line, in which case the character behind the cursor is + deleted. By default, this is not bound to a key. + +'quoted-insert (C-q or C-v)' + Add the next character typed to the line verbatim. This is how to + insert key sequences like 'C-q', for example. + +'tab-insert (M-)' + Insert a tab character. + +'self-insert (a, b, A, 1, !, ...)' + Insert yourself. + +'transpose-chars (C-t)' + Drag the character before the cursor forward over the character at + the cursor, moving the cursor forward as well. If the insertion + point is at the end of the line, then this transposes the last two + characters of the line. Negative arguments have no effect. + +'transpose-words (M-t)' + Drag the word before point past the word after point, moving point + past that word as well. If the insertion point is at the end of + the line, this transposes the last two words on the line. + +'upcase-word (M-u)' + Uppercase the current (or following) word. With a negative + argument, uppercase the previous word, but do not move the cursor. + +'downcase-word (M-l)' + Lowercase the current (or following) word. With a negative + argument, lowercase the previous word, but do not move the cursor. + +'capitalize-word (M-c)' + Capitalize the current (or following) word. With a negative + argument, capitalize the previous word, but do not move the cursor. + +'overwrite-mode ()' + Toggle overwrite mode. With an explicit positive numeric argument, + switches to overwrite mode. With an explicit non-positive numeric + argument, switches to insert mode. This command affects only + 'emacs' mode; 'vi' mode does overwrite differently. Each call to + 'readline()' starts in insert mode. + + In overwrite mode, characters bound to 'self-insert' replace the + text at point rather than pushing the text to the right. + Characters bound to 'backward-delete-char' replace the character + before point with a space. + + By default, this command is unbound. + + +File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands + +32.4.4 Killing And Yanking +-------------------------- + +'kill-line (C-k)' + Kill the text from point to the end of the line. + +'backward-kill-line (C-x Rubout)' + Kill backward to the beginning of the line. + +'unix-line-discard (C-u)' + Kill backward from the cursor to the beginning of the current line. + +'kill-whole-line ()' + Kill all characters on the current line, no matter where point is. + By default, this is unbound. + +'kill-word (M-d)' + Kill from point to the end of the current word, or if between + words, to the end of the next word. Word boundaries are the same + as 'forward-word'. + +'backward-kill-word (M-)' + Kill the word behind point. Word boundaries are the same as + 'backward-word'. + +'unix-word-rubout (C-w)' + Kill the word behind point, using white space as a word boundary. + The killed text is saved on the kill-ring. + +'unix-filename-rubout ()' + Kill the word behind point, using white space and the slash + character as the word boundaries. The killed text is saved on the + kill-ring. + +'delete-horizontal-space ()' + Delete all spaces and tabs around point. By default, this is + unbound. + +'kill-region ()' + Kill the text in the current region. By default, this command is + unbound. + +'copy-region-as-kill ()' + Copy the text in the region to the kill buffer, so it can be yanked + right away. By default, this command is unbound. + +'copy-backward-word ()' + Copy the word before point to the kill buffer. The word boundaries + are the same as 'backward-word'. By default, this command is + unbound. + +'copy-forward-word ()' + Copy the word following point to the kill buffer. The word + boundaries are the same as 'forward-word'. By default, this + command is unbound. + +'yank (C-y)' + Yank the top of the kill ring into the buffer at point. + +'yank-pop (M-y)' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is 'yank' or 'yank-pop'. + + +File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands + +32.4.5 Specifying Numeric Arguments +----------------------------------- + +'digit-argument (M-0, M-1, ... M--)' + Add this digit to the argument already accumulating, or start a new + argument. 'M--' starts a negative argument. + +'universal-argument ()' + This is another way to specify an argument. If this command is + followed by one or more digits, optionally with a leading minus + sign, those digits define the argument. If the command is followed + by digits, executing 'universal-argument' again ends the numeric + argument, but is otherwise ignored. As a special case, if this + command is immediately followed by a character that is neither a + digit or minus sign, the argument count for the next command is + multiplied by four. The argument count is initially one, so + executing this function the first time makes the argument count + four, a second time makes the argument count sixteen, and so on. + By default, this is not bound to a key. + + +File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands + +32.4.6 Letting Readline Type For You +------------------------------------ + +'complete ()' + Attempt to perform completion on the text before point. The actual + completion performed is application-specific. The default is + filename completion. + +'possible-completions (M-?)' + List the possible completions of the text before point. When + displaying completions, Readline sets the number of columns used + for display to the value of 'completion-display-width', the value + of the environment variable 'COLUMNS', or the screen width, in that + order. + +'insert-completions (M-*)' + Insert all completions of the text before point that would have + been generated by 'possible-completions'. + +'menu-complete ()' + Similar to 'complete', but replaces the word to be completed with a + single match from the list of possible completions. Repeated + execution of 'menu-complete' steps through the list of possible + completions, inserting each match in turn. At the end of the list + of completions, the bell is rung (subject to the setting of + 'bell-style') and the original text is restored. An argument of N + moves N positions forward in the list of matches; a negative + argument may be used to move backward through the list. This + command is intended to be bound to , but is unbound by + default. + +'menu-complete-backward ()' + Identical to 'menu-complete', but moves backward through the list + of possible completions, as if 'menu-complete' had been given a + negative argument. + +'delete-char-or-list ()' + Deletes the character under the cursor if not at the beginning or + end of the line (like 'delete-char'). If at the end of the line, + behaves identically to 'possible-completions'. This command is + unbound by default. + + +File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands + +32.4.7 Keyboard Macros +---------------------- + +'start-kbd-macro (C-x ()' + Begin saving the characters typed into the current keyboard macro. + +'end-kbd-macro (C-x ))' + Stop saving the characters typed into the current keyboard macro + and save the definition. + +'call-last-kbd-macro (C-x e)' + Re-execute the last keyboard macro defined, by making the + characters in the macro appear as if typed at the keyboard. + + +File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands + +32.4.8 Some Miscellaneous Commands +---------------------------------- + +'re-read-init-file (C-x C-r)' + Read in the contents of the INPUTRC file, and incorporate any + bindings or variable assignments found there. + +'abort (C-g)' + Abort the current editing command and ring the terminal's bell + (subject to the setting of 'bell-style'). + +'do-uppercase-version (M-a, M-b, M-X, ...)' + If the metafied character X is lowercase, run the command that is + bound to the corresponding uppercase character. + +'prefix-meta ()' + Metafy the next character typed. This is for keyboards without a + meta key. Typing ' f' is equivalent to typing 'M-f'. + +'undo (C-_ or C-x C-u)' + Incremental undo, separately remembered for each line. + +'revert-line (M-r)' + Undo all changes made to this line. This is like executing the + 'undo' command enough times to get back to the beginning. + +'tilde-expand (M-~)' + Perform tilde expansion on the current word. + +'set-mark (C-@)' + Set the mark to the point. If a numeric argument is supplied, the + mark is set to that position. + +'exchange-point-and-mark (C-x C-x)' + Swap the point with the mark. The current cursor position is set + to the saved position, and the old cursor position is saved as the + mark. + +'character-search (C-])' + A character is read and point is moved to the next occurrence of + that character. A negative count searches for previous + occurrences. + +'character-search-backward (M-C-])' + A character is read and point is moved to the previous occurrence + of that character. A negative count searches for subsequent + occurrences. + +'skip-csi-sequence ()' + Read enough characters to consume a multi-key sequence such as + those defined for keys like Home and End. Such sequences begin + with a Control Sequence Indicator (CSI), usually ESC-[. If this + sequence is bound to "\e[", keys producing such sequences will have + no effect unless explicitly bound to a readline command, instead of + inserting stray characters into the editing buffer. This is + unbound by default, but usually bound to ESC-[. + +'insert-comment (M-#)' + Without a numeric argument, the value of the 'comment-begin' + variable is inserted at the beginning of the current line. If a + numeric argument is supplied, this command acts as a toggle: if the + characters at the beginning of the line do not match the value of + 'comment-begin', the value is inserted, otherwise the characters in + 'comment-begin' are deleted from the beginning of the line. In + either case, the line is accepted as if a newline had been typed. + +'dump-functions ()' + Print all of the functions and their key bindings to the Readline + output stream. If a numeric argument is supplied, the output is + formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +'dump-variables ()' + Print all of the settable variables and their values to the + Readline output stream. If a numeric argument is supplied, the + output is formatted in such a way that it can be made part of an + INPUTRC file. This command is unbound by default. + +'dump-macros ()' + Print all of the Readline key sequences bound to macros and the + strings they output. If a numeric argument is supplied, the output + is formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +'emacs-editing-mode (C-e)' + When in 'vi' command mode, this causes a switch to 'emacs' editing + mode. + +'vi-editing-mode (M-C-j)' + When in 'emacs' editing mode, this causes a switch to 'vi' editing + mode. + + +File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing + +32.5 Readline vi Mode +===================== + +While the Readline library does not have a full set of 'vi' editing +functions, it does contain enough to allow simple editing of the line. +The Readline 'vi' mode behaves as specified in the POSIX standard. + + In order to switch interactively between 'emacs' and 'vi' editing +modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi' +mode and to vi-editing-mode in 'emacs' mode). The Readline default is +'emacs' mode. + + When you enter a line in 'vi' mode, you are already placed in +'insertion' mode, as if you had typed an 'i'. Pressing switches +you into 'command' mode, where you can edit the text of the line with +the standard 'vi' movement keys, move to previous history lines with 'k' +and subsequent lines with 'j', and so forth. + + +File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top + +33 Using History Interactively +****************************** + +This chapter describes how to use the GNU History Library interactively, +from a user's standpoint. It should be considered a user's guide. For +information on using the GNU History Library in your own programs, *note +(history)Programming with GNU History::. + +* Menu: + +* History Interaction:: What it feels like using History as a user. + + +File: gdb.info, Node: History Interaction, Up: Using History Interactively + +33.1 History Expansion +====================== + +The History library provides a history expansion feature that is similar +to the history expansion provided by 'csh'. This section describes the +syntax used to manipulate the history information. + + History expansions introduce words from the history list into the +input stream, making it easy to repeat commands, insert the arguments to +a previous command into the current input line, or fix errors in +previous commands quickly. + + History expansion takes place in two parts. The first is to +determine which line from the history list should be used during +substitution. The second is to select portions of that line for +inclusion into the current one. The line selected from the history is +called the "event", and the portions of that line that are acted upon +are called "words". Various "modifiers" are available to manipulate the +selected words. The line is broken into words in the same fashion that +Bash does, so that several words surrounded by quotes are considered one +word. History expansions are introduced by the appearance of the +history expansion character, which is '!' by default. + +* Menu: + +* Event Designators:: How to specify which history line to use. +* Word Designators:: Specifying which words are of interest. +* Modifiers:: Modifying the results of substitution. + + +File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction + +33.1.1 Event Designators +------------------------ + +An event designator is a reference to a command line entry in the +history list. Unless the reference is absolute, events are relative to +the current position in the history list. + +'!' + Start a history substitution, except when followed by a space, tab, + the end of the line, or '='. + +'!N' + Refer to command line N. + +'!-N' + Refer to the command N lines back. + +'!!' + Refer to the previous command. This is a synonym for '!-1'. + +'!STRING' + Refer to the most recent command preceding the current position in + the history list starting with STRING. + +'!?STRING[?]' + Refer to the most recent command preceding the current position in + the history list containing STRING. The trailing '?' may be + omitted if the STRING is followed immediately by a newline. + +'^STRING1^STRING2^' + Quick Substitution. Repeat the last command, replacing STRING1 + with STRING2. Equivalent to '!!:s/STRING1/STRING2/'. + +'!#' + The entire command line typed so far. + + +File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction + +33.1.2 Word Designators +----------------------- + +Word designators are used to select desired words from the event. A ':' +separates the event specification from the word designator. It may be +omitted if the word designator begins with a '^', '$', '*', '-', or '%'. +Words are numbered from the beginning of the line, with the first word +being denoted by 0 (zero). Words are inserted into the current line +separated by single spaces. + + For example, + +'!!' + designates the preceding command. When you type this, the + preceding command is repeated in toto. + +'!!:$' + designates the last argument of the preceding command. This may be + shortened to '!$'. + +'!fi:2' + designates the second argument of the most recent command starting + with the letters 'fi'. + + Here are the word designators: + +'0 (zero)' + The '0'th word. For many applications, this is the command word. + +'N' + The Nth word. + +'^' + The first argument; that is, word 1. + +'$' + The last argument. + +'%' + The word matched by the most recent '?STRING?' search. + +'X-Y' + A range of words; '-Y' abbreviates '0-Y'. + +'*' + All of the words, except the '0'th. This is a synonym for '1-$'. + It is not an error to use '*' if there is just one word in the + event; the empty string is returned in that case. + +'X*' + Abbreviates 'X-$' + +'X-' + Abbreviates 'X-$' like 'X*', but omits the last word. + + If a word designator is supplied without an event specification, the +previous command is used as the event. + + +File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction + +33.1.3 Modifiers +---------------- + +After the optional word designator, you can add a sequence of one or +more of the following modifiers, each preceded by a ':'. + +'h' + Remove a trailing pathname component, leaving only the head. + +'t' + Remove all leading pathname components, leaving the tail. + +'r' + Remove a trailing suffix of the form '.SUFFIX', leaving the + basename. + +'e' + Remove all but the trailing suffix. + +'p' + Print the new command but do not execute it. + +'s/OLD/NEW/' + Substitute NEW for the first occurrence of OLD in the event line. + Any delimiter may be used in place of '/'. The delimiter may be + quoted in OLD and NEW with a single backslash. If '&' appears in + NEW, it is replaced by OLD. A single backslash will quote the '&'. + The final delimiter is optional if it is the last character on the + input line. + +'&' + Repeat the previous substitution. + +'g' +'a' + Cause changes to be applied over the entire event line. Used in + conjunction with 's', as in 'gs/OLD/NEW/', or with '&'. + +'G' + Apply the following 's' modifier once to each word in the event. + + +File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top + +Appendix A In Memoriam +********************** + +The GDB project mourns the loss of the following long-time contributors: + +'Fred Fish' + Fred was a long-standing contributor to GDB (1991-2006), and to + Free Software in general. Outside of GDB, he was known in the + Amiga world for his series of Fish Disks, and the GeekGadget + project. + +'Michael Snyder' + Michael was one of the Global Maintainers of the GDB project, with + contributions recorded as early as 1996, until 2011. In addition + to his day to day participation, he was a large driving force + behind adding Reverse Debugging to GDB. + + Beyond their technical contributions to the project, they were also +enjoyable members of the Free Software Community. We will miss them. + + +File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top + +Appendix B Formatting Documentation +*********************************** + +The GDB 4 release includes an already-formatted reference card, ready +for printing with PostScript or Ghostscript, in the 'gdb' subdirectory +of the main source directory(1). If you can use PostScript or +Ghostscript with your printer, you can print the reference card +immediately with 'refcard.ps'. + + The release also includes the source for the reference card. You can +format it, using TeX, by typing: + + make refcard.dvi + + The GDB reference card is designed to print in "landscape" mode on US +"letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches +high. You will need to specify this form of printing as an option to +your DVI output program. + + All the documentation for GDB comes as part of the machine-readable +distribution. The documentation is written in Texinfo format, which is +a documentation system that uses a single source file to produce both +on-line information and a printed manual. You can use one of the Info +formatting commands to create the on-line version of the documentation +and TeX (or 'texi2roff') to typeset the printed version. + + GDB includes an already formatted copy of the on-line Info version of +this manual in the 'gdb' subdirectory. The main Info file is +'gdb-7.7.1/gdb/gdb.info', and it refers to subordinate files matching +'gdb.info*' in the same directory. If necessary, you can print out +these files, or read them with any editor; but they are easier to read +using the 'info' subsystem in GNU Emacs or the standalone 'info' +program, available as part of the GNU Texinfo distribution. + + If you want to format these Info files yourself, you need one of the +Info formatting programs, such as 'texinfo-format-buffer' or 'makeinfo'. + + If you have 'makeinfo' installed, and are in the top level GDB source +directory ('gdb-7.7.1', in the case of version 7.7.1), you can make the +Info file by typing: + + cd gdb + make gdb.info + + If you want to typeset and print copies of this manual, you need TeX, +a program to print its DVI output files, and 'texinfo.tex', the Texinfo +definitions file. + + TeX is a typesetting program; it does not print files directly, but +produces output files called DVI files. To print a typeset document, +you need a program to print DVI files. If your system has TeX +installed, chances are it has such a program. The precise command to +use depends on your system; 'lpr -d' is common; another (for PostScript +devices) is 'dvips'. The DVI print command may require a file name +without any extension or a '.dvi' extension. + + TeX also requires a macro definitions file called 'texinfo.tex'. +This file tells TeX how to typeset a document written in Texinfo format. +On its own, TeX cannot either read or typeset a Texinfo file. +'texinfo.tex' is distributed with GDB and is located in the +'gdb-VERSION-NUMBER/texinfo' directory. + + If you have TeX and a DVI printer program installed, you can typeset +and print this manual. First switch to the 'gdb' subdirectory of the +main source directory (for example, to 'gdb-7.7.1/gdb') and type: + + make gdb.dvi + + Then give 'gdb.dvi' to your DVI printing program. + + ---------- Footnotes ---------- + + (1) In 'gdb-7.7.1/gdb/refcard.ps' of the version 7.7.1 release. + + +File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top + +Appendix C Installing GDB +************************* + +* Menu: + +* Requirements:: Requirements for building GDB +* Running Configure:: Invoking the GDB 'configure' script +* Separate Objdir:: Compiling GDB in another directory +* Config Names:: Specifying names for hosts and targets +* Configure Options:: Summary of options for configure +* System-wide configuration:: Having a system-wide init file + + +File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB + +C.1 Requirements for Building GDB +================================= + +Building GDB requires various tools and packages to be available. Other +packages will be used only if they are found. + +Tools/Packages Necessary for Building GDB +========================================= + +ISO C90 compiler + GDB is written in ISO C90. It should be buildable with any working + C90 compiler, e.g. GCC. + +Tools/Packages Optional for Building GDB +======================================== + +Expat + GDB can use the Expat XML parsing library. This library may be + included with your operating system distribution; if it is not, you + can get the latest version from . + The 'configure' script will search for this library in several + standard locations; if it is installed in an unusual path, you can + use the '--with-libexpat-prefix' option to specify its location. + + Expat is used for: + + * Remote protocol memory maps (*note Memory Map Format::) + * Target descriptions (*note Target Descriptions::) + * Remote shared library lists (*Note Library List Format::, or + alternatively *note Library List Format for SVR4 Targets::) + * MS-Windows shared libraries (*note Shared Libraries::) + * Traceframe info (*note Traceframe Info Format::) + * Branch trace (*note Branch Trace Format::) + +zlib + GDB will use the 'zlib' library, if available, to read compressed + debug sections. Some linkers, such as GNU gold, are capable of + producing binaries with compressed debug sections. If GDB is + compiled with 'zlib', it will be able to read the debug information + in such binaries. + + The 'zlib' library is likely included with your operating system + distribution; if it is not, you can get the latest version from + . + +iconv + GDB's features related to character sets (*note Character Sets::) + require a functioning 'iconv' implementation. If you are on a GNU + system, then this is provided by the GNU C Library. Some other + systems also provide a working 'iconv'. + + If GDB is using the 'iconv' program which is installed in a + non-standard place, you will need to tell GDB where to find it. + This is done with '--with-iconv-bin' which specifies the directory + that contains the 'iconv' program. + + On systems without 'iconv', you can install GNU Libiconv. If you + have previously installed Libiconv, you can use the + '--with-libiconv-prefix' option to configure. + + GDB's top-level 'configure' and 'Makefile' will arrange to build + Libiconv if a directory named 'libiconv' appears in the top-most + source directory. If Libiconv is built this way, and if the + operating system does not provide a suitable 'iconv' + implementation, then the just-built library will automatically be + used by GDB. One easy way to set this up is to download GNU + Libiconv, unpack it, and then rename the directory holding the + Libiconv source code to 'libiconv'. + + +File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB + +C.2 Invoking the GDB 'configure' Script +======================================= + +GDB comes with a 'configure' script that automates the process of +preparing GDB for installation; you can then use 'make' to build the +'gdb' program. + + The GDB distribution includes all the source code you need for GDB in +a single directory, whose name is usually composed by appending the +version number to 'gdb'. + + For example, the GDB version 7.7.1 distribution is in the 'gdb-7.7.1' +directory. That directory contains: + +'gdb-7.7.1/configure (and supporting files)' + script for configuring GDB and all its supporting libraries + +'gdb-7.7.1/gdb' + the source specific to GDB itself + +'gdb-7.7.1/bfd' + source for the Binary File Descriptor library + +'gdb-7.7.1/include' + GNU include files + +'gdb-7.7.1/libiberty' + source for the '-liberty' free software library + +'gdb-7.7.1/opcodes' + source for the library of opcode tables and disassemblers + +'gdb-7.7.1/readline' + source for the GNU command-line interface + +'gdb-7.7.1/glob' + source for the GNU filename pattern-matching subroutine + +'gdb-7.7.1/mmalloc' + source for the GNU memory-mapped malloc package + + The simplest way to configure and build GDB is to run 'configure' +from the 'gdb-VERSION-NUMBER' source directory, which in this example is +the 'gdb-7.7.1' directory. + + First switch to the 'gdb-VERSION-NUMBER' source directory if you are +not already in it; then run 'configure'. Pass the identifier for the +platform on which GDB will run as an argument. + + For example: + + cd gdb-7.7.1 + ./configure HOST + make + +where HOST is an identifier such as 'sun4' or 'decstation', that +identifies the platform where GDB will run. (You can often leave off +HOST; 'configure' tries to guess the correct value by examining your +system.) + + Running 'configure HOST' and then running 'make' builds the 'bfd', +'readline', 'mmalloc', and 'libiberty' libraries, then 'gdb' itself. +The configured source files, and the binaries, are left in the +corresponding source directories. + + 'configure' is a Bourne-shell ('/bin/sh') script; if your system does +not recognize this automatically when you run a different shell, you may +need to run 'sh' on it explicitly: + + sh configure HOST + + If you run 'configure' from a directory that contains source +directories for multiple libraries or programs, such as the 'gdb-7.7.1' +source directory for version 7.7.1, 'configure' creates configuration +files for every directory level underneath (unless you tell it not to, +with the '--norecursion' option). + + You should run the 'configure' script from the top directory in the +source tree, the 'gdb-VERSION-NUMBER' directory. If you run 'configure' +from one of the subdirectories, you will configure only that +subdirectory. That is usually not what you want. In particular, if you +run the first 'configure' from the 'gdb' subdirectory of the +'gdb-VERSION-NUMBER' directory, you will omit the configuration of +'bfd', 'readline', and other sibling directories of the 'gdb' +subdirectory. This leads to build errors about missing include files +such as 'bfd/bfd.h'. + + You can install 'gdb' anywhere; it has no hardwired paths. However, +you should make sure that the shell on your path (named by the 'SHELL' +environment variable) is publicly readable. Remember that GDB uses the +shell to start your program--some systems refuse to let GDB debug child +processes whose programs are not readable. + + +File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB + +C.3 Compiling GDB in Another Directory +====================================== + +If you want to run GDB versions for several host or target machines, you +need a different 'gdb' compiled for each combination of host and target. +'configure' is designed to make this easy by allowing you to generate +each configuration in a separate subdirectory, rather than in the source +directory. If your 'make' program handles the 'VPATH' feature (GNU +'make' does), running 'make' in each of these directories builds the +'gdb' program specified there. + + To build 'gdb' in a separate directory, run 'configure' with the +'--srcdir' option to specify where to find the source. (You also need +to specify a path to find 'configure' itself from your working +directory. If the path to 'configure' would be the same as the argument +to '--srcdir', you can leave out the '--srcdir' option; it is assumed.) + + For example, with version 7.7.1, you can build GDB in a separate +directory for a Sun 4 like this: + + cd gdb-7.7.1 + mkdir ../gdb-sun4 + cd ../gdb-sun4 + ../gdb-7.7.1/configure sun4 + make + + When 'configure' builds a configuration using a remote source +directory, it creates a tree for the binaries with the same structure +(and using the same names) as the tree under the source directory. In +the example, you'd find the Sun 4 library 'libiberty.a' in the directory +'gdb-sun4/libiberty', and GDB itself in 'gdb-sun4/gdb'. + + Make sure that your path to the 'configure' script has just one +instance of 'gdb' in it. If your path to 'configure' looks like +'../gdb-7.7.1/gdb/configure', you are configuring only one subdirectory +of GDB, not the whole package. This leads to build errors about missing +include files such as 'bfd/bfd.h'. + + One popular reason to build several GDB configurations in separate +directories is to configure GDB for cross-compiling (where GDB runs on +one machine--the "host"--while debugging programs that run on another +machine--the "target"). You specify a cross-debugging target by giving +the '--target=TARGET' option to 'configure'. + + When you run 'make' to build a program or library, you must run it in +a configured directory--whatever directory you were in when you called +'configure' (or one of its subdirectories). + + The 'Makefile' that 'configure' generates in each source directory +also runs recursively. If you type 'make' in a source directory such as +'gdb-7.7.1' (or in a separate configured directory configured with +'--srcdir=DIRNAME/gdb-7.7.1'), you will build all the required +libraries, and then build GDB. + + When you have multiple hosts or targets configured in separate +directories, you can run 'make' on them in parallel (for example, if +they are NFS-mounted on each of the hosts); they will not interfere with +each other. + + +File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB + +C.4 Specifying Names for Hosts and Targets +========================================== + +The specifications used for hosts and targets in the 'configure' script +are based on a three-part naming scheme, but some short predefined +aliases are also supported. The full naming scheme encodes three pieces +of information in the following pattern: + + ARCHITECTURE-VENDOR-OS + + For example, you can use the alias 'sun4' as a HOST argument, or as +the value for TARGET in a '--target=TARGET' option. The equivalent full +name is 'sparc-sun-sunos4'. + + The 'configure' script accompanying GDB does not provide any query +facility to list all supported host and target names or aliases. +'configure' calls the Bourne shell script 'config.sub' to map +abbreviations to full names; you can read the script, if you wish, or +you can use it to test your guesses on abbreviations--for example: + + % sh config.sub i386-linux + i386-pc-linux-gnu + % sh config.sub alpha-linux + alpha-unknown-linux-gnu + % sh config.sub hp9k700 + hppa1.1-hp-hpux + % sh config.sub sun4 + sparc-sun-sunos4.1.1 + % sh config.sub sun3 + m68k-sun-sunos4.1.1 + % sh config.sub i986v + Invalid configuration `i986v': machine `i986v' not recognized + +'config.sub' is also distributed in the GDB source directory +('gdb-7.7.1', for version 7.7.1). + + +File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB + +C.5 'configure' Options +======================= + +Here is a summary of the 'configure' options and arguments that are most +often useful for building GDB. 'configure' also has several other +options not listed here. *note (configure.info)What Configure Does::, +for a full explanation of 'configure'. + + configure [--help] + [--prefix=DIR] + [--exec-prefix=DIR] + [--srcdir=DIRNAME] + [--norecursion] [--rm] + [--target=TARGET] + HOST + +You may introduce options with a single '-' rather than '--' if you +prefer; but you may abbreviate option names if you use '--'. + +'--help' + Display a quick summary of how to invoke 'configure'. + +'--prefix=DIR' + Configure the source to install programs and files under directory + 'DIR'. + +'--exec-prefix=DIR' + Configure the source to install programs under directory 'DIR'. + +'--srcdir=DIRNAME' + *Warning: using this option requires GNU 'make', or another 'make' + that implements the 'VPATH' feature.* + Use this option to make configurations in directories separate from + the GDB source directories. Among other things, you can use this + to build (or maintain) several configurations simultaneously, in + separate directories. 'configure' writes configuration-specific + files in the current directory, but arranges for them to use the + source in the directory DIRNAME. 'configure' creates directories + under the working directory in parallel to the source directories + below DIRNAME. + +'--norecursion' + Configure only the directory level where 'configure' is executed; + do not propagate configuration to subdirectories. + +'--target=TARGET' + Configure GDB for cross-debugging programs running on the specified + TARGET. Without this option, GDB is configured to debug programs + that run on the same machine (HOST) as GDB itself. + + There is no convenient way to generate a list of all available + targets. + +'HOST ...' + Configure GDB to run on the specified HOST. + + There is no convenient way to generate a list of all available + hosts. + + There are many other options available as well, but they are +generally needed for special purposes only. + + +File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB + +C.6 System-wide configuration and settings +========================================== + +GDB can be configured to have a system-wide init file; this file will be +read and executed at startup (*note What GDB does during startup: +Startup.). + + Here is the corresponding configure option: + +'--with-system-gdbinit=FILE' + Specify that the default location of the system-wide init file is + FILE. + + If GDB has been configured with the option '--prefix=$prefix', it may +be subject to relocation. Two possible cases: + + * If the default location of this init file contains '$prefix', it + will be subject to relocation. Suppose that the configure options + are '--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit'; + if GDB is moved from '$prefix' to '$install', the system init file + is looked for as '$install/etc/gdbinit' instead of + '$prefix/etc/gdbinit'. + + * By contrast, if the default location does not contain the prefix, + it will not be relocated. E.g. if GDB has been configured with + '--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit', + then GDB will always look for '/usr/share/gdb/gdbinit', wherever + GDB is installed. + + If the configured location of the system-wide init file (as given by +the '--with-system-gdbinit' option at configure time) is in the +data-directory (as specified by '--with-gdb-datadir' at configure time) +or in one of its subdirectories, then GDB will look for the system-wide +init file in the directory specified by the '--data-directory' +command-line option. Note that the system-wide init file is only read +once, during GDB initialization. If the data-directory is changed after +GDB has started with the 'set data-directory' command, the file will not +be reread. + +* Menu: + +* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts + + +File: gdb.info, Node: System-wide Configuration Scripts, Up: System-wide configuration + +C.6.1 Installed System-wide Configuration Scripts +------------------------------------------------- + +The 'system-gdbinit' directory, located inside the data-directory (as +specified by '--with-gdb-datadir' at configure time) contains a number +of scripts which can be used as system-wide init files. To +automatically source those scripts at startup, GDB should be configured +with '--with-system-gdbinit'. Otherwise, any user should be able to +source them by hand as needed. + + The following scripts are currently available: + + * 'elinos.py' This script is useful when debugging a program on an + ELinOS target. It takes advantage of the environment variables + defined in a standard ELinOS environment in order to determine the + location of the system shared libraries, and then sets the + 'solib-absolute-prefix' and 'solib-search-path' variables + appropriately. + + * 'wrs-linux.py' This script is useful when debugging a program on a + target running Wind River Linux. It expects the 'ENV_PREFIX' to be + set to the host-side sysroot used by the target system. + + +File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top + +Appendix D Maintenance Commands +******************************* + +In addition to commands intended for GDB users, GDB includes a number of +commands intended for GDB developers, that are not documented elsewhere +in this manual. These commands are provided here for reference. (For +commands that turn on debugging messages, see *note Debugging Output::.) + +'maint agent [-at LOCATION,] EXPRESSION' +'maint agent-eval [-at LOCATION,] EXPRESSION' + Translate the given EXPRESSION into remote agent bytecodes. This + command is useful for debugging the Agent Expression mechanism + (*note Agent Expressions::). The 'agent' version produces an + expression useful for data collection, such as by tracepoints, + while 'maint agent-eval' produces an expression that evaluates + directly to a result. For instance, a collection expression for + 'globa + globb' will include bytecodes to record four bytes of + memory at each of the addresses of 'globa' and 'globb', while + discarding the result of the addition, while an evaluation + expression will do the addition and return the sum. If '-at' is + given, generate remote agent bytecode for LOCATION. If not, + generate remote agent bytecode for current frame PC address. + +'maint agent-printf FORMAT,EXPR,...' + Translate the given format string and list of argument expressions + into remote agent bytecodes and display them as a disassembled + list. This command is useful for debugging the agent version of + dynamic printf (*note Dynamic Printf::). + +'maint info breakpoints' + Using the same format as 'info breakpoints', display both the + breakpoints you've set explicitly, and those GDB is using for + internal purposes. Internal breakpoints are shown with negative + breakpoint numbers. The type column identifies what kind of + breakpoint is shown: + + 'breakpoint' + Normal, explicitly set breakpoint. + + 'watchpoint' + Normal, explicitly set watchpoint. + + 'longjmp' + Internal breakpoint, used to handle correctly stepping through + 'longjmp' calls. + + 'longjmp resume' + Internal breakpoint at the target of a 'longjmp'. + + 'until' + Temporary internal breakpoint used by the GDB 'until' command. + + 'finish' + Temporary internal breakpoint used by the GDB 'finish' + command. + + 'shlib events' + Shared library events. + +'maint info bfds' + This prints information about each 'bfd' object that is known to + GDB. *Note BFD: (bfd)Top. + +'set displaced-stepping' +'show displaced-stepping' + Control whether or not GDB will do "displaced stepping" if the + target supports it. Displaced stepping is a way to single-step + over breakpoints without removing them from the inferior, by + executing an out-of-line copy of the instruction that was + originally at the breakpoint location. It is also known as + out-of-line single-stepping. + + 'set displaced-stepping on' + If the target architecture supports it, GDB will use displaced + stepping to step over breakpoints. + + 'set displaced-stepping off' + GDB will not use displaced stepping to step over breakpoints, + even if such is supported by the target architecture. + + 'set displaced-stepping auto' + This is the default mode. GDB will use displaced stepping + only if non-stop mode is active (*note Non-Stop Mode::) and + the target architecture supports displaced stepping. + +'maint check-psymtabs' + Check the consistency of currently expanded psymtabs versus + symtabs. Use this to check, for example, whether a symbol is in + one but not the other. + +'maint check-symtabs' + Check the consistency of currently expanded symtabs. + +'maint expand-symtabs [REGEXP]' + Expand symbol tables. If REGEXP is specified, only expand symbol + tables for file names matching REGEXP. + +'maint cplus first_component NAME' + Print the first C++ class/namespace component of NAME. + +'maint cplus namespace' + Print the list of possible C++ namespaces. + +'maint demangle NAME' + Demangle a C++ or Objective-C mangled NAME. + +'maint deprecate COMMAND [REPLACEMENT]' +'maint undeprecate COMMAND' + Deprecate or undeprecate the named COMMAND. Deprecated commands + cause GDB to issue a warning when you use them. The optional + argument REPLACEMENT says which newer command should be used in + favor of the deprecated one; if it is given, GDB will mention the + replacement as part of the warning. + +'maint dump-me' + Cause a fatal signal in the debugger and force it to dump its core. + This is supported only on systems which support aborting a program + with the 'SIGQUIT' signal. + +'maint internal-error [MESSAGE-TEXT]' +'maint internal-warning [MESSAGE-TEXT]' + Cause GDB to call the internal function 'internal_error' or + 'internal_warning' and hence behave as though an internal error or + internal warning has been detected. In addition to reporting the + internal problem, these functions give the user the opportunity to + either quit GDB or create a core file of the current GDB session. + + These commands take an optional parameter MESSAGE-TEXT that is used + as the text of the error or warning message. + + Here's an example of using 'internal-error': + + (gdb) maint internal-error testing, 1, 2 + .../maint.c:121: internal-error: testing, 1, 2 + A problem internal to GDB has been detected. Further + debugging may prove unreliable. + Quit this debugging session? (y or n) n + Create a core file? (y or n) n + (gdb) + +'maint set internal-error ACTION [ask|yes|no]' +'maint show internal-error ACTION' +'maint set internal-warning ACTION [ask|yes|no]' +'maint show internal-warning ACTION' + When GDB reports an internal problem (error or warning) it gives + the user the opportunity to both quit GDB and create a core file of + the current GDB session. These commands let you override the + default behaviour for each particular ACTION, described in the + table below. + + 'quit' + You can specify that GDB should always (yes) or never (no) + quit. The default is to ask the user what to do. + + 'corefile' + You can specify that GDB should always (yes) or never (no) + create a core file. The default is to ask the user what to + do. + +'maint packet TEXT' + If GDB is talking to an inferior via the serial protocol, then this + command sends the string TEXT to the inferior, and displays the + response packet. GDB supplies the initial '$' character, the + terminating '#' character, and the checksum. + +'maint print architecture [FILE]' + Print the entire architecture configuration. The optional argument + FILE names the file where the output goes. + +'maint print c-tdesc' + Print the current target description (*note Target Descriptions::) + as a C source file. The created source file can be used in GDB + when an XML parser is not available to parse the description. + +'maint print dummy-frames' + Prints the contents of GDB's internal dummy-frame stack. + + (gdb) b add + ... + (gdb) print add(2,3) + Breakpoint 2, add (a=2, b=3) at ... + 58 return (a + b); + The program being debugged stopped while in a function called from GDB. + ... + (gdb) maint print dummy-frames + 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 + top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c} + call_lo=0x01014000 call_hi=0x01014001 + (gdb) + + Takes an optional file parameter. + +'maint print registers [FILE]' +'maint print raw-registers [FILE]' +'maint print cooked-registers [FILE]' +'maint print register-groups [FILE]' +'maint print remote-registers [FILE]' + Print GDB's internal register data structures. + + The command 'maint print raw-registers' includes the contents of + the raw register cache; the command 'maint print cooked-registers' + includes the (cooked) value of all registers, including registers + which aren't available on the target nor visible to user; the + command 'maint print register-groups' includes the groups that each + register is a member of; and the command 'maint print + remote-registers' includes the remote target's register numbers and + offsets in the 'G' packets. + + These commands take an optional parameter, a file name to which to + write the information. + +'maint print reggroups [FILE]' + Print GDB's internal register group data structures. The optional + argument FILE tells to what file to write the information. + + The register groups info looks like this: + + (gdb) maint print reggroups + Group Type + general user + float user + all user + vector user + system user + save internal + restore internal + +'flushregs' + This command forces GDB to flush its internal register cache. + +'maint print objfiles [REGEXP]' + Print a dump of all known object files. If REGEXP is specified, + only print object files whose names match REGEXP. For each object + file, this command prints its name, address in memory, and all of + its psymtabs and symtabs. + +'maint print section-scripts [REGEXP]' + Print a dump of scripts specified in the '.debug_gdb_section' + section. If REGEXP is specified, only print scripts loaded by + object files matching REGEXP. For each script, this command prints + its name as specified in the objfile, and the full path if known. + *Note dotdebug_gdb_scripts section::. + +'maint print statistics' + This command prints, for each object file in the program, various + data about that object file followed by the byte cache ("bcache") + statistics for the object file. The objfile data includes the + number of minimal, partial, full, and stabs symbols, the number of + types defined by the objfile, the number of as yet unexpanded psym + tables, the number of line tables and string tables, and the amount + of memory used by the various tables. The bcache statistics + include the counts, sizes, and counts of duplicates of all and + unique objects, max, average, and median entry size, total memory + used and its overhead and savings, and various measures of the hash + table size and chain lengths. + +'maint print target-stack' + A "target" is an interface between the debugger and a particular + kind of file or process. Targets can be stacked in "strata", so + that more than one target can potentially respond to a request. In + particular, memory accesses will walk down the stack of targets + until they find a target that is interested in handling that + particular address. + + This command prints a short description of each layer that was + pushed on the "target stack", starting from the top layer down to + the bottom one. + +'maint print type EXPR' + Print the type chain for a type specified by EXPR. The argument + can be either a type name or a symbol. If it is a symbol, the type + of that symbol is described. The type chain produced by this + command is a recursive definition of the data type as stored in + GDB's data structures, including its flags and contained types. + +'maint set dwarf2 always-disassemble' +'maint show dwarf2 always-disassemble' + Control the behavior of 'info address' when using DWARF debugging + information. + + The default is 'off', which means that GDB should try to describe a + variable's location in an easily readable format. When 'on', GDB + will instead display the DWARF location expression in an + assembly-like format. Note that some locations are too complex for + GDB to describe simply; in this case you will always see the + disassembly form. + + Here is an example of the resulting disassembly: + + (gdb) info addr argc + Symbol "argc" is a complex DWARF expression: + 1: DW_OP_fbreg 0 + + For more information on these expressions, see the DWARF standard + (http://www.dwarfstd.org/). + +'maint set dwarf2 max-cache-age' +'maint show dwarf2 max-cache-age' + Control the DWARF 2 compilation unit cache. + + In object files with inter-compilation-unit references, such as + those produced by the GCC option '-feliminate-dwarf2-dups', the + DWARF 2 reader needs to frequently refer to previously read + compilation units. This setting controls how long a compilation + unit will remain in the cache if it is not referenced. A higher + limit means that cached compilation units will be stored in memory + longer, and more total memory will be used. Setting it to zero + disables caching, which will slow down GDB startup, but reduce + memory consumption. + +'maint set profile' +'maint show profile' + Control profiling of GDB. + + Profiling will be disabled until you use the 'maint set profile' + command to enable it. When you enable profiling, the system will + begin collecting timing and execution count data; when you disable + profiling or exit GDB, the results will be written to a log file. + Remember that if you use profiling, GDB will overwrite the + profiling log file (often called 'gmon.out'). If you have a record + of important profiling data in a 'gmon.out' file, be sure to move + it to a safe location. + + Configuring with '--enable-profiling' arranges for GDB to be + compiled with the '-pg' compiler option. + +'maint set show-debug-regs' +'maint show show-debug-regs' + Control whether to show variables that mirror the hardware debug + registers. Use 'on' to enable, 'off' to disable. If enabled, the + debug registers values are shown when GDB inserts or removes a + hardware breakpoint or watchpoint, and when the inferior triggers a + hardware-assisted breakpoint or watchpoint. + +'maint set show-all-tib' +'maint show show-all-tib' + Control whether to show all non zero areas within a 1k block + starting at thread local base, when using the 'info w32 + thread-information-block' command. + +'maint set per-command' +'maint show per-command' + + GDB can display the resources used by each command. This is useful + in debugging performance problems. + + 'maint set per-command space [on|off]' + 'maint show per-command space' + Enable or disable the printing of the memory used by GDB for + each command. If enabled, GDB will display how much memory + each command took, following the command's own output. This + can also be requested by invoking GDB with the '--statistics' + command-line switch (*note Mode Options::). + + 'maint set per-command time [on|off]' + 'maint show per-command time' + Enable or disable the printing of the execution time of GDB + for each command. If enabled, GDB will display how much time + it took to execute each command, following the command's own + output. Both CPU time and wallclock time are printed. + Printing both is useful when trying to determine whether the + cost is CPU or, e.g., disk/network latency. Note that the CPU + time printed is for GDB only, it does not include the + execution time of the inferior because there's no mechanism + currently to compute how much time was spent by GDB and how + much time was spent by the program been debugged. This can + also be requested by invoking GDB with the '--statistics' + command-line switch (*note Mode Options::). + + 'maint set per-command symtab [on|off]' + 'maint show per-command symtab' + Enable or disable the printing of basic symbol table + statistics for each command. If enabled, GDB will display the + following information: + + a. number of symbol tables + b. number of primary symbol tables + c. number of blocks in the blockvector + +'maint space VALUE' + An alias for 'maint set per-command space'. A non-zero value + enables it, zero disables it. + +'maint time VALUE' + An alias for 'maint set per-command time'. A non-zero value + enables it, zero disables it. + +'maint translate-address [SECTION] ADDR' + Find the symbol stored at the location specified by the address + ADDR and an optional section name SECTION. If found, GDB prints + the name of the closest symbol and an offset from the symbol's + location to the specified address. This is similar to the 'info + address' command (*note Symbols::), except that this command also + allows to find symbols in other sections. + + If section was not specified, the section in which the symbol was + found is also printed. For dynamically linked executables, the + name of executable or shared library containing the symbol is + printed as well. + + The following command is useful for non-interactive invocations of +GDB, such as in the test suite. + +'set watchdog NSEC' + Set the maximum number of seconds GDB will wait for the target + operation to finish. If this time expires, GDB reports and error + and the command is aborted. + +'show watchdog' + Show the current setting of the target wait timeout. + + +File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top + +Appendix E GDB Remote Serial Protocol +************************************* + +* Menu: + +* Overview:: +* Packets:: +* Stop Reply Packets:: +* General Query Packets:: +* Architecture-Specific Protocol Details:: +* Tracepoint Packets:: +* Host I/O Packets:: +* Interrupts:: +* Notification Packets:: +* Remote Non-Stop:: +* Packet Acknowledgment:: +* Examples:: +* File-I/O Remote Protocol Extension:: +* Library List Format:: +* Library List Format for SVR4 Targets:: +* Memory Map Format:: +* Thread List Format:: +* Traceframe Info Format:: +* Branch Trace Format:: + + +File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol + +E.1 Overview +============ + +There may be occasions when you need to know something about the +protocol--for example, if there is only one serial port to your target +machine, you might want your program to do something special if it +recognizes a packet meant for GDB. + + In the examples below, '->' and '<-' are used to indicate transmitted +and received data, respectively. + + All GDB commands and responses (other than acknowledgments and +notifications, see *note Notification Packets::) are sent as a PACKET. +A PACKET is introduced with the character '$', the actual PACKET-DATA, +and the terminating character '#' followed by a two-digit CHECKSUM: + + $PACKET-DATA#CHECKSUM + +The two-digit CHECKSUM is computed as the modulo 256 sum of all +characters between the leading '$' and the trailing '#' (an eight bit +unsigned checksum). + + Implementors should note that prior to GDB 5.0 the protocol +specification also included an optional two-digit SEQUENCE-ID: + + $SEQUENCE-ID:PACKET-DATA#CHECKSUM + +That SEQUENCE-ID was appended to the acknowledgment. GDB has never +output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 must +not accept SEQUENCE-ID. + + When either the host or the target machine receives a packet, the +first response expected is an acknowledgment: either '+' (to indicate +the package was received correctly) or '-' (to request retransmission): + + -> $PACKET-DATA#CHECKSUM + <- + + + The '+'/'-' acknowledgments can be disabled once a connection is +established. *Note Packet Acknowledgment::, for details. + + The host (GDB) sends COMMANDs, and the target (the debugging stub +incorporated in your program) sends a RESPONSE. In the case of step and +continue COMMANDs, the response is only sent when the operation has +completed, and the target has again stopped all threads in all attached +processes. This is the default all-stop mode behavior, but the remote +protocol also supports GDB's non-stop execution mode; see *note Remote +Non-Stop::, for details. + + PACKET-DATA consists of a sequence of characters with the exception +of '#' and '$' (see 'X' packet for additional exceptions). + + Fields within the packet should be separated using ',' ';' or ':'. +Except where otherwise noted all numbers are represented in HEX with +leading zeros suppressed. + + Implementors should note that prior to GDB 5.0, the character ':' +could not appear as the third character in a packet (as it would +potentially conflict with the SEQUENCE-ID). + + Binary data in most packets is encoded either as two hexadecimal +digits per byte of binary data. This allowed the traditional remote +protocol to work over connections which were only seven-bit clean. Some +packets designed more recently assume an eight-bit clean connection, and +use a more efficient encoding to send and receive binary data. + + The binary data representation uses '7d' (ASCII '}') as an escape +character. Any escaped byte is transmitted as the escape character +followed by the original character XORed with '0x20'. For example, the +byte '0x7d' would be transmitted as the two bytes '0x7d 0x5d'. The +bytes '0x23' (ASCII '#'), '0x24' (ASCII '$'), and '0x7d' (ASCII '}') +must always be escaped. Responses sent by the stub must also escape +'0x2a' (ASCII '*'), so that it is not interpreted as the start of a +run-length encoded sequence (described next). + + Response DATA can be run-length encoded to save space. Run-length +encoding replaces runs of identical characters with one instance of the +repeated character, followed by a '*' and a repeat count. The repeat +count is itself sent encoded, to avoid binary characters in DATA: a +value of N is sent as 'N+29'. For a repeat count greater or equal to 3, +this produces a printable ASCII character, e.g. a space (ASCII code 32) +for a repeat count of 3. (This is because run-length encoding starts to +win for counts 3 or more.) Thus, for example, '0* ' is a run-length +encoding of "0000": the space character after '*' means repeat the +leading '0' '32 - 29 = 3' more times. + + The printable characters '#' and '$' or with a numeric value greater +than 126 must not be used. Runs of six repeats ('#') or seven repeats +('$') can be expanded using a repeat count of only five ('"'). For +example, '00000000' can be encoded as '0*"00'. + + The error response returned for some packets includes a two character +error number. That number is not well defined. + + For any COMMAND not supported by the stub, an empty response ('$#00') +should be returned. That way it is possible to extend the protocol. A +newer GDB can tell if a packet is supported based on that response. + + At a minimum, a stub is required to support the 'g' and 'G' commands +for register access, and the 'm' and 'M' commands for memory access. +Stubs that only control single-threaded targets can implement run +control with the 'c' (continue), and 's' (step) commands. Stubs that +support multi-threading targets should support the 'vCont' command. All +other commands are optional. + + +File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol + +E.2 Packets +=========== + +The following table provides a complete list of all currently defined +COMMANDs and their corresponding response DATA. *Note File-I/O Remote +Protocol Extension::, for details about the File I/O extension of the +remote protocol. + + Each packet's description has a template showing the packet's overall +syntax, followed by an explanation of the packet's meaning. We include +spaces in some of the templates for clarity; these are not part of the +packet's syntax. No GDB packet uses spaces to separate its components. +For example, a template like 'foo BAR BAZ' describes a packet beginning +with the three ASCII bytes 'foo', followed by a BAR, followed directly +by a BAZ. GDB does not transmit a space character between the 'foo' and +the BAR, or between the BAR and the BAZ. + + Several packets and replies include a THREAD-ID field to identify a +thread. Normally these are positive numbers with a target-specific +interpretation, formatted as big-endian hex strings. A THREAD-ID can +also be a literal '-1' to indicate all threads, or '0' to pick any +thread. + + In addition, the remote protocol supports a multiprocess feature in +which the THREAD-ID syntax is extended to optionally include both +process and thread ID fields, as 'pPID.TID'. The PID (process) and TID +(thread) components each have the format described above: a positive +number with target-specific interpretation formatted as a big-endian hex +string, literal '-1' to indicate all processes or threads +(respectively), or '0' to indicate an arbitrary process or thread. +Specifying just a process, as 'pPID', is equivalent to 'pPID.-1'. It is +an error to specify all processes but a specific thread, such as +'p-1.TID'. Note that the 'p' prefix is _not_ used for those packets and +replies explicitly documented to include a process ID, rather than a +THREAD-ID. + + The multiprocess THREAD-ID syntax extensions are only used if both +GDB and the stub report support for the 'multiprocess' feature using +'qSupported'. *Note multiprocess extensions::, for more information. + + Note that all packet forms beginning with an upper- or lower-case +letter, other than those described here, are reserved for future use. + + Here are the packet descriptions. + +'!' + Enable extended mode. In extended mode, the remote server is made + persistent. The 'R' packet is used to restart the program being + debugged. + + Reply: + 'OK' + The remote target both supports and has enabled extended mode. + +'?' + Indicate the reason the target halted. The reply is the same as + for step and continue. This packet has a special interpretation + when the target is in non-stop mode; see *note Remote Non-Stop::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'A ARGLEN,ARGNUM,ARG,...' + Initialized 'argv[]' array passed into program. ARGLEN specifies + the number of bytes in the hex encoded byte stream ARG. See + 'gdbserver' for more details. + + Reply: + 'OK' + The arguments were set. + 'E NN' + An error occurred. + +'b BAUD' + (Don't use this packet; its behavior is not well-defined.) Change + the serial line speed to BAUD. + + JTC: _When does the transport layer state change? When it's + received, or after the ACK is transmitted. In either case, there + are problems if the command or the acknowledgment packet is + dropped._ + + Stan: _If people really wanted to add something like this, and get + it working for the first time, they ought to modify ser-unix.c to + send some kind of out-of-band message to a specially-setup stub and + have the switch happen "in between" packets, so that from remote + protocol's point of view, nothing actually happened._ + +'B ADDR,MODE' + Set (MODE is 'S') or clear (MODE is 'C') a breakpoint at ADDR. + + Don't use this packet. Use the 'Z' and 'z' packets instead (*note + insert breakpoint or watchpoint packet::). + +'bc' + Backward continue. Execute the target system in reverse. No + parameter. *Note Reverse Execution::, for more information. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'bs' + Backward single step. Execute one instruction in reverse. No + parameter. *Note Reverse Execution::, for more information. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'c [ADDR]' + Continue. ADDR is address to resume. If ADDR is omitted, resume + at current address. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'C SIG[;ADDR]' + Continue with signal SIG (hex signal number). If ';ADDR' is + omitted, resume at same address. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'d' + Toggle debug flag. + + Don't use this packet; instead, define a general set packet (*note + General Query Packets::). + +'D' +'D;PID' + The first form of the packet is used to detach GDB from the remote + system. It is sent to the remote target before GDB disconnects via + the 'detach' command. + + The second form, including a process ID, is used when multiprocess + protocol extensions are enabled (*note multiprocess extensions::), + to detach only a specific process. The PID is specified as a + big-endian hex string. + + Reply: + 'OK' + for success + 'E NN' + for an error + +'F RC,EE,CF;XX' + A reply from GDB to an 'F' packet sent by the target. This is part + of the File-I/O protocol extension. *Note File-I/O Remote Protocol + Extension::, for the specification. + +'g' + Read general registers. + + Reply: + 'XX...' + Each byte of register data is described by two hex digits. + The bytes with the register are transmitted in target byte + order. The size of each register and their position within + the 'g' packet are determined by the GDB internal gdbarch + functions 'DEPRECATED_REGISTER_RAW_SIZE' and + 'gdbarch_register_name'. The specification of several + standard 'g' packets is specified below. + + When reading registers from a trace frame (*note Using the + Collected Data: Analyze Collected Data.), the stub may also + return a string of literal 'x''s in place of the register data + digits, to indicate that the corresponding register has not + been collected, thus its value is unavailable. For example, + for an architecture with 4 registers of 4 bytes each, the + following reply indicates to GDB that registers 0 and 2 have + not been collected, while registers 1 and 3 have been + collected, and both have zero value: + + -> g + <- xxxxxxxx00000000xxxxxxxx00000000 + + 'E NN' + for an error. + +'G XX...' + Write general registers. *Note read registers packet::, for a + description of the XX... data. + + Reply: + 'OK' + for success + 'E NN' + for an error + +'H OP THREAD-ID' + Set thread for subsequent operations ('m', 'M', 'g', 'G', et.al.). + OP depends on the operation to be performed: it should be 'c' for + step and continue operations (note that this is deprecated, + supporting the 'vCont' command is a better option), 'g' for other + operations. The thread designator THREAD-ID has the format and + interpretation described in *note thread-id syntax::. + + Reply: + 'OK' + for success + 'E NN' + for an error + +'i [ADDR[,NNN]]' + Step the remote target by a single clock cycle. If ',NNN' is + present, cycle step NNN cycles. If ADDR is present, cycle step + starting at that address. + +'I' + Signal, then cycle step. *Note step with signal packet::. *Note + cycle step packet::. + +'k' + Kill request. + + FIXME: _There is no description of how to operate when a specific + thread context has been selected (i.e. does 'k' kill only that + thread?)_. + +'m ADDR,LENGTH' + Read LENGTH bytes of memory starting at address ADDR. Note that + ADDR may not be aligned to any particular boundary. + + The stub need not use any particular size or alignment when + gathering data from memory for the response; even if ADDR is + word-aligned and LENGTH is a multiple of the word size, the stub is + free to use byte accesses, or not. For this reason, this packet + may not be suitable for accessing memory-mapped I/O devices. + + Reply: + 'XX...' + Memory contents; each byte is transmitted as a two-digit + hexadecimal number. The reply may contain fewer bytes than + requested if the server was able to read only part of the + region of memory. + 'E NN' + NN is errno + +'M ADDR,LENGTH:XX...' + Write LENGTH bytes of memory starting at address ADDR. XX... is + the data; each byte is transmitted as a two-digit hexadecimal + number. + + Reply: + 'OK' + for success + 'E NN' + for an error (this includes the case where only part of the + data was written). + +'p N' + Read the value of register N; N is in hex. *Note read registers + packet::, for a description of how the returned register value is + encoded. + + Reply: + 'XX...' + the register's value + 'E NN' + for an error + '' + Indicating an unrecognized QUERY. + +'P N...=R...' + Write register N... with value R.... The register number N is in + hexadecimal, and R... contains two hex digits for each byte in the + register (target byte order). + + Reply: + 'OK' + for success + 'E NN' + for an error + +'q NAME PARAMS...' +'Q NAME PARAMS...' + General query ('q') and set ('Q'). These packets are described + fully in *note General Query Packets::. + +'r' + Reset the entire system. + + Don't use this packet; use the 'R' packet instead. + +'R XX' + Restart the program being debugged. XX, while needed, is ignored. + This packet is only available in extended mode (*note extended + mode::). + + The 'R' packet has no reply. + +'s [ADDR]' + Single step. ADDR is the address at which to resume. If ADDR is + omitted, resume at same address. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'S SIG[;ADDR]' + Step with signal. This is analogous to the 'C' packet, but + requests a single-step, rather than a normal resumption of + execution. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'t ADDR:PP,MM' + Search backwards starting at address ADDR for a match with pattern + PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3 + digits. + +'T THREAD-ID' + Find out if the thread THREAD-ID is alive. *Note thread-id + syntax::. + + Reply: + 'OK' + thread is still alive + 'E NN' + thread is dead + +'v' + Packets starting with 'v' are identified by a multi-letter name, up + to the first ';' or '?' (or the end of the packet). + +'vAttach;PID' + Attach to a new process with the specified process ID PID. The + process ID is a hexadecimal integer identifying the process. In + all-stop mode, all threads in the attached process are stopped; in + non-stop mode, it may be attached without being stopped if that is + supported by the target. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'E NN' + for an error + 'Any stop packet' + for success in all-stop mode (*note Stop Reply Packets::) + 'OK' + for success in non-stop mode (*note Remote Non-Stop::) + +'vCont[;ACTION[:THREAD-ID]]...' + Resume the inferior, specifying different actions for each thread. + If an action is specified with no THREAD-ID, then it is applied to + any threads that don't have a specific action specified; if no + default action is specified then other threads should remain + stopped in all-stop mode and in their current state in non-stop + mode. Specifying multiple default actions is an error; specifying + no actions is also an error. Thread IDs are specified using the + syntax described in *note thread-id syntax::. + + Currently supported actions are: + + 'c' + Continue. + 'C SIG' + Continue with signal SIG. The signal SIG should be two hex + digits. + 's' + Step. + 'S SIG' + Step with signal SIG. The signal SIG should be two hex + digits. + 't' + Stop. + 'r START,END' + Step once, and then keep stepping as long as the thread stops + at addresses between START (inclusive) and END (exclusive). + The remote stub reports a stop reply when either the thread + goes out of the range or is stopped due to an unrelated + reason, such as hitting a breakpoint. *Note range stepping::. + + If the range is empty (START == END), then the action becomes + equivalent to the 's' action. In other words, single-step + once, and report the stop (even if the stepped instruction + jumps to START). + + (A stop reply may be sent at any point even if the PC is still + within the stepping range; for example, it is valid to + implement this packet in a degenerate way as a single + instruction step operation.) + + The optional argument ADDR normally associated with the 'c', 'C', + 's', and 'S' packets is not supported in 'vCont'. + + The 't' action is only relevant in non-stop mode (*note Remote + Non-Stop::) and may be ignored by the stub otherwise. A stop reply + should be generated for any affected thread not already stopped. + When a thread is stopped by means of a 't' action, the + corresponding stop reply should indicate that the thread has + stopped with signal '0', regardless of whether the target uses some + other signal as an implementation detail. + + The stub must support 'vCont' if it reports support for + multiprocess extensions (*note multiprocess extensions::). Note + that in this case 'vCont' actions can be specified to apply to all + threads in a process by using the 'pPID.-1' form of the THREAD-ID. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'vCont?' + Request a list of actions supported by the 'vCont' packet. + + Reply: + 'vCont[;ACTION...]' + The 'vCont' packet is supported. Each ACTION is a supported + command in the 'vCont' packet. + '' + The 'vCont' packet is not supported. + +'vFile:OPERATION:PARAMETER...' + Perform a file operation on the target system. For details, see + *note Host I/O Packets::. + +'vFlashErase:ADDR,LENGTH' + Direct the stub to erase LENGTH bytes of flash starting at ADDR. + The region may enclose any number of flash blocks, but its start + and end must fall on block boundaries, as indicated by the flash + block size appearing in the memory map (*note Memory Map Format::). + GDB groups flash memory programming operations together, and sends + a 'vFlashDone' request after each group; the stub is allowed to + delay erase operation until the 'vFlashDone' packet is received. + + Reply: + 'OK' + for success + 'E NN' + for an error + +'vFlashWrite:ADDR:XX...' + Direct the stub to write data to flash address ADDR. The data is + passed in binary form using the same encoding as for the 'X' packet + (*note Binary Data::). The memory ranges specified by + 'vFlashWrite' packets preceding a 'vFlashDone' packet must not + overlap, and must appear in order of increasing addresses (although + 'vFlashErase' packets for higher addresses may already have been + received; the ordering is guaranteed only between 'vFlashWrite' + packets). If a packet writes to an address that was neither erased + by a preceding 'vFlashErase' packet nor by some other + target-specific method, the results are unpredictable. + + Reply: + 'OK' + for success + 'E.memtype' + for vFlashWrite addressing non-flash memory + 'E NN' + for an error + +'vFlashDone' + Indicate to the stub that flash programming operation is finished. + The stub is permitted to delay or batch the effects of a group of + 'vFlashErase' and 'vFlashWrite' packets until a 'vFlashDone' packet + is received. The contents of the affected regions of flash memory + are unpredictable until the 'vFlashDone' request is completed. + +'vKill;PID' + Kill the process with the specified process ID. PID is a + hexadecimal integer identifying the process. This packet is used + in preference to 'k' when multiprocess protocol extensions are + supported; see *note multiprocess extensions::. + + Reply: + 'E NN' + for an error + 'OK' + for success + +'vRun;FILENAME[;ARGUMENT]...' + Run the program FILENAME, passing it each ARGUMENT on its command + line. The file and arguments are hex-encoded strings. If FILENAME + is an empty string, the stub may use a default program (e.g. the + last program run). The program is created in the stopped state. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'E NN' + for an error + 'Any stop packet' + for success (*note Stop Reply Packets::) + +'vStopped' + *Note Notification Packets::. + +'X ADDR,LENGTH:XX...' + Write data to memory, where the data is transmitted in binary. + ADDR is address, LENGTH is number of bytes, 'XX...' is binary data + (*note Binary Data::). + + Reply: + 'OK' + for success + 'E NN' + for an error + +'z TYPE,ADDR,KIND' +'Z TYPE,ADDR,KIND' + Insert ('Z') or remove ('z') a TYPE breakpoint or watchpoint + starting at address ADDRESS of kind KIND. + + Each breakpoint and watchpoint packet TYPE is documented + separately. + + _Implementation notes: A remote target shall return an empty string + for an unrecognized breakpoint or watchpoint packet TYPE. A remote + target shall support either both or neither of a given 'ZTYPE...' + and 'zTYPE...' packet pair. To avoid potential problems with + duplicate packets, the operations should be implemented in an + idempotent way._ + +'z0,ADDR,KIND' +'Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]' + Insert ('Z0') or remove ('z0') a memory breakpoint at address ADDR + of type KIND. + + A memory breakpoint is implemented by replacing the instruction at + ADDR with a software breakpoint or trap instruction. The KIND is + target-specific and typically indicates the size of the breakpoint + in bytes that should be inserted. E.g., the ARM and MIPS can + insert either a 2 or 4 byte breakpoint. Some architectures have + additional meanings for KIND; COND_LIST is an optional list of + conditional expressions in bytecode form that should be evaluated + on the target's side. These are the conditions that should be + taken into consideration when deciding if the breakpoint trigger + should be reported back to GDBN. + + The COND_LIST parameter is comprised of a series of expressions, + concatenated without separators. Each expression has the following + form: + + 'X LEN,EXPR' + LEN is the length of the bytecode expression and EXPR is the + actual conditional expression in bytecode form. + + The optional CMD_LIST parameter introduces commands that may be run + on the target, rather than being reported back to GDB. The + parameter starts with a numeric flag PERSIST; if the flag is + nonzero, then the breakpoint may remain active and the commands + continue to be run even when GDB disconnects from the target. + Following this flag is a series of expressions concatenated with no + separators. Each expression has the following form: + + 'X LEN,EXPR' + LEN is the length of the bytecode expression and EXPR is the + actual conditional expression in bytecode form. + + see *note Architecture-Specific Protocol Details::. + + _Implementation note: It is possible for a target to copy or move + code that contains memory breakpoints (e.g., when implementing + overlays). The behavior of this packet, in the presence of such a + target, is not defined._ + + Reply: + 'OK' + success + '' + not supported + 'E NN' + for an error + +'z1,ADDR,KIND' +'Z1,ADDR,KIND[;COND_LIST...]' + Insert ('Z1') or remove ('z1') a hardware breakpoint at address + ADDR. + + A hardware breakpoint is implemented using a mechanism that is not + dependant on being able to modify the target's memory. KIND and + COND_LIST have the same meaning as in 'Z0' packets. + + _Implementation note: A hardware breakpoint is not affected by code + movement._ + + Reply: + 'OK' + success + '' + not supported + 'E NN' + for an error + +'z2,ADDR,KIND' +'Z2,ADDR,KIND' + Insert ('Z2') or remove ('z2') a write watchpoint at ADDR. KIND is + interpreted as the number of bytes to watch. + + Reply: + 'OK' + success + '' + not supported + 'E NN' + for an error + +'z3,ADDR,KIND' +'Z3,ADDR,KIND' + Insert ('Z3') or remove ('z3') a read watchpoint at ADDR. KIND is + interpreted as the number of bytes to watch. + + Reply: + 'OK' + success + '' + not supported + 'E NN' + for an error + +'z4,ADDR,KIND' +'Z4,ADDR,KIND' + Insert ('Z4') or remove ('z4') an access watchpoint at ADDR. KIND + is interpreted as the number of bytes to watch. + + Reply: + 'OK' + success + '' + not supported + 'E NN' + for an error + + +File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol + +E.3 Stop Reply Packets +====================== + +The 'C', 'c', 'S', 's', 'vCont', 'vAttach', 'vRun', 'vStopped', and '?' +packets can receive any of the below as a reply. Except for '?' and +'vStopped', that reply is only returned when the target halts. In the +below the exact meaning of "signal number" is defined by the header +'include/gdb/signals.h' in the GDB source code. + + As in the description of request packets, we include spaces in the +reply templates for clarity; these are not part of the reply packet's +syntax. No GDB stop reply packet uses spaces to separate its +components. + +'S AA' + The program received signal number AA (a two-digit hexadecimal + number). This is equivalent to a 'T' response with no N:R pairs. + +'T AA N1:R1;N2:R2;...' + The program received signal number AA (a two-digit hexadecimal + number). This is equivalent to an 'S' response, except that the + 'N:R' pairs can carry values of important registers and other + information directly in the stop reply packet, reducing round-trip + latency. Single-step and breakpoint traps are reported this way. + Each 'N:R' pair is interpreted as follows: + + * If N is a hexadecimal number, it is a register number, and the + corresponding R gives that register's value. R is a series of + bytes in target byte order, with each byte given by a + two-digit hex number. + + * If N is 'thread', then R is the THREAD-ID of the stopped + thread, as specified in *note thread-id syntax::. + + * If N is 'core', then R is the hexadecimal number of the core + on which the stop event was detected. + + * If N is a recognized "stop reason", it describes a more + specific event that stopped the target. The currently defined + stop reasons are listed below. AA should be '05', the trap + signal. At most one stop reason should be present. + + * Otherwise, GDB should ignore this 'N:R' pair and go on to the + next; this allows us to extend the protocol in the future. + + The currently defined stop reasons are: + + 'watch' + 'rwatch' + 'awatch' + The packet indicates a watchpoint hit, and R is the data + address, in hex. + + 'library' + The packet indicates that the loaded libraries have changed. + GDB should use 'qXfer:libraries:read' to fetch a new list of + loaded libraries. R is ignored. + + 'replaylog' + The packet indicates that the target cannot continue replaying + logged execution events, because it has reached the end (or + the beginning when executing backward) of the log. The value + of R will be either 'begin' or 'end'. *Note Reverse + Execution::, for more information. + +'W AA' +'W AA ; process:PID' + The process exited, and AA is the exit status. This is only + applicable to certain targets. + + The second form of the response, including the process ID of the + exited process, can be used only when GDB has reported support for + multiprocess protocol extensions; see *note multiprocess + extensions::. The PID is formatted as a big-endian hex string. + +'X AA' +'X AA ; process:PID' + The process terminated with signal AA. + + The second form of the response, including the process ID of the + terminated process, can be used only when GDB has reported support + for multiprocess protocol extensions; see *note multiprocess + extensions::. The PID is formatted as a big-endian hex string. + +'O XX...' + 'XX...' is hex encoding of ASCII data, to be written as the + program's console output. This can happen at any time while the + program is running and the debugger should continue to wait for + 'W', 'T', etc. This reply is not permitted in non-stop mode. + +'F CALL-ID,PARAMETER...' + CALL-ID is the identifier which says which host system call should + be called. This is just the name of the function. Translation + into the correct system call is only applicable as it's defined in + GDB. *Note File-I/O Remote Protocol Extension::, for a list of + implemented system calls. + + 'PARAMETER...' is a list of parameters as defined for this very + system call. + + The target replies with this packet when it expects GDB to call a + host system call on behalf of the target. GDB replies with an + appropriate 'F' packet and keeps up waiting for the next reply + packet from the target. The latest 'C', 'c', 'S' or 's' action is + expected to be continued. *Note File-I/O Remote Protocol + Extension::, for more details. + + +File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol + +E.4 General Query Packets +========================= + +Packets starting with 'q' are "general query packets"; packets starting +with 'Q' are "general set packets". General query and set packets are a +semi-unified form for retrieving and sending information to and from the +stub. + + The initial letter of a query or set packet is followed by a name +indicating what sort of thing the packet applies to. For example, GDB +may use a 'qSymbol' packet to exchange symbol definitions with the stub. +These packet names follow some conventions: + + * The name must not contain commas, colons or semicolons. + * Most GDB query and set packets have a leading upper case letter. + * The names of custom vendor packets should use a company prefix, in + lower case, followed by a period. For example, packets designed at + the Acme Corporation might begin with 'qacme.foo' (for querying + foos) or 'Qacme.bar' (for setting bars). + + The name of a query or set packet should be separated from any +parameters by a ':'; the parameters themselves should be separated by +',' or ';'. Stubs must be careful to match the full packet name, and +check for a separator or the end of the packet, in case two packet names +share a common prefix. New packets should not begin with 'qC', 'qP', or +'qL'(1). + + Like the descriptions of the other packets, each description here has +a template showing the packet's overall syntax, followed by an +explanation of the packet's meaning. We include spaces in some of the +templates for clarity; these are not part of the packet's syntax. No +GDB packet uses spaces to separate its components. + + Here are the currently defined query and set packets: + +'QAgent:1' +'QAgent:0' + Turn on or off the agent as a helper to perform some debugging + operations delegated from GDB (*note Control Agent::). + +'QAllow:OP:VAL...' + Specify which operations GDB expects to request of the target, as a + semicolon-separated list of operation name and value pairs. + Possible values for OP include 'WriteReg', 'WriteMem', + 'InsertBreak', 'InsertTrace', 'InsertFastTrace', and 'Stop'. VAL + is either 0, indicating that GDB will not request the operation, or + 1, indicating that it may. (The target can then use this to set up + its own internals optimally, for instance if the debugger never + expects to insert breakpoints, it may not need to install its own + trap handler.) + +'qC' + Return the current thread ID. + + Reply: + 'QC THREAD-ID' + Where THREAD-ID is a thread ID as documented in *note + thread-id syntax::. + '(anything else)' + Any other reply implies the old thread ID. + +'qCRC:ADDR,LENGTH' + Compute the CRC checksum of a block of memory using CRC-32 defined + in IEEE 802.3. The CRC is computed byte at a time, taking the most + significant bit of each byte first. The initial pattern code + '0xffffffff' is used to ensure leading zeros affect the CRC. + + _Note:_ This is the same CRC used in validating separate debug + files (*note Debugging Information in Separate Files: Separate + Debug Files.). However the algorithm is slightly different. When + validating separate debug files, the CRC is computed taking the + _least_ significant bit of each byte first, and the final result is + inverted to detect trailing zeros. + + Reply: + 'E NN' + An error (such as memory fault) + 'C CRC32' + The specified memory region's checksum is CRC32. + +'QDisableRandomization:VALUE' + Some target operating systems will randomize the virtual address + space of the inferior process as a security feature, but provide a + feature to disable such randomization, e.g. to allow for a more + deterministic debugging experience. On such systems, this packet + with a VALUE of 1 directs the target to disable address space + randomization for processes subsequently started via 'vRun' + packets, while a packet with a VALUE of 0 tells the target to + enable address space randomization. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'OK' + The request succeeded. + + 'E NN' + An error occurred. NN are hex digits. + + '' + An empty reply indicates that 'QDisableRandomization' is not + supported by the stub. + + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). This should only be done on targets that actually + support disabling address space randomization. + +'qfThreadInfo' +'qsThreadInfo' + Obtain a list of all active thread IDs from the target (OS). Since + there may be too many active threads to fit into one reply packet, + this query works iteratively: it may require more than one + query/reply sequence to obtain the entire list of threads. The + first query of the sequence will be the 'qfThreadInfo' query; + subsequent queries in the sequence will be the 'qsThreadInfo' + query. + + NOTE: This packet replaces the 'qL' query (see below). + + Reply: + 'm THREAD-ID' + A single thread ID + 'm THREAD-ID,THREAD-ID...' + a comma-separated list of thread IDs + 'l' + (lower case letter 'L') denotes end of list. + + In response to each query, the target will reply with a list of one + or more thread IDs, separated by commas. GDB will respond to each + reply with a request for more thread ids (using the 'qs' form of + the query), until the target responds with 'l' (lower-case ell, for + "last"). Refer to *note thread-id syntax::, for the format of the + THREAD-ID fields. + +'qGetTLSAddr:THREAD-ID,OFFSET,LM' + Fetch the address associated with thread local storage specified by + THREAD-ID, OFFSET, and LM. + + THREAD-ID is the thread ID associated with the thread for which to + fetch the TLS address. *Note thread-id syntax::. + + OFFSET is the (big endian, hex encoded) offset associated with the + thread local variable. (This offset is obtained from the debug + information associated with the variable.) + + LM is the (big endian, hex encoded) OS/ABI-specific encoding of the + load module associated with the thread local storage. For example, + a GNU/Linux system will pass the link map address of the shared + object associated with the thread local storage under + consideration. Other operating environments may choose to + represent the load module differently, so the precise meaning of + this parameter will vary. + + Reply: + 'XX...' + Hex encoded (big endian) bytes representing the address of the + thread local storage requested. + + 'E NN' + An error occurred. NN are hex digits. + + '' + An empty reply indicates that 'qGetTLSAddr' is not supported + by the stub. + +'qGetTIBAddr:THREAD-ID' + Fetch address of the Windows OS specific Thread Information Block. + + THREAD-ID is the thread ID associated with the thread. + + Reply: + 'XX...' + Hex encoded (big endian) bytes representing the linear address + of the thread information block. + + 'E NN' + An error occured. This means that either the thread was not + found, or the address could not be retrieved. + + '' + An empty reply indicates that 'qGetTIBAddr' is not supported + by the stub. + +'qL STARTFLAG THREADCOUNT NEXTTHREAD' + Obtain thread information from RTOS. Where: STARTFLAG (one hex + digit) is one to indicate the first query and zero to indicate a + subsequent query; THREADCOUNT (two hex digits) is the maximum + number of threads the response packet can contain; and NEXTTHREAD + (eight hex digits), for subsequent queries (STARTFLAG is zero), is + returned in the response as ARGTHREAD. + + Don't use this packet; use the 'qfThreadInfo' query instead (see + above). + + Reply: + 'qM COUNT DONE ARGTHREAD THREAD...' + Where: COUNT (two hex digits) is the number of threads being + returned; DONE (one hex digit) is zero to indicate more + threads and one indicates no further threads; ARGTHREADID + (eight hex digits) is NEXTTHREAD from the request packet; + THREAD... is a sequence of thread IDs from the target. + THREADID (eight hex digits). See + 'remote.c:parse_threadlist_response()'. + +'qOffsets' + Get section offsets that the target used when relocating the + downloaded image. + + Reply: + 'Text=XXX;Data=YYY[;Bss=ZZZ]' + Relocate the 'Text' section by XXX from its original address. + Relocate the 'Data' section by YYY from its original address. + If the object file format provides segment information (e.g. + ELF 'PT_LOAD' program headers), GDB will relocate entire + segments by the supplied offsets. + + _Note: while a 'Bss' offset may be included in the response, + GDB ignores this and instead applies the 'Data' offset to the + 'Bss' section._ + + 'TextSeg=XXX[;DataSeg=YYY]' + Relocate the first segment of the object file, which + conventionally contains program code, to a starting address of + XXX. If 'DataSeg' is specified, relocate the second segment, + which conventionally contains modifiable data, to a starting + address of YYY. GDB will report an error if the object file + does not contain segment information, or does not contain at + least as many segments as mentioned in the reply. Extra + segments are kept at fixed offsets relative to the last + relocated segment. + +'qP MODE THREAD-ID' + Returns information on THREAD-ID. Where: MODE is a hex encoded 32 + bit mode; THREAD-ID is a thread ID (*note thread-id syntax::). + + Don't use this packet; use the 'qThreadExtraInfo' query instead + (see below). + + Reply: see 'remote.c:remote_unpack_thread_info_response()'. + +'QNonStop:1' +'QNonStop:0' + Enter non-stop ('QNonStop:1') or all-stop ('QNonStop:0') mode. + *Note Remote Non-Stop::, for more information. + + Reply: + 'OK' + The request succeeded. + + 'E NN' + An error occurred. NN are hex digits. + + '' + An empty reply indicates that 'QNonStop' is not supported by + the stub. + + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). Use of this packet is controlled by the 'set + non-stop' command; *note Non-Stop Mode::. + +'QPassSignals: SIGNAL [;SIGNAL]...' + Each listed SIGNAL should be passed directly to the inferior + process. Signals are numbered identically to continue packets and + stop replies (*note Stop Reply Packets::). Each SIGNAL list item + should be strictly greater than the previous item. These signals + do not need to stop the inferior, or be reported to GDB. All other + signals should be reported to GDB. Multiple 'QPassSignals' packets + do not combine; any earlier 'QPassSignals' list is completely + replaced by the new list. This packet improves performance when + using 'handle SIGNAL nostop noprint pass'. + + Reply: + 'OK' + The request succeeded. + + 'E NN' + An error occurred. NN are hex digits. + + '' + An empty reply indicates that 'QPassSignals' is not supported + by the stub. + + Use of this packet is controlled by the 'set remote pass-signals' + command (*note set remote pass-signals: Remote Configuration.). + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). + +'QProgramSignals: SIGNAL [;SIGNAL]...' + Each listed SIGNAL may be delivered to the inferior process. + Others should be silently discarded. + + In some cases, the remote stub may need to decide whether to + deliver a signal to the program or not without GDB involvement. + One example of that is while detaching -- the program's threads may + have stopped for signals that haven't yet had a chance of being + reported to GDB, and so the remote stub can use the signal list + specified by this packet to know whether to deliver or ignore those + pending signals. + + This does not influence whether to deliver a signal as requested by + a resumption packet (*note vCont packet::). + + Signals are numbered identically to continue packets and stop + replies (*note Stop Reply Packets::). Each SIGNAL list item should + be strictly greater than the previous item. Multiple + 'QProgramSignals' packets do not combine; any earlier + 'QProgramSignals' list is completely replaced by the new list. + + Reply: + 'OK' + The request succeeded. + + 'E NN' + An error occurred. NN are hex digits. + + '' + An empty reply indicates that 'QProgramSignals' is not + supported by the stub. + + Use of this packet is controlled by the 'set remote + program-signals' command (*note set remote program-signals: Remote + Configuration.). This packet is not probed by default; the remote + stub must request it, by supplying an appropriate 'qSupported' + response (*note qSupported::). + +'qRcmd,COMMAND' + COMMAND (hex encoded) is passed to the local interpreter for + execution. Invalid commands should be reported using the output + string. Before the final result packet, the target may also + respond with a number of intermediate 'OOUTPUT' console output + packets. _Implementors should note that providing access to a + stubs's interpreter may have security implications_. + + Reply: + 'OK' + A command response with no output. + 'OUTPUT' + A command response with the hex encoded output string OUTPUT. + 'E NN' + Indicate a badly formed request. + '' + An empty reply indicates that 'qRcmd' is not recognized. + + (Note that the 'qRcmd' packet's name is separated from the command + by a ',', not a ':', contrary to the naming conventions above. + Please don't use this packet as a model for new packets.) + +'qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN' + Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. ADDRESS and + LENGTH are encoded in hex. SEARCH-PATTERN is a sequence of bytes, + hex encoded. + + Reply: + '0' + The pattern was not found. + '1,address' + The pattern was found at ADDRESS. + 'E NN' + A badly formed request or an error was encountered while + searching memory. + '' + An empty reply indicates that 'qSearch:memory' is not + recognized. + +'QStartNoAckMode' + Request that the remote stub disable the normal '+'/'-' protocol + acknowledgments (*note Packet Acknowledgment::). + + Reply: + 'OK' + The stub has switched to no-acknowledgment mode. GDB + acknowledges this reponse, but neither the stub nor GDB shall + send or expect further '+'/'-' acknowledgments in the current + connection. + '' + An empty reply indicates that the stub does not support + no-acknowledgment mode. + +'qSupported [:GDBFEATURE [;GDBFEATURE]... ]' + Tell the remote stub about features supported by GDB, and query the + stub for features it supports. This packet allows GDB and the + remote stub to take advantage of each others' features. + 'qSupported' also consolidates multiple feature probes at startup, + to improve GDB performance--a single larger packet performs better + than multiple smaller probe packets on high-latency links. Some + features may enable behavior which must not be on by default, e.g. + because it would confuse older clients or stubs. Other features + may describe packets which could be automatically probed for, but + are not. These features must be reported before GDB will use them. + This "default unsupported" behavior is not appropriate for all + packets, but it helps to keep the initial connection time under + control with new versions of GDB which support increasing numbers + of packets. + + Reply: + 'STUBFEATURE [;STUBFEATURE]...' + The stub supports or does not support each returned + STUBFEATURE, depending on the form of each STUBFEATURE (see + below for the possible forms). + '' + An empty reply indicates that 'qSupported' is not recognized, + or that no features needed to be reported to GDB. + + The allowed forms for each feature (either a GDBFEATURE in the + 'qSupported' packet, or a STUBFEATURE in the response) are: + + 'NAME=VALUE' + The remote protocol feature NAME is supported, and associated + with the specified VALUE. The format of VALUE depends on the + feature, but it must not include a semicolon. + 'NAME+' + The remote protocol feature NAME is supported, and does not + need an associated value. + 'NAME-' + The remote protocol feature NAME is not supported. + 'NAME?' + The remote protocol feature NAME may be supported, and GDB + should auto-detect support in some other way when it is + needed. This form will not be used for GDBFEATURE + notifications, but may be used for STUBFEATURE responses. + + Whenever the stub receives a 'qSupported' request, the supplied set + of GDB features should override any previous request. This allows + GDB to put the stub in a known state, even if the stub had + previously been communicating with a different version of GDB. + + The following values of GDBFEATURE (for the packet sent by GDB) are + defined: + + 'multiprocess' + This feature indicates whether GDB supports multiprocess + extensions to the remote protocol. GDB does not use such + extensions unless the stub also reports that it supports them + by including 'multiprocess+' in its 'qSupported' reply. *Note + multiprocess extensions::, for details. + + 'xmlRegisters' + This feature indicates that GDB supports the XML target + description. If the stub sees 'xmlRegisters=' with target + specific strings separated by a comma, it will report register + description. + + 'qRelocInsn' + This feature indicates whether GDB supports the 'qRelocInsn' + packet (*note Relocate instruction reply packet: Tracepoint + Packets.). + + Stubs should ignore any unknown values for GDBFEATURE. Any GDB + which sends a 'qSupported' packet supports receiving packets of + unlimited length (earlier versions of GDB may reject overly long + responses). Additional values for GDBFEATURE may be defined in the + future to let the stub take advantage of new features in GDB, e.g. + incompatible improvements in the remote protocol--the + 'multiprocess' feature is an example of such a feature. The stub's + reply should be independent of the GDBFEATURE entries sent by GDB; + first GDB describes all the features it supports, and then the stub + replies with all the features it supports. + + Similarly, GDB will silently ignore unrecognized stub feature + responses, as long as each response uses one of the standard forms. + + Some features are flags. A stub which supports a flag feature + should respond with a '+' form response. Other features require + values, and the stub should respond with an '=' form response. + + Each feature has a default value, which GDB will use if + 'qSupported' is not available or if the feature is not mentioned in + the 'qSupported' response. The default values are fixed; a stub is + free to omit any feature responses that match the defaults. + + Not all features can be probed, but for those which can, the + probing mechanism is useful: in some cases, a stub's internal + architecture may not allow the protocol layer to know some + information about the underlying target in advance. This is + especially common in stubs which may be configured for multiple + targets. + + These are the currently defined stub features and their properties: + + Feature Name Value Default Probe + Required Allowed + + 'PacketSize' Yes '-' No + + 'qXfer:auxv:read' No '-' Yes + + 'qXfer:btrace:read' No '-' Yes + + 'qXfer:features:read' No '-' Yes + + 'qXfer:libraries:read' No '-' Yes + + 'qXfer:libraries-svr4:read'No '-' Yes + + 'augmented-libraries-svr4-read'No '-' No + + 'qXfer:memory-map:read' No '-' Yes + + 'qXfer:sdata:read' No '-' Yes + + 'qXfer:spu:read' No '-' Yes + + 'qXfer:spu:write' No '-' Yes + + 'qXfer:siginfo:read' No '-' Yes + + 'qXfer:siginfo:write' No '-' Yes + + 'qXfer:threads:read' No '-' Yes + + 'qXfer:traceframe-info:read'No '-' Yes + + 'qXfer:uib:read' No '-' Yes + + 'qXfer:fdpic:read' No '-' Yes + + 'Qbtrace:off' Yes '-' Yes + + 'Qbtrace:bts' Yes '-' Yes + + 'QNonStop' No '-' Yes + + 'QPassSignals' No '-' Yes + + 'QStartNoAckMode' No '-' Yes + + 'multiprocess' No '-' No + + 'ConditionalBreakpoints' No '-' No + + 'ConditionalTracepoints' No '-' No + + 'ReverseContinue' No '-' No + + 'ReverseStep' No '-' No + + 'TracepointSource' No '-' No + + 'QAgent' No '-' No + + 'QAllow' No '-' No + + 'QDisableRandomization' No '-' No + + 'EnableDisableTracepoints'No '-' No + + 'QTBuffer:size' No '-' No + + 'tracenz' No '-' No + + 'BreakpointCommands' No '-' No + + + These are the currently defined stub features, in more detail: + + 'PacketSize=BYTES' + The remote stub can accept packets up to at least BYTES in + length. GDB will send packets up to this size for bulk + transfers, and will never send larger packets. This is a + limit on the data characters in the packet, including the + frame and checksum. There is no trailing NUL byte in a remote + protocol packet; if the stub stores packets in a + NUL-terminated format, it should allow an extra byte in its + buffer for the NUL. If this stub feature is not supported, GDB + guesses based on the size of the 'g' packet response. + + 'qXfer:auxv:read' + The remote stub understands the 'qXfer:auxv:read' packet + (*note qXfer auxiliary vector read::). + + 'qXfer:btrace:read' + The remote stub understands the 'qXfer:btrace:read' packet + (*note qXfer btrace read::). + + 'qXfer:features:read' + The remote stub understands the 'qXfer:features:read' packet + (*note qXfer target description read::). + + 'qXfer:libraries:read' + The remote stub understands the 'qXfer:libraries:read' packet + (*note qXfer library list read::). + + 'qXfer:libraries-svr4:read' + The remote stub understands the 'qXfer:libraries-svr4:read' + packet (*note qXfer svr4 library list read::). + + 'augmented-libraries-svr4-read' + The remote stub understands the augmented form of the + 'qXfer:libraries-svr4:read' packet (*note qXfer svr4 library + list read::). + + 'qXfer:memory-map:read' + The remote stub understands the 'qXfer:memory-map:read' packet + (*note qXfer memory map read::). + + 'qXfer:sdata:read' + The remote stub understands the 'qXfer:sdata:read' packet + (*note qXfer sdata read::). + + 'qXfer:spu:read' + The remote stub understands the 'qXfer:spu:read' packet (*note + qXfer spu read::). + + 'qXfer:spu:write' + The remote stub understands the 'qXfer:spu:write' packet + (*note qXfer spu write::). + + 'qXfer:siginfo:read' + The remote stub understands the 'qXfer:siginfo:read' packet + (*note qXfer siginfo read::). + + 'qXfer:siginfo:write' + The remote stub understands the 'qXfer:siginfo:write' packet + (*note qXfer siginfo write::). + + 'qXfer:threads:read' + The remote stub understands the 'qXfer:threads:read' packet + (*note qXfer threads read::). + + 'qXfer:traceframe-info:read' + The remote stub understands the 'qXfer:traceframe-info:read' + packet (*note qXfer traceframe info read::). + + 'qXfer:uib:read' + The remote stub understands the 'qXfer:uib:read' packet (*note + qXfer unwind info block::). + + 'qXfer:fdpic:read' + The remote stub understands the 'qXfer:fdpic:read' packet + (*note qXfer fdpic loadmap read::). + + 'QNonStop' + The remote stub understands the 'QNonStop' packet (*note + QNonStop::). + + 'QPassSignals' + The remote stub understands the 'QPassSignals' packet (*note + QPassSignals::). + + 'QStartNoAckMode' + The remote stub understands the 'QStartNoAckMode' packet and + prefers to operate in no-acknowledgment mode. *Note Packet + Acknowledgment::. + + 'multiprocess' + The remote stub understands the multiprocess extensions to the + remote protocol syntax. The multiprocess extensions affect + the syntax of thread IDs in both packets and replies (*note + thread-id syntax::), and add process IDs to the 'D' packet and + 'W' and 'X' replies. Note that reporting this feature + indicates support for the syntactic extensions only, not that + the stub necessarily supports debugging of more than one + process at a time. The stub must not use multiprocess + extensions in packet replies unless GDB has also indicated it + supports them in its 'qSupported' request. + + 'qXfer:osdata:read' + The remote stub understands the 'qXfer:osdata:read' packet + ((*note qXfer osdata read::). + + 'ConditionalBreakpoints' + The target accepts and implements evaluation of conditional + expressions defined for breakpoints. The target will only + report breakpoint triggers when such conditions are true + (*note Break Conditions: Conditions.). + + 'ConditionalTracepoints' + The remote stub accepts and implements conditional expressions + defined for tracepoints (*note Tracepoint Conditions::). + + 'ReverseContinue' + The remote stub accepts and implements the reverse continue + packet (*note bc::). + + 'ReverseStep' + The remote stub accepts and implements the reverse step packet + (*note bs::). + + 'TracepointSource' + The remote stub understands the 'QTDPsrc' packet that supplies + the source form of tracepoint definitions. + + 'QAgent' + The remote stub understands the 'QAgent' packet. + + 'QAllow' + The remote stub understands the 'QAllow' packet. + + 'QDisableRandomization' + The remote stub understands the 'QDisableRandomization' + packet. + + 'StaticTracepoint' + The remote stub supports static tracepoints. + + 'InstallInTrace' + The remote stub supports installing tracepoint in tracing. + + 'EnableDisableTracepoints' + The remote stub supports the 'QTEnable' (*note QTEnable::) and + 'QTDisable' (*note QTDisable::) packets that allow tracepoints + to be enabled and disabled while a trace experiment is + running. + + 'QTBuffer:size' + The remote stub supports the 'QTBuffer:size' (*note + QTBuffer-size::) packet that allows to change the size of the + trace buffer. + + 'tracenz' + The remote stub supports the 'tracenz' bytecode for collecting + strings. See *note Bytecode Descriptions:: for details about + the bytecode. + + 'BreakpointCommands' + The remote stub supports running a breakpoint's command list + itself, rather than reporting the hit to GDB. + + 'Qbtrace:off' + The remote stub understands the 'Qbtrace:off' packet. + + 'Qbtrace:bts' + The remote stub understands the 'Qbtrace:bts' packet. + +'qSymbol::' + Notify the target that GDB is prepared to serve symbol lookup + requests. Accept requests from the target for the values of + symbols. + + Reply: + 'OK' + The target does not need to look up any (more) symbols. + 'qSymbol:SYM_NAME' + The target requests the value of symbol SYM_NAME (hex + encoded). GDB may provide the value by using the + 'qSymbol:SYM_VALUE:SYM_NAME' message, described below. + +'qSymbol:SYM_VALUE:SYM_NAME' + Set the value of SYM_NAME to SYM_VALUE. + + SYM_NAME (hex encoded) is the name of a symbol whose value the + target has previously requested. + + SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot + supply a value for SYM_NAME, then this field will be empty. + + Reply: + 'OK' + The target does not need to look up any (more) symbols. + 'qSymbol:SYM_NAME' + The target requests the value of a new symbol SYM_NAME (hex + encoded). GDB will continue to supply the values of symbols + (if available), until the target ceases to request them. + +'qTBuffer' +'QTBuffer' +'QTDisconnected' +'QTDP' +'QTDPsrc' +'QTDV' +'qTfP' +'qTfV' +'QTFrame' +'qTMinFTPILen' + + *Note Tracepoint Packets::. + +'qThreadExtraInfo,THREAD-ID' + Obtain a printable string description of a thread's attributes from + the target OS. THREAD-ID is a thread ID; see *note thread-id + syntax::. This string may contain anything that the target OS + thinks is interesting for GDB to tell the user about the thread. + The string is displayed in GDB's 'info threads' display. Some + examples of possible thread extra info strings are 'Runnable', or + 'Blocked on Mutex'. + + Reply: + 'XX...' + Where 'XX...' is a hex encoding of ASCII data, comprising the + printable string containing the extra information about the + thread's attributes. + + (Note that the 'qThreadExtraInfo' packet's name is separated from + the command by a ',', not a ':', contrary to the naming conventions + above. Please don't use this packet as a model for new packets.) + +'QTNotes' +'qTP' +'QTSave' +'qTsP' +'qTsV' +'QTStart' +'QTStop' +'QTEnable' +'QTDisable' +'QTinit' +'QTro' +'qTStatus' +'qTV' +'qTfSTM' +'qTsSTM' +'qTSTMat' + *Note Tracepoint Packets::. + +'qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH' + Read uninterpreted bytes from the target's special data area + identified by the keyword OBJECT. Request LENGTH bytes starting at + OFFSET bytes into the data. The content and encoding of ANNEX is + specific to OBJECT; it can supply additional details about what + data to access. + + Here are the specific requests of this form defined so far. All + 'qXfer:OBJECT:read:...' requests use the same reply formats, listed + below. + + 'qXfer:auxv:read::OFFSET,LENGTH' + Access the target's "auxiliary vector". *Note auxiliary + vector: OS Information. Note ANNEX must be empty. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:btrace:read:ANNEX:OFFSET,LENGTH' + + Return a description of the current branch trace. *Note + Branch Trace Format::. The annex part of the generic 'qXfer' + packet may have one of the following values: + + 'all' + Returns all available branch trace. + + 'new' + Returns all available branch trace if the branch trace + changed since the last read request. + + This packet is not probed by default; the remote stub must + request it by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:features:read:ANNEX:OFFSET,LENGTH' + Access the "target description". *Note Target Descriptions::. + The annex specifies which XML document to access. The main + description is always loaded from the 'target.xml' annex. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:libraries:read:ANNEX:OFFSET,LENGTH' + Access the target's list of loaded libraries. *Note Library + List Format::. The annex part of the generic 'qXfer' packet + must be empty (*note qXfer read::). + + Targets which maintain a list of libraries in the program's + memory do not need to implement this packet; it is designed + for platforms where the operating system manages the list of + loaded libraries. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:libraries-svr4:read:ANNEX:OFFSET,LENGTH' + Access the target's list of loaded libraries when the target + is an SVR4 platform. *Note Library List Format for SVR4 + Targets::. The annex part of the generic 'qXfer' packet must + be empty unless the remote stub indicated it supports the + augmented form of this packet by supplying an appropriate + 'qSupported' response (*note qXfer read::, *note + qSupported::). + + This packet is optional for better performance on SVR4 + targets. GDB uses memory read packets to read the SVR4 + library list otherwise. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + If the remote stub indicates it supports the augmented form of + this packet then the annex part of the generic 'qXfer' packet + may contain a semicolon-separated list of 'NAME=VALUE' + arguments. The currently supported arguments are: + + 'start=ADDRESS' + A hexadecimal number specifying the address of the + 'struct link_map' to start reading the library list from. + If unset or zero then the first 'struct link_map' in the + library list will be chosen as the starting point. + + 'prev=ADDRESS' + A hexadecimal number specifying the address of the + 'struct link_map' immediately preceding the 'struct + link_map' specified by the 'start' argument. If unset or + zero then the remote stub will expect that no 'struct + link_map' exists prior to the starting point. + + Arguments that are not understood by the remote stub will be + silently ignored. + + 'qXfer:memory-map:read::OFFSET,LENGTH' + Access the target's "memory-map". *Note Memory Map Format::. + The annex part of the generic 'qXfer' packet must be empty + (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:sdata:read::OFFSET,LENGTH' + + Read contents of the extra collected static tracepoint marker + information. The annex part of the generic 'qXfer' packet + must be empty (*note qXfer read::). *Note Tracepoint Action + Lists: Tracepoint Actions. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:siginfo:read::OFFSET,LENGTH' + Read contents of the extra signal information on the target + system. The annex part of the generic 'qXfer' packet must be + empty (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:spu:read:ANNEX:OFFSET,LENGTH' + Read contents of an 'spufs' file on the target system. The + annex specifies which file to read; it must be of the form + 'ID/NAME', where ID specifies an SPU context ID in the target + process, and NAME identifes the 'spufs' file in that context + to be accessed. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:threads:read::OFFSET,LENGTH' + Access the list of threads on target. *Note Thread List + Format::. The annex part of the generic 'qXfer' packet must + be empty (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:traceframe-info:read::OFFSET,LENGTH' + + Return a description of the current traceframe's contents. + *Note Traceframe Info Format::. The annex part of the generic + 'qXfer' packet must be empty (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:uib:read:PC:OFFSET,LENGTH' + + Return the unwind information block for PC. This packet is + used on OpenVMS/ia64 to ask the kernel unwind information. + + This packet is not probed by default. + + 'qXfer:fdpic:read:ANNEX:OFFSET,LENGTH' + Read contents of 'loadmap's on the target system. The annex, + either 'exec' or 'interp', specifies which 'loadmap', + executable 'loadmap' or interpreter 'loadmap' to read. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:osdata:read::OFFSET,LENGTH' + Access the target's "operating system information". *Note + Operating System Information::. + + Reply: + 'm DATA' + Data DATA (*note Binary Data::) has been read from the target. + There may be more data at a higher address (although it is + permitted to return 'm' even for the last valid block of data, + as long as at least one byte of data was read). DATA may have + fewer bytes than the LENGTH in the request. + + 'l DATA' + Data DATA (*note Binary Data::) has been read from the target. + There is no more data to be read. DATA may have fewer bytes + than the LENGTH in the request. + + 'l' + The OFFSET in the request is at the end of the data. There is + no more data to be read. + + 'E00' + The request was malformed, or ANNEX was invalid. + + 'E NN' + The offset was invalid, or there was an error encountered + reading the data. NN is a hex-encoded 'errno' value. + + '' + An empty reply indicates the OBJECT string was not recognized + by the stub, or that the object does not support reading. + +'qXfer:OBJECT:write:ANNEX:OFFSET:DATA...' + Write uninterpreted bytes into the target's special data area + identified by the keyword OBJECT, starting at OFFSET bytes into the + data. DATA... is the binary-encoded data (*note Binary Data::) to + be written. The content and encoding of ANNEX is specific to + OBJECT; it can supply additional details about what data to access. + + Here are the specific requests of this form defined so far. All + 'qXfer:OBJECT:write:...' requests use the same reply formats, + listed below. + + 'qXfer:siginfo:write::OFFSET:DATA...' + Write DATA to the extra signal information on the target + system. The annex part of the generic 'qXfer' packet must be + empty (*note qXfer write::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:spu:write:ANNEX:OFFSET:DATA...' + Write DATA to an 'spufs' file on the target system. The annex + specifies which file to write; it must be of the form + 'ID/NAME', where ID specifies an SPU context ID in the target + process, and NAME identifes the 'spufs' file in that context + to be accessed. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + Reply: + 'NN' + NN (hex encoded) is the number of bytes written. This may be + fewer bytes than supplied in the request. + + 'E00' + The request was malformed, or ANNEX was invalid. + + 'E NN' + The offset was invalid, or there was an error encountered + writing the data. NN is a hex-encoded 'errno' value. + + '' + An empty reply indicates the OBJECT string was not recognized + by the stub, or that the object does not support writing. + +'qXfer:OBJECT:OPERATION:...' + Requests of this form may be added in the future. When a stub does + not recognize the OBJECT keyword, or its support for OBJECT does + not recognize the OPERATION keyword, the stub must respond with an + empty packet. + +'qAttached:PID' + Return an indication of whether the remote server attached to an + existing process or created a new process. When the multiprocess + protocol extensions are supported (*note multiprocess + extensions::), PID is an integer in hexadecimal format identifying + the target process. Otherwise, GDB will omit the PID field and the + query packet will be simplified as 'qAttached'. + + This query is used, for example, to know whether the remote process + should be detached or killed when a GDB session is ended with the + 'quit' command. + + Reply: + '1' + The remote server attached to an existing process. + '0' + The remote server created a new process. + 'E NN' + A badly formed request or an error was encountered. + +'Qbtrace:bts' + Enable branch tracing for the current thread using bts tracing. + + Reply: + 'OK' + Branch tracing has been enabled. + 'E.errtext' + A badly formed request or an error was encountered. + +'Qbtrace:off' + Disable branch tracing for the current thread. + + Reply: + 'OK' + Branch tracing has been disabled. + 'E.errtext' + A badly formed request or an error was encountered. + + ---------- Footnotes ---------- + + (1) The 'qP' and 'qL' packets predate these conventions, and have +arguments without any terminator for the packet name; we suspect they +are in widespread use in places that are difficult to upgrade. The 'qC' +packet has no arguments, but some existing stubs (e.g. RedBoot) are +known to not check for the end of the packet. + + +File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol + +E.5 Architecture-Specific Protocol Details +========================================== + +This section describes how the remote protocol is applied to specific +target architectures. Also see *note Standard Target Features::, for +details of XML target descriptions for each architecture. + +* Menu: + +* ARM-Specific Protocol Details:: +* MIPS-Specific Protocol Details:: + + +File: gdb.info, Node: ARM-Specific Protocol Details, Next: MIPS-Specific Protocol Details, Up: Architecture-Specific Protocol Details + +E.5.1 ARM-specific Protocol Details +----------------------------------- + +* Menu: + +* ARM Breakpoint Kinds:: + + +File: gdb.info, Node: ARM Breakpoint Kinds, Up: ARM-Specific Protocol Details + +E.5.1.1 ARM Breakpoint Kinds +............................ + +These breakpoint kinds are defined for the 'Z0' and 'Z1' packets. + +2 + 16-bit Thumb mode breakpoint. + +3 + 32-bit Thumb mode (Thumb-2) breakpoint. + +4 + 32-bit ARM mode breakpoint. + + +File: gdb.info, Node: MIPS-Specific Protocol Details, Prev: ARM-Specific Protocol Details, Up: Architecture-Specific Protocol Details + +E.5.2 MIPS-specific Protocol Details +------------------------------------ + +* Menu: + +* MIPS Register packet Format:: +* MIPS Breakpoint Kinds:: + + +File: gdb.info, Node: MIPS Register packet Format, Next: MIPS Breakpoint Kinds, Up: MIPS-Specific Protocol Details + +E.5.2.1 MIPS Register Packet Format +................................... + +The following 'g'/'G' packets have previously been defined. In the +below, some thirty-two bit registers are transferred as sixty-four bits. +Those registers should be zero/sign extended (which?) to fill the space +allocated. Register bytes are transferred in target byte order. The +two nibbles within a register byte are transferred most-significant - +least-significant. + +MIPS32 + All registers are transferred as thirty-two bit quantities in the + order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 + floating-point registers; fsr; fir; fp. + +MIPS64 + All registers are transferred as sixty-four bit quantities + (including thirty-two bit registers such as 'sr'). The ordering is + the same as 'MIPS32'. + + +File: gdb.info, Node: MIPS Breakpoint Kinds, Prev: MIPS Register packet Format, Up: MIPS-Specific Protocol Details + +E.5.2.2 MIPS Breakpoint Kinds +............................. + +These breakpoint kinds are defined for the 'Z0' and 'Z1' packets. + +2 + 16-bit MIPS16 mode breakpoint. + +3 + 16-bit microMIPS mode breakpoint. + +4 + 32-bit standard MIPS mode breakpoint. + +5 + 32-bit microMIPS mode breakpoint. + + +File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol + +E.6 Tracepoint Packets +====================== + +Here we describe the packets GDB uses to implement tracepoints (*note +Tracepoints::). + +'QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]' + Create a new tracepoint, number N, at ADDR. If ENA is 'E', then + the tracepoint is enabled; if it is 'D', then the tracepoint is + disabled. STEP is the tracepoint's step count, and PASS is its + pass count. If an 'F' is present, then the tracepoint is to be a + fast tracepoint, and the FLEN is the number of bytes that the + target should copy elsewhere to make room for the tracepoint. If + an 'X' is present, it introduces a tracepoint condition, which + consists of a hexadecimal length, followed by a comma and + hex-encoded bytes, in a manner similar to action encodings as + described below. If the trailing '-' is present, further 'QTDP' + packets will follow to specify this tracepoint's actions. + + Replies: + 'OK' + The packet was understood and carried out. + 'qRelocInsn' + *Note Relocate instruction reply packet: Tracepoint Packets. + '' + The packet was not recognized. + +'QTDP:-N:ADDR:[S]ACTION...[-]' + Define actions to be taken when a tracepoint is hit. N and ADDR + must be the same as in the initial 'QTDP' packet for this + tracepoint. This packet may only be sent immediately after another + 'QTDP' packet that ended with a '-'. If the trailing '-' is + present, further 'QTDP' packets will follow, specifying more + actions for this tracepoint. + + In the series of action packets for a given tracepoint, at most one + can have an 'S' before its first ACTION. If such a packet is sent, + it and the following packets define "while-stepping" actions. Any + prior packets define ordinary actions -- that is, those taken when + the tracepoint is first hit. If no action packet has an 'S', then + all the packets in the series specify ordinary tracepoint actions. + + The 'ACTION...' portion of the packet is a series of actions, + concatenated without separators. Each action has one of the + following forms: + + 'R MASK' + Collect the registers whose bits are set in MASK. MASK is a + hexadecimal number whose I'th bit is set if register number I + should be collected. (The least significant bit is numbered + zero.) Note that MASK may be any number of digits long; it + may not fit in a 32-bit word. + + 'M BASEREG,OFFSET,LEN' + Collect LEN bytes of memory starting at the address in + register number BASEREG, plus OFFSET. If BASEREG is '-1', + then the range has a fixed address: OFFSET is the address of + the lowest byte to collect. The BASEREG, OFFSET, and LEN + parameters are all unsigned hexadecimal values (the '-1' value + for BASEREG is a special case). + + 'X LEN,EXPR' + Evaluate EXPR, whose length is LEN, and collect memory as it + directs. EXPR is an agent expression, as described in *note + Agent Expressions::. Each byte of the expression is encoded + as a two-digit hex number in the packet; LEN is the number of + bytes in the expression (and thus one-half the number of hex + digits in the packet). + + Any number of actions may be packed together in a single 'QTDP' + packet, as long as the packet does not exceed the maximum packet + length (400 bytes, for many stubs). There may be only one 'R' + action per tracepoint, and it must precede any 'M' or 'X' actions. + Any registers referred to by 'M' and 'X' actions must be collected + by a preceding 'R' action. (The "while-stepping" actions are + treated as if they were attached to a separate tracepoint, as far + as these restrictions are concerned.) + + Replies: + 'OK' + The packet was understood and carried out. + 'qRelocInsn' + *Note Relocate instruction reply packet: Tracepoint Packets. + '' + The packet was not recognized. + +'QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES' + Specify a source string of tracepoint N at address ADDR. This is + useful to get accurate reproduction of the tracepoints originally + downloaded at the beginning of the trace run. TYPE is the name of + the tracepoint part, such as 'cond' for the tracepoint's + conditional expression (see below for a list of types), while BYTES + is the string, encoded in hexadecimal. + + START is the offset of the BYTES within the overall source string, + while SLEN is the total length of the source string. This is + intended for handling source strings that are longer than will fit + in a single packet. + + The available string types are 'at' for the location, 'cond' for + the conditional, and 'cmd' for an action command. GDB sends a + separate packet for each command in the action list, in the same + order in which the commands are stored in the list. + + The target does not need to do anything with source strings except + report them back as part of the replies to the 'qTfP'/'qTsP' query + packets. + + Although this packet is optional, and GDB will only send it if the + target replies with 'TracepointSource' *Note General Query + Packets::, it makes both disconnected tracing and trace files much + easier to use. Otherwise the user must be careful that the + tracepoints in effect while looking at trace frames are identical + to the ones in effect during the trace run; even a small + discrepancy could cause 'tdump' not to work, or a particular trace + frame not be found. + +'QTDV:N:VALUE' + Create a new trace state variable, number N, with an initial value + of VALUE, which is a 64-bit signed integer. Both N and VALUE are + encoded as hexadecimal values. GDB has the option of not using + this packet for initial values of zero; the target should simply + create the trace state variables as they are mentioned in + expressions. + +'QTFrame:N' + Select the N'th tracepoint frame from the buffer, and use the + register and memory contents recorded there to answer subsequent + request packets from GDB. + + A successful reply from the stub indicates that the stub has found + the requested frame. The response is a series of parts, + concatenated without separators, describing the frame we selected. + Each part has one of the following forms: + + 'F F' + The selected frame is number N in the trace frame buffer; F is + a hexadecimal number. If F is '-1', then there was no frame + matching the criteria in the request packet. + + 'T T' + The selected trace frame records a hit of tracepoint number T; + T is a hexadecimal number. + +'QTFrame:pc:ADDR' + Like 'QTFrame:N', but select the first tracepoint frame after the + currently selected frame whose PC is ADDR; ADDR is a hexadecimal + number. + +'QTFrame:tdp:T' + Like 'QTFrame:N', but select the first tracepoint frame after the + currently selected frame that is a hit of tracepoint T; T is a + hexadecimal number. + +'QTFrame:range:START:END' + Like 'QTFrame:N', but select the first tracepoint frame after the + currently selected frame whose PC is between START (inclusive) and + END (inclusive); START and END are hexadecimal numbers. + +'QTFrame:outside:START:END' + Like 'QTFrame:range:START:END', but select the first frame + _outside_ the given range of addresses (exclusive). + +'qTMinFTPILen' + This packet requests the minimum length of instruction at which a + fast tracepoint (*note Set Tracepoints::) may be placed. For + instance, on the 32-bit x86 architecture, it is possible to use a + 4-byte jump, but it depends on the target system being able to + create trampolines in the first 64K of memory, which might or might + not be possible for that system. So the reply to this packet will + be 4 if it is able to arrange for that. + + Replies: + + '0' + The minimum instruction length is currently unknown. + 'LENGTH' + The minimum instruction length is LENGTH, where LENGTH is + greater or equal to 1. LENGTH is a hexadecimal number. A + reply of 1 means that a fast tracepoint may be placed on any + instruction regardless of size. + 'E' + An error has occurred. + '' + An empty reply indicates that the request is not supported by + the stub. + +'QTStart' + Begin the tracepoint experiment. Begin collecting data from + tracepoint hits in the trace frame buffer. This packet supports + the 'qRelocInsn' reply (*note Relocate instruction reply packet: + Tracepoint Packets.). + +'QTStop' + End the tracepoint experiment. Stop collecting trace frames. + +'QTEnable:N:ADDR' + Enable tracepoint N at address ADDR in a started tracepoint + experiment. If the tracepoint was previously disabled, then + collection of data from it will resume. + +'QTDisable:N:ADDR' + Disable tracepoint N at address ADDR in a started tracepoint + experiment. No more data will be collected from the tracepoint + unless 'QTEnable:N:ADDR' is subsequently issued. + +'QTinit' + Clear the table of tracepoints, and empty the trace frame buffer. + +'QTro:START1,END1:START2,END2:...' + Establish the given ranges of memory as "transparent". The stub + will answer requests for these ranges from memory's current + contents, if they were not collected as part of the tracepoint hit. + + GDB uses this to mark read-only regions of memory, like those + containing program code. Since these areas never change, they + should still have the same contents they did when the tracepoint + was hit, so there's no reason for the stub to refuse to provide + their contents. + +'QTDisconnected:VALUE' + Set the choice to what to do with the tracing run when GDB + disconnects from the target. A VALUE of 1 directs the target to + continue the tracing run, while 0 tells the target to stop tracing + if GDB is no longer in the picture. + +'qTStatus' + Ask the stub if there is a trace experiment running right now. + + The reply has the form: + + 'TRUNNING[;FIELD]...' + RUNNING is a single digit '1' if the trace is presently + running, or '0' if not. It is followed by semicolon-separated + optional fields that an agent may use to report additional + status. + + If the trace is not running, the agent may report any of several + explanations as one of the optional fields: + + 'tnotrun:0' + No trace has been run yet. + + 'tstop[:TEXT]:0' + The trace was stopped by a user-originated stop command. The + optional TEXT field is a user-supplied string supplied as part + of the stop command (for instance, an explanation of why the + trace was stopped manually). It is hex-encoded. + + 'tfull:0' + The trace stopped because the trace buffer filled up. + + 'tdisconnected:0' + The trace stopped because GDB disconnected from the target. + + 'tpasscount:TPNUM' + The trace stopped because tracepoint TPNUM exceeded its pass + count. + + 'terror:TEXT:TPNUM' + The trace stopped because tracepoint TPNUM had an error. The + string TEXT is available to describe the nature of the error + (for instance, a divide by zero in the condition expression). + TEXT is hex encoded. + + 'tunknown:0' + The trace stopped for some other reason. + + Additional optional fields supply statistical and other + information. Although not required, they are extremely useful for + users monitoring the progress of a trace run. If a trace has + stopped, and these numbers are reported, they must reflect the + state of the just-stopped trace. + + 'tframes:N' + The number of trace frames in the buffer. + + 'tcreated:N' + The total number of trace frames created during the run. This + may be larger than the trace frame count, if the buffer is + circular. + + 'tsize:N' + The total size of the trace buffer, in bytes. + + 'tfree:N' + The number of bytes still unused in the buffer. + + 'circular:N' + The value of the circular trace buffer flag. '1' means that + the trace buffer is circular and old trace frames will be + discarded if necessary to make room, '0' means that the trace + buffer is linear and may fill up. + + 'disconn:N' + The value of the disconnected tracing flag. '1' means that + tracing will continue after GDB disconnects, '0' means that + the trace run will stop. + +'qTP:TP:ADDR' + Ask the stub for the current state of tracepoint number TP at + address ADDR. + + Replies: + 'VHITS:USAGE' + The tracepoint has been hit HITS times so far during the trace + run, and accounts for USAGE in the trace buffer. Note that + 'while-stepping' steps are not counted as separate hits, but + the steps' space consumption is added into the usage number. + +'qTV:VAR' + Ask the stub for the value of the trace state variable number VAR. + + Replies: + 'VVALUE' + The value of the variable is VALUE. This will be the current + value of the variable if the user is examining a running + target, or a saved value if the variable was collected in the + trace frame that the user is looking at. Note that multiple + requests may result in different reply values, such as when + requesting values while the program is running. + + 'U' + The value of the variable is unknown. This would occur, for + example, if the user is examining a trace frame in which the + requested variable was not collected. + +'qTfP' +'qTsP' + These packets request data about tracepoints that are being used by + the target. GDB sends 'qTfP' to get the first piece of data, and + multiple 'qTsP' to get additional pieces. Replies to these packets + generally take the form of the 'QTDP' packets that define + tracepoints. (FIXME add detailed syntax) + +'qTfV' +'qTsV' + These packets request data about trace state variables that are on + the target. GDB sends 'qTfV' to get the first vari of data, and + multiple 'qTsV' to get additional variables. Replies to these + packets follow the syntax of the 'QTDV' packets that define trace + state variables. + +'qTfSTM' +'qTsSTM' + These packets request data about static tracepoint markers that + exist in the target program. GDB sends 'qTfSTM' to get the first + piece of data, and multiple 'qTsSTM' to get additional pieces. + Replies to these packets take the following form: + + Reply: + 'm ADDRESS:ID:EXTRA' + A single marker + 'm ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...' + a comma-separated list of markers + 'l' + (lower case letter 'L') denotes end of list. + 'E NN' + An error occurred. NN are hex digits. + '' + An empty reply indicates that the request is not supported by + the stub. + + ADDRESS is encoded in hex. ID and EXTRA are strings encoded in + hex. + + In response to each query, the target will reply with a list of one + or more markers, separated by commas. GDB will respond to each + reply with a request for more markers (using the 'qs' form of the + query), until the target responds with 'l' (lower-case ell, for + "last"). + +'qTSTMat:ADDRESS' + This packets requests data about static tracepoint markers in the + target program at ADDRESS. Replies to this packet follow the + syntax of the 'qTfSTM' and 'qTsSTM' packets that list static + tracepoint markers. + +'QTSave:FILENAME' + This packet directs the target to save trace data to the file name + FILENAME in the target's filesystem. FILENAME is encoded as a hex + string; the interpretation of the file name (relative vs absolute, + wild cards, etc) is up to the target. + +'qTBuffer:OFFSET,LEN' + Return up to LEN bytes of the current contents of trace buffer, + starting at OFFSET. The trace buffer is treated as if it were a + contiguous collection of traceframes, as per the trace file format. + The reply consists as many hex-encoded bytes as the target can + deliver in a packet; it is not an error to return fewer than were + asked for. A reply consisting of just 'l' indicates that no bytes + are available. + +'QTBuffer:circular:VALUE' + This packet directs the target to use a circular trace buffer if + VALUE is 1, or a linear buffer if the value is 0. + +'QTBuffer:size:SIZE' + This packet directs the target to make the trace buffer be of size + SIZE if possible. A value of '-1' tells the target to use whatever + size it prefers. + +'QTNotes:[TYPE:TEXT][;TYPE:TEXT]...' + This packet adds optional textual notes to the trace run. + Allowable types include 'user', 'notes', and 'tstop', the TEXT + fields are arbitrary strings, hex-encoded. + +E.6.1 Relocate instruction reply packet +--------------------------------------- + +When installing fast tracepoints in memory, the target may need to +relocate the instruction currently at the tracepoint address to a +different address in memory. For most instructions, a simple copy is +enough, but, for example, call instructions that implicitly push the +return address on the stack, and relative branches or other PC-relative +instructions require offset adjustment, so that the effect of executing +the instruction at a different address is the same as if it had executed +in the original location. + + In response to several of the tracepoint packets, the target may also +respond with a number of intermediate 'qRelocInsn' request packets +before the final result packet, to have GDB handle this relocation +operation. If a packet supports this mechanism, its documentation will +explicitly say so. See for example the above descriptions for the +'QTStart' and 'QTDP' packets. The format of the request is: + +'qRelocInsn:FROM;TO' + + This requests GDB to copy instruction at address FROM to address + TO, possibly adjusted so that executing the instruction at TO has + the same effect as executing it at FROM. GDB writes the adjusted + instruction to target memory starting at TO. + + Replies: +'qRelocInsn:ADJUSTED_SIZE' + Informs the stub the relocation is complete. ADJUSTED_SIZE is the + length in bytes of resulting relocated instruction sequence. +'E NN' + A badly formed request was detected, or an error was encountered + while relocating the instruction. + + +File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol + +E.7 Host I/O Packets +==================== + +The "Host I/O" packets allow GDB to perform I/O operations on the far +side of a remote link. For example, Host I/O is used to upload and +download files to a remote target with its own filesystem. Host I/O +uses the same constant values and data structure layout as the +target-initiated File-I/O protocol. However, the Host I/O packets are +structured differently. The target-initiated protocol relies on target +memory to store parameters and buffers. Host I/O requests are initiated +by GDB, and the target's memory is not involved. *Note File-I/O Remote +Protocol Extension::, for more details on the target-initiated protocol. + + The Host I/O request packets all encode a single operation along with +its arguments. They have this format: + +'vFile:OPERATION: PARAMETER...' + OPERATION is the name of the particular request; the target should + compare the entire packet name up to the second colon when checking + for a supported operation. The format of PARAMETER depends on the + operation. Numbers are always passed in hexadecimal. Negative + numbers have an explicit minus sign (i.e. two's complement is not + used). Strings (e.g. filenames) are encoded as a series of + hexadecimal bytes. The last argument to a system call may be a + buffer of escaped binary data (*note Binary Data::). + + The valid responses to Host I/O packets are: + +'F RESULT [, ERRNO] [; ATTACHMENT]' + RESULT is the integer value returned by this operation, usually + non-negative for success and -1 for errors. If an error has + occured, ERRNO will be included in the result. ERRNO will have a + value defined by the File-I/O protocol (*note Errno Values::). For + operations which return data, ATTACHMENT supplies the data as a + binary buffer. Binary buffers in response packets are escaped in + the normal way (*note Binary Data::). See the individual packet + documentation for the interpretation of RESULT and ATTACHMENT. + +'' + An empty response indicates that this operation is not recognized. + + These are the supported Host I/O operations: + +'vFile:open: PATHNAME, FLAGS, MODE' + Open a file at PATHNAME and return a file descriptor for it, or + return -1 if an error occurs. PATHNAME is a string, FLAGS is an + integer indicating a mask of open flags (*note Open Flags::), and + MODE is an integer indicating a mask of mode bits to use if the + file is created (*note mode_t Values::). *Note open::, for details + of the open flags and mode values. + +'vFile:close: FD' + Close the open file corresponding to FD and return 0, or -1 if an + error occurs. + +'vFile:pread: FD, COUNT, OFFSET' + Read data from the open file corresponding to FD. Up to COUNT + bytes will be read from the file, starting at OFFSET relative to + the start of the file. The target may read fewer bytes; common + reasons include packet size limits and an end-of-file condition. + The number of bytes read is returned. Zero should only be returned + for a successful read at the end of the file, or if COUNT was zero. + + The data read should be returned as a binary attachment on success. + If zero bytes were read, the response should include an empty + binary attachment (i.e. a trailing semicolon). The return value is + the number of target bytes read; the binary attachment may be + longer if some characters were escaped. + +'vFile:pwrite: FD, OFFSET, DATA' + Write DATA (a binary buffer) to the open file corresponding to FD. + Start the write at OFFSET from the start of the file. Unlike many + 'write' system calls, there is no separate COUNT argument; the + length of DATA in the packet is used. 'vFile:write' returns the + number of bytes written, which may be shorter than the length of + DATA, or -1 if an error occurred. + +'vFile:unlink: PATHNAME' + Delete the file at PATHNAME on the target. Return 0, or -1 if an + error occurs. PATHNAME is a string. + +'vFile:readlink: FILENAME' + Read value of symbolic link FILENAME on the target. Return the + number of bytes read, or -1 if an error occurs. + + The data read should be returned as a binary attachment on success. + If zero bytes were read, the response should include an empty + binary attachment (i.e. a trailing semicolon). The return value is + the number of target bytes read; the binary attachment may be + longer if some characters were escaped. + + +File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol + +E.8 Interrupts +============== + +When a program on the remote target is running, GDB may attempt to +interrupt it by sending a 'Ctrl-C', 'BREAK' or a 'BREAK' followed by +'g', control of which is specified via GDB's 'interrupt-sequence'. + + The precise meaning of 'BREAK' is defined by the transport mechanism +and may, in fact, be undefined. GDB does not currently define a 'BREAK' +mechanism for any of the network interfaces except for TCP, in which +case GDB sends the 'telnet' BREAK sequence. + + 'Ctrl-C', on the other hand, is defined and implemented for all +transport mechanisms. It is represented by sending the single byte +'0x03' without any of the usual packet overhead described in the +Overview section (*note Overview::). When a '0x03' byte is transmitted +as part of a packet, it is considered to be packet data and does _not_ +represent an interrupt. E.g., an 'X' packet (*note X packet::), used +for binary downloads, may include an unescaped '0x03' as part of its +packet. + + 'BREAK' followed by 'g' is also known as Magic SysRq g. When Linux +kernel receives this sequence from serial port, it stops execution and +connects to gdb. + + Stubs are not required to recognize these interrupt mechanisms and +the precise meaning associated with receipt of the interrupt is +implementation defined. If the target supports debugging of multiple +threads and/or processes, it should attempt to interrupt all +currently-executing threads and processes. If the stub is successful at +interrupting the running program, it should send one of the stop reply +packets (*note Stop Reply Packets::) to GDB as a result of successfully +stopping the program in all-stop mode, and a stop reply for each stopped +thread in non-stop mode. Interrupts received while the program is +stopped are discarded. + + +File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol + +E.9 Notification Packets +======================== + +The GDB remote serial protocol includes "notifications", packets that +require no acknowledgment. Both the GDB and the stub may send +notifications (although the only notifications defined at present are +sent by the stub). Notifications carry information without incurring +the round-trip latency of an acknowledgment, and so are useful for +low-impact communications where occasional packet loss is not a problem. + + A notification packet has the form '% DATA # CHECKSUM', where DATA is +the content of the notification, and CHECKSUM is a checksum of DATA, +computed and formatted as for ordinary GDB packets. A notification's +DATA never contains '$', '%' or '#' characters. Upon receiving a +notification, the recipient sends no '+' or '-' to acknowledge the +notification's receipt or to report its corruption. + + Every notification's DATA begins with a name, which contains no colon +characters, followed by a colon character. + + Recipients should silently ignore corrupted notifications and +notifications they do not understand. Recipients should restart timeout +periods on receipt of a well-formed notification, whether or not they +understand it. + + Senders should only send the notifications described here when this +protocol description specifies that they are permitted. In the future, +we may extend the protocol to permit existing notifications in new +contexts; this rule helps older senders avoid confusing newer +recipients. + + (Older versions of GDB ignore bytes received until they see the '$' +byte that begins an ordinary packet, so new stubs may transmit +notifications without fear of confusing older clients. There are no +notifications defined for GDB to send at the moment, but we assume that +most older stubs would ignore them, as well.) + + Each notification is comprised of three parts: +'NAME:EVENT' + The notification packet is sent by the side that initiates the + exchange (currently, only the stub does that), with EVENT carrying + the specific information about the notification. NAME is the name + of the notification. +'ACK' + The acknowledge sent by the other side, usually GDB, to acknowledge + the exchange and request the event. + + The purpose of an asynchronous notification mechanism is to report to +GDB that something interesting happened in the remote stub. + + The remote stub may send notification NAME:EVENT at any time, but GDB +acknowledges the notification when appropriate. The notification event +is pending before GDB acknowledges. Only one notification at a time may +be pending; if additional events occur before GDB has acknowledged the +previous notification, they must be queued by the stub for later +synchronous transmission in response to ACK packets from GDB. Because +the notification mechanism is unreliable, the stub is permitted to +resend a notification if it believes GDB may not have received it. + + Specifically, notifications may appear when GDB is not otherwise +reading input from the stub, or when GDB is expecting to read a normal +synchronous response or a '+'/'-' acknowledgment to a packet it has +sent. Notification packets are distinct from any other communication +from the stub so there is no ambiguity. + + After receiving a notification, GDB shall acknowledge it by sending a +ACK packet as a regular, synchronous request to the stub. Such +acknowledgment is not required to happen immediately, as GDB is +permitted to send other, unrelated packets to the stub first, which the +stub should process normally. + + Upon receiving a ACK packet, if the stub has other queued events to +report to GDB, it shall respond by sending a normal EVENT. GDB shall +then send another ACK packet to solicit further responses; again, it is +permitted to send other, unrelated packets as well which the stub should +process normally. + + If the stub receives a ACK packet and there are no additional EVENT +to report, the stub shall return an 'OK' response. At this point, GDB +has finished processing a notification and the stub has completed +sending any queued events. GDB won't accept any new notifications until +the final 'OK' is received . If further notification events occur, the +stub shall send a new notification, GDB shall accept the notification, +and the process shall be repeated. + + The process of asynchronous notification can be illustrated by the +following example: + <- %%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0; + ... + -> vStopped + <- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0; + -> vStopped + <- T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0; + -> vStopped + <- OK + + The following notifications are defined: + +NotificationAck Event Description + +Stop vStopped REPLY. The REPLY has the Report an asynchronous + form of a stop reply, as stop event in non-stop + described in *note Stop mode. + Reply Packets::. Refer + to *note Remote + Non-Stop::, for + information on how these + notifications are + acknowledged by GDB. + + +File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol + +E.10 Remote Protocol Support for Non-Stop Mode +============================================== + +GDB's remote protocol supports non-stop debugging of multi-threaded +programs, as described in *note Non-Stop Mode::. If the stub supports +non-stop mode, it should report that to GDB by including 'QNonStop+' in +its 'qSupported' response (*note qSupported::). + + GDB typically sends a 'QNonStop' packet only when establishing a new +connection with the stub. Entering non-stop mode does not alter the +state of any currently-running threads, but targets must stop all +threads in any already-attached processes when entering all-stop mode. +GDB uses the '?' packet as necessary to probe the target state after a +mode change. + + In non-stop mode, when an attached process encounters an event that +would otherwise be reported with a stop reply, it uses the asynchronous +notification mechanism (*note Notification Packets::) to inform GDB. In +contrast to all-stop mode, where all threads in all processes are +stopped when a stop reply is sent, in non-stop mode only the thread +reporting the stop event is stopped. That is, when reporting a 'S' or +'T' response to indicate completion of a step operation, hitting a +breakpoint, or a fault, only the affected thread is stopped; any other +still-running threads continue to run. When reporting a 'W' or 'X' +response, all running threads belonging to other attached processes +continue to run. + + In non-stop mode, the target shall respond to the '?' packet as +follows. First, any incomplete stop reply notification/'vStopped' +sequence in progress is abandoned. The target must begin a new sequence +reporting stop events for all stopped threads, whether or not it has +previously reported those events to GDB. The first stop reply is sent +as a synchronous reply to the '?' packet, and subsequent stop replies +are sent as responses to 'vStopped' packets using the mechanism +described above. The target must not send asynchronous stop reply +notifications until the sequence is complete. If all threads are +running when the target receives the '?' packet, or if the target is not +attached to any process, it shall respond 'OK'. + + +File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol + +E.11 Packet Acknowledgment +========================== + +By default, when either the host or the target machine receives a +packet, the first response expected is an acknowledgment: either '+' (to +indicate the package was received correctly) or '-' (to request +retransmission). This mechanism allows the GDB remote protocol to +operate over unreliable transport mechanisms, such as a serial line. + + In cases where the transport mechanism is itself reliable (such as a +pipe or TCP connection), the '+'/'-' acknowledgments are redundant. It +may be desirable to disable them in that case to reduce communication +overhead, or for other reasons. This can be accomplished by means of +the 'QStartNoAckMode' packet; *note QStartNoAckMode::. + + When in no-acknowledgment mode, neither the stub nor GDB shall send +or expect '+'/'-' protocol acknowledgments. The packet and response +format still includes the normal checksum, as described in *note +Overview::, but the checksum may be ignored by the receiver. + + If the stub supports 'QStartNoAckMode' and prefers to operate in +no-acknowledgment mode, it should report that to GDB by including +'QStartNoAckMode+' in its response to 'qSupported'; *note qSupported::. +If GDB also supports 'QStartNoAckMode' and it has not been disabled via +the 'set remote noack-packet off' command (*note Remote +Configuration::), GDB may then send a 'QStartNoAckMode' packet to the +stub. Only then may the stub actually turn off packet acknowledgments. +GDB sends a final '+' acknowledgment of the stub's 'OK' response, which +can be safely ignored by the stub. + + Note that 'set remote noack-packet' command only affects negotiation +between GDB and the stub when subsequent connections are made; it does +not affect the protocol acknowledgment state for any current connection. +Since '+'/'-' acknowledgments are enabled by default when a new +connection is established, there is also no protocol request to +re-enable the acknowledgments for the current connection, once disabled. + + +File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol + +E.12 Examples +============= + +Example sequence of a target being re-started. Notice how the restart +does not get any direct output: + + -> R00 + <- + + _target restarts_ + -> ? + <- + + <- T001:1234123412341234 + -> + + + Example sequence of a target being stepped by a single instruction: + + -> G1445... + <- + + -> s + <- + + _time passes_ + <- T001:1234123412341234 + -> + + -> g + <- + + <- 1455... + -> + + + +File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol + +E.13 File-I/O Remote Protocol Extension +======================================= + +* Menu: + +* File-I/O Overview:: +* Protocol Basics:: +* The F Request Packet:: +* The F Reply Packet:: +* The Ctrl-C Message:: +* Console I/O:: +* List of Supported Calls:: +* Protocol-specific Representation of Datatypes:: +* Constants:: +* File-I/O Examples:: + + +File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension + +E.13.1 File-I/O Overview +------------------------ + +The "File I/O remote protocol extension" (short: File-I/O) allows the +target to use the host's file system and console I/O to perform various +system calls. System calls on the target system are translated into a +remote protocol packet to the host system, which then performs the +needed actions and returns a response packet to the target system. This +simulates file system operations even on targets that lack file systems. + + The protocol is defined to be independent of both the host and target +systems. It uses its own internal representation of datatypes and +values. Both GDB and the target's GDB stub are responsible for +translating the system-dependent value representations into the internal +protocol representations when data is transmitted. + + The communication is synchronous. A system call is possible only +when GDB is waiting for a response from the 'C', 'c', 'S' or 's' +packets. While GDB handles the request for a system call, the target is +stopped to allow deterministic access to the target's memory. Therefore +File-I/O is not interruptible by target signals. On the other hand, it +is possible to interrupt File-I/O by a user interrupt ('Ctrl-C') within +GDB. + + The target's request to perform a host system call does not finish +the latest 'C', 'c', 'S' or 's' action. That means, after finishing the +system call, the target returns to continuing the previous activity +(continue, step). No additional continue or step request from GDB is +required. + + (gdb) continue + <- target requests 'system call X' + target is stopped, GDB executes system call + -> GDB returns result + ... target continues, GDB returns to wait for the target + <- target hits breakpoint and sends a Txx packet + + The protocol only supports I/O on the console and to regular files on +the host file system. Character or block special devices, pipes, named +pipes, sockets or any other communication method on the host system are +not supported by this protocol. + + File I/O is not supported in non-stop mode. + + +File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension + +E.13.2 Protocol Basics +---------------------- + +The File-I/O protocol uses the 'F' packet as the request as well as +reply packet. Since a File-I/O system call can only occur when GDB is +waiting for a response from the continuing or stepping target, the +File-I/O request is a reply that GDB has to expect as a result of a +previous 'C', 'c', 'S' or 's' packet. This 'F' packet contains all +information needed to allow GDB to call the appropriate host system +call: + + * A unique identifier for the requested system call. + + * All parameters to the system call. Pointers are given as addresses + in the target memory address space. Pointers to strings are given + as pointer/length pair. Numerical values are given as they are. + Numerical control flags are given in a protocol-specific + representation. + + At this point, GDB has to perform the following actions. + + * If the parameters include pointer values to data needed as input to + a system call, GDB requests this data from the target with a + standard 'm' packet request. This additional communication has to + be expected by the target implementation and is handled as any + other 'm' packet. + + * GDB translates all value from protocol representation to host + representation as needed. Datatypes are coerced into the host + types. + + * GDB calls the system call. + + * It then coerces datatypes back to protocol representation. + + * If the system call is expected to return data in buffer space + specified by pointer parameters to the call, the data is + transmitted to the target using a 'M' or 'X' packet. This packet + has to be expected by the target implementation and is handled as + any other 'M' or 'X' packet. + + Eventually GDB replies with another 'F' packet which contains all +necessary information for the target to continue. This at least +contains + + * Return value. + + * 'errno', if has been changed by the system call. + + * "Ctrl-C" flag. + + After having done the needed type and value coercion, the target +continues the latest continue or step action. + + +File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension + +E.13.3 The 'F' Request Packet +----------------------------- + +The 'F' request packet has the following format: + +'FCALL-ID,PARAMETER...' + + CALL-ID is the identifier to indicate the host system call to be + called. This is just the name of the function. + + PARAMETER... are the parameters to the system call. Parameters are + hexadecimal integer values, either the actual values in case of + scalar datatypes, pointers to target buffer space in case of + compound datatypes and unspecified memory areas, or pointer/length + pairs in case of string parameters. These are appended to the + CALL-ID as a comma-delimited list. All values are transmitted in + ASCII string representation, pointer/length pairs separated by a + slash. + + +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 + +E.13.4 The 'F' Reply Packet +--------------------------- + +The 'F' reply packet has the following format: + +'FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT' + + RETCODE is the return code of the system call as hexadecimal value. + + ERRNO is the 'errno' set by the call, in protocol-specific + representation. This parameter can be omitted if the call was + successful. + + CTRL-C FLAG is only sent if the user requested a break. In this + case, ERRNO must be sent as well, even if the call was successful. + The CTRL-C FLAG itself consists of the character 'C': + + F0,0,C + + or, if the call was interrupted before the host call has been + performed: + + F-1,4,C + + assuming 4 is the protocol-specific representation of 'EINTR'. + + +File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension + +E.13.5 The 'Ctrl-C' Message +--------------------------- + +If the 'Ctrl-C' flag is set in the GDB reply packet (*note The F Reply +Packet::), the target should behave as if it had gotten a break message. +The meaning for the target is "system call interrupted by 'SIGINT'". +Consequentially, the target should actually stop (as with a break +message) and return to GDB with a 'T02' packet. + + It's important for the target to know in which state the system call +was interrupted. There are two possible cases: + + * The system call hasn't been performed on the host yet. + + * The system call on the host has been finished. + + These two states can be distinguished by the target by the value of +the returned 'errno'. If it's the protocol representation of 'EINTR', +the system call hasn't been performed. This is equivalent to the +'EINTR' handling on POSIX systems. In any other case, the target may +presume that the system call has been finished -- successfully or not -- +and should behave as if the break message arrived right after the system +call. + + GDB must behave reliably. If the system call has not been called +yet, GDB may send the 'F' reply immediately, setting 'EINTR' as 'errno' +in the packet. If the system call on the host has been finished before +the user requests a break, the full action must be finished by GDB. +This requires sending 'M' or 'X' packets as necessary. The 'F' packet +may only be sent when either nothing has happened or the full action has +been completed. + + +File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension + +E.13.6 Console I/O +------------------ + +By default and if not explicitly closed by the target system, the file +descriptors 0, 1 and 2 are connected to the GDB console. Output on the +GDB console is handled as any other file output operation ('write(1, +...)' or 'write(2, ...)'). Console input is handled by GDB so that +after the target read request from file descriptor 0 all following +typing is buffered until either one of the following conditions is met: + + * The user types 'Ctrl-c'. The behaviour is as explained above, and + the 'read' system call is treated as finished. + + * The user presses . This is treated as end of input with a + trailing newline. + + * The user types 'Ctrl-d'. This is treated as end of input. No + trailing character (neither newline nor 'Ctrl-D') is appended to + the input. + + If the user has typed more characters than fit in the buffer given to +the 'read' call, the trailing characters are buffered in GDB until +either another 'read(0, ...)' is requested by the target, or debugging +is stopped at the user's request. + + +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 + +E.13.7 List of Supported Calls +------------------------------ + +* Menu: + +* open:: +* close:: +* read:: +* write:: +* lseek:: +* rename:: +* unlink:: +* stat/fstat:: +* gettimeofday:: +* isatty:: +* system:: + + +File: gdb.info, Node: open, Next: close, Up: List of Supported Calls + +open +.... + +Synopsis: + int open(const char *pathname, int flags); + int open(const char *pathname, int flags, mode_t mode); + +Request: + 'Fopen,PATHPTR/LEN,FLAGS,MODE' + + FLAGS is the bitwise 'OR' of the following values: + + 'O_CREAT' + If the file does not exist it will be created. The host rules + apply as far as file ownership and time stamps are concerned. + + 'O_EXCL' + When used with 'O_CREAT', if the file already exists it is an + error and open() fails. + + 'O_TRUNC' + If the file already exists and the open mode allows writing + ('O_RDWR' or 'O_WRONLY' is given) it will be truncated to zero + length. + + 'O_APPEND' + The file is opened in append mode. + + 'O_RDONLY' + The file is opened for reading only. + + 'O_WRONLY' + The file is opened for writing only. + + 'O_RDWR' + The file is opened for reading and writing. + + Other bits are silently ignored. + + MODE is the bitwise 'OR' of the following values: + + 'S_IRUSR' + User has read permission. + + 'S_IWUSR' + User has write permission. + + 'S_IRGRP' + Group has read permission. + + 'S_IWGRP' + Group has write permission. + + 'S_IROTH' + Others have read permission. + + 'S_IWOTH' + Others have write permission. + + Other bits are silently ignored. + +Return value: + 'open' returns the new file descriptor or -1 if an error occurred. + +Errors: + + 'EEXIST' + PATHNAME already exists and 'O_CREAT' and 'O_EXCL' were used. + + 'EISDIR' + PATHNAME refers to a directory. + + 'EACCES' + The requested access is not allowed. + + 'ENAMETOOLONG' + PATHNAME was too long. + + 'ENOENT' + A directory component in PATHNAME does not exist. + + 'ENODEV' + PATHNAME refers to a device, pipe, named pipe or socket. + + 'EROFS' + PATHNAME refers to a file on a read-only filesystem and write + access was requested. + + 'EFAULT' + PATHNAME is an invalid pointer value. + + 'ENOSPC' + No space on device to create the file. + + 'EMFILE' + The process already has the maximum number of files open. + + 'ENFILE' + The limit on the total number of files open on the system has + been reached. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls + +close +..... + +Synopsis: + int close(int fd); + +Request: + 'Fclose,FD' + +Return value: + 'close' returns zero on success, or -1 if an error occurred. + +Errors: + + 'EBADF' + FD isn't a valid open file descriptor. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls + +read +.... + +Synopsis: + int read(int fd, void *buf, unsigned int count); + +Request: + 'Fread,FD,BUFPTR,COUNT' + +Return value: + On success, the number of bytes read is returned. Zero indicates + end of file. If count is zero, read returns zero as well. On + error, -1 is returned. + +Errors: + + 'EBADF' + FD is not a valid file descriptor or is not open for reading. + + 'EFAULT' + BUFPTR is an invalid pointer value. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls + +write +..... + +Synopsis: + int write(int fd, const void *buf, unsigned int count); + +Request: + 'Fwrite,FD,BUFPTR,COUNT' + +Return value: + On success, the number of bytes written are returned. Zero + indicates nothing was written. On error, -1 is returned. + +Errors: + + 'EBADF' + FD is not a valid file descriptor or is not open for writing. + + 'EFAULT' + BUFPTR is an invalid pointer value. + + 'EFBIG' + An attempt was made to write a file that exceeds the + host-specific maximum file size allowed. + + 'ENOSPC' + No space on device to write the data. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls + +lseek +..... + +Synopsis: + long lseek (int fd, long offset, int flag); + +Request: + 'Flseek,FD,OFFSET,FLAG' + + FLAG is one of: + + 'SEEK_SET' + The offset is set to OFFSET bytes. + + 'SEEK_CUR' + The offset is set to its current location plus OFFSET bytes. + + 'SEEK_END' + The offset is set to the size of the file plus OFFSET bytes. + +Return value: + On success, the resulting unsigned offset in bytes from the + beginning of the file is returned. Otherwise, a value of -1 is + returned. + +Errors: + + 'EBADF' + FD is not a valid open file descriptor. + + 'ESPIPE' + FD is associated with the GDB console. + + 'EINVAL' + FLAG is not a proper value. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls + +rename +...... + +Synopsis: + int rename(const char *oldpath, const char *newpath); + +Request: + 'Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN' + +Return value: + On success, zero is returned. On error, -1 is returned. + +Errors: + + 'EISDIR' + NEWPATH is an existing directory, but OLDPATH is not a + directory. + + 'EEXIST' + NEWPATH is a non-empty directory. + + 'EBUSY' + OLDPATH or NEWPATH is a directory that is in use by some + process. + + 'EINVAL' + An attempt was made to make a directory a subdirectory of + itself. + + 'ENOTDIR' + A component used as a directory in OLDPATH or new path is not + a directory. Or OLDPATH is a directory and NEWPATH exists but + is not a directory. + + 'EFAULT' + OLDPATHPTR or NEWPATHPTR are invalid pointer values. + + 'EACCES' + No access to the file or the path of the file. + + 'ENAMETOOLONG' + + OLDPATH or NEWPATH was too long. + + 'ENOENT' + A directory component in OLDPATH or NEWPATH does not exist. + + 'EROFS' + The file is on a read-only filesystem. + + 'ENOSPC' + The device containing the file has no room for the new + directory entry. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls + +unlink +...... + +Synopsis: + int unlink(const char *pathname); + +Request: + 'Funlink,PATHNAMEPTR/LEN' + +Return value: + On success, zero is returned. On error, -1 is returned. + +Errors: + + 'EACCES' + No access to the file or the path of the file. + + 'EPERM' + The system does not allow unlinking of directories. + + 'EBUSY' + The file PATHNAME cannot be unlinked because it's being used + by another process. + + 'EFAULT' + PATHNAMEPTR is an invalid pointer value. + + 'ENAMETOOLONG' + PATHNAME was too long. + + 'ENOENT' + A directory component in PATHNAME does not exist. + + 'ENOTDIR' + A component of the path is not a directory. + + 'EROFS' + The file is on a read-only filesystem. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls + +stat/fstat +.......... + +Synopsis: + int stat(const char *pathname, struct stat *buf); + int fstat(int fd, struct stat *buf); + +Request: + 'Fstat,PATHNAMEPTR/LEN,BUFPTR' + 'Ffstat,FD,BUFPTR' + +Return value: + On success, zero is returned. On error, -1 is returned. + +Errors: + + 'EBADF' + FD is not a valid open file. + + 'ENOENT' + A directory component in PATHNAME does not exist or the path + is an empty string. + + 'ENOTDIR' + A component of the path is not a directory. + + 'EFAULT' + PATHNAMEPTR is an invalid pointer value. + + 'EACCES' + No access to the file or the path of the file. + + 'ENAMETOOLONG' + PATHNAME was too long. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls + +gettimeofday +............ + +Synopsis: + int gettimeofday(struct timeval *tv, void *tz); + +Request: + 'Fgettimeofday,TVPTR,TZPTR' + +Return value: + On success, 0 is returned, -1 otherwise. + +Errors: + + 'EINVAL' + TZ is a non-NULL pointer. + + 'EFAULT' + TVPTR and/or TZPTR is an invalid pointer value. + + +File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls + +isatty +...... + +Synopsis: + int isatty(int fd); + +Request: + 'Fisatty,FD' + +Return value: + Returns 1 if FD refers to the GDB console, 0 otherwise. + +Errors: + + 'EINTR' + The call was interrupted by the user. + + Note that the 'isatty' call is treated as a special case: it returns +1 to the target if the file descriptor is attached to the GDB console, 0 +otherwise. Implementing through system calls would require implementing +'ioctl' and would be more complex than needed. + + +File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls + +system +...... + +Synopsis: + int system(const char *command); + +Request: + 'Fsystem,COMMANDPTR/LEN' + +Return value: + If LEN is zero, the return value indicates whether a shell is + available. A zero return value indicates a shell is not available. + For non-zero LEN, the value returned is -1 on error and the return + status of the command otherwise. Only the exit status of the + command is returned, which is extracted from the host's 'system' + return value by calling 'WEXITSTATUS(retval)'. In case '/bin/sh' + could not be executed, 127 is returned. + +Errors: + + 'EINTR' + The call was interrupted by the user. + + GDB takes over the full task of calling the necessary host calls to +perform the 'system' call. The return value of 'system' on the host is +simplified before it's returned to the target. Any termination signal +information from the child process is discarded, and the return value +consists entirely of the exit status of the called command. + + Due to security concerns, the 'system' call is by default refused by +GDB. The user has to allow this call explicitly with the 'set remote +system-call-allowed 1' command. + +'set remote system-call-allowed' + Control whether to allow the 'system' calls in the File I/O + protocol for the remote target. The default is zero (disabled). + +'show remote system-call-allowed' + Show whether the 'system' calls are allowed in the File I/O + protocol. + + +File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension + +E.13.8 Protocol-specific Representation of Datatypes +---------------------------------------------------- + +* Menu: + +* Integral Datatypes:: +* Pointer Values:: +* Memory Transfer:: +* struct stat:: +* struct timeval:: + + +File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes + +Integral Datatypes +.................. + +The integral datatypes used in the system calls are 'int', 'unsigned +int', 'long', 'unsigned long', 'mode_t', and 'time_t'. + + 'int', 'unsigned int', 'mode_t' and 'time_t' are implemented as 32 +bit values in this protocol. + + 'long' and 'unsigned long' are implemented as 64 bit types. + + *Note Limits::, for corresponding MIN and MAX values (similar to +those in 'limits.h') to allow range checking on host and target. + + 'time_t' datatypes are defined as seconds since the Epoch. + + All integral datatypes transferred as part of a memory read or write +of a structured datatype e.g. a 'struct stat' have to be given in big +endian byte order. + + +File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes + +Pointer Values +.............. + +Pointers to target data are transmitted as they are. An exception is +made for pointers to buffers for which the length isn't transmitted as +part of the function call, namely strings. Strings are transmitted as a +pointer/length pair, both as hex values, e.g. + + 1aaf/12 + +which is a pointer to data of length 18 bytes at position 0x1aaf. The +length is defined as the full string length in bytes, including the +trailing null byte. For example, the string '"hello world"' at address +0x123456 is transmitted as + + 123456/d + + +File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes + +Memory Transfer +............... + +Structured data which is transferred using a memory read or write (for +example, a 'struct stat') is expected to be in a protocol-specific +format with all scalar multibyte datatypes being big endian. +Translation to this representation needs to be done both by the target +before the 'F' packet is sent, and by GDB before it transfers memory to +the target. Transferred pointers to structured data should point to the +already-coerced data at any time. + + +File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes + +struct stat +........... + +The buffer of type 'struct stat' used by the target and GDB is defined +as follows: + + struct stat { + unsigned int st_dev; /* device */ + unsigned int st_ino; /* inode */ + mode_t st_mode; /* protection */ + unsigned int st_nlink; /* number of hard links */ + unsigned int st_uid; /* user ID of owner */ + unsigned int st_gid; /* group ID of owner */ + unsigned int st_rdev; /* device type (if inode device) */ + unsigned long st_size; /* total size, in bytes */ + unsigned long st_blksize; /* blocksize for filesystem I/O */ + unsigned long st_blocks; /* number of blocks allocated */ + time_t st_atime; /* time of last access */ + time_t st_mtime; /* time of last modification */ + time_t st_ctime; /* time of last change */ + }; + + The integral datatypes conform to the definitions given in the +appropriate section (see *note Integral Datatypes::, for details) so +this structure is of size 64 bytes. + + The values of several fields have a restricted meaning and/or range +of values. + +'st_dev' + A value of 0 represents a file, 1 the console. + +'st_ino' + No valid meaning for the target. Transmitted unchanged. + +'st_mode' + Valid mode bits are described in *note Constants::. Any other bits + have currently no meaning for the target. + +'st_uid' +'st_gid' +'st_rdev' + No valid meaning for the target. Transmitted unchanged. + +'st_atime' +'st_mtime' +'st_ctime' + These values have a host and file system dependent accuracy. + Especially on Windows hosts, the file system may not support exact + timing values. + + The target gets a 'struct stat' of the above representation and is +responsible for coercing it to the target representation before +continuing. + + Note that due to size differences between the host, target, and +protocol representations of 'struct stat' members, these members could +eventually get truncated on the target. + + +File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes + +struct timeval +.............. + +The buffer of type 'struct timeval' used by the File-I/O protocol is +defined as follows: + + struct timeval { + time_t tv_sec; /* second */ + long tv_usec; /* microsecond */ + }; + + The integral datatypes conform to the definitions given in the +appropriate section (see *note Integral Datatypes::, for details) so +this structure is of size 8 bytes. + + +File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension + +E.13.9 Constants +---------------- + +The following values are used for the constants inside of the protocol. +GDB and target are responsible for translating these values before and +after the call as needed. + +* Menu: + +* Open Flags:: +* mode_t Values:: +* Errno Values:: +* Lseek Flags:: +* Limits:: + + +File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants + +Open Flags +.......... + +All values are given in hexadecimal representation. + + O_RDONLY 0x0 + O_WRONLY 0x1 + O_RDWR 0x2 + O_APPEND 0x8 + O_CREAT 0x200 + O_TRUNC 0x400 + O_EXCL 0x800 + + +File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants + +mode_t Values +............. + +All values are given in octal representation. + + S_IFREG 0100000 + S_IFDIR 040000 + S_IRUSR 0400 + S_IWUSR 0200 + S_IXUSR 0100 + S_IRGRP 040 + S_IWGRP 020 + S_IXGRP 010 + S_IROTH 04 + S_IWOTH 02 + S_IXOTH 01 + + +File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants + +Errno Values +............ + +All values are given in decimal representation. + + EPERM 1 + ENOENT 2 + EINTR 4 + EBADF 9 + EACCES 13 + EFAULT 14 + EBUSY 16 + EEXIST 17 + ENODEV 19 + ENOTDIR 20 + EISDIR 21 + EINVAL 22 + ENFILE 23 + EMFILE 24 + EFBIG 27 + ENOSPC 28 + ESPIPE 29 + EROFS 30 + ENAMETOOLONG 91 + EUNKNOWN 9999 + + 'EUNKNOWN' is used as a fallback error value if a host system returns +any error value not in the list of supported error numbers. + + +File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants + +Lseek Flags +........... + + SEEK_SET 0 + SEEK_CUR 1 + SEEK_END 2 + + +File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants + +Limits +...... + +All values are given in decimal representation. + + INT_MIN -2147483648 + INT_MAX 2147483647 + UINT_MAX 4294967295 + LONG_MIN -9223372036854775808 + LONG_MAX 9223372036854775807 + ULONG_MAX 18446744073709551615 + + +File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension + +E.13.10 File-I/O Examples +------------------------- + +Example sequence of a write call, file descriptor 3, buffer is at target +address 0x1234, 6 bytes should be written: + + <- Fwrite,3,1234,6 + _request memory read from target_ + -> m1234,6 + <- XXXXXX + _return "6 bytes written"_ + -> F6 + + Example sequence of a read call, file descriptor 3, buffer is at +target address 0x1234, 6 bytes should be read: + + <- Fread,3,1234,6 + _request memory write to target_ + -> X1234,6:XXXXXX + _return "6 bytes read"_ + -> F6 + + Example sequence of a read call, call fails on the host due to +invalid file descriptor ('EBADF'): + + <- Fread,3,1234,6 + -> F-1,9 + + Example sequence of a read call, user presses 'Ctrl-c' before syscall +on host is called: + + <- Fread,3,1234,6 + -> F-1,4,C + <- T02 + + Example sequence of a read call, user presses 'Ctrl-c' after syscall +on host is called: + + <- Fread,3,1234,6 + -> X1234,6:XXXXXX + <- T02 + + +File: gdb.info, Node: Library List Format, Next: Library List Format for SVR4 Targets, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol + +E.14 Library List Format +======================== + +On some platforms, a dynamic loader (e.g. 'ld.so') runs in the same +process as your application to manage libraries. In this case, GDB can +use the loader's symbol table and normal memory operations to maintain a +list of shared libraries. On other platforms, the operating system +manages loaded libraries. GDB can not retrieve the list of currently +loaded libraries through memory operations, so it uses the +'qXfer:libraries:read' packet (*note qXfer library list read::) instead. +The remote stub queries the target's operating system and reports which +libraries are loaded. + + The 'qXfer:libraries:read' packet returns an XML document which lists +loaded libraries and their offsets. Each library has an associated name +and one or more segment or section base addresses, which report where +the library was loaded in memory. + + For the common case of libraries that are fully linked binaries, the +library should have a list of segments. If the target supports dynamic +linking of a relocatable object file, its library XML element should +instead include a list of allocated sections. The segment or section +bases are start addresses, not relocation offsets; they do not depend on +the library's link-time base addresses. + + GDB must be linked with the Expat library to support XML library +lists. *Note Expat::. + + A simple memory map, with one loaded library relocated by a single +offset, looks like this: + + + + + + + + Another simple memory map, with one loaded library with three +allocated sections (.text, .data, .bss), looks like this: + + + +
+
+
+ + + + The format of a library list is described by this DTD: + + + + + + + + + + + + In addition, segments and section descriptors cannot be mixed within +a single library element, and you must supply at least one segment or +section for each library. + + +File: gdb.info, Node: Library List Format for SVR4 Targets, Next: Memory Map Format, Prev: Library List Format, Up: Remote Protocol + +E.15 Library List Format for SVR4 Targets +========================================= + +On SVR4 platforms GDB can use the symbol table of a dynamic loader (e.g. +'ld.so') and normal memory operations to maintain a list of shared +libraries. Still a special library list provided by this packet is more +efficient for the GDB remote protocol. + + The 'qXfer:libraries-svr4:read' packet returns an XML document which +lists loaded libraries and their SVR4 linker parameters. For each +library on SVR4 target, the following parameters are reported: + + - 'name', the absolute file name from the 'l_name' field of 'struct + link_map'. + - 'lm' with address of 'struct link_map' used for TLS (Thread Local + Storage) access. + - 'l_addr', the displacement as read from the field 'l_addr' of + 'struct link_map'. For prelinked libraries this is not an absolute + memory address. It is a displacement of absolute memory address + against address the file was prelinked to during the library load. + - 'l_ld', which is memory address of the 'PT_DYNAMIC' segment + + Additionally the single 'main-lm' attribute specifies address of +'struct link_map' used for the main executable. This parameter is used +for TLS access and its presence is optional. + + GDB must be linked with the Expat library to support XML SVR4 library +lists. *Note Expat::. + + A simple memory map, with two loaded libraries (which do not use +prelink), looks like this: + + + + + + + The format of an SVR4 library list is described by this DTD: + + + + + + + + + + + + +File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format for SVR4 Targets, Up: Remote Protocol + +E.16 Memory Map Format +====================== + +To be able to write into flash memory, GDB needs to obtain a memory map +from the target. This section describes the format of the memory map. + + The memory map is obtained using the 'qXfer:memory-map:read' (*note +qXfer memory map read::) packet and is an XML document that lists memory +regions. + + GDB must be linked with the Expat library to support XML memory maps. +*Note Expat::. + + The top-level structure of the document is shown below: + + + + + region... + + + Each region can be either: + + * A region of RAM starting at ADDR and extending for LENGTH bytes + from there: + + + + * A region of read-only memory: + + + + * A region of flash memory, with erasure blocks BLOCKSIZE bytes in + length: + + + BLOCKSIZE + + + Regions must not overlap. GDB assumes that areas of memory not +covered by the memory map are RAM, and uses the ordinary 'M' and 'X' +packets to write to addresses in such ranges. + + The formal DTD for memory map format is given below: + + + + + + + + + + + + + + + + + +File: gdb.info, Node: Thread List Format, Next: Traceframe Info Format, Prev: Memory Map Format, Up: Remote Protocol + +E.17 Thread List Format +======================= + +To efficiently update the list of threads and their attributes, GDB +issues the 'qXfer:threads:read' packet (*note qXfer threads read::) and +obtains the XML document with the following structure: + + + + + ... description ... + + + + Each 'thread' element must have the 'id' attribute that identifies +the thread (*note thread-id syntax::). The 'core' attribute, if +present, specifies which processor core the thread was last executing +on. The content of the of 'thread' element is interpreted as +human-readable auxilliary information. + + +File: gdb.info, Node: Traceframe Info Format, Next: Branch Trace Format, Prev: Thread List Format, Up: Remote Protocol + +E.18 Traceframe Info Format +=========================== + +To be able to know which objects in the inferior can be examined when +inspecting a tracepoint hit, GDB needs to obtain the list of memory +ranges, registers and trace state variables that have been collected in +a traceframe. + + This list is obtained using the 'qXfer:traceframe-info:read' (*note +qXfer traceframe info read::) packet and is an XML document. + + GDB must be linked with the Expat library to support XML traceframe +info discovery. *Note Expat::. + + The top-level structure of the document is shown below: + + + + + block... + + + Each traceframe block can be either: + + * A region of collected memory starting at ADDR and extending for + LENGTH bytes from there: + + + + * A block indicating trace state variable numbered NUMBER has been + collected: + + + + The formal DTD for the traceframe info format is given below: + + + + + + + + + + +File: gdb.info, Node: Branch Trace Format, Prev: Traceframe Info Format, Up: Remote Protocol + +E.19 Branch Trace Format +======================== + +In order to display the branch trace of an inferior thread, GDB needs to +obtain the list of branches. This list is represented as list of +sequential code blocks that are connected via branches. The code in +each block has been executed sequentially. + + This list is obtained using the 'qXfer:btrace:read' (*note qXfer +btrace read::) packet and is an XML document. + + GDB must be linked with the Expat library to support XML traceframe +info discovery. *Note Expat::. + + The top-level structure of the document is shown below: + + + + + block... + + + * A block of sequentially executed instructions starting at BEGIN and + ending at END: + + + + The formal DTD for the branch trace format is given below: + + + + + + + + +File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top + +Appendix F The GDB Agent Expression Mechanism +********************************************* + +In some applications, it is not feasible for the debugger to interrupt +the program's execution long enough for the developer to learn anything +helpful about its behavior. If the program's correctness depends on its +real-time behavior, delays introduced by a debugger might cause the +program to fail, even when the code itself is correct. It is useful to +be able to observe the program's behavior without interrupting it. + + Using GDB's 'trace' and 'collect' commands, the user can specify +locations in the program, and arbitrary expressions to evaluate when +those locations are reached. Later, using the 'tfind' command, she can +examine the values those expressions had when the program hit the trace +points. The expressions may also denote objects in memory -- structures +or arrays, for example -- whose values GDB should record; while visiting +a particular tracepoint, the user may inspect those objects as if they +were in memory at that moment. However, because GDB records these +values without interacting with the user, it can do so quickly and +unobtrusively, hopefully not disturbing the program's behavior. + + When GDB is debugging a remote target, the GDB "agent" code running +on the target computes the values of the expressions itself. To avoid +having a full symbolic expression evaluator on the agent, GDB translates +expressions in the source language into a simpler bytecode language, and +then sends the bytecode to the agent; the agent then executes the +bytecode, and records the values for GDB to retrieve later. + + The bytecode language is simple; there are forty-odd opcodes, the +bulk of which are the usual vocabulary of C operands (addition, +subtraction, shifts, and so on) and various sizes of literals and memory +reference operations. The bytecode interpreter operates strictly on +machine-level values -- various sizes of integers and floating point +numbers -- and requires no information about types or symbols; thus, the +interpreter's internal data structures are simple, and each bytecode +requires only a few native machine instructions to implement it. The +interpreter is small, and strict limits on the memory and time required +to evaluate an expression are easy to determine, making it suitable for +use by the debugging agent in real-time applications. + +* Menu: + +* General Bytecode Design:: Overview of the interpreter. +* Bytecode Descriptions:: What each one does. +* Using Agent Expressions:: How agent expressions fit into the big picture. +* Varying Target Capabilities:: How to discover what the target can do. +* Rationale:: Why we did it this way. + + +File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions + +F.1 General Bytecode Design +=========================== + +The agent represents bytecode expressions as an array of bytes. Each +instruction is one byte long (thus the term "bytecode"). Some +instructions are followed by operand bytes; for example, the 'goto' +instruction is followed by a destination for the jump. + + The bytecode interpreter is a stack-based machine; most instructions +pop their operands off the stack, perform some operation, and push the +result back on the stack for the next instruction to consume. Each +element of the stack may contain either a integer or a floating point +value; these values are as many bits wide as the largest integer that +can be directly manipulated in the source language. Stack elements +carry no record of their type; bytecode could push a value as an +integer, then pop it as a floating point value. However, GDB will not +generate code which does this. In C, one might define the type of a +stack element as follows: + union agent_val { + LONGEST l; + DOUBLEST d; + }; +where 'LONGEST' and 'DOUBLEST' are 'typedef' names for the largest +integer and floating point types on the machine. + + By the time the bytecode interpreter reaches the end of the +expression, the value of the expression should be the only value left on +the stack. For tracing applications, 'trace' bytecodes in the +expression will have recorded the necessary data, and the value on the +stack may be discarded. For other applications, like conditional +breakpoints, the value may be useful. + + Separate from the stack, the interpreter has two registers: +'pc' + The address of the next bytecode to execute. + +'start' + The address of the start of the bytecode expression, necessary for + interpreting the 'goto' and 'if_goto' instructions. + +Neither of these registers is directly visible to the bytecode language +itself, but they are useful for defining the meanings of the bytecode +operations. + + There are no instructions to perform side effects on the running +program, or call the program's functions; we assume that these +expressions are only used for unobtrusive debugging, not for patching +the running code. + + Most bytecode instructions do not distinguish between the various +sizes of values, and operate on full-width values; the upper bits of the +values are simply ignored, since they do not usually make a difference +to the value computed. The exceptions to this rule are: + +memory reference instructions ('ref'N) + There are distinct instructions to fetch different word sizes from + memory. Once on the stack, however, the values are treated as + full-size integers. They may need to be sign-extended; the 'ext' + instruction exists for this purpose. + +the sign-extension instruction ('ext' N) + These clearly need to know which portion of their operand is to be + extended to occupy the full length of the word. + + If the interpreter is unable to evaluate an expression completely for +some reason (a memory location is inaccessible, or a divisor is zero, +for example), we say that interpretation "terminates with an error". +This means that the problem is reported back to the interpreter's caller +in some helpful way. In general, code using agent expressions should +assume that they may attempt to divide by zero, fetch arbitrary memory +locations, and misbehave in other ways. + + Even complicated C expressions compile to a few bytecode +instructions; for example, the expression 'x + y * z' would typically +produce code like the following, assuming that 'x' and 'y' live in +registers, and 'z' is a global variable holding a 32-bit 'int': + reg 1 + reg 2 + const32 address of z + ref32 + ext 32 + mul + add + end + + In detail, these mean: + +'reg 1' + Push the value of register 1 (presumably holding 'x') onto the + stack. + +'reg 2' + Push the value of register 2 (holding 'y'). + +'const32 address of z' + Push the address of 'z' onto the stack. + +'ref32' + Fetch a 32-bit word from the address at the top of the stack; + replace the address on the stack with the value. Thus, we replace + the address of 'z' with 'z''s value. + +'ext 32' + Sign-extend the value on the top of the stack from 32 bits to full + length. This is necessary because 'z' is a signed integer. + +'mul' + Pop the top two numbers on the stack, multiply them, and push their + product. Now the top of the stack contains the value of the + expression 'y * z'. + +'add' + Pop the top two numbers, add them, and push the sum. Now the top + of the stack contains the value of 'x + y * z'. + +'end' + Stop executing; the value left on the stack top is the value to be + recorded. + + +File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions + +F.2 Bytecode Descriptions +========================= + +Each bytecode description has the following form: + +'add' (0x02): A B => A+B + + Pop the top two stack items, A and B, as integers; push their sum, + as an integer. + + In this example, 'add' is the name of the bytecode, and '(0x02)' is +the one-byte value used to encode the bytecode, in hexadecimal. The +phrase "A B => A+B" shows the stack before and after the bytecode +executes. Beforehand, the stack must contain at least two values, A and +B; since the top of the stack is to the right, B is on the top of the +stack, and A is underneath it. After execution, the bytecode will have +popped A and B from the stack, and replaced them with a single value, +A+B. There may be other values on the stack below those shown, but the +bytecode affects only those shown. + + Here is another example: + +'const8' (0x22) N: => N + Push the 8-bit integer constant N on the stack, without sign + extension. + + In this example, the bytecode 'const8' takes an operand N directly +from the bytecode stream; the operand follows the 'const8' bytecode +itself. We write any such operands immediately after the name of the +bytecode, before the colon, and describe the exact encoding of the +operand in the bytecode stream in the body of the bytecode description. + + For the 'const8' bytecode, there are no stack items given before the +=>; this simply means that the bytecode consumes no values from the +stack. If a bytecode consumes no values, or produces no values, the +list on either side of the => may be empty. + + If a value is written as A, B, or N, then the bytecode treats it as +an integer. If a value is written is ADDR, then the bytecode treats it +as an address. + + We do not fully describe the floating point operations here; although +this design can be extended in a clean way to handle floating point +values, they are not of immediate interest to the customer, so we avoid +describing them, to save time. + +'float' (0x01): => + + Prefix for floating-point bytecodes. Not implemented yet. + +'add' (0x02): A B => A+B + Pop two integers from the stack, and push their sum, as an integer. + +'sub' (0x03): A B => A-B + Pop two integers from the stack, subtract the top value from the + next-to-top value, and push the difference. + +'mul' (0x04): A B => A*B + Pop two integers from the stack, multiply them, and push the + product on the stack. Note that, when one multiplies two N-bit + numbers yielding another N-bit number, it is irrelevant whether the + numbers are signed or not; the results are the same. + +'div_signed' (0x05): A B => A/B + Pop two signed integers from the stack; divide the next-to-top + value by the top value, and push the quotient. If the divisor is + zero, terminate with an error. + +'div_unsigned' (0x06): A B => A/B + Pop two unsigned integers from the stack; divide the next-to-top + value by the top value, and push the quotient. If the divisor is + zero, terminate with an error. + +'rem_signed' (0x07): A B => A MODULO B + Pop two signed integers from the stack; divide the next-to-top + value by the top value, and push the remainder. If the divisor is + zero, terminate with an error. + +'rem_unsigned' (0x08): A B => A MODULO B + Pop two unsigned integers from the stack; divide the next-to-top + value by the top value, and push the remainder. If the divisor is + zero, terminate with an error. + +'lsh' (0x09): A B => A< '(signed)'A>>B + Pop two integers from the stack; let A be the next-to-top value, + and B be the top value. Shift A right by B bits, inserting copies + of the top bit at the high end, and push the result. + +'rsh_unsigned' (0x0b): A B => A>>B + Pop two integers from the stack; let A be the next-to-top value, + and B be the top value. Shift A right by B bits, inserting zero + bits at the high end, and push the result. + +'log_not' (0x0e): A => !A + Pop an integer from the stack; if it is zero, push the value one; + otherwise, push the value zero. + +'bit_and' (0x0f): A B => A&B + Pop two integers from the stack, and push their bitwise 'and'. + +'bit_or' (0x10): A B => A|B + Pop two integers from the stack, and push their bitwise 'or'. + +'bit_xor' (0x11): A B => A^B + Pop two integers from the stack, and push their bitwise + exclusive-'or'. + +'bit_not' (0x12): A => ~A + Pop an integer from the stack, and push its bitwise complement. + +'equal' (0x13): A B => A=B + Pop two integers from the stack; if they are equal, push the value + one; otherwise, push the value zero. + +'less_signed' (0x14): A B => A A A, sign-extended from N bits + Pop an unsigned value from the stack; treating it as an N-bit + twos-complement value, extend it to full length. This means that + all bits to the left of bit N-1 (where the least significant bit is + bit 0) are set to the value of bit N-1. Note that N may be larger + than or equal to the width of the stack elements of the bytecode + engine; in this case, the bytecode should have no effect. + + The number of source bits to preserve, N, is encoded as a single + byte unsigned integer following the 'ext' bytecode. + +'zero_ext' (0x2a) N: A => A, zero-extended from N bits + Pop an unsigned value from the stack; zero all but the bottom N + bits. This means that all bits to the left of bit N-1 (where the + least significant bit is bit 0) are set to the value of bit N-1. + + The number of source bits to preserve, N, is encoded as a single + byte unsigned integer following the 'zero_ext' bytecode. + +'ref8' (0x17): ADDR => A +'ref16' (0x18): ADDR => A +'ref32' (0x19): ADDR => A +'ref64' (0x1a): ADDR => A + Pop an address ADDR from the stack. For bytecode 'ref'N, fetch an + N-bit value from ADDR, using the natural target endianness. Push + the fetched value as an unsigned integer. + + Note that ADDR may not be aligned in any particular way; the 'refN' + bytecodes should operate correctly for any address. + + If attempting to access memory at ADDR would cause a processor + exception of some sort, terminate with an error. + +'ref_float' (0x1b): ADDR => D +'ref_double' (0x1c): ADDR => D +'ref_long_double' (0x1d): ADDR => D +'l_to_d' (0x1e): A => D +'d_to_l' (0x1f): D => A + Not implemented yet. + +'dup' (0x28): A => A A + Push another copy of the stack's top element. + +'swap' (0x2b): A B => B A + Exchange the top two items on the stack. + +'pop' (0x29): A => + Discard the top value on the stack. + +'pick' (0x32) N: A ... B => A ... B A + Duplicate an item from the stack and push it on the top of the + stack. N, a single byte, indicates the stack item to copy. If N + is zero, this is the same as 'dup'; if N is one, it copies the item + under the top item, etc. If N exceeds the number of items on the + stack, terminate with an error. + +'rot' (0x33): A B C => C B A + Rotate the top three items on the stack. + +'if_goto' (0x20) OFFSET: A => + Pop an integer off the stack; if it is non-zero, branch to the + given offset in the bytecode string. Otherwise, continue to the + next instruction in the bytecode stream. In other words, if A is + non-zero, set the 'pc' register to 'start' + OFFSET. Thus, an + offset of zero denotes the beginning of the expression. + + The OFFSET is stored as a sixteen-bit unsigned value, stored + immediately following the 'if_goto' bytecode. It is always stored + most significant byte first, regardless of the target's normal + endianness. The offset is not guaranteed to fall at any particular + alignment within the bytecode stream; thus, on machines where + fetching a 16-bit on an unaligned address raises an exception, you + should fetch the offset one byte at a time. + +'goto' (0x21) OFFSET: => + Branch unconditionally to OFFSET; in other words, set the 'pc' + register to 'start' + OFFSET. + + The offset is stored in the same way as for the 'if_goto' bytecode. + +'const8' (0x22) N: => N +'const16' (0x23) N: => N +'const32' (0x24) N: => N +'const64' (0x25) N: => N + Push the integer constant N on the stack, without sign extension. + To produce a small negative value, push a small twos-complement + value, and then sign-extend it using the 'ext' bytecode. + + The constant N is stored in the appropriate number of bytes + following the 'const'B bytecode. The constant N is always stored + most significant byte first, regardless of the target's normal + endianness. The constant is not guaranteed to fall at any + particular alignment within the bytecode stream; thus, on machines + where fetching a 16-bit on an unaligned address raises an + exception, you should fetch N one byte at a time. + +'reg' (0x26) N: => A + Push the value of register number N, without sign extension. The + registers are numbered following GDB's conventions. + + The register number N is encoded as a 16-bit unsigned integer + immediately following the 'reg' bytecode. It is always stored most + significant byte first, regardless of the target's normal + endianness. The register number is not guaranteed to fall at any + particular alignment within the bytecode stream; thus, on machines + where fetching a 16-bit on an unaligned address raises an + exception, you should fetch the register number one byte at a time. + +'getv' (0x2c) N: => V + Push the value of trace state variable number N, without sign + extension. + + The variable number N is encoded as a 16-bit unsigned integer + immediately following the 'getv' bytecode. It is always stored + most significant byte first, regardless of the target's normal + endianness. The variable number is not guaranteed to fall at any + particular alignment within the bytecode stream; thus, on machines + where fetching a 16-bit on an unaligned address raises an + exception, you should fetch the register number one byte at a time. + +'setv' (0x2d) N: => V + Set trace state variable number N to the value found on the top of + the stack. The stack is unchanged, so that the value is readily + available if the assignment is part of a larger expression. The + handling of N is as described for 'getv'. + +'trace' (0x0c): ADDR SIZE => + Record the contents of the SIZE bytes at ADDR in a trace buffer, + for later retrieval by GDB. + +'trace_quick' (0x0d) SIZE: ADDR => ADDR + Record the contents of the SIZE bytes at ADDR in a trace buffer, + for later retrieval by GDB. SIZE is a single byte unsigned integer + following the 'trace' opcode. + + This bytecode is equivalent to the sequence 'dup const8 SIZE + trace', but we provide it anyway to save space in bytecode strings. + +'trace16' (0x30) SIZE: ADDR => ADDR + Identical to trace_quick, except that SIZE is a 16-bit big-endian + unsigned integer, not a single byte. This should probably have + been named 'trace_quick16', for consistency. + +'tracev' (0x2e) N: => A + Record the value of trace state variable number N in the trace + buffer. The handling of N is as described for 'getv'. + +'tracenz' (0x2f) ADDR SIZE => + Record the bytes at ADDR in a trace buffer, for later retrieval by + GDB. Stop at either the first zero byte, or when SIZE bytes have + been recorded, whichever occurs first. + +'printf' (0x34) NUMARGS STRING => + Do a formatted print, in the style of the C function 'printf'). + The value of NUMARGS is the number of arguments to expect on the + stack, while STRING is the format string, prefixed with a two-byte + length. The last byte of the string must be zero, and is included + in the length. The format string includes escaped sequences just + as it appears in C source, so for instance the format string + '"\t%d\n"' is six characters long, and the output will consist of a + tab character, a decimal number, and a newline. At the top of the + stack, above the values to be printed, this bytecode will pop a + "function" and "channel". If the function is nonzero, then the + target may treat it as a function and call it, passing the channel + as a first argument, as with the C function 'fprintf'. If the + function is zero, then the target may simply call a standard + formatted print function of its choice. In all, this bytecode pops + 2 + NUMARGS stack elements, and pushes nothing. + +'end' (0x27): => + Stop executing bytecode; the result should be the top element of + the stack. If the purpose of the expression was to compute an + lvalue or a range of memory, then the next-to-top of the stack is + the lvalue's address, and the top of the stack is the lvalue's + size, in bytes. + + +File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions + +F.3 Using Agent Expressions +=========================== + +Agent expressions can be used in several different ways by GDB, and the +debugger can generate different bytecode sequences as appropriate. + + One possibility is to do expression evaluation on the target rather +than the host, such as for the conditional of a conditional tracepoint. +In such a case, GDB compiles the source expression into a bytecode +sequence that simply gets values from registers or memory, does +arithmetic, and returns a result. + + Another way to use agent expressions is for tracepoint data +collection. GDB generates a different bytecode sequence for collection; +in addition to bytecodes that do the calculation, GDB adds 'trace' +bytecodes to save the pieces of memory that were used. + + * The user selects trace points in the program's code at which GDB + should collect data. + + * The user specifies expressions to evaluate at each trace point. + These expressions may denote objects in memory, in which case those + objects' contents are recorded as the program runs, or computed + values, in which case the values themselves are recorded. + + * GDB transmits the tracepoints and their associated expressions to + the GDB agent, running on the debugging target. + + * The agent arranges to be notified when a trace point is hit. + + * When execution on the target reaches a trace point, the agent + evaluates the expressions associated with that trace point, and + records the resulting values and memory ranges. + + * Later, when the user selects a given trace event and inspects the + objects and expression values recorded, GDB talks to the agent to + retrieve recorded data as necessary to meet the user's requests. + If the user asks to see an object whose contents have not been + recorded, GDB reports an error. + + +File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions + +F.4 Varying Target Capabilities +=============================== + +Some targets don't support floating-point, and some would rather not +have to deal with 'long long' operations. Also, different targets will +have different stack sizes, and different bytecode buffer lengths. + + Thus, GDB needs a way to ask the target about itself. We haven't +worked out the details yet, but in general, GDB should be able to send +the target a packet asking it to describe itself. The reply should be a +packet whose length is explicit, so we can add new information to the +packet in future revisions of the agent, without confusing old versions +of GDB, and it should contain a version number. It should contain at +least the following information: + + * whether floating point is supported + + * whether 'long long' is supported + + * maximum acceptable size of bytecode stack + + * maximum acceptable length of bytecode expressions + + * which registers are actually available for collection + + * whether the target supports disabled tracepoints + + +File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions + +F.5 Rationale +============= + +Some of the design decisions apparent above are arguable. + +What about stack overflow/underflow? + GDB should be able to query the target to discover its stack size. + Given that information, GDB can determine at translation time + whether a given expression will overflow the stack. But this spec + isn't about what kinds of error-checking GDB ought to do. + +Why are you doing everything in LONGEST? + + Speed isn't important, but agent code size is; using LONGEST brings + in a bunch of support code to do things like division, etc. So + this is a serious concern. + + First, note that you don't need different bytecodes for different + operand sizes. You can generate code without _knowing_ how big the + stack elements actually are on the target. If the target only + supports 32-bit ints, and you don't send any 64-bit bytecodes, + everything just works. The observation here is that the MIPS and + the Alpha have only fixed-size registers, and you can still get C's + semantics even though most instructions only operate on full-sized + words. You just need to make sure everything is properly + sign-extended at the right times. So there is no need for 32- and + 64-bit variants of the bytecodes. Just implement everything using + the largest size you support. + + GDB should certainly check to see what sizes the target supports, + so the user can get an error earlier, rather than later. But this + information is not necessary for correctness. + +Why don't you have '>' or '<=' operators? + I want to keep the interpreter small, and we don't need them. We + can combine the 'less_' opcodes with 'log_not', and swap the order + of the operands, yielding all four asymmetrical comparison + operators. For example, '(x <= y)' is '! (x > y)', which is '! (y + < x)'. + +Why do you have 'log_not'? +Why do you have 'ext'? +Why do you have 'zero_ext'? + These are all easily synthesized from other instructions, but I + expect them to be used frequently, and they're simple, so I include + them to keep bytecode strings short. + + 'log_not' is equivalent to 'const8 0 equal'; it's used in half the + relational operators. + + 'ext N' is equivalent to 'const8 S-N lsh const8 S-N rsh_signed', + where S is the size of the stack elements; it follows 'refM' and + REG bytecodes when the value should be signed. See the next + bulleted item. + + 'zero_ext N' is equivalent to 'constM MASK log_and'; it's used + whenever we push the value of a register, because we can't assume + the upper bits of the register aren't garbage. + +Why not have sign-extending variants of the 'ref' operators? + Because that would double the number of 'ref' operators, and we + need the 'ext' bytecode anyway for accessing bitfields. + +Why not have constant-address variants of the 'ref' operators? + Because that would double the number of 'ref' operators again, and + 'const32 ADDRESS ref32' is only one byte longer. + +Why do the 'refN' operators have to support unaligned fetches? + GDB will generate bytecode that fetches multi-byte values at + unaligned addresses whenever the executable's debugging information + tells it to. Furthermore, GDB does not know the value the pointer + will have when GDB generates the bytecode, so it cannot determine + whether a particular fetch will be aligned or not. + + In particular, structure bitfields may be several bytes long, but + follow no alignment rules; members of packed structures are not + necessarily aligned either. + + In general, there are many cases where unaligned references occur + in correct C code, either at the programmer's explicit request, or + at the compiler's discretion. Thus, it is simpler to make the GDB + agent bytecodes work correctly in all circumstances than to make + GDB guess in each case whether the compiler did the usual thing. + +Why are there no side-effecting operators? + Because our current client doesn't want them? That's a cheap + answer. I think the real answer is that I'm afraid of implementing + function calls. We should re-visit this issue after the present + contract is delivered. + +Why aren't the 'goto' ops PC-relative? + The interpreter has the base address around anyway for PC bounds + checking, and it seemed simpler. + +Why is there only one offset size for the 'goto' ops? + Offsets are currently sixteen bits. I'm not happy with this + situation either: + + Suppose we have multiple branch ops with different offset sizes. + As I generate code left-to-right, all my jumps are forward jumps + (there are no loops in expressions), so I never know the target + when I emit the jump opcode. Thus, I have to either always assume + the largest offset size, or do jump relaxation on the code after I + generate it, which seems like a big waste of time. + + I can imagine a reasonable expression being longer than 256 bytes. + I can't imagine one being longer than 64k. Thus, we need 16-bit + offsets. This kind of reasoning is so bogus, but relaxation is + pathetic. + + The other approach would be to generate code right-to-left. Then + I'd always know my offset size. That might be fun. + +Where is the function call bytecode? + + When we add side-effects, we should add this. + +Why does the 'reg' bytecode take a 16-bit register number? + + Intel's IA-64 architecture has 128 general-purpose registers, and + 128 floating-point registers, and I'm sure it has some random + control registers. + +Why do we need 'trace' and 'trace_quick'? + Because GDB needs to record all the memory contents and registers + an expression touches. If the user wants to evaluate an expression + 'x->y->z', the agent must record the values of 'x' and 'x->y' as + well as the value of 'x->y->z'. + +Don't the 'trace' bytecodes make the interpreter less general? + They do mean that the interpreter contains special-purpose code, + but that doesn't mean the interpreter can only be used for that + purpose. If an expression doesn't use the 'trace' bytecodes, they + don't get in its way. + +Why doesn't 'trace_quick' consume its arguments the way everything else does? + In general, you do want your operators to consume their arguments; + it's consistent, and generally reduces the amount of stack + rearrangement necessary. However, 'trace_quick' is a kludge to + save space; it only exists so we needn't write 'dup const8 SIZE + trace' before every memory reference. Therefore, it's okay for it + not to consume its arguments; it's meant for a specific context in + which we know exactly what it should do with the stack. If we're + going to have a kludge, it should be an effective kludge. + +Why does 'trace16' exist? + That opcode was added by the customer that contracted Cygnus for + the data tracing work. I personally think it is unnecessary; + objects that large will be quite rare, so it is okay to use 'dup + const16 SIZE trace' in those cases. + + Whatever we decide to do with 'trace16', we should at least leave + opcode 0x30 reserved, to remain compatible with the customer who + added it. + + +File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top + +Appendix G Target Descriptions +****************************** + +One of the challenges of using GDB to debug embedded systems is that +there are so many minor variants of each processor architecture in use. +It is common practice for vendors to start with a standard processor +core -- ARM, PowerPC, or MIPS, for example -- and then make changes to +adapt it to a particular market niche. Some architectures have hundreds +of variants, available from dozens of vendors. This leads to a number +of problems: + + * With so many different customized processors, it is difficult for + the GDB maintainers to keep up with the changes. + * Since individual variants may have short lifetimes or limited + audiences, it may not be worthwhile to carry information about + every variant in the GDB source tree. + * When GDB does support the architecture of the embedded system at + hand, the task of finding the correct architecture name to give the + 'set architecture' command can be error-prone. + + To address these problems, the GDB remote protocol allows a target +system to not only identify itself to GDB, but to actually describe its +own features. This lets GDB support processor variants it has never +seen before -- to the extent that the descriptions are accurate, and +that GDB understands them. + + GDB must be linked with the Expat library to support XML target +descriptions. *Note Expat::. + +* Menu: + +* Retrieving Descriptions:: How descriptions are fetched from a target. +* Target Description Format:: The contents of a target description. +* Predefined Target Types:: Standard types available for target + descriptions. +* Standard Target Features:: Features GDB knows about. + + +File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions + +G.1 Retrieving Descriptions +=========================== + +Target descriptions can be read from the target automatically, or +specified by the user manually. The default behavior is to read the +description from the target. GDB retrieves it via the remote protocol +using 'qXfer' requests (*note qXfer: General Query Packets.). The ANNEX +in the 'qXfer' packet will be 'target.xml'. The contents of the +'target.xml' annex are an XML document, of the form described in *note +Target Description Format::. + + Alternatively, you can specify a file to read for the target +description. If a file is set, the target will not be queried. The +commands to specify a file are: + +'set tdesc filename PATH' + Read the target description from PATH. + +'unset tdesc filename' + Do not read the XML target description from a file. GDB will use + the description supplied by the current target. + +'show tdesc filename' + Show the filename to read for a target description, if any. + + +File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions + +G.2 Target Description Format +============================= + +A target description annex is an XML (http://www.w3.org/XML/) document +which complies with the Document Type Definition provided in the GDB +sources in 'gdb/features/gdb-target.dtd'. This means you can use +generally available tools like 'xmllint' to check that your feature +descriptions are well-formed and valid. However, to help people +unfamiliar with XML write descriptions for their targets, we also +describe the grammar here. + + Target descriptions can identify the architecture of the remote +target and (for some architectures) provide information about custom +register sets. They can also identify the OS ABI of the remote target. +GDB can use this information to autoconfigure for your target, or to +warn you if you connect to an unsupported target. + + Here is a simple target description: + + + i386:x86-64 + + +This minimal description only says that the target uses the x86-64 +architecture. + + A target description has the following overall form, with [ ] marking +optional elements and ... marking repeatable elements. The elements are +explained further below. + + + + + [ARCHITECTURE] + [OSABI] + [COMPATIBLE] + [FEATURE...] + + +The description is generally insensitive to whitespace and line breaks, +under the usual common-sense rules. The XML version declaration and +document type declaration can generally be omitted (GDB does not require +them), but specifying them may be useful for XML validation tools. The +'version' attribute for '' may also be omitted, but we recommend +including it; if future versions of GDB use an incompatible revision of +'gdb-target.dtd', they will detect and report the version mismatch. + +G.2.1 Inclusion +--------------- + +It can sometimes be valuable to split a target description up into +several different annexes, either for organizational purposes, or to +share files between different possible target descriptions. You can +divide a description into multiple files by replacing any element of the +target description with an inclusion directive of the form: + + + +When GDB encounters an element of this form, it will retrieve the named +XML DOCUMENT, and replace the inclusion directive with the contents of +that document. If the current description was read using 'qXfer', then +so will be the included document; DOCUMENT will be interpreted as the +name of an annex. If the current description was read from a file, GDB +will look for DOCUMENT as a file in the same directory where it found +the original description. + +G.2.2 Architecture +------------------ + +An '' element has this form: + + ARCH + + ARCH is one of the architectures from the set accepted by 'set +architecture' (*note Specifying a Debugging Target: Targets.). + +G.2.3 OS ABI +------------ + +This optional field was introduced in GDB version 7.0. Previous +versions of GDB ignore it. + + An '' element has this form: + + ABI-NAME + + ABI-NAME is an OS ABI name from the same selection accepted by 'set osabi' +(*note Configuring the Current ABI: ABI.). + +G.2.4 Compatible Architecture +----------------------------- + +This optional field was introduced in GDB version 7.0. Previous +versions of GDB ignore it. + + A '' element has this form: + + ARCH + + ARCH is one of the architectures from the set accepted by 'set +architecture' (*note Specifying a Debugging Target: Targets.). + + A '' element is used to specify that the target is able +to run binaries in some other than the main target architecture given by +the '' element. For example, on the Cell Broadband +Engine, the main architecture is 'powerpc:common' or 'powerpc:common64', +but the system is able to run binaries in the 'spu' architecture as +well. The way to describe this capability with '' is as +follows: + + powerpc:common + spu + +G.2.5 Features +-------------- + +Each '' describes some logical portion of the target system. +Features are currently used to describe available CPU registers and the +types of their contents. A '' element has this form: + + + [TYPE...] + REG... + + +Each feature's name should be unique within the description. The name +of a feature does not matter unless GDB has some special knowledge of +the contents of that feature; if it does, the feature should have its +standard name. *Note Standard Target Features::. + +G.2.6 Types +----------- + +Any register's value is a collection of bits which GDB must interpret. +The default interpretation is a two's complement integer, but other +types can be requested by name in the register description. Some +predefined types are provided by GDB (*note Predefined Target Types::), +and the description can define additional composite types. + + Each type element must have an 'id' attribute, which gives a unique +(within the containing '') name to the type. Types must be +defined before they are used. + + Some targets offer vector registers, which can be treated as arrays +of scalar elements. These types are written as '' elements, +specifying the array element type, TYPE, and the number of elements, +COUNT: + + + + If a register's value is usefully viewed in multiple ways, define it +with a union type containing the useful representations. The '' +element contains one or more '' elements, each of which has a +NAME and a TYPE: + + + + ... + + + If a register's value is composed from several separate values, +define it with a structure type. There are two forms of the '' +element; a '' element must either contain only bitfields or +contain no bitfields. If the structure contains only bitfields, its +total size in bytes must be specified, each bitfield must have an +explicit start and end, and bitfields are automatically assigned an +integer type. The field's START should be less than or equal to its +END, and zero represents the least significant bit. + + + + ... + + + If the structure contains no bitfields, then each field has an +explicit type, and no implicit padding is added. + + + + ... + + + If a register's value is a series of single-bit flags, define it with +a flags type. The '' element has an explicit SIZE and contains +one or more '' elements. Each field has a NAME, a START, and an +END. Only single-bit flags are supported. + + + + ... + + +G.2.7 Registers +--------------- + +Each register is represented as an element with this form: + + + +The components are as follows: + +NAME + The register's name; it must be unique within the target + description. + +BITSIZE + The register's size, in bits. + +REGNUM + The register's number. If omitted, a register's number is one + greater than that of the previous register (either in the current + feature or in a preceding feature); the first register in the + target description defaults to zero. This register number is used + to read or write the register; e.g. it is used in the remote 'p' + and 'P' packets, and registers appear in the 'g' and 'G' packets in + order of increasing register number. + +SAVE-RESTORE + Whether the register should be preserved across inferior function + calls; this must be either 'yes' or 'no'. The default is 'yes', + which is appropriate for most registers except for some system + control registers; this is not related to the target's ABI. + +TYPE + The type of the register. TYPE may be a predefined type, a type + defined in the current feature, or one of the special types 'int' + and 'float'. 'int' is an integer type of the correct size for + BITSIZE, and 'float' is a floating point type (in the + architecture's normal floating point format) of the correct size + for BITSIZE. The default is 'int'. + +GROUP + The register group to which this register belongs. GROUP must be + either 'general', 'float', or 'vector'. If no GROUP is specified, + GDB will not display the register in 'info registers'. + + +File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions + +G.3 Predefined Target Types +=========================== + +Type definitions in the self-description can build up composite types +from basic building blocks, but can not define fundamental types. +Instead, standard identifiers are provided by GDB for the fundamental +types. The currently supported types are: + +'int8' +'int16' +'int32' +'int64' +'int128' + Signed integer types holding the specified number of bits. + +'uint8' +'uint16' +'uint32' +'uint64' +'uint128' + Unsigned integer types holding the specified number of bits. + +'code_ptr' +'data_ptr' + Pointers to unspecified code and data. The program counter and any + dedicated return address register may be marked as code pointers; + printing a code pointer converts it into a symbolic address. The + stack pointer and any dedicated address registers may be marked as + data pointers. + +'ieee_single' + Single precision IEEE floating point. + +'ieee_double' + Double precision IEEE floating point. + +'arm_fpa_ext' + The 12-byte extended precision format used by ARM FPA registers. + +'i387_ext' + The 10-byte extended precision format used by x87 registers. + +'i386_eflags' + 32bit EFLAGS register used by x86. + +'i386_mxcsr' + 32bit MXCSR register used by x86. + + +File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions + +G.4 Standard Target Features +============================ + +A target description must contain either no registers or all the +target's registers. If the description contains no registers, then GDB +will assume a default register layout, selected based on the +architecture. If the description contains any registers, the default +layout will not be used; the standard registers must be described in the +target description, in such a way that GDB can recognize them. + + This is accomplished by giving specific names to feature elements +which contain standard registers. GDB will look for features with those +names and verify that they contain the expected registers; if any known +feature is missing required registers, or if any required feature is +missing, GDB will reject the target description. You can add additional +registers to any of the standard features -- GDB will display them just +as if they were added to an unrecognized feature. + + This section lists the known features and their expected contents. +Sample XML documents for these features are included in the GDB source +tree, in the directory 'gdb/features'. + + Names recognized by GDB should include the name of the company or +organization which selected the name, and the overall architecture to +which the feature applies; so e.g. the feature containing ARM core +registers is named 'org.gnu.gdb.arm.core'. + + The names of registers are not case sensitive for the purpose of +recognizing standard features, but GDB will only display registers using +the capitalization used in the description. + +* Menu: + +* AArch64 Features:: +* ARM Features:: +* i386 Features:: +* MIPS Features:: +* M68K Features:: +* Nios II Features:: +* PowerPC Features:: +* S/390 and System z Features:: +* TIC6x Features:: + + +File: gdb.info, Node: AArch64 Features, Next: ARM Features, Up: Standard Target Features + +G.4.1 AArch64 Features +---------------------- + +The 'org.gnu.gdb.aarch64.core' feature is required for AArch64 targets. +It should contain registers 'x0' through 'x30', 'sp', 'pc', and 'cpsr'. + + The 'org.gnu.gdb.aarch64.fpu' feature is optional. If present, it +should contain registers 'v0' through 'v31', 'fpsr', and 'fpcr'. + + +File: gdb.info, Node: ARM Features, Next: i386 Features, Prev: AArch64 Features, Up: Standard Target Features + +G.4.2 ARM Features +------------------ + +The 'org.gnu.gdb.arm.core' feature is required for non-M-profile ARM +targets. It should contain registers 'r0' through 'r13', 'sp', 'lr', +'pc', and 'cpsr'. + + For M-profile targets (e.g. Cortex-M3), the 'org.gnu.gdb.arm.core' +feature is replaced by 'org.gnu.gdb.arm.m-profile'. It should contain +registers 'r0' through 'r13', 'sp', 'lr', 'pc', and 'xpsr'. + + The 'org.gnu.gdb.arm.fpa' feature is optional. If present, it should +contain registers 'f0' through 'f7' and 'fps'. + + The 'org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it +should contain at least registers 'wR0' through 'wR15' and 'wCGR0' +through 'wCGR3'. The 'wCID', 'wCon', 'wCSSF', and 'wCASF' registers are +optional. + + The 'org.gnu.gdb.arm.vfp' feature is optional. If present, it should +contain at least registers 'd0' through 'd15'. If they are present, +'d16' through 'd31' should also be included. GDB will synthesize the +single-precision registers from halves of the double-precision +registers. + + The 'org.gnu.gdb.arm.neon' feature is optional. It does not need to +contain registers; it instructs GDB to display the VFP double-precision +registers as vectors and to synthesize the quad-precision registers from +pairs of double-precision registers. If this feature is present, +'org.gnu.gdb.arm.vfp' must also be present and include 32 +double-precision registers. + + +File: gdb.info, Node: i386 Features, Next: MIPS Features, Prev: ARM Features, Up: Standard Target Features + +G.4.3 i386 Features +------------------- + +The 'org.gnu.gdb.i386.core' feature is required for i386/amd64 targets. +It should describe the following registers: + + - 'eax' through 'edi' plus 'eip' for i386 + - 'rax' through 'r15' plus 'rip' for amd64 + - 'eflags', 'cs', 'ss', 'ds', 'es', 'fs', 'gs' + - 'st0' through 'st7' + - 'fctrl', 'fstat', 'ftag', 'fiseg', 'fioff', 'foseg', 'fooff' and + 'fop' + + The register sets may be different, depending on the target. + + The 'org.gnu.gdb.i386.sse' feature is optional. It should describe +registers: + + - 'xmm0' through 'xmm7' for i386 + - 'xmm0' through 'xmm15' for amd64 + - 'mxcsr' + + The 'org.gnu.gdb.i386.avx' feature is optional and requires the +'org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits +of YMM registers: + + - 'ymm0h' through 'ymm7h' for i386 + - 'ymm0h' through 'ymm15h' for amd64 + + The 'org.gnu.gdb.i386.mpx' is an optional feature representing +Intel(R) Memory Protection Extension (MPX). It should describe the +following registers: + + - 'bnd0raw' through 'bnd3raw' for i386 and amd64. + - 'bndcfgu' and 'bndstatus' for i386 and amd64. + + The 'org.gnu.gdb.i386.linux' feature is optional. It should describe +a single register, 'orig_eax'. + + +File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: i386 Features, Up: Standard Target Features + +G.4.4 MIPS Features +------------------- + +The 'org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It +should contain registers 'r0' through 'r31', 'lo', 'hi', and 'pc'. They +may be 32-bit or 64-bit depending on the target. + + The 'org.gnu.gdb.mips.cp0' feature is also required. It should +contain at least the 'status', 'badvaddr', and 'cause' registers. They +may be 32-bit or 64-bit depending on the target. + + The 'org.gnu.gdb.mips.fpu' feature is currently required, though it +may be optional in a future version of GDB. It should contain registers +'f0' through 'f31', 'fcsr', and 'fir'. They may be 32-bit or 64-bit +depending on the target. + + The 'org.gnu.gdb.mips.dsp' feature is optional. It should contain +registers 'hi1' through 'hi3', 'lo1' through 'lo3', and 'dspctl'. The +'dspctl' register should be 32-bit and the rest may be 32-bit or 64-bit +depending on the target. + + The 'org.gnu.gdb.mips.linux' feature is optional. It should contain +a single register, 'restart', which is used by the Linux kernel to +control restartable syscalls. + + +File: gdb.info, Node: M68K Features, Next: Nios II Features, Prev: MIPS Features, Up: Standard Target Features + +G.4.5 M68K Features +------------------- + +''org.gnu.gdb.m68k.core'' +''org.gnu.gdb.coldfire.core'' +''org.gnu.gdb.fido.core'' + One of those features must be always present. The feature that is + present determines which flavor of m68k is used. The feature that + is present should contain registers 'd0' through 'd7', 'a0' through + 'a5', 'fp', 'sp', 'ps' and 'pc'. + +''org.gnu.gdb.coldfire.fp'' + This feature is optional. If present, it should contain registers + 'fp0' through 'fp7', 'fpcontrol', 'fpstatus' and 'fpiaddr'. + + +File: gdb.info, Node: Nios II Features, Next: PowerPC Features, Prev: M68K Features, Up: Standard Target Features + +G.4.6 Nios II Features +---------------------- + +The 'org.gnu.gdb.nios2.cpu' feature is required for Nios II targets. It +should contain the 32 core registers ('zero', 'at', 'r2' through 'r23', +'et' through 'ra'), 'pc', and the 16 control registers ('status' through +'mpuacc'). + + +File: gdb.info, Node: PowerPC Features, Next: S/390 and System z Features, Prev: Nios II Features, Up: Standard Target Features + +G.4.7 PowerPC Features +---------------------- + +The 'org.gnu.gdb.power.core' feature is required for PowerPC targets. +It should contain registers 'r0' through 'r31', 'pc', 'msr', 'cr', 'lr', +'ctr', and 'xer'. They may be 32-bit or 64-bit depending on the target. + + The 'org.gnu.gdb.power.fpu' feature is optional. It should contain +registers 'f0' through 'f31' and 'fpscr'. + + The 'org.gnu.gdb.power.altivec' feature is optional. It should +contain registers 'vr0' through 'vr31', 'vscr', and 'vrsave'. + + The 'org.gnu.gdb.power.vsx' feature is optional. It should contain +registers 'vs0h' through 'vs31h'. GDB will combine these registers with +the floating point registers ('f0' through 'f31') and the altivec +registers ('vr0' through 'vr31') to present the 128-bit wide registers +'vs0' through 'vs63', the set of vector registers for POWER7. + + The 'org.gnu.gdb.power.spe' feature is optional. It should contain +registers 'ev0h' through 'ev31h', 'acc', and 'spefscr'. SPE targets +should provide 32-bit registers in 'org.gnu.gdb.power.core' and provide +the upper halves in 'ev0h' through 'ev31h'. GDB will combine these to +present registers 'ev0' through 'ev31' to the user. + + +File: gdb.info, Node: S/390 and System z Features, Next: TIC6x Features, Prev: PowerPC Features, Up: Standard Target Features + +G.4.8 S/390 and System z Features +--------------------------------- + +The 'org.gnu.gdb.s390.core' feature is required for S/390 and System z +targets. It should contain the PSW and the 16 general registers. In +particular, System z targets should provide the 64-bit registers 'pswm', +'pswa', and 'r0' through 'r15'. S/390 targets should provide the 32-bit +versions of these registers. A System z target that runs in 31-bit +addressing mode should provide 32-bit versions of 'pswm' and 'pswa', as +well as the general register's upper halves 'r0h' through 'r15h', and +their lower halves 'r0l' through 'r15l'. + + The 'org.gnu.gdb.s390.fpr' feature is required. It should contain +the 64-bit registers 'f0' through 'f15', and 'fpc'. + + The 'org.gnu.gdb.s390.acr' feature is required. It should contain +the 32-bit registers 'acr0' through 'acr15'. + + The 'org.gnu.gdb.s390.linux' feature is optional. It should contain +the register 'orig_r2', which is 64-bit wide on System z targets and +32-bit otherwise. In addition, the feature may contain the 'last_break' +register, whose width depends on the addressing mode, as well as the +'system_call' register, which is always 32-bit wide. + + The 'org.gnu.gdb.s390.tdb' feature is optional. It should contain +the 64-bit registers 'tdb0', 'tac', 'tct', 'atia', and 'tr0' through +'tr15'. + + +File: gdb.info, Node: TIC6x Features, Prev: S/390 and System z Features, Up: Standard Target Features + +G.4.9 TMS320C6x Features +------------------------ + +The 'org.gnu.gdb.tic6x.core' feature is required for TMS320C6x targets. +It should contain registers 'A0' through 'A15', registers 'B0' through +'B15', 'CSR' and 'PC'. + + The 'org.gnu.gdb.tic6x.gp' feature is optional. It should contain +registers 'A16' through 'A31' and 'B16' through 'B31'. + + The 'org.gnu.gdb.tic6x.c6xp' feature is optional. It should contain +registers 'TSR', 'ILC' and 'RILC'. + + +File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top + +Appendix H Operating System Information +*************************************** + +* Menu: + +* Process list:: + +Users of GDB often wish to obtain information about the state of the +operating system running on the target--for example the list of +processes, or the list of open files. This section describes the +mechanism that makes it possible. This mechanism is similar to the +target features mechanism (*note Target Descriptions::), but focuses on +a different aspect of target. + + Operating system information is retrived from the target via the +remote protocol, using 'qXfer' requests (*note qXfer osdata read::). +The object name in the request should be 'osdata', and the ANNEX +identifies the data to be fetched. + + +File: gdb.info, Node: Process list, Up: Operating System Information + +H.1 Process list +================ + +When requesting the process list, the ANNEX field in the 'qXfer' request +should be 'processes'. The returned data is an XML document. The +formal syntax of this document is defined in 'gdb/features/osdata.dtd'. + + An example document is: + + + + + + 1 + root + /sbin/init + 1,2,3 + + + + Each item should include a column whose name is 'pid'. The value of +that column should identify the process on the target. The 'user' and +'command' columns are optional, and will be displayed by GDB. The +'cores' column, if present, should contain a comma-separated list of +cores that this process is running on. Target may provide additional +columns, which GDB currently ignores. + + +File: gdb.info, Node: Trace File Format, Next: Index Section Format, Prev: Operating System Information, Up: Top + +Appendix I Trace File Format +**************************** + +The trace file comes in three parts: a header, a textual description +section, and a trace frame section with binary data. + + The header has the form '\x7fTRACE0\n'. The first byte is '0x7f' so +as to indicate that the file contains binary data, while the '0' is a +version number that may have different values in the future. + + The description section consists of multiple lines of ASCII text +separated by newline characters ('0xa'). The lines may include a +variety of optional descriptive or context-setting information, such as +tracepoint definitions or register set size. GDB will ignore any line +that it does not recognize. An empty line marks the end of this +section. + + The trace frame section consists of a number of consecutive frames. +Each frame begins with a two-byte tracepoint number, followed by a +four-byte size giving the amount of data in the frame. The data in the +frame consists of a number of blocks, each introduced by a character +indicating its type (at least register, memory, and trace state +variable). The data in this section is raw binary, not a hexadecimal or +other encoding; its endianness matches the target's endianness. + +'R BYTES' + Register block. The number and ordering of bytes matches that of a + 'g' packet in the remote protocol. Note that these are the actual + bytes, in target order and GDB register order, not a hexadecimal + encoding. + +'M ADDRESS LENGTH BYTES...' + Memory block. This is a contiguous block of memory, at the 8-byte + address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH + bytes. + +'V NUMBER VALUE' + Trace state variable block. This records the 8-byte signed value + VALUE of trace state variable numbered NUMBER. + + Future enhancements of the trace file format may include additional +types of blocks. + + +File: gdb.info, Node: Index Section Format, Next: Man Pages, Prev: Trace File Format, Up: Top + +Appendix J '.gdb_index' section format +************************************** + +This section documents the index section that is created by 'save +gdb-index' (*note Index Files::). The index section is DWARF-specific; +some knowledge of DWARF is assumed in this description. + + The mapped index file format is designed to be directly 'mmap'able on +any architecture. In most cases, a datum is represented using a +little-endian 32-bit integer value, called an 'offset_type'. Big endian +machines must byte-swap the values before using them. Exceptions to +this rule are noted. The data is laid out such that alignment is always +respected. + + A mapped index consists of several areas, laid out in order. + + 1. The file header. This is a sequence of values, of 'offset_type' + unless otherwise noted: + + 1. The version number, currently 8. Versions 1, 2 and 3 are + obsolete. Version 4 uses a different hashing function from + versions 5 and 6. Version 6 includes symbols for inlined + functions, whereas versions 4 and 5 do not. Version 7 adds + attributes to the CU indices in the symbol table. Version 8 + specifies that symbols from DWARF type units + ('DW_TAG_type_unit') refer to the type unit's symbol table and + not the compilation unit ('DW_TAG_comp_unit') using the type. + + GDB will only read version 4, 5, or 6 indices by specifying + 'set use-deprecated-index-sections on'. GDB has a workaround + for potentially broken version 7 indices so it is currently + not flagged as deprecated. + + 2. The offset, from the start of the file, of the CU list. + + 3. The offset, from the start of the file, of the types CU list. + Note that this area can be empty, in which case this offset + will be equal to the next offset. + + 4. The offset, from the start of the file, of the address area. + + 5. The offset, from the start of the file, of the symbol table. + + 6. The offset, from the start of the file, of the constant pool. + + 2. The CU list. This is a sequence of pairs of 64-bit little-endian + values, sorted by the CU offset. The first element in each pair is + the offset of a CU in the '.debug_info' section. The second + element in each pair is the length of that CU. References to a CU + elsewhere in the map are done using a CU index, which is just the + 0-based index into this table. Note that if there are type CUs, + then conceptually CUs and type CUs form a single list for the + purposes of CU indices. + + 3. The types CU list. This is a sequence of triplets of 64-bit + little-endian values. In a triplet, the first value is the CU + offset, the second value is the type offset in the CU, and the + third value is the type signature. The types CU list is not + sorted. + + 4. The address area. The address area consists of a sequence of + address entries. Each address entry has three elements: + + 1. The low address. This is a 64-bit little-endian value. + + 2. The high address. This is a 64-bit little-endian value. Like + 'DW_AT_high_pc', the value is one byte beyond the end. + + 3. The CU index. This is an 'offset_type' value. + + 5. The symbol table. This is an open-addressed hash table. The size + of the hash table is always a power of 2. + + Each slot in the hash table consists of a pair of 'offset_type' + values. The first value is the offset of the symbol's name in the + constant pool. The second value is the offset of the CU vector in + the constant pool. + + If both values are 0, then this slot in the hash table is empty. + This is ok because while 0 is a valid constant pool index, it + cannot be a valid index for both a string and a CU vector. + + The hash value for a table entry is computed by applying an + iterative hash function to the symbol's name. Starting with an + initial value of 'r = 0', each (unsigned) character 'c' in the + string is incorporated into the hash using the formula depending on + the index version: + + Version 4 + The formula is 'r = r * 67 + c - 113'. + + Versions 5 to 7 + The formula is 'r = r * 67 + tolower (c) - 113'. + + The terminating '\0' is not incorporated into the hash. + + The step size used in the hash table is computed via '((hash * 17) + & (size - 1)) | 1', where 'hash' is the hash value, and 'size' is + the size of the hash table. The step size is used to find the next + candidate slot when handling a hash collision. + + The names of C++ symbols in the hash table are canonicalized. We + don't currently have a simple description of the canonicalization + algorithm; if you intend to create new index sections, you must + read the code. + + 6. The constant pool. This is simply a bunch of bytes. It is + organized so that alignment is correct: CU vectors are stored + first, followed by strings. + + A CU vector in the constant pool is a sequence of 'offset_type' + values. The first value is the number of CU indices in the vector. + Each subsequent value is the index and symbol attributes of a CU in + the CU list. This element in the hash table is used to indicate + which CUs define the symbol and how the symbol is used. See below + for the format of each CU index+attributes entry. + + A string in the constant pool is zero-terminated. + + Attributes were added to CU index values in '.gdb_index' version 7. +If a symbol has multiple uses within a CU then there is one CU +index+attributes value for each use. + + The format of each CU index+attributes entry is as follows (bit 0 = +LSB): + +Bits 0-23 + This is the index of the CU in the CU list. +Bits 24-27 + These bits are reserved for future purposes and must be zero. +Bits 28-30 + The kind of the symbol in the CU. + + 0 + This value is reserved and should not be used. By reserving + zero the full 'offset_type' value is backwards compatible with + previous versions of the index. + 1 + The symbol is a type. + 2 + The symbol is a variable or an enum value. + 3 + The symbol is a function. + 4 + Any other kind of symbol. + 5,6,7 + These values are reserved. + +Bit 31 + This bit is zero if the value is global and one if it is static. + + The determination of whether a symbol is global or static is + complicated. The authorative reference is the file 'dwarf2read.c' + in GDB sources. + + This pseudo-code describes the computation of a symbol's kind and +global/static attributes in the index. + + is_external = get_attribute (die, DW_AT_external); + language = get_attribute (cu_die, DW_AT_language); + switch (die->tag) + { + case DW_TAG_typedef: + case DW_TAG_base_type: + case DW_TAG_subrange_type: + kind = TYPE; + is_static = 1; + break; + case DW_TAG_enumerator: + kind = VARIABLE; + is_static = (language != CPLUS && language != JAVA); + break; + case DW_TAG_subprogram: + kind = FUNCTION; + is_static = ! (is_external || language == ADA); + break; + case DW_TAG_constant: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_variable: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_namespace: + kind = TYPE; + is_static = 0; + break; + case DW_TAG_class_type: + case DW_TAG_interface_type: + case DW_TAG_structure_type: + case DW_TAG_union_type: + case DW_TAG_enumeration_type: + kind = TYPE; + is_static = (language != CPLUS && language != JAVA); + break; + default: + assert (0); + } + + +File: gdb.info, Node: Man Pages, Next: Copying, Prev: Index Section Format, Up: Top + +Appendix K Manual pages +*********************** + +* Menu: + +* gdb man:: The GNU Debugger man page +* gdbserver man:: Remote Server for the GNU Debugger man page +* gcore man:: Generate a core file of a running program +* gdbinit man:: gdbinit scripts + + +File: gdb.info, Node: gdb man, Next: gdbserver man, Up: Man Pages + +gdb man +======= + +gdb ['-help'] ['-nh'] ['-nx'] ['-q'] ['-batch'] ['-cd='DIR] ['-f'] +['-b' BPS] ['-tty='DEV] ['-s' SYMFILE] ['-e' PROG] ['-se' PROG] +['-c' CORE] ['-p' PROCID] ['-x' CMDS] ['-d' DIR] [PROG|PROG PROCID|PROG +CORE] + + The purpose of a debugger such as GDB is to allow you to see what is +going on "inside" another program while it executes - or what another +program was doing at the moment it crashed. + + GDB can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: + + * Start your program, specifying anything that might affect its + behavior. + + * Make your program stop on specified conditions. + + * Examine what has happened, when your program has stopped. + + * Change things in your program, so you can experiment with + correcting the effects of one bug and go on to learn about another. + + You can use GDB to debug programs written in C, C++, Fortran and +Modula-2. + + GDB is invoked with the shell command 'gdb'. Once started, it reads +commands from the terminal until you tell it to exit with the GDB +command 'quit'. You can get online help from GDB itself by using the +command 'help'. + + You can run 'gdb' with no arguments or options; but the most usual +way to start GDB is with one argument or two, specifying an executable +program as the argument: + + gdb program + + You can also start with both an executable program and a core file +specified: + + gdb program core + + You can, instead, specify a process ID as a second argument, if you +want to debug a running process: + + gdb program 1234 + gdb -p 1234 + +would attach GDB to process '1234' (unless you also have a file named +'1234'; GDB does check for a core file first). With option '-p' you can +omit the PROGRAM filename. + + Here are some of the most frequently needed GDB commands: + +'break [FILE:]FUNCTIOP' + Set a breakpoint at FUNCTION (in FILE). + +'run [ARGLIST]' + Start your program (with ARGLIST, if specified). + +'bt' + Backtrace: display the program stack. + +'print EXPR' + Display the value of an expression. + +'c' + Continue running your program (after stopping, e.g. at a + breakpoint). + +'next' + Execute next program line (after stopping); step _over_ any + function calls in the line. + +'edit [FILE:]FUNCTION' + look at the program line where it is presently stopped. + +'list [FILE:]FUNCTION' + type the text of the program in the vicinity of where it is + presently stopped. + +'step' + Execute next program line (after stopping); step _into_ any + function calls in the line. + +'help [NAME]' + Show information about GDB command NAME, or general information + about using GDB. + +'quit' + Exit from GDB. + + Any arguments other than options specify an executable file and core +file (or process ID); that is, the first argument encountered with no +associated option flag is equivalent to a '-se' option, and the second, +if any, is equivalent to a '-c' option if it's the name of a file. Many +options have both long and short forms; both are shown here. The long +forms are also recognized if you truncate them, so long as enough of the +option is present to be unambiguous. (If you prefer, you can flag +option arguments with '+' rather than '-', though we illustrate the more +usual convention.) + + All the options and command line arguments you give are processed in +sequential order. The order makes a difference when the '-x' option is +used. + +'-help' +'-h' + List all options, with brief explanations. + +'-symbols=FILE' +'-s FILE' + Read symbol table from file FILE. + +'-write' + Enable writing into executable and core files. + +'-exec=FILE' +'-e FILE' + Use file FILE as the executable file to execute when appropriate, + and for examining pure data in conjunction with a core dump. + +'-se=FILE' + Read symbol table from file FILE and use it as the executable file. + +'-core=FILE' +'-c FILE' + Use file FILE as a core dump to examine. + +'-command=FILE' +'-x FILE' + Execute GDB commands from file FILE. + +'-ex COMMAND' + Execute given GDB COMMAND. + +'-directory=DIRECTORY' +'-d DIRECTORY' + Add DIRECTORY to the path to search for source files. + +'-nh' + Do not execute commands from '~/.gdbinit'. + +'-nx' +'-n' + Do not execute commands from any '.gdbinit' initialization files. + +'-quiet' +'-q' + "Quiet". Do not print the introductory and copyright messages. + These messages are also suppressed in batch mode. + +'-batch' + Run in batch mode. Exit with status '0' after processing all the + command files specified with '-x' (and '.gdbinit', if not + inhibited). Exit with nonzero status if an error occurs in + executing the GDB commands in the command files. + + Batch mode may be useful for running GDB as a filter, for example + to download and run a program on another computer; in order to make + this more useful, the message + + Program exited normally. + + (which is ordinarily issued whenever a program running under GDB + control terminates) is not issued when running in batch mode. + +'-cd=DIRECTORY' + Run GDB using DIRECTORY as its working directory, instead of the + current directory. + +'-fullname' +'-f' + Emacs sets this option when it runs GDB as a subprocess. It tells + GDB to output the full file name and line number in a standard, + recognizable fashion each time a stack frame is displayed (which + includes each time the program stops). This recognizable format + looks like two '\032' characters, followed by the file name, line + number and character position separated by colons, and a newline. + The Emacs-to-GDB interface program uses the two '\032' characters + as a signal to display the source code for the frame. + +'-b BPS' + Set the line speed (baud rate or bits per second) of any serial + interface used by GDB for remote debugging. + +'-tty=DEVICE' + Run using DEVICE for your program's standard input and output. + + +File: gdb.info, Node: gdbserver man, Next: gcore man, Prev: gdb man, Up: Man Pages + +gdbserver man +============= + +gdbserver COMM PROG [ARGS...] + +gdbserver -attach COMM PID + +gdbserver -multi COMM + + 'gdbserver' is a program that allows you to run GDB on a different +machine than the one which is running the program being debugged. + +Usage (server (target) side) +---------------------------- + +First, you need to have a copy of the program you want to debug put onto +the target system. The program can be stripped to save space if needed, +as 'gdbserver' doesn't care about symbols. All symbol handling is taken +care of by the GDB running on the host system. + + To use the server, you log on to the target system, and run the +'gdbserver' program. You must tell it (a) how to communicate with GDB, +(b) the name of your program, and (c) its arguments. The general syntax +is: + + target> gdbserver COMM PROGRAM [ARGS ...] + + For example, using a serial port, you might say: + + target> gdbserver /dev/com1 emacs foo.txt + + This tells 'gdbserver' to debug emacs with an argument of foo.txt, +and to communicate with GDB via '/dev/com1'. 'gdbserver' now waits +patiently for the host GDB to communicate with it. + + To use a TCP connection, you could say: + + target> gdbserver host:2345 emacs foo.txt + + This says pretty much the same thing as the last example, except that +we are going to communicate with the 'host' GDB via TCP. The 'host:2345' +argument means that we are expecting to see a TCP connection from 'host' +to local TCP port 2345. (Currently, the 'host' part is ignored.) You +can choose any number you want for the port number as long as it does +not conflict with any existing TCP ports on the target system. This +same port number must be used in the host GDBs 'target remote' command, +which will be described shortly. Note that if you chose a port number +that conflicts with another service, 'gdbserver' will print an error +message and exit. + + 'gdbserver' can also attach to running programs. This is +accomplished via the '--attach' argument. The syntax is: + + target> gdbserver --attach COMM PID + + PID is the process ID of a currently running process. It isn't +necessary to point 'gdbserver' at a binary for the running process. + + To start 'gdbserver' without supplying an initial command to run or +process ID to attach, use the '--multi' command line option. In such +case you should connect using 'target extended-remote' to start the +program you want to debug. + + target> gdbserver --multi COMM + +Usage (host side) +----------------- + +You need an unstripped copy of the target program on your host system, +since GDB needs to examine it's symbol tables and such. Start up GDB as +you normally would, with the target program as the first argument. (You +may need to use the '--baud' option if the serial line is running at +anything except 9600 baud.) That is 'gdb TARGET-PROG', or 'gdb --baud +BAUD TARGET-PROG'. After that, the only new command you need to know +about is 'target remote' (or 'target extended-remote'). Its argument is +either a device name (usually a serial device, like '/dev/ttyb'), or a +'HOST:PORT' descriptor. For example: + + (gdb) target remote /dev/ttyb + +communicates with the server via serial line '/dev/ttyb', and: + + (gdb) target remote the-target:2345 + +communicates via a TCP connection to port 2345 on host 'the-target', +where you previously started up 'gdbserver' with the same port number. +Note that for TCP connections, you must start up 'gdbserver' prior to +using the 'target remote' command, otherwise you may get an error that +looks something like 'Connection refused'. + + 'gdbserver' can also debug multiple inferiors at once, described in +*note Inferiors and Programs::. In such case use the 'extended-remote' +GDB command variant: + + (gdb) target extended-remote the-target:2345 + + The 'gdbserver' option '--multi' may or may not be used in such case. + + There are three different modes for invoking 'gdbserver': + + * Debug a specific program specified by its program name: + + gdbserver COMM PROG [ARGS...] + + The COMM parameter specifies how should the server communicate with + GDB; it is either a device name (to use a serial line), a TCP port + number (':1234'), or '-' or 'stdio' to use stdin/stdout of + 'gdbserver'. Specify the name of the program to debug in PROG. + Any remaining arguments will be passed to the program verbatim. + When the program exits, GDB will close the connection, and + 'gdbserver' will exit. + + * Debug a specific program by specifying the process ID of a running + program: + + gdbserver --attach COMM PID + + The COMM parameter is as described above. Supply the process ID of + a running program in PID; GDB will do everything else. Like with + the previous mode, when the process PID exits, GDB will close the + connection, and 'gdbserver' will exit. + + * Multi-process mode - debug more than one program/process: + + gdbserver --multi COMM + + In this mode, GDB can instruct 'gdbserver' which command(s) to run. + Unlike the other 2 modes, GDB will not close the connection when a + process being debugged exits, so you can debug several processes in + the same session. + + In each of the modes you may specify these options: + +'--help' + List all options, with brief explanations. + +'--version' + This option causes 'gdbserver' to print its version number and + exit. + +'--attach' + 'gdbserver' will attach to a running program. The syntax is: + + target> gdbserver --attach COMM PID + + PID is the process ID of a currently running process. It isn't + necessary to point 'gdbserver' at a binary for the running process. + +'--multi' + To start 'gdbserver' without supplying an initial command to run or + process ID to attach, use this command line option. Then you can + connect using 'target extended-remote' and start the program you + want to debug. The syntax is: + + target> gdbserver --multi COMM + +'--debug' + Instruct 'gdbserver' to display extra status information about the + debugging process. This option is intended for 'gdbserver' + development and for bug reports to the developers. + +'--remote-debug' + Instruct 'gdbserver' to display remote protocol debug output. This + option is intended for 'gdbserver' development and for bug reports + to the developers. + +'--wrapper' + Specify a wrapper to launch programs for debugging. The option + should be followed by the name of the wrapper, then any + command-line arguments to pass to the wrapper, then '--' indicating + the end of the wrapper arguments. + +'--once' + By default, 'gdbserver' keeps the listening TCP port open, so that + additional connections are possible. However, if you start + 'gdbserver' with the '--once' option, it will stop listening for + any further connection attempts after connecting to the first GDB + session. + + +File: gdb.info, Node: gcore man, Next: gdbinit man, Prev: gdbserver man, Up: Man Pages + +gcore +===== + +gcore [-o FILENAME] PID + + Generate a core dump of a running program with process ID PID. +Produced file is equivalent to a kernel produced core file as if the +process crashed (and if 'ulimit -c' were used to set up an appropriate +core dump limit). Unlike after a crash, after 'gcore' the program +remains running without any change. + +'-o FILENAME' + The optional argument FILENAME specifies the file name where to put + the core dump. If not specified, the file name defaults to + 'core.PID', where PID is the running program process ID. + + +File: gdb.info, Node: gdbinit man, Prev: gcore man, Up: Man Pages + +gdbinit +======= + + +~/.gdbinit + +./.gdbinit + + These files contain GDB commands to automatically execute during GDB +startup. The lines of contents are canned sequences of commands, +described in *note Sequences::. + + Please read more in *note Startup::. + +'(not enabled with --with-system-gdbinit during compilation)' + System-wide initialization file. It is executed unless user + specified GDB option '-nx' or '-n'. See more in *note System-wide + configuration::. + +'~/.gdbinit' + User initialization file. It is executed unless user specified GDB + options '-nx', '-n' or '-nh'. + +'./.gdbinit' + Initialization file for current directory. It may need to be + enabled with GDB security command 'set auto-load local-gdbinit'. + See more in *note Init File in the Current Directory::. + + +File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Man Pages, Up: Top + +Appendix L GNU GENERAL PUBLIC LICENSE +************************************* + + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + +Preamble +======== + +The GNU General Public License is a free, copyleft license for software +and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + +TERMS AND CONDITIONS +==================== + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public + License. + + "Copyright" also means copyright-like laws that apply to other + kinds of works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this + License. Each licensee is addressed as "you". "Licensees" and + "recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the + work in a fashion requiring copyright permission, other than the + making of an exact copy. The resulting work is called a "modified + version" of the earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work + based on the Program. + + To "propagate" a work means to do anything with it that, without + permission, would make you directly or secondarily liable for + infringement under applicable copyright law, except executing it on + a computer or modifying a private copy. Propagation includes + copying, distribution (with or without modification), making + available to the public, and in some countries other activities as + well. + + To "convey" a work means any kind of propagation that enables other + parties to make or receive copies. Mere interaction with a user + through a computer network, with no transfer of a copy, is not + conveying. + + An interactive user interface displays "Appropriate Legal Notices" + to the extent that it includes a convenient and prominently visible + feature that (1) displays an appropriate copyright notice, and (2) + tells the user that there is no warranty for the work (except to + the extent that warranties are provided), that licensees may convey + the work under this License, and how to view a copy of this + License. If the interface presents a list of user commands or + options, such as a menu, a prominent item in the list meets this + criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work + for making modifications to it. "Object code" means any non-source + form of a work. + + A "Standard Interface" means an interface that either is an + official standard defined by a recognized standards body, or, in + the case of interfaces specified for a particular programming + language, one that is widely used among developers working in that + language. + + The "System Libraries" of an executable work include anything, + other than the work as a whole, that (a) is included in the normal + form of packaging a Major Component, but which is not part of that + Major Component, and (b) serves only to enable use of the work with + that Major Component, or to implement a Standard Interface for + which an implementation is available to the public in source code + form. A "Major Component", in this context, means a major + essential component (kernel, window system, and so on) of the + specific operating system (if any) on which the executable work + runs, or a compiler used to produce the work, or an object code + interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all + the source code needed to generate, install, and (for an executable + work) run the object code and to modify the work, including scripts + to control those activities. However, it does not include the + work's System Libraries, or general-purpose tools or generally + available free programs which are used unmodified in performing + those activities but which are not part of the work. For example, + Corresponding Source includes interface definition files associated + with source files for the work, and the source code for shared + libraries and dynamically linked subprograms that the work is + specifically designed to require, such as by intimate data + communication or control flow between those subprograms and other + parts of the work. + + The Corresponding Source need not include anything that users can + regenerate automatically from other parts of the Corresponding + Source. + + The Corresponding Source for a work in source code form is that + same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of + copyright on the Program, and are irrevocable provided the stated + conditions are met. This License explicitly affirms your unlimited + permission to run the unmodified Program. The output from running + a covered work is covered by this License only if the output, given + its content, constitutes a covered work. This License acknowledges + your rights of fair use or other equivalent, as provided by + copyright law. + + You may make, run and propagate covered works that you do not + convey, without conditions so long as your license otherwise + remains in force. You may convey covered works to others for the + sole purpose of having them make modifications exclusively for you, + or provide you with facilities for running those works, provided + that you comply with the terms of this License in conveying all + material for which you do not control copyright. Those thus making + or running the covered works for you must do so exclusively on your + behalf, under your direction and control, on terms that prohibit + them from making any copies of your copyrighted material outside + their relationship with you. + + Conveying under any other circumstances is permitted solely under + the conditions stated below. Sublicensing is not allowed; section + 10 makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological + measure under any applicable law fulfilling obligations under + article 11 of the WIPO copyright treaty adopted on 20 December + 1996, or similar laws prohibiting or restricting circumvention of + such measures. + + When you convey a covered work, you waive any legal power to forbid + circumvention of technological measures to the extent such + circumvention is effected by exercising rights under this License + with respect to the covered work, and you disclaim any intention to + limit operation or modification of the work as a means of + enforcing, against the work's users, your or third parties' legal + rights to forbid circumvention of technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you + receive it, in any medium, provided that you conspicuously and + appropriately publish on each copy an appropriate copyright notice; + keep intact all notices stating that this License and any + non-permissive terms added in accord with section 7 apply to the + code; keep intact all notices of the absence of any warranty; and + give all recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, + and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to + produce it from the Program, in the form of source code under the + terms of section 4, provided that you also meet all of these + conditions: + + a. The work must carry prominent notices stating that you + modified it, and giving a relevant date. + + b. The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in + section 4 to "keep intact all notices". + + c. You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable + section 7 additional terms, to the whole of the work, and all + its parts, regardless of how they are packaged. This License + gives no permission to license the work in any other way, but + it does not invalidate such permission if you have separately + received it. + + d. If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has + interactive interfaces that do not display Appropriate Legal + Notices, your work need not make them do so. + + A compilation of a covered work with other separate and independent + works, which are not by their nature extensions of the covered + work, and which are not combined with it such as to form a larger + program, in or on a volume of a storage or distribution medium, is + called an "aggregate" if the compilation and its resulting + copyright are not used to limit the access or legal rights of the + compilation's users beyond what the individual works permit. + Inclusion of a covered work in an aggregate does not cause this + License to apply to the other parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms + of sections 4 and 5, provided that you also convey the + machine-readable Corresponding Source under the terms of this + License, in one of these ways: + + a. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that + product model, to give anyone who possesses the object code + either (1) a copy of the Corresponding Source for all the + software in the product that is covered by this License, on a + durable physical medium customarily used for software + interchange, for a price no more than your reasonable cost of + physically performing this conveying of source, or (2) access + to copy the Corresponding Source from a network server at no + charge. + + c. Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, + and only if you received the object code with such an offer, + in accord with subsection 6b. + + d. Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to + the Corresponding Source in the same way through the same + place at no further charge. You need not require recipients + to copy the Corresponding Source along with the object code. + If the place to copy the object code is a network server, the + Corresponding Source may be on a different server (operated by + you or a third party) that supports equivalent copying + facilities, provided you maintain clear directions next to the + object code saying where to find the Corresponding Source. + Regardless of what server hosts the Corresponding Source, you + remain obligated to ensure that it is available for as long as + needed to satisfy these requirements. + + e. Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the + general public at no charge under subsection 6d. + + A separable portion of the object code, whose source code is + excluded from the Corresponding Source as a System Library, need + not be included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means + any tangible personal property which is normally used for personal, + family, or household purposes, or (2) anything designed or sold for + incorporation into a dwelling. In determining whether a product is + a consumer product, doubtful cases shall be resolved in favor of + coverage. For a particular product received by a particular user, + "normally used" refers to a typical or common use of that class of + product, regardless of the status of the particular user or of the + way in which the particular user actually uses, or expects or is + expected to use, the product. A product is a consumer product + regardless of whether the product has substantial commercial, + industrial or non-consumer uses, unless such uses represent the + only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, + procedures, authorization keys, or other information required to + install and execute modified versions of a covered work in that + User Product from a modified version of its Corresponding Source. + The information must suffice to ensure that the continued + functioning of the modified object code is in no case prevented or + interfered with solely because modification has been made. + + If you convey an object code work under this section in, or with, + or specifically for use in, a User Product, and the conveying + occurs as part of a transaction in which the right of possession + and use of the User Product is transferred to the recipient in + perpetuity or for a fixed term (regardless of how the transaction + is characterized), the Corresponding Source conveyed under this + section must be accompanied by the Installation Information. But + this requirement does not apply if neither you nor any third party + retains the ability to install modified object code on the User + Product (for example, the work has been installed in ROM). + + The requirement to provide Installation Information does not + include a requirement to continue to provide support service, + warranty, or updates for a work that has been modified or installed + by the recipient, or for the User Product in which it has been + modified or installed. Access to a network may be denied when the + modification itself materially and adversely affects the operation + of the network or violates the rules and protocols for + communication across the network. + + Corresponding Source conveyed, and Installation Information + provided, in accord with this section must be in a format that is + publicly documented (and with an implementation available to the + public in source code form), and must require no special password + or key for unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of + this License by making exceptions from one or more of its + conditions. Additional permissions that are applicable to the + entire Program shall be treated as though they were included in + this License, to the extent that they are valid under applicable + law. If additional permissions apply only to part of the Program, + that part may be used separately under those permissions, but the + entire Program remains governed by this License without regard to + the additional permissions. + + When you convey a copy of a covered work, you may at your option + remove any additional permissions from that copy, or from any part + of it. (Additional permissions may be written to require their own + removal in certain cases when you modify the work.) You may place + additional permissions on material, added by you to a covered work, + for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material + you add to a covered work, you may (if authorized by the copyright + holders of that material) supplement the terms of this License with + terms: + + a. Disclaiming warranty or limiting liability differently from + the terms of sections 15 and 16 of this License; or + + b. Requiring preservation of specified reasonable legal notices + or author attributions in that material or in the Appropriate + Legal Notices displayed by works containing it; or + + c. Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be marked + in reasonable ways as different from the original version; or + + d. Limiting the use for publicity purposes of names of licensors + or authors of the material; or + + e. Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f. Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified + versions of it) with contractual assumptions of liability to + the recipient, for any liability that these contractual + assumptions directly impose on those licensors and authors. + + All other non-permissive additional terms are considered "further + restrictions" within the meaning of section 10. If the Program as + you received it, or any part of it, contains a notice stating that + it is governed by this License along with a term that is a further + restriction, you may remove that term. If a license document + contains a further restriction but permits relicensing or conveying + under this License, you may add to a covered work material governed + by the terms of that license document, provided that the further + restriction does not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you + must place, in the relevant source files, a statement of the + additional terms that apply to those files, or a notice indicating + where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in + the form of a separately written license, or stated as exceptions; + the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly + provided under this License. Any attempt otherwise to propagate or + modify it is void, and will automatically terminate your rights + under this License (including any patent licenses granted under the + third paragraph of section 11). + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, you do not qualify to receive new licenses + for the same material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or + run a copy of the Program. Ancillary propagation of a covered work + occurring solely as a consequence of using peer-to-peer + transmission to receive a copy likewise does not require + acceptance. However, nothing other than this License grants you + permission to propagate or modify any covered work. These actions + infringe copyright if you do not accept this License. Therefore, + by modifying or propagating a covered work, you indicate your + acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically + receives a license from the original licensors, to run, modify and + propagate that work, subject to this License. You are not + responsible for enforcing compliance by third parties with this + License. + + An "entity transaction" is a transaction transferring control of an + organization, or substantially all assets of one, or subdividing an + organization, or merging organizations. If propagation of a + covered work results from an entity transaction, each party to that + transaction who receives a copy of the work also receives whatever + licenses to the work the party's predecessor in interest had or + could give under the previous paragraph, plus a right to possession + of the Corresponding Source of the work from the predecessor in + interest, if the predecessor has it or can get it with reasonable + efforts. + + You may not impose any further restrictions on the exercise of the + rights granted or affirmed under this License. For example, you + may not impose a license fee, royalty, or other charge for exercise + of rights granted under this License, and you may not initiate + litigation (including a cross-claim or counterclaim in a lawsuit) + alleging that any patent claim is infringed by making, using, + selling, offering for sale, or importing the Program or any portion + of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this + License of the Program or a work on which the Program is based. + The work thus licensed is called the contributor's "contributor + version". + + A contributor's "essential patent claims" are all patent claims + owned or controlled by the contributor, whether already acquired or + hereafter acquired, that would be infringed by some manner, + permitted by this License, of making, using, or selling its + contributor version, but do not include claims that would be + infringed only as a consequence of further modification of the + contributor version. For purposes of this definition, "control" + includes the right to grant patent sublicenses in a manner + consistent with the requirements of this License. + + Each contributor grants you a non-exclusive, worldwide, + royalty-free patent license under the contributor's essential + patent claims, to make, use, sell, offer for sale, import and + otherwise run, modify and propagate the contents of its contributor + version. + + In the following three paragraphs, a "patent license" is any + express agreement or commitment, however denominated, not to + enforce a patent (such as an express permission to practice a + patent or covenant not to sue for patent infringement). To "grant" + such a patent license to a party means to make such an agreement or + commitment not to enforce a patent against the party. + + If you convey a covered work, knowingly relying on a patent + license, and the Corresponding Source of the work is not available + for anyone to copy, free of charge and under the terms of this + License, through a publicly available network server or other + readily accessible means, then you must either (1) cause the + Corresponding Source to be so available, or (2) arrange to deprive + yourself of the benefit of the patent license for this particular + work, or (3) arrange, in a manner consistent with the requirements + of this License, to extend the patent license to downstream + recipients. "Knowingly relying" means you have actual knowledge + that, but for the patent license, your conveying the covered work + in a country, or your recipient's use of the covered work in a + country, would infringe one or more identifiable patents in that + country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or + arrangement, you convey, or propagate by procuring conveyance of, a + covered work, and grant a patent license to some of the parties + receiving the covered work authorizing them to use, propagate, + modify or convey a specific copy of the covered work, then the + patent license you grant is automatically extended to all + recipients of the covered work and works based on it. + + A patent license is "discriminatory" if it does not include within + the scope of its coverage, prohibits the exercise of, or is + conditioned on the non-exercise of one or more of the rights that + are specifically granted under this License. You may not convey a + covered work if you are a party to an arrangement with a third + party that is in the business of distributing software, under which + you make payment to the third party based on the extent of your + activity of conveying the work, and under which the third party + grants, to any of the parties who would receive the covered work + from you, a discriminatory patent license (a) in connection with + copies of the covered work conveyed by you (or copies made from + those copies), or (b) primarily for and in connection with specific + products or compilations that contain the covered work, unless you + entered into that arrangement, or that patent license was granted, + prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting + any implied license or other defenses to infringement that may + otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement + or otherwise) that contradict the conditions of this License, they + do not excuse you from the conditions of this License. If you + cannot convey a covered work so as to satisfy simultaneously your + obligations under this License and any other pertinent obligations, + then as a consequence you may not convey it at all. For example, + if you agree to terms that obligate you to collect a royalty for + further conveying from those to whom you convey the Program, the + only way you could satisfy both those terms and this License would + be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have + permission to link or combine any covered work with a work licensed + under version 3 of the GNU Affero General Public License into a + single combined work, and to convey the resulting work. The terms + of this License will continue to apply to the part which is the + covered work, but the special requirements of the GNU Affero + General Public License, section 13, concerning interaction through + a network will apply to the combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new + versions of the GNU General Public License from time to time. Such + new versions will be similar in spirit to the present version, but + may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Program specifies that a certain numbered version of the GNU + General Public License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that numbered version or of any later version published by the Free + Software Foundation. If the Program does not specify a version + number of the GNU General Public License, you may choose any + version ever published by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future + versions of the GNU General Public License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Program. + + Later license versions may give you additional or different + permissions. However, no additional obligations are imposed on any + author or copyright holder as a result of your choosing to follow a + later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY + APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE + COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" + WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE + RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. + SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL + NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES + AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR + DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE + THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA + BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD + PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER + PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF + THE POSSIBILITY OF SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided + above cannot be given local legal effect according to their terms, + reviewing courts shall apply local law that most closely + approximates an absolute waiver of all civil liability in + connection with the Program, unless a warranty or assumption of + liability accompanies a copy of the Program in return for a fee. + +END OF TERMS AND CONDITIONS +=========================== + +How to Apply These Terms to Your New Programs +============================================= + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or (at + your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + + Also add information on how to contact you by electronic and paper +mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + PROGRAM Copyright (C) YEAR NAME OF AUTHOR + This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type 'show c' for details. + + The hypothetical commands 'show w' and 'show c' should show the +appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an "about box". + + You should also get your employer (if you work as a programmer) or +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. For more information on this, and how to apply and follow +the GNU GPL, see . + + The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Lesser General Public License instead of this License. But first, +please read . + + +File: gdb.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Copying, Up: Top + +Appendix M GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: gdb.info, Node: Concept Index, Next: Command and Variable Index, Prev: GNU Free Documentation License, Up: Top + +Concept Index +************* + +[index] +* Menu: + +* '!' packet: Packets. (line 49) +* "No symbol "foo" in current context": Variables. (line 122) +* '#' in Modula-2: GDB/M2. (line 18) +* '$': Value History. (line 13) +* '$$': Value History. (line 13) +* '$_' and 'info breakpoints': Set Breaks. (line 125) +* '$_' and 'info line': Machine Code. (line 30) +* '$_', '$__', and value history: Memory. (line 105) +* '--annotate': Mode Options. (line 120) +* '--args': Mode Options. (line 133) +* '--attach', 'gdbserver' option: Server. (line 86) +* '--batch': Mode Options. (line 44) +* '--batch-silent': Mode Options. (line 62) +* '--baud': Mode Options. (line 139) +* '--cd': Mode Options. (line 101) +* '--command': File Options. (line 51) +* '--configuration': Mode Options. (line 183) +* '--core': File Options. (line 43) +* '--data-directory': Mode Options. (line 105) +* '--debug', 'gdbserver' option: Server. (line 166) +* '--directory': File Options. (line 77) +* '--eval-command': File Options. (line 57) +* '--exec': File Options. (line 35) +* '--fullname': Mode Options. (line 110) +* '--init-command': File Options. (line 67) +* '--init-eval-command': File Options. (line 72) +* '--interpreter': Mode Options. (line 158) +* '--multi', 'gdbserver' option: Server. (line 119) +* '--nh': Mode Options. (line 34) +* '--nowindows': Mode Options. (line 91) +* '--nx': Mode Options. (line 11) +* '--once', 'gdbserver' option: Server. (line 151) +* '--pid': File Options. (line 47) +* '--quiet': Mode Options. (line 40) +* '--readnow': File Options. (line 81) +* '--remote-debug', 'gdbserver' option: Server. (line 167) +* '--return-child-result': Mode Options. (line 74) +* '--se': File Options. (line 39) +* '--silent': Mode Options. (line 40) +* '--statistics': Mode Options. (line 175) +* '--symbols': File Options. (line 31) +* '--tty': Mode Options. (line 148) +* '--tui': Mode Options. (line 151) +* '--version': Mode Options. (line 179) +* '--windows': Mode Options. (line 97) +* '--with-gdb-datadir': Data Files. (line 19) +* '--with-relocated-sources': Source Path. (line 88) +* '--with-sysroot': Files. (line 441) +* '--wrapper', 'gdbserver' option: Server. (line 172) +* '--write': Mode Options. (line 170) +* '-b': Mode Options. (line 139) +* '-c': File Options. (line 43) +* '-d': File Options. (line 77) +* '-e': File Options. (line 35) +* '-ex': File Options. (line 57) +* '-f': Mode Options. (line 110) +* '-iex': File Options. (line 72) +* '-info-gdb-mi-command': GDB/MI Support Commands. + (line 14) +* '-ix': File Options. (line 67) +* '-l': Mode Options. (line 143) +* '-n': Mode Options. (line 11) +* '-nw': Mode Options. (line 91) +* '-p': File Options. (line 47) +* '-q': Mode Options. (line 40) +* '-r': File Options. (line 81) +* '-s': File Options. (line 31) +* '-t': Mode Options. (line 148) +* '-w': Mode Options. (line 97) +* '-x': File Options. (line 51) +* '.', Modula-2 scope operator: M2 Scope. (line 6) +* '.build-id' directory: Separate Debug Files. + (line 6) +* '.debug' subdirectories: Separate Debug Files. + (line 6) +* '.debug_gdb_scripts' section: dotdebug_gdb_scripts section. + (line 6) +* '.gdbinit': Startup. (line 65) +* '.gdb_index' section: Index Files. (line 6) +* .gdb_index section format: Index Section Format. + (line 6) +* '.gnu_debugdata' section: MiniDebugInfo. (line 6) +* '.gnu_debuglink' sections: Separate Debug Files. + (line 76) +* '.note.gnu.build-id' sections: Separate Debug Files. + (line 92) +* '.o' files, reading symbols from: Files. (line 132) +* /proc: SVR4 Process Information. + (line 6) +* : Target Description Format. + (line 72) +* '': Target Description Format. + (line 95) +* : Target Description Format. + (line 119) +* : Target Description Format. + (line 185) +* values: Registers. (line 101) +* '': Target Description Format. + (line 82) +* : Target Description Format. + (line 198) +* : Target Description Format. + (line 163) +* : Target Description Format. + (line 153) +* : Target Description Format. + (line 146) +* '?' packet: Packets. (line 58) +* '_NSPrintForDebugger', and printing Objective-C objects: The Print Command with Objective-C. + (line 11) +* {TYPE}: Expressions. (line 41) +* 'A' packet: Packets. (line 65) +* AArch64 support: AArch64. (line 6) +* abbreviation: Command Syntax. (line 13) +* acknowledgment, for GDB remote: Packet Acknowledgment. + (line 6) +* active targets: Active Targets. (line 6) +* Ada: Ada. (line 6) +* Ada exception catching: Set Catchpoints. (line 66) +* Ada mode, general: Ada Mode Intro. (line 6) +* Ada task switching: Ada Tasks. (line 113) +* Ada tasking and core file debugging: Ada Tasks and Core Files. + (line 6) +* Ada, deviations from: Additions to Ada. (line 6) +* Ada, omissions from: Omissions from Ada. (line 6) +* Ada, problems: Ada Glitches. (line 6) +* Ada, tasking: Ada Tasks. (line 6) +* add new commands for external monitor: Connecting. (line 105) +* address of a symbol: Symbols. (line 74) +* address size for remote targets: Remote Configuration. + (line 12) +* ADP (Angel Debugger Protocol) logging: ARM. (line 84) +* aggregates (Ada): Omissions from Ada. (line 44) +* AIX shared library debugging: Debugging Output. (line 30) +* AIX threads: Debugging Output. (line 36) +* aliases for commands: Aliases. (line 6) +* alignment of remote memory accesses: Packets. (line 231) +* all-stop mode: All-Stop Mode. (line 6) +* Alpha stack: MIPS. (line 6) +* ambiguous expressions: Ambiguous Expressions. + (line 6) +* annotations: Annotations Overview. + (line 6) +* annotations for errors, warnings and interrupts: Errors. (line 6) +* annotations for invalidation messages: Invalidation. (line 6) +* annotations for prompts: Prompting. (line 6) +* annotations for running programs: Annotations for Running. + (line 6) +* annotations for source display: Source Annotations. (line 6) +* append data to a file: Dump/Restore Files. (line 6) +* apply command to several threads: Threads. (line 116) +* architecture debugging info: Debugging Output. (line 23) +* argument count in user-defined commands: Define. (line 25) +* arguments (to your program): Arguments. (line 6) +* arguments, to 'gdbserver': Server. (line 34) +* arguments, to user-defined commands: Define. (line 6) +* ARM 32-bit mode: ARM. (line 24) +* ARM AArch64: Debugging Output. (line 17) +* ARM RDI: ARM. (line 6) +* array aggregates (Ada): Omissions from Ada. (line 44) +* arrays: Arrays. (line 6) +* arrays in expressions: Expressions. (line 13) +* artificial array: Arrays. (line 6) +* assembly instructions: Machine Code. (line 36) +* assignment: Assignment. (line 6) +* async output in GDB/MI: GDB/MI Output Syntax. + (line 98) +* async records in GDB/MI: GDB/MI Async Records. + (line 6) +* asynchronous execution: Background Execution. + (line 6) +* asynchronous execution, and process record and replay: Process Record and Replay. + (line 68) +* AT&T disassembly flavor: Machine Code. (line 131) +* attach: Attach. (line 6) +* attach to a program, 'gdbserver': Server. (line 86) +* auto-loading: Auto-loading. (line 6) +* auto-loading extensions: Auto-loading extensions. + (line 6) +* auto-loading init file in the current directory: Init File in the Current Directory. + (line 6) +* auto-loading libthread_db.so.1: libthread_db.so.1 file. + (line 6) +* auto-loading safe-path: Auto-loading safe path. + (line 6) +* auto-loading verbose mode: Auto-loading verbose mode. + (line 6) +* auto-retry, for remote TCP target: Remote Configuration. + (line 117) +* automatic display: Auto Display. (line 6) +* automatic hardware breakpoints: Set Breaks. (line 287) +* automatic overlay debugging: Automatic Overlay Debugging. + (line 6) +* automatic thread selection: All-Stop Mode. (line 28) +* auxiliary vector: OS Information. (line 9) +* AVR: AVR. (line 6) +* 'b' packet: Packets. (line 76) +* 'B' packet: Packets. (line 91) +* background execution: Background Execution. + (line 6) +* backtrace beyond 'main' function: Backtrace. (line 105) +* backtrace limit: Backtrace. (line 142) +* base name differences: Files. (line 508) +* baud rate for remote targets: Remote Configuration. + (line 21) +* 'bc' packet: Packets. (line 96) +* bcache statistics: Maintenance Commands. + (line 246) +* bits in remote address: Remote Configuration. + (line 12) +* blocks in python: Blocks In Python. (line 6) +* bookmark: Checkpoint/Restart. (line 6) +* branch trace format: Branch Trace Format. + (line 6) +* break in overloaded functions: Debugging C Plus Plus. + (line 9) +* break on a system call.: Set Catchpoints. (line 95) +* break on fork/exec: Set Catchpoints. (line 90) +* BREAK signal instead of Ctrl-C: Remote Configuration. + (line 29) +* breakpoint address adjusted: Breakpoint-related Warnings. + (line 6) +* breakpoint at static probe point: Specify Location. (line 91) +* breakpoint commands: Break Commands. (line 6) +* breakpoint commands for GDB/MI: GDB/MI Breakpoint Commands. + (line 6) +* breakpoint commands, in remote protocol: General Query Packets. + (line 722) +* breakpoint conditions: Conditions. (line 6) +* breakpoint kinds, ARM: ARM Breakpoint Kinds. + (line 6) +* breakpoint kinds, MIPS: MIPS Breakpoint Kinds. + (line 6) +* breakpoint numbers: Breakpoints. (line 41) +* breakpoint on events: Breakpoints. (line 33) +* breakpoint on memory address: Breakpoints. (line 20) +* breakpoint on variable modification: Breakpoints. (line 20) +* breakpoint ranges: Breakpoints. (line 48) +* 'breakpoint' subroutine, remote: Stub Contents. (line 31) +* breakpointing Ada elaboration code: Stopping Before Main Program. + (line 6) +* breakpoints: Breakpoints. (line 6) +* breakpoints and tasks, in Ada: Ada Tasks. (line 133) +* breakpoints and threads: Thread-Specific Breakpoints. + (line 10) +* breakpoints at functions matching a regexp: Set Breaks. (line 89) +* breakpoints in overlays: Overlay Commands. (line 91) +* breakpoints in python: Breakpoints In Python. + (line 6) +* breakpoints, multiple locations: Set Breaks. (line 192) +* 'bs' packet: Packets. (line 102) +* bug criteria: Bug Criteria. (line 6) +* bug reports: Bug Reporting. (line 6) +* bugs in GDB: GDB Bugs. (line 6) +* build ID sections: Separate Debug Files. + (line 92) +* build ID, and separate debugging files: Separate Debug Files. + (line 6) +* building GDB, requirements for: Requirements. (line 6) +* built-in simulator target: Target Commands. (line 73) +* builtin Go functions: Go. (line 31) +* builtin Go types: Go. (line 28) +* C and C++: C. (line 6) +* C and C++ checks: C Checks. (line 6) +* C and C++ constants: C Constants. (line 6) +* C and C++ defaults: C Defaults. (line 6) +* C and C++ operators: C Operators. (line 6) +* 'c' packet: Packets. (line 109) +* 'C' packet: Packets. (line 118) +* C++: C. (line 10) +* C++ compilers: C Plus Plus Expressions. + (line 8) +* C++ exception handling: Debugging C Plus Plus. + (line 20) +* C++ overload debugging info: Debugging Output. (line 127) +* C++ scope resolution: Variables. (line 90) +* C++ symbol decoding style: Print Settings. (line 427) +* C++ symbol display: Debugging C Plus Plus. + (line 36) +* caching data of targets: Caching Target Data. + (line 6) +* call dummy stack unwinding: Calling. (line 35) +* call dummy stack unwinding on unhandled exception.: Calling. + (line 46) +* call overloaded functions: C Plus Plus Expressions. + (line 26) +* call stack: Stack. (line 9) +* call stack traces: Backtrace. (line 6) +* call-clobbered registers: Registers. (line 101) +* caller-saved registers: Registers. (line 101) +* calling functions: Calling. (line 6) +* calling make: Shell Commands. (line 21) +* case sensitivity in symbol names: Symbols. (line 27) +* case-insensitive symbol names: Symbols. (line 27) +* casts, in expressions: Expressions. (line 26) +* casts, to view memory: Expressions. (line 41) +* catch Ada exceptions: Set Catchpoints. (line 66) +* catchpoints: Breakpoints. (line 33) +* catchpoints, setting: Set Catchpoints. (line 6) +* Cell Broadband Engine: SPU. (line 6) +* change working directory: Working Directory. (line 16) +* character sets: Character Sets. (line 6) +* charset: Character Sets. (line 6) +* checkpoint: Checkpoint/Restart. (line 6) +* checkpoints and process id: Checkpoint/Restart. (line 76) +* checks, range: Type Checking. (line 44) +* checks, type: Checks. (line 23) +* checksum, for GDB remote: Overview. (line 21) +* choosing target byte order: Byte Order. (line 6) +* circular trace buffer: Starting and Stopping Trace Experiments. + (line 80) +* clearing breakpoints, watchpoints, catchpoints: Delete Breaks. + (line 6) +* close, file-i/o system call: close. (line 6) +* closest symbol and offset for an address: Symbols. (line 84) +* code address and its source line: Machine Code. (line 25) +* code compression, MIPS: MIPS. (line 49) +* COFF/PE exported symbols: Debugging Output. (line 50) +* collected data discarded: Starting and Stopping Trace Experiments. + (line 6) +* colon, doubled as scope operator: M2 Scope. (line 6) +* colon-colon, context for variables/functions: Variables. (line 44) +* command editing: Readline Bare Essentials. + (line 6) +* command files: Command Files. (line 6) +* command history: Command History. (line 6) +* command hooks: Hooks. (line 6) +* command interpreters: Interpreters. (line 6) +* command line editing: Editing. (line 6) +* command scripts, debugging: Messages/Warnings. (line 65) +* command tracing: Messages/Warnings. (line 60) +* commands for C++: Debugging C Plus Plus. + (line 6) +* commands in python: Commands In Python. (line 6) +* commands to access python: Python Commands. (line 6) +* comment: Command Syntax. (line 37) +* 'COMMON' blocks, Fortran: Special Fortran Commands. + (line 9) +* common targets: Target Commands. (line 46) +* compatibility, GDB/MI and CLI: GDB/MI Compatibility with CLI. + (line 6) +* compilation directory: Source Path. (line 106) +* compiling, on Sparclet: Sparclet. (line 16) +* completion: Completion. (line 6) +* completion of Python commands: Commands In Python. (line 70) +* completion of quoted strings: Completion. (line 57) +* completion of structure field names: Completion. (line 95) +* completion of union field names: Completion. (line 95) +* compressed debug sections: Requirements. (line 38) +* conditional breakpoints: Conditions. (line 6) +* conditional tracepoints: Tracepoint Conditions. + (line 6) +* configuring GDB: Running Configure. (line 6) +* confirmation: Messages/Warnings. (line 49) +* connection timeout, for remote TCP target: Remote Configuration. + (line 133) +* console i/o as part of file-i/o: Console I/O. (line 6) +* console interpreter: Interpreters. (line 21) +* console output in GDB/MI: GDB/MI Output Syntax. + (line 106) +* constants, in file-i/o protocol: Constants. (line 6) +* continuing: Continuing and Stepping. + (line 6) +* continuing threads: Thread Stops. (line 6) +* control C, and remote debugging: Bootstrapping. (line 25) +* controlling terminal: Input/Output. (line 23) +* convenience functions: Convenience Funs. (line 6) +* convenience functions in python: Functions In Python. + (line 6) +* convenience variables: Convenience Vars. (line 6) +* convenience variables for tracepoints: Tracepoint Variables. + (line 6) +* convenience variables, and trace state variables: Trace State Variables. + (line 17) +* convenience variables, initializing: Convenience Vars. (line 42) +* core dump file: Files. (line 6) +* core dump file target: Target Commands. (line 54) +* crash of debugger: Bug Criteria. (line 9) +* CRC algorithm definition: Separate Debug Files. + (line 136) +* CRC of memory block, remote request: General Query Packets. + (line 65) +* CRIS: CRIS. (line 6) +* CRIS mode: CRIS. (line 26) +* CRIS version: CRIS. (line 10) +* Ctrl-BREAK, MS-Windows: Cygwin Native. (line 9) +* ctrl-c message, in file-i/o protocol: The Ctrl-C Message. (line 6) +* current Ada task ID: Ada Tasks. (line 103) +* current directory: Source Path. (line 106) +* current Go package: Go. (line 11) +* current stack frame: Frames. (line 45) +* current thread: Threads. (line 39) +* current thread, remote request: General Query Packets. + (line 55) +* custom JIT debug info: Custom Debug Info. (line 6) +* Cygwin DLL, debugging: Cygwin Native. (line 42) +* Cygwin-specific commands: Cygwin Native. (line 6) +* D: D. (line 6) +* 'd' packet: Packets. (line 127) +* 'D' packet: Packets. (line 134) +* Darwin: Darwin. (line 6) +* data breakpoints: Breakpoints. (line 20) +* data manipulation, in GDB/MI: GDB/MI Data Manipulation. + (line 6) +* dcache line-size: Caching Target Data. + (line 60) +* dcache size: Caching Target Data. + (line 57) +* dead names, GNU Hurd: Hurd Native. (line 84) +* debug expression parser: Debugging Output. (line 132) +* debug formats and C++: C Plus Plus Expressions. + (line 8) +* debug link sections: Separate Debug Files. + (line 76) +* debug remote protocol: Debugging Output. (line 139) +* debugger crash: Bug Criteria. (line 9) +* debugging agent: In-Process Agent. (line 6) +* debugging C++ programs: C Plus Plus Expressions. + (line 8) +* debugging information directory, global: Separate Debug Files. + (line 6) +* debugging information in separate files: Separate Debug Files. + (line 6) +* debugging 'libthread_db': Threads. (line 209) +* debugging multiple processes: Forks. (line 51) +* debugging optimized code: Optimized Code. (line 6) +* debugging stub, example: Remote Stub. (line 6) +* debugging target: Targets. (line 6) +* debugging the Cygwin DLL: Cygwin Native. (line 42) +* decimal floating point format: Decimal Floating Point. + (line 6) +* default collection action: Tracepoint Actions. (line 134) +* default data directory: Data Files. (line 19) +* default source path substitution: Source Path. (line 88) +* default system root: Files. (line 441) +* define trace state variable, remote request: Tracepoint Packets. + (line 121) +* defining macros interactively: Macros. (line 59) +* definition of a macro, showing: Macros. (line 47) +* delete breakpoints: Delete Breaks. (line 41) +* deleting breakpoints, watchpoints, catchpoints: Delete Breaks. + (line 6) +* deliver a signal to a program: Signaling. (line 6) +* demangling C++ names: Print Settings. (line 408) +* deprecated commands: Maintenance Commands. + (line 109) +* derived type of an object, printing: Print Settings. (line 460) +* descriptor tables display: DJGPP Native. (line 24) +* detach from task, GNU Hurd: Hurd Native. (line 59) +* detach from thread, GNU Hurd: Hurd Native. (line 109) +* direct memory access (DMA) on MS-DOS: DJGPP Native. (line 74) +* directories for source files: Source Path. (line 6) +* directory, compilation: Source Path. (line 106) +* directory, current: Source Path. (line 106) +* disable address space randomization, remote request: General Query Packets. + (line 84) +* disconnected tracing: Starting and Stopping Trace Experiments. + (line 45) +* displaced stepping debugging info: Debugging Output. (line 68) +* displaced stepping support: Maintenance Commands. + (line 66) +* displaced stepping, and process record and replay: Process Record and Replay. + (line 63) +* display command history: Command History. (line 80) +* display derived types: Print Settings. (line 460) +* display disabled out of scope: Auto Display. (line 86) +* display GDB copyright: Help. (line 138) +* display of expressions: Auto Display. (line 6) +* display remote monitor communications: Target Commands. (line 101) +* display remote packets: Debugging Output. (line 139) +* DJGPP debugging: DJGPP Native. (line 6) +* DLLs with no debugging symbols: Non-debug DLL Symbols. + (line 6) +* do not print frame argument values: Print Settings. (line 154) +* documentation: Formatting Documentation. + (line 22) +* don't repeat command: Define. (line 61) +* don't repeat Python command: Commands In Python. (line 42) +* DOS file-name semantics of file names.: Files. (line 464) +* DOS serial data link, remote debugging: DJGPP Native. (line 118) +* DOS serial port status: DJGPP Native. (line 139) +* download server address (M32R): M32R/D. (line 27) +* download to Sparclet: Sparclet Download. (line 6) +* download to VxWorks: VxWorks Download. (line 6) +* DPMI: DJGPP Native. (line 6) +* dprintf: Dynamic Printf. (line 6) +* dump all data collected at tracepoint: tdump. (line 6) +* dump core from inferior: Core File Generation. + (line 6) +* dump data to a file: Dump/Restore Files. (line 6) +* dump/restore files: Dump/Restore Files. (line 6) +* DVC register: PowerPC Embedded. (line 6) +* DWARF 2 compilation units cache: Maintenance Commands. + (line 303) +* DWARF-2 CFI and CRIS: CRIS. (line 18) +* DWARF2 DIEs: Debugging Output. (line 56) +* DWARF2 Reading: Debugging Output. (line 61) +* dynamic linking: Files. (line 112) +* dynamic printf: Dynamic Printf. (line 6) +* dynamic varobj: GDB/MI Variable Objects. + (line 166) +* editing: Editing. (line 15) +* editing command lines: Readline Bare Essentials. + (line 6) +* editing source files: Edit. (line 6) +* eight-bit characters in strings: Print Settings. (line 353) +* elaboration phase: Starting. (line 90) +* ELinOS system-wide configuration script: System-wide Configuration Scripts. + (line 15) +* Emacs: Emacs. (line 6) +* empty response, for unsupported packets: Overview. (line 97) +* enable/disable a breakpoint: Disabling. (line 6) +* entering numbers: Numbers. (line 6) +* environment (of your program): Environment. (line 6) +* errno values, in file-i/o protocol: Errno Values. (line 6) +* error on valid input: Bug Criteria. (line 12) +* event debugging info: Debugging Output. (line 74) +* event designators: Event Designators. (line 6) +* event handling: Set Catchpoints. (line 6) +* examine process image: SVR4 Process Information. + (line 6) +* examining data: Data. (line 6) +* examining memory: Memory. (line 9) +* exception handlers: Set Catchpoints. (line 6) +* exceptions, python: Exception Handling. (line 6) +* executable file: Files. (line 16) +* executable file target: Target Commands. (line 50) +* executable file, for remote target: Remote Configuration. + (line 88) +* execute commands from a file: Command Files. (line 17) +* execute forward or backward in time: Reverse Execution. (line 86) +* execute remote command, remote request: General Query Packets. + (line 333) +* execution, foreground, background and asynchronous: Background Execution. + (line 6) +* exiting GDB: Quitting GDB. (line 6) +* expand macro once: Macros. (line 38) +* expanding preprocessor macros: Macros. (line 29) +* explore type: Data. (line 145) +* explore value: Data. (line 138) +* exploring hierarchical data structures: Data. (line 36) +* expression debugging info: Debugging Output. (line 79) +* expression parser, debugging info: Debugging Output. (line 132) +* expressions: Expressions. (line 6) +* expressions in Ada: Ada. (line 11) +* expressions in C or C++: C. (line 6) +* expressions in C++: C Plus Plus Expressions. + (line 6) +* expressions in Modula-2: Modula-2. (line 12) +* extend GDB for remote targets: Connecting. (line 105) +* extending GDB: Extending GDB. (line 6) +* extra signal information: Signals. (line 106) +* 'F' packet: Packets. (line 150) +* 'F' reply packet: The F Reply Packet. (line 6) +* 'F' request packet: The F Request Packet. + (line 6) +* fast tracepoints: Set Tracepoints. (line 24) +* fast tracepoints, setting: Create and Delete Tracepoints. + (line 51) +* fatal signal: Bug Criteria. (line 9) +* fatal signals: Signals. (line 15) +* features of the remote protocol: General Query Packets. + (line 386) +* file name canonicalization: Files. (line 508) +* file transfer: File Transfer. (line 6) +* file transfer, remote protocol: Host I/O Packets. (line 6) +* file-i/o examples: File-I/O Examples. (line 6) +* file-i/o overview: File-I/O Overview. (line 6) +* File-I/O remote protocol extension: File-I/O Remote Protocol Extension. + (line 6) +* file-i/o reply packet: The F Reply Packet. (line 6) +* file-i/o request packet: The F Request Packet. + (line 6) +* filename-display: Backtrace. (line 152) +* find downloadable SREC files (M32R): M32R/D. (line 15) +* find trace snapshot: tfind. (line 6) +* flinching: Messages/Warnings. (line 49) +* float promotion: ABI. (line 34) +* floating point: Floating Point Hardware. + (line 6) +* floating point registers: Registers. (line 15) +* floating point, MIPS remote: MIPS Embedded. (line 58) +* focus of debugging: Threads. (line 39) +* foo: Symbol Errors. (line 54) +* foreground execution: Background Execution. + (line 6) +* fork, debugging programs which call: Forks. (line 6) +* format options: Print Settings. (line 6) +* formatted output: Output Formats. (line 6) +* Fortran: Summary. (line 40) +* Fortran Defaults: Fortran Defaults. (line 6) +* Fortran operators and expressions: Fortran Operators. (line 6) +* Fortran-specific support in GDB: Fortran. (line 6) +* FR-V shared-library debugging: Debugging Output. (line 152) +* frame debugging info: Debugging Output. (line 85) +* frame decorator api: Frame Decorator API. + (line 6) +* frame filters api: Frame Filter API. (line 6) +* frame number: Frames. (line 28) +* frame pointer: Frames. (line 21) +* frame pointer register: Registers. (line 26) +* frame, definition: Frames. (line 6) +* frameless execution: Frames. (line 34) +* frames in python: Frames In Python. (line 6) +* free memory information (MS-DOS): DJGPP Native. (line 19) +* fstat, file-i/o system call: stat/fstat. (line 6) +* Fujitsu: Remote Stub. (line 68) +* full symbol tables, listing GDB's internal: Symbols. (line 357) +* function call arguments, optimized out: Backtrace. (line 83) +* function entry/exit, wrong values of variables: Variables. (line 106) +* functions without line info, and stepping: Continuing and Stepping. + (line 91) +* 'g' packet: Packets. (line 155) +* 'G' packet: Packets. (line 184) +* 'g++', GNU C++ compiler: C. (line 10) +* garbled pointers: DJGPP Native. (line 42) +* GCC and C++: C Plus Plus Expressions. + (line 8) +* GDB bugs, reporting: Bug Reporting. (line 6) +* GDB internal error: Maintenance Commands. + (line 143) +* gdb module: Basic Python. (line 28) +* GDB reference card: Formatting Documentation. + (line 6) +* GDB startup: Startup. (line 6) +* GDB version number: Help. (line 128) +* 'gdb.ini': Startup. (line 65) +* gdb.printing: gdb.printing. (line 6) +* gdb.prompt: gdb.prompt. (line 6) +* gdb.types: gdb.types. (line 6) +* 'gdb.Value': Values From Inferior. + (line 6) +* GDB/MI development: GDB/MI Development and Front Ends. + (line 6) +* GDB/MI General Design: GDB/MI General Design. + (line 6) +* GDB/MI, async records: GDB/MI Async Records. + (line 6) +* GDB/MI, breakpoint commands: GDB/MI Breakpoint Commands. + (line 6) +* GDB/MI, compatibility with CLI: GDB/MI Compatibility with CLI. + (line 6) +* GDB/MI, data manipulation: GDB/MI Data Manipulation. + (line 6) +* GDB/MI, input syntax: GDB/MI Input Syntax. + (line 6) +* GDB/MI, its purpose: GDB/MI. (line 9) +* GDB/MI, output syntax: GDB/MI Output Syntax. + (line 6) +* GDB/MI, result records: GDB/MI Result Records. + (line 6) +* GDB/MI, simple examples: GDB/MI Simple Examples. + (line 6) +* GDB/MI, stream records: GDB/MI Stream Records. + (line 6) +* gdbarch debugging info: Debugging Output. (line 23) +* 'GDBHISTFILE', environment variable: Command History. (line 26) +* 'gdbserver', command-line arguments: Server. (line 34) +* 'gdbserver', multiple processes: Server. (line 106) +* gdbserver, search path for 'libthread_db': Server. (line 237) +* GDT: DJGPP Native. (line 24) +* get thread information block address: General Query Packets. + (line 171) +* get thread-local storage address, remote request: General Query Packets. + (line 140) +* gettimeofday, file-i/o system call: gettimeofday. (line 6) +* getting structure elements using gdb.Field objects as subscripts: Values From Inferior. + (line 26) +* global debugging information directories: Separate Debug Files. + (line 6) +* GNU C++: C. (line 10) +* GNU Emacs: Emacs. (line 6) +* GNU Hurd debugging: Hurd Native. (line 6) +* GNU/Hurd debug messages: Debugging Output. (line 90) +* GNU/Linux LWP debug messages: Debugging Output. (line 105) +* Go (programming language): Go. (line 6) +* 'H' packet: Packets. (line 194) +* handling signals: Signals. (line 27) +* hardware breakpoints: Set Breaks. (line 60) +* hardware debug registers: Maintenance Commands. + (line 329) +* hardware watchpoints: Set Watchpoints. (line 31) +* hash mark while downloading: Target Commands. (line 92) +* 'heuristic-fence-post' (Alpha, MIPS): MIPS. (line 14) +* history events: Event Designators. (line 8) +* history expansion: History Interaction. + (line 6) +* history expansion, turn on/off: Command History. (line 55) +* history file: Command History. (line 26) +* history number: Value History. (line 13) +* history of values printed by GDB: Value History. (line 6) +* history size: Command History. (line 45) +* history substitution: Command History. (line 26) +* 'HISTSIZE', environment variable: Command History. (line 45) +* hooks, for commands: Hooks. (line 6) +* hooks, post-command: Hooks. (line 11) +* hooks, pre-command: Hooks. (line 6) +* host character set: Character Sets. (line 6) +* Host I/O, remote protocol: Host I/O Packets. (line 6) +* how many arguments (user-defined commands): Define. (line 25) +* HPPA support: HPPA. (line 6) +* 'i' packet: Packets. (line 208) +* 'I' packet: Packets. (line 213) +* i/o: Input/Output. (line 6) +* I/O registers (Atmel AVR): AVR. (line 10) +* i386: Remote Stub. (line 56) +* 'i386-stub.c': Remote Stub. (line 56) +* IDT: DJGPP Native. (line 24) +* ignore count (of breakpoint): Conditions. (line 79) +* in-process agent protocol: In-Process Agent Protocol. + (line 6) +* incomplete type: Symbols. (line 206) +* indentation in structure display: Print Settings. (line 329) +* index files: Index Files. (line 6) +* index section format: Index Section Format. + (line 6) +* inferior: Inferiors and Programs. + (line 13) +* inferior debugging info: Debugging Output. (line 94) +* inferior events in Python: Events In Python. (line 6) +* inferior functions, calling: Calling. (line 6) +* inferior tty: Input/Output. (line 44) +* inferiors in Python: Inferiors In Python. + (line 6) +* infinite recursion in user-defined commands: Define. (line 78) +* info for known .debug_gdb_scripts-loaded scripts: Maintenance Commands. + (line 239) +* info for known object files: Maintenance Commands. + (line 233) +* info proc cmdline: SVR4 Process Information. + (line 35) +* info proc cwd: SVR4 Process Information. + (line 39) +* info proc exe: SVR4 Process Information. + (line 43) +* information about static tracepoint markers: Listing Static Tracepoint Markers. + (line 6) +* information about tracepoints: Listing Tracepoints. + (line 6) +* inheritance: Debugging C Plus Plus. + (line 26) +* init file: Startup. (line 11) +* init file name: Startup. (line 65) +* initial frame: Frames. (line 12) +* initialization file, readline: Readline Init File. (line 6) +* inline functions, debugging: Inline Functions. (line 6) +* innermost frame: Frames. (line 12) +* input syntax for GDB/MI: GDB/MI Input Syntax. + (line 6) +* installation: Installing GDB. (line 6) +* instructions, assembly: Machine Code. (line 36) +* integral datatypes, in file-i/o protocol: Integral Datatypes. + (line 6) +* Intel: Remote Stub. (line 56) +* Intel disassembly flavor: Machine Code. (line 131) +* Intel(R) Memory Protection Extensions (MPX).: i386. (line 21) +* interaction, readline: Readline Interaction. + (line 6) +* internal commands: Maintenance Commands. + (line 6) +* internal errors, control of GDB behavior: Maintenance Commands. + (line 143) +* internal GDB breakpoints: Set Breaks. (line 373) +* interrupt: Quitting GDB. (line 13) +* interrupt debuggee on MS-Windows: Cygwin Native. (line 9) +* interrupt remote programs: Remote Configuration. + (line 29) +* interrupt remote programs <1>: Remote Configuration. + (line 94) +* interrupting remote programs: Connecting. (line 78) +* interrupting remote targets: Bootstrapping. (line 25) +* interrupts (remote protocol): Interrupts. (line 6) +* invalid input: Bug Criteria. (line 16) +* invoke another interpreter: Interpreters. (line 36) +* ipa protocol commands: IPA Protocol Commands. + (line 6) +* ipa protocol objects: IPA Protocol Objects. + (line 6) +* isatty, file-i/o system call: isatty. (line 6) +* JIT compilation interface: JIT Interface. (line 6) +* JIT debug info reader: Custom Debug Info. (line 6) +* just-in-time compilation: JIT Interface. (line 6) +* just-in-time compilation, debugging messages: Debugging Output. + (line 101) +* 'k' packet: Packets. (line 217) +* kernel crash dump: BSD libkvm Interface. + (line 6) +* kernel memory image: BSD libkvm Interface. + (line 6) +* kill ring: Readline Killing Commands. + (line 18) +* killing text: Readline Killing Commands. + (line 6) +* languages: Languages. (line 6) +* last tracepoint number: Create and Delete Tracepoints. + (line 123) +* latest breakpoint: Set Breaks. (line 6) +* lazy strings in python: Lazy Strings In Python. + (line 6) +* LDT: DJGPP Native. (line 24) +* leaving GDB: Quitting GDB. (line 6) +* libkvm: BSD libkvm Interface. + (line 6) +* library list format, remote protocol: Library List Format. + (line 6) +* library list format, remote protocol <1>: Library List Format for SVR4 Targets. + (line 6) +* limit hardware breakpoints and watchpoints: Remote Configuration. + (line 72) +* limit hardware watchpoints length: Remote Configuration. + (line 77) +* limit on number of printed array elements: Print Settings. (line 141) +* limits, in file-i/o protocol: Limits. (line 6) +* line tables in python: Line Tables In Python. + (line 6) +* linespec: Specify Location. (line 6) +* Linux lightweight processes: Debugging Output. (line 105) +* list active threads, remote request: General Query Packets. + (line 114) +* list of supported file-i/o calls: List of Supported Calls. + (line 6) +* list output in GDB/MI: GDB/MI Output Syntax. + (line 117) +* 'list', how many lines to display: List. (line 30) +* listing GDB's internal symbol tables: Symbols. (line 357) +* listing machine instructions: Machine Code. (line 36) +* listing mapped overlays: Overlay Commands. (line 60) +* load address, overlay's: How Overlays Work. (line 6) +* load shared library: Files. (line 325) +* load symbols from memory: Files. (line 179) +* local variables: Symbols. (line 249) +* locate address: Output Formats. (line 35) +* lock scheduler: All-Stop Mode. (line 37) +* log output in GDB/MI: GDB/MI Output Syntax. + (line 113) +* logging file name: Logging Output. (line 12) +* logging GDB output: Logging Output. (line 6) +* lseek flags, in file-i/o protocol: Lseek Flags. (line 6) +* lseek, file-i/o system call: lseek. (line 6) +* 'm' packet: Packets. (line 224) +* 'M' packet: Packets. (line 243) +* M32-EVA target board address: M32R/D. (line 21) +* M32R/Chaos debugging: M32R/D. (line 50) +* m680x0: Remote Stub. (line 59) +* 'm68k-stub.c': Remote Stub. (line 59) +* Mach-O symbols processing: Debugging Output. (line 110) +* machine instructions: Machine Code. (line 36) +* macro definition, showing: Macros. (line 47) +* macro expansion, showing the results of preprocessor: Macros. + (line 29) +* macros, example of debugging with: Macros. (line 83) +* macros, from debug info: Macros. (line 47) +* macros, user-defined: Macros. (line 59) +* mailing lists: GDB/MI Development and Front Ends. + (line 34) +* maintenance commands: Maintenance Commands. + (line 6) +* Man pages: Man Pages. (line 6) +* managing frame filters: Frame Filter Management. + (line 6) +* manual overlay debugging: Overlay Commands. (line 23) +* map an overlay: Overlay Commands. (line 30) +* mapinfo list, QNX Neutrino: SVR4 Process Information. + (line 93) +* mapped address: How Overlays Work. (line 6) +* mapped overlays: How Overlays Work. (line 6) +* markers, static tracepoints: Set Tracepoints. (line 28) +* maximum value for offset of closest symbol: Print Settings. + (line 70) +* member functions: C Plus Plus Expressions. + (line 16) +* memory address space mappings: SVR4 Process Information. + (line 47) +* memory map format: Memory Map Format. (line 6) +* memory region attributes: Memory Region Attributes. + (line 6) +* memory tracing: Breakpoints. (line 20) +* memory transfer, in file-i/o protocol: Memory Transfer. (line 6) +* memory used by commands: Maintenance Commands. + (line 382) +* memory used for symbol tables: Files. (line 313) +* memory, alignment and size of remote accesses: Packets. (line 231) +* memory, viewing as typed object: Expressions. (line 41) +* mi interpreter: Interpreters. (line 26) +* mi1 interpreter: Interpreters. (line 34) +* mi2 interpreter: Interpreters. (line 31) +* minimal language: Unsupported Languages. + (line 6) +* minimal symbol dump: Symbols. (line 339) +* Minimal symbols and DLLs: Non-debug DLL Symbols. + (line 6) +* MIPS addresses, masking: MIPS. (line 80) +* MIPS boards: MIPS Embedded. (line 6) +* MIPS remote floating point: MIPS Embedded. (line 58) +* MIPS stack: MIPS. (line 6) +* miscellaneous settings: Other Misc Settings. + (line 6) +* MMX registers (x86): Registers. (line 71) +* mode_t values, in file-i/o protocol: mode_t Values. (line 6) +* Modula-2: Summary. (line 29) +* Modula-2 built-ins: Built-In Func/Proc. (line 6) +* Modula-2 checks: M2 Checks. (line 6) +* Modula-2 constants: Built-In Func/Proc. (line 111) +* Modula-2 defaults: M2 Defaults. (line 6) +* Modula-2 operators: M2 Operators. (line 6) +* Modula-2 types: M2 Types. (line 6) +* Modula-2, deviations from: Deviations. (line 6) +* Modula-2, GDB support: Modula-2. (line 6) +* monitor commands, for 'gdbserver': Server. (line 220) +* Motorola 680x0: Remote Stub. (line 59) +* MS Windows debugging: Cygwin Native. (line 6) +* MS-DOS system info: DJGPP Native. (line 19) +* MS-DOS-specific commands: DJGPP Native. (line 6) +* multiple locations, breakpoints: Set Breaks. (line 192) +* multiple processes: Forks. (line 6) +* multiple processes with 'gdbserver': Server. (line 106) +* multiple targets: Active Targets. (line 6) +* multiple threads: Threads. (line 6) +* multiple threads, backtrace: Backtrace. (line 49) +* multiple-symbols menu: Ambiguous Expressions. + (line 51) +* multiprocess extensions, in remote protocol: General Query Packets. + (line 652) +* name a thread: Threads. (line 125) +* names of symbols: Symbols. (line 14) +* namespace in C++: C Plus Plus Expressions. + (line 20) +* native Cygwin debugging: Cygwin Native. (line 6) +* native DJGPP debugging: DJGPP Native. (line 6) +* native script auto-loading: Auto-loading sequences. + (line 6) +* negative breakpoint numbers: Set Breaks. (line 373) +* 'New' SYSTAG message: Threads. (line 45) +* Newlib OS ABI and its influence on the longjmp handling: ABI. + (line 11) +* Nios II architecture: Nios II. (line 6) +* non-member C++ functions, set breakpoint in: Set Breaks. (line 105) +* non-stop mode: Non-Stop Mode. (line 6) +* non-stop mode, and 'breakpoint always-inserted': Set Breaks. + (line 329) +* non-stop mode, and process record and replay: Process Record and Replay. + (line 68) +* non-stop mode, and 'set displaced-stepping': Maintenance Commands. + (line 83) +* non-stop mode, remote request: General Query Packets. + (line 247) +* noninvasive task options: Hurd Native. (line 72) +* notation, readline: Readline Bare Essentials. + (line 6) +* notational conventions, for GDB/MI: GDB/MI. (line 25) +* notification packets: Notification Packets. + (line 6) +* notify output in GDB/MI: GDB/MI Output Syntax. + (line 102) +* NULL elements in arrays: Print Settings. (line 320) +* number of array elements to print: Print Settings. (line 141) +* number representation: Numbers. (line 6) +* numbers for breakpoints: Breakpoints. (line 41) +* object files, relocatable, reading symbols from: Files. (line 132) +* Objective-C: Objective-C. (line 6) +* Objective-C, classes and selectors: Symbols. (line 309) +* Objective-C, print objects: The Print Command with Objective-C. + (line 6) +* 'OBJFILE-gdb.gdb': objfile-gdbdotext file. + (line 6) +* 'OBJFILE-gdb.py': objfile-gdbdotext file. + (line 6) +* 'OBJFILE-gdb.scm': objfile-gdbdotext file. + (line 6) +* objfiles in python: Objfiles In Python. (line 6) +* observer debugging info: Debugging Output. (line 122) +* octal escapes in strings: Print Settings. (line 353) +* online documentation: Help. (line 6) +* opaque data types: Symbols. (line 321) +* open flags, in file-i/o protocol: Open Flags. (line 6) +* open, file-i/o system call: open. (line 6) +* OpenCL C: OpenCL C. (line 6) +* OpenCL C Datatypes: OpenCL C Datatypes. (line 6) +* OpenCL C Expressions: OpenCL C Expressions. + (line 6) +* OpenCL C Operators: OpenCL C Operators. (line 6) +* operating system information: Operating System Information. + (line 6) +* operating system information, process list: Process list. (line 6) +* optimized code, debugging: Optimized Code. (line 6) +* optimized code, wrong values of variables: Variables. (line 106) +* optimized out value in Python: Values From Inferior. + (line 56) +* optimized out, in backtrace: Backtrace. (line 83) +* optional debugging messages: Debugging Output. (line 6) +* optional warnings: Messages/Warnings. (line 6) +* OS ABI: ABI. (line 11) +* OS information: OS Information. (line 6) +* out-of-line single-stepping: Maintenance Commands. + (line 66) +* outermost frame: Frames. (line 12) +* output formats: Output Formats. (line 6) +* output syntax of GDB/MI: GDB/MI Output Syntax. + (line 6) +* overlay area: How Overlays Work. (line 6) +* overlay example program: Overlay Sample Program. + (line 6) +* overlays: Overlays. (line 6) +* overlays, setting breakpoints in: Overlay Commands. (line 91) +* overloaded functions, calling: C Plus Plus Expressions. + (line 26) +* overloaded functions, overload resolution: Debugging C Plus Plus. + (line 55) +* overloading in C++: Debugging C Plus Plus. + (line 15) +* 'p' packet: Packets. (line 255) +* 'P' packet: Packets. (line 268) +* packet acknowledgment, for GDB remote: Packet Acknowledgment. + (line 6) +* packet size, remote protocol: General Query Packets. + (line 562) +* packets, notification: Notification Packets. + (line 6) +* packets, reporting on stdout: Debugging Output. (line 139) +* packets, tracepoint: Tracepoint Packets. (line 6) +* page tables display (MS-DOS): DJGPP Native. (line 55) +* parameters in python: Parameters In Python. + (line 6) +* partial symbol dump: Symbols. (line 339) +* partial symbol tables, listing GDB's internal: Symbols. (line 357) +* Pascal: Summary. (line 35) +* Pascal objects, static members display: Print Settings. (line 489) +* Pascal support in GDB, limitations: Pascal. (line 6) +* pass signals to inferior, remote request: General Query Packets. + (line 267) +* patching binaries: Patching. (line 6) +* patching object files: Files. (line 26) +* pause current task (GNU Hurd): Hurd Native. (line 48) +* pause current thread (GNU Hurd): Hurd Native. (line 90) +* pauses in output: Screen Size. (line 6) +* pending breakpoints: Set Breaks. (line 236) +* physical address from linear address: DJGPP Native. (line 80) +* physname: Debugging Output. (line 41) +* pipe, 'target remote' to: Connecting. (line 61) +* pipes: Starting. (line 62) +* pointer values, in file-i/o protocol: Pointer Values. (line 6) +* pointer, finding referent: Print Settings. (line 80) +* port rights, GNU Hurd: Hurd Native. (line 84) +* port sets, GNU Hurd: Hurd Native. (line 84) +* PowerPC architecture: PowerPC. (line 6) +* prefix for data files: Data Files. (line 6) +* prefix for shared library file names: Files. (line 381) +* premature return from system calls: Interrupted System Calls. + (line 6) +* preprocessor macro expansion, showing the results of: Macros. + (line 29) +* pretty print arrays: Print Settings. (line 115) +* pretty print C++ virtual function tables: Print Settings. (line 500) +* pretty-printer commands: Pretty-Printer Commands. + (line 6) +* print all frame argument values: Print Settings. (line 154) +* print an Objective-C object description: The Print Command with Objective-C. + (line 11) +* print array indexes: Print Settings. (line 125) +* print frame argument values for scalars only: Print Settings. + (line 154) +* print list of auto-loaded canned sequences of commands scripts: Auto-loading sequences. + (line 21) +* print list of auto-loaded Python scripts: Python Auto-loading. + (line 23) +* print messages on inferior start and exit: Inferiors and Programs. + (line 117) +* print messages on thread start and exit: Threads. (line 150) +* print settings: Print Settings. (line 6) +* print structures in indented form: Print Settings. (line 329) +* print/don't print memory addresses: Print Settings. (line 13) +* printing byte arrays: Output Formats. (line 60) +* printing data: Data. (line 6) +* printing frame argument values: Print Settings. (line 154) +* printing strings: Output Formats. (line 60) +* probe static tracepoint marker: Create and Delete Tracepoints. + (line 76) +* probing markers, static tracepoints: Set Tracepoints. (line 28) +* process detailed status information: SVR4 Process Information. + (line 55) +* process ID: SVR4 Process Information. + (line 19) +* process info via '/proc': SVR4 Process Information. + (line 6) +* process list, QNX Neutrino: SVR4 Process Information. + (line 89) +* process record and replay: Process Record and Replay. + (line 6) +* process status register: Registers. (line 26) +* processes, multiple: Forks. (line 6) +* 'procfs' API calls: SVR4 Process Information. + (line 68) +* profiling GDB: Maintenance Commands. + (line 313) +* program counter register: Registers. (line 26) +* program entry point: Backtrace. (line 105) +* programming in python: Python API. (line 6) +* progspaces in python: Progspaces In Python. + (line 6) +* prompt: Prompt. (line 6) +* protocol basics, file-i/o: Protocol Basics. (line 6) +* protocol, GDB remote serial: Overview. (line 14) +* protocol-specific representation of datatypes, in file-i/o protocol: Protocol-specific Representation of Datatypes. + (line 6) +* python api: Python API. (line 6) +* Python architectures: Architectures In Python. + (line 6) +* Python auto-loading: Python Auto-loading. + (line 6) +* python commands: Python Commands. (line 6) +* python commands <1>: Commands In Python. (line 6) +* python convenience functions: Functions In Python. + (line 6) +* python directory: Python. (line 10) +* python exceptions: Exception Handling. (line 6) +* python finish breakpoints: Finish Breakpoints in Python. + (line 6) +* python functions: Basic Python. (line 28) +* python module: Basic Python. (line 28) +* python modules: Python modules. (line 6) +* python pagination: Basic Python. (line 6) +* python parameters: Parameters In Python. + (line 6) +* python scripting: Python. (line 6) +* python stdout: Basic Python. (line 6) +* Python, working with types: Types In Python. (line 6) +* python, working with values from inferior: Values From Inferior. + (line 6) +* 'q' packet: Packets. (line 280) +* 'Q' packet: Packets. (line 280) +* 'QAllow' packet: General Query Packets. + (line 44) +* 'qAttached' packet: General Query Packets. + (line 1069) +* 'qC' packet: General Query Packets. + (line 55) +* 'qCRC' packet: General Query Packets. + (line 65) +* 'QDisableRandomization' packet: General Query Packets. + (line 84) +* 'qfThreadInfo' packet: General Query Packets. + (line 114) +* 'qGetTIBAddr' packet: General Query Packets. + (line 171) +* 'qGetTLSAddr' packet: General Query Packets. + (line 140) +* 'QNonStop' packet: General Query Packets. + (line 247) +* 'qOffsets' packet: General Query Packets. + (line 210) +* 'qP' packet: General Query Packets. + (line 237) +* 'QPassSignals' packet: General Query Packets. + (line 267) +* 'QProgramSignals' packet: General Query Packets. + (line 295) +* 'qRcmd' packet: General Query Packets. + (line 333) +* 'qSearch memory' packet: General Query Packets. + (line 355) +* 'QStartNoAckMode' packet: General Query Packets. + (line 372) +* 'qsThreadInfo' packet: General Query Packets. + (line 114) +* 'qSupported' packet: General Query Packets. + (line 386) +* 'qSymbol' packet: General Query Packets. + (line 732) +* 'qTBuffer' packet: Tracepoint Packets. (line 388) +* 'QTBuffer size' packet: Tracepoint Packets. (line 401) +* 'QTDisable' packet: Tracepoint Packets. (line 205) +* 'QTDisconnected' packet: Tracepoint Packets. (line 224) +* 'QTDP' packet: Tracepoint Packets. (line 10) +* 'QTDPsrc' packet: Tracepoint Packets. (line 90) +* 'QTDV' packet: Tracepoint Packets. (line 121) +* 'QTEnable' packet: Tracepoint Packets. (line 200) +* 'qTfP' packet: Tracepoint Packets. (line 331) +* 'QTFrame' packet: Tracepoint Packets. (line 129) +* 'qTfSTM' packet: Tracepoint Packets. (line 348) +* 'qTfV' packet: Tracepoint Packets. (line 339) +* 'qThreadExtraInfo' packet: General Query Packets. + (line 775) +* 'QTinit' packet: Tracepoint Packets. (line 210) +* 'qTMinFTPILen' packet: Tracepoint Packets. (line 167) +* 'QTNotes' packet: Tracepoint Packets. (line 406) +* 'qTP' packet: Tracepoint Packets. (line 303) +* 'QTro' packet: Tracepoint Packets. (line 213) +* 'QTSave' packet: Tracepoint Packets. (line 382) +* 'qTsP' packet: Tracepoint Packets. (line 332) +* 'qTsSTM' packet: Tracepoint Packets. (line 348) +* 'QTStart' packet: Tracepoint Packets. (line 191) +* 'qTStatus' packet: Tracepoint Packets. (line 230) +* 'qTSTMat' packet: Tracepoint Packets. (line 376) +* 'QTStop' packet: Tracepoint Packets. (line 197) +* 'qTsV' packet: Tracepoint Packets. (line 340) +* 'qTV' packet: Tracepoint Packets. (line 314) +* query attached, remote request: General Query Packets. + (line 1069) +* quotes in commands: Completion. (line 57) +* quoting Ada internal identifiers: Additions to Ada. (line 76) +* quoting names: Symbols. (line 14) +* 'qXfer' packet: General Query Packets. + (line 812) +* 'r' packet: Packets. (line 284) +* 'R' packet: Packets. (line 289) +* range checking: Type Checking. (line 45) +* range stepping: Continuing and Stepping. + (line 209) +* ranged breakpoint: PowerPC Embedded. (line 33) +* ranges of breakpoints: Breakpoints. (line 48) +* Ravenscar Profile: Ravenscar Profile. (line 6) +* raw printing: Output Formats. (line 76) +* RDI heartbeat: ARM. (line 107) +* read special object, remote request: General Query Packets. + (line 812) +* read, file-i/o system call: read. (line 6) +* read-only sections: Files. (line 261) +* reading symbols from relocatable object files: Files. (line 132) +* reading symbols immediately: Files. (line 89) +* readline: Editing. (line 6) +* receive rights, GNU Hurd: Hurd Native. (line 84) +* recent tracepoint number: Create and Delete Tracepoints. + (line 123) +* record aggregates (Ada): Omissions from Ada. (line 44) +* record mode: Process Record and Replay. + (line 19) +* record serial communications on file: Remote Configuration. + (line 57) +* recording a session script: Bug Reporting. (line 108) +* recording inferior's execution and replaying it: Process Record and Replay. + (line 6) +* redirection: Input/Output. (line 6) +* reference card: Formatting Documentation. + (line 6) +* reference declarations: C Plus Plus Expressions. + (line 50) +* register packet format, MIPS: MIPS Register packet Format. + (line 6) +* registers: Registers. (line 6) +* regular expression: Set Breaks. (line 89) +* reloading the overlay table: Overlay Commands. (line 52) +* relocatable object files, reading symbols from: Files. (line 132) +* remote async notification debugging info: Debugging Output. + (line 116) +* remote connection without stubs: Server. (line 6) +* remote debugging: Remote Debugging. (line 6) +* remote memory comparison: Memory. (line 119) +* remote monitor prompt: MIPS Embedded. (line 105) +* remote packets, enabling and disabling: Remote Configuration. + (line 145) +* remote programs, interrupting: Connecting. (line 78) +* remote protocol debugging: Debugging Output. (line 139) +* remote protocol, binary data: Overview. (line 63) +* remote protocol, field separator: Overview. (line 55) +* remote query requests: General Query Packets. + (line 6) +* remote serial debugging summary: Debug Session. (line 6) +* remote serial debugging, overview: Remote Stub. (line 14) +* remote serial protocol: Overview. (line 14) +* remote serial stub: Stub Contents. (line 6) +* remote serial stub list: Remote Stub. (line 53) +* remote serial stub, initialization: Stub Contents. (line 10) +* remote serial stub, main routine: Stub Contents. (line 15) +* remote stub, example: Remote Stub. (line 6) +* remote stub, support routines: Bootstrapping. (line 6) +* remote target: Target Commands. (line 58) +* remote target, file transfer: File Transfer. (line 6) +* remote target, limit break- and watchpoints: Remote Configuration. + (line 72) +* remote target, limit watchpoints length: Remote Configuration. + (line 77) +* remote timeout: Remote Configuration. + (line 65) +* remove actions from a tracepoint: Tracepoint Actions. (line 21) +* rename, file-i/o system call: rename. (line 6) +* Renesas: Remote Stub. (line 62) +* repeated array elements: Print Settings. (line 307) +* repeating command sequences: Command Syntax. (line 41) +* repeating commands: Command Syntax. (line 21) +* replay log events, remote reply: Stop Reply Packets. (line 61) +* replay mode: Process Record and Replay. + (line 10) +* reporting bugs in GDB: GDB Bugs. (line 6) +* reprint the last value: Data. (line 23) +* reset SDI connection, M32R: M32R/D. (line 44) +* resources used by commands: Maintenance Commands. + (line 345) +* response time, MIPS debugging: MIPS. (line 10) +* restart: Checkpoint/Restart. (line 6) +* restore data from a file: Dump/Restore Files. (line 6) +* restrictions on Go expressions: Go. (line 35) +* result records in GDB/MI: GDB/MI Result Records. + (line 6) +* resume threads of multiple processes simultaneously: All-Stop Mode. + (line 53) +* resuming execution: Continuing and Stepping. + (line 6) +* 'retransmit-timeout', MIPS protocol: MIPS Embedded. (line 81) +* returning from a function: Returning. (line 6) +* reverse execution: Reverse Execution. (line 6) +* rewind program state: Checkpoint/Restart. (line 6) +* ROM at zero address, RDI: ARM. (line 97) +* run to main procedure: Starting. (line 79) +* run until specified location: Continuing and Stepping. + (line 116) +* running: Starting. (line 6) +* running and debugging Sparclet programs: Sparclet Execution. + (line 6) +* running programs backward: Reverse Execution. (line 6) +* running VxWorks tasks: VxWorks Attach. (line 6) +* running, on Sparclet: Sparclet. (line 28) +* 's' packet: Packets. (line 296) +* 'S' packet: Packets. (line 305) +* save breakpoints to a file for future sessions: Save Breakpoints. + (line 9) +* save command history: Command History. (line 36) +* save GDB output to a file: Logging Output. (line 6) +* save tracepoints for future sessions: save tracepoints. (line 6) +* scheduler locking mode: All-Stop Mode. (line 37) +* scope: M2 Scope. (line 6) +* scripting commands: Command Files. (line 6) +* scripting with python: Python. (line 6) +* SDS protocol: PowerPC Embedded. (line 82) +* search for a thread: Threads. (line 136) +* search path for 'libthread_db': Threads. (line 171) +* searching memory: Searching Memory. (line 6) +* searching memory, in remote debugging: General Query Packets. + (line 355) +* searching source files: Search. (line 6) +* section offsets, remote request: General Query Packets. + (line 210) +* segment descriptor tables: DJGPP Native. (line 24) +* select Ctrl-C, BREAK or BREAK-g: Remote Configuration. + (line 94) +* select trace snapshot: tfind. (line 6) +* selected frame: Stack. (line 19) +* selecting frame silently: Frames. (line 51) +* semaphores on static probe points: Static Probe Points. + (line 19) +* send command to remote monitor: Connecting. (line 105) +* send command to simulator: Embedded Processors. + (line 9) +* send interrupt-sequence on start: Remote Configuration. + (line 107) +* send PMON command: MIPS Embedded. (line 128) +* send rights, GNU Hurd: Hurd Native. (line 84) +* sending files to remote systems: File Transfer. (line 6) +* separate debug sections: MiniDebugInfo. (line 6) +* separate debugging information files: Separate Debug Files. + (line 6) +* sequence-id, for GDB remote: Overview. (line 30) +* serial connections, debugging: Debugging Output. (line 139) +* serial line, 'target remote': Connecting. (line 18) +* serial protocol, GDB remote: Overview. (line 14) +* server prefix: Server Prefix. (line 6) +* 'server', command prefix: Command History. (line 20) +* set ABI for MIPS: MIPS. (line 32) +* set breakpoints in many functions: Set Breaks. (line 89) +* set breakpoints on all functions: Set Breaks. (line 109) +* set fast tracepoint: Create and Delete Tracepoints. + (line 51) +* set inferior controlling terminal: Input/Output. (line 44) +* set static tracepoint: Create and Delete Tracepoints. + (line 76) +* set tdesc filename: Retrieving Descriptions. + (line 18) +* set tracepoint: Create and Delete Tracepoints. + (line 6) +* setting variables: Assignment. (line 6) +* setting watchpoints: Set Watchpoints. (line 6) +* SH: Remote Stub. (line 62) +* 'sh-stub.c': Remote Stub. (line 62) +* shared libraries: Files. (line 283) +* shared library events, remote reply: Stop Reply Packets. (line 56) +* shell escape: Shell Commands. (line 10) +* show all convenience functions: Convenience Funs. (line 84) +* show all user variables and functions: Convenience Vars. (line 37) +* show last commands: Command History. (line 80) +* show tdesc filename: Retrieving Descriptions. + (line 25) +* signals: Signals. (line 6) +* signals the inferior may see, remote request: General Query Packets. + (line 295) +* 'SIGQUIT' signal, dump core of GDB: Maintenance Commands. + (line 118) +* simulator, Z8000: Z8000. (line 6) +* size of remote memory accesses: Packets. (line 231) +* size of screen: Screen Size. (line 6) +* skipping over functions and files: Skipping Over Functions and Files. + (line 6) +* snapshot of a process: Checkpoint/Restart. (line 6) +* software watchpoints: Set Watchpoints. (line 31) +* source file and line of a symbol: Print Settings. (line 50) +* source line and its code address: Machine Code. (line 6) +* source path: Source Path. (line 6) +* Sparc: Remote Stub. (line 65) +* 'sparc-stub.c': Remote Stub. (line 65) +* 'sparcl-stub.c': Remote Stub. (line 68) +* Sparclet: Sparclet. (line 6) +* SparcLite: Remote Stub. (line 68) +* Special Fortran commands: Special Fortran Commands. + (line 6) +* specifying location: Specify Location. (line 6) +* SPU: SPU. (line 6) +* SSE registers (x86): Registers. (line 71) +* stack frame: Frames. (line 6) +* stack on Alpha: MIPS. (line 6) +* stack on MIPS: MIPS. (line 6) +* stack pointer register: Registers. (line 26) +* stacking targets: Active Targets. (line 6) +* standard registers: Registers. (line 26) +* start a new trace experiment: Starting and Stopping Trace Experiments. + (line 6) +* starting: Starting. (line 6) +* startup code, and backtrace: Backtrace. (line 105) +* stat, file-i/o system call: stat/fstat. (line 6) +* static members of C++ objects: Print Settings. (line 478) +* static members of Pascal objects: Print Settings. (line 489) +* static probe point, SystemTap: Static Probe Points. + (line 6) +* static tracepoints: Set Tracepoints. (line 28) +* static tracepoints, in remote protocol: General Query Packets. + (line 700) +* static tracepoints, setting: Create and Delete Tracepoints. + (line 76) +* status of trace data collection: Starting and Stopping Trace Experiments. + (line 27) +* status output in GDB/MI: GDB/MI Output Syntax. + (line 94) +* stepping: Continuing and Stepping. + (line 6) +* stepping into functions with no line info: Continuing and Stepping. + (line 91) +* stop a running trace experiment: Starting and Stopping Trace Experiments. + (line 16) +* stop on C++ exceptions: Set Catchpoints. (line 16) +* stop reply packets: Stop Reply Packets. (line 6) +* stopped threads: Thread Stops. (line 6) +* stream records in GDB/MI: GDB/MI Stream Records. + (line 6) +* string tracing, in remote protocol: General Query Packets. + (line 717) +* 'struct gdb_reader_funcs': Writing JIT Debug Info Readers. + (line 22) +* 'struct gdb_symbol_callbacks': Writing JIT Debug Info Readers. + (line 43) +* 'struct gdb_unwind_callbacks': Writing JIT Debug Info Readers. + (line 43) +* struct return convention: i386. (line 7) +* struct stat, in file-i/o protocol: struct stat. (line 6) +* struct timeval, in file-i/o protocol: struct timeval. (line 6) +* struct/union returned in registers: i386. (line 7) +* structure field name completion: Completion. (line 95) +* stub example, remote debugging: Remote Stub. (line 6) +* stupid questions: Messages/Warnings. (line 49) +* Super-H: Super-H. (line 6) +* supported GDB/MI features, list: GDB/MI Support Commands. + (line 57) +* supported packets, remote query: General Query Packets. + (line 386) +* switching threads: Threads. (line 6) +* switching threads automatically: All-Stop Mode. (line 28) +* symbol decoding style, C++: Print Settings. (line 427) +* symbol dump: Symbols. (line 339) +* symbol file functions: Debugging Output. (line 157) +* symbol from address: Symbols. (line 84) +* symbol lookup, remote request: General Query Packets. + (line 732) +* symbol names: Symbols. (line 14) +* symbol table: Files. (line 6) +* symbol table creation: Debugging Output. (line 162) +* symbol tables in python: Symbol Tables In Python. + (line 6) +* symbol tables, listing GDB's internal: Symbols. (line 357) +* symbol, source file and line: Print Settings. (line 50) +* symbols in python: Symbols In Python. (line 6) +* symbols, reading from relocatable object files: Files. (line 132) +* symbols, reading immediately: Files. (line 89) +* synchronize with remote MIPS target: MIPS Embedded. (line 96) +* 'syscall DSO': Files. (line 179) +* system calls and thread breakpoints: Interrupted System Calls. + (line 6) +* system root, alternate: Files. (line 381) +* system, file-i/o system call: system. (line 6) +* system-wide configuration scripts: System-wide Configuration Scripts. + (line 6) +* system-wide init file: System-wide configuration. + (line 6) +* 't' packet: Packets. (line 315) +* 'T' packet: Packets. (line 320) +* 'T' packet reply: Stop Reply Packets. (line 22) +* tail call frames, debugging: Tail Call Frames. (line 6) +* target architecture: Targets. (line 17) +* target byte order: Byte Order. (line 6) +* target character set: Character Sets. (line 6) +* target debugging info: Debugging Output. (line 169) +* target descriptions: Target Descriptions. + (line 6) +* target descriptions, AArch64 features: AArch64 Features. (line 6) +* target descriptions, ARM features: ARM Features. (line 6) +* target descriptions, i386 features: i386 Features. (line 6) +* target descriptions, inclusion: Target Description Format. + (line 53) +* target descriptions, M68K features: M68K Features. (line 6) +* target descriptions, MIPS features: MIPS Features. (line 6) +* target descriptions, Nios II features: Nios II Features. (line 6) +* target descriptions, PowerPC features: PowerPC Features. (line 6) +* target descriptions, predefined types: Predefined Target Types. + (line 6) +* target descriptions, S/390 features: S/390 and System z Features. + (line 6) +* target descriptions, standard features: Standard Target Features. + (line 6) +* target descriptions, System z features: S/390 and System z Features. + (line 6) +* target descriptions, TIC6x features: TIC6x Features. (line 6) +* target descriptions, TMS320C6x features: TIC6x Features. (line 6) +* target descriptions, XML format: Target Description Format. + (line 6) +* target output in GDB/MI: GDB/MI Output Syntax. + (line 110) +* 'target remote': Connecting. (line 11) +* target stack description: Maintenance Commands. + (line 259) +* target-assisted range stepping: Continuing and Stepping. + (line 209) +* task attributes (GNU Hurd): Hurd Native. (line 48) +* task breakpoints, in Ada: Ada Tasks. (line 133) +* task exception port, GNU Hurd: Hurd Native. (line 67) +* task suspend count: Hurd Native. (line 59) +* task switching with program using Ravenscar Profile: Ravenscar Profile. + (line 10) +* TCP port, 'target remote': Connecting. (line 29) +* terminal: Input/Output. (line 6) +* Text User Interface: TUI. (line 6) +* thread attributes info, remote request: General Query Packets. + (line 775) +* thread breakpoints: Thread-Specific Breakpoints. + (line 10) +* thread breakpoints and system calls: Interrupted System Calls. + (line 6) +* thread default settings, GNU Hurd: Hurd Native. (line 130) +* thread identifier (GDB): Threads. (line 57) +* thread identifier (system): Threads. (line 45) +* thread info (Solaris): Threads. (line 92) +* thread information, remote request: General Query Packets. + (line 237) +* thread list format: Thread List Format. (line 6) +* thread number: Threads. (line 57) +* thread properties, GNU Hurd: Hurd Native. (line 90) +* thread suspend count, GNU Hurd: Hurd Native. (line 109) +* THREAD-ID, in remote protocol: Packets. (line 20) +* threads and watchpoints: Set Watchpoints. (line 179) +* threads in python: Threads In Python. (line 6) +* threads of execution: Threads. (line 6) +* threads, automatic switching: All-Stop Mode. (line 28) +* threads, continuing: Thread Stops. (line 6) +* threads, stopped: Thread Stops. (line 6) +* time of command execution: Maintenance Commands. + (line 386) +* timeout for commands: Maintenance Commands. + (line 407) +* timeout for serial communications: Remote Configuration. + (line 65) +* timeout, for remote target connection: Remote Configuration. + (line 133) +* 'timeout', MIPS protocol: MIPS Embedded. (line 81) +* timestampping debugging info: Debugging Output. (line 178) +* trace experiment, status of: Starting and Stopping Trace Experiments. + (line 27) +* trace file format: Trace File Format. (line 6) +* trace files: Trace Files. (line 6) +* trace state variable value, remote request: Tracepoint Packets. + (line 314) +* trace state variables: Trace State Variables. + (line 6) +* traceback: Backtrace. (line 6) +* traceframe info format: Traceframe Info Format. + (line 6) +* tracepoint actions: Tracepoint Actions. (line 6) +* tracepoint conditions: Tracepoint Conditions. + (line 6) +* tracepoint data, display: tdump. (line 6) +* tracepoint deletion: Create and Delete Tracepoints. + (line 126) +* tracepoint number: Create and Delete Tracepoints. + (line 123) +* tracepoint packets: Tracepoint Packets. (line 6) +* tracepoint pass count: Tracepoint Passcounts. + (line 6) +* tracepoint restrictions: Tracepoint Restrictions. + (line 6) +* tracepoint status, remote request: Tracepoint Packets. (line 303) +* tracepoint variables: Tracepoint Variables. + (line 6) +* tracepoints: Tracepoints. (line 6) +* tracepoints support in 'gdbserver': Server. (line 255) +* trailing underscore, in Fortran symbols: Fortran. (line 9) +* translating between character sets: Character Sets. (line 6) +* TUI: TUI. (line 6) +* TUI commands: TUI Commands. (line 6) +* TUI configuration variables: TUI Configuration. (line 6) +* TUI key bindings: TUI Keys. (line 6) +* TUI single key mode: TUI Single Key Mode. + (line 6) +* type casting memory: Expressions. (line 41) +* type chain of a data type: Maintenance Commands. + (line 271) +* type checking: Checks. (line 24) +* type conversions in C++: C Plus Plus Expressions. + (line 26) +* type printer: Type Printing API. (line 9) +* type printing API for Python: Type Printing API. (line 6) +* types in Python: Types In Python. (line 6) +* UDP port, 'target remote': Connecting. (line 50) +* union field name completion: Completion. (line 95) +* unions in structures, printing: Print Settings. (line 367) +* unknown address, locating: Output Formats. (line 35) +* unlink, file-i/o system call: unlink. (line 6) +* unlinked object files: Files. (line 26) +* unload symbols from shared libraries: Files. (line 343) +* unmap an overlay: Overlay Commands. (line 39) +* unmapped overlays: How Overlays Work. (line 6) +* unset tdesc filename: Retrieving Descriptions. + (line 21) +* unsupported languages: Unsupported Languages. + (line 6) +* unwind stack in called functions: Calling. (line 35) +* unwind stack in called functions with unhandled exceptions: Calling. + (line 46) +* use only software watchpoints: Set Watchpoints. (line 108) +* user-defined command: Define. (line 6) +* user-defined macros: Macros. (line 59) +* user-defined variables: Convenience Vars. (line 6) +* value history: Value History. (line 6) +* values from inferior, with Python: Values From Inferior. + (line 6) +* variable name conflict: Variables. (line 36) +* variable object debugging info: Debugging Output. (line 185) +* variable objects in GDB/MI: GDB/MI Variable Objects. + (line 9) +* variable values, wrong: Variables. (line 106) +* variables, readline: Readline Init File Syntax. + (line 34) +* variables, setting: Assignment. (line 16) +* 'vAttach' packet: Packets. (line 334) +* 'vCont' packet: Packets. (line 352) +* 'vCont?' packet: Packets. (line 411) +* vector unit: Vector Unit. (line 6) +* vector, auxiliary: OS Information. (line 9) +* verbose operation: Messages/Warnings. (line 6) +* verify remote memory image: Memory. (line 119) +* 'vFile' packet: Packets. (line 421) +* 'vFlashDone' packet: Packets. (line 460) +* 'vFlashErase' packet: Packets. (line 425) +* 'vFlashWrite' packet: Packets. (line 440) +* virtual functions (C++) display: Print Settings. (line 500) +* 'vKill' packet: Packets. (line 467) +* volatile registers: Registers. (line 101) +* 'vRun' packet: Packets. (line 479) +* 'vStopped' packet: Packets. (line 494) +* VTBL display: Print Settings. (line 500) +* VxWorks: VxWorks. (line 6) +* watchdog timer: Maintenance Commands. + (line 407) +* watchpoints: Breakpoints. (line 20) +* watchpoints and threads: Set Watchpoints. (line 179) +* weak alias functions: Calling. (line 57) +* where to look for shared libraries: Files. (line 376) +* wild pointer, interpreting: Print Settings. (line 80) +* Wind River Linux system-wide configuration script: System-wide Configuration Scripts. + (line 22) +* word completion: Completion. (line 6) +* working directory: Source Path. (line 106) +* working directory (of your program): Working Directory. (line 6) +* working language: Languages. (line 13) +* write data into object, remote request: General Query Packets. + (line 1016) +* write, file-i/o system call: write. (line 6) +* writing a frame filter: Writing a Frame Filter. + (line 6) +* writing a pretty-printer: Writing a Pretty-Printer. + (line 6) +* writing convenience functions: Functions In Python. + (line 6) +* writing into corefiles: Patching. (line 6) +* writing into executables: Patching. (line 6) +* writing JIT debug info readers: Writing JIT Debug Info Readers. + (line 6) +* wrong values: Variables. (line 106) +* 'x' command, default address: Machine Code. (line 30) +* 'X' packet: Packets. (line 497) +* Xilinx MicroBlaze: MicroBlaze. (line 6) +* XInclude: Target Description Format. + (line 53) +* XMD, Xilinx Microprocessor Debugger: MicroBlaze. (line 6) +* XML parser debugging: Debugging Output. (line 191) +* yanking text: Readline Killing Commands. + (line 6) +* 'z' packet: Packets. (line 509) +* 'Z' packets: Packets. (line 509) +* 'z0' packet: Packets. (line 524) +* 'Z0' packet: Packets. (line 524) +* 'z1' packet: Packets. (line 575) +* 'Z1' packet: Packets. (line 575) +* 'z2' packet: Packets. (line 595) +* 'Z2' packet: Packets. (line 595) +* 'z3' packet: Packets. (line 608) +* 'Z3' packet: Packets. (line 608) +* 'z4' packet: Packets. (line 621) +* 'Z4' packet: Packets. (line 621) +* Z8000: Z8000. (line 6) +* Zilog Z8000 simulator: Z8000. (line 6) + + +File: gdb.info, Node: Command and Variable Index, Prev: Concept Index, Up: Top + +Command, Variable, and Function Index +************************************* + +[index] +* Menu: + +* !: Shell Commands. (line 10) +* # (a comment): Command Syntax. (line 37) +* $bpnum, convenience variable: Set Breaks. (line 6) +* $cdir, convenience variable: Source Path. (line 106) +* $cwd, convenience variable: Source Path. (line 106) +* $tpnum: Create and Delete Tracepoints. + (line 123) +* $tracepoint: Tracepoint Variables. + (line 10) +* $trace_file: Tracepoint Variables. + (line 16) +* $trace_frame: Tracepoint Variables. + (line 6) +* $trace_func: Tracepoint Variables. + (line 19) +* $trace_line: Tracepoint Variables. + (line 13) +* $_, convenience variable: Convenience Vars. (line 65) +* $_exception, convenience variable: Set Catchpoints. (line 21) +* $_exitcode, convenience variable: Convenience Vars. (line 80) +* $_exitsignal, convenience variable: Convenience Vars. (line 85) +* $_isvoid, convenience function: Convenience Funs. (line 15) +* $_memeq, convenience function: Convenience Funs. (line 65) +* $_probe_arg, convenience variable: Static Probe Points. (line 46) +* $_regex, convenience function: Convenience Funs. (line 69) +* $_sdata, collect: Tracepoint Actions. (line 78) +* $_sdata, inspect, convenience variable: Convenience Vars. (line 142) +* $_siginfo, convenience variable: Convenience Vars. (line 148) +* $_streq, convenience function: Convenience Funs. (line 74) +* $_strlen, convenience function: Convenience Funs. (line 78) +* $_thread, convenience variable: Threads. (line 110) +* $_tlb, convenience variable: Convenience Vars. (line 154) +* $__, convenience variable: Convenience Vars. (line 74) +* -ada-task-info: GDB/MI Ada Tasking Commands. + (line 9) +* -add-inferior: GDB/MI Miscellaneous Commands. + (line 288) +* -break-after: GDB/MI Breakpoint Commands. + (line 11) +* -break-commands: GDB/MI Breakpoint Commands. + (line 56) +* -break-condition: GDB/MI Breakpoint Commands. + (line 90) +* -break-delete: GDB/MI Breakpoint Commands. + (line 127) +* -break-disable: GDB/MI Breakpoint Commands. + (line 161) +* -break-enable: GDB/MI Breakpoint Commands. + (line 197) +* -break-info: GDB/MI Breakpoint Commands. + (line 232) +* -break-insert: GDB/MI Breakpoint Commands. + (line 256) +* -break-list: GDB/MI Breakpoint Commands. + (line 409) +* -break-passcount: GDB/MI Breakpoint Commands. + (line 481) +* -break-watch: GDB/MI Breakpoint Commands. + (line 493) +* -catch-assert: Ada Exception GDB/MI Catchpoint Commands. + (line 12) +* -catch-exception: Ada Exception GDB/MI Catchpoint Commands. + (line 46) +* -catch-load: Shared Library GDB/MI Catchpoint Commands. + (line 9) +* -catch-unload: Shared Library GDB/MI Catchpoint Commands. + (line 36) +* -data-disassemble: GDB/MI Data Manipulation. + (line 12) +* -data-evaluate-expression: GDB/MI Data Manipulation. + (line 174) +* -data-list-changed-registers: GDB/MI Data Manipulation. + (line 212) +* -data-list-register-names: GDB/MI Data Manipulation. + (line 248) +* -data-list-register-values: GDB/MI Data Manipulation. + (line 288) +* -data-read-memory: GDB/MI Data Manipulation. + (line 375) +* -data-read-memory-bytes: GDB/MI Data Manipulation. + (line 482) +* -data-write-memory-bytes: GDB/MI Data Manipulation. + (line 555) +* -dprintf-insert: GDB/MI Breakpoint Commands. + (line 342) +* -enable-frame-filters: GDB/MI Stack Manipulation. + (line 9) +* -enable-pretty-printing: GDB/MI Variable Objects. + (line 118) +* -enable-timings: GDB/MI Miscellaneous Commands. + (line 385) +* -environment-cd: GDB/MI Program Context. + (line 33) +* -environment-directory: GDB/MI Program Context. + (line 56) +* -environment-path: GDB/MI Program Context. + (line 100) +* -environment-pwd: GDB/MI Program Context. + (line 141) +* -exec-arguments: GDB/MI Program Context. + (line 9) +* -exec-continue: GDB/MI Program Execution. + (line 13) +* -exec-finish: GDB/MI Program Execution. + (line 53) +* -exec-interrupt: GDB/MI Program Execution. + (line 96) +* -exec-jump: GDB/MI Program Execution. + (line 146) +* -exec-next: GDB/MI Program Execution. + (line 170) +* -exec-next-instruction: GDB/MI Program Execution. + (line 201) +* -exec-return: GDB/MI Program Execution. + (line 237) +* -exec-run: GDB/MI Program Execution. + (line 280) +* -exec-step: GDB/MI Program Execution. + (line 350) +* -exec-step-instruction: GDB/MI Program Execution. + (line 392) +* -exec-until: GDB/MI Program Execution. + (line 433) +* -file-exec-and-symbols: GDB/MI File Commands. + (line 12) +* -file-exec-file: GDB/MI File Commands. + (line 40) +* -file-list-exec-source-file: GDB/MI File Commands. + (line 67) +* -file-list-exec-source-files: GDB/MI File Commands. + (line 93) +* -file-symbol-file: GDB/MI File Commands. + (line 123) +* -gdb-exit: GDB/MI Miscellaneous Commands. + (line 9) +* -gdb-set: GDB/MI Miscellaneous Commands. + (line 31) +* -gdb-show: GDB/MI Miscellaneous Commands. + (line 54) +* -gdb-version: GDB/MI Miscellaneous Commands. + (line 77) +* -inferior-tty-set: GDB/MI Miscellaneous Commands. + (line 336) +* -inferior-tty-show: GDB/MI Miscellaneous Commands. + (line 359) +* -info-ada-exceptions: GDB/MI Ada Exceptions Commands. + (line 9) +* -info-gdb-mi-command: GDB/MI Support Commands. + (line 14) +* -info-os: GDB/MI Miscellaneous Commands. + (line 216) +* -interpreter-exec: GDB/MI Miscellaneous Commands. + (line 310) +* -list-features: GDB/MI Support Commands. + (line 57) +* -list-target-features: GDB/MI Support Commands. + (line 112) +* -list-thread-groups: GDB/MI Miscellaneous Commands. + (line 111) +* -stack-info-depth: GDB/MI Stack Manipulation. + (line 50) +* -stack-info-frame: GDB/MI Stack Manipulation. + (line 24) +* -stack-list-arguments: GDB/MI Stack Manipulation. + (line 88) +* -stack-list-frames: GDB/MI Stack Manipulation. + (line 182) +* -stack-list-locals: GDB/MI Stack Manipulation. + (line 281) +* -stack-list-variables: GDB/MI Stack Manipulation. + (line 327) +* -stack-select-frame: GDB/MI Stack Manipulation. + (line 355) +* -symbol-list-lines: GDB/MI Symbol Query. (line 9) +* -target-attach: GDB/MI Target Manipulation. + (line 9) +* -target-detach: GDB/MI Target Manipulation. + (line 36) +* -target-disconnect: GDB/MI Target Manipulation. + (line 61) +* -target-download: GDB/MI Target Manipulation. + (line 85) +* -target-file-delete: GDB/MI File Transfer Commands. + (line 57) +* -target-file-get: GDB/MI File Transfer Commands. + (line 33) +* -target-file-put: GDB/MI File Transfer Commands. + (line 9) +* -target-select: GDB/MI Target Manipulation. + (line 192) +* -thread-info: GDB/MI Thread Commands. + (line 9) +* -thread-list-ids: GDB/MI Thread Commands. + (line 88) +* -thread-select: GDB/MI Thread Commands. + (line 116) +* -trace-define-variable: GDB/MI Tracepoint Commands. + (line 80) +* -trace-find: GDB/MI Tracepoint Commands. + (line 12) +* -trace-frame-collected: GDB/MI Tracepoint Commands. + (line 97) +* -trace-list-variables: GDB/MI Tracepoint Commands. + (line 204) +* -trace-save: GDB/MI Tracepoint Commands. + (line 246) +* -trace-start: GDB/MI Tracepoint Commands. + (line 263) +* -trace-status: GDB/MI Tracepoint Commands. + (line 279) +* -trace-stop: GDB/MI Tracepoint Commands. + (line 350) +* -var-assign: GDB/MI Variable Objects. + (line 492) +* -var-create: GDB/MI Variable Objects. + (line 136) +* -var-delete: GDB/MI Variable Objects. + (line 224) +* -var-evaluate-expression: GDB/MI Variable Objects. + (line 471) +* -var-info-expression: GDB/MI Variable Objects. + (line 408) +* -var-info-num-children: GDB/MI Variable Objects. + (line 273) +* -var-info-path-expression: GDB/MI Variable Objects. + (line 433) +* -var-info-type: GDB/MI Variable Objects. + (line 395) +* -var-list-children: GDB/MI Variable Objects. + (line 289) +* -var-set-format: GDB/MI Variable Objects. + (line 237) +* -var-set-frozen: GDB/MI Variable Objects. + (line 636) +* -var-set-update-range: GDB/MI Variable Objects. + (line 662) +* -var-set-visualizer: GDB/MI Variable Objects. + (line 685) +* -var-show-attributes: GDB/MI Variable Objects. + (line 457) +* -var-show-format: GDB/MI Variable Objects. + (line 260) +* -var-update: GDB/MI Variable Objects. + (line 516) +* @, referencing memory as an array: Arrays. (line 6) +* ^connected: GDB/MI Result Records. + (line 22) +* ^done: GDB/MI Result Records. + (line 9) +* ^error: GDB/MI Result Records. + (line 25) +* ^exit: GDB/MI Result Records. + (line 36) +* ^running: GDB/MI Result Records. + (line 14) +* __init__ on TypePrinter: gdb.types. (line 82) +* abort (C-g): Miscellaneous Commands. + (line 10) +* accept-line (Newline or Return): Commands For History. + (line 6) +* actions: Tracepoint Actions. (line 6) +* ada-task-info: GDB/MI Support Commands. + (line 94) +* add-auto-load-safe-path: Auto-loading safe path. + (line 50) +* add-inferior: Inferiors and Programs. + (line 60) +* add-shared-symbol-files: Files. (line 189) +* add-symbol-file: Files. (line 112) +* add-symbol-file-from-memory: Files. (line 179) +* advance LOCATION: Continuing and Stepping. + (line 179) +* alias: Aliases. (line 21) +* append: Dump/Restore Files. (line 32) +* apropos: Help. (line 62) +* Architecture.disassemble: Architectures In Python. + (line 15) +* Architecture.name: Architectures In Python. + (line 12) +* assf: Files. (line 189) +* attach: Attach. (line 6) +* attach&: Background Execution. + (line 36) +* awatch: Set Watchpoints. (line 83) +* b ('break'): Set Breaks. (line 6) +* backtrace: Backtrace. (line 11) +* backward-char (C-b): Commands For Moving. (line 15) +* backward-delete-char (Rubout): Commands For Text. (line 11) +* backward-kill-line (C-x Rubout): Commands For Killing. + (line 9) +* backward-kill-word (M-): Commands For Killing. + (line 24) +* backward-word (M-b): Commands For Moving. (line 22) +* beginning-of-history (M-<): Commands For History. + (line 19) +* beginning-of-line (C-a): Commands For Moving. (line 6) +* bell-style: Readline Init File Syntax. + (line 35) +* bind-tty-special-chars: Readline Init File Syntax. + (line 42) +* Block.end: Blocks In Python. (line 81) +* Block.function: Blocks In Python. (line 84) +* Block.global_block: Blocks In Python. (line 99) +* Block.is_global: Blocks In Python. (line 107) +* Block.is_static: Blocks In Python. (line 111) +* Block.is_valid: Blocks In Python. (line 68) +* Block.start: Blocks In Python. (line 78) +* Block.static_block: Blocks In Python. (line 103) +* Block.superblock: Blocks In Python. (line 94) +* BP_ACCESS_WATCHPOINT: Breakpoints In Python. + (line 152) +* BP_BREAKPOINT: Breakpoints In Python. + (line 140) +* BP_HARDWARE_WATCHPOINT: Breakpoints In Python. + (line 146) +* BP_READ_WATCHPOINT: Breakpoints In Python. + (line 149) +* BP_WATCHPOINT: Breakpoints In Python. + (line 143) +* break: Set Breaks. (line 6) +* break ... task TASKNO (Ada): Ada Tasks. (line 133) +* break ... thread THREADNO: Thread-Specific Breakpoints. + (line 10) +* break, and Objective-C: Method Names in Commands. + (line 9) +* break-range: PowerPC Embedded. (line 41) +* breakpoint annotation: Annotations for Running. + (line 47) +* breakpoint-notifications: GDB/MI Support Commands. + (line 91) +* Breakpoint.commands: Breakpoints In Python. + (line 177) +* Breakpoint.condition: Breakpoints In Python. + (line 172) +* Breakpoint.delete: Breakpoints In Python. + (line 81) +* Breakpoint.enabled: Breakpoints In Python. + (line 86) +* Breakpoint.expression: Breakpoints In Python. + (line 166) +* Breakpoint.hit_count: Breakpoints In Python. + (line 155) +* Breakpoint.ignore_count: Breakpoints In Python. + (line 109) +* Breakpoint.is_valid: Breakpoints In Python. + (line 73) +* Breakpoint.location: Breakpoints In Python. + (line 160) +* Breakpoint.number: Breakpoints In Python. + (line 113) +* Breakpoint.silent: Breakpoints In Python. + (line 90) +* Breakpoint.stop: Breakpoints In Python. + (line 30) +* Breakpoint.task: Breakpoints In Python. + (line 103) +* Breakpoint.temporary: Breakpoints In Python. + (line 128) +* Breakpoint.thread: Breakpoints In Python. + (line 98) +* Breakpoint.type: Breakpoints In Python. + (line 118) +* Breakpoint.visible: Breakpoints In Python. + (line 123) +* Breakpoint.__init__: Breakpoints In Python. + (line 8) +* BreakpointEvent.breakpoint: Events In Python. (line 105) +* BreakpointEvent.breakpoints: Events In Python. (line 101) +* breakpoints-invalid annotation: Invalidation. (line 14) +* bt ('backtrace'): Backtrace. (line 11) +* c ('continue'): Continuing and Stepping. + (line 15) +* c (SingleKey TUI key): TUI Single Key Mode. (line 10) +* C-L: TUI Keys. (line 65) +* C-x 1: TUI Keys. (line 19) +* C-x 2: TUI Keys. (line 26) +* C-x a: TUI Keys. (line 11) +* C-x A: TUI Keys. (line 12) +* C-x C-a: TUI Keys. (line 10) +* C-x o: TUI Keys. (line 34) +* C-x s: TUI Keys. (line 41) +* call: Calling. (line 10) +* call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) +* capitalize-word (M-c): Commands For Text. (line 49) +* catch: Set Catchpoints. (line 10) +* catch assert: Set Catchpoints. (line 87) +* catch catch: Set Catchpoints. (line 16) +* catch exception: Set Catchpoints. (line 66) +* catch exception unhandled: Set Catchpoints. (line 83) +* catch exec: Set Catchpoints. (line 90) +* catch fork: Set Catchpoints. (line 212) +* catch load: Set Catchpoints. (line 221) +* catch rethrow: Set Catchpoints. (line 16) +* catch signal: Set Catchpoints. (line 226) +* catch syscall: Set Catchpoints. (line 95) +* catch throw: Set Catchpoints. (line 16) +* catch unload: Set Catchpoints. (line 221) +* catch vfork: Set Catchpoints. (line 216) +* cd: Working Directory. (line 16) +* cdir: Source Path. (line 106) +* character-search (C-]): Miscellaneous Commands. + (line 41) +* character-search-backward (M-C-]): Miscellaneous Commands. + (line 46) +* checkpoint: Checkpoint/Restart. (line 26) +* clear: Delete Breaks. (line 21) +* clear, and Objective-C: Method Names in Commands. + (line 9) +* clear-screen (C-l): Commands For Moving. (line 26) +* clone-inferior: Inferiors and Programs. + (line 67) +* collect (tracepoints): Tracepoint Actions. (line 49) +* colon-colon, in Modula-2: M2 Scope. (line 6) +* Command.complete: Commands In Python. (line 70) +* Command.dont_repeat: Commands In Python. (line 42) +* Command.invoke: Commands In Python. (line 48) +* Command.__init__: Commands In Python. (line 10) +* commands: Break Commands. (line 11) +* commands annotation: Prompting. (line 27) +* COMMAND_BREAKPOINTS: Commands In Python. (line 142) +* COMMAND_DATA: Commands In Python. (line 113) +* COMMAND_FILES: Commands In Python. (line 124) +* COMMAND_MAINTENANCE: Commands In Python. (line 166) +* COMMAND_NONE: Commands In Python. (line 103) +* COMMAND_OBSCURE: Commands In Python. (line 160) +* COMMAND_RUNNING: Commands In Python. (line 107) +* COMMAND_STACK: Commands In Python. (line 118) +* COMMAND_STATUS: Commands In Python. (line 136) +* COMMAND_SUPPORT: Commands In Python. (line 129) +* COMMAND_TRACEPOINTS: Commands In Python. (line 148) +* COMMAND_USER: Commands In Python. (line 154) +* comment-begin: Readline Init File Syntax. + (line 47) +* compare-sections: Memory. (line 125) +* complete: Help. (line 77) +* complete (): Commands For Completion. + (line 6) +* COMPLETE_COMMAND: Commands In Python. (line 187) +* COMPLETE_EXPRESSION: Commands In Python. (line 195) +* COMPLETE_FILENAME: Commands In Python. (line 180) +* COMPLETE_LOCATION: Commands In Python. (line 183) +* COMPLETE_NONE: Commands In Python. (line 177) +* COMPLETE_SYMBOL: Commands In Python. (line 191) +* completion-display-width: Readline Init File Syntax. + (line 52) +* completion-ignore-case: Readline Init File Syntax. + (line 59) +* completion-map-case: Readline Init File Syntax. + (line 64) +* completion-prefix-display-length: Readline Init File Syntax. + (line 70) +* completion-query-items: Readline Init File Syntax. + (line 77) +* condition: Conditions. (line 58) +* continue: Continuing and Stepping. + (line 15) +* continue&: Background Execution. + (line 51) +* convert-meta: Readline Init File Syntax. + (line 87) +* copy-backward-word (): Commands For Killing. + (line 49) +* copy-forward-word (): Commands For Killing. + (line 54) +* copy-region-as-kill (): Commands For Killing. + (line 45) +* core-file: Files. (line 96) +* ctf: Trace Files. (line 28) +* Ctrl-o (operate-and-get-next): Command Syntax. (line 41) +* cwd: Source Path. (line 106) +* d ('delete'): Delete Breaks. (line 41) +* d (SingleKey TUI key): TUI Single Key Mode. (line 13) +* data-read-memory-bytes: GDB/MI Support Commands. + (line 88) +* debug_chaos: M32R/D. (line 50) +* define: Define. (line 37) +* delete: Delete Breaks. (line 41) +* delete checkpoint CHECKPOINT-ID: Checkpoint/Restart. (line 53) +* delete display: Auto Display. (line 45) +* delete mem: Memory Region Attributes. + (line 34) +* delete tracepoint: Create and Delete Tracepoints. + (line 126) +* delete tvariable: Trace State Variables. + (line 42) +* delete-char (C-d): Commands For Text. (line 6) +* delete-char-or-list (): Commands For Completion. + (line 39) +* delete-horizontal-space (): Commands For Killing. + (line 37) +* detach: Attach. (line 36) +* detach (remote): Connecting. (line 91) +* detach inferiors INFNO...: Inferiors and Programs. + (line 96) +* digit-argument ('M-0', 'M-1', ... 'M--'): Numeric Arguments. + (line 6) +* dir: Source Path. (line 38) +* directory: Source Path. (line 38) +* dis ('disable'): Disabling. (line 37) +* disable: Disabling. (line 37) +* disable display: Auto Display. (line 56) +* disable frame-filter: Frame Filter Management. + (line 16) +* disable mem: Memory Region Attributes. + (line 38) +* disable pretty-printer: Pretty-Printer Commands. + (line 20) +* disable tracepoint: Enable and Disable Tracepoints. + (line 9) +* disable type-printer: Symbols. (line 245) +* disable-completion: Readline Init File Syntax. + (line 93) +* disassemble: Machine Code. (line 36) +* disconnect: Connecting. (line 98) +* display: Auto Display. (line 23) +* dll-symbols: Cygwin Native. (line 38) +* do ('down'): Selection. (line 40) +* do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. + (line 14) +* document: Define. (line 49) +* dont-repeat: Define. (line 61) +* down: Selection. (line 40) +* Down: TUI Keys. (line 56) +* down-silently: Selection. (line 64) +* downcase-word (M-l): Commands For Text. (line 45) +* dprintf: Dynamic Printf. (line 26) +* dprintf-style agent: Dynamic Printf. (line 46) +* dprintf-style call: Dynamic Printf. (line 42) +* dprintf-style gdb: Dynamic Printf. (line 39) +* dump: Dump/Restore Files. (line 13) +* dump-functions (): Miscellaneous Commands. + (line 69) +* dump-macros (): Miscellaneous Commands. + (line 81) +* dump-variables (): Miscellaneous Commands. + (line 75) +* e ('edit'): Edit. (line 6) +* echo: Output. (line 12) +* edit: Edit. (line 6) +* editing-mode: Readline Init File Syntax. + (line 98) +* else: Command Files. (line 74) +* emacs-editing-mode (C-e): Miscellaneous Commands. + (line 87) +* enable: Disabling. (line 44) +* enable display: Auto Display. (line 65) +* enable frame-filter: Frame Filter Management. + (line 26) +* enable mem: Memory Region Attributes. + (line 42) +* enable pretty-printer: Pretty-Printer Commands. + (line 25) +* enable tracepoint: Enable and Disable Tracepoints. + (line 19) +* enable type-printer: Symbols. (line 245) +* enable-keypad: Readline Init File Syntax. + (line 109) +* enabled of type_printer: Type Printing API. (line 13) +* end (breakpoint commands): Break Commands. (line 11) +* end (if/else/while commands): Command Files. (line 103) +* end (user-defined commands): Define. (line 49) +* end-kbd-macro (C-x )): Keyboard Macros. (line 9) +* end-of-history (M->): Commands For History. + (line 22) +* end-of-line (C-e): Commands For Moving. (line 9) +* error annotation: Errors. (line 10) +* error-begin annotation: Errors. (line 22) +* eval: Output. (line 117) +* EventRegistry.connect: Events In Python. (line 19) +* EventRegistry.disconnect: Events In Python. (line 23) +* exceptionHandler: Bootstrapping. (line 38) +* exchange-point-and-mark (C-x C-x): Miscellaneous Commands. + (line 36) +* exec-file: Files. (line 39) +* exec-run-start-option: GDB/MI Support Commands. + (line 105) +* exited annotation: Annotations for Running. + (line 18) +* ExitedEvent: Events In Python. (line 72) +* ExitedEvent.exit_code: Events In Python. (line 67) +* expand-tilde: Readline Init File Syntax. + (line 120) +* explore: Data. (line 36) +* f ('frame'): Selection. (line 11) +* f (SingleKey TUI key): TUI Single Key Mode. (line 16) +* fg (resume foreground execution): Continuing and Stepping. + (line 15) +* file: Files. (line 16) +* fin ('finish'): Continuing and Stepping. + (line 108) +* find: Searching Memory. (line 9) +* finish: Continuing and Stepping. + (line 108) +* finish&: Background Execution. + (line 54) +* FinishBreakpoint.out_of_scope: Finish Breakpoints in Python. + (line 21) +* FinishBreakpoint.return_value: Finish Breakpoints in Python. + (line 38) +* FinishBreakpoint.__init__: Finish Breakpoints in Python. + (line 14) +* flushregs: Maintenance Commands. + (line 230) +* flush_i_cache: Bootstrapping. (line 60) +* fo ('forward-search'): Search. (line 9) +* focus: TUI Commands. (line 40) +* forward-backward-delete-char (): Commands For Text. (line 15) +* forward-char (C-f): Commands For Moving. (line 12) +* forward-search: Search. (line 9) +* forward-search-history (C-s): Commands For History. + (line 30) +* forward-word (M-f): Commands For Moving. (line 18) +* frame, command: Frames. (line 45) +* frame, selecting: Selection. (line 11) +* Frame.architecture: Frames In Python. (line 46) +* Frame.block: Frames In Python. (line 128) +* Frame.find_sal: Frames In Python. (line 141) +* Frame.function: Frames In Python. (line 131) +* Frame.is_valid: Frames In Python. (line 36) +* Frame.name: Frames In Python. (line 42) +* Frame.newer: Frames In Python. (line 138) +* Frame.older: Frames In Python. (line 135) +* Frame.pc: Frames In Python. (line 125) +* Frame.read_var: Frames In Python. (line 145) +* Frame.select: Frames In Python. (line 153) +* Frame.type: Frames In Python. (line 50) +* Frame.unwind_stop_reason: Frames In Python. (line 77) +* FrameDecorator.address: Frame Decorator API. (line 56) +* FrameDecorator.elided: Frame Decorator API. (line 25) +* FrameDecorator.filename: Frame Decorator API. (line 66) +* FrameDecorator.frame_args: Frame Decorator API. (line 87) +* FrameDecorator.frame_locals: Frame Decorator API. (line 139) +* FrameDecorator.function: Frame Decorator API. (line 45) +* FrameDecorator.inferior_frame: Frame Decorator API. (line 172) +* FrameDecorator.line: Frame Decorator API. (line 77) +* FrameFilter.enabled: Frame Filter API. (line 122) +* FrameFilter.filter: Frame Filter API. (line 75) +* FrameFilter.name: Frame Filter API. (line 115) +* FrameFilter.priority: Frame Filter API. (line 131) +* frames-invalid annotation: Invalidation. (line 9) +* frozen-varobjs: GDB/MI Support Commands. + (line 75) +* ftrace: Create and Delete Tracepoints. + (line 51) +* Function: Functions In Python. (line 6) +* Function.invoke: Functions In Python. (line 19) +* Function.__init__: Functions In Python. (line 10) +* gcore: Core File Generation. + (line 17) +* gdb.Block: Blocks In Python. (line 6) +* gdb.block_for_pc: Blocks In Python. (line 61) +* gdb.block_for_pc <1>: Blocks In Python. (line 61) +* gdb.BP_ACCESS_WATCHPOINT: Breakpoints In Python. + (line 152) +* gdb.BP_BREAKPOINT: Breakpoints In Python. + (line 140) +* gdb.BP_HARDWARE_WATCHPOINT: Breakpoints In Python. + (line 146) +* gdb.BP_READ_WATCHPOINT: Breakpoints In Python. + (line 149) +* gdb.BP_WATCHPOINT: Breakpoints In Python. + (line 143) +* gdb.Breakpoint: Breakpoints In Python. + (line 6) +* gdb.breakpoints: Basic Python. (line 53) +* gdb.breakpoints <1>: Basic Python. (line 53) +* gdb.COMMAND_BREAKPOINTS: Commands In Python. (line 142) +* gdb.COMMAND_DATA: Commands In Python. (line 113) +* gdb.COMMAND_FILES: Commands In Python. (line 124) +* gdb.COMMAND_MAINTENANCE: Commands In Python. (line 166) +* gdb.COMMAND_NONE: Commands In Python. (line 103) +* gdb.COMMAND_OBSCURE: Commands In Python. (line 160) +* gdb.COMMAND_RUNNING: Commands In Python. (line 107) +* gdb.COMMAND_STACK: Commands In Python. (line 118) +* gdb.COMMAND_STATUS: Commands In Python. (line 136) +* gdb.COMMAND_SUPPORT: Commands In Python. (line 129) +* gdb.COMMAND_TRACEPOINTS: Commands In Python. (line 148) +* gdb.COMMAND_USER: Commands In Python. (line 154) +* gdb.COMPLETE_COMMAND: Commands In Python. (line 187) +* gdb.COMPLETE_EXPRESSION: Commands In Python. (line 195) +* gdb.COMPLETE_FILENAME: Commands In Python. (line 180) +* gdb.COMPLETE_LOCATION: Commands In Python. (line 183) +* gdb.COMPLETE_NONE: Commands In Python. (line 177) +* gdb.COMPLETE_SYMBOL: Commands In Python. (line 191) +* gdb.current_objfile: Objfiles In Python. (line 15) +* gdb.current_objfile <1>: Objfiles In Python. (line 15) +* gdb.current_progspace: Progspaces In Python. + (line 14) +* gdb.current_progspace <1>: Progspaces In Python. + (line 14) +* gdb.decode_line: Basic Python. (line 184) +* gdb.decode_line <1>: Basic Python. (line 184) +* gdb.default_visualizer: Pretty Printing API. (line 85) +* gdb.default_visualizer <1>: Pretty Printing API. (line 85) +* gdb.error: Exception Handling. (line 22) +* gdb.execute: Basic Python. (line 36) +* gdb.execute <1>: Basic Python. (line 36) +* gdb.find_pc_line: Basic Python. (line 91) +* gdb.find_pc_line <1>: Basic Python. (line 91) +* gdb.FinishBreakpoint: Finish Breakpoints in Python. + (line 6) +* gdb.flush: Basic Python. (line 150) +* gdb.flush <1>: Basic Python. (line 150) +* gdb.frame_stop_reason_string: Frames In Python. (line 29) +* gdb.Function: Functions In Python. (line 6) +* gdb.GdbError: Exception Handling. (line 42) +* gdb.history: Basic Python. (line 68) +* gdb.history <1>: Basic Python. (line 68) +* gdb.Inferior: Inferiors In Python. (line 6) +* gdb.inferiors: Inferiors In Python. (line 14) +* gdb.InferiorThread: Threads In Python. (line 6) +* gdb.LazyString: Lazy Strings In Python. + (line 6) +* gdb.LineTable: Line Tables In Python. + (line 6) +* gdb.lookup_global_symbol: Symbols In Python. (line 33) +* gdb.lookup_global_symbol <1>: Symbols In Python. (line 33) +* gdb.lookup_symbol: Symbols In Python. (line 13) +* gdb.lookup_symbol <1>: Symbols In Python. (line 13) +* gdb.lookup_type: Types In Python. (line 11) +* gdb.lookup_type <1>: Types In Python. (line 11) +* gdb.MemoryError: Exception Handling. (line 30) +* gdb.newest_frame: Frames In Python. (line 26) +* gdb.newest_frame <1>: Frames In Python. (line 26) +* gdb.Objfile: Objfiles In Python. (line 6) +* gdb.objfiles: Objfiles In Python. (line 21) +* gdb.objfiles <1>: Objfiles In Python. (line 21) +* gdb.Parameter: Parameters In Python. + (line 6) +* gdb.parameter: Basic Python. (line 57) +* gdb.parameter <1>: Basic Python. (line 57) +* gdb.PARAM_AUTO_BOOLEAN: Parameters In Python. + (line 93) +* gdb.PARAM_BOOLEAN: Parameters In Python. + (line 89) +* gdb.PARAM_ENUM: Parameters In Python. + (line 127) +* gdb.PARAM_FILENAME: Parameters In Python. + (line 119) +* gdb.PARAM_INTEGER: Parameters In Python. + (line 102) +* gdb.PARAM_OPTIONAL_FILENAME: Parameters In Python. + (line 116) +* gdb.PARAM_STRING: Parameters In Python. + (line 106) +* gdb.PARAM_STRING_NOESCAPE: Parameters In Python. + (line 112) +* gdb.PARAM_UINTEGER: Parameters In Python. + (line 98) +* gdb.PARAM_ZINTEGER: Parameters In Python. + (line 123) +* gdb.parse_and_eval: Basic Python. (line 80) +* gdb.parse_and_eval <1>: Basic Python. (line 80) +* gdb.post_event: Basic Python. (line 98) +* gdb.post_event <1>: Basic Python. (line 98) +* gdb.Progspace: Progspaces In Python. + (line 6) +* gdb.progspaces: Progspaces In Python. + (line 18) +* gdb.progspaces <1>: Progspaces In Python. + (line 18) +* gdb.prompt_hook: Basic Python. (line 196) +* gdb.PYTHONDIR: Basic Python. (line 33) +* gdb.PYTHONDIR <1>: Basic Python. (line 33) +* gdb.search_memory: Inferiors In Python. (line 61) +* gdb.selected_frame: Frames In Python. (line 22) +* gdb.selected_frame <1>: Frames In Python. (line 22) +* gdb.selected_inferior: Inferiors In Python. (line 17) +* gdb.selected_thread: Threads In Python. (line 13) +* gdb.selected_thread <1>: Threads In Python. (line 13) +* gdb.solib_name: Basic Python. (line 180) +* gdb.solib_name <1>: Basic Python. (line 180) +* gdb.STDERR: Basic Python. (line 140) +* gdb.STDERR <1>: Basic Python. (line 160) +* gdb.STDLOG: Basic Python. (line 143) +* gdb.STDLOG <1>: Basic Python. (line 163) +* gdb.STDOUT: Basic Python. (line 137) +* gdb.STDOUT <1>: Basic Python. (line 157) +* gdb.string_to_argv: Commands In Python. (line 61) +* gdb.Symbol: Symbols In Python. (line 6) +* gdb.SYMBOL_FUNCTIONS_DOMAIN: Symbols In Python. (line 128) +* gdb.SYMBOL_LABEL_DOMAIN: Symbols In Python. (line 123) +* gdb.SYMBOL_LOC_ARG: Symbols In Python. (line 145) +* gdb.SYMBOL_LOC_BLOCK: Symbols In Python. (line 161) +* gdb.SYMBOL_LOC_COMPUTED: Symbols In Python. (line 171) +* gdb.SYMBOL_LOC_CONST: Symbols In Python. (line 139) +* gdb.SYMBOL_LOC_CONST_BYTES: Symbols In Python. (line 163) +* gdb.SYMBOL_LOC_LOCAL: Symbols In Python. (line 156) +* gdb.SYMBOL_LOC_OPTIMIZED_OUT: Symbols In Python. (line 169) +* gdb.SYMBOL_LOC_REF_ARG: Symbols In Python. (line 148) +* gdb.SYMBOL_LOC_REGISTER: Symbols In Python. (line 143) +* gdb.SYMBOL_LOC_REGPARM_ADDR: Symbols In Python. (line 152) +* gdb.SYMBOL_LOC_STATIC: Symbols In Python. (line 141) +* gdb.SYMBOL_LOC_TYPEDEF: Symbols In Python. (line 158) +* gdb.SYMBOL_LOC_UNDEF: Symbols In Python. (line 137) +* gdb.SYMBOL_LOC_UNRESOLVED: Symbols In Python. (line 165) +* gdb.SYMBOL_STRUCT_DOMAIN: Symbols In Python. (line 121) +* gdb.SYMBOL_TYPES_DOMAIN: Symbols In Python. (line 130) +* gdb.SYMBOL_UNDEF_DOMAIN: Symbols In Python. (line 115) +* gdb.SYMBOL_VARIABLES_DOMAIN: Symbols In Python. (line 125) +* gdb.SYMBOL_VAR_DOMAIN: Symbols In Python. (line 118) +* gdb.Symtab: Symbol Tables In Python. + (line 6) +* gdb.Symtab_and_line: Symbol Tables In Python. + (line 6) +* gdb.target_charset: Basic Python. (line 169) +* gdb.target_charset <1>: Basic Python. (line 169) +* gdb.target_wide_charset: Basic Python. (line 174) +* gdb.target_wide_charset <1>: Basic Python. (line 174) +* gdb.Type: Types In Python. (line 6) +* gdb.TYPE_CODE_ARRAY: Types In Python. (line 187) +* gdb.TYPE_CODE_BITSTRING: Types In Python. (line 225) +* gdb.TYPE_CODE_BOOL: Types In Python. (line 246) +* gdb.TYPE_CODE_CHAR: Types In Python. (line 243) +* gdb.TYPE_CODE_COMPLEX: Types In Python. (line 249) +* gdb.TYPE_CODE_DECFLOAT: Types In Python. (line 258) +* gdb.TYPE_CODE_ENUM: Types In Python. (line 196) +* gdb.TYPE_CODE_ERROR: Types In Python. (line 228) +* gdb.TYPE_CODE_FLAGS: Types In Python. (line 199) +* gdb.TYPE_CODE_FLT: Types In Python. (line 208) +* gdb.TYPE_CODE_FUNC: Types In Python. (line 202) +* gdb.TYPE_CODE_INT: Types In Python. (line 205) +* gdb.TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 261) +* gdb.TYPE_CODE_MEMBERPTR: Types In Python. (line 237) +* gdb.TYPE_CODE_METHOD: Types In Python. (line 231) +* gdb.TYPE_CODE_METHODPTR: Types In Python. (line 234) +* gdb.TYPE_CODE_NAMESPACE: Types In Python. (line 255) +* gdb.TYPE_CODE_PTR: Types In Python. (line 184) +* gdb.TYPE_CODE_RANGE: Types In Python. (line 217) +* gdb.TYPE_CODE_REF: Types In Python. (line 240) +* gdb.TYPE_CODE_SET: Types In Python. (line 214) +* gdb.TYPE_CODE_STRING: Types In Python. (line 220) +* gdb.TYPE_CODE_STRUCT: Types In Python. (line 190) +* gdb.TYPE_CODE_TYPEDEF: Types In Python. (line 252) +* gdb.TYPE_CODE_UNION: Types In Python. (line 193) +* gdb.TYPE_CODE_VOID: Types In Python. (line 211) +* gdb.WP_ACCESS: Breakpoints In Python. + (line 70) +* gdb.WP_READ: Breakpoints In Python. + (line 64) +* gdb.WP_WRITE: Breakpoints In Python. + (line 67) +* gdb.write: Basic Python. (line 132) +* gdb.write <1>: Basic Python. (line 132) +* gdbserver: Server. (line 6) +* gdb_init_reader: Writing JIT Debug Info Readers. + (line 20) +* generate-core-file: Core File Generation. + (line 17) +* getDebugChar: Bootstrapping. (line 14) +* gnu_debuglink_crc32: Separate Debug Files. + (line 160) +* h ('help'): Help. (line 9) +* handle: Signals. (line 49) +* handle_exception: Stub Contents. (line 15) +* hbreak: Set Breaks. (line 60) +* help: Help. (line 6) +* help function: Convenience Funs. (line 84) +* help target: Target Commands. (line 19) +* help user-defined: Define. (line 66) +* history-preserve-point: Readline Init File Syntax. + (line 124) +* history-search-backward (): Commands For History. + (line 50) +* history-search-forward (): Commands For History. + (line 45) +* history-size: Readline Init File Syntax. + (line 130) +* hook: Hooks. (line 6) +* hookpost: Hooks. (line 11) +* horizontal-scroll-mode: Readline Init File Syntax. + (line 135) +* i ('info'): Help. (line 100) +* if: Command Files. (line 74) +* ignore: Conditions. (line 90) +* INCLUDE_RDB: VxWorks. (line 32) +* inferior INFNO: Inferiors and Programs. + (line 48) +* Inferior.is_valid: Inferiors In Python. (line 35) +* Inferior.num: Inferiors In Python. (line 22) +* Inferior.pid: Inferiors In Python. (line 25) +* Inferior.read_memory: Inferiors In Python. (line 47) +* Inferior.read_memory <1>: Inferiors In Python. (line 47) +* Inferior.search_memory: Inferiors In Python. (line 61) +* Inferior.threads: Inferiors In Python. (line 42) +* Inferior.was_attached: Inferiors In Python. (line 29) +* Inferior.write_memory: Inferiors In Python. (line 54) +* Inferior.write_memory <1>: Inferiors In Python. (line 54) +* InferiorThread.is_exited: Threads In Python. (line 59) +* InferiorThread.is_running: Threads In Python. (line 56) +* InferiorThread.is_stopped: Threads In Python. (line 53) +* InferiorThread.is_valid: Threads In Python. (line 42) +* InferiorThread.name: Threads In Python. (line 19) +* InferiorThread.num: Threads In Python. (line 29) +* InferiorThread.ptid: Threads In Python. (line 32) +* InferiorThread.switch: Threads In Python. (line 49) +* info: Help. (line 100) +* info address: Symbols. (line 74) +* info all-registers: Registers. (line 15) +* info args: Frame Info. (line 44) +* info auto-load: Auto-loading. (line 60) +* info auto-load gdb-scripts: Auto-loading sequences. + (line 21) +* info auto-load libthread-db: libthread_db.so.1 file. + (line 29) +* info auto-load local-gdbinit: Init File in the Current Directory. + (line 22) +* info auto-load python-scripts: Python Auto-loading. (line 23) +* info auxv: OS Information. (line 20) +* info breakpoints: Set Breaks. (line 125) +* info checkpoints: Checkpoint/Restart. (line 31) +* info classes: Symbols. (line 309) +* info common: Special Fortran Commands. + (line 9) +* info copying: Help. (line 138) +* info dcache: Caching Target Data. (line 46) +* info display: Auto Display. (line 78) +* info dll: Cygwin Native. (line 35) +* info dos: DJGPP Native. (line 15) +* info exceptions: Ada Exceptions. (line 8) +* info extensions: Show. (line 34) +* info f ('info frame'): Frame Info. (line 17) +* info files: Files. (line 207) +* info float: Floating Point Hardware. + (line 9) +* info frame: Frame Info. (line 17) +* info frame, show the source language: Show. (line 15) +* info frame-filter: Frame Filter Management. + (line 12) +* info functions: Symbols. (line 289) +* info handle: Signals. (line 33) +* info inferiors: Inferiors and Programs. + (line 25) +* info io_registers, AVR: AVR. (line 10) +* info line: Machine Code. (line 14) +* info line, and Objective-C: Method Names in Commands. + (line 9) +* info locals: Frame Info. (line 48) +* info macro: Macros. (line 47) +* info macros: Macros. (line 54) +* info mem: Memory Region Attributes. + (line 45) +* info meminfo: SVR4 Process Information. + (line 93) +* info os: OS Information. (line 37) +* info os files: OS Information. (line 69) +* info os modules: OS Information. (line 111) +* info os msg: OS Information. (line 100) +* info os processes: OS Information. (line 43) +* info os procgroups: OS Information. (line 52) +* info os semaphores: OS Information. (line 92) +* info os shm: OS Information. (line 82) +* info os sockets: OS Information. (line 75) +* info os threads: OS Information. (line 62) +* info pidlist: SVR4 Process Information. + (line 89) +* info pretty-printer: Pretty-Printer Commands. + (line 6) +* info probes: Static Probe Points. (line 30) +* info proc: SVR4 Process Information. + (line 19) +* info program: Stopping. (line 18) +* info record: Process Record and Replay. + (line 171) +* info registers: Registers. (line 11) +* info scope: Symbols. (line 249) +* info selectors: Symbols. (line 315) +* info serial: DJGPP Native. (line 139) +* info set: Help. (line 121) +* info share: Files. (line 328) +* info sharedlibrary: Files. (line 328) +* info signals: Signals. (line 33) +* info skip: Skipping Over Functions and Files. + (line 56) +* info source: Symbols. (line 270) +* info source, show the source language: Show. (line 21) +* info sources: Symbols. (line 283) +* info spu: SPU. (line 10) +* info stack: Backtrace. (line 46) +* info static-tracepoint-markers: Listing Static Tracepoint Markers. + (line 6) +* info symbol: Symbols. (line 84) +* info target: Files. (line 207) +* info task TASKNO: Ada Tasks. (line 87) +* info tasks: Ada Tasks. (line 9) +* info terminal: Input/Output. (line 12) +* info threads: Threads. (line 60) +* info tp [N...]: Listing Tracepoints. (line 6) +* info tracepoints [N...]: Listing Tracepoints. (line 6) +* info tvariables: Trace State Variables. + (line 37) +* info type-printers: Symbols. (line 237) +* info types: Symbols. (line 223) +* info variables: Symbols. (line 300) +* info vector: Vector Unit. (line 9) +* info w32: Cygwin Native. (line 19) +* info warranty: Help. (line 142) +* info watchpoints [N...]: Set Watchpoints. (line 87) +* info win: TUI Commands. (line 18) +* info-gdb-mi-command: GDB/MI Support Commands. + (line 99) +* init-if-undefined: Convenience Vars. (line 42) +* input-meta: Readline Init File Syntax. + (line 142) +* insert-comment (M-#): Miscellaneous Commands. + (line 60) +* insert-completions (M-*): Commands For Completion. + (line 18) +* inspect: Data. (line 6) +* instantiate on type_printer: Type Printing API. (line 22) +* interpreter-exec: Interpreters. (line 42) +* interrupt: Background Execution. + (line 70) +* isearch-terminators: Readline Init File Syntax. + (line 149) +* j ('jump'): Jumping. (line 10) +* jit-reader-load: Using JIT Debug Info Readers. + (line 6) +* jit-reader-unload: Using JIT Debug Info Readers. + (line 6) +* jump: Jumping. (line 10) +* jump, and Objective-C: Method Names in Commands. + (line 9) +* KeyboardInterrupt: Exception Handling. (line 34) +* keymap: Readline Init File Syntax. + (line 156) +* kill: Kill Process. (line 6) +* kill inferiors INFNO...: Inferiors and Programs. + (line 102) +* kill-line (C-k): Commands For Killing. + (line 6) +* kill-region (): Commands For Killing. + (line 41) +* kill-whole-line (): Commands For Killing. + (line 15) +* kill-word (M-d): Commands For Killing. + (line 19) +* kvm: BSD libkvm Interface. + (line 24) +* l ('list'): List. (line 6) +* language-option: GDB/MI Support Commands. + (line 96) +* layout: TUI Commands. (line 21) +* LazyString.address: Lazy Strings In Python. + (line 26) +* LazyString.encoding: Lazy Strings In Python. + (line 36) +* LazyString.length: Lazy Strings In Python. + (line 30) +* LazyString.type: Lazy Strings In Python. + (line 43) +* LazyString.value: Lazy Strings In Python. + (line 20) +* Left: TUI Keys. (line 59) +* LineTable.has_line: Line Tables In Python. + (line 57) +* LineTable.line: Line Tables In Python. + (line 51) +* LineTable.source_lines: Line Tables In Python. + (line 62) +* LineTableEntry.line: Line Tables In Python. + (line 16) +* LineTableEntry.pc: Line Tables In Python. + (line 21) +* list: List. (line 6) +* list, and Objective-C: Method Names in Commands. + (line 9) +* load FILENAME: Target Commands. (line 108) +* loop_break: Command Files. (line 93) +* loop_continue: Command Files. (line 97) +* macro define: Macros. (line 59) +* macro exp1: Macros. (line 36) +* macro expand: Macros. (line 29) +* macro list: Macros. (line 80) +* macro undef: Macros. (line 74) +* maint agent: Maintenance Commands. + (line 11) +* maint agent-eval: Maintenance Commands. + (line 11) +* maint agent-printf: Maintenance Commands. + (line 26) +* maint check-psymtabs: Maintenance Commands. + (line 88) +* maint check-symtabs: Maintenance Commands. + (line 93) +* maint cplus first_component: Maintenance Commands. + (line 100) +* maint cplus namespace: Maintenance Commands. + (line 103) +* maint demangle: Maintenance Commands. + (line 106) +* maint deprecate: Maintenance Commands. + (line 109) +* maint dump-me: Maintenance Commands. + (line 117) +* maint expand-symtabs: Maintenance Commands. + (line 96) +* maint info bfds: Maintenance Commands. + (line 62) +* maint info breakpoints: Maintenance Commands. + (line 32) +* maint info program-spaces: Inferiors and Programs. + (line 139) +* maint info psymtabs: Symbols. (line 357) +* maint info sections: Files. (line 216) +* maint info sol-threads: Threads. (line 92) +* maint info symtabs: Symbols. (line 357) +* maint internal-error: Maintenance Commands. + (line 122) +* maint internal-warning: Maintenance Commands. + (line 122) +* maint packet: Maintenance Commands. + (line 162) +* maint print architecture: Maintenance Commands. + (line 168) +* maint print c-tdesc: Maintenance Commands. + (line 172) +* maint print cooked-registers: Maintenance Commands. + (line 195) +* maint print dummy-frames: Maintenance Commands. + (line 177) +* maint print msymbols: Symbols. (line 339) +* maint print objfiles: Maintenance Commands. + (line 233) +* maint print psymbols: Symbols. (line 339) +* maint print raw-registers: Maintenance Commands. + (line 195) +* maint print reggroups: Maintenance Commands. + (line 214) +* maint print register-groups: Maintenance Commands. + (line 195) +* maint print registers: Maintenance Commands. + (line 195) +* maint print remote-registers: Maintenance Commands. + (line 195) +* maint print section-scripts: Maintenance Commands. + (line 239) +* maint print statistics: Maintenance Commands. + (line 246) +* maint print symbols: Symbols. (line 339) +* maint print target-stack: Maintenance Commands. + (line 259) +* maint print type: Maintenance Commands. + (line 271) +* maint print unwind, HPPA: HPPA. (line 17) +* maint set dwarf2 always-disassemble: Maintenance Commands. + (line 278) +* maint set dwarf2 max-cache-age: Maintenance Commands. + (line 299) +* maint set internal-error: Maintenance Commands. + (line 143) +* maint set internal-warning: Maintenance Commands. + (line 143) +* maint set per-command: Maintenance Commands. + (line 343) +* maint set profile: Maintenance Commands. + (line 313) +* maint set show-all-tib: Maintenance Commands. + (line 337) +* maint set show-debug-regs: Maintenance Commands. + (line 329) +* maint show dwarf2 always-disassemble: Maintenance Commands. + (line 278) +* maint show dwarf2 max-cache-age: Maintenance Commands. + (line 299) +* maint show internal-error: Maintenance Commands. + (line 143) +* maint show internal-warning: Maintenance Commands. + (line 143) +* maint show per-command: Maintenance Commands. + (line 343) +* maint show profile: Maintenance Commands. + (line 313) +* maint show show-all-tib: Maintenance Commands. + (line 337) +* maint show show-debug-regs: Maintenance Commands. + (line 329) +* maint space: Maintenance Commands. + (line 382) +* maint time: Maintenance Commands. + (line 386) +* maint translate-address: Maintenance Commands. + (line 390) +* maint undeprecate: Maintenance Commands. + (line 109) +* make: Shell Commands. (line 21) +* mark-modified-lines: Readline Init File Syntax. + (line 169) +* mark-symlinked-directories: Readline Init File Syntax. + (line 174) +* match-hidden-files: Readline Init File Syntax. + (line 179) +* may-insert-breakpoints: Observer Mode. (line 50) +* may-insert-fast-tracepoints: Observer Mode. (line 69) +* may-insert-tracepoints: Observer Mode. (line 59) +* may-interrupt: Observer Mode. (line 79) +* may-write-memory: Observer Mode. (line 41) +* may-write-registers: Observer Mode. (line 32) +* mem: Memory Region Attributes. + (line 22) +* memset: Bootstrapping. (line 70) +* menu-complete (): Commands For Completion. + (line 22) +* menu-complete-backward (): Commands For Completion. + (line 34) +* menu-complete-display-prefix: Readline Init File Syntax. + (line 186) +* meta-flag: Readline Init File Syntax. + (line 142) +* monitor: Connecting. (line 105) +* n ('next'): Continuing and Stepping. + (line 76) +* n (SingleKey TUI key): TUI Single Key Mode. (line 19) +* name of type_printer: Type Printing API. (line 18) +* NewObjFileEvent.new_objfile: Events In Python. (line 115) +* next: Continuing and Stepping. + (line 76) +* next&: Background Execution. + (line 45) +* next-history (C-n): Commands For History. + (line 16) +* nexti: Continuing and Stepping. + (line 201) +* nexti&: Background Execution. + (line 48) +* ni ('nexti'): Continuing and Stepping. + (line 201) +* non-incremental-forward-search-history (M-n): Commands For History. + (line 40) +* non-incremental-reverse-search-history (M-p): Commands For History. + (line 35) +* nosharedlibrary: Files. (line 343) +* Objfile: Objfiles In Python. (line 6) +* Objfile.filename: Objfiles In Python. (line 28) +* Objfile.frame_filters: Objfiles In Python. (line 43) +* Objfile.is_valid: Objfiles In Python. (line 49) +* Objfile.pretty_printers: Objfiles In Python. (line 31) +* Objfile.type_printers: Objfiles In Python. (line 39) +* observer: Observer Mode. (line 22) +* output: Output. (line 35) +* output-meta: Readline Init File Syntax. + (line 191) +* overlay: Overlay Commands. (line 17) +* overload-choice annotation: Prompting. (line 32) +* overwrite-mode (): Commands For Text. (line 53) +* page-completions: Readline Init File Syntax. + (line 196) +* Parameter: Parameters In Python. + (line 6) +* Parameter.get_set_string: Parameters In Python. + (line 73) +* Parameter.get_show_string: Parameters In Python. + (line 79) +* Parameter.set_doc: Parameters In Python. + (line 53) +* Parameter.show_doc: Parameters In Python. + (line 59) +* Parameter.value: Parameters In Python. + (line 65) +* Parameter.__init__: Parameters In Python. + (line 18) +* PARAM_AUTO_BOOLEAN: Parameters In Python. + (line 93) +* PARAM_BOOLEAN: Parameters In Python. + (line 89) +* PARAM_ENUM: Parameters In Python. + (line 127) +* PARAM_FILENAME: Parameters In Python. + (line 119) +* PARAM_INTEGER: Parameters In Python. + (line 102) +* PARAM_OPTIONAL_FILENAME: Parameters In Python. + (line 116) +* PARAM_STRING: Parameters In Python. + (line 106) +* PARAM_STRING_NOESCAPE: Parameters In Python. + (line 112) +* PARAM_UINTEGER: Parameters In Python. + (line 98) +* PARAM_ZINTEGER: Parameters In Python. + (line 123) +* passcount: Tracepoint Passcounts. + (line 6) +* path: Environment. (line 14) +* pending-breakpoints: GDB/MI Support Commands. + (line 79) +* PgDn: TUI Keys. (line 50) +* PgUp: TUI Keys. (line 47) +* pi: Python Commands. (line 9) +* pmon, MIPS remote: MIPS Embedded. (line 128) +* po ('print-object'): The Print Command with Objective-C. + (line 6) +* possible-completions (M-?): Commands For Completion. + (line 11) +* post-commands annotation: Prompting. (line 27) +* post-overload-choice annotation: Prompting. (line 32) +* post-prompt annotation: Prompting. (line 24) +* post-prompt-for-continue annotation: Prompting. (line 40) +* post-query annotation: Prompting. (line 36) +* pre-commands annotation: Prompting. (line 27) +* pre-overload-choice annotation: Prompting. (line 32) +* pre-prompt annotation: Prompting. (line 24) +* pre-prompt-for-continue annotation: Prompting. (line 40) +* pre-query annotation: Prompting. (line 36) +* prefix-meta (): Miscellaneous Commands. + (line 18) +* pretty_printer.children: Pretty Printing API. (line 11) +* pretty_printer.display_hint: Pretty Printing API. (line 24) +* pretty_printer.to_string: Pretty Printing API. (line 53) +* previous-history (C-p): Commands For History. + (line 12) +* print: Data. (line 6) +* print-object: The Print Command with Objective-C. + (line 6) +* printf: Output. (line 46) +* proc-trace-entry: SVR4 Process Information. + (line 85) +* proc-trace-exit: SVR4 Process Information. + (line 85) +* proc-untrace-entry: SVR4 Process Information. + (line 85) +* proc-untrace-exit: SVR4 Process Information. + (line 85) +* Progspace: Progspaces In Python. + (line 6) +* Progspace.filename: Progspaces In Python. + (line 24) +* Progspace.frame_filters: Progspaces In Python. + (line 39) +* Progspace.pretty_printers: Progspaces In Python. + (line 27) +* Progspace.type_printers: Progspaces In Python. + (line 35) +* prompt annotation: Prompting. (line 24) +* prompt-for-continue annotation: Prompting. (line 40) +* ptype: Symbols. (line 158) +* putDebugChar: Bootstrapping. (line 20) +* pwd: Working Directory. (line 20) +* py: Python Commands. (line 23) +* python: GDB/MI Support Commands. + (line 82) +* python <1>: Python Commands. (line 23) +* python-interactive: Python Commands. (line 9) +* q ('quit'): Quitting GDB. (line 6) +* q (SingleKey TUI key): TUI Single Key Mode. (line 22) +* query annotation: Prompting. (line 36) +* quit annotation: Errors. (line 6) +* quit [EXPRESSION]: Quitting GDB. (line 6) +* quoted-insert (C-q or C-v): Commands For Text. (line 20) +* r ('run'): Starting. (line 6) +* r (SingleKey TUI key): TUI Single Key Mode. (line 25) +* rbreak: Set Breaks. (line 89) +* rc ('reverse-continue'): Reverse Execution. (line 30) +* rdilogenable: ARM. (line 90) +* rdilogfile: ARM. (line 84) +* re-read-init-file (C-x C-r): Miscellaneous Commands. + (line 6) +* readnow: Files. (line 89) +* rec: Process Record and Replay. + (line 38) +* rec btrace: Process Record and Replay. + (line 38) +* rec del: Process Record and Replay. + (line 196) +* rec full: Process Record and Replay. + (line 38) +* rec function-call-history: Process Record and Replay. + (line 243) +* rec instruction-history: Process Record and Replay. + (line 202) +* rec s: Process Record and Replay. + (line 73) +* recognize on type_recognizer: Type Printing API. (line 42) +* record: Process Record and Replay. + (line 38) +* record btrace: Process Record and Replay. + (line 38) +* record delete: Process Record and Replay. + (line 196) +* record full: Process Record and Replay. + (line 38) +* record function-call-history: Process Record and Replay. + (line 243) +* record goto: Process Record and Replay. + (line 96) +* record instruction-history: Process Record and Replay. + (line 202) +* record restore: Process Record and Replay. + (line 117) +* record save: Process Record and Replay. + (line 110) +* record stop: Process Record and Replay. + (line 73) +* redraw-current-line (): Commands For Moving. (line 30) +* refresh: TUI Commands. (line 58) +* remote delete: File Transfer. (line 23) +* remote get: File Transfer. (line 19) +* remote put: File Transfer. (line 15) +* remotetimeout: Sparclet. (line 12) +* remove-inferiors: Inferiors and Programs. + (line 86) +* remove-symbol-file: Files. (line 160) +* restart CHECKPOINT-ID: Checkpoint/Restart. (line 41) +* restore: Dump/Restore Files. (line 38) +* RET (repeat last command): Command Syntax. (line 21) +* return: Returning. (line 6) +* reverse-continue: Reverse Execution. (line 30) +* reverse-finish: Reverse Execution. (line 77) +* reverse-next: Reverse Execution. (line 60) +* reverse-nexti: Reverse Execution. (line 69) +* reverse-search: Search. (line 16) +* reverse-search-history (C-r): Commands For History. + (line 26) +* reverse-step: Reverse Execution. (line 37) +* reverse-stepi: Reverse Execution. (line 52) +* revert-all-at-newline: Readline Init File Syntax. + (line 206) +* revert-line (M-r): Miscellaneous Commands. + (line 25) +* Right: TUI Keys. (line 62) +* rn ('reverse-next'): Reverse Execution. (line 60) +* rni ('reverse-nexti'): Reverse Execution. (line 69) +* rs ('step'): Reverse Execution. (line 37) +* rsi ('reverse-stepi'): Reverse Execution. (line 52) +* run: Starting. (line 6) +* run&: Background Execution. + (line 32) +* rwatch: Set Watchpoints. (line 79) +* s (SingleKey TUI key): TUI Single Key Mode. (line 28) +* s ('step'): Continuing and Stepping. + (line 44) +* save breakpoints: Save Breakpoints. (line 9) +* save gdb-index: Index Files. (line 19) +* save tracepoints: save tracepoints. (line 6) +* save-tracepoints: save tracepoints. (line 6) +* sdireset: M32R/D. (line 44) +* sdistatus: M32R/D. (line 47) +* sds, a command: PowerPC Embedded. (line 93) +* search: Search. (line 9) +* section: Files. (line 199) +* select-frame: Frames. (line 51) +* self-insert (a, b, A, 1, !, ...): Commands For Text. (line 27) +* set: Help. (line 109) +* set ada trust-PAD-over-XVS: Ada Glitches. (line 42) +* set agent off: In-Process Agent. (line 47) +* set agent on: In-Process Agent. (line 38) +* set annotate: Annotations Overview. + (line 29) +* set architecture: Targets. (line 21) +* set args: Arguments. (line 21) +* set arm: ARM. (line 17) +* set auto-load gdb-scripts: Auto-loading sequences. + (line 13) +* set auto-load libthread-db: libthread_db.so.1 file. + (line 21) +* set auto-load local-gdbinit: Init File in the Current Directory. + (line 14) +* set auto-load off: Auto-loading. (line 32) +* set auto-load python-scripts: Python Auto-loading. (line 17) +* set auto-load safe-path: Auto-loading safe path. + (line 32) +* set auto-load scripts-directory: objfile-gdbdotext file. + (line 35) +* set auto-solib-add: Files. (line 305) +* set backtrace: Backtrace. (line 116) +* set basenames-may-differ: Files. (line 524) +* set board-address: M32R/D. (line 21) +* set breakpoint always-inserted: Set Breaks. (line 317) +* set breakpoint auto-hw: Set Breaks. (line 297) +* set breakpoint condition-evaluation: Set Breaks. (line 345) +* set breakpoint pending: Set Breaks. (line 266) +* set can-use-hw-watchpoints: Set Watchpoints. (line 116) +* set case-sensitive: Symbols. (line 27) +* set charset: Character Sets. (line 46) +* set check range: Range Checking. (line 34) +* set check type: Type Checking. (line 35) +* set circular-trace-buffer: Starting and Stopping Trace Experiments. + (line 93) +* set code-cache: Caching Target Data. (line 36) +* set coerce-float-to-double: ABI. (line 45) +* set com1base: DJGPP Native. (line 122) +* set com1irq: DJGPP Native. (line 122) +* set com2base: DJGPP Native. (line 122) +* set com2irq: DJGPP Native. (line 122) +* set com3base: DJGPP Native. (line 122) +* set com3irq: DJGPP Native. (line 122) +* set com4base: DJGPP Native. (line 122) +* set com4irq: DJGPP Native. (line 122) +* set complaints: Messages/Warnings. (line 29) +* set confirm: Messages/Warnings. (line 49) +* set cp-abi: ABI. (line 57) +* set cygwin-exceptions: Cygwin Native. (line 42) +* set data-directory: Data Files. (line 12) +* set dcache line-size: Caching Target Data. (line 60) +* set dcache size: Caching Target Data. (line 57) +* set debug: Debugging Output. (line 17) +* set debug aarch64: AArch64. (line 10) +* set debug auto-load: Auto-loading verbose mode. + (line 27) +* set debug darwin: Darwin. (line 9) +* set debug entry-values: Tail Call Frames. (line 47) +* set debug hppa: HPPA. (line 10) +* set debug libthread-db: Threads. (line 209) +* set debug mach-o: Darwin. (line 16) +* set debug mips: MIPS. (line 100) +* set debug monitor: Target Commands. (line 101) +* set debug nios2: Nios II. (line 10) +* set debug-file-directory: Separate Debug Files. + (line 67) +* set debugevents: Cygwin Native. (line 71) +* set debugexceptions: Cygwin Native. (line 82) +* set debugexec: Cygwin Native. (line 78) +* set debugmemory: Cygwin Native. (line 86) +* set default-collect: Tracepoint Actions. (line 134) +* set demangle-style: Print Settings. (line 427) +* set detach-on-fork: Forks. (line 54) +* set directories: Source Path. (line 118) +* set disable-randomization: Starting. (line 158) +* set disassemble-next-line: Machine Code. (line 143) +* set disassembly-flavor: Machine Code. (line 131) +* set disconnected-dprintf: Dynamic Printf. (line 83) +* set disconnected-tracing: Starting and Stopping Trace Experiments. + (line 55) +* set displaced-stepping: Maintenance Commands. + (line 66) +* set download-path: M32R/D. (line 15) +* set editing: Editing. (line 15) +* set endian: Byte Order. (line 13) +* set environment: Environment. (line 39) +* set exceptions, Hurd command: Hurd Native. (line 39) +* set exec-direction: Reverse Execution. (line 83) +* set exec-done-display: Debugging Output. (line 11) +* set exec-wrapper: Starting. (line 110) +* set extended-prompt: Prompt. (line 25) +* set extension-language: Show. (line 30) +* set follow-exec-mode: Forks. (line 101) +* set follow-fork-mode: Forks. (line 35) +* set frame-filter priority: Frame Filter Management. + (line 84) +* set gnutarget: Target Commands. (line 28) +* set hash, for remote monitors: Target Commands. (line 92) +* set height: Screen Size. (line 20) +* set history expansion: Command History. (line 67) +* set history filename: Command History. (line 26) +* set history save: Command History. (line 36) +* set history size: Command History. (line 45) +* set host-charset: Character Sets. (line 33) +* set inferior-tty: Input/Output. (line 49) +* set input-radix: Numbers. (line 14) +* set interactive-mode: Other Misc Settings. (line 6) +* set language: Manually. (line 9) +* set libthread-db-search-path: Threads. (line 171) +* set listsize: List. (line 33) +* set logging: Logging Output. (line 9) +* set mach-exceptions: Darwin. (line 27) +* set max-user-call-depth: Define. (line 78) +* set mem inaccessible-by-default: Memory Region Attributes. + (line 123) +* set mips abi: MIPS. (line 32) +* set mips compression: MIPS. (line 49) +* set mips mask-address: MIPS. (line 80) +* set mipsfpu: MIPS Embedded. (line 58) +* set monitor-prompt, MIPS remote: MIPS Embedded. (line 105) +* set monitor-warnings, MIPS remote: MIPS Embedded. (line 119) +* set multiple-symbols: Ambiguous Expressions. + (line 50) +* set new-console: Cygwin Native. (line 54) +* set new-group: Cygwin Native. (line 63) +* set non-stop: Non-Stop Mode. (line 38) +* set opaque-type-resolution: Symbols. (line 321) +* set osabi: ABI. (line 11) +* set output-radix: Numbers. (line 30) +* set overload-resolution: Debugging C Plus Plus. + (line 55) +* set pagination: Screen Size. (line 39) +* set powerpc: PowerPC Embedded. (line 51) +* set print: Print Settings. (line 11) +* set print entry-values: Print Settings. (line 206) +* set print frame-arguments: Print Settings. (line 154) +* set print inferior-events: Inferiors and Programs. + (line 117) +* set print thread-events: Threads. (line 150) +* set print type methods: Symbols. (line 44) +* set print type typedefs: Symbols. (line 57) +* set processor: Targets. (line 31) +* set procfs-file: SVR4 Process Information. + (line 74) +* set procfs-trace: SVR4 Process Information. + (line 68) +* set prompt: Prompt. (line 16) +* set python print-stack: Python Commands. (line 46) +* set radix: Numbers. (line 43) +* set range-stepping: Continuing and Stepping. + (line 220) +* set ravenscar task-switching off: Ravenscar Profile. (line 14) +* set ravenscar task-switching on: Ravenscar Profile. (line 10) +* set rdiheartbeat: ARM. (line 107) +* set rdiromatzero: ARM. (line 97) +* set record: Process Record and Replay. + (line 233) +* set record full: Process Record and Replay. + (line 121) +* set remote: Remote Configuration. + (line 6) +* set remote system-call-allowed: system. (line 37) +* set remote-mips64-transfers-32bit-regs: MIPS. (line 90) +* set remotecache: Caching Target Data. (line 20) +* set remoteflow: Remote Configuration. + (line 41) +* set retransmit-timeout: MIPS Embedded. (line 81) +* set schedule-multiple: All-Stop Mode. (line 66) +* set script-extension: Extending GDB. (line 27) +* set sdstimeout: PowerPC Embedded. (line 86) +* set server-address: M32R/D. (line 27) +* set sh calling-convention: Super-H. (line 9) +* set shell: Cygwin Native. (line 90) +* set signal-thread: Hurd Native. (line 21) +* set signals, Hurd command: Hurd Native. (line 11) +* set sigs, Hurd command: Hurd Native. (line 11) +* set sigthread: Hurd Native. (line 21) +* set solib-absolute-prefix: Files. (line 381) +* set solib-search-path: Files. (line 450) +* set spu: SPU. (line 38) +* set stack-cache: Caching Target Data. (line 28) +* set startup-with-shell: Starting. (line 135) +* set step-mode: Continuing and Stepping. + (line 90) +* set stop-on-solib-events: Files. (line 358) +* set stopped, Hurd command: Hurd Native. (line 31) +* set struct-convention: i386. (line 7) +* set substitute-path: Source Path. (line 125) +* set syn-garbage-limit, MIPS remote: MIPS Embedded. (line 96) +* set sysroot: Files. (line 381) +* set target-async: Background Execution. + (line 17) +* set target-charset: Character Sets. (line 28) +* set target-file-system-kind (unix|dos-based|auto): Files. (line 464) +* set target-wide-charset: Character Sets. (line 61) +* set task, Hurd commands: Hurd Native. (line 48) +* set tcp: Remote Configuration. + (line 116) +* set thread, Hurd command: Hurd Native. (line 90) +* set timeout: MIPS Embedded. (line 81) +* set trace-buffer-size: Starting and Stopping Trace Experiments. + (line 107) +* set trace-commands: Messages/Warnings. (line 65) +* set trace-notes: Starting and Stopping Trace Experiments. + (line 126) +* set trace-stop-notes: Starting and Stopping Trace Experiments. + (line 132) +* set trace-user: Starting and Stopping Trace Experiments. + (line 122) +* set trust-readonly-sections: Files. (line 261) +* set tui active-border-mode: TUI Configuration. (line 24) +* set tui border-kind: TUI Configuration. (line 9) +* set tui border-mode: TUI Configuration. (line 23) +* set unwind-on-terminating-exception: Calling. (line 46) +* set unwindonsignal: Calling. (line 35) +* set variable: Assignment. (line 16) +* set verbose: Messages/Warnings. (line 15) +* set watchdog: Maintenance Commands. + (line 407) +* set width: Screen Size. (line 20) +* set write: Patching. (line 15) +* set-mark (C-@): Miscellaneous Commands. + (line 32) +* set_debug_traps: Stub Contents. (line 10) +* share: Files. (line 334) +* sharedlibrary: Files. (line 334) +* shell: Shell Commands. (line 10) +* show: Help. (line 114) +* show ada trust-PAD-over-XVS: Ada Glitches. (line 42) +* show agent: In-Process Agent. (line 51) +* show annotate: Annotations Overview. + (line 34) +* show architecture: Targets. (line 21) +* show args: Arguments. (line 28) +* show arm: ARM. (line 21) +* show auto-load: Auto-loading. (line 45) +* show auto-load gdb-scripts: Auto-loading sequences. + (line 17) +* show auto-load libthread-db: libthread_db.so.1 file. + (line 25) +* show auto-load local-gdbinit: Init File in the Current Directory. + (line 18) +* show auto-load python-scripts: Python Auto-loading. (line 20) +* show auto-load safe-path: Auto-loading safe path. + (line 46) +* show auto-load scripts-directory: objfile-gdbdotext file. + (line 59) +* show auto-solib-add: Files. (line 322) +* show backtrace: Backtrace. (line 123) +* show basenames-may-differ: Files. (line 527) +* show board-address: M32R/D. (line 24) +* show breakpoint always-inserted: Set Breaks. (line 317) +* show breakpoint auto-hw: Set Breaks. (line 297) +* show breakpoint condition-evaluation: Set Breaks. (line 345) +* show breakpoint pending: Set Breaks. (line 266) +* show can-use-hw-watchpoints: Set Watchpoints. (line 119) +* show case-sensitive: Symbols. (line 40) +* show charset: Character Sets. (line 52) +* show check range: Range Checking. (line 34) +* show check type: Type Checking. (line 35) +* show circular-trace-buffer: Starting and Stopping Trace Experiments. + (line 100) +* show code-cache: Caching Target Data. (line 42) +* show coerce-float-to-double: ABI. (line 54) +* show com1base: DJGPP Native. (line 134) +* show com1irq: DJGPP Native. (line 134) +* show com2base: DJGPP Native. (line 134) +* show com2irq: DJGPP Native. (line 134) +* show com3base: DJGPP Native. (line 134) +* show com3irq: DJGPP Native. (line 134) +* show com4base: DJGPP Native. (line 134) +* show com4irq: DJGPP Native. (line 134) +* show commands: Command History. (line 80) +* show complaints: Messages/Warnings. (line 35) +* show configuration: Help. (line 147) +* show confirm: Messages/Warnings. (line 57) +* show convenience: Convenience Vars. (line 37) +* show copying: Help. (line 138) +* show cp-abi: ABI. (line 57) +* show cygwin-exceptions: Cygwin Native. (line 50) +* show data-directory: Data Files. (line 16) +* show dcache line-size: Caching Target Data. (line 68) +* show dcache size: Caching Target Data. (line 64) +* show debug: Debugging Output. (line 20) +* show debug auto-load: Auto-loading verbose mode. + (line 30) +* show debug darwin: Darwin. (line 13) +* show debug entry-values: Tail Call Frames. (line 55) +* show debug libthread-db: Threads. (line 209) +* show debug mach-o: Darwin. (line 23) +* show debug mips: MIPS. (line 104) +* show debug monitor: Target Commands. (line 105) +* show debug nios2: Nios II. (line 14) +* show debug-file-directory: Separate Debug Files. + (line 72) +* show default-collect: Tracepoint Actions. (line 142) +* show detach-on-fork: Forks. (line 69) +* show directories: Source Path. (line 122) +* show disassemble-next-line: Machine Code. (line 143) +* show disassembly-flavor: Machine Code. (line 140) +* show disconnected-dprintf: Dynamic Printf. (line 88) +* show disconnected-tracing: Starting and Stopping Trace Experiments. + (line 62) +* show displaced-stepping: Maintenance Commands. + (line 66) +* show download-path: M32R/D. (line 18) +* show editing: Editing. (line 22) +* show environment: Environment. (line 33) +* show exceptions, Hurd command: Hurd Native. (line 45) +* show exec-done-display: Debugging Output. (line 14) +* show extended-prompt: Prompt. (line 39) +* show follow-fork-mode: Forks. (line 48) +* show frame-filter priority: Frame Filter Management. + (line 91) +* show gnutarget: Target Commands. (line 40) +* show hash, for remote monitors: Target Commands. (line 98) +* show height: Screen Size. (line 20) +* show history: Command History. (line 72) +* show host-charset: Character Sets. (line 55) +* show inferior-tty: Input/Output. (line 52) +* show input-radix: Numbers. (line 35) +* show interactive-mode: Other Misc Settings. (line 20) +* show language: Show. (line 10) +* show libthread-db-search-path: Threads. (line 206) +* show listsize: List. (line 39) +* show logging: Logging Output. (line 22) +* show mach-exceptions: Darwin. (line 34) +* show max-user-call-depth: Define. (line 78) +* show mem inaccessible-by-default: Memory Region Attributes. + (line 129) +* show mips abi: MIPS. (line 46) +* show mips compression: MIPS. (line 72) +* show mips mask-address: MIPS. (line 86) +* show mipsfpu: MIPS Embedded. (line 58) +* show monitor-prompt, MIPS remote: MIPS Embedded. (line 115) +* show monitor-warnings, MIPS remote: MIPS Embedded. (line 125) +* show multiple-symbols: Ambiguous Expressions. + (line 70) +* show new-console: Cygwin Native. (line 59) +* show new-group: Cygwin Native. (line 68) +* show non-stop: Non-Stop Mode. (line 41) +* show opaque-type-resolution: Symbols. (line 336) +* show osabi: ABI. (line 11) +* show output-radix: Numbers. (line 38) +* show overload-resolution: Debugging C Plus Plus. + (line 72) +* show pagination: Screen Size. (line 45) +* show paths: Environment. (line 29) +* show print: Print Settings. (line 39) +* show print inferior-events: Inferiors and Programs. + (line 125) +* show print thread-events: Threads. (line 160) +* show print type methods: Symbols. (line 53) +* show print type typedefs: Symbols. (line 70) +* show processor: Targets. (line 31) +* show procfs-file: SVR4 Process Information. + (line 79) +* show procfs-trace: SVR4 Process Information. + (line 71) +* show prompt: Prompt. (line 19) +* show radix: Numbers. (line 43) +* show range-stepping: Continuing and Stepping. + (line 220) +* show ravenscar task-switching: Ravenscar Profile. (line 22) +* show rdiheartbeat: ARM. (line 112) +* show rdiromatzero: ARM. (line 104) +* show record: Process Record and Replay. + (line 239) +* show record full: Process Record and Replay. + (line 139) +* show remote: Remote Configuration. + (line 6) +* show remote system-call-allowed: system. (line 41) +* show remote-mips64-transfers-32bit-regs: MIPS. (line 96) +* show remotecache: Caching Target Data. (line 25) +* show remoteflow: Remote Configuration. + (line 45) +* show retransmit-timeout: MIPS Embedded. (line 81) +* show script-extension: Extending GDB. (line 27) +* show sdstimeout: PowerPC Embedded. (line 90) +* show server-address: M32R/D. (line 31) +* show sh calling-convention: Super-H. (line 22) +* show shell: Cygwin Native. (line 94) +* show signal-thread: Hurd Native. (line 27) +* show signals, Hurd command: Hurd Native. (line 17) +* show sigs, Hurd command: Hurd Native. (line 17) +* show sigthread: Hurd Native. (line 27) +* show solib-search-path: Files. (line 461) +* show spu: SPU. (line 43) +* show stack-cache: Caching Target Data. (line 33) +* show stop-on-solib-events: Files. (line 364) +* show stopped, Hurd command: Hurd Native. (line 36) +* show struct-convention: i386. (line 15) +* show substitute-path: Source Path. (line 162) +* show syn-garbage-limit, MIPS remote: MIPS Embedded. (line 101) +* show sysroot: Files. (line 447) +* show target-async: Background Execution. + (line 20) +* show target-charset: Character Sets. (line 58) +* show target-file-system-kind: Files. (line 464) +* show target-wide-charset: Character Sets. (line 67) +* show task, Hurd commands: Hurd Native. (line 56) +* show tcp: Remote Configuration. + (line 116) +* show thread, Hurd command: Hurd Native. (line 100) +* show timeout: MIPS Embedded. (line 81) +* show trace-buffer-size: Starting and Stopping Trace Experiments. + (line 114) +* show trace-notes: Starting and Stopping Trace Experiments. + (line 129) +* show trace-stop-notes: Starting and Stopping Trace Experiments. + (line 137) +* show trace-user: Starting and Stopping Trace Experiments. + (line 124) +* show unwind-on-terminating-exception: Calling. (line 54) +* show unwindonsignal: Calling. (line 42) +* show user: Define. (line 71) +* show values: Value History. (line 47) +* show verbose: Messages/Warnings. (line 21) +* show version: Help. (line 128) +* show warranty: Help. (line 142) +* show width: Screen Size. (line 20) +* show write: Patching. (line 26) +* show-all-if-ambiguous: Readline Init File Syntax. + (line 212) +* show-all-if-unmodified: Readline Init File Syntax. + (line 218) +* si ('stepi'): Continuing and Stepping. + (line 188) +* signal: Signaling. (line 6) +* signal annotation: Annotations for Running. + (line 42) +* signal-name annotation: Annotations for Running. + (line 22) +* signal-name-end annotation: Annotations for Running. + (line 22) +* signal-string annotation: Annotations for Running. + (line 22) +* signal-string-end annotation: Annotations for Running. + (line 22) +* SignalEvent.stop_signal: Events In Python. (line 91) +* signalled annotation: Annotations for Running. + (line 22) +* silent: Break Commands. (line 43) +* sim: Z8000. (line 15) +* sim, a command: Embedded Processors. (line 13) +* skip delete: Skipping Over Functions and Files. + (line 82) +* skip disable: Skipping Over Functions and Files. + (line 90) +* skip enable: Skipping Over Functions and Files. + (line 86) +* skip file: Skipping Over Functions and Files. + (line 46) +* skip function: Skipping Over Functions and Files. + (line 34) +* skip-completed-text: Readline Init File Syntax. + (line 227) +* skip-csi-sequence (): Miscellaneous Commands. + (line 51) +* source: Command Files. (line 17) +* source annotation: Source Annotations. (line 6) +* start: Starting. (line 78) +* start-kbd-macro (C-x (): Keyboard Macros. (line 6) +* starting annotation: Annotations for Running. + (line 6) +* STDERR: Basic Python. (line 140) +* STDERR <1>: Basic Python. (line 160) +* STDLOG: Basic Python. (line 143) +* STDLOG <1>: Basic Python. (line 163) +* STDOUT: Basic Python. (line 137) +* STDOUT <1>: Basic Python. (line 157) +* step: Continuing and Stepping. + (line 44) +* step&: Background Execution. + (line 39) +* stepi: Continuing and Stepping. + (line 188) +* stepi&: Background Execution. + (line 42) +* stop, a pseudo-command: Hooks. (line 21) +* stopping annotation: Annotations for Running. + (line 6) +* strace: Create and Delete Tracepoints. + (line 76) +* symbol-file: Files. (line 45) +* Symbol.addr_class: Symbols In Python. (line 74) +* Symbol.is_argument: Symbols In Python. (line 84) +* Symbol.is_constant: Symbols In Python. (line 87) +* Symbol.is_function: Symbols In Python. (line 90) +* Symbol.is_valid: Symbols In Python. (line 98) +* Symbol.is_variable: Symbols In Python. (line 93) +* Symbol.line: Symbols In Python. (line 57) +* Symbol.linkage_name: Symbols In Python. (line 65) +* Symbol.name: Symbols In Python. (line 61) +* Symbol.needs_frame: Symbols In Python. (line 79) +* Symbol.print_name: Symbols In Python. (line 69) +* Symbol.symtab: Symbols In Python. (line 52) +* Symbol.type: Symbols In Python. (line 47) +* Symbol.value: Symbols In Python. (line 105) +* SYMBOL_FUNCTIONS_DOMAIN: Symbols In Python. (line 128) +* SYMBOL_LABEL_DOMAIN: Symbols In Python. (line 123) +* SYMBOL_LOC_ARG: Symbols In Python. (line 145) +* SYMBOL_LOC_BLOCK: Symbols In Python. (line 161) +* SYMBOL_LOC_COMPUTED: Symbols In Python. (line 171) +* SYMBOL_LOC_CONST: Symbols In Python. (line 139) +* SYMBOL_LOC_CONST_BYTES: Symbols In Python. (line 163) +* SYMBOL_LOC_LOCAL: Symbols In Python. (line 156) +* SYMBOL_LOC_OPTIMIZED_OUT: Symbols In Python. (line 169) +* SYMBOL_LOC_REF_ARG: Symbols In Python. (line 148) +* SYMBOL_LOC_REGISTER: Symbols In Python. (line 143) +* SYMBOL_LOC_REGPARM_ADDR: Symbols In Python. (line 152) +* SYMBOL_LOC_STATIC: Symbols In Python. (line 141) +* SYMBOL_LOC_TYPEDEF: Symbols In Python. (line 158) +* SYMBOL_LOC_UNDEF: Symbols In Python. (line 137) +* SYMBOL_LOC_UNRESOLVED: Symbols In Python. (line 165) +* SYMBOL_STRUCT_DOMAIN: Symbols In Python. (line 121) +* SYMBOL_TYPES_DOMAIN: Symbols In Python. (line 130) +* SYMBOL_UNDEF_DOMAIN: Symbols In Python. (line 115) +* SYMBOL_VARIABLES_DOMAIN: Symbols In Python. (line 125) +* SYMBOL_VAR_DOMAIN: Symbols In Python. (line 118) +* Symtab.filename: Symbol Tables In Python. + (line 43) +* Symtab.fullname: Symbol Tables In Python. + (line 60) +* Symtab.global_block: Symbol Tables In Python. + (line 63) +* Symtab.is_valid: Symbol Tables In Python. + (line 53) +* Symtab.linetable: Symbol Tables In Python. + (line 71) +* Symtab.objfile: Symbol Tables In Python. + (line 47) +* Symtab.static_block: Symbol Tables In Python. + (line 67) +* Symtab_and_line.is_valid: Symbol Tables In Python. + (line 34) +* Symtab_and_line.last: Symbol Tables In Python. + (line 24) +* Symtab_and_line.line: Symbol Tables In Python. + (line 28) +* Symtab_and_line.pc: Symbol Tables In Python. + (line 20) +* Symtab_and_line.symtab: Symbol Tables In Python. + (line 16) +* sysinfo: DJGPP Native. (line 19) +* tab-insert (M-): Commands For Text. (line 24) +* tabset: TUI Commands. (line 84) +* target: Target Commands. (line 49) +* target array: MIPS Embedded. (line 48) +* target ctf: Trace Files. (line 28) +* target dbug: M68K. (line 9) +* target ddb PORT: MIPS Embedded. (line 40) +* target dink32: PowerPC Embedded. (line 72) +* target lsi PORT: MIPS Embedded. (line 43) +* target m32r: M32R/D. (line 6) +* target m32rsdi: M32R/D. (line 9) +* target mips PORT: MIPS Embedded. (line 14) +* target op50n: PA. (line 6) +* target pmon PORT: MIPS Embedded. (line 37) +* target ppcbug: PowerPC Embedded. (line 75) +* target ppcbug1: PowerPC Embedded. (line 76) +* target r3900: MIPS Embedded. (line 45) +* target rdi: ARM. (line 6) +* target rdp: ARM. (line 11) +* target record: Process Record and Replay. + (line 38) +* target record-btrace: Process Record and Replay. + (line 38) +* target record-full: Process Record and Replay. + (line 38) +* target sds: PowerPC Embedded. (line 79) +* target sim, with Z8000: Z8000. (line 15) +* target sparclite: Sparclite. (line 6) +* target tfile: Trace Files. (line 28) +* target vxworks: VxWorks. (line 6) +* target w89k: PA. (line 9) +* task (Ada): Ada Tasks. (line 103) +* tbreak: Set Breaks. (line 54) +* tcatch: Set Catchpoints. (line 251) +* tdump: tdump. (line 6) +* teval (tracepoints): Tracepoint Actions. (line 110) +* tfile: Trace Files. (line 28) +* tfind: tfind. (line 6) +* thbreak: Set Breaks. (line 79) +* this, inside C++ member functions: C Plus Plus Expressions. + (line 20) +* thread apply: Threads. (line 116) +* thread find: Threads. (line 136) +* thread name: Threads. (line 125) +* thread THREADNO: Threads. (line 94) +* thread-info: GDB/MI Support Commands. + (line 86) +* ThreadEvent.inferior_thread: Events In Python. (line 54) +* tilde-expand (M-~): Miscellaneous Commands. + (line 29) +* tload, M32R: M32R/D. (line 39) +* trace: Create and Delete Tracepoints. + (line 6) +* transpose-chars (C-t): Commands For Text. (line 30) +* transpose-words (M-t): Commands For Text. (line 36) +* tsave: Trace Files. (line 12) +* tstart [ NOTES ]: Starting and Stopping Trace Experiments. + (line 6) +* tstatus: Starting and Stopping Trace Experiments. + (line 27) +* tstop [ NOTES ]: Starting and Stopping Trace Experiments. + (line 16) +* tty: Input/Output. (line 23) +* tui reg: TUI Commands. (line 61) +* tvariable: Trace State Variables. + (line 26) +* Type.array: Types In Python. (line 103) +* Type.code: Types In Python. (line 33) +* Type.const: Types In Python. (line 124) +* Type.fields: Types In Python. (line 54) +* Type.name: Types In Python. (line 37) +* Type.pointer: Types In Python. (line 147) +* Type.range: Types In Python. (line 137) +* Type.reference: Types In Python. (line 143) +* Type.sizeof: Types In Python. (line 41) +* Type.strip_typedefs: Types In Python. (line 151) +* Type.tag: Types In Python. (line 46) +* Type.target: Types In Python. (line 155) +* Type.template_argument: Types In Python. (line 169) +* Type.unqualified: Types In Python. (line 132) +* Type.vector: Types In Python. (line 111) +* Type.volatile: Types In Python. (line 128) +* TYPE_CODE_ARRAY: Types In Python. (line 187) +* TYPE_CODE_BITSTRING: Types In Python. (line 225) +* TYPE_CODE_BOOL: Types In Python. (line 246) +* TYPE_CODE_CHAR: Types In Python. (line 243) +* TYPE_CODE_COMPLEX: Types In Python. (line 249) +* TYPE_CODE_DECFLOAT: Types In Python. (line 258) +* TYPE_CODE_ENUM: Types In Python. (line 196) +* TYPE_CODE_ERROR: Types In Python. (line 228) +* TYPE_CODE_FLAGS: Types In Python. (line 199) +* TYPE_CODE_FLT: Types In Python. (line 208) +* TYPE_CODE_FUNC: Types In Python. (line 202) +* TYPE_CODE_INT: Types In Python. (line 205) +* TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 261) +* TYPE_CODE_MEMBERPTR: Types In Python. (line 237) +* TYPE_CODE_METHOD: Types In Python. (line 231) +* TYPE_CODE_METHODPTR: Types In Python. (line 234) +* TYPE_CODE_NAMESPACE: Types In Python. (line 255) +* TYPE_CODE_PTR: Types In Python. (line 184) +* TYPE_CODE_RANGE: Types In Python. (line 217) +* TYPE_CODE_REF: Types In Python. (line 240) +* TYPE_CODE_SET: Types In Python. (line 214) +* TYPE_CODE_STRING: Types In Python. (line 220) +* TYPE_CODE_STRUCT: Types In Python. (line 190) +* TYPE_CODE_TYPEDEF: Types In Python. (line 252) +* TYPE_CODE_UNION: Types In Python. (line 193) +* TYPE_CODE_VOID: Types In Python. (line 211) +* u (SingleKey TUI key): TUI Single Key Mode. (line 31) +* u ('until'): Continuing and Stepping. + (line 116) +* undefined-command-error-code: GDB/MI Support Commands. + (line 101) +* undisplay: Auto Display. (line 45) +* undo (C-_ or C-x C-u): Miscellaneous Commands. + (line 22) +* universal-argument (): Numeric Arguments. (line 10) +* unix-filename-rubout (): Commands For Killing. + (line 32) +* unix-line-discard (C-u): Commands For Killing. + (line 12) +* unix-word-rubout (C-w): Commands For Killing. + (line 28) +* unset environment: Environment. (line 55) +* unset substitute-path: Source Path. (line 154) +* until: Continuing and Stepping. + (line 116) +* until&: Background Execution. + (line 57) +* up: Selection. (line 35) +* Up: TUI Keys. (line 53) +* up-silently: Selection. (line 64) +* upcase-word (M-u): Commands For Text. (line 41) +* update: TUI Commands. (line 76) +* upload, M32R: M32R/D. (line 34) +* use_dbt_break: M32R/D. (line 64) +* use_debug_dma: M32R/D. (line 53) +* use_ib_break: M32R/D. (line 61) +* use_mon_code: M32R/D. (line 57) +* v (SingleKey TUI key): TUI Single Key Mode. (line 34) +* Value.address: Values From Inferior. + (line 51) +* Value.cast: Values From Inferior. + (line 125) +* Value.dereference: Values From Inferior. + (line 131) +* Value.dynamic_cast: Values From Inferior. + (line 209) +* Value.dynamic_type: Values From Inferior. + (line 65) +* Value.fetch_lazy: Values From Inferior. + (line 271) +* Value.is_lazy: Values From Inferior. + (line 80) +* Value.is_optimized_out: Values From Inferior. + (line 56) +* Value.lazy_string: Values From Inferior. + (line 249) +* Value.referenced_value: Values From Inferior. + (line 184) +* Value.reinterpret_cast: Values From Inferior. + (line 213) +* Value.string: Values From Inferior. + (line 217) +* Value.type: Values From Inferior. + (line 61) +* Value.__init__: Values From Inferior. + (line 93) +* vi-editing-mode (M-C-j): Miscellaneous Commands. + (line 91) +* visible-stats: Readline Init File Syntax. + (line 240) +* vxworks-timeout: VxWorks. (line 22) +* w (SingleKey TUI key): TUI Single Key Mode. (line 37) +* watch: Set Watchpoints. (line 42) +* watchpoint annotation: Annotations for Running. + (line 50) +* whatis: Symbols. (line 103) +* where: Backtrace. (line 46) +* while: Command Files. (line 85) +* while-stepping (tracepoints): Tracepoint Actions. (line 118) +* winheight: TUI Commands. (line 80) +* WP_ACCESS: Breakpoints In Python. + (line 70) +* WP_READ: Breakpoints In Python. + (line 64) +* WP_WRITE: Breakpoints In Python. + (line 67) +* x (examine memory): Memory. (line 9) +* x(examine), and info line: Machine Code. (line 30) +* yank (C-y): Commands For Killing. + (line 59) +* yank-last-arg (M-. or M-_): Commands For History. + (line 64) +* yank-nth-arg (M-C-y): Commands For History. + (line 55) +* yank-pop (M-y): Commands For Killing. + (line 62) + + + +Tag Table: +Node: Top1702 +Node: Summary5160 +Node: Free Software7021 +Node: Free Documentation7761 +Node: Contributors12695 +Node: Sample Session20793 +Node: Invocation27631 +Node: Invoking GDB28174 +Node: File Options30486 +Node: Mode Options33543 +Ref: -nx33770 +Ref: -nh34854 +Node: Startup41157 +Ref: Home Directory Init File41708 +Ref: Option -init-eval-command41818 +Ref: Init File in the Current Directory during Startup42158 +Ref: Startup-Footnote-144354 +Node: Quitting GDB44463 +Node: Shell Commands45360 +Node: Logging Output46287 +Node: Commands47124 +Node: Command Syntax47762 +Node: Completion49928 +Ref: Completion-Footnote-155292 +Node: Help55452 +Node: Running61203 +Node: Compilation62432 +Node: Starting64516 +Node: Arguments74638 +Node: Environment75907 +Node: Working Directory79283 +Node: Input/Output80435 +Node: Attach82406 +Node: Kill Process84872 +Node: Inferiors and Programs85853 +Node: Threads93095 +Ref: set libthread-db-search-path100499 +Node: Forks102553 +Node: Checkpoint/Restart108867 +Ref: Checkpoint/Restart-Footnote-1113395 +Node: Stopping113430 +Node: Breakpoints114693 +Node: Set Breaks118232 +Node: Set Watchpoints136950 +Node: Set Catchpoints146354 +Node: Delete Breaks157224 +Node: Disabling159164 +Node: Conditions162549 +Node: Break Commands168196 +Node: Dynamic Printf171417 +Node: Save Breakpoints175676 +Node: Static Probe Points176851 +Node: Error in Breakpoints179538 +Node: Breakpoint-related Warnings180274 +Node: Continuing and Stepping182601 +Ref: range stepping191976 +Node: Skipping Over Functions and Files193056 +Node: Signals196628 +Ref: extra signal information201058 +Node: Thread Stops202562 +Node: All-Stop Mode203661 +Node: Non-Stop Mode207561 +Node: Background Execution211034 +Node: Thread-Specific Breakpoints213598 +Node: Interrupted System Calls215602 +Node: Observer Mode217116 +Node: Reverse Execution220552 +Ref: Reverse Execution-Footnote-1225177 +Ref: Reverse Execution-Footnote-2225804 +Node: Process Record and Replay225854 +Node: Stack238819 +Node: Frames240367 +Node: Backtrace243119 +Ref: backtrace-command243470 +Ref: Backtrace-Footnote-1249240 +Node: Frame Filter Management249428 +Ref: disable frame-filter all249972 +Node: Selection254272 +Node: Frame Info257150 +Node: Source259137 +Node: List260203 +Node: Specify Location262905 +Node: Edit267509 +Ref: Edit-Footnote-1268985 +Node: Search269220 +Node: Source Path270028 +Ref: set substitute-path276394 +Node: Machine Code278614 +Node: Data285515 +Node: Expressions293179 +Node: Ambiguous Expressions295270 +Node: Variables298500 +Node: Arrays304566 +Node: Output Formats307097 +Ref: Output Formats-Footnote-1310470 +Node: Memory310627 +Node: Auto Display316779 +Node: Print Settings321321 +Ref: set print entry-values329483 +Node: Pretty Printing340797 +Node: Pretty-Printer Introduction341311 +Node: Pretty-Printer Example343066 +Node: Pretty-Printer Commands343844 +Node: Value History346268 +Node: Convenience Vars348690 +Node: Convenience Funs355172 +Node: Registers358043 +Ref: Registers-Footnote-1363972 +Node: Floating Point Hardware364367 +Node: Vector Unit364899 +Node: OS Information365286 +Ref: linux info os infotypes367310 +Node: Memory Region Attributes371517 +Node: Dump/Restore Files376181 +Node: Core File Generation378486 +Node: Character Sets379710 +Node: Caching Target Data386075 +Ref: Caching Target Data-Footnote-1388803 +Node: Searching Memory389041 +Node: Optimized Code391919 +Node: Inline Functions393596 +Node: Tail Call Frames396223 +Ref: set debug entry-values398363 +Node: Macros402437 +Ref: Macros-Footnote-1410013 +Node: Tracepoints410166 +Node: Set Tracepoints412228 +Node: Create and Delete Tracepoints415166 +Node: Enable and Disable Tracepoints421567 +Node: Tracepoint Passcounts422807 +Node: Tracepoint Conditions424218 +Node: Trace State Variables425912 +Node: Tracepoint Actions428103 +Node: Listing Tracepoints434406 +Node: Listing Static Tracepoint Markers436108 +Node: Starting and Stopping Trace Experiments437956 +Ref: disconnected tracing439701 +Node: Tracepoint Restrictions444121 +Node: Analyze Collected Data447890 +Node: tfind449196 +Node: tdump453618 +Node: save tracepoints456133 +Node: Tracepoint Variables456629 +Node: Trace Files457757 +Node: Overlays460127 +Node: How Overlays Work460847 +Ref: A code overlay463402 +Node: Overlay Commands466815 +Node: Automatic Overlay Debugging470997 +Node: Overlay Sample Program473136 +Node: Languages474873 +Node: Setting476036 +Node: Filenames477737 +Node: Manually478548 +Node: Automatically479757 +Node: Show480818 +Ref: show language481106 +Node: Checks482140 +Node: Type Checking483145 +Node: Range Checking484974 +Node: Supported Languages487375 +Node: C488675 +Node: C Operators489639 +Node: C Constants493952 +Node: C Plus Plus Expressions496831 +Node: C Defaults500174 +Node: C Checks500842 +Node: Debugging C501402 +Node: Debugging C Plus Plus501886 +Node: Decimal Floating Point505360 +Node: D506630 +Node: Go506888 +Node: Objective-C507982 +Node: Method Names in Commands508445 +Node: The Print Command with Objective-C510136 +Node: OpenCL C510787 +Node: OpenCL C Datatypes511062 +Node: OpenCL C Expressions511437 +Node: OpenCL C Operators511794 +Node: Fortran512026 +Node: Fortran Operators512747 +Node: Fortran Defaults513603 +Node: Special Fortran Commands513988 +Node: Pascal514494 +Node: Modula-2515009 +Node: M2 Operators515984 +Node: Built-In Func/Proc518982 +Node: M2 Constants521842 +Node: M2 Types523443 +Node: M2 Defaults526661 +Node: Deviations527262 +Node: M2 Checks528363 +Node: M2 Scope529180 +Node: GDB/M2530204 +Node: Ada531117 +Node: Ada Mode Intro532227 +Node: Omissions from Ada534138 +Node: Additions to Ada538491 +Node: Stopping Before Main Program542418 +Node: Ada Exceptions542952 +Node: Ada Tasks544149 +Node: Ada Tasks and Core Files550553 +Node: Ravenscar Profile551471 +Node: Ada Glitches552540 +Node: Unsupported Languages555328 +Node: Symbols556018 +Node: Altering573359 +Node: Assignment574328 +Node: Jumping577434 +Node: Signaling579596 +Node: Returning580729 +Node: Calling584080 +Node: Patching587107 +Node: GDB Files588184 +Node: Files588904 +Ref: Shared Libraries602494 +Ref: Files-Footnote-1614124 +Node: Separate Debug Files614299 +Ref: debug-file-directory617403 +Node: MiniDebugInfo626048 +Node: Index Files628499 +Node: Symbol Errors630561 +Node: Data Files634177 +Node: Targets635133 +Node: Active Targets636613 +Node: Target Commands637687 +Ref: load641813 +Node: Byte Order642794 +Node: Remote Debugging643768 +Node: Connecting645030 +Node: File Transfer649965 +Node: Server650904 +Ref: Monitor Commands for gdbserver661125 +Ref: Server-Footnote-1665782 +Node: Remote Configuration665902 +Ref: set remotebreak666928 +Ref: set remote hardware-watchpoint-limit668391 +Ref: set remote hardware-breakpoint-limit668391 +Ref: set remote hardware-watchpoint-length-limit668617 +Ref: set remote exec-file669032 +Node: Remote Stub678521 +Node: Stub Contents681416 +Node: Bootstrapping683523 +Node: Debug Session687333 +Node: Configurations689374 +Node: Native690143 +Node: HP-UX690712 +Node: BSD libkvm Interface691001 +Node: SVR4 Process Information692072 +Node: DJGPP Native695876 +Node: Cygwin Native702435 +Node: Non-debug DLL Symbols706382 +Node: Hurd Native710938 +Node: Darwin716194 +Node: Embedded OS717455 +Node: VxWorks717931 +Node: VxWorks Connection720145 +Node: VxWorks Download721079 +Node: VxWorks Attach722814 +Node: Embedded Processors723211 +Node: ARM724344 +Node: M32R/D728467 +Node: M68K730169 +Node: MicroBlaze730461 +Node: MIPS Embedded731910 +Node: PowerPC Embedded736847 +Node: PA740613 +Node: Sparclet740896 +Node: Sparclet File742365 +Node: Sparclet Connection743245 +Node: Sparclet Download743723 +Node: Sparclet Execution744771 +Node: Sparclite745362 +Node: Z8000745734 +Node: AVR747116 +Node: CRIS747479 +Node: Super-H748457 +Node: Architectures749516 +Node: AArch64749953 +Node: i386750359 +Ref: i386-Footnote-1752591 +Node: Alpha752677 +Node: MIPS752810 +Node: HPPA756704 +Node: SPU757222 +Node: PowerPC759408 +Node: Nios II760143 +Node: Controlling GDB760532 +Node: Prompt761428 +Node: Editing763146 +Node: Command History764089 +Node: Screen Size767620 +Node: Numbers769554 +Node: ABI771525 +Node: Auto-loading774698 +Ref: set auto-load off776073 +Ref: show auto-load776709 +Ref: info auto-load777488 +Node: Init File in the Current Directory780157 +Ref: set auto-load local-gdbinit780732 +Ref: show auto-load local-gdbinit780914 +Ref: info auto-load local-gdbinit781078 +Node: libthread_db.so.1 file781226 +Ref: set auto-load libthread-db782165 +Ref: show auto-load libthread-db782296 +Ref: info auto-load libthread-db782433 +Node: Auto-loading safe path782617 +Ref: set auto-load safe-path783923 +Ref: show auto-load safe-path784662 +Ref: add-auto-load-safe-path784785 +Node: Auto-loading verbose mode787679 +Ref: set debug auto-load788842 +Ref: show debug auto-load788943 +Node: Messages/Warnings789065 +Ref: confirmation requests790499 +Node: Debugging Output791703 +Node: Other Misc Settings800180 +Node: Extending GDB801204 +Node: Sequences802927 +Node: Define803588 +Node: Hooks807386 +Node: Command Files809751 +Node: Output814824 +Node: Auto-loading sequences819788 +Ref: set auto-load gdb-scripts820283 +Ref: show auto-load gdb-scripts820407 +Ref: info auto-load gdb-scripts820537 +Node: Python820768 +Node: Python Commands821959 +Node: Python API824287 +Node: Basic Python826594 +Ref: prompt_hook835194 +Node: Exception Handling835792 +Node: Values From Inferior838288 +Node: Types In Python850286 +Node: Pretty Printing API859508 +Node: Selecting Pretty-Printers863404 +Node: Writing a Pretty-Printer865737 +Node: Type Printing API871059 +Node: Frame Filter API873657 +Node: Frame Decorator API880938 +Ref: frame_args884522 +Node: Writing a Frame Filter887852 +Node: Inferiors In Python899319 +Node: Events In Python902203 +Node: Threads In Python907382 +Node: Commands In Python909822 +Node: Parameters In Python919228 +Node: Functions In Python924688 +Node: Progspaces In Python926905 +Node: Objfiles In Python928589 +Node: Frames In Python930848 +Node: Blocks In Python937015 +Node: Symbols In Python941377 +Node: Symbol Tables In Python948585 +Node: Line Tables In Python951510 +Node: Breakpoints In Python954347 +Node: Finish Breakpoints in Python962261 +Node: Lazy Strings In Python964367 +Node: Architectures In Python966601 +Node: Python Auto-loading968790 +Ref: set auto-load python-scripts969419 +Ref: show auto-load python-scripts969519 +Ref: info auto-load python-scripts969625 +Node: Python modules970650 +Node: gdb.printing971036 +Node: gdb.types972450 +Node: gdb.prompt975475 +Node: Auto-loading extensions977124 +Node: objfile-gdbdotext file978302 +Ref: set auto-load scripts-directory979709 +Ref: with-auto-load-dir980085 +Ref: show auto-load scripts-directory980903 +Node: dotdebug_gdb_scripts section981233 +Node: Which flavor to choose?983025 +Node: Aliases984846 +Node: Interpreters987706 +Node: TUI989804 +Node: TUI Overview990748 +Node: TUI Keys993181 +Node: TUI Single Key Mode995485 +Node: TUI Commands996360 +Node: TUI Configuration998744 +Node: Emacs1000050 +Node: GDB/MI1005487 +Node: GDB/MI General Design1007461 +Node: Context management1009981 +Node: Asynchronous and non-stop modes1013809 +Node: Thread groups1015800 +Node: GDB/MI Command Syntax1018078 +Node: GDB/MI Input Syntax1018321 +Node: GDB/MI Output Syntax1019871 +Node: GDB/MI Compatibility with CLI1023441 +Node: GDB/MI Development and Front Ends1024178 +Node: GDB/MI Output Records1025832 +Node: GDB/MI Result Records1026238 +Node: GDB/MI Stream Records1027588 +Node: GDB/MI Async Records1028853 +Node: GDB/MI Breakpoint Information1038468 +Node: GDB/MI Frame Information1042419 +Node: GDB/MI Thread Information1043505 +Node: GDB/MI Ada Exception Information1044485 +Node: GDB/MI Simple Examples1044908 +Node: GDB/MI Command Description Format1047116 +Node: GDB/MI Breakpoint Commands1047996 +Node: GDB/MI Catchpoint Commands1067842 +Node: Shared Library GDB/MI Catchpoint Commands1068210 +Node: Ada Exception GDB/MI Catchpoint Commands1069868 +Node: GDB/MI Program Context1072272 +Node: GDB/MI Thread Commands1076540 +Node: GDB/MI Ada Tasking Commands1080496 +Node: GDB/MI Program Execution1082749 +Node: GDB/MI Stack Manipulation1094783 +Ref: -stack-list-arguments1096682 +Ref: -stack-list-frames1100387 +Ref: -stack-list-locals1104250 +Ref: -stack-list-variables1105740 +Node: GDB/MI Variable Objects1107274 +Ref: -var-set-format1117232 +Ref: -var-list-children1118350 +Ref: -var-update1127142 +Ref: -var-set-frozen1130140 +Ref: -var-set-update-range1130937 +Ref: -var-set-visualizer1131466 +Node: GDB/MI Data Manipulation1132956 +Node: GDB/MI Tracepoint Commands1152494 +Node: GDB/MI Symbol Query1164079 +Node: GDB/MI File Commands1164768 +Node: GDB/MI Target Manipulation1168063 +Node: GDB/MI File Transfer Commands1174278 +Node: GDB/MI Ada Exceptions Commands1175601 +Node: GDB/MI Support Commands1176954 +Node: GDB/MI Miscellaneous Commands1181527 +Ref: -interpreter-exec1191551 +Node: Annotations1193891 +Node: Annotations Overview1194810 +Node: Server Prefix1197273 +Node: Prompting1198007 +Node: Errors1199524 +Node: Invalidation1200420 +Node: Annotations for Running1200899 +Node: Source Annotations1202419 +Node: JIT Interface1203344 +Node: Declarations1205143 +Node: Registering Code1206530 +Node: Unregistering Code1207502 +Node: Custom Debug Info1208129 +Node: Using JIT Debug Info Readers1209425 +Node: Writing JIT Debug Info Readers1210439 +Node: In-Process Agent1212634 +Ref: Control Agent1214577 +Node: In-Process Agent Protocol1215444 +Node: IPA Protocol Objects1216235 +Ref: agent expression object1217233 +Ref: tracepoint action object1217438 +Ref: tracepoint object1217518 +Node: IPA Protocol Commands1220094 +Node: GDB Bugs1221546 +Node: Bug Criteria1222278 +Node: Bug Reporting1223155 +Node: Command Line Editing1230984 +Node: Introduction and Notation1231636 +Node: Readline Interaction1233257 +Node: Readline Bare Essentials1234446 +Node: Readline Movement Commands1236227 +Node: Readline Killing Commands1237185 +Node: Readline Arguments1239101 +Node: Searching1240143 +Node: Readline Init File1242293 +Node: Readline Init File Syntax1243444 +Node: Conditional Init Constructs1258543 +Node: Sample Init File1261066 +Node: Bindable Readline Commands1264180 +Node: Commands For Moving1265232 +Node: Commands For History1266090 +Node: Commands For Text1269485 +Node: Commands For Killing1272208 +Node: Numeric Arguments1274348 +Node: Commands For Completion1275484 +Node: Keyboard Macros1277450 +Node: Miscellaneous Commands1278018 +Node: Readline vi Mode1281866 +Node: Using History Interactively1282776 +Node: History Interaction1283291 +Node: Event Designators1284713 +Node: Word Designators1285850 +Node: Modifiers1287485 +Node: In Memoriam1288706 +Node: Formatting Documentation1289589 +Ref: Formatting Documentation-Footnote-11292909 +Node: Installing GDB1292977 +Node: Requirements1293549 +Ref: Expat1294118 +Node: Running Configure1296685 +Node: Separate Objdir1300254 +Node: Config Names1303149 +Node: Configure Options1304598 +Node: System-wide configuration1306969 +Node: System-wide Configuration Scripts1308929 +Node: Maintenance Commands1310113 +Ref: maint info breakpoints1311768 +Node: Remote Protocol1327695 +Node: Overview1328349 +Ref: Binary Data1330894 +Node: Packets1333419 +Ref: thread-id syntax1334319 +Ref: extended mode1335764 +Ref: bc1337488 +Ref: bs1337698 +Ref: read registers packet1339303 +Ref: cycle step packet1341236 +Ref: write register packet1343113 +Ref: step with signal packet1344110 +Ref: vCont packet1345566 +Ref: X packet1351378 +Ref: insert breakpoint or watchpoint packet1351665 +Node: Stop Reply Packets1355707 +Node: General Query Packets1360451 +Ref: QNonStop1370675 +Ref: QPassSignals1371302 +Ref: QProgramSignals1372474 +Ref: qSearch memory1374954 +Ref: QStartNoAckMode1375453 +Ref: qSupported1375984 +Ref: multiprocess extensions1388682 +Ref: install tracepoint in tracing1390712 +Ref: qXfer read1394072 +Ref: qXfer auxiliary vector read1394567 +Ref: qXfer btrace read1394915 +Ref: qXfer target description read1395538 +Ref: qXfer library list read1395972 +Ref: qXfer svr4 library list read1396628 +Ref: qXfer memory map read1398481 +Ref: qXfer sdata read1398868 +Ref: qXfer siginfo read1399334 +Ref: qXfer spu read1399731 +Ref: qXfer threads read1400255 +Ref: qXfer traceframe info read1400658 +Ref: qXfer unwind info block1401076 +Ref: qXfer fdpic loadmap read1401310 +Ref: qXfer osdata read1401726 +Ref: qXfer write1402933 +Ref: qXfer siginfo write1403486 +Ref: qXfer spu write1403883 +Ref: General Query Packets-Footnote-11406416 +Node: Architecture-Specific Protocol Details1406743 +Node: ARM-Specific Protocol Details1407252 +Node: ARM Breakpoint Kinds1407500 +Node: MIPS-Specific Protocol Details1407831 +Node: MIPS Register packet Format1408114 +Node: MIPS Breakpoint Kinds1409041 +Node: Tracepoint Packets1409459 +Ref: QTEnable1418454 +Ref: QTDisable1418650 +Ref: qTfSTM1424189 +Ref: qTsSTM1424189 +Ref: qTSTMat1425228 +Ref: QTBuffer-size1426375 +Node: Host I/O Packets1428344 +Node: Interrupts1432954 +Node: Notification Packets1434857 +Node: Remote Non-Stop1440266 +Node: Packet Acknowledgment1442556 +Node: Examples1444671 +Node: File-I/O Remote Protocol Extension1445265 +Node: File-I/O Overview1445727 +Node: Protocol Basics1447926 +Node: The F Request Packet1450155 +Node: The F Reply Packet1451056 +Node: The Ctrl-C Message1451974 +Node: Console I/O1453600 +Node: List of Supported Calls1454816 +Node: open1455178 +Node: close1457686 +Node: read1458069 +Node: write1458678 +Node: lseek1459449 +Node: rename1460333 +Node: unlink1461740 +Node: stat/fstat1462687 +Node: gettimeofday1463580 +Node: isatty1464016 +Node: system1464612 +Node: Protocol-specific Representation of Datatypes1466154 +Node: Integral Datatypes1466531 +Node: Pointer Values1467338 +Node: Memory Transfer1468042 +Node: struct stat1468662 +Node: struct timeval1470864 +Node: Constants1471381 +Node: Open Flags1471830 +Node: mode_t Values1472171 +Node: Errno Values1472663 +Node: Lseek Flags1473473 +Node: Limits1473658 +Node: File-I/O Examples1474018 +Node: Library List Format1475106 +Node: Library List Format for SVR4 Targets1477888 +Node: Memory Map Format1480355 +Node: Thread List Format1482930 +Node: Traceframe Info Format1483748 +Node: Branch Trace Format1485434 +Node: Agent Expressions1486779 +Node: General Bytecode Design1489600 +Node: Bytecode Descriptions1494394 +Node: Using Agent Expressions1507825 +Node: Varying Target Capabilities1509802 +Node: Rationale1510963 +Node: Target Descriptions1518352 +Node: Retrieving Descriptions1520226 +Node: Target Description Format1521311 +Node: Predefined Target Types1530359 +Node: Standard Target Features1531743 +Node: AArch64 Features1533607 +Node: ARM Features1534030 +Node: i386 Features1535548 +Node: MIPS Features1536905 +Node: M68K Features1538090 +Node: Nios II Features1538753 +Node: PowerPC Features1539151 +Node: S/390 and System z Features1540474 +Node: TIC6x Features1541939 +Node: Operating System Information1542499 +Node: Process list1543334 +Node: Trace File Format1544397 +Node: Index Section Format1546390 +Node: Man Pages1554360 +Node: gdb man1554766 +Node: gdbserver man1560802 +Node: gcore man1567807 +Node: gdbinit man1568464 +Node: Copying1569347 +Node: GNU Free Documentation License1606907 +Node: Concept Index1632053 +Node: Command and Variable Index1755064 + +End Tag Table diff --git a/util/X86MAC64/share/info/gdb.info-1 b/util/X86MAC64/share/info/gdb.info-1 new file mode 100644 index 0000000000..357548f3d2 --- /dev/null +++ b/util/X86MAC64/share/info/gdb.info-1 @@ -0,0 +1,7127 @@ +This is gdb.info, produced by makeinfo version 5.1 from gdb.texinfo. + +Copyright (C) 1988-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 7.7.1. + + Copyright (C) 1988-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir) + +Debugging with GDB +****************** + +This file describes GDB, the GNU symbolic debugger. + + This is the Tenth Edition, for GDB (GDB) Version 7.7.1. + + Copyright (C) 1988-2014 Free Software Foundation, Inc. + + This edition of the GDB manual is dedicated to the memory of Fred +Fish. Fred was a long-standing contributor to GDB and to Free software +in general. We will miss him. + +* Menu: + +* Summary:: Summary of GDB +* Sample Session:: A sample GDB session + +* Invocation:: Getting in and out of GDB +* Commands:: GDB commands +* Running:: Running programs under GDB +* Stopping:: Stopping and continuing +* Reverse Execution:: Running programs backward +* Process Record and Replay:: Recording inferior's execution and replaying it +* Stack:: Examining the stack +* Source:: Examining source files +* Data:: Examining data +* Optimized Code:: Debugging optimized code +* Macros:: Preprocessor Macros +* Tracepoints:: Debugging remote targets non-intrusively +* Overlays:: Debugging programs that use overlays + +* Languages:: Using GDB with different languages + +* Symbols:: Examining the symbol table +* Altering:: Altering execution +* GDB Files:: GDB files +* Targets:: Specifying a debugging target +* Remote Debugging:: Debugging remote programs +* Configurations:: Configuration-specific information +* Controlling GDB:: Controlling GDB +* Extending GDB:: Extending GDB +* Interpreters:: Command Interpreters +* TUI:: GDB Text User Interface +* Emacs:: Using GDB under GNU Emacs +* GDB/MI:: GDB's Machine Interface. +* Annotations:: GDB's annotation interface. +* JIT Interface:: Using the JIT debugging interface. +* In-Process Agent:: In-Process Agent + +* GDB Bugs:: Reporting bugs in GDB + +* Command Line Editing:: Command Line Editing +* Using History Interactively:: Using History Interactively +* In Memoriam:: In Memoriam +* Formatting Documentation:: How to format and print GDB documentation +* Installing GDB:: Installing GDB +* Maintenance Commands:: Maintenance Commands +* Remote Protocol:: GDB Remote Serial Protocol +* Agent Expressions:: The GDB Agent Expression Mechanism +* Target Descriptions:: How targets can describe themselves to + GDB +* Operating System Information:: Getting additional information from + the operating system +* Trace File Format:: GDB trace file format +* Index Section Format:: .gdb_index section format +* Man Pages:: Manual pages +* Copying:: GNU General Public License says + how you can copy and share GDB +* GNU Free Documentation License:: The license for this documentation +* Concept Index:: Index of GDB concepts +* Command and Variable Index:: Index of GDB commands, variables, + functions, and Python data types + + +File: gdb.info, Node: Summary, Next: Sample Session, Up: Top + +Summary of GDB +************** + +The purpose of a debugger such as GDB is to allow you to see what is +going on "inside" another program while it executes--or what another +program was doing at the moment it crashed. + + GDB can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: + + * Start your program, specifying anything that might affect its + behavior. + + * Make your program stop on specified conditions. + + * Examine what has happened, when your program has stopped. + + * Change things in your program, so you can experiment with + correcting the effects of one bug and go on to learn about another. + + You can use GDB to debug programs written in C and C++. For more +information, see *note Supported Languages: Supported Languages. For +more information, see *note C and C++: C. + + Support for D is partial. For information on D, see *note D: D. + + Support for Modula-2 is partial. For information on Modula-2, see +*note Modula-2: Modula-2. + + Support for OpenCL C is partial. For information on OpenCL C, see +*note OpenCL C: OpenCL C. + + Debugging Pascal programs which use sets, subranges, file variables, +or nested functions does not currently work. GDB does not support +entering expressions, printing values, or similar features using Pascal +syntax. + + GDB can be used to debug programs written in Fortran, although it may +be necessary to refer to some variables with a trailing underscore. + + GDB can be used to debug programs written in Objective-C, using +either the Apple/NeXT or the GNU Objective-C runtime. + +* Menu: + +* Free Software:: Freely redistributable software +* Free Documentation:: Free Software Needs Free Documentation +* Contributors:: Contributors to GDB + + +File: gdb.info, Node: Free Software, Next: Free Documentation, Up: Summary + +Free Software +============= + +GDB is "free software", protected by the GNU General Public License +(GPL). The GPL gives you the freedom to copy or adapt a licensed +program--but every person getting a copy also gets with it the freedom +to modify that copy (which means that they must get access to the source +code), and the freedom to distribute further copies. Typical software +companies use copyrights to limit your freedoms; the Free Software +Foundation uses the GPL to preserve these freedoms. + + Fundamentally, the General Public License is a license which says +that you have these freedoms and that you cannot take these freedoms +away from anyone else. + + +File: gdb.info, Node: Free Documentation, Next: Contributors, Prev: Free Software, Up: Summary + +Free Software Needs Free Documentation +====================================== + +The biggest deficiency in the free software community today is not in +the software--it is the lack of good free documentation that we can +include with the free software. Many of our most important programs do +not come with free reference manuals and free introductory texts. +Documentation is an essential part of any software package; when an +important free software package does not come with a free manual and a +free tutorial, that is a major gap. We have many such gaps today. + + Consider Perl, for instance. The tutorial manuals that people +normally use are non-free. How did this come about? Because the +authors of those manuals published them with restrictive terms--no +copying, no modification, source files not available--which exclude them +from the free software world. + + That wasn't the first time this sort of thing happened, and it was +far from the last. Many times we have heard a GNU user eagerly describe +a manual that he is writing, his intended contribution to the community, +only to learn that he had ruined everything by signing a publication +contract to make it non-free. + + Free documentation, like free software, is a matter of freedom, not +price. The problem with the non-free manual is not that publishers +charge a price for printed copies--that in itself is fine. (The Free +Software Foundation sells printed copies of manuals, too.) The problem +is the restrictions on the use of the manual. Free manuals are +available in source code form, and give you permission to copy and +modify. Non-free manuals do not allow this. + + The criteria of freedom for a free manual are roughly the same as for +free software. Redistribution (including the normal kinds of commercial +redistribution) must be permitted, so that the manual can accompany +every copy of the program, both on-line and on paper. + + Permission for modification of the technical content is crucial too. +When people modify the software, adding or changing features, if they +are conscientious they will change the manual too--so they can provide +accurate and clear documentation for the modified program. A manual +that leaves you no choice but to write a new manual to document a +changed version of the program is not really available to our community. + + Some kinds of limits on the way modification is handled are +acceptable. For example, requirements to preserve the original author's +copyright notice, the distribution terms, or the list of authors, are +ok. It is also no problem to require modified versions to include +notice that they were modified. Even entire sections that may not be +deleted or changed are acceptable, as long as they deal with +nontechnical topics (like this one). These kinds of restrictions are +acceptable because they don't obstruct the community's normal use of the +manual. + + However, it must be possible to modify all the _technical_ content of +the manual, and then distribute the result in all the usual media, +through all the usual channels. Otherwise, the restrictions obstruct +the use of the manual, it is not free, and we need another manual to +replace it. + + Please spread the word about this issue. Our community continues to +lose manuals to proprietary publishing. If we spread the word that free +software needs free reference manuals and free tutorials, perhaps the +next person who wants to contribute by writing documentation will +realize, before it is too late, that only free manuals contribute to the +free software community. + + If you are writing documentation, please insist on publishing it +under the GNU Free Documentation License or another free documentation +license. Remember that this decision requires your approval--you don't +have to let the publisher decide. Some commercial publishers will use a +free license if you insist, but they will not propose the option; it is +up to you to raise the issue and say firmly that this is what you want. +If the publisher you are dealing with refuses, please try other +publishers. If you're not sure whether a proposed license is free, +write to . + + You can encourage commercial publishers to sell more free, copylefted +manuals and tutorials by buying them, and particularly by buying copies +from the publishers that paid for their writing or for major +improvements. Meanwhile, try to avoid buying non-free documentation at +all. Check the distribution terms of a manual before you buy it, and +insist that whoever seeks your business must respect your freedom. +Check the history of the book, and try to reward the publishers that +have paid or pay the authors to work on it. + + The Free Software Foundation maintains a list of free documentation +published by other publishers, at +. + + +File: gdb.info, Node: Contributors, Prev: Free Documentation, Up: Summary + +Contributors to GDB +=================== + +Richard Stallman was the original author of GDB, and of many other GNU +programs. Many others have contributed to its development. This +section attempts to credit major contributors. One of the virtues of +free software is that everyone is free to contribute to it; with regret, +we cannot actually acknowledge everyone here. The file 'ChangeLog' in +the GDB distribution approximates a blow-by-blow account. + + Changes much prior to version 2.0 are lost in the mists of time. + + _Plea:_ Additions to this section are particularly welcome. If you + or your friends (or enemies, to be evenhanded) have been unfairly + omitted from this list, we would like to add your names! + + So that they may not regard their many labors as thankless, we +particularly thank those who shepherded GDB through major releases: +Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim +Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs (release +4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); +Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); +John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon +(releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 3.1, and +3.0). + + Richard Stallman, assisted at various times by Peter TerMaat, Chris +Hanson, and Richard Mlynarik, handled releases through 2.8. + + Michael Tiemann is the author of most of the GNU C++ support in GDB, +with significant additional contributions from Per Bothner and Daniel +Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ was +by Peter TerMaat (who also did much general update work leading to +release 3.0). + + GDB uses the BFD subroutine library to examine multiple object-file +formats; BFD was a joint project of David V. Henkel-Wallace, Rich +Pixley, Steve Chamberlain, and John Gilmore. + + David Johnson wrote the original COFF support; Pace Willison did the +original support for encapsulated COFF. + + Brent Benson of Harris Computer Systems contributed DWARF 2 support. + + Adam de Boor and Bradley Davis contributed the ISI Optimum V support. +Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS +support. Jean-Daniel Fekete contributed Sun 386i support. Chris Hanson +improved the HP9000 support. Noboyuki Hikichi and Tomoyuki Hasei +contributed Sony/News OS 3 support. David Johnson contributed Encore +Umax support. Jyrki Kuoppala contributed Altos 3068 support. Jeff Law +contributed HP PA and SOM support. Keith Packard contributed NS32K +support. Doug Rabson contributed Acorn Risc Machine support. Bob Rusk +contributed Harris Nighthawk CX-UX support. Chris Smith contributed +Convex support (and Fortran debugging). Jonathan Stone contributed +Pyramid support. Michael Tiemann contributed SPARC support. Tim Tucker +contributed support for the Gould NP1 and Gould Powernode. Pace +Willison contributed Intel 386 support. Jay Vosburgh contributed +Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. + + Andreas Schwab contributed M68K GNU/Linux support. + + Rich Schaefer and Peter Schauer helped with support of SunOS shared +libraries. + + Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about +several machine instruction sets. + + Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped +develop remote debugging. Intel Corporation, Wind River Systems, AMD, +and ARM contributed remote debugging modules for the i960, VxWorks, A29K +UDI, and RDI targets, respectively. + + Brian Fox is the author of the readline libraries providing +command-line editing and command history. + + Andrew Beers of SUNY Buffalo wrote the language-switching code, the +Modula-2 support, and contributed the Languages chapter of this manual. + + Fred Fish wrote most of the support for Unix System Vr4. He also +enhanced the command-completion support to cover C++ overloaded symbols. + + Hitachi America (now Renesas America), Ltd. sponsored the support +for H8/300, H8/500, and Super-H processors. + + NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx +processors. + + Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and +M32R/D processors. + + Toshiba sponsored the support for the TX39 Mips processor. + + Matsushita sponsored the support for the MN10200 and MN10300 +processors. + + Fujitsu sponsored the support for SPARClite and FR30 processors. + + Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware +watchpoints. + + Michael Snyder added support for tracepoints. + + Stu Grossman wrote gdbserver. + + Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly +innumerable bug fixes and cleanups throughout GDB. + + The following people at the Hewlett-Packard Company contributed +support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 +(narrow mode), HP's implementation of kernel threads, HP's aC++ +compiler, and the Text User Interface (nee Terminal User Interface): Ben +Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, Satish +Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase provided +HP-specific information in this manual. + + DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert +Hoehne made significant contributions to the DJGPP port. + + Cygnus Solutions has sponsored GDB maintenance and much of its +development since 1991. Cygnus engineers who have worked on GDB +fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin +Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim +Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, +Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek +Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In +addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, +JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug +Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff +Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, +Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin +Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela +Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David +Zuhn have made contributions both large and small. + + Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for +Cygnus Solutions, implemented the original GDB/MI interface. + + Jim Blandy added support for preprocessor macros, while working for +Red Hat. + + Andrew Cagney designed GDB's architecture vector. Many people +including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, +Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, +Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna +Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration +of old architectures to this new framework. + + Andrew Cagney completely re-designed and re-implemented GDB's +unwinder framework, this consisting of a fresh new design featuring +frame IDs, independent frame sniffers, and the sentinel frame. Mark +Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind +unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad +unwinders. The architecture-specific changes, each involving a complete +rewrite of the architecture's frame code, were carried out by Jim +Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane Carrez, +Randolph Chung, Orjan Friberg, Richard Henderson, Daniel Jacobowitz, +Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei Sakamoto, Yoshinori +Sato, Michael Snyder, Corinna Vinschen, and Ulrich Weigand. + + Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from +Tensilica, Inc. contributed support for Xtensa processors. Others who +have worked on the Xtensa port of GDB in the past include Steve Tjiang, +John Newlin, and Scott Foehner. + + Michael Eager and staff of Xilinx, Inc., contributed support for the +Xilinx MicroBlaze architecture. + + +File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top + +1 A Sample GDB Session +********************** + +You can use this manual at your leisure to read all about GDB. However, +a handful of commands are enough to get started using the debugger. +This chapter illustrates those commands. + + One of the preliminary versions of GNU 'm4' (a generic macro +processor) exhibits the following bug: sometimes, when we change its +quote strings from the default, the commands used to capture one macro +definition within another stop working. In the following short 'm4' +session, we define a macro 'foo' which expands to '0000'; we then use +the 'm4' built-in 'defn' to define 'bar' as the same thing. However, +when we change the open quote string to '' and the close quote +string to '', the same procedure fails to define a new synonym +'baz': + + $ cd gnu/m4 + $ ./m4 + define(foo,0000) + + foo + 0000 + define(bar,defn('foo')) + + bar + 0000 + changequote(,) + + define(baz,defn(foo)) + baz + Ctrl-d + m4: End of input: 0: fatal error: EOF in string + +Let us use GDB to try to see what is going on. + + $ gdb m4 + GDB is free software and you are welcome to distribute copies + of it under certain conditions; type "show copying" to see + the conditions. + There is absolutely no warranty for GDB; type "show warranty" + for details. + + GDB 7.7.1, Copyright 1999 Free Software Foundation, Inc... + (gdb) + +GDB reads only enough symbol data to know where to find the rest when +needed; as a result, the first prompt comes up very quickly. We now +tell GDB to use a narrower display width than usual, so that examples +fit in this manual. + + (gdb) set width 70 + +We need to see how the 'm4' built-in 'changequote' works. Having looked +at the source, we know the relevant subroutine is 'm4_changequote', so +we set a breakpoint there with the GDB 'break' command. + + (gdb) break m4_changequote + Breakpoint 1 at 0x62f4: file builtin.c, line 879. + +Using the 'run' command, we start 'm4' running under GDB control; as +long as control does not reach the 'm4_changequote' subroutine, the +program runs as usual: + + (gdb) run + Starting program: /work/Editorial/gdb/gnu/m4/m4 + define(foo,0000) + + foo + 0000 + +To trigger the breakpoint, we call 'changequote'. GDB suspends +execution of 'm4', displaying information about the context where it +stops. + + changequote(,) + + Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) + at builtin.c:879 + 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) + +Now we use the command 'n' ('next') to advance execution to the next +line of the current function. + + (gdb) n + 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ + : nil, + +'set_quotes' looks like a promising subroutine. We can go into it by +using the command 's' ('step') instead of 'next'. 'step' goes to the +next line to be executed in _any_ subroutine, so it steps into +'set_quotes'. + + (gdb) s + set_quotes (lq=0x34c78 "", rq=0x34c88 "") + at input.c:530 + 530 if (lquote != def_lquote) + +The display that shows the subroutine where 'm4' is now suspended (and +its arguments) is called a stack frame display. It shows a summary of +the stack. We can use the 'backtrace' command (which can also be +spelled 'bt'), to see where we are in the stack as a whole: the +'backtrace' command displays a stack frame for each active subroutine. + + (gdb) bt + #0 set_quotes (lq=0x34c78 "", rq=0x34c88 "") + at input.c:530 + #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) + at builtin.c:882 + #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 + #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) + at macro.c:71 + #4 0x79dc in expand_input () at macro.c:40 + #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 + +We step through a few more lines to see what happens. The first two +times, we can use 's'; the next two times we use 'n' to avoid falling +into the 'xstrdup' subroutine. + + (gdb) s + 0x3b5c 532 if (rquote != def_rquote) + (gdb) s + 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ + def_lquote : xstrdup(lq); + (gdb) n + 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ + : xstrdup(rq); + (gdb) n + 538 len_lquote = strlen(rquote); + +The last line displayed looks a little odd; we can examine the variables +'lquote' and 'rquote' to see if they are in fact the new left and right +quotes we specified. We use the command 'p' ('print') to see their +values. + + (gdb) p lquote + $1 = 0x35d40 "" + (gdb) p rquote + $2 = 0x35d50 "" + +'lquote' and 'rquote' are indeed the new left and right quotes. To look +at some context, we can display ten lines of source surrounding the +current line with the 'l' ('list') command. + + (gdb) l + 533 xfree(rquote); + 534 + 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ + : xstrdup (lq); + 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ + : xstrdup (rq); + 537 + 538 len_lquote = strlen(rquote); + 539 len_rquote = strlen(lquote); + 540 } + 541 + 542 void + +Let us step past the two lines that set 'len_lquote' and 'len_rquote', +and then examine the values of those variables. + + (gdb) n + 539 len_rquote = strlen(lquote); + (gdb) n + 540 } + (gdb) p len_lquote + $3 = 9 + (gdb) p len_rquote + $4 = 7 + +That certainly looks wrong, assuming 'len_lquote' and 'len_rquote' are +meant to be the lengths of 'lquote' and 'rquote' respectively. We can +set them to better values using the 'p' command, since it can print the +value of any expression--and that expression can include subroutine +calls and assignments. + + (gdb) p len_lquote=strlen(lquote) + $5 = 7 + (gdb) p len_rquote=strlen(rquote) + $6 = 9 + +Is that enough to fix the problem of using the new quotes with the 'm4' +built-in 'defn'? We can allow 'm4' to continue executing with the 'c' +('continue') command, and then try the example that caused trouble +initially: + + (gdb) c + Continuing. + + define(baz,defn(foo)) + + baz + 0000 + +Success! The new quotes now work just as well as the default ones. The +problem seems to have been just the two typos defining the wrong +lengths. We allow 'm4' exit by giving it an EOF as input: + + Ctrl-d + Program exited normally. + +The message 'Program exited normally.' is from GDB; it indicates 'm4' +has finished executing. We can end our GDB session with the GDB 'quit' +command. + + (gdb) quit + + +File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top + +2 Getting In and Out of GDB +*************************** + +This chapter discusses how to start GDB, and how to get out of it. The +essentials are: + * type 'gdb' to start GDB. + * type 'quit' or 'Ctrl-d' to exit. + +* Menu: + +* Invoking GDB:: How to start GDB +* Quitting GDB:: How to quit GDB +* Shell Commands:: How to use shell commands inside GDB +* Logging Output:: How to log GDB's output to a file + + +File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation + +2.1 Invoking GDB +================ + +Invoke GDB by running the program 'gdb'. Once started, GDB reads +commands from the terminal until you tell it to exit. + + You can also run 'gdb' with a variety of arguments and options, to +specify more of your debugging environment at the outset. + + The command-line options described here are designed to cover a +variety of situations; in some environments, some of these options may +effectively be unavailable. + + The most usual way to start GDB is with one argument, specifying an +executable program: + + gdb PROGRAM + +You can also start with both an executable program and a core file +specified: + + gdb PROGRAM CORE + + You can, instead, specify a process ID as a second argument, if you +want to debug a running process: + + gdb PROGRAM 1234 + +would attach GDB to process '1234' (unless you also have a file named +'1234'; GDB does check for a core file first). + + Taking advantage of the second command-line argument requires a +fairly complete operating system; when you use GDB as a remote debugger +attached to a bare board, there may not be any notion of "process", and +there is often no way to get a core dump. GDB will warn you if it is +unable to attach or to read core dumps. + + You can optionally have 'gdb' pass any arguments after the executable +file to the inferior using '--args'. This option stops option +processing. + gdb --args gcc -O2 -c foo.c + This will cause 'gdb' to debug 'gcc', and to set 'gcc''s command-line +arguments (*note Arguments::) to '-O2 -c foo.c'. + + You can run 'gdb' without printing the front material, which +describes GDB's non-warranty, by specifying '-silent': + + gdb -silent + +You can further control how GDB starts up by using command-line options. +GDB itself can remind you of the options available. + +Type + + gdb -help + +to display all available options and briefly describe their use ('gdb +-h' is a shorter equivalent). + + All options and command line arguments you give are processed in +sequential order. The order makes a difference when the '-x' option is +used. + +* Menu: + +* File Options:: Choosing files +* Mode Options:: Choosing modes +* Startup:: What GDB does during startup + + +File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB + +2.1.1 Choosing Files +-------------------- + +When GDB starts, it reads any arguments other than options as specifying +an executable file and core file (or process ID). This is the same as if +the arguments were specified by the '-se' and '-c' (or '-p') options +respectively. (GDB reads the first argument that does not have an +associated option flag as equivalent to the '-se' option followed by +that argument; and the second argument that does not have an associated +option flag, if any, as equivalent to the '-c'/'-p' option followed by +that argument.) If the second argument begins with a decimal digit, GDB +will first attempt to attach to it as a process, and if that fails, +attempt to open it as a corefile. If you have a corefile whose name +begins with a digit, you can prevent GDB from treating it as a pid by +prefixing it with './', e.g. './12345'. + + If GDB has not been configured to included core file support, such as +for most embedded targets, then it will complain about a second argument +and ignore it. + + Many options have both long and short forms; both are shown in the +following list. GDB also recognizes the long forms if you truncate +them, so long as enough of the option is present to be unambiguous. (If +you prefer, you can flag option arguments with '--' rather than '-', +though we illustrate the more usual convention.) + +'-symbols FILE' +'-s FILE' + Read symbol table from file FILE. + +'-exec FILE' +'-e FILE' + Use file FILE as the executable file to execute when appropriate, + and for examining pure data in conjunction with a core dump. + +'-se FILE' + Read symbol table from file FILE and use it as the executable file. + +'-core FILE' +'-c FILE' + Use file FILE as a core dump to examine. + +'-pid NUMBER' +'-p NUMBER' + Connect to process ID NUMBER, as with the 'attach' command. + +'-command FILE' +'-x FILE' + Execute commands from file FILE. The contents of this file is + evaluated exactly as the 'source' command would. *Note Command + files: Command Files. + +'-eval-command COMMAND' +'-ex COMMAND' + Execute a single GDB command. + + This option may be used multiple times to call multiple commands. + It may also be interleaved with '-command' as required. + + gdb -ex 'target sim' -ex 'load' \ + -x setbreakpoints -ex 'run' a.out + +'-init-command FILE' +'-ix FILE' + Execute commands from file FILE before loading the inferior (but + after loading gdbinit files). *Note Startup::. + +'-init-eval-command COMMAND' +'-iex COMMAND' + Execute a single GDB command before loading the inferior (but after + loading gdbinit files). *Note Startup::. + +'-directory DIRECTORY' +'-d DIRECTORY' + Add DIRECTORY to the path to search for source and script files. + +'-r' +'-readnow' + Read each symbol file's entire symbol table immediately, rather + than the default, which is to read it incrementally as it is + needed. This makes startup slower, but makes future operations + faster. + + +File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB + +2.1.2 Choosing Modes +-------------------- + +You can run GDB in various alternative modes--for example, in batch mode +or quiet mode. + +'-nx' +'-n' + Do not execute commands found in any initialization file. There + are three init files, loaded in the following order: + + 'system.gdbinit' + This is the system-wide init file. Its location is specified + with the '--with-system-gdbinit' configure option (*note + System-wide configuration::). It is loaded first when GDB + starts, before command line options have been processed. + '~/.gdbinit' + This is the init file in your home directory. It is loaded + next, after 'system.gdbinit', and before command options have + been processed. + './.gdbinit' + This is the init file in the current directory. It is loaded + last, after command line options other than '-x' and '-ex' + have been processed. Command line options '-x' and '-ex' are + processed last, after './.gdbinit' has been loaded. + + For further documentation on startup processing, *Note Startup::. + For documentation on how to write command files, *Note Command + Files: Command Files. + +'-nh' + Do not execute commands found in '~/.gdbinit', the init file in + your home directory. *Note Startup::. + +'-quiet' +'-silent' +'-q' + "Quiet". Do not print the introductory and copyright messages. + These messages are also suppressed in batch mode. + +'-batch' + Run in batch mode. Exit with status '0' after processing all the + command files specified with '-x' (and all commands from + initialization files, if not inhibited with '-n'). Exit with + nonzero status if an error occurs in executing the GDB commands in + the command files. Batch mode also disables pagination, sets + unlimited terminal width and height *note Screen Size::, and acts + as if 'set confirm off' were in effect (*note Messages/Warnings::). + + Batch mode may be useful for running GDB as a filter, for example + to download and run a program on another computer; in order to make + this more useful, the message + + Program exited normally. + + (which is ordinarily issued whenever a program running under GDB + control terminates) is not issued when running in batch mode. + +'-batch-silent' + Run in batch mode exactly like '-batch', but totally silently. All + GDB output to 'stdout' is prevented ('stderr' is unaffected). This + is much quieter than '-silent' and would be useless for an + interactive session. + + This is particularly useful when using targets that give 'Loading + section' messages, for example. + + Note that targets that give their output via GDB, as opposed to + writing directly to 'stdout', will also be made silent. + +'-return-child-result' + The return code from GDB will be the return code from the child + process (the process being debugged), with the following + exceptions: + + * GDB exits abnormally. E.g., due to an incorrect argument or + an internal error. In this case the exit code is the same as + it would have been without '-return-child-result'. + * The user quits with an explicit value. E.g., 'quit 1'. + * The child process never runs, or is not allowed to terminate, + in which case the exit code will be -1. + + This option is useful in conjunction with '-batch' or + '-batch-silent', when GDB is being used as a remote program loader + or simulator interface. + +'-nowindows' +'-nw' + "No windows". If GDB comes with a graphical user interface (GUI) + built in, then this option tells GDB to only use the command-line + interface. If no GUI is available, this option has no effect. + +'-windows' +'-w' + If GDB includes a GUI, then this option requires it to be used if + possible. + +'-cd DIRECTORY' + Run GDB using DIRECTORY as its working directory, instead of the + current directory. + +'-data-directory DIRECTORY' + Run GDB using DIRECTORY as its data directory. The data directory + is where GDB searches for its auxiliary files. *Note Data Files::. + +'-fullname' +'-f' + GNU Emacs sets this option when it runs GDB as a subprocess. It + tells GDB to output the full file name and line number in a + standard, recognizable fashion each time a stack frame is displayed + (which includes each time your program stops). This recognizable + format looks like two '\032' characters, followed by the file name, + line number and character position separated by colons, and a + newline. The Emacs-to-GDB interface program uses the two '\032' + characters as a signal to display the source code for the frame. + +'-annotate LEVEL' + This option sets the "annotation level" inside GDB. Its effect is + identical to using 'set annotate LEVEL' (*note Annotations::). The + annotation LEVEL controls how much information GDB prints together + with its prompt, values of expressions, source lines, and other + types of output. Level 0 is the normal, level 1 is for use when + GDB is run as a subprocess of GNU Emacs, level 3 is the maximum + annotation suitable for programs that control GDB, and level 2 has + been deprecated. + + The annotation mechanism has largely been superseded by GDB/MI + (*note GDB/MI::). + +'--args' + Change interpretation of command line so that arguments following + the executable file are passed as command line arguments to the + inferior. This option stops option processing. + +'-baud BPS' +'-b BPS' + Set the line speed (baud rate or bits per second) of any serial + interface used by GDB for remote debugging. + +'-l TIMEOUT' + Set the timeout (in seconds) of any communication used by GDB for + remote debugging. + +'-tty DEVICE' +'-t DEVICE' + Run using DEVICE for your program's standard input and output. + +'-tui' + Activate the "Text User Interface" when starting. The Text User + Interface manages several text windows on the terminal, showing + source, assembly, registers and GDB command outputs (*note GDB Text + User Interface: TUI.). Do not use this option if you run GDB from + Emacs (*note Using GDB under GNU Emacs: Emacs.). + +'-interpreter INTERP' + Use the interpreter INTERP for interface with the controlling + program or device. This option is meant to be set by programs + which communicate with GDB using it as a back end. *Note Command + Interpreters: Interpreters. + + '--interpreter=mi' (or '--interpreter=mi2') causes GDB to use the + "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included + since GDB version 6.0. The previous GDB/MI interface, included in + GDB version 5.3 and selected with '--interpreter=mi1', is + deprecated. Earlier GDB/MI interfaces are no longer supported. + +'-write' + Open the executable and core files for both reading and writing. + This is equivalent to the 'set write on' command inside GDB (*note + Patching::). + +'-statistics' + This option causes GDB to print statistics about time and memory + usage after it completes each command and returns to the prompt. + +'-version' + This option causes GDB to print its version number and no-warranty + blurb, and exit. + +'-configuration' + This option causes GDB to print details about its build-time + configuration parameters, and then exit. These details can be + important when reporting GDB bugs (*note GDB Bugs::). + + +File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB + +2.1.3 What GDB Does During Startup +---------------------------------- + +Here's the description of what GDB does during session startup: + + 1. Sets up the command interpreter as specified by the command line + (*note interpreter: Mode Options.). + + 2. Reads the system-wide "init file" (if '--with-system-gdbinit' was + used when building GDB; *note System-wide configuration and + settings: System-wide configuration.) and executes all the commands + in that file. + + 3. Reads the init file (if any) in your home directory(1) and executes + all the commands in that file. + + 4. Executes commands and command files specified by the '-iex' and + '-ix' options in their specified order. Usually you should use the + '-ex' and '-x' options instead, but this way you can apply settings + before GDB init files get executed and before inferior gets loaded. + + 5. Processes command line options and operands. + + 6. Reads and executes the commands from init file (if any) in the + current working directory as long as 'set auto-load local-gdbinit' + is set to 'on' (*note Init File in the Current Directory::). This + is only done if the current directory is different from your home + directory. Thus, you can have more than one init file, one generic + in your home directory, and another, specific to the program you + are debugging, in the directory where you invoke GDB. + + 7. If the command line specified a program to debug, or a process to + attach to, or a core file, GDB loads any auto-loaded scripts + provided for the program or for its loaded shared libraries. *Note + Auto-loading::. + + If you wish to disable the auto-loading during startup, you must do + something like the following: + + $ gdb -iex "set auto-load python-scripts off" myprogram + + Option '-ex' does not work because the auto-loading is then turned + off too late. + + 8. Executes commands and command files specified by the '-ex' and '-x' + options in their specified order. *Note Command Files::, for more + details about GDB command files. + + 9. Reads the command history recorded in the "history file". *Note + Command History::, for more details about the command history and + the files where GDB records it. + + Init files use the same syntax as "command files" (*note Command +Files::) and are processed by GDB in the same way. The init file in +your home directory can set options (such as 'set complaints') that +affect subsequent processing of command line options and operands. Init +files are not executed if you use the '-nx' option (*note Choosing +Modes: Mode Options.). + + To display the list of init files loaded by gdb at startup, you can +use 'gdb --help'. + + The GDB init files are normally called '.gdbinit'. The DJGPP port of +GDB uses the name 'gdb.ini', due to the limitations of file names +imposed by DOS filesystems. The Windows port of GDB uses the standard +name, but if it finds a 'gdb.ini' file in your home directory, it warns +you about that and suggests to rename the file to the standard name. + + ---------- Footnotes ---------- + + (1) On DOS/Windows systems, the home directory is the one pointed to +by the 'HOME' environment variable. + + +File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation + +2.2 Quitting GDB +================ + +'quit [EXPRESSION]' +'q' + To exit GDB, use the 'quit' command (abbreviated 'q'), or type an + end-of-file character (usually 'Ctrl-d'). If you do not supply + EXPRESSION, GDB will terminate normally; otherwise it will + terminate using the result of EXPRESSION as the error code. + + An interrupt (often 'Ctrl-c') does not exit from GDB, but rather +terminates the action of any GDB command that is in progress and returns +to GDB command level. It is safe to type the interrupt character at any +time because GDB does not allow it to take effect until a time when it +is safe. + + If you have been using GDB to control an attached process or device, +you can release it with the 'detach' command (*note Debugging an +Already-running Process: Attach.). + + +File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation + +2.3 Shell Commands +================== + +If you need to execute occasional shell commands during your debugging +session, there is no need to leave or suspend GDB; you can just use the +'shell' command. + +'shell COMMAND-STRING' +'!COMMAND-STRING' + Invoke a standard shell to execute COMMAND-STRING. Note that no + space is needed between '!' and COMMAND-STRING. If it exists, the + environment variable 'SHELL' determines which shell to run. + Otherwise GDB uses the default shell ('/bin/sh' on Unix systems, + 'COMMAND.COM' on MS-DOS, etc.). + + The utility 'make' is often needed in development environments. You +do not have to use the 'shell' command for this purpose in GDB: + +'make MAKE-ARGS' + Execute the 'make' program with the specified arguments. This is + equivalent to 'shell make MAKE-ARGS'. + + +File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation + +2.4 Logging Output +================== + +You may want to save the output of GDB commands to a file. There are +several commands to control GDB's logging. + +'set logging on' + Enable logging. +'set logging off' + Disable logging. +'set logging file FILE' + Change the name of the current logfile. The default logfile is + 'gdb.txt'. +'set logging overwrite [on|off]' + By default, GDB will append to the logfile. Set 'overwrite' if you + want 'set logging on' to overwrite the logfile instead. +'set logging redirect [on|off]' + By default, GDB output will go to both the terminal and the + logfile. Set 'redirect' if you want output to go only to the log + file. +'show logging' + Show the current values of the logging settings. + + +File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top + +3 GDB Commands +************** + +You can abbreviate a GDB command to the first few letters of the command +name, if that abbreviation is unambiguous; and you can repeat certain +GDB commands by typing just . You can also use the key to +get GDB to fill out the rest of a word in a command (or to show you the +alternatives available, if there is more than one possibility). + +* Menu: + +* Command Syntax:: How to give commands to GDB +* Completion:: Command completion +* Help:: How to ask GDB for help + + +File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands + +3.1 Command Syntax +================== + +A GDB command is a single line of input. There is no limit on how long +it can be. It starts with a command name, which is followed by +arguments whose meaning depends on the command name. For example, the +command 'step' accepts an argument which is the number of times to step, +as in 'step 5'. You can also use the 'step' command with no arguments. +Some commands do not allow any arguments. + + GDB command names may always be truncated if that abbreviation is +unambiguous. Other possible command abbreviations are listed in the +documentation for individual commands. In some cases, even ambiguous +abbreviations are allowed; for example, 's' is specially defined as +equivalent to 'step' even though there are other commands whose names +start with 's'. You can test abbreviations by using them as arguments +to the 'help' command. + + A blank line as input to GDB (typing just ) means to repeat the +previous command. Certain commands (for example, 'run') will not repeat +this way; these are commands whose unintentional repetition might cause +trouble and which you are unlikely to want to repeat. User-defined +commands can disable this feature; see *note dont-repeat: Define. + + The 'list' and 'x' commands, when you repeat them with , +construct new arguments rather than repeating exactly as typed. This +permits easy scanning of source or memory. + + GDB can also use in another way: to partition lengthy output, +in a way similar to the common utility 'more' (*note Screen Size: Screen +Size.). Since it is easy to press one too many in this situation, +GDB disables command repetition after any command that generates this +sort of display. + + Any text from a '#' to the end of the line is a comment; it does +nothing. This is useful mainly in command files (*note Command Files: +Command Files.). + + The 'Ctrl-o' binding is useful for repeating a complex sequence of +commands. This command accepts the current line, like , and then +fetches the next line relative to the current line from the history for +editing. + + +File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands + +3.2 Command Completion +====================== + +GDB can fill in the rest of a word in a command for you, if there is +only one possibility; it can also show you what the valid possibilities +are for the next word in a command, at any time. This works for GDB +commands, GDB subcommands, and the names of symbols in your program. + + Press the key whenever you want GDB to fill out the rest of a +word. If there is only one possibility, GDB fills in the word, and +waits for you to finish the command (or press to enter it). For +example, if you type + + (gdb) info bre + +GDB fills in the rest of the word 'breakpoints', since that is the only +'info' subcommand beginning with 'bre': + + (gdb) info breakpoints + +You can either press at this point, to run the 'info breakpoints' +command, or backspace and enter something else, if 'breakpoints' does +not look like the command you expected. (If you were sure you wanted +'info breakpoints' in the first place, you might as well just type +immediately after 'info bre', to exploit command abbreviations rather +than command completion). + + If there is more than one possibility for the next word when you +press , GDB sounds a bell. You can either supply more characters +and try again, or just press a second time; GDB displays all the +possible completions for that word. For example, you might want to set +a breakpoint on a subroutine whose name begins with 'make_', but when +you type 'b make_' GDB just sounds the bell. Typing again +displays all the function names in your program that begin with those +characters, for example: + + (gdb) b make_ +GDB sounds bell; press again, to see: + make_a_section_from_file make_environ + make_abs_section make_function_type + make_blockvector make_pointer_type + make_cleanup make_reference_type + make_command make_symbol_completion_list + (gdb) b make_ + +After displaying the available possibilities, GDB copies your partial +input ('b make_' in the example) so you can finish the command. + + If you just want to see the list of alternatives in the first place, +you can press 'M-?' rather than pressing twice. 'M-?' means +' ?'. You can type this either by holding down a key designated +as the shift on your keyboard (if there is one) while typing '?', +or as followed by '?'. + + Sometimes the string you need, while logically a "word", may contain +parentheses or other characters that GDB normally excludes from its +notion of a word. To permit word completion to work in this situation, +you may enclose words in ''' (single quote marks) in GDB commands. + + The most likely situation where you might need this is in typing the +name of a C++ function. This is because C++ allows function overloading +(multiple definitions of the same function, distinguished by argument +type). For example, when you want to set a breakpoint you may need to +distinguish whether you mean the version of 'name' that takes an 'int' +parameter, 'name(int)', or the version that takes a 'float' parameter, +'name(float)'. To use the word-completion facilities in this situation, +type a single quote ''' at the beginning of the function name. This +alerts GDB that it may need to consider more information than usual when +you press or 'M-?' to request word completion: + + (gdb) b 'bubble( M-? + bubble(double,double) bubble(int,int) + (gdb) b 'bubble( + + In some cases, GDB can tell that completing a name requires using +quotes. When this happens, GDB inserts the quote for you (while +completing as much as it can) if you do not type the quote in the first +place: + + (gdb) b bub +GDB alters your input line to the following, and rings a bell: + (gdb) b 'bubble( + +In general, GDB can tell that a quote is needed (and inserts it) if you +have not yet started typing the argument list when you ask for +completion on an overloaded symbol. + + For more information about overloaded functions, see *note C++ +Expressions: C Plus Plus Expressions. You can use the command 'set +overload-resolution off' to disable overload resolution; see *note GDB +Features for C++: Debugging C Plus Plus. + + When completing in an expression which looks up a field in a +structure, GDB also tries(1) to limit completions to the field names +available in the type of the left-hand-side: + + (gdb) p gdb_stdout.M-? + magic to_fputs to_rewind + to_data to_isatty to_write + to_delete to_put to_write_async_safe + to_flush to_read + +This is because the 'gdb_stdout' is a variable of the type 'struct +ui_file' that is defined in GDB sources as follows: + + struct ui_file + { + int *magic; + ui_file_flush_ftype *to_flush; + ui_file_write_ftype *to_write; + ui_file_write_async_safe_ftype *to_write_async_safe; + ui_file_fputs_ftype *to_fputs; + ui_file_read_ftype *to_read; + ui_file_delete_ftype *to_delete; + ui_file_isatty_ftype *to_isatty; + ui_file_rewind_ftype *to_rewind; + ui_file_put_ftype *to_put; + void *to_data; + } + + ---------- Footnotes ---------- + + (1) The completer can be confused by certain kinds of invalid +expressions. Also, it only examines the static type of the expression, +not the dynamic type. + + +File: gdb.info, Node: Help, Prev: Completion, Up: Commands + +3.3 Getting Help +================ + +You can always ask GDB itself for information on its commands, using the +command 'help'. + +'help' +'h' + You can use 'help' (abbreviated 'h') with no arguments to display a + short list of named classes of commands: + + (gdb) help + List of classes of commands: + + aliases -- Aliases of other commands + breakpoints -- Making program stop at certain points + data -- Examining data + files -- Specifying and examining files + internals -- Maintenance commands + obscure -- Obscure features + running -- Running the program + stack -- Examining the stack + status -- Status inquiries + support -- Support facilities + tracepoints -- Tracing of program execution without + stopping the program + user-defined -- User-defined commands + + Type "help" followed by a class name for a list of + commands in that class. + Type "help" followed by command name for full + documentation. + Command name abbreviations are allowed if unambiguous. + (gdb) + +'help CLASS' + Using one of the general help classes as an argument, you can get a + list of the individual commands in that class. For example, here + is the help display for the class 'status': + + (gdb) help status + Status inquiries. + + List of commands: + + info -- Generic command for showing things + about the program being debugged + show -- Generic command for showing things + about the debugger + + Type "help" followed by command name for full + documentation. + Command name abbreviations are allowed if unambiguous. + (gdb) + +'help COMMAND' + With a command name as 'help' argument, GDB displays a short + paragraph on how to use that command. + +'apropos ARGS' + The 'apropos' command searches through all of the GDB commands, and + their documentation, for the regular expression specified in ARGS. + It prints out all matches found. For example: + + apropos alias + + results in: + + alias -- Define a new command that is an alias of an existing command + aliases -- Aliases of other commands + d -- Delete some breakpoints or auto-display expressions + del -- Delete some breakpoints or auto-display expressions + delete -- Delete some breakpoints or auto-display expressions + +'complete ARGS' + The 'complete ARGS' command lists all the possible completions for + the beginning of a command. Use ARGS to specify the beginning of + the command you want completed. For example: + + complete i + + results in: + + if + ignore + info + inspect + + This is intended for use by GNU Emacs. + + In addition to 'help', you can use the GDB commands 'info' and 'show' +to inquire about the state of your program, or the state of GDB itself. +Each command supports many topics of inquiry; this manual introduces +each of them in the appropriate context. The listings under 'info' and +under 'show' in the Command, Variable, and Function Index point to all +the sub-commands. *Note Command and Variable Index::. + +'info' + This command (abbreviated 'i') is for describing the state of your + program. For example, you can show the arguments passed to a + function with 'info args', list the registers currently in use with + 'info registers', or list the breakpoints you have set with 'info + breakpoints'. You can get a complete list of the 'info' + sub-commands with 'help info'. + +'set' + You can assign the result of an expression to an environment + variable with 'set'. For example, you can set the GDB prompt to a + $-sign with 'set prompt $'. + +'show' + In contrast to 'info', 'show' is for describing the state of GDB + itself. You can change most of the things you can 'show', by using + the related command 'set'; for example, you can control what number + system is used for displays with 'set radix', or simply inquire + which is currently in use with 'show radix'. + + To display all the settable parameters and their current values, + you can use 'show' with no arguments; you may also use 'info set'. + Both commands produce the same display. + + Here are several miscellaneous 'show' subcommands, all of which are +exceptional in lacking corresponding 'set' commands: + +'show version' + Show what version of GDB is running. You should include this + information in GDB bug-reports. If multiple versions of GDB are in + use at your site, you may need to determine which version of GDB + you are running; as GDB evolves, new commands are introduced, and + old ones may wither away. Also, many system vendors ship variant + versions of GDB, and there are variant versions of GDB in GNU/Linux + distributions as well. The version number is the same as the one + announced when you start GDB. + +'show copying' +'info copying' + Display information about permission for copying GDB. + +'show warranty' +'info warranty' + Display the GNU "NO WARRANTY" statement, or a warranty, if your + version of GDB comes with one. + +'show configuration' + Display detailed information about the way GDB was configured when + it was built. This displays the optional arguments passed to the + 'configure' script and also configuration parameters detected + automatically by 'configure'. When reporting a GDB bug (*note GDB + Bugs::), it is important to include this information in your + report. + + +File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top + +4 Running Programs Under GDB +**************************** + +When you run a program under GDB, you must first generate debugging +information when you compile it. + + You may start GDB with its arguments, if any, in an environment of +your choice. If you are doing native debugging, you may redirect your +program's input and output, debug an already running process, or kill a +child process. + +* Menu: + +* Compilation:: Compiling for debugging +* Starting:: Starting your program +* Arguments:: Your program's arguments +* Environment:: Your program's environment + +* Working Directory:: Your program's working directory +* Input/Output:: Your program's input and output +* Attach:: Debugging an already-running process +* Kill Process:: Killing the child process + +* Inferiors and Programs:: Debugging multiple inferiors and programs +* Threads:: Debugging programs with multiple threads +* Forks:: Debugging forks +* Checkpoint/Restart:: Setting a _bookmark_ to return to later + + +File: gdb.info, Node: Compilation, Next: Starting, Up: Running + +4.1 Compiling for Debugging +=========================== + +In order to debug a program effectively, you need to generate debugging +information when you compile it. This debugging information is stored +in the object file; it describes the data type of each variable or +function and the correspondence between source line numbers and +addresses in the executable code. + + To request debugging information, specify the '-g' option when you +run the compiler. + + Programs that are to be shipped to your customers are compiled with +optimizations, using the '-O' compiler option. However, some compilers +are unable to handle the '-g' and '-O' options together. Using those +compilers, you cannot generate optimized executables containing +debugging information. + + GCC, the GNU C/C++ compiler, supports '-g' with or without '-O', +making it possible to debug optimized code. We recommend that you +_always_ use '-g' whenever you compile a program. You may think your +program is correct, but there is no sense in pushing your luck. For +more information, see *note Optimized Code::. + + Older versions of the GNU C compiler permitted a variant option '-gg' +for debugging information. GDB no longer supports this format; if your +GNU C compiler has this option, do not use it. + + GDB knows about preprocessor macros and can show you their expansion +(*note Macros::). Most compilers do not include information about +preprocessor macros in the debugging information if you specify the '-g' +flag alone. Version 3.1 and later of GCC, the GNU C compiler, provides +macro information if you are using the DWARF debugging format, and +specify the option '-g3'. + + *Note Options for Debugging Your Program or GCC: (gcc.info)Debugging +Options, for more information on GCC options affecting debug +information. + + You will have the best debugging experience if you use the latest +version of the DWARF debugging format that your compiler supports. +DWARF is currently the most expressive and best supported debugging +format in GDB. + + +File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running + +4.2 Starting your Program +========================= + +'run' +'r' + Use the 'run' command to start your program under GDB. You must + first specify the program name (except on VxWorks) with an argument + to GDB (*note Getting In and Out of GDB: Invocation.), or by using + the 'file' or 'exec-file' command (*note Commands to Specify Files: + Files.). + + If you are running your program in an execution environment that +supports processes, 'run' creates an inferior process and makes that +process run your program. In some environments without processes, 'run' +jumps to the start of your program. Other targets, like 'remote', are +always running. If you get an error message like this one: + + The "remote" target does not support "run". + Try "help target" or "continue". + +then use 'continue' to run your program. You may need 'load' first +(*note load::). + + The execution of a program is affected by certain information it +receives from its superior. GDB provides ways to specify this +information, which you must do _before_ starting your program. (You can +change it after starting your program, but such changes only affect your +program the next time you start it.) This information may be divided +into four categories: + +The _arguments._ + Specify the arguments to give your program as the arguments of the + 'run' command. If a shell is available on your target, the shell + is used to pass the arguments, so that you may use normal + conventions (such as wildcard expansion or variable substitution) + in describing the arguments. In Unix systems, you can control + which shell is used with the 'SHELL' environment variable. If you + do not define 'SHELL', GDB uses the default shell ('/bin/sh'). You + can disable use of any shell with the 'set startup-with-shell' + command (see below for details). + +The _environment._ + Your program normally inherits its environment from GDB, but you + can use the GDB commands 'set environment' and 'unset environment' + to change parts of the environment that affect your program. *Note + Your Program's Environment: Environment. + +The _working directory._ + Your program inherits its working directory from GDB. You can set + the GDB working directory with the 'cd' command in GDB. *Note Your + Program's Working Directory: Working Directory. + +The _standard input and output._ + Your program normally uses the same device for standard input and + standard output as GDB is using. You can redirect input and output + in the 'run' command line, or you can use the 'tty' command to set + a different device for your program. *Note Your Program's Input + and Output: Input/Output. + + _Warning:_ While input and output redirection work, you cannot use + pipes to pass the output of the program you are debugging to + another program; if you attempt this, GDB is likely to wind up + debugging the wrong program. + + When you issue the 'run' command, your program begins to execute +immediately. *Note Stopping and Continuing: Stopping, for discussion of +how to arrange for your program to stop. Once your program has stopped, +you may call functions in your program, using the 'print' or 'call' +commands. *Note Examining Data: Data. + + If the modification time of your symbol file has changed since the +last time GDB read its symbols, GDB discards its symbol table, and reads +it again. When it does this, GDB tries to retain your current +breakpoints. + +'start' + The name of the main procedure can vary from language to language. + With C or C++, the main procedure name is always 'main', but other + languages such as Ada do not require a specific name for their main + procedure. The debugger provides a convenient way to start the + execution of the program and to stop at the beginning of the main + procedure, depending on the language used. + + The 'start' command does the equivalent of setting a temporary + breakpoint at the beginning of the main procedure and then invoking + the 'run' command. + + Some programs contain an "elaboration" phase where some startup + code is executed before the main procedure is called. This depends + on the languages used to write your program. In C++, for instance, + constructors for static and global objects are executed before + 'main' is called. It is therefore possible that the debugger stops + before reaching the main procedure. However, the temporary + breakpoint will remain to halt execution. + + Specify the arguments to give to your program as arguments to the + 'start' command. These arguments will be given verbatim to the + underlying 'run' command. Note that the same arguments will be + reused if no argument is provided during subsequent calls to + 'start' or 'run'. + + It is sometimes necessary to debug the program during elaboration. + In these cases, using the 'start' command would stop the execution + of your program too late, as the program would have already + completed the elaboration phase. Under these circumstances, insert + breakpoints in your elaboration code before running your program. + +'set exec-wrapper WRAPPER' +'show exec-wrapper' +'unset exec-wrapper' + When 'exec-wrapper' is set, the specified wrapper is used to launch + programs for debugging. GDB starts your program with a shell + command of the form 'exec WRAPPER PROGRAM'. Quoting is added to + PROGRAM and its arguments, but not to WRAPPER, so you should add + quotes if appropriate for your shell. The wrapper runs until it + executes your program, and then GDB takes control. + + You can use any program that eventually calls 'execve' with its + arguments as a wrapper. Several standard Unix utilities do this, + e.g. 'env' and 'nohup'. Any Unix shell script ending with 'exec + "$@"' will also work. + + For example, you can use 'env' to pass an environment variable to + the debugged program, without setting the variable in your shell's + environment: + + (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so' + (gdb) run + + This command is available when debugging locally on most targets, + excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino. + +'set startup-with-shell' +'set startup-with-shell on' +'set startup-with-shell off' +'show set startup-with-shell' + On Unix systems, by default, if a shell is available on your + target, GDB) uses it to start your program. Arguments of the 'run' + command are passed to the shell, which does variable substitution, + expands wildcard characters and performs redirection of I/O. In + some circumstances, it may be useful to disable such use of a + shell, for example, when debugging the shell itself or diagnosing + startup failures such as: + + (gdb) run + Starting program: ./a.out + During startup program terminated with signal SIGSEGV, Segmentation fault. + + which indicates the shell or the wrapper specified with + 'exec-wrapper' crashed, not your program. Most often, this is + caused by something odd in your shell's non-interactive mode + initialization file--such as '.cshrc' for C-shell, $'.zshenv' for + the Z shell, or the file specified in the 'BASH_ENV' environment + variable for BASH. + +'set disable-randomization' +'set disable-randomization on' + This option (enabled by default in GDB) will turn off the native + randomization of the virtual address space of the started program. + This option is useful for multiple debugging sessions to make the + execution better reproducible and memory addresses reusable across + debugging sessions. + + This feature is implemented only on certain targets, including + GNU/Linux. On GNU/Linux you can get the same behavior using + + (gdb) set exec-wrapper setarch `uname -m` -R + +'set disable-randomization off' + Leave the behavior of the started executable unchanged. Some bugs + rear their ugly heads only when the program is loaded at certain + addresses. If your bug disappears when you run the program under + GDB, that might be because GDB by default disables the address + randomization on platforms, such as GNU/Linux, which do that for + stand-alone programs. Use 'set disable-randomization off' to try + to reproduce such elusive bugs. + + On targets where it is available, virtual address space + randomization protects the programs against certain kinds of + security attacks. In these cases the attacker needs to know the + exact location of a concrete executable code. Randomizing its + location makes it impossible to inject jumps misusing a code at its + expected addresses. + + Prelinking shared libraries provides a startup performance + advantage but it makes addresses in these libraries predictable for + privileged processes by having just unprivileged access at the + target system. Reading the shared library binary gives enough + information for assembling the malicious code misusing it. Still + even a prelinked shared library can get loaded at a new random + address just requiring the regular relocation process during the + startup. Shared libraries not already prelinked are always loaded + at a randomly chosen address. + + Position independent executables (PIE) contain position independent + code similar to the shared libraries and therefore such executables + get loaded at a randomly chosen address upon startup. PIE + executables always load even already prelinked shared libraries at + a random address. You can build such executable using 'gcc -fPIE + -pie'. + + Heap (malloc storage), stack and custom mmap areas are always + placed randomly (as long as the randomization is enabled). + +'show disable-randomization' + Show the current setting of the explicit disable of the native + randomization of the virtual address space of the started program. + + +File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running + +4.3 Your Program's Arguments +============================ + +The arguments to your program can be specified by the arguments of the +'run' command. They are passed to a shell, which expands wildcard +characters and performs redirection of I/O, and thence to your program. +Your 'SHELL' environment variable (if it exists) specifies what shell +GDB uses. If you do not define 'SHELL', GDB uses the default shell +('/bin/sh' on Unix). + + On non-Unix systems, the program is usually invoked directly by GDB, +which emulates I/O redirection via the appropriate system calls, and the +wildcard characters are expanded by the startup code of the program, not +by the shell. + + 'run' with no arguments uses the same arguments used by the previous +'run', or those set by the 'set args' command. + +'set args' + Specify the arguments to be used the next time your program is run. + If 'set args' has no arguments, 'run' executes your program with no + arguments. Once you have run your program with arguments, using + 'set args' before the next 'run' is the only way to run it again + without arguments. + +'show args' + Show the arguments to give your program when it is started. + + +File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running + +4.4 Your Program's Environment +============================== + +The "environment" consists of a set of environment variables and their +values. Environment variables conventionally record such things as your +user name, your home directory, your terminal type, and your search path +for programs to run. Usually you set up environment variables with the +shell and they are inherited by all the other programs you run. When +debugging, it can be useful to try running your program with a modified +environment without having to start GDB over again. + +'path DIRECTORY' + Add DIRECTORY to the front of the 'PATH' environment variable (the + search path for executables) that will be passed to your program. + The value of 'PATH' used by GDB does not change. You may specify + several directory names, separated by whitespace or by a + system-dependent separator character (':' on Unix, ';' on MS-DOS + and MS-Windows). If DIRECTORY is already in the path, it is moved + to the front, so it is searched sooner. + + You can use the string '$cwd' to refer to whatever is the current + working directory at the time GDB searches the path. If you use + '.' instead, it refers to the directory where you executed the + 'path' command. GDB replaces '.' in the DIRECTORY argument (with + the current path) before adding DIRECTORY to the search path. + +'show paths' + Display the list of search paths for executables (the 'PATH' + environment variable). + +'show environment [VARNAME]' + Print the value of environment variable VARNAME to be given to your + program when it starts. If you do not supply VARNAME, print the + names and values of all environment variables to be given to your + program. You can abbreviate 'environment' as 'env'. + +'set environment VARNAME [=VALUE]' + Set environment variable VARNAME to VALUE. The value changes for + your program only, not for GDB itself. VALUE may be any string; + the values of environment variables are just strings, and any + interpretation is supplied by your program itself. The VALUE + parameter is optional; if it is eliminated, the variable is set to + a null value. + + For example, this command: + + set env USER = foo + + tells the debugged program, when subsequently run, that its user is + named 'foo'. (The spaces around '=' are used for clarity here; + they are not actually required.) + +'unset environment VARNAME' + Remove variable VARNAME from the environment to be passed to your + program. This is different from 'set env VARNAME ='; 'unset + environment' removes the variable from the environment, rather than + assigning it an empty value. + + _Warning:_ On Unix systems, GDB runs your program using the shell +indicated by your 'SHELL' environment variable if it exists (or +'/bin/sh' if not). If your 'SHELL' variable names a shell that runs an +initialization file when started non-interactively--such as '.cshrc' for +C-shell, $'.zshenv' for the Z shell, or the file specified in the +'BASH_ENV' environment variable for BASH--any variables you set in that +file affect your program. You may wish to move setting of environment +variables to files that are only run when you sign on, such as '.login' +or '.profile'. + + +File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running + +4.5 Your Program's Working Directory +==================================== + +Each time you start your program with 'run', it inherits its working +directory from the current working directory of GDB. The GDB working +directory is initially whatever it inherited from its parent process +(typically the shell), but you can specify a new working directory in +GDB with the 'cd' command. + + The GDB working directory also serves as a default for the commands +that specify files for GDB to operate on. *Note Commands to Specify +Files: Files. + +'cd [DIRECTORY]' + Set the GDB working directory to DIRECTORY. If not given, + DIRECTORY uses ''~''. + +'pwd' + Print the GDB working directory. + + It is generally impossible to find the current working directory of +the process being debugged (since a program can change its directory +during its run). If you work on a system where GDB is configured with +the '/proc' support, you can use the 'info proc' command (*note SVR4 +Process Information::) to find out the current working directory of the +debuggee. + + +File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running + +4.6 Your Program's Input and Output +=================================== + +By default, the program you run under GDB does input and output to the +same terminal that GDB uses. GDB switches the terminal to its own +terminal modes to interact with you, but it records the terminal modes +your program was using and switches back to them when you continue +running your program. + +'info terminal' + Displays information recorded by GDB about the terminal modes your + program is using. + + You can redirect your program's input and/or output using shell +redirection with the 'run' command. For example, + + run > outfile + +starts your program, diverting its output to the file 'outfile'. + + Another way to specify where your program should do input and output +is with the 'tty' command. This command accepts a file name as +argument, and causes this file to be the default for future 'run' +commands. It also resets the controlling terminal for the child +process, for future 'run' commands. For example, + + tty /dev/ttyb + +directs that processes started with subsequent 'run' commands default to +do input and output on the terminal '/dev/ttyb' and have that as their +controlling terminal. + + An explicit redirection in 'run' overrides the 'tty' command's effect +on the input/output device, but not its effect on the controlling +terminal. + + When you use the 'tty' command or redirect input in the 'run' +command, only the input _for your program_ is affected. The input for +GDB still comes from your terminal. 'tty' is an alias for 'set +inferior-tty'. + + You can use the 'show inferior-tty' command to tell GDB to display +the name of the terminal that will be used for future runs of your +program. + +'set inferior-tty /dev/ttyb' + Set the tty for the program being debugged to /dev/ttyb. + +'show inferior-tty' + Show the current tty for the program being debugged. + + +File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running + +4.7 Debugging an Already-running Process +======================================== + +'attach PROCESS-ID' + This command attaches to a running process--one that was started + outside GDB. ('info files' shows your active targets.) The + command takes as argument a process ID. The usual way to find out + the PROCESS-ID of a Unix process is with the 'ps' utility, or with + the 'jobs -l' shell command. + + 'attach' does not repeat if you press a second time after + executing the command. + + To use 'attach', your program must be running in an environment which +supports processes; for example, 'attach' does not work for programs on +bare-board targets that lack an operating system. You must also have +permission to send the process a signal. + + When you use 'attach', the debugger finds the program running in the +process first by looking in the current working directory, then (if the +program is not found) by using the source file search path (*note +Specifying Source Directories: Source Path.). You can also use the +'file' command to load the program. *Note Commands to Specify Files: +Files. + + The first thing GDB does after arranging to debug the specified +process is to stop it. You can examine and modify an attached process +with all the GDB commands that are ordinarily available when you start +processes with 'run'. You can insert breakpoints; you can step and +continue; you can modify storage. If you would rather the process +continue running, you may use the 'continue' command after attaching GDB +to the process. + +'detach' + When you have finished debugging the attached process, you can use + the 'detach' command to release it from GDB control. Detaching the + process continues its execution. After the 'detach' command, that + process and GDB become completely independent once more, and you + are ready to 'attach' another process or start one with 'run'. + 'detach' does not repeat if you press again after executing + the command. + + If you exit GDB while you have an attached process, you detach that +process. If you use the 'run' command, you kill that process. By +default, GDB asks for confirmation if you try to do either of these +things; you can control whether or not you need to confirm by using the +'set confirm' command (*note Optional Warnings and Messages: +Messages/Warnings.). + + +File: gdb.info, Node: Kill Process, Next: Inferiors and Programs, Prev: Attach, Up: Running + +4.8 Killing the Child Process +============================= + +'kill' + Kill the child process in which your program is running under GDB. + + This command is useful if you wish to debug a core dump instead of a +running process. GDB ignores any core dump file while your program is +running. + + On some operating systems, a program cannot be executed outside GDB +while you have breakpoints set on it inside GDB. You can use the 'kill' +command in this situation to permit running your program outside the +debugger. + + The 'kill' command is also useful if you wish to recompile and relink +your program, since on many systems it is impossible to modify an +executable file while it is running in a process. In this case, when +you next type 'run', GDB notices that the file has changed, and reads +the symbol table again (while trying to preserve your current breakpoint +settings). + + +File: gdb.info, Node: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running + +4.9 Debugging Multiple Inferiors and Programs +============================================= + +GDB lets you run and debug multiple programs in a single session. In +addition, GDB on some systems may let you run several programs +simultaneously (otherwise you have to exit from one before starting +another). In the most general case, you can have multiple threads of +execution in each of multiple processes, launched from multiple +executables. + + GDB represents the state of each program execution with an object +called an "inferior". An inferior typically corresponds to a process, +but is more general and applies also to targets that do not have +processes. Inferiors may be created before a process runs, and may be +retained after a process exits. Inferiors have unique identifiers that +are different from process ids. Usually each inferior will also have +its own distinct address space, although some embedded targets may have +several inferiors running in different parts of a single address space. +Each inferior may in turn have multiple threads running in it. + + To find out what inferiors exist at any moment, use 'info inferiors': + +'info inferiors' + Print a list of all inferiors currently being managed by GDB. + + GDB displays for each inferior (in this order): + + 1. the inferior number assigned by GDB + + 2. the target system's inferior identifier + + 3. the name of the executable the inferior is running. + + An asterisk '*' preceding the GDB inferior number indicates the + current inferior. + + For example, + + (gdb) info inferiors + Num Description Executable + 2 process 2307 hello + * 1 process 3401 goodbye + + To switch focus between inferiors, use the 'inferior' command: + +'inferior INFNO' + Make inferior number INFNO the current inferior. The argument + INFNO is the inferior number assigned by GDB, as shown in the first + field of the 'info inferiors' display. + + You can get multiple executables into a debugging session via the +'add-inferior' and 'clone-inferior' commands. On some systems GDB can +add inferiors to the debug session automatically by following calls to +'fork' and 'exec'. To remove inferiors from the debugging session use +the 'remove-inferiors' command. + +'add-inferior [ -copies N ] [ -exec EXECUTABLE ]' + Adds N inferiors to be run using EXECUTABLE as the executable. N + defaults to 1. If no executable is specified, the inferiors begins + empty, with no program. You can still assign or change the program + assigned to the inferior at any time by using the 'file' command + with the executable name as its argument. + +'clone-inferior [ -copies N ] [ INFNO ]' + Adds N inferiors ready to execute the same program as inferior + INFNO. N defaults to 1. INFNO defaults to the number of the + current inferior. This is a convenient command when you want to + run another instance of the inferior you are debugging. + + (gdb) info inferiors + Num Description Executable + * 1 process 29964 helloworld + (gdb) clone-inferior + Added inferior 2. + 1 inferiors added. + (gdb) info inferiors + Num Description Executable + 2 helloworld + * 1 process 29964 helloworld + + You can now simply switch focus to inferior 2 and run it. + +'remove-inferiors INFNO...' + Removes the inferior or inferiors INFNO.... It is not possible to + remove an inferior that is running with this command. For those, + use the 'kill' or 'detach' command first. + + To quit debugging one of the running inferiors that is not the +current inferior, you can either detach from it by using the 'detach inferior' +command (allowing it to run independently), or kill it using the 'kill inferiors' +command: + +'detach inferior INFNO...' + Detach from the inferior or inferiors identified by GDB inferior + number(s) INFNO.... Note that the inferior's entry still stays on + the list of inferiors shown by 'info inferiors', but its + Description will show ''. + +'kill inferiors INFNO...' + Kill the inferior or inferiors identified by GDB inferior number(s) + INFNO.... Note that the inferior's entry still stays on the list + of inferiors shown by 'info inferiors', but its Description will + show ''. + + After the successful completion of a command such as 'detach', +'detach inferiors', 'kill' or 'kill inferiors', or after a normal +process exit, the inferior is still valid and listed with 'info +inferiors', ready to be restarted. + + To be notified when inferiors are started or exit under GDB's control +use 'set print inferior-events': + +'set print inferior-events' +'set print inferior-events on' +'set print inferior-events off' + The 'set print inferior-events' command allows you to enable or + disable printing of messages when GDB notices that new inferiors + have started or that inferiors have exited or have been detached. + By default, these messages will not be printed. + +'show print inferior-events' + Show whether messages will be printed when GDB detects that + inferiors have started, exited or have been detached. + + Many commands will work the same with multiple programs as with a +single program: e.g., 'print myglobal' will simply display the value of +'myglobal' in the current inferior. + + Occasionaly, when debugging GDB itself, it may be useful to get more +info about the relationship of inferiors, programs, address spaces in a +debug session. You can do that with the 'maint info program-spaces' +command. + +'maint info program-spaces' + Print a list of all program spaces currently being managed by GDB. + + GDB displays for each program space (in this order): + + 1. the program space number assigned by GDB + + 2. the name of the executable loaded into the program space, with + e.g., the 'file' command. + + An asterisk '*' preceding the GDB program space number indicates + the current program space. + + In addition, below each program space line, GDB prints extra + information that isn't suitable to display in tabular form. For + example, the list of inferiors bound to the program space. + + (gdb) maint info program-spaces + Id Executable + 2 goodbye + Bound inferiors: ID 1 (process 21561) + * 1 hello + + Here we can see that no inferior is running the program 'hello', + while 'process 21561' is running the program 'goodbye'. On some + targets, it is possible that multiple inferiors are bound to the + same program space. The most common example is that of debugging + both the parent and child processes of a 'vfork' call. For + example, + + (gdb) maint info program-spaces + Id Executable + * 1 vfork-test + Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) + + Here, both inferior 2 and inferior 1 are running in the same + program space as a result of inferior 1 having executed a 'vfork' + call. + + +File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running + +4.10 Debugging Programs with Multiple Threads +============================================= + +In some operating systems, such as HP-UX and Solaris, a single program +may have more than one "thread" of execution. The precise semantics of +threads differ from one operating system to another, but in general the +threads of a single program are akin to multiple processes--except that +they share one address space (that is, they can all examine and modify +the same variables). On the other hand, each thread has its own +registers and execution stack, and perhaps private memory. + + GDB provides these facilities for debugging multi-thread programs: + + * automatic notification of new threads + * 'thread THREADNO', a command to switch among threads + * 'info threads', a command to inquire about existing threads + * 'thread apply [THREADNO] [ALL] ARGS', a command to apply a command + to a list of threads + * thread-specific breakpoints + * 'set print thread-events', which controls printing of messages on + thread start and exit. + * 'set libthread-db-search-path PATH', which lets the user specify + which 'libthread_db' to use if the default choice isn't compatible + with the program. + + _Warning:_ These facilities are not yet available on every GDB + configuration where the operating system supports threads. If your + GDB does not support threads, these commands have no effect. For + example, a system without thread support shows no output from 'info + threads', and always rejects the 'thread' command, like this: + + (gdb) info threads + (gdb) thread 1 + Thread ID 1 not known. Use the "info threads" command to + see the IDs of currently known threads. + + The GDB thread debugging facility allows you to observe all threads +while your program runs--but whenever GDB takes control, one thread in +particular is always the focus of debugging. This thread is called the +"current thread". Debugging commands show program information from the +perspective of the current thread. + + Whenever GDB detects a new thread in your program, it displays the +target system's identification for the thread with a message in the form +'[New SYSTAG]'. SYSTAG is a thread identifier whose form varies +depending on the particular system. For example, on GNU/Linux, you +might see + + [New Thread 0x41e02940 (LWP 25582)] + +when GDB notices a new thread. In contrast, on an SGI system, the +SYSTAG is simply something like 'process 368', with no further +qualifier. + + For debugging purposes, GDB associates its own thread number--always +a single integer--with each thread in your program. + +'info threads [ID...]' + Display a summary of all threads currently in your program. + Optional argument ID... is one or more thread ids separated by + spaces, and means to print information only about the specified + thread or threads. GDB displays for each thread (in this order): + + 1. the thread number assigned by GDB + + 2. the target system's thread identifier (SYSTAG) + + 3. the thread's name, if one is known. A thread can either be + named by the user (see 'thread name', below), or, in some + cases, by the program itself. + + 4. the current stack frame summary for that thread + + An asterisk '*' to the left of the GDB thread number indicates the + current thread. + + For example, + + (gdb) info threads + Id Target Id Frame + 3 process 35 thread 27 0x34e5 in sigpause () + 2 process 35 thread 23 0x34e5 in sigpause () + * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) + at threadtest.c:68 + + On Solaris, you can display more information about user threads with +a Solaris-specific command: + +'maint info sol-threads' + Display info on Solaris user threads. + +'thread THREADNO' + Make thread number THREADNO the current thread. The command + argument THREADNO is the internal GDB thread number, as shown in + the first field of the 'info threads' display. GDB responds by + displaying the system identifier of the thread you selected, and + its current stack frame summary: + + (gdb) thread 2 + [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))] + #0 some_function (ignore=0x0) at example.c:8 + 8 printf ("hello\n"); + + As with the '[New ...]' message, the form of the text after + 'Switching to' depends on your system's conventions for identifying + threads. + + The debugger convenience variable '$_thread' contains the number of + the current thread. You may find this useful in writing breakpoint + conditional expressions, command scripts, and so forth. See *Note + Convenience Variables: Convenience Vars, for general information on + convenience variables. + +'thread apply [THREADNO | all] COMMAND' + The 'thread apply' command allows you to apply the named COMMAND to + one or more threads. Specify the numbers of the threads that you + want affected with the command argument THREADNO. It can be a + single thread number, one of the numbers shown in the first field + of the 'info threads' display; or it could be a range of thread + numbers, as in '2-4'. To apply a command to all threads, type + 'thread apply all COMMAND'. + +'thread name [NAME]' + This command assigns a name to the current thread. If no argument + is given, any existing user-specified name is removed. The thread + name appears in the 'info threads' display. + + On some systems, such as GNU/Linux, GDB is able to determine the + name of the thread as given by the OS. On these systems, a name + specified with 'thread name' will override the system-give name, + and removing the user-specified name will cause GDB to once again + display the system-specified name. + +'thread find [REGEXP]' + Search for and display thread ids whose name or SYSTAG matches the + supplied regular expression. + + As well as being the complement to the 'thread name' command, this + command also allows you to identify a thread by its target SYSTAG. + For instance, on GNU/Linux, the target SYSTAG is the LWP id. + + (GDB) thread find 26688 + Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' + (GDB) info thread 4 + Id Target Id Frame + 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () + +'set print thread-events' +'set print thread-events on' +'set print thread-events off' + The 'set print thread-events' command allows you to enable or + disable printing of messages when GDB notices that new threads have + started or that threads have exited. By default, these messages + will be printed if detection of these events is supported by the + target. Note that these messages cannot be disabled on all + targets. + +'show print thread-events' + Show whether messages will be printed when GDB detects that threads + have started and exited. + + *Note Stopping and Starting Multi-thread Programs: Thread Stops, for +more information about how GDB behaves when you stop and start programs +with multiple threads. + + *Note Setting Watchpoints: Set Watchpoints, for information about +watchpoints in programs with multiple threads. + +'set libthread-db-search-path [PATH]' + If this variable is set, PATH is a colon-separated list of + directories GDB will use to search for 'libthread_db'. If you omit + PATH, 'libthread-db-search-path' will be reset to its default value + ('$sdir:$pdir' on GNU/Linux and Solaris systems). Internally, the + default value comes from the 'LIBTHREAD_DB_SEARCH_PATH' macro. + + On GNU/Linux and Solaris systems, GDB uses a "helper" + 'libthread_db' library to obtain information about threads in the + inferior process. GDB will use 'libthread-db-search-path' to find + 'libthread_db'. GDB also consults first if inferior specific + thread debugging library loading is enabled by 'set auto-load + libthread-db' (*note libthread_db.so.1 file::). + + A special entry '$sdir' for 'libthread-db-search-path' refers to + the default system directories that are normally searched for + loading shared libraries. The '$sdir' entry is the only kind not + needing to be enabled by 'set auto-load libthread-db' (*note + libthread_db.so.1 file::). + + A special entry '$pdir' for 'libthread-db-search-path' refers to + the directory from which 'libpthread' was loaded in the inferior + process. + + For any 'libthread_db' library GDB finds in above directories, GDB + attempts to initialize it with the current inferior process. If + this initialization fails (which could happen because of a version + mismatch between 'libthread_db' and 'libpthread'), GDB will unload + 'libthread_db', and continue with the next directory. If none of + 'libthread_db' libraries initialize successfully, GDB will issue a + warning and thread debugging will be disabled. + + Setting 'libthread-db-search-path' is currently implemented only on + some platforms. + +'show libthread-db-search-path' + Display current libthread_db search path. + +'set debug libthread-db' +'show debug libthread-db' + Turns on or off display of 'libthread_db'-related events. Use '1' + to enable, '0' to disable. + + +File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running + +4.11 Debugging Forks +==================== + +On most systems, GDB has no special support for debugging programs which +create additional processes using the 'fork' function. When a program +forks, GDB will continue to debug the parent process and the child +process will run unimpeded. If you have set a breakpoint in any code +which the child then executes, the child will get a 'SIGTRAP' signal +which (unless it catches the signal) will cause it to terminate. + + However, if you want to debug the child process there is a workaround +which isn't too painful. Put a call to 'sleep' in the code which the +child process executes after the fork. It may be useful to sleep only +if a certain environment variable is set, or a certain file exists, so +that the delay need not occur when you don't want to run GDB on the +child. While the child is sleeping, use the 'ps' program to get its +process ID. Then tell GDB (a new invocation of GDB if you are also +debugging the parent process) to attach to the child process (*note +Attach::). From that point on you can debug the child process just like +any other process which you attached to. + + On some systems, GDB provides support for debugging programs that +create additional processes using the 'fork' or 'vfork' functions. +Currently, the only platforms with this feature are HP-UX (11.x and +later only?) and GNU/Linux (kernel version 2.5.60 and later). + + By default, when a program forks, GDB will continue to debug the +parent process and the child process will run unimpeded. + + If you want to follow the child process instead of the parent +process, use the command 'set follow-fork-mode'. + +'set follow-fork-mode MODE' + Set the debugger response to a program call of 'fork' or 'vfork'. + A call to 'fork' or 'vfork' creates a new process. The MODE + argument can be: + + 'parent' + The original process is debugged after a fork. The child + process runs unimpeded. This is the default. + + 'child' + The new process is debugged after a fork. The parent process + runs unimpeded. + +'show follow-fork-mode' + Display the current debugger response to a 'fork' or 'vfork' call. + + On Linux, if you want to debug both the parent and child processes, +use the command 'set detach-on-fork'. + +'set detach-on-fork MODE' + Tells gdb whether to detach one of the processes after a fork, or + retain debugger control over them both. + + 'on' + The child process (or parent process, depending on the value + of 'follow-fork-mode') will be detached and allowed to run + independently. This is the default. + + 'off' + Both processes will be held under the control of GDB. One + process (child or parent, depending on the value of + 'follow-fork-mode') is debugged as usual, while the other is + held suspended. + +'show detach-on-fork' + Show whether detach-on-fork mode is on/off. + + If you choose to set 'detach-on-fork' mode off, then GDB will retain +control of all forked processes (including nested forks). You can list +the forked processes under the control of GDB by using the 'info inferiors' +command, and switch from one fork to another by using the 'inferior' +command (*note Debugging Multiple Inferiors and Programs: Inferiors and +Programs.). + + To quit debugging one of the forked processes, you can either detach +from it by using the 'detach inferiors' command (allowing it to run +independently), or kill it using the 'kill inferiors' command. *Note +Debugging Multiple Inferiors and Programs: Inferiors and Programs. + + If you ask to debug a child process and a 'vfork' is followed by an +'exec', GDB executes the new target up to the first breakpoint in the +new target. If you have a breakpoint set on 'main' in your original +program, the breakpoint will also be set on the child process's 'main'. + + On some systems, when a child process is spawned by 'vfork', you +cannot debug the child or parent until an 'exec' call completes. + + If you issue a 'run' command to GDB after an 'exec' call executes, +the new target restarts. To restart the parent process, use the 'file' +command with the parent executable name as its argument. By default, +after an 'exec' call executes, GDB discards the symbols of the previous +executable image. You can change this behaviour with the 'set follow-exec-mode' +command. + +'set follow-exec-mode MODE' + + Set debugger response to a program call of 'exec'. An 'exec' call + replaces the program image of a process. + + 'follow-exec-mode' can be: + + 'new' + GDB creates a new inferior and rebinds the process to this new + inferior. The program the process was running before the + 'exec' call can be restarted afterwards by restarting the + original inferior. + + For example: + + (gdb) info inferiors + (gdb) info inferior + Id Description Executable + * 1 prog1 + (gdb) run + process 12020 is executing new program: prog2 + Program exited normally. + (gdb) info inferiors + Id Description Executable + * 2 prog2 + 1 prog1 + + 'same' + GDB keeps the process bound to the same inferior. The new + executable image replaces the previous executable loaded in + the inferior. Restarting the inferior after the 'exec' call, + with e.g., the 'run' command, restarts the executable the + process was running after the 'exec' call. This is the + default mode. + + For example: + + (gdb) info inferiors + Id Description Executable + * 1 prog1 + (gdb) run + process 12020 is executing new program: prog2 + Program exited normally. + (gdb) info inferiors + Id Description Executable + * 1 prog2 + + You can use the 'catch' command to make GDB stop whenever a 'fork', +'vfork', or 'exec' call is made. *Note Setting Catchpoints: Set +Catchpoints. + + +File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running + +4.12 Setting a _Bookmark_ to Return to Later +============================================ + +On certain operating systems(1), GDB is able to save a "snapshot" of a +program's state, called a "checkpoint", and come back to it later. + + Returning to a checkpoint effectively undoes everything that has +happened in the program since the 'checkpoint' was saved. This includes +changes in memory, registers, and even (within some limits) system +state. Effectively, it is like going back in time to the moment when +the checkpoint was saved. + + Thus, if you're stepping thru a program and you think you're getting +close to the point where things go wrong, you can save a checkpoint. +Then, if you accidentally go too far and miss the critical statement, +instead of having to restart your program from the beginning, you can +just go back to the checkpoint and start again from there. + + This can be especially useful if it takes a lot of time or steps to +reach the point where you think the bug occurs. + + To use the 'checkpoint'/'restart' method of debugging: + +'checkpoint' + Save a snapshot of the debugged program's current execution state. + The 'checkpoint' command takes no arguments, but each checkpoint is + assigned a small integer id, similar to a breakpoint id. + +'info checkpoints' + List the checkpoints that have been saved in the current debugging + session. For each checkpoint, the following information will be + listed: + + 'Checkpoint ID' + 'Process ID' + 'Code Address' + 'Source line, or label' + +'restart CHECKPOINT-ID' + Restore the program state that was saved as checkpoint number + CHECKPOINT-ID. All program variables, registers, stack frames etc. + will be returned to the values that they had when the checkpoint + was saved. In essence, gdb will "wind back the clock" to the point + in time when the checkpoint was saved. + + Note that breakpoints, GDB variables, command history etc. are not + affected by restoring a checkpoint. In general, a checkpoint only + restores things that reside in the program being debugged, not in + the debugger. + +'delete checkpoint CHECKPOINT-ID' + Delete the previously-saved checkpoint identified by CHECKPOINT-ID. + + Returning to a previously saved checkpoint will restore the user +state of the program being debugged, plus a significant subset of the +system (OS) state, including file pointers. It won't "un-write" data +from a file, but it will rewind the file pointer to the previous +location, so that the previously written data can be overwritten. For +files opened in read mode, the pointer will also be restored so that the +previously read data can be read again. + + Of course, characters that have been sent to a printer (or other +external device) cannot be "snatched back", and characters received from +eg. a serial device can be removed from internal program buffers, but +they cannot be "pushed back" into the serial pipeline, ready to be +received again. Similarly, the actual contents of files that have been +changed cannot be restored (at this time). + + However, within those constraints, you actually can "rewind" your +program to a previously saved point in time, and begin debugging it +again -- and you can change the course of events so as to debug a +different execution path this time. + + Finally, there is one bit of internal program state that will be +different when you return to a checkpoint -- the program's process id. +Each checkpoint will have a unique process id (or PID), and each will be +different from the program's original PID. If your program has saved a +local copy of its process id, this could potentially pose a problem. + +4.12.1 A Non-obvious Benefit of Using Checkpoints +------------------------------------------------- + +On some systems such as GNU/Linux, address space randomization is +performed on new processes for security reasons. This makes it +difficult or impossible to set a breakpoint, or watchpoint, on an +absolute address if you have to restart the program, since the absolute +location of a symbol will change from one execution to the next. + + A checkpoint, however, is an _identical_ copy of a process. +Therefore if you create a checkpoint at (eg.) the start of main, and +simply return to that checkpoint instead of restarting the process, you +can avoid the effects of address randomization and your symbols will all +stay in the same place. + + ---------- Footnotes ---------- + + (1) Currently, only GNU/Linux. + + +File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top + +5 Stopping and Continuing +************************* + +The principal purposes of using a debugger are so that you can stop your +program before it terminates; or so that, if your program runs into +trouble, you can investigate and find out why. + + Inside GDB, your program may stop for any of several reasons, such as +a signal, a breakpoint, or reaching a new line after a GDB command such +as 'step'. You may then examine and change variables, set new +breakpoints or remove old ones, and then continue execution. Usually, +the messages shown by GDB provide ample explanation of the status of +your program--but you can also explicitly request this information at +any time. + +'info program' + Display information about the status of your program: whether it is + running or not, what process it is, and why it stopped. + +* Menu: + +* Breakpoints:: Breakpoints, watchpoints, and catchpoints +* Continuing and Stepping:: Resuming execution +* Skipping Over Functions and Files:: + Skipping over functions and files +* Signals:: Signals +* Thread Stops:: Stopping and starting multi-thread programs + + +File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping + +5.1 Breakpoints, Watchpoints, and Catchpoints +============================================= + +A "breakpoint" makes your program stop whenever a certain point in the +program is reached. For each breakpoint, you can add conditions to +control in finer detail whether your program stops. You can set +breakpoints with the 'break' command and its variants (*note Setting +Breakpoints: Set Breaks.), to specify the place where your program +should stop by line number, function name or exact address in the +program. + + On some systems, you can set breakpoints in shared libraries before +the executable is run. There is a minor limitation on HP-UX systems: +you must wait until the executable is run in order to set breakpoints in +shared library routines that are not called directly by the program (for +example, routines that are arguments in a 'pthread_create' call). + + A "watchpoint" is a special breakpoint that stops your program when +the value of an expression changes. The expression may be a value of a +variable, or it could involve values of one or more variables combined +by operators, such as 'a + b'. This is sometimes called "data +breakpoints". You must use a different command to set watchpoints +(*note Setting Watchpoints: Set Watchpoints.), but aside from that, you +can manage a watchpoint like any other breakpoint: you enable, disable, +and delete both breakpoints and watchpoints using the same commands. + + You can arrange to have values from your program displayed +automatically whenever GDB stops at a breakpoint. *Note Automatic +Display: Auto Display. + + A "catchpoint" is another special breakpoint that stops your program +when a certain kind of event occurs, such as the throwing of a C++ +exception or the loading of a library. As with watchpoints, you use a +different command to set a catchpoint (*note Setting Catchpoints: Set +Catchpoints.), but aside from that, you can manage a catchpoint like any +other breakpoint. (To stop when your program receives a signal, use the +'handle' command; see *note Signals: Signals.) + + GDB assigns a number to each breakpoint, watchpoint, or catchpoint +when you create it; these numbers are successive integers starting with +one. In many of the commands for controlling various features of +breakpoints you use the breakpoint number to say which breakpoint you +want to change. Each breakpoint may be "enabled" or "disabled"; if +disabled, it has no effect on your program until you enable it again. + + Some GDB commands accept a range of breakpoints on which to operate. +A breakpoint range is either a single breakpoint number, like '5', or +two such numbers, in increasing order, separated by a hyphen, like +'5-7'. When a breakpoint range is given to a command, all breakpoints +in that range are operated on. + +* Menu: + +* Set Breaks:: Setting breakpoints +* Set Watchpoints:: Setting watchpoints +* Set Catchpoints:: Setting catchpoints +* Delete Breaks:: Deleting breakpoints +* Disabling:: Disabling breakpoints +* Conditions:: Break conditions +* Break Commands:: Breakpoint command lists +* Dynamic Printf:: Dynamic printf +* Save Breakpoints:: How to save breakpoints in a file +* Static Probe Points:: Listing static probe points +* Error in Breakpoints:: "Cannot insert breakpoints" +* Breakpoint-related Warnings:: "Breakpoint address adjusted..." + + +File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints + +5.1.1 Setting Breakpoints +------------------------- + +Breakpoints are set with the 'break' command (abbreviated 'b'). The +debugger convenience variable '$bpnum' records the number of the +breakpoint you've set most recently; see *note Convenience Variables: +Convenience Vars, for a discussion of what you can do with convenience +variables. + +'break LOCATION' + Set a breakpoint at the given LOCATION, which can specify a + function name, a line number, or an address of an instruction. + (*Note Specify Location::, for a list of all the possible ways to + specify a LOCATION.) The breakpoint will stop your program just + before it executes any of the code in the specified LOCATION. + + When using source languages that permit overloading of symbols, + such as C++, a function name may refer to more than one possible + place to break. *Note Ambiguous Expressions: Ambiguous + Expressions, for a discussion of that situation. + + It is also possible to insert a breakpoint that will stop the + program only if a specific thread (*note Thread-Specific + Breakpoints::) or a specific task (*note Ada Tasks::) hits that + breakpoint. + +'break' + When called without any arguments, 'break' sets a breakpoint at the + next instruction to be executed in the selected stack frame (*note + Examining the Stack: Stack.). In any selected frame but the + innermost, this makes your program stop as soon as control returns + to that frame. This is similar to the effect of a 'finish' command + in the frame inside the selected frame--except that 'finish' does + not leave an active breakpoint. If you use 'break' without an + argument in the innermost frame, GDB stops the next time it reaches + the current location; this may be useful inside loops. + + GDB normally ignores breakpoints when it resumes execution, until + at least one instruction has been executed. If it did not do this, + you would be unable to proceed past a breakpoint without first + disabling the breakpoint. This rule applies whether or not the + breakpoint already existed when your program stopped. + +'break ... if COND' + Set a breakpoint with condition COND; evaluate the expression COND + each time the breakpoint is reached, and stop only if the value is + nonzero--that is, if COND evaluates as true. '...' stands for one + of the possible arguments described above (or no argument) + specifying where to break. *Note Break Conditions: Conditions, for + more information on breakpoint conditions. + +'tbreak ARGS' + Set a breakpoint enabled only for one stop. ARGS are the same as + for the 'break' command, and the breakpoint is set in the same way, + but the breakpoint is automatically deleted after the first time + your program stops there. *Note Disabling Breakpoints: Disabling. + +'hbreak ARGS' + Set a hardware-assisted breakpoint. ARGS are the same as for the + 'break' command and the breakpoint is set in the same way, but the + breakpoint requires hardware support and some target hardware may + not have this support. The main purpose of this is EPROM/ROM code + debugging, so you can set a breakpoint at an instruction without + changing the instruction. This can be used with the new + trap-generation provided by SPARClite DSU and most x86-based + targets. These targets will generate traps when a program accesses + some data or instruction address that is assigned to the debug + registers. However the hardware breakpoint registers can take a + limited number of breakpoints. For example, on the DSU, only two + data breakpoints can be set at a time, and GDB will reject this + command if more than two are used. Delete or disable unused + hardware breakpoints before setting new ones (*note Disabling + Breakpoints: Disabling.). *Note Break Conditions: Conditions. For + remote targets, you can restrict the number of hardware breakpoints + GDB will use, see *note set remote hardware-breakpoint-limit::. + +'thbreak ARGS' + Set a hardware-assisted breakpoint enabled only for one stop. ARGS + are the same as for the 'hbreak' command and the breakpoint is set + in the same way. However, like the 'tbreak' command, the + breakpoint is automatically deleted after the first time your + program stops there. Also, like the 'hbreak' command, the + breakpoint requires hardware support and some target hardware may + not have this support. *Note Disabling Breakpoints: Disabling. + See also *note Break Conditions: Conditions. + +'rbreak REGEX' + Set breakpoints on all functions matching the regular expression + REGEX. This command sets an unconditional breakpoint on all + matches, printing a list of all breakpoints it set. Once these + breakpoints are set, they are treated just like the breakpoints set + with the 'break' command. You can delete them, disable them, or + make them conditional the same way as any other breakpoint. + + The syntax of the regular expression is the standard one used with + tools like 'grep'. Note that this is different from the syntax + used by shells, so for instance 'foo*' matches all functions that + include an 'fo' followed by zero or more 'o's. There is an + implicit '.*' leading and trailing the regular expression you + supply, so to match only functions that begin with 'foo', use + '^foo'. + + When debugging C++ programs, 'rbreak' is useful for setting + breakpoints on overloaded functions that are not members of any + special classes. + + The 'rbreak' command can be used to set breakpoints in *all* the + functions in a program, like this: + + (gdb) rbreak . + +'rbreak FILE:REGEX' + If 'rbreak' is called with a filename qualification, it limits the + search for functions matching the given regular expression to the + specified FILE. This can be used, for example, to set breakpoints + on every function in a given file: + + (gdb) rbreak file.c:. + + The colon separating the filename qualifier from the regex may + optionally be surrounded by spaces. + +'info breakpoints [N...]' +'info break [N...]' + Print a table of all breakpoints, watchpoints, and catchpoints set + and not deleted. Optional argument N means print information only + about the specified breakpoint(s) (or watchpoint(s) or + catchpoint(s)). For each breakpoint, following columns are + printed: + + _Breakpoint Numbers_ + _Type_ + Breakpoint, watchpoint, or catchpoint. + _Disposition_ + Whether the breakpoint is marked to be disabled or deleted + when hit. + _Enabled or Disabled_ + Enabled breakpoints are marked with 'y'. 'n' marks + breakpoints that are not enabled. + _Address_ + Where the breakpoint is in your program, as a memory address. + For a pending breakpoint whose address is not yet known, this + field will contain ''. Such breakpoint won't fire + until a shared library that has the symbol or line referred by + breakpoint is loaded. See below for details. A breakpoint + with several locations will have '' in this + field--see below for details. + _What_ + Where the breakpoint is in the source for your program, as a + file and line number. For a pending breakpoint, the original + string passed to the breakpoint command will be listed as it + cannot be resolved until the appropriate shared library is + loaded in the future. + + If a breakpoint is conditional, there are two evaluation modes: + "host" and "target". If mode is "host", breakpoint condition + evaluation is done by GDB on the host's side. If it is "target", + then the condition is evaluated by the target. The 'info break' + command shows the condition on the line following the affected + breakpoint, together with its condition evaluation mode in between + parentheses. + + Breakpoint commands, if any, are listed after that. A pending + breakpoint is allowed to have a condition specified for it. The + condition is not parsed for validity until a shared library is + loaded that allows the pending breakpoint to resolve to a valid + location. + + 'info break' with a breakpoint number N as argument lists only that + breakpoint. The convenience variable '$_' and the default + examining-address for the 'x' command are set to the address of the + last breakpoint listed (*note Examining Memory: Memory.). + + 'info break' displays a count of the number of times the breakpoint + has been hit. This is especially useful in conjunction with the + 'ignore' command. You can ignore a large number of breakpoint + hits, look at the breakpoint info to see how many times the + breakpoint was hit, and then run again, ignoring one less than that + number. This will get you quickly to the last hit of that + breakpoint. + + For a breakpoints with an enable count (xref) greater than 1, 'info + break' also displays that count. + + GDB allows you to set any number of breakpoints at the same place in +your program. There is nothing silly or meaningless about this. When +the breakpoints are conditional, this is even useful (*note Break +Conditions: Conditions.). + + It is possible that a breakpoint corresponds to several locations in +your program. Examples of this situation are: + + * Multiple functions in the program may have the same name. + + * For a C++ constructor, the GCC compiler generates several instances + of the function body, used in different cases. + + * For a C++ template function, a given line in the function can + correspond to any number of instantiations. + + * For an inlined function, a given source line can correspond to + several places where that function is inlined. + + In all those cases, GDB will insert a breakpoint at all the relevant +locations. + + A breakpoint with multiple locations is displayed in the breakpoint +table using several rows--one header row, followed by one row for each +breakpoint location. The header row has '' in the address +column. The rows for individual locations contain the actual addresses +for locations, and show the functions to which those locations belong. +The number column for a location is of the form +BREAKPOINT-NUMBER.LOCATION-NUMBER. + + For example: + + Num Type Disp Enb Address What + 1 breakpoint keep y + stop only if i==1 + breakpoint already hit 1 time + 1.1 y 0x080486a2 in void foo() at t.cc:8 + 1.2 y 0x080486ca in void foo() at t.cc:8 + + Each location can be individually enabled or disabled by passing +BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the 'enable' and +'disable' commands. Note that you cannot delete the individual +locations from the list, you can only delete the entire list of +locations that belong to their parent breakpoint (with the 'delete NUM' +command, where NUM is the number of the parent breakpoint, 1 in the +above example). Disabling or enabling the parent breakpoint (*note +Disabling::) affects all of the locations that belong to that +breakpoint. + + It's quite common to have a breakpoint inside a shared library. +Shared libraries can be loaded and unloaded explicitly, and possibly +repeatedly, as the program is executed. To support this use case, GDB +updates breakpoint locations whenever any shared library is loaded or +unloaded. Typically, you would set a breakpoint in a shared library at +the beginning of your debugging session, when the library is not loaded, +and when the symbols from the library are not available. When you try +to set breakpoint, GDB will ask you if you want to set a so called +"pending breakpoint"--breakpoint whose address is not yet resolved. + + After the program is run, whenever a new shared library is loaded, +GDB reevaluates all the breakpoints. When a newly loaded shared library +contains the symbol or line referred to by some pending breakpoint, that +breakpoint is resolved and becomes an ordinary breakpoint. When a +library is unloaded, all breakpoints that refer to its symbols or source +lines become pending again. + + This logic works for breakpoints with multiple locations, too. For +example, if you have a breakpoint in a C++ template function, and a +newly loaded shared library has an instantiation of that template, a new +location is added to the list of locations for the breakpoint. + + Except for having unresolved address, pending breakpoints do not +differ from regular breakpoints. You can set conditions or commands, +enable and disable them and perform other breakpoint operations. + + GDB provides some additional commands for controlling what happens +when the 'break' command cannot resolve breakpoint address specification +to an address: + +'set breakpoint pending auto' + This is the default behavior. When GDB cannot find the breakpoint + location, it queries you whether a pending breakpoint should be + created. + +'set breakpoint pending on' + This indicates that an unrecognized breakpoint location should + automatically result in a pending breakpoint being created. + +'set breakpoint pending off' + This indicates that pending breakpoints are not to be created. Any + unrecognized breakpoint location results in an error. This setting + does not affect any pending breakpoints previously created. + +'show breakpoint pending' + Show the current behavior setting for creating pending breakpoints. + + The settings above only affect the 'break' command and its variants. +Once breakpoint is set, it will be automatically updated as shared +libraries are loaded and unloaded. + + For some targets, GDB can automatically decide if hardware or +software breakpoints should be used, depending on whether the breakpoint +address is read-only or read-write. This applies to breakpoints set +with the 'break' command as well as to internal breakpoints set by +commands like 'next' and 'finish'. For breakpoints set with 'hbreak', +GDB will always use hardware breakpoints. + + You can control this automatic behaviour with the following +commands:: + +'set breakpoint auto-hw on' + This is the default behavior. When GDB sets a breakpoint, it will + try to use the target memory map to decide if software or hardware + breakpoint must be used. + +'set breakpoint auto-hw off' + This indicates GDB should not automatically select breakpoint type. + If the target provides a memory map, GDB will warn when trying to + set software breakpoint at a read-only address. + + GDB normally implements breakpoints by replacing the program code at +the breakpoint address with a special instruction, which, when executed, +given control to the debugger. By default, the program code is so +modified only when the program is resumed. As soon as the program +stops, GDB restores the original instructions. This behaviour guards +against leaving breakpoints inserted in the target should gdb abrubptly +disconnect. However, with slow remote targets, inserting and removing +breakpoint can reduce the performance. This behavior can be controlled +with the following commands:: + +'set breakpoint always-inserted off' + All breakpoints, including newly added by the user, are inserted in + the target only when the target is resumed. All breakpoints are + removed from the target when it stops. + +'set breakpoint always-inserted on' + Causes all breakpoints to be inserted in the target at all times. + If the user adds a new breakpoint, or changes an existing + breakpoint, the breakpoints in the target are updated immediately. + A breakpoint is removed from the target only when breakpoint itself + is removed. + +'set breakpoint always-inserted auto' + This is the default mode. If GDB is controlling the inferior in + non-stop mode (*note Non-Stop Mode::), gdb behaves as if + 'breakpoint always-inserted' mode is on. If GDB is controlling the + inferior in all-stop mode, GDB behaves as if 'breakpoint + always-inserted' mode is off. + + GDB handles conditional breakpoints by evaluating these conditions +when a breakpoint breaks. If the condition is true, then the process +being debugged stops, otherwise the process is resumed. + + If the target supports evaluating conditions on its end, GDB may +download the breakpoint, together with its conditions, to it. + + This feature can be controlled via the following commands: + +'set breakpoint condition-evaluation host' + This option commands GDB to evaluate the breakpoint conditions on + the host's side. Unconditional breakpoints are sent to the target + which in turn receives the triggers and reports them back to GDB + for condition evaluation. This is the standard evaluation mode. + +'set breakpoint condition-evaluation target' + This option commands GDB to download breakpoint conditions to the + target at the moment of their insertion. The target is responsible + for evaluating the conditional expression and reporting breakpoint + stop events back to GDB whenever the condition is true. Due to + limitations of target-side evaluation, some conditions cannot be + evaluated there, e.g., conditions that depend on local data that is + only known to the host. Examples include conditional expressions + involving convenience variables, complex types that cannot be + handled by the agent expression parser and expressions that are too + long to be sent over to the target, specially when the target is a + remote system. In these cases, the conditions will be evaluated by + GDB. + +'set breakpoint condition-evaluation auto' + This is the default mode. If the target supports evaluating + breakpoint conditions on its end, GDB will download breakpoint + conditions to the target (limitations mentioned previously apply). + If the target does not support breakpoint condition evaluation, + then GDB will fallback to evaluating all these conditions on the + host's side. + + GDB itself sometimes sets breakpoints in your program for special +purposes, such as proper handling of 'longjmp' (in C programs). These +internal breakpoints are assigned negative numbers, starting with '-1'; +'info breakpoints' does not display them. You can see these breakpoints +with the GDB maintenance command 'maint info breakpoints' (*note maint +info breakpoints::). + + +File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints + +5.1.2 Setting Watchpoints +------------------------- + +You can use a watchpoint to stop execution whenever the value of an +expression changes, without having to predict a particular place where +this may happen. (This is sometimes called a "data breakpoint".) The +expression may be as simple as the value of a single variable, or as +complex as many variables combined by operators. Examples include: + + * A reference to the value of a single variable. + + * An address cast to an appropriate data type. For example, '*(int + *)0x12345678' will watch a 4-byte region at the specified address + (assuming an 'int' occupies 4 bytes). + + * An arbitrarily complex expression, such as 'a*b + c/d'. The + expression can use any operators valid in the program's native + language (*note Languages::). + + You can set a watchpoint on an expression even if the expression can +not be evaluated yet. For instance, you can set a watchpoint on +'*global_ptr' before 'global_ptr' is initialized. GDB will stop when +your program sets 'global_ptr' and the expression produces a valid +value. If the expression becomes valid in some other way than changing +a variable (e.g. if the memory pointed to by '*global_ptr' becomes +readable as the result of a 'malloc' call), GDB may not stop until the +next time the expression changes. + + Depending on your system, watchpoints may be implemented in software +or hardware. GDB does software watchpointing by single-stepping your +program and testing the variable's value each time, which is hundreds of +times slower than normal execution. (But this may still be worth it, to +catch errors where you have no clue what part of your program is the +culprit.) + + On some systems, such as HP-UX, PowerPC, GNU/Linux and most other +x86-based targets, GDB includes support for hardware watchpoints, which +do not slow down the running of your program. + +'watch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]' + Set a watchpoint for an expression. GDB will break when the + expression EXPR is written into by the program and its value + changes. The simplest (and the most popular) use of this command + is to watch the value of a single variable: + + (gdb) watch foo + + If the command includes a '[thread THREADNUM]' argument, GDB breaks + only when the thread identified by THREADNUM changes the value of + EXPR. If any other threads change the value of EXPR, GDB will not + break. Note that watchpoints restricted to a single thread in this + way only work with Hardware Watchpoints. + + Ordinarily a watchpoint respects the scope of variables in EXPR + (see below). The '-location' argument tells GDB to instead watch + the memory referred to by EXPR. In this case, GDB will evaluate + EXPR, take the address of the result, and watch the memory at that + address. The type of the result is used to determine the size of + the watched memory. If the expression's result does not have an + address, then GDB will print an error. + + The '[mask MASKVALUE]' argument allows creation of masked + watchpoints, if the current architecture supports this feature + (e.g., PowerPC Embedded architecture, see *note PowerPC + Embedded::.) A "masked watchpoint" specifies a mask in addition to + an address to watch. The mask specifies that some bits of an + address (the bits which are reset in the mask) should be ignored + when matching the address accessed by the inferior against the + watchpoint address. Thus, a masked watchpoint watches many + addresses simultaneously--those addresses whose unmasked bits are + identical to the unmasked bits in the watchpoint address. The + 'mask' argument implies '-location'. Examples: + + (gdb) watch foo mask 0xffff00ff + (gdb) watch *0xdeadbeef mask 0xffffff00 + +'rwatch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]' + Set a watchpoint that will break when the value of EXPR is read by + the program. + +'awatch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]' + Set a watchpoint that will break when EXPR is either read from or + written into by the program. + +'info watchpoints [N...]' + This command prints a list of watchpoints, using the same format as + 'info break' (*note Set Breaks::). + + If you watch for a change in a numerically entered address you need +to dereference it, as the address itself is just a constant number which +will never change. GDB refuses to create a watchpoint that watches a +never-changing value: + + (gdb) watch 0x600850 + Cannot watch constant value 0x600850. + (gdb) watch *(int *) 0x600850 + Watchpoint 1: *(int *) 6293584 + + GDB sets a "hardware watchpoint" if possible. Hardware watchpoints +execute very quickly, and the debugger reports a change in value at the +exact instruction where the change occurs. If GDB cannot set a hardware +watchpoint, it sets a software watchpoint, which executes more slowly +and reports the change in value at the next _statement_, not the +instruction, after the change occurs. + + You can force GDB to use only software watchpoints with the 'set +can-use-hw-watchpoints 0' command. With this variable set to zero, GDB +will never try to use hardware watchpoints, even if the underlying +system supports them. (Note that hardware-assisted watchpoints that +were set _before_ setting 'can-use-hw-watchpoints' to zero will still +use the hardware mechanism of watching expression values.) + +'set can-use-hw-watchpoints' + Set whether or not to use hardware watchpoints. + +'show can-use-hw-watchpoints' + Show the current mode of using hardware watchpoints. + + For remote targets, you can restrict the number of hardware +watchpoints GDB will use, see *note set remote +hardware-breakpoint-limit::. + + When you issue the 'watch' command, GDB reports + + Hardware watchpoint NUM: EXPR + +if it was able to set a hardware watchpoint. + + Currently, the 'awatch' and 'rwatch' commands can only set hardware +watchpoints, because accesses to data that don't change the value of the +watched expression cannot be detected without examining every +instruction as it is being executed, and GDB does not do that currently. +If GDB finds that it is unable to set a hardware breakpoint with the +'awatch' or 'rwatch' command, it will print a message like this: + + Expression cannot be implemented with read/access watchpoint. + + Sometimes, GDB cannot set a hardware watchpoint because the data type +of the watched expression is wider than what a hardware watchpoint on +the target machine can handle. For example, some systems can only watch +regions that are up to 4 bytes wide; on such systems you cannot set +hardware watchpoints for an expression that yields a double-precision +floating-point number (which is typically 8 bytes wide). As a +work-around, it might be possible to break the large region into a +series of smaller ones and watch them with separate watchpoints. + + If you set too many hardware watchpoints, GDB might be unable to +insert all of them when you resume the execution of your program. Since +the precise number of active watchpoints is unknown until such time as +the program is about to be resumed, GDB might not be able to warn you +about this when you set the watchpoints, and the warning will be printed +only when the program is resumed: + + Hardware watchpoint NUM: Could not insert watchpoint + +If this happens, delete or disable some of the watchpoints. + + Watching complex expressions that reference many variables can also +exhaust the resources available for hardware-assisted watchpoints. +That's because GDB needs to watch every variable in the expression with +separately allocated resources. + + If you call a function interactively using 'print' or 'call', any +watchpoints you have set will be inactive until GDB reaches another kind +of breakpoint or the call completes. + + GDB automatically deletes watchpoints that watch local (automatic) +variables, or expressions that involve such variables, when they go out +of scope, that is, when the execution leaves the block in which these +variables were defined. In particular, when the program being debugged +terminates, _all_ local variables go out of scope, and so only +watchpoints that watch global variables remain set. If you rerun the +program, you will need to set all such watchpoints again. One way of +doing that would be to set a code breakpoint at the entry to the 'main' +function and when it breaks, set all the watchpoints. + + In multi-threaded programs, watchpoints will detect changes to the +watched expression from every thread. + + _Warning:_ In multi-threaded programs, software watchpoints have + only limited usefulness. If GDB creates a software watchpoint, it + can only watch the value of an expression _in a single thread_. If + you are confident that the expression can only change due to the + current thread's activity (and if you are also confident that no + other thread can become current), then you can use software + watchpoints as usual. However, GDB may not notice when a + non-current thread's activity changes the expression. (Hardware + watchpoints, in contrast, watch an expression in all threads.) + + *Note set remote hardware-watchpoint-limit::. + + +File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints + +5.1.3 Setting Catchpoints +------------------------- + +You can use "catchpoints" to cause the debugger to stop for certain +kinds of program events, such as C++ exceptions or the loading of a +shared library. Use the 'catch' command to set a catchpoint. + +'catch EVENT' + Stop when EVENT occurs. EVENT can be any of the following: + + 'throw [REGEXP]' + 'rethrow [REGEXP]' + 'catch [REGEXP]' + The throwing, re-throwing, or catching of a C++ exception. + + If REGEXP is given, then only exceptions whose type matches + the regular expression will be caught. + + The convenience variable '$_exception' is available at an + exception-related catchpoint, on some systems. This holds the + exception being thrown. + + There are currently some limitations to C++ exception handling + in GDB: + + * The support for these commands is system-dependent. + Currently, only systems using the 'gnu-v3' C++ ABI (*note + ABI::) are supported. + + * The regular expression feature and the '$_exception' + convenience variable rely on the presence of some SDT + probes in 'libstdc++'. If these probes are not present, + then these features cannot be used. These probes were + first available in the GCC 4.8 release, but whether or + not they are available in your GCC also depends on how it + was built. + + * The '$_exception' convenience variable is only valid at + the instruction at which an exception-related catchpoint + is set. + + * When an exception-related catchpoint is hit, GDB stops at + a location in the system library which implements runtime + exception support for C++, usually 'libstdc++'. You can + use 'up' (*note Selection::) to get to your code. + + * If you call a function interactively, GDB normally + returns control to you when the function has finished + executing. If the call raises an exception, however, the + call may bypass the mechanism that returns control to you + and cause your program either to abort or to simply + continue running until it hits a breakpoint, catches a + signal that GDB is listening for, or exits. This is the + case even if you set a catchpoint for the exception; + catchpoints on exceptions are disabled within interactive + calls. *Note Calling::, for information on controlling + this with 'set unwind-on-terminating-exception'. + + * You cannot raise an exception interactively. + + * You cannot install an exception handler interactively. + + 'exception' + An Ada exception being raised. If an exception name is + specified at the end of the command (eg 'catch exception + Program_Error'), the debugger will stop only when this + specific exception is raised. Otherwise, the debugger stops + execution when any Ada exception is raised. + + When inserting an exception catchpoint on a user-defined + exception whose name is identical to one of the exceptions + defined by the language, the fully qualified name must be used + as the exception name. Otherwise, GDB will assume that it + should stop on the pre-defined exception rather than the + user-defined one. For instance, assuming an exception called + 'Constraint_Error' is defined in package 'Pck', then the + command to use to catch such exceptions is 'catch exception + Pck.Constraint_Error'. + + 'exception unhandled' + An exception that was raised but is not handled by the + program. + + 'assert' + A failed Ada assertion. + + 'exec' + A call to 'exec'. This is currently only available for HP-UX + and GNU/Linux. + + 'syscall' + 'syscall [NAME | NUMBER] ...' + A call to or return from a system call, a.k.a. "syscall". A + syscall is a mechanism for application programs to request a + service from the operating system (OS) or one of the OS system + services. GDB can catch some or all of the syscalls issued by + the debuggee, and show the related information for each + syscall. If no argument is specified, calls to and returns + from all system calls will be caught. + + NAME can be any system call name that is valid for the + underlying OS. Just what syscalls are valid depends on the OS. + On GNU and Unix systems, you can find the full list of valid + syscall names on '/usr/include/asm/unistd.h'. + + Normally, GDB knows in advance which syscalls are valid for + each OS, so you can use the GDB command-line completion + facilities (*note command completion: Completion.) to list the + available choices. + + You may also specify the system call numerically. A syscall's + number is the value passed to the OS's syscall dispatcher to + identify the requested service. When you specify the syscall + by its name, GDB uses its database of syscalls to convert the + name into the corresponding numeric code, but using the number + directly may be useful if GDB's database does not have the + complete list of syscalls on your system (e.g., because GDB + lags behind the OS upgrades). + + The example below illustrates how this command works if you + don't provide arguments to it: + + (gdb) catch syscall + Catchpoint 1 (syscall) + (gdb) r + Starting program: /tmp/catch-syscall + + Catchpoint 1 (call to syscall 'close'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) c + Continuing. + + Catchpoint 1 (returned from syscall 'close'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) + + Here is an example of catching a system call by name: + + (gdb) catch syscall chroot + Catchpoint 1 (syscall 'chroot' [61]) + (gdb) r + Starting program: /tmp/catch-syscall + + Catchpoint 1 (call to syscall 'chroot'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) c + Continuing. + + Catchpoint 1 (returned from syscall 'chroot'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) + + An example of specifying a system call numerically. In the + case below, the syscall number has a corresponding entry in + the XML file, so GDB finds its name and prints it: + + (gdb) catch syscall 252 + Catchpoint 1 (syscall(s) 'exit_group') + (gdb) r + Starting program: /tmp/catch-syscall + + Catchpoint 1 (call to syscall 'exit_group'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) c + Continuing. + + Program exited normally. + (gdb) + + However, there can be situations when there is no + corresponding name in XML file for that syscall number. In + this case, GDB prints a warning message saying that it was not + able to find the syscall name, but the catchpoint will be set + anyway. See the example below: + + (gdb) catch syscall 764 + warning: The number '764' does not represent a known syscall. + Catchpoint 2 (syscall 764) + (gdb) + + If you configure GDB using the '--without-expat' option, it + will not be able to display syscall names. Also, if your + architecture does not have an XML file describing its system + calls, you will not be able to see the syscall names. It is + important to notice that these two features are used for + accessing the syscall name database. In either case, you will + see a warning like this: + + (gdb) catch syscall + warning: Could not open "syscalls/i386-linux.xml" + warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. + GDB will not be able to display syscall names. + Catchpoint 1 (syscall) + (gdb) + + Of course, the file name will change depending on your + architecture and system. + + Still using the example above, you can also try to catch a + syscall by its number. In this case, you would see something + like: + + (gdb) catch syscall 252 + Catchpoint 1 (syscall(s) 252) + + Again, in this case GDB would not be able to display syscall's + names. + + 'fork' + A call to 'fork'. This is currently only available for HP-UX + and GNU/Linux. + + 'vfork' + A call to 'vfork'. This is currently only available for HP-UX + and GNU/Linux. + + 'load [regexp]' + 'unload [regexp]' + The loading or unloading of a shared library. If REGEXP is + given, then the catchpoint will stop only if the regular + expression matches one of the affected libraries. + + 'signal [SIGNAL... | 'all']' + The delivery of a signal. + + With no arguments, this catchpoint will catch any signal that + is not used internally by GDB, specifically, all signals + except 'SIGTRAP' and 'SIGINT'. + + With the argument 'all', all signals, including those used by + GDB, will be caught. This argument cannot be used with other + signal names. + + Otherwise, the arguments are a list of signal names as given + to 'handle' (*note Signals::). Only signals specified in this + list will be caught. + + One reason that 'catch signal' can be more useful than + 'handle' is that you can attach commands and conditions to the + catchpoint. + + When a signal is caught by a catchpoint, the signal's 'stop' + and 'print' settings, as specified by 'handle', are ignored. + However, whether the signal is still delivered to the inferior + depends on the 'pass' setting; this can be changed in the + catchpoint's commands. + +'tcatch EVENT' + Set a catchpoint that is enabled only for one stop. The catchpoint + is automatically deleted after the first time the event is caught. + + Use the 'info break' command to list the current catchpoints. + + +File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints + +5.1.4 Deleting Breakpoints +-------------------------- + +It is often necessary to eliminate a breakpoint, watchpoint, or +catchpoint once it has done its job and you no longer want your program +to stop there. This is called "deleting" the breakpoint. A breakpoint +that has been deleted no longer exists; it is forgotten. + + With the 'clear' command you can delete breakpoints according to +where they are in your program. With the 'delete' command you can +delete individual breakpoints, watchpoints, or catchpoints by specifying +their breakpoint numbers. + + It is not necessary to delete a breakpoint to proceed past it. GDB +automatically ignores breakpoints on the first instruction to be +executed when you continue execution without changing the execution +address. + +'clear' + Delete any breakpoints at the next instruction to be executed in + the selected stack frame (*note Selecting a Frame: Selection.). + When the innermost frame is selected, this is a good way to delete + a breakpoint where your program just stopped. + +'clear LOCATION' + Delete any breakpoints set at the specified LOCATION. *Note + Specify Location::, for the various forms of LOCATION; the most + useful ones are listed below: + + 'clear FUNCTION' + 'clear FILENAME:FUNCTION' + Delete any breakpoints set at entry to the named FUNCTION. + + 'clear LINENUM' + 'clear FILENAME:LINENUM' + Delete any breakpoints set at or within the code of the + specified LINENUM of the specified FILENAME. + +'delete [breakpoints] [RANGE...]' + Delete the breakpoints, watchpoints, or catchpoints of the + breakpoint ranges specified as arguments. If no argument is + specified, delete all breakpoints (GDB asks confirmation, unless + you have 'set confirm off'). You can abbreviate this command as + 'd'. + + +File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints + +5.1.5 Disabling Breakpoints +--------------------------- + +Rather than deleting a breakpoint, watchpoint, or catchpoint, you might +prefer to "disable" it. This makes the breakpoint inoperative as if it +had been deleted, but remembers the information on the breakpoint so +that you can "enable" it again later. + + You disable and enable breakpoints, watchpoints, and catchpoints with +the 'enable' and 'disable' commands, optionally specifying one or more +breakpoint numbers as arguments. Use 'info break' to print a list of +all breakpoints, watchpoints, and catchpoints if you do not know which +numbers to use. + + Disabling and enabling a breakpoint that has multiple locations +affects all of its locations. + + A breakpoint, watchpoint, or catchpoint can have any of several +different states of enablement: + + * Enabled. The breakpoint stops your program. A breakpoint set with + the 'break' command starts out in this state. + * Disabled. The breakpoint has no effect on your program. + * Enabled once. The breakpoint stops your program, but then becomes + disabled. + * Enabled for a count. The breakpoint stops your program for the + next N times, then becomes disabled. + * Enabled for deletion. The breakpoint stops your program, but + immediately after it does so it is deleted permanently. A + breakpoint set with the 'tbreak' command starts out in this state. + + You can use the following commands to enable or disable breakpoints, +watchpoints, and catchpoints: + +'disable [breakpoints] [RANGE...]' + Disable the specified breakpoints--or all breakpoints, if none are + listed. A disabled breakpoint has no effect but is not forgotten. + All options such as ignore-counts, conditions and commands are + remembered in case the breakpoint is enabled again later. You may + abbreviate 'disable' as 'dis'. + +'enable [breakpoints] [RANGE...]' + Enable the specified breakpoints (or all defined breakpoints). + They become effective once again in stopping your program. + +'enable [breakpoints] once RANGE...' + Enable the specified breakpoints temporarily. GDB disables any of + these breakpoints immediately after stopping your program. + +'enable [breakpoints] count COUNT RANGE...' + Enable the specified breakpoints temporarily. GDB records COUNT + with each of the specified breakpoints, and decrements a + breakpoint's count when it is hit. When any count reaches 0, GDB + disables that breakpoint. If a breakpoint has an ignore count + (*note Break Conditions: Conditions.), that will be decremented to + 0 before COUNT is affected. + +'enable [breakpoints] delete RANGE...' + Enable the specified breakpoints to work once, then die. GDB + deletes any of these breakpoints as soon as your program stops + there. Breakpoints set by the 'tbreak' command start out in this + state. + + Except for a breakpoint set with 'tbreak' (*note Setting Breakpoints: +Set Breaks.), breakpoints that you set are initially enabled; +subsequently, they become disabled or enabled only when you use one of +the commands above. (The command 'until' can set and delete a +breakpoint of its own, but it does not change the state of your other +breakpoints; see *note Continuing and Stepping: Continuing and +Stepping.) + + +File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints + +5.1.6 Break Conditions +---------------------- + +The simplest sort of breakpoint breaks every time your program reaches a +specified place. You can also specify a "condition" for a breakpoint. +A condition is just a Boolean expression in your programming language +(*note Expressions: Expressions.). A breakpoint with a condition +evaluates the expression each time your program reaches it, and your +program stops only if the condition is _true_. + + This is the converse of using assertions for program validation; in +that situation, you want to stop when the assertion is violated--that +is, when the condition is false. In C, if you want to test an assertion +expressed by the condition ASSERT, you should set the condition '! +ASSERT' on the appropriate breakpoint. + + Conditions are also accepted for watchpoints; you may not need them, +since a watchpoint is inspecting the value of an expression anyhow--but +it might be simpler, say, to just set a watchpoint on a variable name, +and specify a condition that tests whether the new value is an +interesting one. + + Break conditions can have side effects, and may even call functions +in your program. This can be useful, for example, to activate functions +that log program progress, or to use your own print functions to format +special data structures. The effects are completely predictable unless +there is another enabled breakpoint at the same address. (In that case, +GDB might see the other breakpoint first and stop your program without +checking the condition of this one.) Note that breakpoint commands are +usually more convenient and flexible than break conditions for the +purpose of performing side effects when a breakpoint is reached (*note +Breakpoint Command Lists: Break Commands.). + + Breakpoint conditions can also be evaluated on the target's side if +the target supports it. Instead of evaluating the conditions locally, +GDB encodes the expression into an agent expression (*note Agent +Expressions::) suitable for execution on the target, independently of +GDB. Global variables become raw memory locations, locals become stack +accesses, and so forth. + + In this case, GDB will only be notified of a breakpoint trigger when +its condition evaluates to true. This mechanism may provide faster +response times depending on the performance characteristics of the +target since it does not need to keep GDB informed about every +breakpoint trigger, even those with false conditions. + + Break conditions can be specified when a breakpoint is set, by using +'if' in the arguments to the 'break' command. *Note Setting +Breakpoints: Set Breaks. They can also be changed at any time with the +'condition' command. + + You can also use the 'if' keyword with the 'watch' command. The +'catch' command does not recognize the 'if' keyword; 'condition' is the +only way to impose a further condition on a catchpoint. + +'condition BNUM EXPRESSION' + Specify EXPRESSION as the break condition for breakpoint, + watchpoint, or catchpoint number BNUM. After you set a condition, + breakpoint BNUM stops your program only if the value of EXPRESSION + is true (nonzero, in C). When you use 'condition', GDB checks + EXPRESSION immediately for syntactic correctness, and to determine + whether symbols in it have referents in the context of your + breakpoint. If EXPRESSION uses symbols not referenced in the + context of the breakpoint, GDB prints an error message: + + No symbol "foo" in current context. + + GDB does not actually evaluate EXPRESSION at the time the + 'condition' command (or a command that sets a breakpoint with a + condition, like 'break if ...') is given, however. *Note + Expressions: Expressions. + +'condition BNUM' + Remove the condition from breakpoint number BNUM. It becomes an + ordinary unconditional breakpoint. + + A special case of a breakpoint condition is to stop only when the +breakpoint has been reached a certain number of times. This is so +useful that there is a special way to do it, using the "ignore count" of +the breakpoint. Every breakpoint has an ignore count, which is an +integer. Most of the time, the ignore count is zero, and therefore has +no effect. But if your program reaches a breakpoint whose ignore count +is positive, then instead of stopping, it just decrements the ignore +count by one and continues. As a result, if the ignore count value is +N, the breakpoint does not stop the next N times your program reaches +it. + +'ignore BNUM COUNT' + Set the ignore count of breakpoint number BNUM to COUNT. The next + COUNT times the breakpoint is reached, your program's execution + does not stop; other than to decrement the ignore count, GDB takes + no action. + + To make the breakpoint stop the next time it is reached, specify a + count of zero. + + When you use 'continue' to resume execution of your program from a + breakpoint, you can specify an ignore count directly as an argument + to 'continue', rather than using 'ignore'. *Note Continuing and + Stepping: Continuing and Stepping. + + If a breakpoint has a positive ignore count and a condition, the + condition is not checked. Once the ignore count reaches zero, GDB + resumes checking the condition. + + You could achieve the effect of the ignore count with a condition + such as '$foo-- <= 0' using a debugger convenience variable that is + decremented each time. *Note Convenience Variables: Convenience + Vars. + + Ignore counts apply to breakpoints, watchpoints, and catchpoints. + + +File: gdb.info, Node: Break Commands, Next: Dynamic Printf, Prev: Conditions, Up: Breakpoints + +5.1.7 Breakpoint Command Lists +------------------------------ + +You can give any breakpoint (or watchpoint or catchpoint) a series of +commands to execute when your program stops due to that breakpoint. For +example, you might want to print the values of certain expressions, or +enable other breakpoints. + +'commands [RANGE...]' +'... COMMAND-LIST ...' +'end' + Specify a list of commands for the given breakpoints. The commands + themselves appear on the following lines. Type a line containing + just 'end' to terminate the commands. + + To remove all commands from a breakpoint, type 'commands' and + follow it immediately with 'end'; that is, give no commands. + + With no argument, 'commands' refers to the last breakpoint, + watchpoint, or catchpoint set (not to the breakpoint most recently + encountered). If the most recent breakpoints were set with a + single command, then the 'commands' will apply to all the + breakpoints set by that command. This applies to breakpoints set + by 'rbreak', and also applies when a single 'break' command creates + multiple breakpoints (*note Ambiguous Expressions: Ambiguous + Expressions.). + + Pressing as a means of repeating the last GDB command is +disabled within a COMMAND-LIST. + + You can use breakpoint commands to start your program up again. +Simply use the 'continue' command, or 'step', or any other command that +resumes execution. + + Any other commands in the command list, after a command that resumes +execution, are ignored. This is because any time you resume execution +(even with a simple 'next' or 'step'), you may encounter another +breakpoint--which could have its own command list, leading to +ambiguities about which list to execute. + + If the first command you specify in a command list is 'silent', the +usual message about stopping at a breakpoint is not printed. This may +be desirable for breakpoints that are to print a specific message and +then continue. If none of the remaining commands print anything, you +see no sign that the breakpoint was reached. 'silent' is meaningful +only at the beginning of a breakpoint command list. + + The commands 'echo', 'output', and 'printf' allow you to print +precisely controlled output, and are often useful in silent breakpoints. +*Note Commands for Controlled Output: Output. + + For example, here is how you could use breakpoint commands to print +the value of 'x' at entry to 'foo' whenever 'x' is positive. + + break foo if x>0 + commands + silent + printf "x is %d\n",x + cont + end + + One application for breakpoint commands is to compensate for one bug +so you can test for another. Put a breakpoint just after the erroneous +line of code, give it a condition to detect the case in which something +erroneous has been done, and give it commands to assign correct values +to any variables that need them. End with the 'continue' command so +that your program does not stop, and start with the 'silent' command so +that no output is produced. Here is an example: + + break 403 + commands + silent + set x = y + 4 + cont + end + + +File: gdb.info, Node: Dynamic Printf, Next: Save Breakpoints, Prev: Break Commands, Up: Breakpoints + +5.1.8 Dynamic Printf +-------------------- + +The dynamic printf command 'dprintf' combines a breakpoint with +formatted printing of your program's data to give you the effect of +inserting 'printf' calls into your program on-the-fly, without having to +recompile it. + + In its most basic form, the output goes to the GDB console. However, +you can set the variable 'dprintf-style' for alternate handling. For +instance, you can ask to format the output by calling your program's +'printf' function. This has the advantage that the characters go to the +program's output device, so they can recorded in redirects to files and +so forth. + + If you are doing remote debugging with a stub or agent, you can also +ask to have the printf handled by the remote agent. In addition to +ensuring that the output goes to the remote program's device along with +any other output the program might produce, you can also ask that the +dprintf remain active even after disconnecting from the remote target. +Using the stub/agent is also more efficient, as it can do everything +without needing to communicate with GDB. + +'dprintf LOCATION,TEMPLATE,EXPRESSION[,EXPRESSION...]' + Whenever execution reaches LOCATION, print the values of one or + more EXPRESSIONS under the control of the string TEMPLATE. To + print several values, separate them with commas. + +'set dprintf-style STYLE' + Set the dprintf output to be handled in one of several different + styles enumerated below. A change of style affects all existing + dynamic printfs immediately. (If you need individual control over + the print commands, simply define normal breakpoints with + explicitly-supplied command lists.) + +'gdb' + Handle the output using the GDB 'printf' command. + +'call' + Handle the output by calling a function in your program (normally + 'printf'). + +'agent' + Have the remote debugging agent (such as 'gdbserver') handle the + output itself. This style is only available for agents that + support running commands on the target. + +'set dprintf-function FUNCTION' + Set the function to call if the dprintf style is 'call'. By + default its value is 'printf'. You may set it to any expression. + that GDB can evaluate to a function, as per the 'call' command. + +'set dprintf-channel CHANNEL' + Set a "channel" for dprintf. If set to a non-empty value, GDB will + evaluate it as an expression and pass the result as a first + argument to the 'dprintf-function', in the manner of 'fprintf' and + similar functions. Otherwise, the dprintf format string will be + the first argument, in the manner of 'printf'. + + As an example, if you wanted 'dprintf' output to go to a logfile + that is a standard I/O stream assigned to the variable 'mylog', you + could do the following: + + (gdb) set dprintf-style call + (gdb) set dprintf-function fprintf + (gdb) set dprintf-channel mylog + (gdb) dprintf 25,"at line 25, glob=%d\n",glob + Dprintf 1 at 0x123456: file main.c, line 25. + (gdb) info break + 1 dprintf keep y 0x00123456 in main at main.c:25 + call (void) fprintf (mylog,"at line 25, glob=%d\n",glob) + continue + (gdb) + + Note that the 'info break' displays the dynamic printf commands as + normal breakpoint commands; you can thus easily see the effect of + the variable settings. + +'set disconnected-dprintf on' +'set disconnected-dprintf off' + Choose whether 'dprintf' commands should continue to run if GDB has + disconnected from the target. This only applies if the + 'dprintf-style' is 'agent'. + +'show disconnected-dprintf off' + Show the current choice for disconnected 'dprintf'. + + GDB does not check the validity of function and channel, relying on +you to supply values that are meaningful for the contexts in which they +are being used. For instance, the function and channel may be the +values of local variables, but if that is the case, then all enabled +dynamic prints must be at locations within the scope of those locals. +If evaluation fails, GDB will report an error. + + +File: gdb.info, Node: Save Breakpoints, Next: Static Probe Points, Prev: Dynamic Printf, Up: Breakpoints + +5.1.9 How to save breakpoints to a file +--------------------------------------- + +To save breakpoint definitions to a file use the 'save breakpoints' +command. + +'save breakpoints [FILENAME]' + This command saves all current breakpoint definitions together with + their commands and ignore counts, into a file 'FILENAME' suitable + for use in a later debugging session. This includes all types of + breakpoints (breakpoints, watchpoints, catchpoints, tracepoints). + To read the saved breakpoint definitions, use the 'source' command + (*note Command Files::). Note that watchpoints with expressions + involving local variables may fail to be recreated because it may + not be possible to access the context where the watchpoint is valid + anymore. Because the saved breakpoint definitions are simply a + sequence of GDB commands that recreate the breakpoints, you can + edit the file in your favorite editing program, and remove the + breakpoint definitions you're not interested in, or that can no + longer be recreated. + + +File: gdb.info, Node: Static Probe Points, Next: Error in Breakpoints, Prev: Save Breakpoints, Up: Breakpoints + +5.1.10 Static Probe Points +-------------------------- + +GDB supports "SDT" probes in the code. SDT stands for Statically +Defined Tracing, and the probes are designed to have a tiny runtime code +and data footprint, and no dynamic relocations. They are usable from +assembly, C and C++ languages. See + for +a good reference on how the SDT probes are implemented. + + Currently, 'SystemTap' () SDT +probes are supported on ELF-compatible systems. See + for +more information on how to add 'SystemTap' SDT probes in your +applications. + + Some probes have an associated semaphore variable; for instance, this +happens automatically if you defined your probe using a DTrace-style +'.d' file. If your probe has a semaphore, GDB will automatically enable +it when you specify a breakpoint using the '-probe-stap' notation. But, +if you put a breakpoint at a probe's location by some other method +(e.g., 'break file:line'), then GDB will not automatically set the +semaphore. + + You can examine the available static static probes using 'info +probes', with optional arguments: + +'info probes stap [PROVIDER [NAME [OBJFILE]]]' + If given, PROVIDER is a regular expression used to match against + provider names when selecting which probes to list. If omitted, + probes by all probes from all providers are listed. + + If given, NAME is a regular expression to match against probe names + when selecting which probes to list. If omitted, probe names are + not considered when deciding whether to display them. + + If given, OBJFILE is a regular expression used to select which + object files (executable or shared libraries) to examine. If not + given, all object files are considered. + +'info probes all' + List the available static probes, from all types. + + A probe may specify up to twelve arguments. These are available at +the point at which the probe is defined--that is, when the current PC is +at the probe's location. The arguments are available using the +convenience variables (*note Convenience Vars::) +'$_probe_arg0'...'$_probe_arg11'. Each probe argument is an integer of +the appropriate size; types are not preserved. The convenience variable +'$_probe_argc' holds the number of arguments at the current probe point. + + These variables are always available, but attempts to access them at +any location other than a probe point will cause GDB to give an error +message. + + +File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Static Probe Points, Up: Breakpoints + +5.1.11 "Cannot insert breakpoints" +---------------------------------- + +If you request too many active hardware-assisted breakpoints and +watchpoints, you will see this error message: + + Stopped; cannot insert breakpoints. + You may have requested too many hardware breakpoints and watchpoints. + +This message is printed when you attempt to resume the program, since +only then GDB knows exactly how many hardware breakpoints and +watchpoints it needs to insert. + + When this message is printed, you need to disable or remove some of +the hardware-assisted breakpoints and watchpoints, and then continue. + + +File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints + +5.1.12 "Breakpoint address adjusted..." +--------------------------------------- + +Some processor architectures place constraints on the addresses at which +breakpoints may be placed. For architectures thus constrained, GDB will +attempt to adjust the breakpoint's address to comply with the +constraints dictated by the architecture. + + One example of such an architecture is the Fujitsu FR-V. The FR-V is +a VLIW architecture in which a number of RISC-like instructions may be +bundled together for parallel execution. The FR-V architecture +constrains the location of a breakpoint instruction within such a bundle +to the instruction with the lowest address. GDB honors this constraint +by adjusting a breakpoint's address to the first in the bundle. + + It is not uncommon for optimized code to have bundles which contain +instructions from different source statements, thus it may happen that a +breakpoint's address will be adjusted from one source statement to +another. Since this adjustment may significantly alter GDB's breakpoint +related behavior from what the user expects, a warning is printed when +the breakpoint is first set and also when the breakpoint is hit. + + A warning like the one below is printed when setting a breakpoint +that's been subject to address adjustment: + + warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. + + Such warnings are printed both for user settable and GDB's internal +breakpoints. If you see one of these warnings, you should verify that a +breakpoint set at the adjusted address will have the desired affect. If +not, the breakpoint in question may be removed and other breakpoints may +be set which will have the desired behavior. E.g., it may be sufficient +to place the breakpoint at a later instruction. A conditional +breakpoint may also be useful in some cases to prevent the breakpoint +from triggering too often. + + GDB will also issue a warning when stopping at one of these adjusted +breakpoints: + + warning: Breakpoint 1 address previously adjusted from 0x00010414 + to 0x00010410. + + When this warning is encountered, it may be too late to take remedial +action except in cases where the breakpoint is hit earlier or more +frequently than expected. + + +File: gdb.info, Node: Continuing and Stepping, Next: Skipping Over Functions and Files, Prev: Breakpoints, Up: Stopping + +5.2 Continuing and Stepping +=========================== + +"Continuing" means resuming program execution until your program +completes normally. In contrast, "stepping" means executing just one +more "step" of your program, where "step" may mean either one line of +source code, or one machine instruction (depending on what particular +command you use). Either when continuing or when stepping, your program +may stop even sooner, due to a breakpoint or a signal. (If it stops due +to a signal, you may want to use 'handle', or use 'signal 0' to resume +execution. *Note Signals: Signals.) + +'continue [IGNORE-COUNT]' +'c [IGNORE-COUNT]' +'fg [IGNORE-COUNT]' + Resume program execution, at the address where your program last + stopped; any breakpoints set at that address are bypassed. The + optional argument IGNORE-COUNT allows you to specify a further + number of times to ignore a breakpoint at this location; its effect + is like that of 'ignore' (*note Break Conditions: Conditions.). + + The argument IGNORE-COUNT is meaningful only when your program + stopped due to a breakpoint. At other times, the argument to + 'continue' is ignored. + + The synonyms 'c' and 'fg' (for "foreground", as the debugged + program is deemed to be the foreground program) are provided purely + for convenience, and have exactly the same behavior as 'continue'. + + To resume execution at a different place, you can use 'return' (*note +Returning from a Function: Returning.) to go back to the calling +function; or 'jump' (*note Continuing at a Different Address: Jumping.) +to go to an arbitrary location in your program. + + A typical technique for using stepping is to set a breakpoint (*note +Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the +beginning of the function or the section of your program where a problem +is believed to lie, run your program until it stops at that breakpoint, +and then step through the suspect area, examining the variables that are +interesting, until you see the problem happen. + +'step' + Continue running your program until control reaches a different + source line, then stop it and return control to GDB. This command + is abbreviated 's'. + + _Warning:_ If you use the 'step' command while control is + within a function that was compiled without debugging + information, execution proceeds until control reaches a + function that does have debugging information. Likewise, it + will not step into a function which is compiled without + debugging information. To step through functions without + debugging information, use the 'stepi' command, described + below. + + The 'step' command only stops at the first instruction of a source + line. This prevents the multiple stops that could otherwise occur + in 'switch' statements, 'for' loops, etc. 'step' continues to stop + if a function that has debugging information is called within the + line. In other words, 'step' _steps inside_ any functions called + within the line. + + Also, the 'step' command only enters a function if there is line + number information for the function. Otherwise it acts like the + 'next' command. This avoids problems when using 'cc -gl' on MIPS + machines. Previously, 'step' entered subroutines if there was any + debugging information about the routine. + +'step COUNT' + Continue running as in 'step', but do so COUNT times. If a + breakpoint is reached, or a signal not related to stepping occurs + before COUNT steps, stepping stops right away. + +'next [COUNT]' + Continue to the next source line in the current (innermost) stack + frame. This is similar to 'step', but function calls that appear + within the line of code are executed without stopping. Execution + stops when control reaches a different line of code at the original + stack level that was executing when you gave the 'next' command. + This command is abbreviated 'n'. + + An argument COUNT is a repeat count, as for 'step'. + + The 'next' command only stops at the first instruction of a source + line. This prevents multiple stops that could otherwise occur in + 'switch' statements, 'for' loops, etc. + +'set step-mode' +'set step-mode on' + The 'set step-mode on' command causes the 'step' command to stop at + the first instruction of a function which contains no debug line + information rather than stepping over it. + + This is useful in cases where you may be interested in inspecting + the machine instructions of a function which has no symbolic info + and do not want GDB to automatically skip over this function. + +'set step-mode off' + Causes the 'step' command to step over any functions which contains + no debug information. This is the default. + +'show step-mode' + Show whether GDB will stop in or step over functions without source + line debug information. + +'finish' + Continue running until just after function in the selected stack + frame returns. Print the returned value (if any). This command + can be abbreviated as 'fin'. + + Contrast this with the 'return' command (*note Returning from a + Function: Returning.). + +'until' +'u' + Continue running until a source line past the current line, in the + current stack frame, is reached. This command is used to avoid + single stepping through a loop more than once. It is like the + 'next' command, except that when 'until' encounters a jump, it + automatically continues execution until the program counter is + greater than the address of the jump. + + This means that when you reach the end of a loop after single + stepping though it, 'until' makes your program continue execution + until it exits the loop. In contrast, a 'next' command at the end + of a loop simply steps back to the beginning of the loop, which + forces you to step through the next iteration. + + 'until' always stops your program if it attempts to exit the + current stack frame. + + 'until' may produce somewhat counterintuitive results if the order + of machine code does not match the order of the source lines. For + example, in the following excerpt from a debugging session, the 'f' + ('frame') command shows that execution is stopped at line '206'; + yet when we use 'until', we get to line '195': + + (gdb) f + #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 + 206 expand_input(); + (gdb) until + 195 for ( ; argc > 0; NEXTARG) { + + This happened because, for execution efficiency, the compiler had + generated code for the loop closure test at the end, rather than + the start, of the loop--even though the test in a C 'for'-loop is + written before the body of the loop. The 'until' command appeared + to step back to the beginning of the loop when it advanced to this + expression; however, it has not really gone to an earlier + statement--not in terms of the actual machine code. + + 'until' with no argument works by means of single instruction + stepping, and hence is slower than 'until' with an argument. + +'until LOCATION' +'u LOCATION' + Continue running your program until either the specified location + is reached, or the current stack frame returns. LOCATION is any of + the forms described in *note Specify Location::. This form of the + command uses temporary breakpoints, and hence is quicker than + 'until' without an argument. The specified location is actually + reached only if it is in the current frame. This implies that + 'until' can be used to skip over recursive function invocations. + For instance in the code below, if the current location is line + '96', issuing 'until 99' will execute the program up to line '99' + in the same invocation of factorial, i.e., after the inner + invocations have returned. + + 94 int factorial (int value) + 95 { + 96 if (value > 1) { + 97 value *= factorial (value - 1); + 98 } + 99 return (value); + 100 } + +'advance LOCATION' + Continue running the program up to the given LOCATION. An argument + is required, which should be of one of the forms described in *note + Specify Location::. Execution will also stop upon exit from the + current stack frame. This command is similar to 'until', but + 'advance' will not skip over recursive function calls, and the + target location doesn't have to be in the same frame as the current + one. + +'stepi' +'stepi ARG' +'si' + Execute one machine instruction, then stop and return to the + debugger. + + It is often useful to do 'display/i $pc' when stepping by machine + instructions. This makes GDB automatically display the next + instruction to be executed, each time your program stops. *Note + Automatic Display: Auto Display. + + An argument is a repeat count, as in 'step'. + +'nexti' +'nexti ARG' +'ni' + Execute one machine instruction, but if it is a function call, + proceed until the function returns. + + An argument is a repeat count, as in 'next'. + + By default, and if available, GDB makes use of target-assisted "range +stepping". In other words, whenever you use a stepping command (e.g., +'step', 'next'), GDB tells the target to step the corresponding range of +instruction addresses instead of issuing multiple single-steps. This +speeds up line stepping, particularly for remote targets. Ideally, +there should be no reason you would want to turn range stepping off. +However, it's possible that a bug in the debug info, a bug in the remote +stub (for remote targets), or even a bug in GDB could make line stepping +behave incorrectly when target-assisted range stepping is enabled. You +can use the following command to turn off range stepping if necessary: + +'set range-stepping' +'show range-stepping' + Control whether range stepping is enabled. + + If 'on', and the target supports it, GDB tells the target to step a + range of addresses itself, instead of issuing multiple + single-steps. If 'off', GDB always issues single-steps, even if + range stepping is supported by the target. The default is 'on'. + + +File: gdb.info, Node: Skipping Over Functions and Files, Next: Signals, Prev: Continuing and Stepping, Up: Stopping + +5.3 Skipping Over Functions and Files +===================================== + +The program you are debugging may contain some functions which are +uninteresting to debug. The 'skip' comand lets you tell GDB to skip a +function or all functions in a file when stepping. + + For example, consider the following C function: + + 101 int func() + 102 { + 103 foo(boring()); + 104 bar(boring()); + 105 } + +Suppose you wish to step into the functions 'foo' and 'bar', but you are +not interested in stepping through 'boring'. If you run 'step' at line +103, you'll enter 'boring()', but if you run 'next', you'll step over +both 'foo' and 'boring'! + + One solution is to 'step' into 'boring' and use the 'finish' command +to immediately exit it. But this can become tedious if 'boring' is +called from many places. + + A more flexible solution is to execute 'skip boring'. This instructs +GDB never to step into 'boring'. Now when you execute 'step' at line +103, you'll step over 'boring' and directly into 'foo'. + + You can also instruct GDB to skip all functions in a file, with, for +example, 'skip file boring.c'. + +'skip [LINESPEC]' +'skip function [LINESPEC]' + After running this command, the function named by LINESPEC or the + function containing the line named by LINESPEC will be skipped over + when stepping. *Note Specify Location::. + + If you do not specify LINESPEC, the function you're currently + debugging will be skipped. + + (If you have a function called 'file' that you want to skip, use + 'skip function file'.) + +'skip file [FILENAME]' + After running this command, any function whose source lives in + FILENAME will be skipped over when stepping. + + If you do not specify FILENAME, functions whose source lives in the + file you're currently debugging will be skipped. + + Skips can be listed, deleted, disabled, and enabled, much like +breakpoints. These are the commands for managing your list of skips: + +'info skip [RANGE]' + Print details about the specified skip(s). If RANGE is not + specified, print a table with details about all functions and files + marked for skipping. 'info skip' prints the following information + about each skip: + + _Identifier_ + A number identifying this skip. + _Type_ + The type of this skip, either 'function' or 'file'. + _Enabled or Disabled_ + Enabled skips are marked with 'y'. Disabled skips are marked + with 'n'. + _Address_ + For function skips, this column indicates the address in + memory of the function being skipped. If you've set a + function skip on a function which has not yet been loaded, + this field will contain ''. Once a shared library + which has the function is loaded, 'info skip' will show the + function's address here. + _What_ + For file skips, this field contains the filename being + skipped. For functions skips, this field contains the + function name and its line number in the file where it is + defined. + +'skip delete [RANGE]' + Delete the specified skip(s). If RANGE is not specified, delete + all skips. + +'skip enable [RANGE]' + Enable the specified skip(s). If RANGE is not specified, enable + all skips. + +'skip disable [RANGE]' + Disable the specified skip(s). If RANGE is not specified, disable + all skips. + + +File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Skipping Over Functions and Files, Up: Stopping + +5.4 Signals +=========== + +A signal is an asynchronous event that can happen in a program. The +operating system defines the possible kinds of signals, and gives each +kind a name and a number. For example, in Unix 'SIGINT' is the signal a +program gets when you type an interrupt character (often 'Ctrl-c'); +'SIGSEGV' is the signal a program gets from referencing a place in +memory far away from all the areas in use; 'SIGALRM' occurs when the +alarm clock timer goes off (which happens only if your program has +requested an alarm). + + Some signals, including 'SIGALRM', are a normal part of the +functioning of your program. Others, such as 'SIGSEGV', indicate +errors; these signals are "fatal" (they kill your program immediately) +if the program has not specified in advance some other way to handle the +signal. 'SIGINT' does not indicate an error in your program, but it is +normally fatal so it can carry out the purpose of the interrupt: to kill +the program. + + GDB has the ability to detect any occurrence of a signal in your +program. You can tell GDB in advance what to do for each kind of +signal. + + Normally, GDB is set up to let the non-erroneous signals like +'SIGALRM' be silently passed to your program (so as not to interfere +with their role in the program's functioning) but to stop your program +immediately whenever an error signal happens. You can change these +settings with the 'handle' command. + +'info signals' +'info handle' + Print a table of all the kinds of signals and how GDB has been told + to handle each one. You can use this to see the signal numbers of + all the defined types of signals. + +'info signals SIG' + Similar, but print information only about the specified signal + number. + + 'info handle' is an alias for 'info signals'. + +'catch signal [SIGNAL... | 'all']' + Set a catchpoint for the indicated signals. *Note Set + Catchpoints::, for details about this command. + +'handle SIGNAL [KEYWORDS...]' + Change the way GDB handles signal SIGNAL. SIGNAL can be the number + of a signal or its name (with or without the 'SIG' at the + beginning); a list of signal numbers of the form 'LOW-HIGH'; or the + word 'all', meaning all the known signals. Optional arguments + KEYWORDS, described below, say what change to make. + + The keywords allowed by the 'handle' command can be abbreviated. +Their full names are: + +'nostop' + GDB should not stop your program when this signal happens. It may + still print a message telling you that the signal has come in. + +'stop' + GDB should stop your program when this signal happens. This + implies the 'print' keyword as well. + +'print' + GDB should print a message when this signal happens. + +'noprint' + GDB should not mention the occurrence of the signal at all. This + implies the 'nostop' keyword as well. + +'pass' +'noignore' + GDB should allow your program to see this signal; your program can + handle the signal, or else it may terminate if the signal is fatal + and not handled. 'pass' and 'noignore' are synonyms. + +'nopass' +'ignore' + GDB should not allow your program to see this signal. 'nopass' and + 'ignore' are synonyms. + + When a signal stops your program, the signal is not visible to the +program until you continue. Your program sees the signal then, if +'pass' is in effect for the signal in question _at that time_. In other +words, after GDB reports a signal, you can use the 'handle' command with +'pass' or 'nopass' to control whether your program sees that signal when +you continue. + + The default is set to 'nostop', 'noprint', 'pass' for non-erroneous +signals such as 'SIGALRM', 'SIGWINCH' and 'SIGCHLD', and to 'stop', +'print', 'pass' for the erroneous signals. + + You can also use the 'signal' command to prevent your program from +seeing a signal, or cause it to see a signal it normally would not see, +or to give it any signal at any time. For example, if your program +stopped due to some sort of memory reference error, you might store +correct values into the erroneous variables and continue, hoping to see +more execution; but your program would probably terminate immediately as +a result of the fatal signal once it saw the signal. To prevent this, +you can continue with 'signal 0'. *Note Giving your Program a Signal: +Signaling. + + On some targets, GDB can inspect extra signal information associated +with the intercepted signal, before it is actually delivered to the +program being debugged. This information is exported by the convenience +variable '$_siginfo', and consists of data that is passed by the kernel +to the signal handler at the time of the receipt of a signal. The data +type of the information itself is target dependent. You can see the +data type using the 'ptype $_siginfo' command. On Unix systems, it +typically corresponds to the standard 'siginfo_t' type, as defined in +the 'signal.h' system header. + + Here's an example, on a GNU/Linux system, printing the stray +referenced address that raised a segmentation fault. + + (gdb) continue + Program received signal SIGSEGV, Segmentation fault. + 0x0000000000400766 in main () + 69 *(int *)p = 0; + (gdb) ptype $_siginfo + type = struct { + int si_signo; + int si_errno; + int si_code; + union { + int _pad[28]; + struct {...} _kill; + struct {...} _timer; + struct {...} _rt; + struct {...} _sigchld; + struct {...} _sigfault; + struct {...} _sigpoll; + } _sifields; + } + (gdb) ptype $_siginfo._sifields._sigfault + type = struct { + void *si_addr; + } + (gdb) p $_siginfo._sifields._sigfault.si_addr + $1 = (void *) 0x7ffff7ff7000 + + Depending on target support, '$_siginfo' may also be writable. + + +File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping + +5.5 Stopping and Starting Multi-thread Programs +=============================================== + +GDB supports debugging programs with multiple threads (*note Debugging +Programs with Multiple Threads: Threads.). There are two modes of +controlling execution of your program within the debugger. In the +default mode, referred to as "all-stop mode", when any thread in your +program stops (for example, at a breakpoint or while being stepped), all +other threads in the program are also stopped by GDB. On some targets, +GDB also supports "non-stop mode", in which other threads can continue +to run freely while you examine the stopped thread in the debugger. + +* Menu: + +* All-Stop Mode:: All threads stop when GDB takes control +* Non-Stop Mode:: Other threads continue to execute +* Background Execution:: Running your program asynchronously +* Thread-Specific Breakpoints:: Controlling breakpoints +* Interrupted System Calls:: GDB may interfere with system calls +* Observer Mode:: GDB does not alter program behavior + + +File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops + +5.5.1 All-Stop Mode +------------------- + +In all-stop mode, whenever your program stops under GDB for any reason, +_all_ threads of execution stop, not just the current thread. This +allows you to examine the overall state of the program, including +switching between threads, without worrying that things may change +underfoot. + + Conversely, whenever you restart the program, _all_ threads start +executing. _This is true even when single-stepping_ with commands like +'step' or 'next'. + + In particular, GDB cannot single-step all threads in lockstep. Since +thread scheduling is up to your debugging target's operating system (not +controlled by GDB), other threads may execute more than one statement +while the current thread completes a single step. Moreover, in general +other threads stop in the middle of a statement, rather than at a clean +statement boundary, when the program stops. + + You might even find your program stopped in another thread after +continuing or even single-stepping. This happens whenever some other +thread runs into a breakpoint, a signal, or an exception before the +first thread completes whatever you requested. + + Whenever GDB stops your program, due to a breakpoint or a signal, it +automatically selects the thread where that breakpoint or signal +happened. GDB alerts you to the context switch with a message such as +'[Switching to Thread N]' to identify the thread. + + On some OSes, you can modify GDB's default behavior by locking the OS +scheduler to allow only a single thread to run. + +'set scheduler-locking MODE' + Set the scheduler locking mode. If it is 'off', then there is no + locking and any thread may run at any time. If 'on', then only the + current thread may run when the inferior is resumed. The 'step' + mode optimizes for single-stepping; it prevents other threads from + preempting the current thread while you are stepping, so that the + focus of debugging does not change unexpectedly. Other threads + only rarely (or never) get a chance to run when you step. They are + more likely to run when you 'next' over a function call, and they + are completely free to run when you use commands like 'continue', + 'until', or 'finish'. However, unless another thread hits a + breakpoint during its timeslice, GDB does not change the current + thread away from the thread that you are debugging. + +'show scheduler-locking' + Display the current scheduler locking mode. + + By default, when you issue one of the execution commands such as +'continue', 'next' or 'step', GDB allows only threads of the current +inferior to run. For example, if GDB is attached to two inferiors, each +with two threads, the 'continue' command resumes only the two threads of +the current inferior. This is useful, for example, when you debug a +program that forks and you want to hold the parent stopped (so that, for +instance, it doesn't run to exit), while you debug the child. In other +situations, you may not be interested in inspecting the current state of +any of the processes GDB is attached to, and you may want to resume them +all until some breakpoint is hit. In the latter case, you can instruct +GDB to allow all threads of all the inferiors to run with the 'set schedule-multiple' +command. + +'set schedule-multiple' + Set the mode for allowing threads of multiple processes to be + resumed when an execution command is issued. When 'on', all + threads of all processes are allowed to run. When 'off', only the + threads of the current process are resumed. The default is 'off'. + The 'scheduler-locking' mode takes precedence when set to 'on', or + while you are stepping and set to 'step'. + +'show schedule-multiple' + Display the current mode for resuming the execution of threads of + multiple processes. + + +File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops + +5.5.2 Non-Stop Mode +------------------- + +For some multi-threaded targets, GDB supports an optional mode of +operation in which you can examine stopped program threads in the +debugger while other threads continue to execute freely. This minimizes +intrusion when debugging live systems, such as programs where some +threads have real-time constraints or must continue to respond to +external events. This is referred to as "non-stop" mode. + + In non-stop mode, when a thread stops to report a debugging event, +_only_ that thread is stopped; GDB does not stop other threads as well, +in contrast to the all-stop mode behavior. Additionally, execution +commands such as 'continue' and 'step' apply by default only to the +current thread in non-stop mode, rather than all threads as in all-stop +mode. This allows you to control threads explicitly in ways that are +not possible in all-stop mode -- for example, stepping one thread while +allowing others to run freely, stepping one thread while holding all +others stopped, or stepping several threads independently and +simultaneously. + + To enter non-stop mode, use this sequence of commands before you run +or attach to your program: + + # Enable the async interface. + set target-async 1 + + # If using the CLI, pagination breaks non-stop. + set pagination off + + # Finally, turn it on! + set non-stop on + + You can use these commands to manipulate the non-stop mode setting: + +'set non-stop on' + Enable selection of non-stop mode. +'set non-stop off' + Disable selection of non-stop mode. +'show non-stop' + Show the current non-stop enablement setting. + + Note these commands only reflect whether non-stop mode is enabled, +not whether the currently-executing program is being run in non-stop +mode. In particular, the 'set non-stop' preference is only consulted +when GDB starts or connects to the target program, and it is generally +not possible to switch modes once debugging has started. Furthermore, +since not all targets support non-stop mode, even when you have enabled +non-stop mode, GDB may still fall back to all-stop operation by default. + + In non-stop mode, all execution commands apply only to the current +thread by default. That is, 'continue' only continues one thread. To +continue all threads, issue 'continue -a' or 'c -a'. + + You can use GDB's background execution commands (*note Background +Execution::) to run some threads in the background while you continue to +examine or step others from GDB. The MI execution commands (*note +GDB/MI Program Execution::) are always executed asynchronously in +non-stop mode. + + Suspending execution is done with the 'interrupt' command when +running in the background, or 'Ctrl-c' during foreground execution. In +all-stop mode, this stops the whole process; but in non-stop mode the +interrupt applies only to the current thread. To stop the whole +program, use 'interrupt -a'. + + Other execution commands do not currently support the '-a' option. + + In non-stop mode, when a thread stops, GDB doesn't automatically make +that thread current, as it does in all-stop mode. This is because the +thread stop notifications are asynchronous with respect to GDB's command +interpreter, and it would be confusing if GDB unexpectedly changed to a +different thread just as you entered a command to operate on the +previously current thread. + + +File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops + +5.5.3 Background Execution +-------------------------- + +GDB's execution commands have two variants: the normal foreground +(synchronous) behavior, and a background (asynchronous) behavior. In +foreground execution, GDB waits for the program to report that some +thread has stopped before prompting for another command. In background +execution, GDB immediately gives a command prompt so that you can issue +other commands while your program runs. + + You need to explicitly enable asynchronous mode before you can use +background execution commands. You can use these commands to manipulate +the asynchronous mode setting: + +'set target-async on' + Enable asynchronous mode. +'set target-async off' + Disable asynchronous mode. +'show target-async' + Show the current target-async setting. + + If the target doesn't support async mode, GDB issues an error message +if you attempt to use the background execution commands. + + To specify background execution, add a '&' to the command. For +example, the background form of the 'continue' command is 'continue&', +or just 'c&'. The execution commands that accept background execution +are: + +'run' + *Note Starting your Program: Starting. + +'attach' + *Note Debugging an Already-running Process: Attach. + +'step' + *Note step: Continuing and Stepping. + +'stepi' + *Note stepi: Continuing and Stepping. + +'next' + *Note next: Continuing and Stepping. + +'nexti' + *Note nexti: Continuing and Stepping. + +'continue' + *Note continue: Continuing and Stepping. + +'finish' + *Note finish: Continuing and Stepping. + +'until' + *Note until: Continuing and Stepping. + + Background execution is especially useful in conjunction with +non-stop mode for debugging programs with multiple threads; see *note +Non-Stop Mode::. However, you can also use these commands in the normal +all-stop mode with the restriction that you cannot issue another +execution command until the previous one finishes. Examples of commands +that are valid in all-stop mode while the program is running include +'help' and 'info break'. + + You can interrupt your program while it is running in the background +by using the 'interrupt' command. + +'interrupt' +'interrupt -a' + + Suspend execution of the running program. In all-stop mode, + 'interrupt' stops the whole process, but in non-stop mode, it stops + only the current thread. To stop the whole program in non-stop + mode, use 'interrupt -a'. + + +File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops + +5.5.4 Thread-Specific Breakpoints +--------------------------------- + +When your program has multiple threads (*note Debugging Programs with +Multiple Threads: Threads.), you can choose whether to set breakpoints +on all threads, or on a particular thread. + +'break LINESPEC thread THREADNO' +'break LINESPEC thread THREADNO if ...' + LINESPEC specifies source lines; there are several ways of writing + them (*note Specify Location::), but the effect is always to + specify some source line. + + Use the qualifier 'thread THREADNO' with a breakpoint command to + specify that you only want GDB to stop the program when a + particular thread reaches this breakpoint. THREADNO is one of the + numeric thread identifiers assigned by GDB, shown in the first + column of the 'info threads' display. + + If you do not specify 'thread THREADNO' when you set a breakpoint, + the breakpoint applies to _all_ threads of your program. + + You can use the 'thread' qualifier on conditional breakpoints as + well; in this case, place 'thread THREADNO' before or after the + breakpoint condition, like this: + + (gdb) break frik.c:13 thread 28 if bartab > lim + + Thread-specific breakpoints are automatically deleted when GDB +detects the corresponding thread is no longer in the thread list. For +example: + + (gdb) c + Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list. + + There are several ways for a thread to disappear, such as a regular +thread exit, but also when you detach from the process with the 'detach' +command (*note Debugging an Already-running Process: Attach.), or if GDB +loses the remote connection (*note Remote Debugging::), etc. Note that +with some targets, GDB is only able to detect a thread has exited when +the user explictly asks for the thread list with the 'info threads' +command. + + +File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops + +5.5.5 Interrupted System Calls +------------------------------ + +There is an unfortunate side effect when using GDB to debug +multi-threaded programs. If one thread stops for a breakpoint, or for +some other reason, and another thread is blocked in a system call, then +the system call may return prematurely. This is a consequence of the +interaction between multiple threads and the signals that GDB uses to +implement breakpoints and other events that stop execution. + + To handle this problem, your program should check the return value of +each system call and react appropriately. This is good programming +style anyways. + + For example, do not write code like this: + + sleep (10); + + The call to 'sleep' will return early if a different thread stops at +a breakpoint or for some other reason. + + Instead, write this: + + int unslept = 10; + while (unslept > 0) + unslept = sleep (unslept); + + A system call is allowed to return early, so the system is still +conforming to its specification. But GDB does cause your multi-threaded +program to behave differently than it would without GDB. + + Also, GDB uses internal breakpoints in the thread library to monitor +certain events such as thread creation and thread destruction. When +such an event happens, a system call in another thread may return +prematurely, even though your program does not appear to stop. + + +File: gdb.info, Node: Observer Mode, Prev: Interrupted System Calls, Up: Thread Stops + +5.5.6 Observer Mode +------------------- + +If you want to build on non-stop mode and observe program behavior +without any chance of disruption by GDB, you can set variables to +disable all of the debugger's attempts to modify state, whether by +writing memory, inserting breakpoints, etc. These operate at a low +level, intercepting operations from all commands. + + When all of these are set to 'off', then GDB is said to be "observer +mode". As a convenience, the variable 'observer' can be set to disable +these, plus enable non-stop mode. + + Note that GDB will not prevent you from making nonsensical +combinations of these settings. For instance, if you have enabled +'may-insert-breakpoints' but disabled 'may-write-memory', then +breakpoints that work by writing trap instructions into the code stream +will still not be able to be placed. + +'set observer on' +'set observer off' + When set to 'on', this disables all the permission variables below + (except for 'insert-fast-tracepoints'), plus enables non-stop + debugging. Setting this to 'off' switches back to normal + debugging, though remaining in non-stop mode. + +'show observer' + Show whether observer mode is on or off. + +'set may-write-registers on' +'set may-write-registers off' + This controls whether GDB will attempt to alter the values of + registers, such as with assignment expressions in 'print', or the + 'jump' command. It defaults to 'on'. + +'show may-write-registers' + Show the current permission to write registers. + +'set may-write-memory on' +'set may-write-memory off' + This controls whether GDB will attempt to alter the contents of + memory, such as with assignment expressions in 'print'. It + defaults to 'on'. + +'show may-write-memory' + Show the current permission to write memory. + +'set may-insert-breakpoints on' +'set may-insert-breakpoints off' + This controls whether GDB will attempt to insert breakpoints. This + affects all breakpoints, including internal breakpoints defined by + GDB. It defaults to 'on'. + +'show may-insert-breakpoints' + Show the current permission to insert breakpoints. + +'set may-insert-tracepoints on' +'set may-insert-tracepoints off' + This controls whether GDB will attempt to insert (regular) + tracepoints at the beginning of a tracing experiment. It affects + only non-fast tracepoints, fast tracepoints being under the control + of 'may-insert-fast-tracepoints'. It defaults to 'on'. + +'show may-insert-tracepoints' + Show the current permission to insert tracepoints. + +'set may-insert-fast-tracepoints on' +'set may-insert-fast-tracepoints off' + This controls whether GDB will attempt to insert fast tracepoints + at the beginning of a tracing experiment. It affects only fast + tracepoints, regular (non-fast) tracepoints being under the control + of 'may-insert-tracepoints'. It defaults to 'on'. + +'show may-insert-fast-tracepoints' + Show the current permission to insert fast tracepoints. + +'set may-interrupt on' +'set may-interrupt off' + This controls whether GDB will attempt to interrupt or stop program + execution. When this variable is 'off', the 'interrupt' command + will have no effect, nor will 'Ctrl-c'. It defaults to 'on'. + +'show may-interrupt' + Show the current permission to interrupt or stop the program. + + +File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top + +6 Running programs backward +*************************** + +When you are debugging a program, it is not unusual to realize that you +have gone too far, and some event of interest has already happened. If +the target environment supports it, GDB can allow you to "rewind" the +program by running it backward. + + A target environment that supports reverse execution should be able +to "undo" the changes in machine state that have taken place as the +program was executing normally. Variables, registers etc. should revert +to their previous values. Obviously this requires a great deal of +sophistication on the part of the target environment; not all target +environments can support reverse execution. + + When a program is executed in reverse, the instructions that have +most recently been executed are "un-executed", in reverse order. The +program counter runs backward, following the previous thread of +execution in reverse. As each instruction is "un-executed", the values +of memory and/or registers that were changed by that instruction are +reverted to their previous states. After executing a piece of source +code in reverse, all side effects of that code should be "undone", and +all variables should be returned to their prior values(1). + + If you are debugging in a target environment that supports reverse +execution, GDB provides the following commands. + +'reverse-continue [IGNORE-COUNT]' +'rc [IGNORE-COUNT]' + Beginning at the point where your program last stopped, start + executing in reverse. Reverse execution will stop for breakpoints + and synchronous exceptions (signals), just like normal execution. + Behavior of asynchronous signals depends on the target environment. + +'reverse-step [COUNT]' + Run the program backward until control reaches the start of a + different source line; then stop it, and return control to GDB. + + Like the 'step' command, 'reverse-step' will only stop at the + beginning of a source line. It "un-executes" the previously + executed source line. If the previous source line included calls + to debuggable functions, 'reverse-step' will step (backward) into + the called function, stopping at the beginning of the _last_ + statement in the called function (typically a return statement). + + Also, as with the 'step' command, if non-debuggable functions are + called, 'reverse-step' will run thru them backward without + stopping. + +'reverse-stepi [COUNT]' + Reverse-execute one machine instruction. Note that the instruction + to be reverse-executed is _not_ the one pointed to by the program + counter, but the instruction executed prior to that one. For + instance, if the last instruction was a jump, 'reverse-stepi' will + take you back from the destination of the jump to the jump + instruction itself. + +'reverse-next [COUNT]' + Run backward to the beginning of the previous line executed in the + current (innermost) stack frame. If the line contains function + calls, they will be "un-executed" without stopping. Starting from + the first line of a function, 'reverse-next' will take you back to + the caller of that function, _before_ the function was called, just + as the normal 'next' command would take you from the last line of a + function back to its return to its caller (2). + +'reverse-nexti [COUNT]' + Like 'nexti', 'reverse-nexti' executes a single instruction in + reverse, except that called functions are "un-executed" atomically. + That is, if the previously executed instruction was a return from + another function, 'reverse-nexti' will continue to execute in + reverse until the call to that function (from the current stack + frame) is reached. + +'reverse-finish' + Just as the 'finish' command takes you to the point where the + current function returns, 'reverse-finish' takes you to the point + where it was called. Instead of ending up at the end of the + current function invocation, you end up at the beginning. + +'set exec-direction' + Set the direction of target execution. +'set exec-direction reverse' + GDB will perform all execution commands in reverse, until the + exec-direction mode is changed to "forward". Affected commands + include 'step, stepi, next, nexti, continue, and finish'. The + 'return' command cannot be used in reverse mode. +'set exec-direction forward' + GDB will perform all execution commands in the normal fashion. + This is the default. + + ---------- Footnotes ---------- + + (1) Note that some side effects are easier to undo than others. For +instance, memory and registers are relatively easy, but device I/O is +hard. Some targets may be able undo things like device I/O, and some +may not. + + The contract between GDB and the reverse executing target requires +only that the target do something reasonable when GDB tells it to +execute backwards, and then report the results back to GDB. Whatever +the target reports back to GDB, GDB will report back to the user. GDB +assumes that the memory and registers that the target reports are in a +consistant state, but GDB accepts whatever it is given. + + (2) Unless the code is too heavily optimized. + + +File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top + +7 Recording Inferior's Execution and Replaying It +************************************************* + +On some platforms, GDB provides a special "process record and replay" +target that can record a log of the process execution, and replay it +later with both forward and reverse execution commands. + + When this target is in use, if the execution log includes the record +for the next instruction, GDB will debug in "replay mode". In the +replay mode, the inferior does not really execute code instructions. +Instead, all the events that normally happen during code execution are +taken from the execution log. While code is not really executed in +replay mode, the values of registers (including the program counter +register) and the memory of the inferior are still changed as they +normally would. Their contents are taken from the execution log. + + If the record for the next instruction is not in the execution log, +GDB will debug in "record mode". In this mode, the inferior executes +normally, and GDB records the execution log for future replay. + + The process record and replay target supports reverse execution +(*note Reverse Execution::), even if the platform on which the inferior +runs does not. However, the reverse execution is limited in this case +by the range of the instructions recorded in the execution log. In +other words, reverse execution on platforms that don't support it +directly can only be done in the replay mode. + + When debugging in the reverse direction, GDB will work in replay mode +as long as the execution log includes the record for the previous +instruction; otherwise, it will work in record mode, if the platform +supports reverse execution, or stop if not. + + For architecture environments that support process record and replay, +GDB provides the following commands: + +'record METHOD' + This command starts the process record and replay target. The + recording method can be specified as parameter. Without a + parameter the command uses the 'full' recording method. The + following recording methods are available: + + 'full' + Full record/replay recording using GDB's software record and + replay implementation. This method allows replaying and + reverse execution. + + 'btrace' + Hardware-supported instruction recording. This method does + not allow replaying and reverse execution. + + This recording method may not be available on all processors. + + The process record and replay target can only debug a process that + is already running. Therefore, you need first to start the process + with the 'run' or 'start' commands, and then start the recording + with the 'record METHOD' command. + + Both 'record METHOD' and 'rec METHOD' are aliases of 'target + record-METHOD'. + + Displaced stepping (*note displaced stepping: Maintenance + Commands.) will be automatically disabled when process record and + replay target is started. That's because the process record and + replay target doesn't support displaced stepping. + + If the inferior is in the non-stop mode (*note Non-Stop Mode::) or + in the asynchronous execution mode (*note Background Execution::), + not all recording methods are available. The 'full' recording + method does not support these two modes. + +'record stop' + Stop the process record and replay target. When process record and + replay target stops, the entire execution log will be deleted and + the inferior will either be terminated, or will remain in its final + state. + + When you stop the process record and replay target in record mode + (at the end of the execution log), the inferior will be stopped at + the next instruction that would have been recorded. In other + words, if you record for a while and then stop recording, the + inferior process will be left in the same state as if the recording + never happened. + + On the other hand, if the process record and replay target is + stopped while in replay mode (that is, not at the end of the + execution log, but at some earlier point), the inferior process + will become "live" at that earlier state, and it will then be + possible to continue the usual "live" debugging of the process from + that state. + + When the inferior process exits, or GDB detaches from it, process + record and replay target will automatically stop itself. + +'record goto' + Go to a specific location in the execution log. There are several + ways to specify the location to go to: + + 'record goto begin' + 'record goto start' + Go to the beginning of the execution log. + + 'record goto end' + Go to the end of the execution log. + + 'record goto N' + Go to instruction number N in the execution log. + +'record save FILENAME' + Save the execution log to a file 'FILENAME'. Default filename is + 'gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the + inferior. + + This command may not be available for all recording methods. + +'record restore FILENAME' + Restore the execution log from a file 'FILENAME'. File must have + been created with 'record save'. + +'set record full insn-number-max LIMIT' +'set record full insn-number-max unlimited' + Set the limit of instructions to be recorded for the 'full' + recording method. Default value is 200000. + + If LIMIT is a positive number, then GDB will start deleting + instructions from the log once the number of the record + instructions becomes greater than LIMIT. For every new recorded + instruction, GDB will delete the earliest recorded instruction to + keep the number of recorded instructions at the limit. (Since + deleting recorded instructions loses information, GDB lets you + control what happens when the limit is reached, by means of the + 'stop-at-limit' option, described below.) + + If LIMIT is 'unlimited' or zero, GDB will never delete recorded + instructions from the execution log. The number of recorded + instructions is limited only by the available memory. + +'show record full insn-number-max' + Show the limit of instructions to be recorded with the 'full' + recording method. + +'set record full stop-at-limit' + Control the behavior of the 'full' recording method when the number + of recorded instructions reaches the limit. If ON (the default), + GDB will stop when the limit is reached for the first time and ask + you whether you want to stop the inferior or continue running it + and recording the execution log. If you decide to continue + recording, each new recorded instruction will cause the oldest one + to be deleted. + + If this option is OFF, GDB will automatically delete the oldest + record to make room for each new one, without asking. + +'show record full stop-at-limit' + Show the current setting of 'stop-at-limit'. + +'set record full memory-query' + Control the behavior when GDB is unable to record memory changes + caused by an instruction for the 'full' recording method. If ON, + GDB will query whether to stop the inferior in that case. + + If this option is OFF (the default), GDB will automatically ignore + the effect of such instructions on memory. Later, when GDB replays + this execution log, it will mark the log of this instruction as not + accessible, and it will not affect the replay results. + +'show record full memory-query' + Show the current setting of 'memory-query'. + +'info record' + Show various statistics about the recording depending on the + recording method: + + 'full' + For the 'full' recording method, it shows the state of process + record and its in-memory execution log buffer, including: + + * Whether in record mode or replay mode. + * Lowest recorded instruction number (counting from when + the current execution log started recording + instructions). + * Highest recorded instruction number. + * Current instruction about to be replayed (if in replay + mode). + * Number of instructions contained in the execution log. + * Maximum number of instructions that may be contained in + the execution log. + + 'btrace' + For the 'btrace' recording method, it shows the number of + instructions that have been recorded and the number of blocks + of sequential control-flow that is formed by the recorded + instructions. + +'record delete' + When record target runs in replay mode ("in the past"), delete the + subsequent execution log and begin to record a new execution log + starting from the current address. This means you will abandon the + previously recorded "future" and begin recording a new "future". + +'record instruction-history' + Disassembles instructions from the recorded execution log. By + default, ten instructions are disassembled. This can be changed + using the 'set record instruction-history-size' command. + Instructions are printed in execution order. There are several + ways to specify what part of the execution log to disassemble: + + 'record instruction-history INSN' + Disassembles ten instructions starting from instruction number + INSN. + + 'record instruction-history INSN, +/-N' + Disassembles N instructions around instruction number INSN. + If N is preceded with '+', disassembles N instructions after + instruction number INSN. If N is preceded with '-', + disassembles N instructions before instruction number INSN. + + 'record instruction-history' + Disassembles ten more instructions after the last disassembly. + + 'record instruction-history -' + Disassembles ten more instructions before the last + disassembly. + + 'record instruction-history BEGIN END' + Disassembles instructions beginning with instruction number + BEGIN until instruction number END. The instruction number + END is not included. + + This command may not be available for all recording methods. + +'set record instruction-history-size SIZE' +'set record instruction-history-size unlimited' + Define how many instructions to disassemble in the 'record + instruction-history' command. The default value is 10. A SIZE of + 'unlimited' means unlimited instructions. + +'show record instruction-history-size' + Show how many instructions to disassemble in the 'record + instruction-history' command. + +'record function-call-history' + Prints the execution history at function granularity. It prints + one line for each sequence of instructions that belong to the same + function giving the name of that function, the source lines for + this instruction sequence (if the '/l' modifier is specified), and + the instructions numbers that form the sequence (if the '/i' + modifier is specified). + + (gdb) list 1, 10 + 1 void foo (void) + 2 { + 3 } + 4 + 5 void bar (void) + 6 { + 7 ... + 8 foo (); + 9 ... + 10 } + (gdb) record function-call-history /l + 1 foo.c:6-8 bar + 2 foo.c:2-3 foo + 3 foo.c:9-10 bar + + By default, ten lines are printed. This can be changed using the + 'set record function-call-history-size' command. Functions are + printed in execution order. There are several ways to specify what + to print: + + 'record function-call-history FUNC' + Prints ten functions starting from function number FUNC. + + 'record function-call-history FUNC, +/-N' + Prints N functions around function number FUNC. If N is + preceded with '+', prints N functions after function number + FUNC. If N is preceded with '-', prints N functions before + function number FUNC. + + 'record function-call-history' + Prints ten more functions after the last ten-line print. + + 'record function-call-history -' + Prints ten more functions before the last ten-line print. + + 'record function-call-history BEGIN END' + Prints functions beginning with function number BEGIN until + function number END. The function number END is not included. + + This command may not be available for all recording methods. + +'set record function-call-history-size SIZE' +'set record function-call-history-size unlimited' + Define how many lines to print in the 'record + function-call-history' command. The default value is 10. A size + of 'unlimited' means unlimited lines. + +'show record function-call-history-size' + Show how many lines to print in the 'record function-call-history' + command. + + +File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top + +8 Examining the Stack +********************* + +When your program has stopped, the first thing you need to know is where +it stopped and how it got there. + + Each time your program performs a function call, information about +the call is generated. That information includes the location of the +call in your program, the arguments of the call, and the local variables +of the function being called. The information is saved in a block of +data called a "stack frame". The stack frames are allocated in a region +of memory called the "call stack". + + When your program stops, the GDB commands for examining the stack +allow you to see all of this information. + + One of the stack frames is "selected" by GDB and many GDB commands +refer implicitly to the selected frame. In particular, whenever you ask +GDB for the value of a variable in your program, the value is found in +the selected frame. There are special GDB commands to select whichever +frame you are interested in. *Note Selecting a Frame: Selection. + + When your program stops, GDB automatically selects the currently +executing frame and describes it briefly, similar to the 'frame' command +(*note Information about a Frame: Frame Info.). + +* Menu: + +* Frames:: Stack frames +* Backtrace:: Backtraces +* Frame Filter Management:: Managing frame filters +* Selection:: Selecting a frame +* Frame Info:: Information on a frame + + +File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack + +8.1 Stack Frames +================ + +The call stack is divided up into contiguous pieces called "stack +frames", or "frames" for short; each frame is the data associated with +one call to one function. The frame contains the arguments given to the +function, the function's local variables, and the address at which the +function is executing. + + When your program is started, the stack has only one frame, that of +the function 'main'. This is called the "initial" frame or the +"outermost" frame. Each time a function is called, a new frame is made. +Each time a function returns, the frame for that function invocation is +eliminated. If a function is recursive, there can be many frames for +the same function. The frame for the function in which execution is +actually occurring is called the "innermost" frame. This is the most +recently created of all the stack frames that still exist. + + Inside your program, stack frames are identified by their addresses. +A stack frame consists of many bytes, each of which has its own address; +each kind of computer has a convention for choosing one byte whose +address serves as the address of the frame. Usually this address is +kept in a register called the "frame pointer register" (*note $fp: +Registers.) while execution is going on in that frame. + + GDB assigns numbers to all existing stack frames, starting with zero +for the innermost frame, one for the frame that called it, and so on +upward. These numbers do not really exist in your program; they are +assigned by GDB to give you a way of designating stack frames in GDB +commands. + + Some compilers provide a way to compile functions so that they +operate without stack frames. (For example, the GCC option + '-fomit-frame-pointer' + generates functions without a frame.) This is occasionally done with +heavily used library functions to save the frame setup time. GDB has +limited facilities for dealing with these function invocations. If the +innermost function invocation has no stack frame, GDB nevertheless +regards it as though it had a separate frame, which is numbered zero as +usual, allowing correct tracing of the function call chain. However, +GDB has no provision for frameless functions elsewhere in the stack. + +'frame ARGS' + The 'frame' command allows you to move from one stack frame to + another, and to print the stack frame you select. ARGS may be + either the address of the frame or the stack frame number. Without + an argument, 'frame' prints the current stack frame. + +'select-frame' + The 'select-frame' command allows you to move from one stack frame + to another without printing the frame. This is the silent version + of 'frame'. + + +File: gdb.info, Node: Backtrace, Next: Frame Filter Management, Prev: Frames, Up: Stack + +8.2 Backtraces +============== + +A backtrace is a summary of how your program got where it is. It shows +one line per frame, for many frames, starting with the currently +executing frame (frame zero), followed by its caller (frame one), and on +up the stack. + +'backtrace' +'bt' + Print a backtrace of the entire stack: one line per frame for all + frames in the stack. + + You can stop the backtrace at any time by typing the system + interrupt character, normally 'Ctrl-c'. + +'backtrace N' +'bt N' + Similar, but print only the innermost N frames. + +'backtrace -N' +'bt -N' + Similar, but print only the outermost N frames. + +'backtrace full' +'bt full' +'bt full N' +'bt full -N' + Print the values of the local variables also. N specifies the + number of frames to print, as described above. + +'backtrace no-filters' +'bt no-filters' +'bt no-filters N' +'bt no-filters -N' +'bt no-filters full' +'bt no-filters full N' +'bt no-filters full -N' + Do not run Python frame filters on this backtrace. *Note Frame + Filter API::, for more information. Additionally use *note disable + frame-filter all:: to turn off all frame filters. This is only + relevant when GDB has been configured with 'Python' support. + + The names 'where' and 'info stack' (abbreviated 'info s') are +additional aliases for 'backtrace'. + + In a multi-threaded program, GDB by default shows the backtrace only +for the current thread. To display the backtrace for several or all of +the threads, use the command 'thread apply' (*note thread apply: +Threads.). For example, if you type 'thread apply all backtrace', GDB +will display the backtrace for all the threads; this is handy when you +debug a core dump of a multi-threaded program. + + Each line in the backtrace shows the frame number and the function +name. The program counter value is also shown--unless you use 'set +print address off'. The backtrace also shows the source file name and +line number, as well as the arguments to the function. The program +counter value is omitted if it is at the beginning of the code for that +line number. + + Here is an example of a backtrace. It was made with the command 'bt +3', so it shows the innermost three frames. + + #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) + at builtin.c:993 + #1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242 + #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) + at macro.c:71 + (More stack frames follow...) + +The display for frame zero does not begin with a program counter value, +indicating that your program has stopped at the beginning of the code +for line '993' of 'builtin.c'. + +The value of parameter 'data' in frame 1 has been replaced by '...'. By +default, GDB prints the value of a parameter only if it is a scalar +(integer, pointer, enumeration, etc). See command 'set print +frame-arguments' in *note Print Settings:: for more details on how to +configure the way function parameter values are printed. + + If your program was compiled with optimizations, some compilers will +optimize away arguments passed to functions if those arguments are never +used after the call. Such optimizations generate code that passes +arguments through registers, but doesn't store those arguments in the +stack frame. GDB has no way of displaying such arguments in stack +frames other than the innermost one. Here's what such a backtrace might +look like: + + #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) + at builtin.c:993 + #1 0x6e38 in expand_macro (sym=) at macro.c:242 + #2 0x6840 in expand_token (obs=0x0, t=, td=0xf7fffb08) + at macro.c:71 + (More stack frames follow...) + +The values of arguments that were not saved in their stack frames are +shown as ''. + + If you need to display the values of such optimized-out arguments, +either deduce that from other variables whose values depend on the one +you are interested in, or recompile without optimizations. + + Most programs have a standard user entry point--a place where system +libraries and startup code transition into user code. For C this is +'main'(1). When GDB finds the entry function in a backtrace it will +terminate the backtrace, to avoid tracing into highly system-specific +(and generally uninteresting) code. + + If you need to examine the startup code, or limit the number of +levels in a backtrace, you can change this behavior: + +'set backtrace past-main' +'set backtrace past-main on' + Backtraces will continue past the user entry point. + +'set backtrace past-main off' + Backtraces will stop when they encounter the user entry point. + This is the default. + +'show backtrace past-main' + Display the current user entry point backtrace policy. + +'set backtrace past-entry' +'set backtrace past-entry on' + Backtraces will continue past the internal entry point of an + application. This entry point is encoded by the linker when the + application is built, and is likely before the user entry point + 'main' (or equivalent) is called. + +'set backtrace past-entry off' + Backtraces will stop when they encounter the internal entry point + of an application. This is the default. + +'show backtrace past-entry' + Display the current internal entry point backtrace policy. + +'set backtrace limit N' +'set backtrace limit 0' +'set backtrace limit unlimited' + Limit the backtrace to N levels. A value of 'unlimited' or zero + means unlimited levels. + +'show backtrace limit' + Display the current limit on backtrace levels. + + You can control how file names are displayed. + +'set filename-display' +'set filename-display relative' + Display file names relative to the compilation directory. This is + the default. + +'set filename-display basename' + Display only basename of a filename. + +'set filename-display absolute' + Display an absolute filename. + +'show filename-display' + Show the current way to display filenames. + + ---------- Footnotes ---------- + + (1) Note that embedded programs (the so-called "free-standing" +environment) are not required to have a 'main' function as the entry +point. They could even have multiple entry points. + + +File: gdb.info, Node: Frame Filter Management, Next: Selection, Prev: Backtrace, Up: Stack + +8.3 Management of Frame Filters. +================================ + +Frame filters are Python based utilities to manage and decorate the +output of frames. *Note Frame Filter API::, for further information. + + Managing frame filters is performed by several commands available +within GDB, detailed here. + +'info frame-filter' + Print a list of installed frame filters from all dictionaries, + showing their name, priority and enabled status. + +'disable frame-filter FILTER-DICTIONARY FILTER-NAME' + Disable a frame filter in the dictionary matching + FILTER-DICTIONARY, or 'all', and FILTER-NAME. FILTER-DICTIONARY + may be 'all', 'global', 'progspace' or the name of the object file + where the frame filter dictionary resides. When 'all' is + specified, all frame filters across all dictionaries are disabled. + FILTER-NAME is the name of the frame filter and is used when 'all' + is not the option for FILTER-DICTIONARY. A disabled frame-filter + is not deleted, it may be enabled again later. + +'enable frame-filter FILTER-DICTIONARY FILTER-NAME' + Enable a frame filter in the dictionary matching FILTER-DICTIONARY, + or 'all', and FILTER-NAME. FILTER-DICTIONARY may be 'all', + 'global', 'progspace' or the name of the object file where the + frame filter dictionary resides. When 'all' is specified, all + frame filters across all dictionaries are enabled. FILTER-NAME is + the name of the frame filter and is used when 'all' is not the + option for FILTER-DICTIONARY. + + Example: + + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 No PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 Yes BuildProgra Filter + + (gdb) disable frame-filter /build/test BuildProgramFilter + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 No PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + + (gdb) enable frame-filter global PrimaryFunctionFilter + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + +'set frame-filter priority FILTER-DICTIONARY FILTER-NAME PRIORITY' + Set the PRIORITY of a frame filter in the dictionary matching + FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME. + FILTER-DICTIONARY may be 'global', 'progspace' or the name of the + object file where the frame filter dictionary resides. PRIORITY is + an integer. + +'show frame-filter priority FILTER-DICTIONARY FILTER-NAME' + Show the PRIORITY of a frame filter in the dictionary matching + FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME. + FILTER-DICTIONARY may be 'global', 'progspace' or the name of the + object file where the frame filter dictionary resides. + + Example: + + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + + (gdb) set frame-filter priority global Reverse 50 + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 50 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + + +File: gdb.info, Node: Selection, Next: Frame Info, Prev: Frame Filter Management, Up: Stack + +8.4 Selecting a Frame +===================== + +Most commands for examining the stack and other data in your program +work on whichever stack frame is selected at the moment. Here are the +commands for selecting a stack frame; all of them finish by printing a +brief description of the stack frame just selected. + +'frame N' +'f N' + Select frame number N. Recall that frame zero is the innermost + (currently executing) frame, frame one is the frame that called the + innermost one, and so on. The highest-numbered frame is the one + for 'main'. + +'frame ADDR' +'f ADDR' + Select the frame at address ADDR. This is useful mainly if the + chaining of stack frames has been damaged by a bug, making it + impossible for GDB to assign numbers properly to all frames. In + addition, this can be useful when your program has multiple stacks + and switches between them. + + On the SPARC architecture, 'frame' needs two addresses to select an + arbitrary frame: a frame pointer and a stack pointer. + + On the MIPS and Alpha architecture, it needs two addresses: a stack + pointer and a program counter. + + On the 29k architecture, it needs three addresses: a register stack + pointer, a program counter, and a memory stack pointer. + +'up N' + Move N frames up the stack. For positive numbers N, this advances + toward the outermost frame, to higher frame numbers, to frames that + have existed longer. N defaults to one. + +'down N' + Move N frames down the stack. For positive numbers N, this + advances toward the innermost frame, to lower frame numbers, to + frames that were created more recently. N defaults to one. You + may abbreviate 'down' as 'do'. + + All of these commands end by printing two lines of output describing +the frame. The first line shows the frame number, the function name, +the arguments, and the source file and line number of execution in that +frame. The second line shows the text of that source line. + + For example: + + (gdb) up + #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) + at env.c:10 + 10 read_input_file (argv[i]); + + After such a printout, the 'list' command with no arguments prints +ten lines centered on the point of execution in the frame. You can also +edit the program at the point of execution with your favorite editing +program by typing 'edit'. *Note Printing Source Lines: List, for +details. + +'up-silently N' +'down-silently N' + These two commands are variants of 'up' and 'down', respectively; + they differ in that they do their work silently, without causing + display of the new frame. They are intended primarily for use in + GDB command scripts, where the output might be unnecessary and + distracting. + + +File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack + +8.5 Information About a Frame +============================= + +There are several other commands to print information about the selected +stack frame. + +'frame' +'f' + When used without any argument, this command does not change which + frame is selected, but prints a brief description of the currently + selected stack frame. It can be abbreviated 'f'. With an + argument, this command is used to select a stack frame. *Note + Selecting a Frame: Selection. + +'info frame' +'info f' + This command prints a verbose description of the selected stack + frame, including: + + * the address of the frame + * the address of the next frame down (called by this frame) + * the address of the next frame up (caller of this frame) + * the language in which the source code corresponding to this + frame is written + * the address of the frame's arguments + * the address of the frame's local variables + * the program counter saved in it (the address of execution in + the caller frame) + * which registers were saved in the frame + + The verbose description is useful when something has gone wrong + that has made the stack format fail to fit the usual conventions. + +'info frame ADDR' +'info f ADDR' + Print a verbose description of the frame at address ADDR, without + selecting that frame. The selected frame remains unchanged by this + command. This requires the same kind of address (more than one for + some architectures) that you specify in the 'frame' command. *Note + Selecting a Frame: Selection. + +'info args' + Print the arguments of the selected frame, each on a separate line. + +'info locals' + Print the local variables of the selected frame, each on a separate + line. These are all variables (declared either static or + automatic) accessible at the point of execution of the selected + frame. + + +File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top + +9 Examining Source Files +************************ + +GDB can print parts of your program's source, since the debugging +information recorded in the program tells GDB what source files were +used to build it. When your program stops, GDB spontaneously prints the +line where it stopped. Likewise, when you select a stack frame (*note +Selecting a Frame: Selection.), GDB prints the line where execution in +that frame has stopped. You can print other portions of source files by +explicit command. + + If you use GDB through its GNU Emacs interface, you may prefer to use +Emacs facilities to view source; see *note Using GDB under GNU Emacs: +Emacs. + +* Menu: + +* List:: Printing source lines +* Specify Location:: How to specify code locations +* Edit:: Editing source files +* Search:: Searching source files +* Source Path:: Specifying source directories +* Machine Code:: Source and machine code + + +File: gdb.info, Node: List, Next: Specify Location, Up: Source + +9.1 Printing Source Lines +========================= + +To print lines from a source file, use the 'list' command (abbreviated +'l'). By default, ten lines are printed. There are several ways to +specify what part of the file you want to print; see *note Specify +Location::, for the full list. + + Here are the forms of the 'list' command most commonly used: + +'list LINENUM' + Print lines centered around line number LINENUM in the current + source file. + +'list FUNCTION' + Print lines centered around the beginning of function FUNCTION. + +'list' + Print more lines. If the last lines printed were printed with a + 'list' command, this prints lines following the last lines printed; + however, if the last line printed was a solitary line printed as + part of displaying a stack frame (*note Examining the Stack: + Stack.), this prints lines centered around that line. + +'list -' + Print lines just before the lines last printed. + + By default, GDB prints ten source lines with any of these forms of +the 'list' command. You can change this using 'set listsize': + +'set listsize COUNT' +'set listsize unlimited' + Make the 'list' command display COUNT source lines (unless the + 'list' argument explicitly specifies some other number). Setting + COUNT to 'unlimited' or 0 means there's no limit. + +'show listsize' + Display the number of lines that 'list' prints. + + Repeating a 'list' command with discards the argument, so it is +equivalent to typing just 'list'. This is more useful than listing the +same lines again. An exception is made for an argument of '-'; that +argument is preserved in repetition so that each repetition moves up in +the source file. + + In general, the 'list' command expects you to supply zero, one or two +"linespecs". Linespecs specify source lines; there are several ways of +writing them (*note Specify Location::), but the effect is always to +specify some source line. + + Here is a complete description of the possible arguments for 'list': + +'list LINESPEC' + Print lines centered around the line specified by LINESPEC. + +'list FIRST,LAST' + Print lines from FIRST to LAST. Both arguments are linespecs. + When a 'list' command has two linespecs, and the source file of the + second linespec is omitted, this refers to the same source file as + the first linespec. + +'list ,LAST' + Print lines ending with LAST. + +'list FIRST,' + Print lines starting with FIRST. + +'list +' + Print lines just after the lines last printed. + +'list -' + Print lines just before the lines last printed. + +'list' + As described in the preceding table. + + +File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source + +9.2 Specifying a Location +========================= + +Several GDB commands accept arguments that specify a location of your +program's code. Since GDB is a source-level debugger, a location +usually specifies some line in the source code; for that reason, +locations are also known as "linespecs". + + Here are all the different ways of specifying a code location that +GDB understands: + +'LINENUM' + Specifies the line number LINENUM of the current source file. + +'-OFFSET' +'+OFFSET' + Specifies the line OFFSET lines before or after the "current line". + For the 'list' command, the current line is the last one printed; + for the breakpoint commands, this is the line at which execution + stopped in the currently selected "stack frame" (*note Frames: + Frames, for a description of stack frames.) When used as the + second of the two linespecs in a 'list' command, this specifies the + line OFFSET lines up or down from the first linespec. + +'FILENAME:LINENUM' + Specifies the line LINENUM in the source file FILENAME. If + FILENAME is a relative file name, then it will match any source + file name with the same trailing components. For example, if + FILENAME is 'gcc/expr.c', then it will match source file name of + '/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or + '/build/trunk/gcc/x-expr.c'. + +'FUNCTION' + Specifies the line that begins the body of the function FUNCTION. + For example, in C, this is the line with the open brace. + +'FUNCTION:LABEL' + Specifies the line where LABEL appears in FUNCTION. + +'FILENAME:FUNCTION' + Specifies the line that begins the body of the function FUNCTION in + the file FILENAME. You only need the file name with a function + name to avoid ambiguity when there are identically named functions + in different source files. + +'LABEL' + Specifies the line at which the label named LABEL appears. GDB + searches for the label in the function corresponding to the + currently selected stack frame. If there is no current selected + stack frame (for instance, if the inferior is not running), then + GDB will not search for a label. + +'*ADDRESS' + Specifies the program address ADDRESS. For line-oriented commands, + such as 'list' and 'edit', this specifies a source line that + contains ADDRESS. For 'break' and other breakpoint oriented + commands, this can be used to set breakpoints in parts of your + program which do not have debugging information or source files. + + Here ADDRESS may be any expression valid in the current working + language (*note working language: Languages.) that specifies a code + address. In addition, as a convenience, GDB extends the semantics + of expressions used in locations to cover the situations that + frequently happen during debugging. Here are the various forms of + ADDRESS: + + 'EXPRESSION' + Any expression valid in the current working language. + + 'FUNCADDR' + An address of a function or procedure derived from its name. + In C, C++, Java, Objective-C, Fortran, minimal, and assembly, + this is simply the function's name FUNCTION (and actually a + special case of a valid expression). In Pascal and Modula-2, + this is '&FUNCTION'. In Ada, this is 'FUNCTION'Address' + (although the Pascal form also works). + + This form specifies the address of the function's first + instruction, before the stack frame and arguments have been + set up. + + ''FILENAME'::FUNCADDR' + Like FUNCADDR above, but also specifies the name of the source + file explicitly. This is useful if the name of the function + does not specify the function unambiguously, e.g., if there + are several functions with identical names in different source + files. + +'-pstap|-probe-stap [OBJFILE:[PROVIDER:]]NAME' + The GNU/Linux tool 'SystemTap' provides a way for applications to + embed static probes. *Note Static Probe Points::, for more + information on finding and using static probes. This form of + linespec specifies the location of such a static probe. + + If OBJFILE is given, only probes coming from that shared library or + executable matching OBJFILE as a regular expression are considered. + If PROVIDER is given, then only probes from that provider are + considered. If several probes match the spec, GDB will insert a + breakpoint at each one of those probes. + + +File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source + +9.3 Editing Source Files +======================== + +To edit the lines in a source file, use the 'edit' command. The editing +program of your choice is invoked with the current line set to the +active line in the program. Alternatively, there are several ways to +specify what part of the file you want to print if you want to see other +parts of the program: + +'edit LOCATION' + Edit the source file specified by 'location'. Editing starts at + that LOCATION, e.g., at the specified source line of the specified + file. *Note Specify Location::, for all the possible forms of the + LOCATION argument; here are the forms of the 'edit' command most + commonly used: + + 'edit NUMBER' + Edit the current source file with NUMBER as the active line + number. + + 'edit FUNCTION' + Edit the file containing FUNCTION at the beginning of its + definition. + +9.3.1 Choosing your Editor +-------------------------- + +You can customize GDB to use any editor you want (1). By default, it is +'/bin/ex', but you can change this by setting the environment variable +'EDITOR' before using GDB. For example, to configure GDB to use the +'vi' editor, you could use these commands with the 'sh' shell: + EDITOR=/usr/bin/vi + export EDITOR + gdb ... + or in the 'csh' shell, + setenv EDITOR /usr/bin/vi + gdb ... + + ---------- Footnotes ---------- + + (1) The only restriction is that your editor (say 'ex'), recognizes +the following command-line syntax: + ex +NUMBER file + The optional numeric value +NUMBER specifies the number of the line +in the file where to start editing. + + +File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source + +9.4 Searching Source Files +========================== + +There are two commands for searching through the current source file for +a regular expression. + +'forward-search REGEXP' +'search REGEXP' + The command 'forward-search REGEXP' checks each line, starting with + the one following the last line listed, for a match for REGEXP. It + lists the line that is found. You can use the synonym 'search + REGEXP' or abbreviate the command name as 'fo'. + +'reverse-search REGEXP' + The command 'reverse-search REGEXP' checks each line, starting with + the one before the last line listed and going backward, for a match + for REGEXP. It lists the line that is found. You can abbreviate + this command as 'rev'. + + +File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source + +9.5 Specifying Source Directories +================================= + +Executable programs sometimes do not record the directories of the +source files from which they were compiled, just the names. Even when +they do, the directories could be moved between the compilation and your +debugging session. GDB has a list of directories to search for source +files; this is called the "source path". Each time GDB wants a source +file, it tries all the directories in the list, in the order they are +present in the list, until it finds a file with the desired name. + + For example, suppose an executable references the file +'/usr/src/foo-1.0/lib/foo.c', and our source path is '/mnt/cross'. The +file is first looked up literally; if this fails, +'/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails, +'/mnt/cross/foo.c' is opened; if this fails, an error message is +printed. GDB does not look up the parts of the source file name, such +as '/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of +the source path are not searched: if the source path is '/mnt/cross', +and the binary refers to 'foo.c', GDB would not find it under +'/mnt/cross/usr/src/foo-1.0/lib'. + + Plain file names, relative file names with leading directories, file +names containing dots, etc. are all treated as described above; for +instance, if the source path is '/mnt/cross', and the source file is +recorded as '../lib/foo.c', GDB would first try '../lib/foo.c', then +'/mnt/cross/../lib/foo.c', and after that--'/mnt/cross/foo.c'. + + Note that the executable search path is _not_ used to locate the +source files. + + Whenever you reset or rearrange the source path, GDB clears out any +information it has cached about where source files are found and where +each line is in the file. + + When you start GDB, its source path includes only 'cdir' and 'cwd', +in that order. To add other directories, use the 'directory' command. + + The search path is used to find both program source files and GDB +script files (read using the '-command' option and 'source' command). + + In addition to the source path, GDB provides a set of commands that +manage a list of source path substitution rules. A "substitution rule" +specifies how to rewrite source directories stored in the program's +debug information in case the sources were moved to a different +directory between compilation and debugging. A rule is made of two +strings, the first specifying what needs to be rewritten in the path, +and the second specifying how it should be rewritten. In *note set +substitute-path::, we name these two parts FROM and TO respectively. +GDB does a simple string replacement of FROM with TO at the start of the +directory part of the source file name, and uses that result instead of +the original file name to look up the sources. + + Using the previous example, suppose the 'foo-1.0' tree has been moved +from '/usr/src' to '/mnt/cross', then you can tell GDB to replace +'/usr/src' in all source path names with '/mnt/cross'. The first lookup +will then be '/mnt/cross/foo-1.0/lib/foo.c' in place of the original +location of '/usr/src/foo-1.0/lib/foo.c'. To define a source path +substitution rule, use the 'set substitute-path' command (*note set +substitute-path::). + + To avoid unexpected substitution results, a rule is applied only if +the FROM part of the directory name ends at a directory separator. For +instance, a rule substituting '/usr/source' into '/mnt/cross' will be +applied to '/usr/source/foo-1.0' but not to '/usr/sourceware/foo-2.0'. +And because the substitution is applied only at the beginning of the +directory name, this rule will not be applied to +'/root/usr/source/baz.c' either. + + In many cases, you can achieve the same result using the 'directory' +command. However, 'set substitute-path' can be more efficient in the +case where the sources are organized in a complex tree with multiple +subdirectories. With the 'directory' command, you need to add each +subdirectory of your project. If you moved the entire tree while +preserving its internal organization, then 'set substitute-path' allows +you to direct the debugger to all the sources with one single command. + + 'set substitute-path' is also more than just a shortcut command. The +source path is only used if the file at the original location no longer +exists. On the other hand, 'set substitute-path' modifies the debugger +behavior to look at the rewritten location instead. So, if for any +reason a source file that is not relevant to your executable is located +at the original location, a substitution rule is the only method +available to point GDB at the new location. + + You can configure a default source path substitution rule by +configuring GDB with the '--with-relocated-sources=DIR' option. The DIR +should be the name of a directory under GDB's configured prefix (set +with '--prefix' or '--exec-prefix'), and directory names in debug +information under DIR will be adjusted automatically if the installed +GDB is moved to a new location. This is useful if GDB, libraries or +executables with debug information and corresponding source code are +being moved together. + +'directory DIRNAME ...' +'dir DIRNAME ...' + Add directory DIRNAME to the front of the source path. Several + directory names may be given to this command, separated by ':' (';' + on MS-DOS and MS-Windows, where ':' usually appears as part of + absolute file names) or whitespace. You may specify a directory + that is already in the source path; this moves it forward, so GDB + searches it sooner. + + You can use the string '$cdir' to refer to the compilation + directory (if one is recorded), and '$cwd' to refer to the current + working directory. '$cwd' is not the same as '.'--the former + tracks the current working directory as it changes during your GDB + session, while the latter is immediately expanded to the current + directory at the time you add an entry to the source path. + +'directory' + Reset the source path to its default value ('$cdir:$cwd' on Unix + systems). This requires confirmation. + +'set directories PATH-LIST' + Set the source path to PATH-LIST. '$cdir:$cwd' are added if + missing. + +'show directories' + Print the source path: show which directories it contains. + +'set substitute-path FROM TO' + Define a source path substitution rule, and add it at the end of + the current list of existing substitution rules. If a rule with + the same FROM was already defined, then the old rule is also + deleted. + + For example, if the file '/foo/bar/baz.c' was moved to + '/mnt/cross/baz.c', then the command + + (gdb) set substitute-path /usr/src /mnt/cross + + will tell GDB to replace '/usr/src' with '/mnt/cross', which will + allow GDB to find the file 'baz.c' even though it was moved. + + In the case when more than one substitution rule have been defined, + the rules are evaluated one by one in the order where they have + been defined. The first one matching, if any, is selected to + perform the substitution. + + For instance, if we had entered the following commands: + + (gdb) set substitute-path /usr/src/include /mnt/include + (gdb) set substitute-path /usr/src /mnt/src + + GDB would then rewrite '/usr/src/include/defs.h' into + '/mnt/include/defs.h' by using the first rule. However, it would + use the second rule to rewrite '/usr/src/lib/foo.c' into + '/mnt/src/lib/foo.c'. + +'unset substitute-path [path]' + If a path is specified, search the current list of substitution + rules for a rule that would rewrite that path. Delete that rule if + found. A warning is emitted by the debugger if no rule could be + found. + + If no path is specified, then all substitution rules are deleted. + +'show substitute-path [path]' + If a path is specified, then print the source path substitution + rule which would rewrite that path, if any. + + If no path is specified, then print all existing source path + substitution rules. + + If your source path is cluttered with directories that are no longer +of interest, GDB may sometimes cause confusion by finding the wrong +versions of source. You can correct the situation as follows: + + 1. Use 'directory' with no argument to reset the source path to its + default value. + + 2. Use 'directory' with suitable arguments to reinstall the + directories you want in the source path. You can add all the + directories in one command. + + +File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source + +9.6 Source and Machine Code +=========================== + +You can use the command 'info line' to map source lines to program +addresses (and vice versa), and the command 'disassemble' to display a +range of addresses as machine instructions. You can use the command +'set disassemble-next-line' to set whether to disassemble next source +line when execution stops. When run under GNU Emacs mode, the 'info +line' command causes the arrow to point to the line specified. Also, +'info line' prints addresses in symbolic form as well as hex. + +'info line LINESPEC' + Print the starting and ending addresses of the compiled code for + source line LINESPEC. You can specify source lines in any of the + ways documented in *note Specify Location::. + + For example, we can use 'info line' to discover the location of the +object code for the first line of function 'm4_changequote': + + (gdb) info line m4_changequote + Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. + +We can also inquire (using '*ADDR' as the form for LINESPEC) what source +line covers a particular address: + (gdb) info line *0x63ff + Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. + + After 'info line', the default address for the 'x' command is changed +to the starting address of the line, so that 'x/i' is sufficient to +begin examining the machine code (*note Examining Memory: Memory.). +Also, this address is saved as the value of the convenience variable +'$_' (*note Convenience Variables: Convenience Vars.). + +'disassemble' +'disassemble /m' +'disassemble /r' + This specialized command dumps a range of memory as machine + instructions. It can also print mixed source+disassembly by + specifying the '/m' modifier and print the raw instructions in hex + as well as in symbolic form by specifying the '/r'. The default + memory range is the function surrounding the program counter of the + selected frame. A single argument to this command is a program + counter value; GDB dumps the function surrounding this value. When + two arguments are given, they should be separated by a comma, + possibly surrounded by whitespace. The arguments specify a range + of addresses to dump, in one of two forms: + + 'START,END' + the addresses from START (inclusive) to END (exclusive) + 'START,+LENGTH' + the addresses from START (inclusive) to 'START+LENGTH' + (exclusive). + + When 2 arguments are specified, the name of the function is also + printed (since there could be several functions in the given + range). + + The argument(s) can be any expression yielding a numeric value, + such as '0x32c4', '&main+10' or '$pc - 8'. + + If the range of memory being disassembled contains current program + counter, the instruction at that location is shown with a '=>' + marker. + + The following example shows the disassembly of a range of addresses +of HP PA-RISC 2.0 code: + + (gdb) disas 0x32c4, 0x32e4 + Dump of assembler code from 0x32c4 to 0x32e4: + 0x32c4 : addil 0,dp + 0x32c8 : ldw 0x22c(sr0,r1),r26 + 0x32cc : ldil 0x3000,r31 + 0x32d0 : ble 0x3f8(sr4,r31) + 0x32d4 : ldo 0(r31),rp + 0x32d8 : addil -0x800,dp + 0x32dc : ldo 0x588(r1),r26 + 0x32e0 : ldil 0x3000,r31 + End of assembler dump. + + Here is an example showing mixed source+assembly for Intel x86, when +the program is stopped just after function prologue: + + (gdb) disas /m main + Dump of assembler code for function main: + 5 { + 0x08048330 <+0>: push %ebp + 0x08048331 <+1>: mov %esp,%ebp + 0x08048333 <+3>: sub $0x8,%esp + 0x08048336 <+6>: and $0xfffffff0,%esp + 0x08048339 <+9>: sub $0x10,%esp + + 6 printf ("Hello.\n"); + => 0x0804833c <+12>: movl $0x8048440,(%esp) + 0x08048343 <+19>: call 0x8048284 + + 7 return 0; + 8 } + 0x08048348 <+24>: mov $0x0,%eax + 0x0804834d <+29>: leave + 0x0804834e <+30>: ret + + End of assembler dump. + + Here is another example showing raw instructions in hex for AMD +x86-64, + + (gdb) disas /r 0x400281,+10 + Dump of assembler code from 0x400281 to 0x40028b: + 0x0000000000400281: 38 36 cmp %dh,(%rsi) + 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax + 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) + 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al + End of assembler dump. + + Addresses cannot be specified as a linespec (*note Specify +Location::). So, for example, if you want to disassemble function 'bar' +in file 'foo.c', you must type 'disassemble 'foo.c'::bar' and not +'disassemble foo.c:bar'. + + Some architectures have more than one commonly-used set of +instruction mnemonics or other syntax. + + For programs that were dynamically linked and use shared libraries, +instructions that call functions or branch to locations in the shared +libraries might show a seemingly bogus location--it's actually a +location of the relocation table. On some architectures, GDB might be +able to resolve these to actual function names. + +'set disassembly-flavor INSTRUCTION-SET' + Select the instruction set to use when disassembling the program + via the 'disassemble' or 'x/i' commands. + + Currently this command is only defined for the Intel x86 family. + You can set INSTRUCTION-SET to either 'intel' or 'att'. The + default is 'att', the AT&T flavor used by default by Unix + assemblers for x86-based targets. + +'show disassembly-flavor' + Show the current setting of the disassembly flavor. + +'set disassemble-next-line' +'show disassemble-next-line' + Control whether or not GDB will disassemble the next source line or + instruction when execution stops. If ON, GDB will display + disassembly of the next source line when execution of the program + being debugged stops. This is _in addition_ to displaying the + source line itself, which GDB always does if possible. If the next + source line cannot be displayed for some reason (e.g., if GDB + cannot find the source file, or there's no line info in the debug + info), GDB will display disassembly of the next _instruction_ + instead of showing the next source line. If AUTO, GDB will display + disassembly of next instruction only if the source line cannot be + displayed. This setting causes GDB to display some feedback when + you step through a function with no line info or whose source file + is unavailable. The default is OFF, which means never display the + disassembly of the next line or instruction. + + +File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top + +10 Examining Data +***************** + +The usual way to examine data in your program is with the 'print' +command (abbreviated 'p'), or its synonym 'inspect'. It evaluates and +prints the value of an expression of the language your program is +written in (*note Using GDB with Different Languages: Languages.). It +may also print the expression using a Python-based pretty-printer (*note +Pretty Printing::). + +'print EXPR' +'print /F EXPR' + EXPR is an expression (in the source language). By default the + value of EXPR is printed in a format appropriate to its data type; + you can choose a different format by specifying '/F', where F is a + letter specifying the format; see *note Output Formats: Output + Formats. + +'print' +'print /F' + If you omit EXPR, GDB displays the last value again (from the + "value history"; *note Value History: Value History.). This allows + you to conveniently inspect the same value in an alternative + format. + + A more low-level way of examining data is with the 'x' command. It +examines data in memory at a specified address and prints it in a +specified format. *Note Examining Memory: Memory. + + If you are interested in information about types, or about how the +fields of a struct or a class are declared, use the 'ptype EXP' command +rather than 'print'. *Note Examining the Symbol Table: Symbols. + + Another way of examining values of expressions and type information +is through the Python extension command 'explore' (available only if the +GDB build is configured with '--with-python'). It offers an interactive +way to start at the highest level (or, the most abstract level) of the +data type of an expression (or, the data type itself) and explore all +the way down to leaf scalar values/fields embedded in the higher level +data types. + +'explore ARG' + ARG is either an expression (in the source language), or a type + visible in the current context of the program being debugged. + + The working of the 'explore' command can be illustrated with an +example. If a data type 'struct ComplexStruct' is defined in your C +program as + + struct SimpleStruct + { + int i; + double d; + }; + + struct ComplexStruct + { + struct SimpleStruct *ss_p; + int arr[10]; + }; + +followed by variable declarations as + + struct SimpleStruct ss = { 10, 1.11 }; + struct ComplexStruct cs = { &ss, { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 } }; + +then, the value of the variable 'cs' can be explored using the 'explore' +command as follows. + + (gdb) explore cs + The value of `cs' is a struct/class of type `struct ComplexStruct' with + the following fields: + + ss_p = + arr = + + Enter the field number of choice: + +Since the fields of 'cs' are not scalar values, you are being prompted +to chose the field you want to explore. Let's say you choose the field +'ss_p' by entering '0'. Then, since this field is a pointer, you will +be asked if it is pointing to a single value. From the declaration of +'cs' above, it is indeed pointing to a single value, hence you enter +'y'. If you enter 'n', then you will be asked if it were pointing to an +array of values, in which case this field will be explored as if it were +an array. + + `cs.ss_p' is a pointer to a value of type `struct SimpleStruct' + Continue exploring it as a pointer to a single value [y/n]: y + The value of `*(cs.ss_p)' is a struct/class of type `struct + SimpleStruct' with the following fields: + + i = 10 .. (Value of type `int') + d = 1.1100000000000001 .. (Value of type `double') + + Press enter to return to parent value: + +If the field 'arr' of 'cs' was chosen for exploration by entering '1' +earlier, then since it is as array, you will be prompted to enter the +index of the element in the array that you want to explore. + + `cs.arr' is an array of `int'. + Enter the index of the element you want to explore in `cs.arr': 5 + + `(cs.arr)[5]' is a scalar value of type `int'. + + (cs.arr)[5] = 4 + + Press enter to return to parent value: + + In general, at any stage of exploration, you can go deeper towards +the leaf values by responding to the prompts appropriately, or hit the +return key to return to the enclosing data structure (the higher level +data structure). + + Similar to exploring values, you can use the 'explore' command to +explore types. Instead of specifying a value (which is typically a +variable name or an expression valid in the current context of the +program being debugged), you specify a type name. If you consider the +same example as above, your can explore the type 'struct ComplexStruct' +by passing the argument 'struct ComplexStruct' to the 'explore' command. + + (gdb) explore struct ComplexStruct + +By responding to the prompts appropriately in the subsequent interactive +session, you can explore the type 'struct ComplexStruct' in a manner +similar to how the value 'cs' was explored in the above example. + + The 'explore' command also has two sub-commands, 'explore value' and +'explore type'. The former sub-command is a way to explicitly specify +that value exploration of the argument is being invoked, while the +latter is a way to explicitly specify that type exploration of the +argument is being invoked. + +'explore value EXPR' + This sub-command of 'explore' explores the value of the expression + EXPR (if EXPR is an expression valid in the current context of the + program being debugged). The behavior of this command is identical + to that of the behavior of the 'explore' command being passed the + argument EXPR. + +'explore type ARG' + This sub-command of 'explore' explores the type of ARG (if ARG is a + type visible in the current context of program being debugged), or + the type of the value/expression ARG (if ARG is an expression valid + in the current context of the program being debugged). If ARG is a + type, then the behavior of this command is identical to that of the + 'explore' command being passed the argument ARG. If ARG is an + expression, then the behavior of this command will be identical to + that of the 'explore' command being passed the type of ARG as the + argument. + +* Menu: + +* Expressions:: Expressions +* Ambiguous Expressions:: Ambiguous Expressions +* Variables:: Program variables +* Arrays:: Artificial arrays +* Output Formats:: Output formats +* Memory:: Examining memory +* Auto Display:: Automatic display +* Print Settings:: Print settings +* Pretty Printing:: Python pretty printing +* Value History:: Value history +* Convenience Vars:: Convenience variables +* Convenience Funs:: Convenience functions +* Registers:: Registers +* Floating Point Hardware:: Floating point hardware +* Vector Unit:: Vector Unit +* OS Information:: Auxiliary data provided by operating system +* Memory Region Attributes:: Memory region attributes +* Dump/Restore Files:: Copy between memory and a file +* Core File Generation:: Cause a program dump its core +* Character Sets:: Debugging programs that use a different + character set than GDB does +* Caching Target Data:: Data caching for targets +* Searching Memory:: Searching memory for a sequence of bytes + + +File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data + +10.1 Expressions +================ + +'print' and many other GDB commands accept an expression and compute its +value. Any kind of constant, variable or operator defined by the +programming language you are using is valid in an expression in GDB. +This includes conditional expressions, function calls, casts, and string +constants. It also includes preprocessor macros, if you compiled your +program to include this information; see *note Compilation::. + + GDB supports array constants in expressions input by the user. The +syntax is {ELEMENT, ELEMENT...}. For example, you can use the command +'print {1, 2, 3}' to create an array of three integers. If you pass an +array to a function or assign it to a program variable, GDB copies the +array to memory that is 'malloc'ed in the target program. + + Because C is so widespread, most of the expressions shown in examples +in this manual are in C. *Note Using GDB with Different Languages: +Languages, for information on how to use expressions in other languages. + + In this section, we discuss operators that you can use in GDB +expressions regardless of your programming language. + + Casts are supported in all languages, not just in C, because it is so +useful to cast a number into a pointer in order to examine a structure +at that address in memory. + + GDB supports these operators, in addition to those common to +programming languages: + +'@' + '@' is a binary operator for treating parts of memory as arrays. + *Note Artificial Arrays: Arrays, for more information. + +'::' + '::' allows you to specify a variable in terms of the file or + function where it is defined. *Note Program Variables: Variables. + +'{TYPE} ADDR' + Refers to an object of type TYPE stored at address ADDR in memory. + ADDR may be any expression whose value is an integer or pointer + (but parentheses are required around binary operators, just as in a + cast). This construct is allowed regardless of what kind of data + is normally supposed to reside at ADDR. + + +File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data + +10.2 Ambiguous Expressions +========================== + +Expressions can sometimes contain some ambiguous elements. For +instance, some programming languages (notably Ada, C++ and Objective-C) +permit a single function name to be defined several times, for +application in different contexts. This is called "overloading". +Another example involving Ada is generics. A "generic package" is +similar to C++ templates and is typically instantiated several times, +resulting in the same function name being defined in different contexts. + + In some cases and depending on the language, it is possible to adjust +the expression to remove the ambiguity. For instance in C++, you can +specify the signature of the function you want to break on, as in 'break +FUNCTION(TYPES)'. In Ada, using the fully qualified name of your +function often makes the expression unambiguous as well. + + When an ambiguity that needs to be resolved is detected, the debugger +has the capability to display a menu of numbered choices for each +possibility, and then waits for the selection with the prompt '>'. The +first option is always '[0] cancel', and typing '0 ' aborts the +current command. If the command in which the expression was used allows +more than one choice to be selected, the next option in the menu is '[1] +all', and typing '1 ' selects all possible choices. + + For example, the following session excerpt shows an attempt to set a +breakpoint at the overloaded symbol 'String::after'. We choose three +particular definitions of that function name: + + (gdb) b String::after + [0] cancel + [1] all + [2] file:String.cc; line number:867 + [3] file:String.cc; line number:860 + [4] file:String.cc; line number:875 + [5] file:String.cc; line number:853 + [6] file:String.cc; line number:846 + [7] file:String.cc; line number:735 + > 2 4 6 + Breakpoint 1 at 0xb26c: file String.cc, line 867. + Breakpoint 2 at 0xb344: file String.cc, line 875. + Breakpoint 3 at 0xafcc: file String.cc, line 846. + Multiple breakpoints were set. + Use the "delete" command to delete unwanted + breakpoints. + (gdb) + +'set multiple-symbols MODE' + + This option allows you to adjust the debugger behavior when an + expression is ambiguous. + + By default, MODE is set to 'all'. If the command with which the + expression is used allows more than one choice, then GDB + automatically selects all possible choices. For instance, + inserting a breakpoint on a function using an ambiguous name + results in a breakpoint inserted on each possible match. However, + if a unique choice must be made, then GDB uses the menu to help you + disambiguate the expression. For instance, printing the address of + an overloaded function will result in the use of the menu. + + When MODE is set to 'ask', the debugger always uses the menu when + an ambiguity is detected. + + Finally, when MODE is set to 'cancel', the debugger reports an + error due to the ambiguity and the command is aborted. + +'show multiple-symbols' + Show the current value of the 'multiple-symbols' setting. + + +File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data + +10.3 Program Variables +====================== + +The most common kind of expression to use is the name of a variable in +your program. + + Variables in expressions are understood in the selected stack frame +(*note Selecting a Frame: Selection.); they must be either: + + * global (or file-static) + +or + + * visible according to the scope rules of the programming language + from the point of execution in that frame + +This means that in the function + + foo (a) + int a; + { + bar (a); + { + int b = test (); + bar (b); + } + } + +you can examine and use the variable 'a' whenever your program is +executing within the function 'foo', but you can only use or examine the +variable 'b' while your program is executing inside the block where 'b' +is declared. + + There is an exception: you can refer to a variable or function whose +scope is a single source file even if the current execution point is not +in this file. But it is possible to have more than one such variable or +function with the same name (in different source files). If that +happens, referring to that name has unpredictable effects. If you wish, +you can specify a static variable in a particular function or file by +using the colon-colon ('::') notation: + + FILE::VARIABLE + FUNCTION::VARIABLE + +Here FILE or FUNCTION is the name of the context for the static +VARIABLE. In the case of file names, you can use quotes to make sure +GDB parses the file name as a single word--for example, to print a +global value of 'x' defined in 'f2.c': + + (gdb) p 'f2.c'::x + + The '::' notation is normally used for referring to static variables, +since you typically disambiguate uses of local variables in functions by +selecting the appropriate frame and using the simple name of the +variable. However, you may also use this notation to refer to local +variables in frames enclosing the selected frame: + + void + foo (int a) + { + if (a < 10) + bar (a); + else + process (a); /* Stop here */ + } + + int + bar (int a) + { + foo (a + 5); + } + +For example, if there is a breakpoint at the commented line, here is +what you might see when the program stops after executing the call +'bar(0)': + + (gdb) p a + $1 = 10 + (gdb) p bar::a + $2 = 5 + (gdb) up 2 + #2 0x080483d0 in foo (a=5) at foobar.c:12 + (gdb) p a + $3 = 5 + (gdb) p bar::a + $4 = 0 + + These uses of '::' are very rarely in conflict with the very similar +use of the same notation in C++. When they are in conflict, the C++ +meaning takes precedence; however, this can be overridden by quoting the +file or function name with single quotes. + + For example, suppose the program is stopped in a method of a class +that has a field named 'includefile', and there is also an include file +named 'includefile' that defines a variable, 'some_global'. + + (gdb) p includefile + $1 = 23 + (gdb) p includefile::some_global + A syntax error in expression, near `'. + (gdb) p 'includefile'::some_global + $2 = 27 + + _Warning:_ Occasionally, a local variable may appear to have the + wrong value at certain points in a function--just after entry to a + new scope, and just before exit. + You may see this problem when you are stepping by machine +instructions. This is because, on most machines, it takes more than one +instruction to set up a stack frame (including local variable +definitions); if you are stepping by machine instructions, variables may +appear to have the wrong values until the stack frame is completely +built. On exit, it usually also takes more than one machine instruction +to destroy a stack frame; after you begin stepping through that group of +instructions, local variable definitions may be gone. + + This may also happen when the compiler does significant +optimizations. To be sure of always seeing accurate values, turn off +all optimization when compiling. + + Another possible effect of compiler optimizations is to optimize +unused variables out of existence, or assign variables to registers (as +opposed to memory addresses). Depending on the support for such cases +offered by the debug info format used by the compiler, GDB might not be +able to display values for such local variables. If that happens, GDB +will print a message like this: + + No symbol "foo" in current context. + + To solve such problems, either recompile without optimizations, or +use a different debug info format, if the compiler supports several such +formats. *Note Compilation::, for more information on choosing compiler +options. *Note C and C++: C, for more information about debug info +formats that are best suited to C++ programs. + + If you ask to print an object whose contents are unknown to GDB, +e.g., because its data type is not completely specified by the debug +information, GDB will say ''. *Note incomplete type: +Symbols, for more about this. + + If you append '@entry' string to a function parameter name you get +its value at the time the function got called. If the value is not +available an error message is printed. Entry values are available only +with some compilers. Entry values are normally also printed at the +function parameter list according to *note set print entry-values::. + + Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29 + 29 i++; + (gdb) next + 30 e (i); + (gdb) print i + $1 = 31 + (gdb) print i@entry + $2 = 30 + + Strings are identified as arrays of 'char' values without specified +signedness. Arrays of either 'signed char' or 'unsigned char' get +printed as arrays of 1 byte sized integers. '-fsigned-char' or +'-funsigned-char' GCC options have no effect as GDB defines literal +string type '"char"' as 'char' without a sign. For program code + + char var0[] = "A"; + signed char var1[] = "A"; + + You get during debugging + (gdb) print var0 + $1 = "A" + (gdb) print var1 + $2 = {65 'A', 0 '\0'} + diff --git a/util/X86MAC64/share/info/gdb.info-2 b/util/X86MAC64/share/info/gdb.info-2 new file mode 100644 index 0000000000..9fd0d737b2 --- /dev/null +++ b/util/X86MAC64/share/info/gdb.info-2 @@ -0,0 +1,7657 @@ +This is gdb.info, produced by makeinfo version 5.1 from gdb.texinfo. + +Copyright (C) 1988-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + +File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data + +10.4 Artificial Arrays +====================== + +It is often useful to print out several successive objects of the same +type in memory; a section of an array, or an array of dynamically +determined size for which only a pointer exists in the program. + + You can do this by referring to a contiguous span of memory as an +"artificial array", using the binary operator '@'. The left operand of +'@' should be the first element of the desired array and be an +individual object. The right operand should be the desired length of +the array. The result is an array value whose elements are all of the +type of the left argument. The first element is actually the left +argument; the second element comes from bytes of memory immediately +following those that hold the first element, and so on. Here is an +example. If a program says + + int *array = (int *) malloc (len * sizeof (int)); + +you can print the contents of 'array' with + + p *array@len + + The left operand of '@' must reside in memory. Array values made +with '@' in this way behave just like other arrays in terms of +subscripting, and are coerced to pointers when used in expressions. +Artificial arrays most often appear in expressions via the value history +(*note Value History: Value History.), after printing one out. + + Another way to create an artificial array is to use a cast. This +re-interprets a value as if it were an array. The value need not be in +memory: + (gdb) p/x (short[2])0x12345678 + $1 = {0x1234, 0x5678} + + As a convenience, if you leave the array length out (as in +'(TYPE[])VALUE') GDB calculates the size to fill the value (as +'sizeof(VALUE)/sizeof(TYPE)': + (gdb) p/x (short[])0x12345678 + $2 = {0x1234, 0x5678} + + Sometimes the artificial array mechanism is not quite enough; in +moderately complex data structures, the elements of interest may not +actually be adjacent--for example, if you are interested in the values +of pointers in an array. One useful work-around in this situation is to +use a convenience variable (*note Convenience Variables: Convenience +Vars.) as a counter in an expression that prints the first interesting +value, and then repeat that expression via . For instance, suppose +you have an array 'dtab' of pointers to structures, and you are +interested in the values of a field 'fv' in each structure. Here is an +example of what you might type: + + set $i = 0 + p dtab[$i++]->fv + + + ... + + +File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data + +10.5 Output Formats +=================== + +By default, GDB prints a value according to its data type. Sometimes +this is not what you want. For example, you might want to print a +number in hex, or a pointer in decimal. Or you might want to view data +in memory at a certain address as a character string or as an +instruction. To do these things, specify an "output format" when you +print a value. + + The simplest use of output formats is to say how to print a value +already computed. This is done by starting the arguments of the 'print' +command with a slash and a format letter. The format letters supported +are: + +'x' + Regard the bits of the value as an integer, and print the integer + in hexadecimal. + +'d' + Print as integer in signed decimal. + +'u' + Print as integer in unsigned decimal. + +'o' + Print as integer in octal. + +'t' + Print as integer in binary. The letter 't' stands for "two". (1) + +'a' + Print as an address, both absolute in hexadecimal and as an offset + from the nearest preceding symbol. You can use this format used to + discover where (in what function) an unknown address is located: + + (gdb) p/a 0x54320 + $3 = 0x54320 <_initialize_vx+396> + + The command 'info symbol 0x54320' yields similar results. *Note + info symbol: Symbols. + +'c' + Regard as an integer and print it as a character constant. This + prints both the numerical value and its character representation. + The character representation is replaced with the octal escape + '\nnn' for characters outside the 7-bit ASCII range. + + Without this format, GDB displays 'char', 'unsigned char', and 'signed char' + data as character constants. Single-byte members of vectors are + displayed as integer data. + +'f' + Regard the bits of the value as a floating point number and print + using typical floating point syntax. + +'s' + Regard as a string, if possible. With this format, pointers to + single-byte data are displayed as null-terminated strings and + arrays of single-byte data are displayed as fixed-length strings. + Other values are displayed in their natural types. + + Without this format, GDB displays pointers to and arrays of 'char', + 'unsigned char', and 'signed char' as strings. Single-byte members + of a vector are displayed as an integer array. + +'z' + Like 'x' formatting, the value is treated as an integer and printed + as hexadecimal, but leading zeros are printed to pad the value to + the size of the integer type. + +'r' + Print using the 'raw' formatting. By default, GDB will use a + Python-based pretty-printer, if one is available (*note Pretty + Printing::). This typically results in a higher-level display of + the value's contents. The 'r' format bypasses any Python + pretty-printer which might exist. + + For example, to print the program counter in hex (*note Registers::), +type + + p/x $pc + +Note that no space is required before the slash; this is because command +names in GDB cannot contain a slash. + + To reprint the last value in the value history with a different +format, you can use the 'print' command with just a format and no +expression. For example, 'p/x' reprints the last value in hex. + + ---------- Footnotes ---------- + + (1) 'b' cannot be used because these format letters are also used +with the 'x' command, where 'b' stands for "byte"; see *note Examining +Memory: Memory. + + +File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data + +10.6 Examining Memory +===================== + +You can use the command 'x' (for "examine") to examine memory in any of +several formats, independently of your program's data types. + +'x/NFU ADDR' +'x ADDR' +'x' + Use the 'x' command to examine memory. + + N, F, and U are all optional parameters that specify how much memory +to display and how to format it; ADDR is an expression giving the +address where you want to start displaying memory. If you use defaults +for NFU, you need not type the slash '/'. Several commands set +convenient defaults for ADDR. + +N, the repeat count + The repeat count is a decimal integer; the default is 1. It + specifies how much memory (counting by units U) to display. + +F, the display format + The display format is one of the formats used by 'print' ('x', 'd', + 'u', 'o', 't', 'a', 'c', 'f', 's'), and in addition 'i' (for + machine instructions). The default is 'x' (hexadecimal) initially. + The default changes each time you use either 'x' or 'print'. + +U, the unit size + The unit size is any of + + 'b' + Bytes. + 'h' + Halfwords (two bytes). + 'w' + Words (four bytes). This is the initial default. + 'g' + Giant words (eight bytes). + + Each time you specify a unit size with 'x', that size becomes the + default unit the next time you use 'x'. For the 'i' format, the + unit size is ignored and is normally not written. For the 's' + format, the unit size defaults to 'b', unless it is explicitly + given. Use 'x /hs' to display 16-bit char strings and 'x /ws' to + display 32-bit strings. The next use of 'x /s' will again display + 8-bit strings. Note that the results depend on the programming + language of the current compilation unit. If the language is C, + the 's' modifier will use the UTF-16 encoding while 'w' will use + UTF-32. The encoding is set by the programming language and cannot + be altered. + +ADDR, starting display address + ADDR is the address where you want GDB to begin displaying memory. + The expression need not have a pointer value (though it may); it is + always interpreted as an integer address of a byte of memory. + *Note Expressions: Expressions, for more information on + expressions. The default for ADDR is usually just after the last + address examined--but several other commands also set the default + address: 'info breakpoints' (to the address of the last breakpoint + listed), 'info line' (to the starting address of a line), and + 'print' (if you use it to display a value from memory). + + For example, 'x/3uh 0x54320' is a request to display three halfwords +('h') of memory, formatted as unsigned decimal integers ('u'), starting +at address '0x54320'. 'x/4xw $sp' prints the four words ('w') of memory +above the stack pointer (here, '$sp'; *note Registers: Registers.) in +hexadecimal ('x'). + + Since the letters indicating unit sizes are all distinct from the +letters specifying output formats, you do not have to remember whether +unit size or format comes first; either order works. The output +specifications '4xw' and '4wx' mean exactly the same thing. (However, +the count N must come first; 'wx4' does not work.) + + Even though the unit size U is ignored for the formats 's' and 'i', +you might still want to use a count N; for example, '3i' specifies that +you want to see three machine instructions, including any operands. For +convenience, especially when used with the 'display' command, the 'i' +format also prints branch delay slot instructions, if any, beyond the +count specified, which immediately follow the last instruction that is +within the count. The command 'disassemble' gives an alternative way of +inspecting machine instructions; see *note Source and Machine Code: +Machine Code. + + All the defaults for the arguments to 'x' are designed to make it +easy to continue scanning memory with minimal specifications each time +you use 'x'. For example, after you have inspected three machine +instructions with 'x/3i ADDR', you can inspect the next seven with just +'x/7'. If you use to repeat the 'x' command, the repeat count N +is used again; the other arguments default as for successive uses of +'x'. + + When examining machine instructions, the instruction at current +program counter is shown with a '=>' marker. For example: + + (gdb) x/5i $pc-6 + 0x804837f : mov %esp,%ebp + 0x8048381 : push %ecx + 0x8048382 : sub $0x4,%esp + => 0x8048385 : movl $0x8048460,(%esp) + 0x804838c : call 0x80482d4 + + The addresses and contents printed by the 'x' command are not saved +in the value history because there is often too much of them and they +would get in the way. Instead, GDB makes these values available for +subsequent use in expressions as values of the convenience variables +'$_' and '$__'. After an 'x' command, the last address examined is +available for use in expressions in the convenience variable '$_'. The +contents of that address, as examined, are available in the convenience +variable '$__'. + + If the 'x' command has a repeat count, the address and contents saved +are from the last memory unit printed; this is not the same as the last +address printed if several units were printed on the last line of +output. + + When you are debugging a program running on a remote target machine +(*note Remote Debugging::), you may wish to verify the program's image +in the remote machine's memory against the executable file you +downloaded to the target. The 'compare-sections' command is provided +for such situations. + +'compare-sections [SECTION-NAME]' + Compare the data of a loadable section SECTION-NAME in the + executable file of the program being debugged with the same section + in the remote machine's memory, and report any mismatches. With no + arguments, compares all loadable sections. This command's + availability depends on the target's support for the '"qCRC"' + remote request. + + +File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data + +10.7 Automatic Display +====================== + +If you find that you want to print the value of an expression frequently +(to see how it changes), you might want to add it to the "automatic +display list" so that GDB prints its value each time your program stops. +Each expression added to the list is given a number to identify it; to +remove an expression from the list, you specify that number. The +automatic display looks like this: + + 2: foo = 38 + 3: bar[5] = (struct hack *) 0x3804 + +This display shows item numbers, expressions and their current values. +As with displays you request manually using 'x' or 'print', you can +specify the output format you prefer; in fact, 'display' decides whether +to use 'print' or 'x' depending your format specification--it uses 'x' +if you specify either the 'i' or 's' format, or a unit size; otherwise +it uses 'print'. + +'display EXPR' + Add the expression EXPR to the list of expressions to display each + time your program stops. *Note Expressions: Expressions. + + 'display' does not repeat if you press again after using it. + +'display/FMT EXPR' + For FMT specifying only a display format and not a size or count, + add the expression EXPR to the auto-display list but arrange to + display it each time in the specified format FMT. *Note Output + Formats: Output Formats. + +'display/FMT ADDR' + For FMT 'i' or 's', or including a unit-size or a number of units, + add the expression ADDR as a memory address to be examined each + time your program stops. Examining means in effect doing 'x/FMT + ADDR'. *Note Examining Memory: Memory. + + For example, 'display/i $pc' can be helpful, to see the machine +instruction about to be executed each time execution stops ('$pc' is a +common name for the program counter; *note Registers: Registers.). + +'undisplay DNUMS...' +'delete display DNUMS...' + Remove items from the list of expressions to display. Specify the + numbers of the displays that you want affected with the command + argument DNUMS. It can be a single display number, one of the + numbers shown in the first field of the 'info display' display; or + it could be a range of display numbers, as in '2-4'. + + 'undisplay' does not repeat if you press after using it. + (Otherwise you would just get the error 'No display number ...'.) + +'disable display DNUMS...' + Disable the display of item numbers DNUMS. A disabled display item + is not printed automatically, but is not forgotten. It may be + enabled again later. Specify the numbers of the displays that you + want affected with the command argument DNUMS. It can be a single + display number, one of the numbers shown in the first field of the + 'info display' display; or it could be a range of display numbers, + as in '2-4'. + +'enable display DNUMS...' + Enable display of item numbers DNUMS. It becomes effective once + again in auto display of its expression, until you specify + otherwise. Specify the numbers of the displays that you want + affected with the command argument DNUMS. It can be a single + display number, one of the numbers shown in the first field of the + 'info display' display; or it could be a range of display numbers, + as in '2-4'. + +'display' + Display the current values of the expressions on the list, just as + is done when your program stops. + +'info display' + Print the list of expressions previously set up to display + automatically, each one with its item number, but without showing + the values. This includes disabled expressions, which are marked + as such. It also includes expressions which would not be displayed + right now because they refer to automatic variables not currently + available. + + If a display expression refers to local variables, then it does not +make sense outside the lexical context for which it was set up. Such an +expression is disabled when execution enters a context where one of its +variables is not defined. For example, if you give the command 'display +last_char' while inside a function with an argument 'last_char', GDB +displays this argument while your program continues to stop inside that +function. When it stops elsewhere--where there is no variable +'last_char'--the display is disabled automatically. The next time your +program stops where 'last_char' is meaningful, you can enable the +display expression once again. + + +File: gdb.info, Node: Print Settings, Next: Pretty Printing, Prev: Auto Display, Up: Data + +10.8 Print Settings +=================== + +GDB provides the following ways to control how arrays, structures, and +symbols are printed. + +These settings are useful for debugging programs in any language: + +'set print address' +'set print address on' + GDB prints memory addresses showing the location of stack traces, + structure values, pointer values, breakpoints, and so forth, even + when it also displays the contents of those addresses. The default + is 'on'. For example, this is what a stack frame display looks + like with 'set print address on': + + (gdb) f + #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") + at input.c:530 + 530 if (lquote != def_lquote) + +'set print address off' + Do not print addresses when displaying their contents. For + example, this is the same stack frame displayed with 'set print + address off': + + (gdb) set print addr off + (gdb) f + #0 set_quotes (lq="<<", rq=">>") at input.c:530 + 530 if (lquote != def_lquote) + + You can use 'set print address off' to eliminate all machine + dependent displays from the GDB interface. For example, with + 'print address off', you should get the same text for backtraces on + all machines--whether or not they involve pointer arguments. + +'show print address' + Show whether or not addresses are to be printed. + + When GDB prints a symbolic address, it normally prints the closest +earlier symbol plus an offset. If that symbol does not uniquely +identify the address (for example, it is a name whose scope is a single +source file), you may need to clarify. One way to do this is with 'info +line', for example 'info line *0x4537'. Alternately, you can set GDB to +print the source file and line number when it prints a symbolic address: + +'set print symbol-filename on' + Tell GDB to print the source file name and line number of a symbol + in the symbolic form of an address. + +'set print symbol-filename off' + Do not print source file name and line number of a symbol. This is + the default. + +'show print symbol-filename' + Show whether or not GDB will print the source file name and line + number of a symbol in the symbolic form of an address. + + Another situation where it is helpful to show symbol filenames and +line numbers is when disassembling code; GDB shows you the line number +and source file that corresponds to each instruction. + + Also, you may wish to see the symbolic form only if the address being +printed is reasonably close to the closest earlier symbol: + +'set print max-symbolic-offset MAX-OFFSET' +'set print max-symbolic-offset unlimited' + Tell GDB to only display the symbolic form of an address if the + offset between the closest earlier symbol and the address is less + than MAX-OFFSET. The default is 'unlimited', which tells GDB to + always print the symbolic form of an address if any symbol precedes + it. Zero is equivalent to 'unlimited'. + +'show print max-symbolic-offset' + Ask how large the maximum offset is that GDB prints in a symbolic + address. + + If you have a pointer and you are not sure where it points, try 'set +print symbol-filename on'. Then you can determine the name and source +file location of the variable where it points, using 'p/a POINTER'. +This interprets the address in symbolic form. For example, here GDB +shows that a variable 'ptt' points at another variable 't', defined in +'hi2.c': + + (gdb) set print symbol-filename on + (gdb) p/a ptt + $4 = 0xe008 + + _Warning:_ For pointers that point to a local variable, 'p/a' does + not show the symbol name and filename of the referent, even with + the appropriate 'set print' options turned on. + + You can also enable '/a'-like formatting all the time using 'set +print symbol on': + +'set print symbol on' + Tell GDB to print the symbol corresponding to an address, if one + exists. + +'set print symbol off' + Tell GDB not to print the symbol corresponding to an address. In + this mode, GDB will still print the symbol corresponding to + pointers to functions. This is the default. + +'show print symbol' + Show whether GDB will display the symbol corresponding to an + address. + + Other settings control how different kinds of objects are printed: + +'set print array' +'set print array on' + Pretty print arrays. This format is more convenient to read, but + uses more space. The default is off. + +'set print array off' + Return to compressed format for arrays. + +'show print array' + Show whether compressed or pretty format is selected for displaying + arrays. + +'set print array-indexes' +'set print array-indexes on' + Print the index of each element when displaying arrays. May be + more convenient to locate a given element in the array or quickly + find the index of a given element in that printed array. The + default is off. + +'set print array-indexes off' + Stop printing element indexes when displaying arrays. + +'show print array-indexes' + Show whether the index of each element is printed when displaying + arrays. + +'set print elements NUMBER-OF-ELEMENTS' +'set print elements unlimited' + Set a limit on how many elements of an array GDB will print. If + GDB is printing a large array, it stops printing after it has + printed the number of elements set by the 'set print elements' + command. This limit also applies to the display of strings. When + GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS + to 'unlimited' or zero means that the number of elements to print + is unlimited. + +'show print elements' + Display the number of elements of a large array that GDB will + print. If the number is 0, then the printing is unlimited. + +'set print frame-arguments VALUE' + This command allows to control how the values of arguments are + printed when the debugger prints a frame (*note Frames::). The + possible values are: + + 'all' + The values of all arguments are printed. + + 'scalars' + Print the value of an argument only if it is a scalar. The + value of more complex arguments such as arrays, structures, + unions, etc, is replaced by '...'. This is the default. Here + is an example where only scalar arguments are shown: + + #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) + at frame-args.c:23 + + 'none' + None of the argument values are printed. Instead, the value + of each argument is replaced by '...'. In this case, the + example above now becomes: + + #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) + at frame-args.c:23 + + By default, only scalar arguments are printed. This command can be + used to configure the debugger to print the value of all arguments, + regardless of their type. However, it is often advantageous to not + print the value of more complex parameters. For instance, it + reduces the amount of information printed in each frame, making the + backtrace more readable. Also, it improves performance when + displaying Ada frames, because the computation of large arguments + can sometimes be CPU-intensive, especially in large applications. + Setting 'print frame-arguments' to 'scalars' (the default) or + 'none' avoids this computation, thus speeding up the display of + each Ada frame. + +'show print frame-arguments' + Show how the value of arguments should be displayed when printing a + frame. + +'set print raw frame-arguments on' + Print frame arguments in raw, non pretty-printed, form. + +'set print raw frame-arguments off' + Print frame arguments in pretty-printed form, if there is a + pretty-printer for the value (*note Pretty Printing::), otherwise + print the value in raw form. This is the default. + +'show print raw frame-arguments' + Show whether to print frame arguments in raw form. + +'set print entry-values VALUE' + Set printing of frame argument values at function entry. In some + cases GDB can determine the value of function argument which was + passed by the function caller, even if the value was modified + inside the called function and therefore is different. With + optimized code, the current value could be unavailable, but the + entry value may still be known. + + The default value is 'default' (see below for its description). + Older GDB behaved as with the setting 'no'. Compilers not + supporting this feature will behave in the 'default' setting the + same way as with the 'no' setting. + + This functionality is currently supported only by DWARF 2 debugging + format and the compiler has to produce 'DW_TAG_GNU_call_site' tags. + With GCC, you need to specify '-O -g' during compilation, to get + this information. + + The VALUE parameter can be one of the following: + + 'no' + Print only actual parameter values, never print values from + function entry point. + #0 equal (val=5) + #0 different (val=6) + #0 lost (val=) + #0 born (val=10) + #0 invalid (val=) + + 'only' + Print only parameter values from function entry point. The + actual parameter values are never printed. + #0 equal (val@entry=5) + #0 different (val@entry=5) + #0 lost (val@entry=5) + #0 born (val@entry=) + #0 invalid (val@entry=) + + 'preferred' + Print only parameter values from function entry point. If + value from function entry point is not known while the actual + value is known, print the actual value for such parameter. + #0 equal (val@entry=5) + #0 different (val@entry=5) + #0 lost (val@entry=5) + #0 born (val=10) + #0 invalid (val@entry=) + + 'if-needed' + Print actual parameter values. If actual parameter value is + not known while value from function entry point is known, + print the entry point value for such parameter. + #0 equal (val=5) + #0 different (val=6) + #0 lost (val@entry=5) + #0 born (val=10) + #0 invalid (val=) + + 'both' + Always print both the actual parameter value and its value + from function entry point, even if values of one or both are + not available due to compiler optimizations. + #0 equal (val=5, val@entry=5) + #0 different (val=6, val@entry=5) + #0 lost (val=, val@entry=5) + #0 born (val=10, val@entry=) + #0 invalid (val=, val@entry=) + + 'compact' + Print the actual parameter value if it is known and also its + value from function entry point if it is known. If neither is + known, print for the actual value ''. If not + in MI mode (*note GDB/MI::) and if both values are known and + identical, print the shortened 'param=param@entry=VALUE' + notation. + #0 equal (val=val@entry=5) + #0 different (val=6, val@entry=5) + #0 lost (val@entry=5) + #0 born (val=10) + #0 invalid (val=) + + 'default' + Always print the actual parameter value. Print also its value + from function entry point, but only if it is known. If not in + MI mode (*note GDB/MI::) and if both values are known and + identical, print the shortened 'param=param@entry=VALUE' + notation. + #0 equal (val=val@entry=5) + #0 different (val=6, val@entry=5) + #0 lost (val=, val@entry=5) + #0 born (val=10) + #0 invalid (val=) + + For analysis messages on possible failures of frame argument values + at function entry resolution see *note set debug entry-values::. + +'show print entry-values' + Show the method being used for printing of frame argument values at + function entry. + +'set print repeats NUMBER-OF-REPEATS' +'set print repeats unlimited' + Set the threshold for suppressing display of repeated array + elements. When the number of consecutive identical elements of an + array exceeds the threshold, GDB prints the string '""', where N is the number of identical repetitions, instead + of displaying the identical elements themselves. Setting the + threshold to 'unlimited' or zero will cause all elements to be + individually printed. The default threshold is 10. + +'show print repeats' + Display the current threshold for printing repeated identical + elements. + +'set print null-stop' + Cause GDB to stop printing the characters of an array when the + first NULL is encountered. This is useful when large arrays + actually contain only short strings. The default is off. + +'show print null-stop' + Show whether GDB stops printing an array on the first NULL + character. + +'set print pretty on' + Cause GDB to print structures in an indented format with one member + per line, like this: + + $1 = { + next = 0x0, + flags = { + sweet = 1, + sour = 1 + }, + meat = 0x54 "Pork" + } + +'set print pretty off' + Cause GDB to print structures in a compact format, like this: + + $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ + meat = 0x54 "Pork"} + + This is the default format. + +'show print pretty' + Show which format GDB is using to print structures. + +'set print sevenbit-strings on' + Print using only seven-bit characters; if this option is set, GDB + displays any eight-bit characters (in strings or character values) + using the notation '\'NNN. This setting is best if you are working + in English (ASCII) and you use the high-order bit of characters as + a marker or "meta" bit. + +'set print sevenbit-strings off' + Print full eight-bit characters. This allows the use of more + international character sets, and is the default. + +'show print sevenbit-strings' + Show whether or not GDB is printing only seven-bit characters. + +'set print union on' + Tell GDB to print unions which are contained in structures and + other unions. This is the default setting. + +'set print union off' + Tell GDB not to print unions which are contained in structures and + other unions. GDB will print '"{...}"' instead. + +'show print union' + Ask GDB whether or not it will print unions which are contained in + structures and other unions. + + For example, given the declarations + + typedef enum {Tree, Bug} Species; + typedef enum {Big_tree, Acorn, Seedling} Tree_forms; + typedef enum {Caterpillar, Cocoon, Butterfly} + Bug_forms; + + struct thing { + Species it; + union { + Tree_forms tree; + Bug_forms bug; + } form; + }; + + struct thing foo = {Tree, {Acorn}}; + + with 'set print union on' in effect 'p foo' would print + + $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} + + and with 'set print union off' in effect it would print + + $1 = {it = Tree, form = {...}} + + 'set print union' affects programs written in C-like languages and + in Pascal. + +These settings are of interest when debugging C++ programs: + +'set print demangle' +'set print demangle on' + Print C++ names in their source form rather than in the encoded + ("mangled") form passed to the assembler and linker for type-safe + linkage. The default is on. + +'show print demangle' + Show whether C++ names are printed in mangled or demangled form. + +'set print asm-demangle' +'set print asm-demangle on' + Print C++ names in their source form rather than their mangled + form, even in assembler code printouts such as instruction + disassemblies. The default is off. + +'show print asm-demangle' + Show whether C++ names in assembly listings are printed in mangled + or demangled form. + +'set demangle-style STYLE' + Choose among several encoding schemes used by different compilers + to represent C++ names. The choices for STYLE are currently: + + 'auto' + Allow GDB to choose a decoding style by inspecting your + program. This is the default. + + 'gnu' + Decode based on the GNU C++ compiler ('g++') encoding + algorithm. + + 'hp' + Decode based on the HP ANSI C++ ('aCC') encoding algorithm. + + 'lucid' + Decode based on the Lucid C++ compiler ('lcc') encoding + algorithm. + + 'arm' + Decode using the algorithm in the 'C++ Annotated Reference + Manual'. *Warning:* this setting alone is not sufficient to + allow debugging 'cfront'-generated executables. GDB would + require further enhancement to permit that. + + If you omit STYLE, you will see a list of possible formats. + +'show demangle-style' + Display the encoding style currently in use for decoding C++ + symbols. + +'set print object' +'set print object on' + When displaying a pointer to an object, identify the _actual_ + (derived) type of the object rather than the _declared_ type, using + the virtual function table. Note that the virtual function table + is required--this feature can only work for objects that have + run-time type identification; a single virtual method in the + object's declared type is sufficient. Note that this setting is + also taken into account when working with variable objects via MI + (*note GDB/MI::). + +'set print object off' + Display only the declared type of objects, without reference to the + virtual function table. This is the default setting. + +'show print object' + Show whether actual, or declared, object types are displayed. + +'set print static-members' +'set print static-members on' + Print static members when displaying a C++ object. The default is + on. + +'set print static-members off' + Do not print static members when displaying a C++ object. + +'show print static-members' + Show whether C++ static members are printed or not. + +'set print pascal_static-members' +'set print pascal_static-members on' + Print static members when displaying a Pascal object. The default + is on. + +'set print pascal_static-members off' + Do not print static members when displaying a Pascal object. + +'show print pascal_static-members' + Show whether Pascal static members are printed or not. + +'set print vtbl' +'set print vtbl on' + Pretty print C++ virtual function tables. The default is off. + (The 'vtbl' commands do not work on programs compiled with the HP + ANSI C++ compiler ('aCC').) + +'set print vtbl off' + Do not pretty print C++ virtual function tables. + +'show print vtbl' + Show whether C++ virtual function tables are pretty printed, or + not. + + +File: gdb.info, Node: Pretty Printing, Next: Value History, Prev: Print Settings, Up: Data + +10.9 Pretty Printing +==================== + +GDB provides a mechanism to allow pretty-printing of values using Python +code. It greatly simplifies the display of complex objects. This +mechanism works for both MI and the CLI. + +* Menu: + +* Pretty-Printer Introduction:: Introduction to pretty-printers +* Pretty-Printer Example:: An example pretty-printer +* Pretty-Printer Commands:: Pretty-printer commands + + +File: gdb.info, Node: Pretty-Printer Introduction, Next: Pretty-Printer Example, Up: Pretty Printing + +10.9.1 Pretty-Printer Introduction +---------------------------------- + +When GDB prints a value, it first sees if there is a pretty-printer +registered for the value. If there is then GDB invokes the +pretty-printer to print the value. Otherwise the value is printed +normally. + + Pretty-printers are normally named. This makes them easy to manage. +The 'info pretty-printer' command will list all the installed +pretty-printers with their names. If a pretty-printer can handle +multiple data types, then its "subprinters" are the printers for the +individual data types. Each such subprinter has its own name. The +format of the name is PRINTER-NAME;SUBPRINTER-NAME. + + Pretty-printers are installed by "registering" them with GDB. +Typically they are automatically loaded and registered when the +corresponding debug information is loaded, thus making them available +without having to do anything special. + + There are three places where a pretty-printer can be registered. + + * Pretty-printers registered globally are available when debugging + all inferiors. + + * Pretty-printers registered with a program space are available only + when debugging that program. *Note Progspaces In Python::, for + more details on program spaces in Python. + + * Pretty-printers registered with an objfile are loaded and unloaded + with the corresponding objfile (e.g., shared library). *Note + Objfiles In Python::, for more details on objfiles in Python. + + *Note Selecting Pretty-Printers::, for further information on how +pretty-printers are selected, + + *Note Writing a Pretty-Printer::, for implementing pretty printers +for new types. + + +File: gdb.info, Node: Pretty-Printer Example, Next: Pretty-Printer Commands, Prev: Pretty-Printer Introduction, Up: Pretty Printing + +10.9.2 Pretty-Printer Example +----------------------------- + +Here is how a C++ 'std::string' looks without a pretty-printer: + + (gdb) print s + $1 = { + static npos = 4294967295, + _M_dataplus = { + > = { + <__gnu_cxx::new_allocator> = { + }, + }, + members of std::basic_string, + std::allocator >::_Alloc_hider: + _M_p = 0x804a014 "abcd" + } + } + + With a pretty-printer for 'std::string' only the contents are +printed: + + (gdb) print s + $2 = "abcd" + + +File: gdb.info, Node: Pretty-Printer Commands, Prev: Pretty-Printer Example, Up: Pretty Printing + +10.9.3 Pretty-Printer Commands +------------------------------ + +'info pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' + Print the list of installed pretty-printers. This includes + disabled pretty-printers, which are marked as such. + + OBJECT-REGEXP is a regular expression matching the objects whose + pretty-printers to list. Objects can be 'global', the program + space's file (*note Progspaces In Python::), and the object files + within that program space (*note Objfiles In Python::). *Note + Selecting Pretty-Printers::, for details on how GDB looks up a + printer from these three objects. + + NAME-REGEXP is a regular expression matching the name of the + printers to list. + +'disable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' + Disable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. A + disabled pretty-printer is not forgotten, it may be enabled again + later. + +'enable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' + Enable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. + + Example: + + Suppose we have three pretty-printers installed: one from library1.so +named 'foo' that prints objects of type 'foo', and another from +library2.so named 'bar' that prints two types of objects, 'bar1' and +'bar2'. + + (gdb) info pretty-printer + library1.so: + foo + library2.so: + bar + bar1 + bar2 + (gdb) info pretty-printer library2 + library2.so: + bar + bar1 + bar2 + (gdb) disable pretty-printer library1 + 1 printer disabled + 2 of 3 printers enabled + (gdb) info pretty-printer + library1.so: + foo [disabled] + library2.so: + bar + bar1 + bar2 + (gdb) disable pretty-printer library2 bar:bar1 + 1 printer disabled + 1 of 3 printers enabled + (gdb) info pretty-printer library2 + library1.so: + foo [disabled] + library2.so: + bar + bar1 [disabled] + bar2 + (gdb) disable pretty-printer library2 bar + 1 printer disabled + 0 of 3 printers enabled + (gdb) info pretty-printer library2 + library1.so: + foo [disabled] + library2.so: + bar [disabled] + bar1 [disabled] + bar2 + + Note that for 'bar' the entire printer can be disabled, as can each +individual subprinter. + + +File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Pretty Printing, Up: Data + +10.10 Value History +=================== + +Values printed by the 'print' command are saved in the GDB "value +history". This allows you to refer to them in other expressions. +Values are kept until the symbol table is re-read or discarded (for +example with the 'file' or 'symbol-file' commands). When the symbol +table changes, the value history is discarded, since the values may +contain pointers back to the types defined in the symbol table. + + The values printed are given "history numbers" by which you can refer +to them. These are successive integers starting with one. 'print' +shows you the history number assigned to a value by printing '$NUM = ' +before the value; here NUM is the history number. + + To refer to any previous value, use '$' followed by the value's +history number. The way 'print' labels its output is designed to remind +you of this. Just '$' refers to the most recent value in the history, +and '$$' refers to the value before that. '$$N' refers to the Nth value +from the end; '$$2' is the value just prior to '$$', '$$1' is equivalent +to '$$', and '$$0' is equivalent to '$'. + + For example, suppose you have just printed a pointer to a structure +and want to see the contents of the structure. It suffices to type + + p *$ + + If you have a chain of structures where the component 'next' points +to the next one, you can print the contents of the next one with this: + + p *$.next + +You can print successive links in the chain by repeating this +command--which you can do by just typing . + + Note that the history records values, not expressions. If the value +of 'x' is 4 and you type these commands: + + print x + set x=5 + +then the value recorded in the value history by the 'print' command +remains 4 even though the value of 'x' has changed. + +'show values' + Print the last ten values in the value history, with their item + numbers. This is like 'p $$9' repeated ten times, except that + 'show values' does not change the history. + +'show values N' + Print ten history values centered on history item number N. + +'show values +' + Print ten history values just after the values last printed. If no + more values are available, 'show values +' produces no display. + + Pressing to repeat 'show values N' has exactly the same effect +as 'show values +'. + + +File: gdb.info, Node: Convenience Vars, Next: Convenience Funs, Prev: Value History, Up: Data + +10.11 Convenience Variables +=========================== + +GDB provides "convenience variables" that you can use within GDB to hold +on to a value and refer to it later. These variables exist entirely +within GDB; they are not part of your program, and setting a convenience +variable has no direct effect on further execution of your program. +That is why you can use them freely. + + Convenience variables are prefixed with '$'. Any name preceded by +'$' can be used for a convenience variable, unless it is one of the +predefined machine-specific register names (*note Registers: +Registers.). (Value history references, in contrast, are _numbers_ +preceded by '$'. *Note Value History: Value History.) + + You can save a value in a convenience variable with an assignment +expression, just as you would set a variable in your program. For +example: + + set $foo = *object_ptr + +would save in '$foo' the value contained in the object pointed to by +'object_ptr'. + + Using a convenience variable for the first time creates it, but its +value is 'void' until you assign a new value. You can alter the value +with another assignment at any time. + + Convenience variables have no fixed types. You can assign a +convenience variable any type of value, including structures and arrays, +even if that variable already has a value of a different type. The +convenience variable, when used as an expression, has the type of its +current value. + +'show convenience' + Print a list of convenience variables used so far, and their + values, as well as a list of the convenience functions. + Abbreviated 'show conv'. + +'init-if-undefined $VARIABLE = EXPRESSION' + Set a convenience variable if it has not already been set. This is + useful for user-defined commands that keep some state. It is + similar, in concept, to using local static variables with + initializers in C (except that convenience variables are global). + It can also be used to allow users to override default values used + in a command script. + + If the variable is already defined then the expression is not + evaluated so any side-effects do not occur. + + One of the ways to use a convenience variable is as a counter to be +incremented or a pointer to be advanced. For example, to print a field +from successive elements of an array of structures: + + set $i = 0 + print bar[$i++]->contents + +Repeat that command by typing . + + Some convenience variables are created automatically by GDB and given +values likely to be useful. + +'$_' + The variable '$_' is automatically set by the 'x' command to the + last address examined (*note Examining Memory: Memory.). Other + commands which provide a default address for 'x' to examine also + set '$_' to that address; these commands include 'info line' and + 'info breakpoint'. The type of '$_' is 'void *' except when set by + the 'x' command, in which case it is a pointer to the type of + '$__'. + +'$__' + The variable '$__' is automatically set by the 'x' command to the + value found in the last address examined. Its type is chosen to + match the format in which the data was printed. + +'$_exitcode' + When the program being debugged terminates normally, GDB + automatically sets this variable to the exit code of the program, + and resets '$_exitsignal' to 'void'. + +'$_exitsignal' + When the program being debugged dies due to an uncaught signal, GDB + automatically sets this variable to that signal's number, and + resets '$_exitcode' to 'void'. + + To distinguish between whether the program being debugged has + exited (i.e., '$_exitcode' is not 'void') or signalled (i.e., + '$_exitsignal' is not 'void'), the convenience function '$_isvoid' + can be used (*note Convenience Functions: Convenience Funs.). For + example, considering the following source code: + + #include + + int + main (int argc, char *argv[]) + { + raise (SIGALRM); + return 0; + } + + A valid way of telling whether the program being debugged has + exited or signalled would be: + + (gdb) define has_exited_or_signalled + Type commands for definition of ``has_exited_or_signalled''. + End with a line saying just ``end''. + >if $_isvoid ($_exitsignal) + >echo The program has exited\n + >else + >echo The program has signalled\n + >end + >end + (gdb) run + Starting program: + + Program terminated with signal SIGALRM, Alarm clock. + The program no longer exists. + (gdb) has_exited_or_signalled + The program has signalled + + As can be seen, GDB correctly informs that the program being + debugged has signalled, since it calls 'raise' and raises a + 'SIGALRM' signal. If the program being debugged had not called + 'raise', then GDB would report a normal exit: + + (gdb) has_exited_or_signalled + The program has exited + +'$_exception' + The variable '$_exception' is set to the exception object being + thrown at an exception-related catchpoint. *Note Set + Catchpoints::. + +'$_probe_argc' +'$_probe_arg0...$_probe_arg11' + Arguments to a static probe. *Note Static Probe Points::. + +'$_sdata' + The variable '$_sdata' contains extra collected static tracepoint + data. *Note Tracepoint Action Lists: Tracepoint Actions. Note + that '$_sdata' could be empty, if not inspecting a trace buffer, or + if extra static tracepoint data has not been collected. + +'$_siginfo' + The variable '$_siginfo' contains extra signal information (*note + extra signal information::). Note that '$_siginfo' could be empty, + if the application has not yet received any signals. For example, + it will be empty before you execute the 'run' command. + +'$_tlb' + The variable '$_tlb' is automatically set when debugging + applications running on MS-Windows in native mode or connected to + gdbserver that supports the 'qGetTIBAddr' request. *Note General + Query Packets::. This variable contains the address of the thread + information block. + + On HP-UX systems, if you refer to a function or variable name that +begins with a dollar sign, GDB searches for a user or system name first, +before it searches for a convenience variable. + + +File: gdb.info, Node: Convenience Funs, Next: Registers, Prev: Convenience Vars, Up: Data + +10.12 Convenience Functions +=========================== + +GDB also supplies some "convenience functions". These have a syntax +similar to convenience variables. A convenience function can be used in +an expression just like an ordinary function; however, a convenience +function is implemented internally to GDB. + + These functions do not require GDB to be configured with 'Python' +support, which means that they are always available. + +'$_isvoid (EXPR)' + Return one if the expression EXPR is 'void'. Otherwise it returns + zero. + + A 'void' expression is an expression where the type of the result + is 'void'. For example, you can examine a convenience variable + (see *note Convenience Variables: Convenience Vars.) to check + whether it is 'void': + + (gdb) print $_exitcode + $1 = void + (gdb) print $_isvoid ($_exitcode) + $2 = 1 + (gdb) run + Starting program: ./a.out + [Inferior 1 (process 29572) exited normally] + (gdb) print $_exitcode + $3 = 0 + (gdb) print $_isvoid ($_exitcode) + $4 = 0 + + In the example above, we used '$_isvoid' to check whether + '$_exitcode' is 'void' before and after the execution of the + program being debugged. Before the execution there is no exit code + to be examined, therefore '$_exitcode' is 'void'. After the + execution the program being debugged returned zero, therefore + '$_exitcode' is zero, which means that it is not 'void' anymore. + + The 'void' expression can also be a call of a function from the + program being debugged. For example, given the following function: + + void + foo (void) + { + } + + The result of calling it inside GDB is 'void': + + (gdb) print foo () + $1 = void + (gdb) print $_isvoid (foo ()) + $2 = 1 + (gdb) set $v = foo () + (gdb) print $v + $3 = void + (gdb) print $_isvoid ($v) + $4 = 1 + + These functions require GDB to be configured with 'Python' support. + +'$_memeq(BUF1, BUF2, LENGTH)' + Returns one if the LENGTH bytes at the addresses given by BUF1 and + BUF2 are equal. Otherwise it returns zero. + +'$_regex(STR, REGEX)' + Returns one if the string STR matches the regular expression REGEX. + Otherwise it returns zero. The syntax of the regular expression is + that specified by 'Python''s regular expression support. + +'$_streq(STR1, STR2)' + Returns one if the strings STR1 and STR2 are equal. Otherwise it + returns zero. + +'$_strlen(STR)' + Returns the length of string STR. + + GDB provides the ability to list and get help on convenience +functions. + +'help function' + Print a list of all convenience functions. + + +File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Funs, Up: Data + +10.13 Registers +=============== + +You can refer to machine register contents, in expressions, as variables +with names starting with '$'. The names of registers are different for +each machine; use 'info registers' to see the names used on your +machine. + +'info registers' + Print the names and values of all registers except floating-point + and vector registers (in the selected stack frame). + +'info all-registers' + Print the names and values of all registers, including + floating-point and vector registers (in the selected stack frame). + +'info registers REGNAME ...' + Print the "relativized" value of each specified register REGNAME. + As discussed in detail below, register values are normally relative + to the selected stack frame. REGNAME may be any register name + valid on the machine you are using, with or without the initial + '$'. + + GDB has four "standard" register names that are available (in +expressions) on most machines--whenever they do not conflict with an +architecture's canonical mnemonics for registers. The register names +'$pc' and '$sp' are used for the program counter register and the stack +pointer. '$fp' is used for a register that contains a pointer to the +current stack frame, and '$ps' is used for a register that contains the +processor status. For example, you could print the program counter in +hex with + + p/x $pc + +or print the instruction to be executed next with + + x/i $pc + +or add four to the stack pointer(1) with + + set $sp += 4 + + Whenever possible, these four standard register names are available +on your machine even though the machine has different canonical +mnemonics, so long as there is no conflict. The 'info registers' +command shows the canonical names. For example, on the SPARC, 'info +registers' displays the processor status register as '$psr' but you can +also refer to it as '$ps'; and on x86-based machines '$ps' is an alias +for the EFLAGS register. + + GDB always considers the contents of an ordinary register as an +integer when the register is examined in this way. Some machines have +special registers which can hold nothing but floating point; these +registers are considered to have floating point values. There is no way +to refer to the contents of an ordinary register as floating point value +(although you can _print_ it as a floating point value with 'print/f +$REGNAME'). + + Some registers have distinct "raw" and "virtual" data formats. This +means that the data format in which the register contents are saved by +the operating system is not the same one that your program normally +sees. For example, the registers of the 68881 floating point +coprocessor are always saved in "extended" (raw) format, but all C +programs expect to work with "double" (virtual) format. In such cases, +GDB normally works with the virtual format only (the format that makes +sense for your program), but the 'info registers' command prints the +data in both formats. + + Some machines have special registers whose contents can be +interpreted in several different ways. For example, modern x86-based +machines have SSE and MMX registers that can hold several values packed +together in several different formats. GDB refers to such registers in +'struct' notation: + + (gdb) print $xmm1 + $1 = { + v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044}, + v2_double = {9.92129282474342e-303, 2.7585945287983262e-313}, + v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", + v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0}, + v4_int32 = {0, 20657912, 11, 13}, + v2_int64 = {88725056443645952, 55834574859}, + uint128 = 0x0000000d0000000b013b36f800000000 + } + +To set values of such registers, you need to tell GDB which view of the +register you wish to change, as if you were assigning value to a +'struct' member: + + (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF + + Normally, register values are relative to the selected stack frame +(*note Selecting a Frame: Selection.). This means that you get the +value that the register would contain if all stack frames farther in +were exited and their saved registers restored. In order to see the +true contents of hardware registers, you must select the innermost frame +(with 'frame 0'). + + Usually ABIs reserve some registers as not needed to be saved by the +callee (a.k.a.: "caller-saved", "call-clobbered" or "volatile" +registers). It may therefore not be possible for GDB to know the value +a register had before the call (in other words, in the outer frame), if +the register value has since been changed by the callee. GDB tries to +deduce where the inner frame saved ("callee-saved") registers, from the +debug info, unwind info, or the machine code generated by your compiler. +If some register is not saved, and GDB knows the register is +"caller-saved" (via its own knowledge of the ABI, or because the +debug/unwind info explicitly says the register's value is undefined), +GDB displays '' as the register's value. With targets that +GDB has no knowledge of the register saving convention, if a register +was not saved by the callee, then its value and location in the outer +frame are assumed to be the same of the inner frame. This is usually +harmless, because if the register is call-clobbered, the caller either +does not care what is in the register after the call, or has code to +restore the value that it does care about. Note, however, that if you +change such a register in the outer frame, you may also be affecting the +inner frame. Also, the more "outer" the frame is you're looking at, the +more likely a call-clobbered register's value is to be wrong, in the +sense that it doesn't actually represent the value the register had just +before the call. + + ---------- Footnotes ---------- + + (1) This is a way of removing one word from the stack, on machines +where stacks grow downward in memory (most machines, nowadays). This +assumes that the innermost stack frame is selected; setting '$sp' is not +allowed when other stack frames are selected. To pop entire frames off +the stack, regardless of machine architecture, use 'return'; see *note +Returning from a Function: Returning. + + +File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data + +10.14 Floating Point Hardware +============================= + +Depending on the configuration, GDB may be able to give you more +information about the status of the floating point hardware. + +'info float' + Display hardware-dependent information about the floating point + unit. The exact contents and layout vary depending on the floating + point chip. Currently, 'info float' is supported on the ARM and + x86 machines. + + +File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data + +10.15 Vector Unit +================= + +Depending on the configuration, GDB may be able to give you more +information about the status of the vector unit. + +'info vector' + Display information about the vector unit. The exact contents and + layout vary depending on the hardware. + + +File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data + +10.16 Operating System Auxiliary Information +============================================ + +GDB provides interfaces to useful OS facilities that can help you debug +your program. + + Some operating systems supply an "auxiliary vector" to programs at +startup. This is akin to the arguments and environment that you specify +for a program, but contains a system-dependent variety of binary values +that tell system libraries important details about the hardware, +operating system, and process. Each value's purpose is identified by an +integer tag; the meanings are well-known but system-specific. Depending +on the configuration and operating system facilities, GDB may be able to +show you this information. For remote targets, this functionality may +further depend on the remote stub's support of the 'qXfer:auxv:read' +packet, see *note qXfer auxiliary vector read::. + +'info auxv' + Display the auxiliary vector of the inferior, which can be either a + live process or a core dump file. GDB prints each tag value + numerically, and also shows names and text descriptions for + recognized tags. Some values in the vector are numbers, some bit + masks, and some pointers to strings or other data. GDB displays + each value in the most appropriate form for a recognized tag, and + in hexadecimal for an unrecognized tag. + + On some targets, GDB can access operating system-specific information +and show it to you. The types of information available will differ +depending on the type of operating system running on the target. The +mechanism used to fetch the data is described in *note Operating System +Information::. For remote targets, this functionality depends on the +remote stub's support of the 'qXfer:osdata:read' packet, see *note qXfer +osdata read::. + +'info os INFOTYPE' + + Display OS information of the requested type. + + On GNU/Linux, the following values of INFOTYPE are valid: + + 'processes' + Display the list of processes on the target. For each + process, GDB prints the process identifier, the name of the + user, the command corresponding to the process, and the list + of processor cores that the process is currently running on. + (To understand what these properties mean, for this and the + following info types, please consult the general GNU/Linux + documentation.) + + 'procgroups' + Display the list of process groups on the target. For each + process, GDB prints the identifier of the process group that + it belongs to, the command corresponding to the process group + leader, the process identifier, and the command line of the + process. The list is sorted first by the process group + identifier, then by the process identifier, so that processes + belonging to the same process group are grouped together and + the process group leader is listed first. + + 'threads' + Display the list of threads running on the target. For each + thread, GDB prints the identifier of the process that the + thread belongs to, the command of the process, the thread + identifier, and the processor core that it is currently + running on. The main thread of a process is not listed. + + 'files' + Display the list of open file descriptors on the target. For + each file descriptor, GDB prints the identifier of the process + owning the descriptor, the command of the owning process, the + value of the descriptor, and the target of the descriptor. + + 'sockets' + Display the list of Internet-domain sockets on the target. + For each socket, GDB prints the address and port of the local + and remote endpoints, the current state of the connection, the + creator of the socket, the IP address family of the socket, + and the type of the connection. + + 'shm' + Display the list of all System V shared-memory regions on the + target. For each shared-memory region, GDB prints the region + key, the shared-memory identifier, the access permissions, the + size of the region, the process that created the region, the + process that last attached to or detached from the region, the + current number of live attaches to the region, and the times + at which the region was last attached to, detach from, and + changed. + + 'semaphores' + Display the list of all System V semaphore sets on the target. + For each semaphore set, GDB prints the semaphore set key, the + semaphore set identifier, the access permissions, the number + of semaphores in the set, the user and group of the owner and + creator of the semaphore set, and the times at which the + semaphore set was operated upon and changed. + + 'msg' + Display the list of all System V message queues on the target. + For each message queue, GDB prints the message queue key, the + message queue identifier, the access permissions, the current + number of bytes on the queue, the current number of messages + on the queue, the processes that last sent and received a + message on the queue, the user and group of the owner and + creator of the message queue, the times at which a message was + last sent and received on the queue, and the time at which the + message queue was last changed. + + 'modules' + Display the list of all loaded kernel modules on the target. + For each module, GDB prints the module name, the size of the + module in bytes, the number of times the module is used, the + dependencies of the module, the status of the module, and the + address of the loaded module in memory. + +'info os' + If INFOTYPE is omitted, then list the possible values for INFOTYPE + and the kind of OS information available for each INFOTYPE. If the + target does not return a list of possible types, this command will + report an error. + + +File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data + +10.17 Memory Region Attributes +============================== + +"Memory region attributes" allow you to describe special handling +required by regions of your target's memory. GDB uses attributes to +determine whether to allow certain types of memory accesses; whether to +use specific width accesses; and whether to cache target memory. By +default the description of memory regions is fetched from the target (if +the current target supports this), but the user can override the fetched +regions. + + Defined memory regions can be individually enabled and disabled. +When a memory region is disabled, GDB uses the default attributes when +accessing memory in that region. Similarly, if no memory regions have +been defined, GDB uses the default attributes when accessing all memory. + + When a memory region is defined, it is given a number to identify it; +to enable, disable, or remove a memory region, you specify that number. + +'mem LOWER UPPER ATTRIBUTES...' + Define a memory region bounded by LOWER and UPPER with attributes + ATTRIBUTES..., and add it to the list of regions monitored by GDB. + Note that UPPER == 0 is a special case: it is treated as the + target's maximum memory address. (0xffff on 16 bit targets, + 0xffffffff on 32 bit targets, etc.) + +'mem auto' + Discard any user changes to the memory regions and use + target-supplied regions, if available, or no regions if the target + does not support. + +'delete mem NUMS...' + Remove memory regions NUMS... from the list of regions monitored by + GDB. + +'disable mem NUMS...' + Disable monitoring of memory regions NUMS.... A disabled memory + region is not forgotten. It may be enabled again later. + +'enable mem NUMS...' + Enable monitoring of memory regions NUMS.... + +'info mem' + Print a table of all defined memory regions, with the following + columns for each region: + + _Memory Region Number_ + _Enabled or Disabled._ + Enabled memory regions are marked with 'y'. Disabled memory + regions are marked with 'n'. + + _Lo Address_ + The address defining the inclusive lower bound of the memory + region. + + _Hi Address_ + The address defining the exclusive upper bound of the memory + region. + + _Attributes_ + The list of attributes set for this memory region. + +10.17.1 Attributes +------------------ + +10.17.1.1 Memory Access Mode +............................ + +The access mode attributes set whether GDB may make read or write +accesses to a memory region. + + While these attributes prevent GDB from performing invalid memory +accesses, they do nothing to prevent the target system, I/O DMA, etc. +from accessing memory. + +'ro' + Memory is read only. +'wo' + Memory is write only. +'rw' + Memory is read/write. This is the default. + +10.17.1.2 Memory Access Size +............................ + +The access size attribute tells GDB to use specific sized accesses in +the memory region. Often memory mapped device registers require +specific sized accesses. If no access size attribute is specified, GDB +may use accesses of any size. + +'8' + Use 8 bit memory accesses. +'16' + Use 16 bit memory accesses. +'32' + Use 32 bit memory accesses. +'64' + Use 64 bit memory accesses. + +10.17.1.3 Data Cache +.................... + +The data cache attributes set whether GDB will cache target memory. +While this generally improves performance by reducing debug protocol +overhead, it can lead to incorrect results because GDB does not know +about volatile variables or memory mapped device registers. + +'cache' + Enable GDB to cache target memory. +'nocache' + Disable GDB from caching target memory. This is the default. + +10.17.2 Memory Access Checking +------------------------------ + +GDB can be instructed to refuse accesses to memory that is not +explicitly described. This can be useful if accessing such regions has +undesired effects for a specific target, or to provide better error +checking. The following commands control this behaviour. + +'set mem inaccessible-by-default [on|off]' + If 'on' is specified, make GDB treat memory not explicitly + described by the memory ranges as non-existent and refuse accesses + to such memory. The checks are only performed if there's at least + one memory range defined. If 'off' is specified, make GDB treat + the memory not explicitly described by the memory ranges as RAM. + The default value is 'on'. +'show mem inaccessible-by-default' + Show the current handling of accesses to unknown memory. + + +File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data + +10.18 Copy Between Memory and a File +==================================== + +You can use the commands 'dump', 'append', and 'restore' to copy data +between target memory and a file. The 'dump' and 'append' commands +write data to a file, and the 'restore' command reads data from a file +back into the inferior's memory. Files may be in binary, Motorola +S-record, Intel hex, or Tektronix Hex format; however, GDB can only +append to binary files. + +'dump [FORMAT] memory FILENAME START_ADDR END_ADDR' +'dump [FORMAT] value FILENAME EXPR' + Dump the contents of memory from START_ADDR to END_ADDR, or the + value of EXPR, to FILENAME in the given format. + + The FORMAT parameter may be any one of: + 'binary' + Raw binary form. + 'ihex' + Intel hex format. + 'srec' + Motorola S-record format. + 'tekhex' + Tektronix Hex format. + + GDB uses the same definitions of these formats as the GNU binary + utilities, like 'objdump' and 'objcopy'. If FORMAT is omitted, GDB + dumps the data in raw binary form. + +'append [binary] memory FILENAME START_ADDR END_ADDR' +'append [binary] value FILENAME EXPR' + Append the contents of memory from START_ADDR to END_ADDR, or the + value of EXPR, to the file FILENAME, in raw binary form. (GDB can + only append data to files in raw binary form.) + +'restore FILENAME [binary] BIAS START END' + Restore the contents of file FILENAME into memory. The 'restore' + command can automatically recognize any known BFD file format, + except for raw binary. To restore a raw binary file you must + specify the optional keyword 'binary' after the filename. + + If BIAS is non-zero, its value will be added to the addresses + contained in the file. Binary files always start at address zero, + so they will be restored at address BIAS. Other bfd files have a + built-in location; they will be restored at offset BIAS from that + location. + + If START and/or END are non-zero, then only data between file + offset START and file offset END will be restored. These offsets + are relative to the addresses in the file, before the BIAS argument + is applied. + + +File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data + +10.19 How to Produce a Core File from Your Program +================================================== + +A "core file" or "core dump" is a file that records the memory image of +a running process and its process status (register values etc.). Its +primary use is post-mortem debugging of a program that crashed while it +ran outside a debugger. A program that crashes automatically produces a +core file, unless this feature is disabled by the user. *Note Files::, +for information on invoking GDB in the post-mortem debugging mode. + + Occasionally, you may wish to produce a core file of the program you +are debugging in order to preserve a snapshot of its state. GDB has a +special command for that. + +'generate-core-file [FILE]' +'gcore [FILE]' + Produce a core dump of the inferior process. The optional argument + FILE specifies the file name where to put the core dump. If not + specified, the file name defaults to 'core.PID', where PID is the + inferior process ID. + + Note that this command is implemented only for some systems (as of + this writing, GNU/Linux, FreeBSD, Solaris, and S390). + + +File: gdb.info, Node: Character Sets, Next: Caching Target Data, Prev: Core File Generation, Up: Data + +10.20 Character Sets +==================== + +If the program you are debugging uses a different character set to +represent characters and strings than the one GDB uses itself, GDB can +automatically translate between the character sets for you. The +character set GDB uses we call the "host character set"; the one the +inferior program uses we call the "target character set". + + For example, if you are running GDB on a GNU/Linux system, which uses +the ISO Latin 1 character set, but you are using GDB's remote protocol +(*note Remote Debugging::) to debug a program running on an IBM +mainframe, which uses the EBCDIC character set, then the host character +set is Latin-1, and the target character set is EBCDIC. If you give GDB +the command 'set target-charset EBCDIC-US', then GDB translates between +EBCDIC and Latin 1 as you print character or string values, or use +character and string literals in expressions. + + GDB has no way to automatically recognize which character set the +inferior program uses; you must tell it, using the 'set target-charset' +command, described below. + + Here are the commands for controlling GDB's character set support: + +'set target-charset CHARSET' + Set the current target character set to CHARSET. To display the + list of supported target character sets, type + 'set target-charset '. + +'set host-charset CHARSET' + Set the current host character set to CHARSET. + + By default, GDB uses a host character set appropriate to the system + it is running on; you can override that default using the 'set + host-charset' command. On some systems, GDB cannot automatically + determine the appropriate host character set. In this case, GDB + uses 'UTF-8'. + + GDB can only use certain character sets as its host character set. + If you type 'set host-charset ', GDB will list the host + character sets it supports. + +'set charset CHARSET' + Set the current host and target character sets to CHARSET. As + above, if you type 'set charset ', GDB will list the + names of the character sets that can be used for both host and + target. + +'show charset' + Show the names of the current host and target character sets. + +'show host-charset' + Show the name of the current host character set. + +'show target-charset' + Show the name of the current target character set. + +'set target-wide-charset CHARSET' + Set the current target's wide character set to CHARSET. This is + the character set used by the target's 'wchar_t' type. To display + the list of supported wide character sets, type + 'set target-wide-charset '. + +'show target-wide-charset' + Show the name of the current target's wide character set. + + Here is an example of GDB's character set support in action. Assume +that the following source code has been placed in the file +'charset-test.c': + + #include + + char ascii_hello[] + = {72, 101, 108, 108, 111, 44, 32, 119, + 111, 114, 108, 100, 33, 10, 0}; + char ibm1047_hello[] + = {200, 133, 147, 147, 150, 107, 64, 166, + 150, 153, 147, 132, 90, 37, 0}; + + main () + { + printf ("Hello, world!\n"); + } + + In this program, 'ascii_hello' and 'ibm1047_hello' are arrays +containing the string 'Hello, world!' followed by a newline, encoded in +the ASCII and IBM1047 character sets. + + We compile the program, and invoke the debugger on it: + + $ gcc -g charset-test.c -o charset-test + $ gdb -nw charset-test + GNU gdb 2001-12-19-cvs + Copyright 2001 Free Software Foundation, Inc. + ... + (gdb) + + We can use the 'show charset' command to see what character sets GDB +is currently using to interpret and display characters and strings: + + (gdb) show charset + The current host and target character set is `ISO-8859-1'. + (gdb) + + For the sake of printing this manual, let's use ASCII as our initial +character set: + (gdb) set charset ASCII + (gdb) show charset + The current host and target character set is `ASCII'. + (gdb) + + Let's assume that ASCII is indeed the correct character set for our +host system -- in other words, let's assume that if GDB prints +characters using the ASCII character set, our terminal will display them +properly. Since our current target character set is also ASCII, the +contents of 'ascii_hello' print legibly: + + (gdb) print ascii_hello + $1 = 0x401698 "Hello, world!\n" + (gdb) print ascii_hello[0] + $2 = 72 'H' + (gdb) + + GDB uses the target character set for character and string literals +you use in expressions: + + (gdb) print '+' + $3 = 43 '+' + (gdb) + + The ASCII character set uses the number 43 to encode the '+' +character. + + GDB relies on the user to tell it which character set the target +program uses. If we print 'ibm1047_hello' while our target character +set is still ASCII, we get jibberish: + + (gdb) print ibm1047_hello + $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%" + (gdb) print ibm1047_hello[0] + $5 = 200 '\310' + (gdb) + + If we invoke the 'set target-charset' followed by , GDB +tells us the character sets it supports: + + (gdb) set target-charset + ASCII EBCDIC-US IBM1047 ISO-8859-1 + (gdb) set target-charset + + We can select IBM1047 as our target character set, and examine the +program's strings again. Now the ASCII string is wrong, but GDB +translates the contents of 'ibm1047_hello' from the target character +set, IBM1047, to the host character set, ASCII, and they display +correctly: + + (gdb) set target-charset IBM1047 + (gdb) show charset + The current host character set is `ASCII'. + The current target character set is `IBM1047'. + (gdb) print ascii_hello + $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" + (gdb) print ascii_hello[0] + $7 = 72 '\110' + (gdb) print ibm1047_hello + $8 = 0x4016a8 "Hello, world!\n" + (gdb) print ibm1047_hello[0] + $9 = 200 'H' + (gdb) + + As above, GDB uses the target character set for character and string +literals you use in expressions: + + (gdb) print '+' + $10 = 78 '+' + (gdb) + + The IBM1047 character set uses the number 78 to encode the '+' +character. + + +File: gdb.info, Node: Caching Target Data, Next: Searching Memory, Prev: Character Sets, Up: Data + +10.21 Caching Data of Targets +============================= + +GDB caches data exchanged between the debugger and a target. Each cache +is associated with the address space of the inferior. *Note Inferiors +and Programs::, about inferior and address space. Such caching +generally improves performance in remote debugging (*note Remote +Debugging::), because it reduces the overhead of the remote protocol by +bundling memory reads and writes into large chunks. Unfortunately, +simply caching everything would lead to incorrect results, since GDB +does not necessarily know anything about volatile values, memory-mapped +I/O addresses, etc. Furthermore, in non-stop mode (*note Non-Stop +Mode::) memory can be changed _while_ a gdb command is executing. +Therefore, by default, GDB only caches data known to be on the stack(1) +or in the code segment. Other regions of memory can be explicitly +marked as cacheable; *note Memory Region Attributes::. + +'set remotecache on' +'set remotecache off' + This option no longer does anything; it exists for compatibility + with old scripts. + +'show remotecache' + Show the current state of the obsolete remotecache flag. + +'set stack-cache on' +'set stack-cache off' + Enable or disable caching of stack accesses. When 'on', use + caching. By default, this option is 'on'. + +'show stack-cache' + Show the current state of data caching for memory accesses. + +'set code-cache on' +'set code-cache off' + Enable or disable caching of code segment accesses. When 'on', use + caching. By default, this option is 'on'. This improves + performance of disassembly in remote debugging. + +'show code-cache' + Show the current state of target memory cache for code segment + accesses. + +'info dcache [line]' + Print the information about the performance of data cache of the + current inferior's address space. The information displayed + includes the dcache width and depth, and for each cache line, its + number, address, and how many times it was referenced. This + command is useful for debugging the data cache operation. + + If a line number is specified, the contents of that line will be + printed in hex. + +'set dcache size SIZE' + Set maximum number of entries in dcache (dcache depth above). + +'set dcache line-size LINE-SIZE' + Set number of bytes each dcache entry caches (dcache width above). + Must be a power of 2. + +'show dcache size' + Show maximum number of dcache entries. *Note info dcache: Caching + Target Data. + +'show dcache line-size' + Show default size of dcache lines. + + ---------- Footnotes ---------- + + (1) In non-stop mode, it is moderately rare for a running thread to +modify the stack of a stopped thread in a way that would interfere with +a backtrace, and caching of stack reads provides a significant speed up +of remote backtraces. + + +File: gdb.info, Node: Searching Memory, Prev: Caching Target Data, Up: Data + +10.22 Search Memory +=================== + +Memory can be searched for a particular sequence of bytes with the +'find' command. + +'find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]' +'find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]' + Search memory for the sequence of bytes specified by VAL1, VAL2, + etc. The search begins at address START_ADDR and continues for + either LEN bytes or through to END_ADDR inclusive. + + S and N are optional parameters. They may be specified in either +order, apart or together. + +S, search query size + The size of each search query value. + + 'b' + bytes + 'h' + halfwords (two bytes) + 'w' + words (four bytes) + 'g' + giant words (eight bytes) + + All values are interpreted in the current language. This means, + for example, that if the current source language is C/C++ then + searching for the string "hello" includes the trailing '\0'. + + If the value size is not specified, it is taken from the value's + type in the current language. This is useful when one wants to + specify the search pattern as a mixture of types. Note that this + means, for example, that in the case of C-like languages a search + for an untyped 0x42 will search for '(int) 0x42' which is typically + four bytes. + +N, maximum number of finds + The maximum number of matches to print. The default is to print + all finds. + + You can use strings as search values. Quote them with double-quotes +('"'). The string value is copied into the search pattern byte by byte, +regardless of the endianness of the target and the size specification. + + The address of each match found is printed as well as a count of the +number of matches found. + + The address of the last value found is stored in convenience variable +'$_'. A count of the number of matches is stored in '$numfound'. + + For example, if stopped at the 'printf' in this function: + + void + hello () + { + static char hello[] = "hello-hello"; + static struct { char c; short s; int i; } + __attribute__ ((packed)) mixed + = { 'c', 0x1234, 0x87654321 }; + printf ("%s\n", hello); + } + +you get during debugging: + + (gdb) find &hello[0], +sizeof(hello), "hello" + 0x804956d + 1 pattern found + (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' + 0x8049567 + 0x804956d + 2 patterns found + (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' + 0x8049567 + 1 pattern found + (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 + 0x8049560 + 1 pattern found + (gdb) print $numfound + $1 = 1 + (gdb) print $_ + $2 = (void *) 0x8049560 + + +File: gdb.info, Node: Optimized Code, Next: Macros, Prev: Data, Up: Top + +11 Debugging Optimized Code +*************************** + +Almost all compilers support optimization. With optimization disabled, +the compiler generates assembly code that corresponds directly to your +source code, in a simplistic way. As the compiler applies more powerful +optimizations, the generated assembly code diverges from your original +source code. With help from debugging information generated by the +compiler, GDB can map from the running program back to constructs from +your original source. + + GDB is more accurate with optimization disabled. If you can +recompile without optimization, it is easier to follow the progress of +your program during debugging. But, there are many cases where you may +need to debug an optimized version. + + When you debug a program compiled with '-g -O', remember that the +optimizer has rearranged your code; the debugger shows you what is +really there. Do not be too surprised when the execution path does not +exactly match your source file! An extreme example: if you define a +variable, but never use it, GDB never sees that variable--because the +compiler optimizes it out of existence. + + Some things do not work as well with '-g -O' as with just '-g', +particularly on machines with instruction scheduling. If in doubt, +recompile with '-g' alone, and if this fixes the problem, please report +it to us as a bug (including a test case!). *Note Variables::, for more +information about debugging optimized code. + +* Menu: + +* Inline Functions:: How GDB presents inlining +* Tail Call Frames:: GDB analysis of jumps to functions + + +File: gdb.info, Node: Inline Functions, Next: Tail Call Frames, Up: Optimized Code + +11.1 Inline Functions +===================== + +"Inlining" is an optimization that inserts a copy of the function body +directly at each call site, instead of jumping to a shared routine. GDB +displays inlined functions just like non-inlined functions. They appear +in backtraces. You can view their arguments and local variables, step +into them with 'step', skip them with 'next', and escape from them with +'finish'. You can check whether a function was inlined by using the +'info frame' command. + + For GDB to support inlined functions, the compiler must record +information about inlining in the debug information -- GCC using the +DWARF 2 format does this, and several other compilers do also. GDB only +supports inlined functions when using DWARF 2. Versions of GCC before +4.1 do not emit two required attributes ('DW_AT_call_file' and +'DW_AT_call_line'); GDB does not display inlined function calls with +earlier versions of GCC. It instead displays the arguments and local +variables of inlined functions as local variables in the caller. + + The body of an inlined function is directly included at its call +site; unlike a non-inlined function, there are no instructions devoted +to the call. GDB still pretends that the call site and the start of the +inlined function are different instructions. Stepping to the call site +shows the call site, and then stepping again shows the first line of the +inlined function, even though no additional instructions are executed. + + This makes source-level debugging much clearer; you can see both the +context of the call and then the effect of the call. Only stepping by a +single instruction using 'stepi' or 'nexti' does not do this; single +instruction steps always show the inlined body. + + There are some ways that GDB does not pretend that inlined function +calls are the same as normal calls: + + * Setting breakpoints at the call site of an inlined function may not + work, because the call site does not contain any code. GDB may + incorrectly move the breakpoint to the next line of the enclosing + function, after the call. This limitation will be removed in a + future version of GDB; until then, set a breakpoint on an earlier + line or inside the inlined function instead. + + * GDB cannot locate the return value of inlined calls after using the + 'finish' command. This is a limitation of compiler-generated + debugging information; after 'finish', you can step to the next + line and print a variable where your program stored the return + value. + + +File: gdb.info, Node: Tail Call Frames, Prev: Inline Functions, Up: Optimized Code + +11.2 Tail Call Frames +===================== + +Function 'B' can call function 'C' in its very last statement. In +unoptimized compilation the call of 'C' is immediately followed by +return instruction at the end of 'B' code. Optimizing compiler may +replace the call and return in function 'B' into one jump to function +'C' instead. Such use of a jump instruction is called "tail call". + + During execution of function 'C', there will be no indication in the +function call stack frames that it was tail-called from 'B'. If +function 'A' regularly calls function 'B' which tail-calls function 'C', +then GDB will see 'A' as the caller of 'C'. However, in some cases GDB +can determine that 'C' was tail-called from 'B', and it will then create +fictitious call frame for that, with the return address set up as if 'B' +called 'C' normally. + + This functionality is currently supported only by DWARF 2 debugging +format and the compiler has to produce 'DW_TAG_GNU_call_site' tags. +With GCC, you need to specify '-O -g' during compilation, to get this +information. + + 'info frame' command (*note Frame Info::) will indicate the tail call +frame kind by text 'tail call frame' such as in this sample GDB output: + + (gdb) x/i $pc - 2 + 0x40066b : jmp 0x400640 + (gdb) info frame + Stack level 1, frame at 0x7fffffffda30: + rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 + tail call frame, caller of frame at 0x7fffffffda30 + source language c++. + Arglist at unknown address. + Locals at unknown address, Previous frame's sp is 0x7fffffffda30 + + The detection of all the possible code path executions can find them +ambiguous. There is no execution history stored (possible *note Reverse +Execution:: is never used for this purpose) and the last known caller +could have reached the known callee by multiple different jump +sequences. In such case GDB still tries to show at least all the +unambiguous top tail callers and all the unambiguous bottom tail calees, +if any. + +'set debug entry-values' + When set to on, enables printing of analysis messages for both + frame argument values at function entry and tail calls. It will + show all the possible valid tail calls code paths it has + considered. It will also print the intersection of them with the + final unambiguous (possibly partial or even empty) code path + result. + +'show debug entry-values' + Show the current state of analysis messages printing for both frame + argument values at function entry and tail calls. + + The analysis messages for tail calls can for example show why the +virtual tail call frame for function 'c' has not been recognized (due to +the indirect reference by variable 'x'): + + static void __attribute__((noinline, noclone)) c (void); + void (*x) (void) = c; + static void __attribute__((noinline, noclone)) a (void) { x++; } + static void __attribute__((noinline, noclone)) c (void) { a (); } + int main (void) { x (); return 0; } + + Breakpoint 1, DW_OP_GNU_entry_value resolving cannot find + DW_TAG_GNU_call_site 0x40039a in main + a () at t.c:3 + 3 static void __attribute__((noinline, noclone)) a (void) { x++; } + (gdb) bt + #0 a () at t.c:3 + #1 0x000000000040039a in main () at t.c:5 + + Another possibility is an ambiguous virtual tail call frames +resolution: + + int i; + static void __attribute__((noinline, noclone)) f (void) { i++; } + static void __attribute__((noinline, noclone)) e (void) { f (); } + static void __attribute__((noinline, noclone)) d (void) { f (); } + static void __attribute__((noinline, noclone)) c (void) { d (); } + static void __attribute__((noinline, noclone)) b (void) + { if (i) c (); else e (); } + static void __attribute__((noinline, noclone)) a (void) { b (); } + int main (void) { a (); return 0; } + + tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d) + tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e) + tailcall: reduced: 0x4004d2(a) | + (gdb) bt + #0 f () at t.c:2 + #1 0x00000000004004d2 in a () at t.c:8 + #2 0x0000000000400395 in main () at t.c:9 + + Frames #0 and #2 are real, #1 is a virtual tail call frame. The code +can have possible execution paths 'main->a->b->c->d->f' or +'main->a->b->e->f', GDB cannot find which one from the inferior state. + + 'initial:' state shows some random possible calling sequence GDB has +found. It then finds another possible calling sequcen - that one is +prefixed by 'compare:'. The non-ambiguous intersection of these two is +printed as the 'reduced:' calling sequence. That one could have many +futher 'compare:' and 'reduced:' statements as long as there remain any +non-ambiguous sequence entries. + + For the frame of function 'b' in both cases there are different +possible '$pc' values ('0x4004cc' or '0x4004ce'), therefore this frame +is also ambigous. The only non-ambiguous frame is the one for function +'a', therefore this one is displayed to the user while the ambiguous +frames are omitted. + + There can be also reasons why printing of frame argument values at +function entry may fail: + + int v; + static void __attribute__((noinline, noclone)) c (int i) { v++; } + static void __attribute__((noinline, noclone)) a (int i); + static void __attribute__((noinline, noclone)) b (int i) { a (i); } + static void __attribute__((noinline, noclone)) a (int i) + { if (i) b (i - 1); else c (0); } + int main (void) { a (5); return 0; } + + (gdb) bt + #0 c (i=i@entry=0) at t.c:2 + #1 0x0000000000400428 in a (DW_OP_GNU_entry_value resolving has found + function "a" at 0x400420 can call itself via tail calls + i=) at t.c:6 + #2 0x000000000040036e in main () at t.c:7 + + GDB cannot find out from the inferior state if and how many times did +function 'a' call itself (via function 'b') as these calls would be tail +calls. Such tail calls would modify thue 'i' variable, therefore GDB +cannot be sure the value it knows would be right - GDB prints +'' instead. + + +File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Optimized Code, Up: Top + +12 C Preprocessor Macros +************************ + +Some languages, such as C and C++, provide a way to define and invoke +"preprocessor macros" which expand into strings of tokens. GDB can +evaluate expressions containing macro invocations, show the result of +macro expansion, and show a macro's definition, including where it was +defined. + + You may need to compile your program specially to provide GDB with +information about preprocessor macros. Most compilers do not include +macros in their debugging information, even when you compile with the +'-g' flag. *Note Compilation::. + + A program may define a macro at one point, remove that definition +later, and then provide a different definition after that. Thus, at +different points in the program, a macro may have different definitions, +or have no definition at all. If there is a current stack frame, GDB +uses the macros in scope at that frame's source code line. Otherwise, +GDB uses the macros in scope at the current listing location; see *note +List::. + + Whenever GDB evaluates an expression, it always expands any macro +invocations present in the expression. GDB also provides the following +commands for working with macros explicitly. + +'macro expand EXPRESSION' +'macro exp EXPRESSION' + Show the results of expanding all preprocessor macro invocations in + EXPRESSION. Since GDB simply expands macros, but does not parse + the result, EXPRESSION need not be a valid expression; it can be + any string of tokens. + +'macro expand-once EXPRESSION' +'macro exp1 EXPRESSION' + (This command is not yet implemented.) Show the results of + expanding those preprocessor macro invocations that appear + explicitly in EXPRESSION. Macro invocations appearing in that + expansion are left unchanged. This command allows you to see the + effect of a particular macro more clearly, without being confused + by further expansions. Since GDB simply expands macros, but does + not parse the result, EXPRESSION need not be a valid expression; it + can be any string of tokens. + +'info macro [-a|-all] [--] MACRO' + Show the current definition or all definitions of the named MACRO, + and describe the source location or compiler command-line where + that definition was established. The optional double dash is to + signify the end of argument processing and the beginning of MACRO + for non C-like macros where the macro may begin with a hyphen. + +'info macros LINESPEC' + Show all macro definitions that are in effect at the location + specified by LINESPEC, and describe the source location or compiler + command-line where those definitions were established. + +'macro define MACRO REPLACEMENT-LIST' +'macro define MACRO(ARGLIST) REPLACEMENT-LIST' + Introduce a definition for a preprocessor macro named MACRO, + invocations of which are replaced by the tokens given in + REPLACEMENT-LIST. The first form of this command defines an + "object-like" macro, which takes no arguments; the second form + defines a "function-like" macro, which takes the arguments given in + ARGLIST. + + A definition introduced by this command is in scope in every + expression evaluated in GDB, until it is removed with the 'macro + undef' command, described below. The definition overrides all + definitions for MACRO present in the program being debugged, as + well as any previous user-supplied definition. + +'macro undef MACRO' + Remove any user-supplied definition for the macro named MACRO. + This command only affects definitions provided with the 'macro + define' command, described above; it cannot remove definitions + present in the program being debugged. + +'macro list' + List all the macros defined using the 'macro define' command. + + Here is a transcript showing the above commands in action. First, we +show our source files: + + $ cat sample.c + #include + #include "sample.h" + + #define M 42 + #define ADD(x) (M + x) + + main () + { + #define N 28 + printf ("Hello, world!\n"); + #undef N + printf ("We're so creative.\n"); + #define N 1729 + printf ("Goodbye, world!\n"); + } + $ cat sample.h + #define Q < + $ + + Now, we compile the program using the GNU C compiler, GCC. We pass +the '-gdwarf-2'(1) _and_ '-g3' flags to ensure the compiler includes +information about preprocessor macros in the debugging information. + + $ gcc -gdwarf-2 -g3 sample.c -o sample + $ + + Now, we start GDB on our sample program: + + $ gdb -nw sample + GNU gdb 2002-05-06-cvs + Copyright 2002 Free Software Foundation, Inc. + GDB is free software, ... + (gdb) + + We can expand macros and examine their definitions, even when the +program is not running. GDB uses the current listing position to decide +which macro definitions are in scope: + + (gdb) list main + 3 + 4 #define M 42 + 5 #define ADD(x) (M + x) + 6 + 7 main () + 8 { + 9 #define N 28 + 10 printf ("Hello, world!\n"); + 11 #undef N + 12 printf ("We're so creative.\n"); + (gdb) info macro ADD + Defined at /home/jimb/gdb/macros/play/sample.c:5 + #define ADD(x) (M + x) + (gdb) info macro Q + Defined at /home/jimb/gdb/macros/play/sample.h:1 + included at /home/jimb/gdb/macros/play/sample.c:2 + #define Q < + (gdb) macro expand ADD(1) + expands to: (42 + 1) + (gdb) macro expand-once ADD(1) + expands to: once (M + 1) + (gdb) + + In the example above, note that 'macro expand-once' expands only the +macro invocation explicit in the original text -- the invocation of +'ADD' -- but does not expand the invocation of the macro 'M', which was +introduced by 'ADD'. + + Once the program is running, GDB uses the macro definitions in force +at the source line of the current stack frame: + + (gdb) break main + Breakpoint 1 at 0x8048370: file sample.c, line 10. + (gdb) run + Starting program: /home/jimb/gdb/macros/play/sample + + Breakpoint 1, main () at sample.c:10 + 10 printf ("Hello, world!\n"); + (gdb) + + At line 10, the definition of the macro 'N' at line 9 is in force: + + (gdb) info macro N + Defined at /home/jimb/gdb/macros/play/sample.c:9 + #define N 28 + (gdb) macro expand N Q M + expands to: 28 < 42 + (gdb) print N Q M + $1 = 1 + (gdb) + + As we step over directives that remove 'N''s definition, and then +give it a new definition, GDB finds the definition (or lack thereof) in +force at each point: + + (gdb) next + Hello, world! + 12 printf ("We're so creative.\n"); + (gdb) info macro N + The symbol `N' has no definition as a C/C++ preprocessor macro + at /home/jimb/gdb/macros/play/sample.c:12 + (gdb) next + We're so creative. + 14 printf ("Goodbye, world!\n"); + (gdb) info macro N + Defined at /home/jimb/gdb/macros/play/sample.c:13 + #define N 1729 + (gdb) macro expand N Q M + expands to: 1729 < 42 + (gdb) print N Q M + $2 = 0 + (gdb) + + In addition to source files, macros can be defined on the compilation +command line using the '-DNAME=VALUE' syntax. For macros defined in +such a way, GDB displays the location of their definition as line zero +of the source file submitted to the compiler. + + (gdb) info macro __STDC__ + Defined at /home/jimb/gdb/macros/play/sample.c:0 + -D__STDC__=1 + (gdb) + + ---------- Footnotes ---------- + + (1) This is the minimum. Recent versions of GCC support '-gdwarf-3' +and '-gdwarf-4'; we recommend always choosing the most recent version of +DWARF. + + +File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top + +13 Tracepoints +************** + +In some applications, it is not feasible for the debugger to interrupt +the program's execution long enough for the developer to learn anything +helpful about its behavior. If the program's correctness depends on its +real-time behavior, delays introduced by a debugger might cause the +program to change its behavior drastically, or perhaps fail, even when +the code itself is correct. It is useful to be able to observe the +program's behavior without interrupting it. + + Using GDB's 'trace' and 'collect' commands, you can specify locations +in the program, called "tracepoints", and arbitrary expressions to +evaluate when those tracepoints are reached. Later, using the 'tfind' +command, you can examine the values those expressions had when the +program hit the tracepoints. The expressions may also denote objects in +memory--structures or arrays, for example--whose values GDB should +record; while visiting a particular tracepoint, you may inspect those +objects as if they were in memory at that moment. However, because GDB +records these values without interacting with you, it can do so quickly +and unobtrusively, hopefully not disturbing the program's behavior. + + The tracepoint facility is currently available only for remote +targets. *Note Targets::. In addition, your remote target must know +how to collect trace data. This functionality is implemented in the +remote stub; however, none of the stubs distributed with GDB support +tracepoints as of this writing. The format of the remote packets used +to implement tracepoints are described in *note Tracepoint Packets::. + + It is also possible to get trace data from a file, in a manner +reminiscent of corefiles; you specify the filename, and use 'tfind' to +search through the file. *Note Trace Files::, for more details. + + This chapter describes the tracepoint commands and features. + +* Menu: + +* Set Tracepoints:: +* Analyze Collected Data:: +* Tracepoint Variables:: +* Trace Files:: + + +File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints + +13.1 Commands to Set Tracepoints +================================ + +Before running such a "trace experiment", an arbitrary number of +tracepoints can be set. A tracepoint is actually a special type of +breakpoint (*note Set Breaks::), so you can manipulate it using standard +breakpoint commands. For instance, as with breakpoints, tracepoint +numbers are successive integers starting from one, and many of the +commands associated with tracepoints take the tracepoint number as their +argument, to identify which tracepoint to work on. + + For each tracepoint, you can specify, in advance, some arbitrary set +of data that you want the target to collect in the trace buffer when it +hits that tracepoint. The collected data can include registers, local +variables, or global data. Later, you can use GDB commands to examine +the values these data had at the time the tracepoint was hit. + + Tracepoints do not support every breakpoint feature. Ignore counts +on tracepoints have no effect, and tracepoints cannot run GDB commands +when they are hit. Tracepoints may not be thread-specific either. + + Some targets may support "fast tracepoints", which are inserted in a +different way (such as with a jump instead of a trap), that is faster +but possibly restricted in where they may be installed. + + Regular and fast tracepoints are dynamic tracing facilities, meaning +that they can be used to insert tracepoints at (almost) any location in +the target. Some targets may also support controlling "static +tracepoints" from GDB. With static tracing, a set of instrumentation +points, also known as "markers", are embedded in the target program, and +can be activated or deactivated by name or address. These are usually +placed at locations which facilitate investigating what the target is +actually doing. GDB's support for static tracing includes being able to +list instrumentation points, and attach them with GDB defined high level +tracepoints that expose the whole range of convenience of GDB's +tracepoints support. Namely, support for collecting registers values +and values of global or local (to the instrumentation point) variables; +tracepoint conditions and trace state variables. The act of installing +a GDB static tracepoint on an instrumentation point, or marker, is +referred to as "probing" a static tracepoint marker. + + 'gdbserver' supports tracepoints on some target systems. *Note +Tracepoints support in 'gdbserver': Server. + + This section describes commands to set tracepoints and associated +conditions and actions. + +* Menu: + +* Create and Delete Tracepoints:: +* Enable and Disable Tracepoints:: +* Tracepoint Passcounts:: +* Tracepoint Conditions:: +* Trace State Variables:: +* Tracepoint Actions:: +* Listing Tracepoints:: +* Listing Static Tracepoint Markers:: +* Starting and Stopping Trace Experiments:: +* Tracepoint Restrictions:: + + +File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints + +13.1.1 Create and Delete Tracepoints +------------------------------------ + +'trace LOCATION' + The 'trace' command is very similar to the 'break' command. Its + argument LOCATION can be a source line, a function name, or an + address in the target program. *Note Specify Location::. The + 'trace' command defines a tracepoint, which is a point in the + target program where the debugger will briefly stop, collect some + data, and then allow the program to continue. Setting a tracepoint + or changing its actions takes effect immediately if the remote stub + supports the 'InstallInTrace' feature (*note install tracepoint in + tracing::). If remote stub doesn't support the 'InstallInTrace' + feature, all these changes don't take effect until the next + 'tstart' command, and once a trace experiment is running, further + changes will not have any effect until the next trace experiment + starts. In addition, GDB supports "pending + tracepoints"--tracepoints whose address is not yet resolved. (This + is similar to pending breakpoints.) Pending tracepoints are not + downloaded to the target and not installed until they are resolved. + The resolution of pending tracepoints requires GDB support--when + debugging with the remote target, and GDB disconnects from the + remote stub (*note disconnected tracing::), pending tracepoints can + not be resolved (and downloaded to the remote stub) while GDB is + disconnected. + + Here are some examples of using the 'trace' command: + + (gdb) trace foo.c:121 // a source file and line number + + (gdb) trace +2 // 2 lines forward + + (gdb) trace my_function // first source line of function + + (gdb) trace *my_function // EXACT start address of function + + (gdb) trace *0x2117c4 // an address + + You can abbreviate 'trace' as 'tr'. + +'trace LOCATION if COND' + Set a tracepoint with condition COND; evaluate the expression COND + each time the tracepoint is reached, and collect data only if the + value is nonzero--that is, if COND evaluates as true. *Note + Tracepoint Conditions: Tracepoint Conditions, for more information + on tracepoint conditions. + +'ftrace LOCATION [ if COND ]' + The 'ftrace' command sets a fast tracepoint. For targets that + support them, fast tracepoints will use a more efficient but + possibly less general technique to trigger data collection, such as + a jump instruction instead of a trap, or some sort of hardware + support. It may not be possible to create a fast tracepoint at the + desired location, in which case the command will exit with an + explanatory message. + + GDB handles arguments to 'ftrace' exactly as for 'trace'. + + On 32-bit x86-architecture systems, fast tracepoints normally need + to be placed at an instruction that is 5 bytes or longer, but can + be placed at 4-byte instructions if the low 64K of memory of the + target program is available to install trampolines. Some Unix-type + systems, such as GNU/Linux, exclude low addresses from the + program's address space; but for instance with the Linux kernel it + is possible to let GDB use this area by doing a 'sysctl' command to + set the 'mmap_min_addr' kernel parameter, as in + + sudo sysctl -w vm.mmap_min_addr=32768 + + which sets the low address to 32K, which leaves plenty of room for + trampolines. The minimum address should be set to a page boundary. + +'strace LOCATION [ if COND ]' + The 'strace' command sets a static tracepoint. For targets that + support it, setting a static tracepoint probes a static + instrumentation point, or marker, found at LOCATION. It may not be + possible to set a static tracepoint at the desired location, in + which case the command will exit with an explanatory message. + + GDB handles arguments to 'strace' exactly as for 'trace', with the + addition that the user can also specify '-m MARKER' as LOCATION. + This probes the marker identified by the MARKER string identifier. + This identifier depends on the static tracepoint backend library + your program is using. You can find all the marker identifiers in + the 'ID' field of the 'info static-tracepoint-markers' command + output. *Note Listing Static Tracepoint Markers: Listing Static + Tracepoint Markers. For example, in the following small program + using the UST tracing engine: + + main () + { + trace_mark(ust, bar33, "str %s", "FOOBAZ"); + } + + the marker id is composed of joining the first two arguments to the + 'trace_mark' call with a slash, which translates to: + + (gdb) info static-tracepoint-markers + Cnt Enb ID Address What + 1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 + Data: "str %s" + [etc...] + + so you may probe the marker above with: + + (gdb) strace -m ust/bar33 + + Static tracepoints accept an extra collect action -- 'collect + $_sdata'. This collects arbitrary user data passed in the probe + point call to the tracing library. In the UST example above, + you'll see that the third argument to 'trace_mark' is a printf-like + format string. The user data is then the result of running that + formating string against the following arguments. Note that 'info + static-tracepoint-markers' command output lists that format string + in the 'Data:' field. + + You can inspect this data when analyzing the trace buffer, by + printing the $_sdata variable like any other variable available to + GDB. *Note Tracepoint Action Lists: Tracepoint Actions. + + The convenience variable '$tpnum' records the tracepoint number of + the most recently set tracepoint. + +'delete tracepoint [NUM]' + Permanently delete one or more tracepoints. With no argument, the + default is to delete all tracepoints. Note that the regular + 'delete' command can remove tracepoints also. + + Examples: + + (gdb) delete trace 1 2 3 // remove three tracepoints + + (gdb) delete trace // remove all tracepoints + + You can abbreviate this command as 'del tr'. + + +File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints + +13.1.2 Enable and Disable Tracepoints +------------------------------------- + +These commands are deprecated; they are equivalent to plain 'disable' +and 'enable'. + +'disable tracepoint [NUM]' + Disable tracepoint NUM, or all tracepoints if no argument NUM is + given. A disabled tracepoint will have no effect during a trace + experiment, but it is not forgotten. You can re-enable a disabled + tracepoint using the 'enable tracepoint' command. If the command + is issued during a trace experiment and the debug target has + support for disabling tracepoints during a trace experiment, then + the change will be effective immediately. Otherwise, it will be + applied to the next trace experiment. + +'enable tracepoint [NUM]' + Enable tracepoint NUM, or all tracepoints. If this command is + issued during a trace experiment and the debug target supports + enabling tracepoints during a trace experiment, then the enabled + tracepoints will become effective immediately. Otherwise, they + will become effective the next time a trace experiment is run. + + +File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Conditions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints + +13.1.3 Tracepoint Passcounts +---------------------------- + +'passcount [N [NUM]]' + Set the "passcount" of a tracepoint. The passcount is a way to + automatically stop a trace experiment. If a tracepoint's passcount + is N, then the trace experiment will be automatically stopped on + the N'th time that tracepoint is hit. If the tracepoint number NUM + is not specified, the 'passcount' command sets the passcount of the + most recently defined tracepoint. If no passcount is given, the + trace experiment will run until stopped explicitly by the user. + + Examples: + + (gdb) passcount 5 2 // Stop on the 5th execution of + // tracepoint 2 + + (gdb) passcount 12 // Stop on the 12th execution of the + // most recently defined tracepoint. + (gdb) trace foo + (gdb) pass 3 + (gdb) trace bar + (gdb) pass 2 + (gdb) trace baz + (gdb) pass 1 // Stop tracing when foo has been + // executed 3 times OR when bar has + // been executed 2 times + // OR when baz has been executed 1 time. + + +File: gdb.info, Node: Tracepoint Conditions, Next: Trace State Variables, Prev: Tracepoint Passcounts, Up: Set Tracepoints + +13.1.4 Tracepoint Conditions +---------------------------- + +The simplest sort of tracepoint collects data every time your program +reaches a specified place. You can also specify a "condition" for a +tracepoint. A condition is just a Boolean expression in your +programming language (*note Expressions: Expressions.). A tracepoint +with a condition evaluates the expression each time your program reaches +it, and data collection happens only if the condition is true. + + Tracepoint conditions can be specified when a tracepoint is set, by +using 'if' in the arguments to the 'trace' command. *Note Setting +Tracepoints: Create and Delete Tracepoints. They can also be set or +changed at any time with the 'condition' command, just as with +breakpoints. + + Unlike breakpoint conditions, GDB does not actually evaluate the +conditional expression itself. Instead, GDB encodes the expression into +an agent expression (*note Agent Expressions::) suitable for execution +on the target, independently of GDB. Global variables become raw memory +locations, locals become stack accesses, and so forth. + + For instance, suppose you have a function that is usually called +frequently, but should not be called after an error has occurred. You +could use the following tracepoint command to collect data about calls +of that function that happen while the error code is propagating through +the program; an unconditional tracepoint could end up collecting +thousands of useless trace frames that you would have to search through. + + (gdb) trace normal_operation if errcode > 0 + + +File: gdb.info, Node: Trace State Variables, Next: Tracepoint Actions, Prev: Tracepoint Conditions, Up: Set Tracepoints + +13.1.5 Trace State Variables +---------------------------- + +A "trace state variable" is a special type of variable that is created +and managed by target-side code. The syntax is the same as that for +GDB's convenience variables (a string prefixed with "$"), but they are +stored on the target. They must be created explicitly, using a +'tvariable' command. They are always 64-bit signed integers. + + Trace state variables are remembered by GDB, and downloaded to the +target along with tracepoint information when the trace experiment +starts. There are no intrinsic limits on the number of trace state +variables, beyond memory limitations of the target. + + Although trace state variables are managed by the target, you can use +them in print commands and expressions as if they were convenience +variables; GDB will get the current value from the target while the +trace experiment is running. Trace state variables share the same +namespace as other "$" variables, which means that you cannot have trace +state variables with names like '$23' or '$pc', nor can you have a trace +state variable and a convenience variable with the same name. + +'tvariable $NAME [ = EXPRESSION ]' + The 'tvariable' command creates a new trace state variable named + '$NAME', and optionally gives it an initial value of EXPRESSION. + EXPRESSION is evaluated when this command is entered; the result + will be converted to an integer if possible, otherwise GDB will + report an error. A subsequent 'tvariable' command specifying the + same name does not create a variable, but instead assigns the + supplied initial value to the existing variable of that name, + overwriting any previous initial value. The default initial value + is 0. + +'info tvariables' + List all the trace state variables along with their initial values. + Their current values may also be displayed, if the trace experiment + is currently running. + +'delete tvariable [ $NAME ... ]' + Delete the given trace state variables, or all of them if no + arguments are specified. + + +File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Trace State Variables, Up: Set Tracepoints + +13.1.6 Tracepoint Action Lists +------------------------------ + +'actions [NUM]' + This command will prompt for a list of actions to be taken when the + tracepoint is hit. If the tracepoint number NUM is not specified, + this command sets the actions for the one that was most recently + defined (so that you can define a tracepoint and then say 'actions' + without bothering about its number). You specify the actions + themselves on the following lines, one action at a time, and + terminate the actions list with a line containing just 'end'. So + far, the only defined actions are 'collect', 'teval', and + 'while-stepping'. + + 'actions' is actually equivalent to 'commands' (*note Breakpoint + Command Lists: Break Commands.), except that only the defined + actions are allowed; any other GDB command is rejected. + + To remove all actions from a tracepoint, type 'actions NUM' and + follow it immediately with 'end'. + + (gdb) collect DATA // collect some data + + (gdb) while-stepping 5 // single-step 5 times, collect data + + (gdb) end // signals the end of actions. + + In the following example, the action list begins with 'collect' + commands indicating the things to be collected when the tracepoint + is hit. Then, in order to single-step and collect additional data + following the tracepoint, a 'while-stepping' command is used, + followed by the list of things to be collected after each step in a + sequence of single steps. The 'while-stepping' command is + terminated by its own separate 'end' command. Lastly, the action + list is terminated by an 'end' command. + + (gdb) trace foo + (gdb) actions + Enter actions for tracepoint 1, one per line: + > collect bar,baz + > collect $regs + > while-stepping 12 + > collect $pc, arr[i] + > end + end + +'collect[/MODS] EXPR1, EXPR2, ...' + Collect values of the given expressions when the tracepoint is hit. + This command accepts a comma-separated list of any valid + expressions. In addition to global, static, or local variables, + the following special arguments are supported: + + '$regs' + Collect all registers. + + '$args' + Collect all function arguments. + + '$locals' + Collect all local variables. + + '$_ret' + Collect the return address. This is helpful if you want to + see more of a backtrace. + + '$_probe_argc' + Collects the number of arguments from the static probe at + which the tracepoint is located. *Note Static Probe Points::. + + '$_probe_argN' + N is an integer between 0 and 11. Collects the Nth argument + from the static probe at which the tracepoint is located. + *Note Static Probe Points::. + + '$_sdata' + Collect static tracepoint marker specific data. Only + available for static tracepoints. *Note Tracepoint Action + Lists: Tracepoint Actions. On the UST static tracepoints + library backend, an instrumentation point resembles a 'printf' + function call. The tracing library is able to collect user + specified data formatted to a character string using the + format provided by the programmer that instrumented the + program. Other backends have similar mechanisms. Here's an + example of a UST marker call: + + const char master_name[] = "$your_name"; + trace_mark(channel1, marker1, "hello %s", master_name) + + In this case, collecting '$_sdata' collects the string 'hello + $yourname'. When analyzing the trace buffer, you can inspect + '$_sdata' like any other variable available to GDB. + + You can give several consecutive 'collect' commands, each one with + a single argument, or one 'collect' command with several arguments + separated by commas; the effect is the same. + + The optional MODS changes the usual handling of the arguments. 's' + requests that pointers to chars be handled as strings, in + particular collecting the contents of the memory being pointed at, + up to the first zero. The upper bound is by default the value of + the 'print elements' variable; if 's' is followed by a decimal + number, that is the upper bound instead. So for instance + 'collect/s25 mystr' collects as many as 25 characters at 'mystr'. + + The command 'info scope' (*note info scope: Symbols.) is + particularly useful for figuring out what data to collect. + +'teval EXPR1, EXPR2, ...' + Evaluate the given expressions when the tracepoint is hit. This + command accepts a comma-separated list of expressions. The results + are discarded, so this is mainly useful for assigning values to + trace state variables (*note Trace State Variables::) without + adding those values to the trace buffer, as would be the case if + the 'collect' action were used. + +'while-stepping N' + Perform N single-step instruction traces after the tracepoint, + collecting new data after each step. The 'while-stepping' command + is followed by the list of what to collect while stepping (followed + by its own 'end' command): + + > while-stepping 12 + > collect $regs, myglobal + > end + > + + Note that '$pc' is not automatically collected by 'while-stepping'; + you need to explicitly collect that register if you need it. You + may abbreviate 'while-stepping' as 'ws' or 'stepping'. + +'set default-collect EXPR1, EXPR2, ...' + This variable is a list of expressions to collect at each + tracepoint hit. It is effectively an additional 'collect' action + prepended to every tracepoint action list. The expressions are + parsed individually for each tracepoint, so for instance a variable + named 'xyz' may be interpreted as a global for one tracepoint, and + a local for another, as appropriate to the tracepoint's location. + +'show default-collect' + Show the list of expressions that are collected by default at each + tracepoint hit. + + +File: gdb.info, Node: Listing Tracepoints, Next: Listing Static Tracepoint Markers, Prev: Tracepoint Actions, Up: Set Tracepoints + +13.1.7 Listing Tracepoints +-------------------------- + +'info tracepoints [NUM...]' + Display information about the tracepoint NUM. If you don't specify + a tracepoint number, displays information about all the tracepoints + defined so far. The format is similar to that used for 'info + breakpoints'; in fact, 'info tracepoints' is the same command, + simply restricting itself to tracepoints. + + A tracepoint's listing may include additional information specific + to tracing: + + * its passcount as given by the 'passcount N' command + + * the state about installed on target of each location + + (gdb) info trace + Num Type Disp Enb Address What + 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 + while-stepping 20 + collect globfoo, $regs + end + collect globfoo2 + end + pass count 1200 + 2 tracepoint keep y + collect $eip + 2.1 y 0x0804859c in func4 at change-loc.h:35 + installed on target + 2.2 y 0xb7ffc480 in func4 at change-loc.h:35 + installed on target + 2.3 y set_tracepoint + 3 tracepoint keep y 0x080485b1 in foo at change-loc.c:29 + not installed on target + (gdb) + + This command can be abbreviated 'info tp'. + + +File: gdb.info, Node: Listing Static Tracepoint Markers, Next: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints + +13.1.8 Listing Static Tracepoint Markers +---------------------------------------- + +'info static-tracepoint-markers' + Display information about all static tracepoint markers defined in + the program. + + For each marker, the following columns are printed: + + _Count_ + An incrementing counter, output to help readability. This is + not a stable identifier. + _ID_ + The marker ID, as reported by the target. + _Enabled or Disabled_ + Probed markers are tagged with 'y'. 'n' identifies marks that + are not enabled. + _Address_ + Where the marker is in your program, as a memory address. + _What_ + Where the marker is in the source for your program, as a file + and line number. If the debug information included in the + program does not allow GDB to locate the source of the marker, + this column will be left blank. + + In addition, the following information may be printed for each + marker: + + _Data_ + User data passed to the tracing library by the marker call. + In the UST backend, this is the format string passed as + argument to the marker call. + _Static tracepoints probing the marker_ + The list of static tracepoints attached to the marker. + + (gdb) info static-tracepoint-markers + Cnt ID Enb Address What + 1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 + Data: number1 %d number2 %d + Probed by static tracepoints: #2 + 2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 + Data: str %s + (gdb) + + +File: gdb.info, Node: Starting and Stopping Trace Experiments, Next: Tracepoint Restrictions, Prev: Listing Static Tracepoint Markers, Up: Set Tracepoints + +13.1.9 Starting and Stopping Trace Experiments +---------------------------------------------- + +'tstart' + This command starts the trace experiment, and begins collecting + data. It has the side effect of discarding all the data collected + in the trace buffer during the previous trace experiment. If any + arguments are supplied, they are taken as a note and stored with + the trace experiment's state. The notes may be arbitrary text, and + are especially useful with disconnected tracing in a multi-user + context; the notes can explain what the trace is doing, supply user + contact information, and so forth. + +'tstop' + This command stops the trace experiment. If any arguments are + supplied, they are recorded with the experiment as a note. This is + useful if you are stopping a trace started by someone else, for + instance if the trace is interfering with the system's behavior and + needs to be stopped quickly. + + *Note*: a trace experiment and data collection may stop + automatically if any tracepoint's passcount is reached (*note + Tracepoint Passcounts::), or if the trace buffer becomes full. + +'tstatus' + This command displays the status of the current trace data + collection. + + Here is an example of the commands we described so far: + + (gdb) trace gdb_c_test + (gdb) actions + Enter actions for tracepoint #1, one per line. + > collect $regs,$locals,$args + > while-stepping 11 + > collect $regs + > end + > end + (gdb) tstart + [time passes ...] + (gdb) tstop + + You can choose to continue running the trace experiment even if GDB +disconnects from the target, voluntarily or involuntarily. For commands +such as 'detach', the debugger will ask what you want to do with the +trace. But for unexpected terminations (GDB crash, network outage), it +would be unfortunate to lose hard-won trace data, so the variable +'disconnected-tracing' lets you decide whether the trace should continue +running without GDB. + +'set disconnected-tracing on' +'set disconnected-tracing off' + Choose whether a tracing run should continue to run if GDB has + disconnected from the target. Note that 'detach' or 'quit' will + ask you directly what to do about a running trace no matter what + this variable's setting, so the variable is mainly useful for + handling unexpected situations, such as loss of the network. + +'show disconnected-tracing' + Show the current choice for disconnected tracing. + + When you reconnect to the target, the trace experiment may or may not +still be running; it might have filled the trace buffer in the meantime, +or stopped for one of the other reasons. If it is running, it will +continue after reconnection. + + Upon reconnection, the target will upload information about the +tracepoints in effect. GDB will then compare that information to the +set of tracepoints currently defined, and attempt to match them up, +allowing for the possibility that the numbers may have changed due to +creation and deletion in the meantime. If one of the target's +tracepoints does not match any in GDB, the debugger will create a new +tracepoint, so that you have a number with which to specify that +tracepoint. This matching-up process is necessarily heuristic, and it +may result in useless tracepoints being created; you may simply delete +them if they are of no use. + + If your target agent supports a "circular trace buffer", then you can +run a trace experiment indefinitely without filling the trace buffer; +when space runs out, the agent deletes already-collected trace frames, +oldest first, until there is enough room to continue collecting. This +is especially useful if your tracepoints are being hit too often, and +your trace gets terminated prematurely because the buffer is full. To +ask for a circular trace buffer, simply set 'circular-trace-buffer' to +on. You can set this at any time, including during tracing; if the +agent can do it, it will change buffer handling on the fly, otherwise it +will not take effect until the next run. + +'set circular-trace-buffer on' +'set circular-trace-buffer off' + Choose whether a tracing run should use a linear or circular buffer + for trace data. A linear buffer will not lose any trace data, but + may fill up prematurely, while a circular buffer will discard old + trace data, but it will have always room for the latest tracepoint + hits. + +'show circular-trace-buffer' + Show the current choice for the trace buffer. Note that this may + not match the agent's current buffer handling, nor is it guaranteed + to match the setting that might have been in effect during a past + run, for instance if you are looking at frames from a trace file. + +'set trace-buffer-size N' +'set trace-buffer-size unlimited' + Request that the target use a trace buffer of N bytes. Not all + targets will honor the request; they may have a compiled-in size + for the trace buffer, or some other limitation. Set to a value of + 'unlimited' or '-1' to let the target use whatever size it likes. + This is also the default. + +'show trace-buffer-size' + Show the current requested size for the trace buffer. Note that + this will only match the actual size if the target supports + size-setting, and was able to handle the requested size. For + instance, if the target can only change buffer size between runs, + this variable will not reflect the change until the next run + starts. Use 'tstatus' to get a report of the actual buffer size. + +'set trace-user TEXT' + +'show trace-user' + +'set trace-notes TEXT' + Set the trace run's notes. + +'show trace-notes' + Show the trace run's notes. + +'set trace-stop-notes TEXT' + Set the trace run's stop notes. The handling of the note is as for + 'tstop' arguments; the set command is convenient way to fix a stop + note that is mistaken or incomplete. + +'show trace-stop-notes' + Show the trace run's stop notes. + + +File: gdb.info, Node: Tracepoint Restrictions, Prev: Starting and Stopping Trace Experiments, Up: Set Tracepoints + +13.1.10 Tracepoint Restrictions +------------------------------- + +There are a number of restrictions on the use of tracepoints. As +described above, tracepoint data gathering occurs on the target without +interaction from GDB. Thus the full capabilities of the debugger are +not available during data gathering, and then at data examination time, +you will be limited by only having what was collected. The following +items describe some common problems, but it is not exhaustive, and you +may run into additional difficulties not mentioned here. + + * Tracepoint expressions are intended to gather objects (lvalues). + Thus the full flexibility of GDB's expression evaluator is not + available. You cannot call functions, cast objects to aggregate + types, access convenience variables or modify values (except by + assignment to trace state variables). Some language features may + implicitly call functions (for instance Objective-C fields with + accessors), and therefore cannot be collected either. + + * Collection of local variables, either individually or in bulk with + '$locals' or '$args', during 'while-stepping' may behave + erratically. The stepping action may enter a new scope (for + instance by stepping into a function), or the location of the + variable may change (for instance it is loaded into a register). + The tracepoint data recorded uses the location information for the + variables that is correct for the tracepoint location. When the + tracepoint is created, it is not possible, in general, to determine + where the steps of a 'while-stepping' sequence will advance the + program--particularly if a conditional branch is stepped. + + * Collection of an incompletely-initialized or partially-destroyed + object may result in something that GDB cannot display, or displays + in a misleading way. + + * When GDB displays a pointer to character it automatically + dereferences the pointer to also display characters of the string + being pointed to. However, collecting the pointer during tracing + does not automatically collect the string. You need to explicitly + dereference the pointer and provide size information if you want to + collect not only the pointer, but the memory pointed to. For + example, '*ptr@50' can be used to collect the 50 element array + pointed to by 'ptr'. + + * It is not possible to collect a complete stack backtrace at a + tracepoint. Instead, you may collect the registers and a few + hundred bytes from the stack pointer with something like + '*(unsigned char *)$esp@300' (adjust to use the name of the actual + stack pointer register on your target architecture, and the amount + of stack you wish to capture). Then the 'backtrace' command will + show a partial backtrace when using a trace frame. The number of + stack frames that can be examined depends on the sizes of the + frames in the collected stack. Note that if you ask for a block so + large that it goes past the bottom of the stack, the target agent + may report an error trying to read from an invalid address. + + * If you do not collect registers at a tracepoint, GDB can infer that + the value of '$pc' must be the same as the address of the + tracepoint and use that when you are looking at a trace frame for + that tracepoint. However, this cannot work if the tracepoint has + multiple locations (for instance if it was set in a function that + was inlined), or if it has a 'while-stepping' loop. In those cases + GDB will warn you that it can't infer '$pc', and default it to + zero. + + +File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints + +13.2 Using the Collected Data +============================= + +After the tracepoint experiment ends, you use GDB commands for examining +the trace data. The basic idea is that each tracepoint collects a trace +"snapshot" every time it is hit and another snapshot every time it +single-steps. All these snapshots are consecutively numbered from zero +and go into a buffer, and you can examine them later. The way you +examine them is to "focus" on a specific trace snapshot. When the +remote stub is focused on a trace snapshot, it will respond to all GDB +requests for memory and registers by reading from the buffer which +belongs to that snapshot, rather than from _real_ memory or registers of +the program being debugged. This means that *all* GDB commands +('print', 'info registers', 'backtrace', etc.) will behave as if we +were currently debugging the program state as it was when the tracepoint +occurred. Any requests for data that are not in the buffer will fail. + +* Menu: + +* tfind:: How to select a trace snapshot +* tdump:: How to display all data for a snapshot +* save tracepoints:: How to save tracepoints for a future run + + +File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data + +13.2.1 'tfind N' +---------------- + +The basic command for selecting a trace snapshot from the buffer is +'tfind N', which finds trace snapshot number N, counting from zero. If +no argument N is given, the next snapshot is selected. + + Here are the various forms of using the 'tfind' command. + +'tfind start' + Find the first snapshot in the buffer. This is a synonym for + 'tfind 0' (since 0 is the number of the first snapshot). + +'tfind none' + Stop debugging trace snapshots, resume _live_ debugging. + +'tfind end' + Same as 'tfind none'. + +'tfind' + No argument means find the next trace snapshot. + +'tfind -' + Find the previous trace snapshot before the current one. This + permits retracing earlier steps. + +'tfind tracepoint NUM' + Find the next snapshot associated with tracepoint NUM. Search + proceeds forward from the last examined trace snapshot. If no + argument NUM is given, it means find the next snapshot collected + for the same tracepoint as the current snapshot. + +'tfind pc ADDR' + Find the next snapshot associated with the value ADDR of the + program counter. Search proceeds forward from the last examined + trace snapshot. If no argument ADDR is given, it means find the + next snapshot with the same value of PC as the current snapshot. + +'tfind outside ADDR1, ADDR2' + Find the next snapshot whose PC is outside the given range of + addresses (exclusive). + +'tfind range ADDR1, ADDR2' + Find the next snapshot whose PC is between ADDR1 and ADDR2 + (inclusive). + +'tfind line [FILE:]N' + Find the next snapshot associated with the source line N. If the + optional argument FILE is given, refer to line N in that source + file. Search proceeds forward from the last examined trace + snapshot. If no argument N is given, it means find the next line + other than the one currently being examined; thus saying 'tfind + line' repeatedly can appear to have the same effect as stepping + from line to line in a _live_ debugging session. + + The default arguments for the 'tfind' commands are specifically +designed to make it easy to scan through the trace buffer. For +instance, 'tfind' with no argument selects the next trace snapshot, and +'tfind -' with no argument selects the previous trace snapshot. So, by +giving one 'tfind' command, and then simply hitting repeatedly you +can examine all the trace snapshots in order. Or, by saying 'tfind -' +and then hitting repeatedly you can examine the snapshots in +reverse order. The 'tfind line' command with no argument selects the +snapshot for the next source line executed. The 'tfind pc' command with +no argument selects the next snapshot with the same program counter (PC) +as the current frame. The 'tfind tracepoint' command with no argument +selects the next trace snapshot collected by the same tracepoint as the +current one. + + In addition to letting you scan through the trace buffer manually, +these commands make it easy to construct GDB scripts that scan through +the trace buffer and print out whatever collected data you are +interested in. Thus, if we want to examine the PC, FP, and SP registers +from each trace frame in the buffer, we can say this: + + (gdb) tfind start + (gdb) while ($trace_frame != -1) + > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ + $trace_frame, $pc, $sp, $fp + > tfind + > end + + Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 + Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 + Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 + Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 + Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 + Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 + Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 + Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 + Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 + Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 + Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 + + Or, if we want to examine the variable 'X' at each source line in the +buffer: + + (gdb) tfind start + (gdb) while ($trace_frame != -1) + > printf "Frame %d, X == %d\n", $trace_frame, X + > tfind line + > end + + Frame 0, X = 1 + Frame 7, X = 2 + Frame 13, X = 255 + + +File: gdb.info, Node: tdump, Next: save tracepoints, Prev: tfind, Up: Analyze Collected Data + +13.2.2 'tdump' +-------------- + +This command takes no arguments. It prints all the data collected at +the current trace snapshot. + + (gdb) trace 444 + (gdb) actions + Enter actions for tracepoint #2, one per line: + > collect $regs, $locals, $args, gdb_long_test + > end + + (gdb) tstart + + (gdb) tfind line 444 + #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) + at gdb_test.c:444 + 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) + + (gdb) tdump + Data collected at tracepoint 2, trace frame 1: + d0 0xc4aa0085 -995491707 + d1 0x18 24 + d2 0x80 128 + d3 0x33 51 + d4 0x71aea3d 119204413 + d5 0x22 34 + d6 0xe0 224 + d7 0x380035 3670069 + a0 0x19e24a 1696330 + a1 0x3000668 50333288 + a2 0x100 256 + a3 0x322000 3284992 + a4 0x3000698 50333336 + a5 0x1ad3cc 1758156 + fp 0x30bf3c 0x30bf3c + sp 0x30bf34 0x30bf34 + ps 0x0 0 + pc 0x20b2c8 0x20b2c8 + fpcontrol 0x0 0 + fpstatus 0x0 0 + fpiaddr 0x0 0 + p = 0x20e5b4 "gdb-test" + p1 = (void *) 0x11 + p2 = (void *) 0x22 + p3 = (void *) 0x33 + p4 = (void *) 0x44 + p5 = (void *) 0x55 + p6 = (void *) 0x66 + gdb_long_test = 17 '\021' + + (gdb) + + 'tdump' works by scanning the tracepoint's current collection actions +and printing the value of each expression listed. So 'tdump' can fail, +if after a run, you change the tracepoint's actions to mention variables +that were not collected during the run. + + Also, for tracepoints with 'while-stepping' loops, 'tdump' uses the +collected value of '$pc' to distinguish between trace frames that were +collected at the tracepoint hit, and frames that were collected while +stepping. This allows it to correctly choose whether to display the +basic list of collections, or the collections from the body of the +while-stepping loop. However, if '$pc' was not collected, then 'tdump' +will always attempt to dump using the basic collection list, and may +fail if a while-stepping frame does not include all the same data that +is collected at the tracepoint hit. + + +File: gdb.info, Node: save tracepoints, Prev: tdump, Up: Analyze Collected Data + +13.2.3 'save tracepoints FILENAME' +---------------------------------- + +This command saves all current tracepoint definitions together with +their actions and passcounts, into a file 'FILENAME' suitable for use in +a later debugging session. To read the saved tracepoint definitions, +use the 'source' command (*note Command Files::). The 'save-tracepoints' +command is a deprecated alias for 'save tracepoints' + + +File: gdb.info, Node: Tracepoint Variables, Next: Trace Files, Prev: Analyze Collected Data, Up: Tracepoints + +13.3 Convenience Variables for Tracepoints +========================================== + +'(int) $trace_frame' + The current trace snapshot (a.k.a. "frame") number, or -1 if no + snapshot is selected. + +'(int) $tracepoint' + The tracepoint for the current trace snapshot. + +'(int) $trace_line' + The line number for the current trace snapshot. + +'(char []) $trace_file' + The source file for the current trace snapshot. + +'(char []) $trace_func' + The name of the function containing '$tracepoint'. + + Note: '$trace_file' is not suitable for use in 'printf', use 'output' +instead. + + Here's a simple example of using these convenience variables for +stepping through all the trace snapshots and printing some of their +data. Note that these are not the same as trace state variables, which +are managed by the target. + + (gdb) tfind start + + (gdb) while $trace_frame != -1 + > output $trace_file + > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint + > tfind + > end + + +File: gdb.info, Node: Trace Files, Prev: Tracepoint Variables, Up: Tracepoints + +13.4 Using Trace Files +====================== + +In some situations, the target running a trace experiment may no longer +be available; perhaps it crashed, or the hardware was needed for a +different activity. To handle these cases, you can arrange to dump the +trace data into a file, and later use that file as a source of trace +data, via the 'target tfile' command. + +'tsave [ -r ] FILENAME' +'tsave [-ctf] DIRNAME' + Save the trace data to FILENAME. By default, this command assumes + that FILENAME refers to the host filesystem, so if necessary GDB + will copy raw trace data up from the target and then save it. If + the target supports it, you can also supply the optional argument + '-r' ("remote") to direct the target to save the data directly into + FILENAME in its own filesystem, which may be more efficient if the + trace buffer is very large. (Note, however, that 'target tfile' + can only read from files accessible to the host.) By default, this + command will save trace frame in tfile format. You can supply the + optional argument '-ctf' to save date in CTF format. The "Common + Trace Format" (CTF) is proposed as a trace format that can be + shared by multiple debugging and tracing tools. Please go to + 'http://www.efficios.com/ctf' to get more information. + +'target tfile FILENAME' +'target ctf DIRNAME' + Use the file named FILENAME or directory named DIRNAME as a source + of trace data. Commands that examine data work as they do with a + live target, but it is not possible to run any new trace + experiments. 'tstatus' will report the state of the trace run at + the moment the data was saved, as well as the current trace frame + you are examining. FILENAME or DIRNAME must be on a filesystem + accessible to the host. + + (gdb) target ctf ctf.ctf + (gdb) tfind + Found trace frame 0, tracepoint 2 + 39 ++a; /* set tracepoint 1 here */ + (gdb) tdump + Data collected at tracepoint 2, trace frame 0: + i = 0 + a = 0 + b = 1 '\001' + c = {"123", "456", "789", "123", "456", "789"} + d = {{{a = 1, b = 2}, {a = 3, b = 4}}, {{a = 5, b = 6}, {a = 7, b = 8}}} + (gdb) p b + $1 = 1 + + +File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top + +14 Debugging Programs That Use Overlays +*************************************** + +If your program is too large to fit completely in your target system's +memory, you can sometimes use "overlays" to work around this problem. +GDB provides some support for debugging programs that use overlays. + +* Menu: + +* How Overlays Work:: A general explanation of overlays. +* Overlay Commands:: Managing overlays in GDB. +* Automatic Overlay Debugging:: GDB can find out which overlays are + mapped by asking the inferior. +* Overlay Sample Program:: A sample program using overlays. + + +File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays + +14.1 How Overlays Work +====================== + +Suppose you have a computer whose instruction address space is only 64 +kilobytes long, but which has much more memory which can be accessed by +other means: special instructions, segment registers, or memory +management hardware, for example. Suppose further that you want to +adapt a program which is larger than 64 kilobytes to run on this system. + + One solution is to identify modules of your program which are +relatively independent, and need not call each other directly; call +these modules "overlays". Separate the overlays from the main program, +and place their machine code in the larger memory. Place your main +program in instruction memory, but leave at least enough space there to +hold the largest overlay as well. + + Now, to call a function located in an overlay, you must first copy +that overlay's machine code from the large memory into the space set +aside for it in the instruction memory, and then jump to its entry point +there. + + Data Instruction Larger + Address Space Address Space Address Space + +-----------+ +-----------+ +-----------+ + | | | | | | + +-----------+ +-----------+ +-----------+<-- overlay 1 + | program | | main | .----| overlay 1 | load address + | variables | | program | | +-----------+ + | and heap | | | | | | + +-----------+ | | | +-----------+<-- overlay 2 + | | +-----------+ | | | load address + +-----------+ | | | .-| overlay 2 | + | | | | | | + mapped --->+-----------+ | | +-----------+ + address | | | | | | + | overlay | <-' | | | + | area | <---' +-----------+<-- overlay 3 + | | <---. | | load address + +-----------+ `--| overlay 3 | + | | | | + +-----------+ | | + +-----------+ + | | + +-----------+ + + A code overlay + + The diagram (*note A code overlay::) shows a system with separate +data and instruction address spaces. To map an overlay, the program +copies its code from the larger address space to the instruction address +space. Since the overlays shown here all use the same mapped address, +only one may be mapped at a time. For a system with a single address +space for data and instructions, the diagram would be similar, except +that the program variables and heap would share an address space with +the main program and the overlay area. + + An overlay loaded into instruction memory and ready for use is called +a "mapped" overlay; its "mapped address" is its address in the +instruction memory. An overlay not present (or only partially present) +in instruction memory is called "unmapped"; its "load address" is its +address in the larger memory. The mapped address is also called the +"virtual memory address", or "VMA"; the load address is also called the +"load memory address", or "LMA". + + Unfortunately, overlays are not a completely transparent way to adapt +a program to limited instruction memory. They introduce a new set of +global constraints you must keep in mind as you design your program: + + * Before calling or returning to a function in an overlay, your + program must make sure that overlay is actually mapped. Otherwise, + the call or return will transfer control to the right address, but + in the wrong overlay, and your program will probably crash. + + * If the process of mapping an overlay is expensive on your system, + you will need to choose your overlays carefully to minimize their + effect on your program's performance. + + * The executable file you load onto your system must contain each + overlay's instructions, appearing at the overlay's load address, + not its mapped address. However, each overlay's instructions must + be relocated and its symbols defined as if the overlay were at its + mapped address. You can use GNU linker scripts to specify + different load and relocation addresses for pieces of your program; + see *note (ld.info)Overlay Description::. + + * The procedure for loading executable files onto your system must be + able to load their contents into the larger address space as well + as the instruction and data spaces. + + The overlay system described above is rather simple, and could be +improved in many ways: + + * If your system has suitable bank switch registers or memory + management hardware, you could use those facilities to make an + overlay's load area contents simply appear at their mapped address + in instruction space. This would probably be faster than copying + the overlay to its mapped area in the usual way. + + * If your overlays are small enough, you could set aside more than + one overlay area, and have more than one overlay mapped at a time. + + * You can use overlays to manage data, as well as instructions. In + general, data overlays are even less transparent to your design + than code overlays: whereas code overlays only require care when + you call or return to functions, data overlays require care every + time you access the data. Also, if you change the contents of a + data overlay, you must copy its contents back out to its load + address before you can copy a different data overlay into the same + mapped area. + + +File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays + +14.2 Overlay Commands +===================== + +To use GDB's overlay support, each overlay in your program must +correspond to a separate section of the executable file. The section's +virtual memory address and load memory address must be the overlay's +mapped and load addresses. Identifying overlays with sections allows +GDB to determine the appropriate address of a function or variable, +depending on whether the overlay is mapped or not. + + GDB's overlay commands all start with the word 'overlay'; you can +abbreviate this as 'ov' or 'ovly'. The commands are: + +'overlay off' + Disable GDB's overlay support. When overlay support is disabled, + GDB assumes that all functions and variables are always present at + their mapped addresses. By default, GDB's overlay support is + disabled. + +'overlay manual' + Enable "manual" overlay debugging. In this mode, GDB relies on you + to tell it which overlays are mapped, and which are not, using the + 'overlay map-overlay' and 'overlay unmap-overlay' commands + described below. + +'overlay map-overlay OVERLAY' +'overlay map OVERLAY' + Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of + the object file section containing the overlay. When an overlay is + mapped, GDB assumes it can find the overlay's functions and + variables at their mapped addresses. GDB assumes that any other + overlays whose mapped ranges overlap that of OVERLAY are now + unmapped. + +'overlay unmap-overlay OVERLAY' +'overlay unmap OVERLAY' + Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the name + of the object file section containing the overlay. When an overlay + is unmapped, GDB assumes it can find the overlay's functions and + variables at their load addresses. + +'overlay auto' + Enable "automatic" overlay debugging. In this mode, GDB consults a + data structure the overlay manager maintains in the inferior to see + which overlays are mapped. For details, see *note Automatic + Overlay Debugging::. + +'overlay load-target' +'overlay load' + Re-read the overlay table from the inferior. Normally, GDB + re-reads the table GDB automatically each time the inferior stops, + so this command should only be necessary if you have changed the + overlay mapping yourself using GDB. This command is only useful + when using automatic overlay debugging. + +'overlay list-overlays' +'overlay list' + Display a list of the overlays currently mapped, along with their + mapped addresses, load addresses, and sizes. + + Normally, when GDB prints a code address, it includes the name of the +function the address falls in: + + (gdb) print main + $3 = {int ()} 0x11a0
+When overlay debugging is enabled, GDB recognizes code in unmapped +overlays, and prints the names of unmapped functions with asterisks +around them. For example, if 'foo' is a function in an unmapped +overlay, GDB prints it this way: + + (gdb) overlay list + No sections are mapped. + (gdb) print foo + $5 = {int (int)} 0x100000 <*foo*> +When 'foo''s overlay is mapped, GDB prints the function's name normally: + + (gdb) overlay list + Section .ov.foo.text, loaded at 0x100000 - 0x100034, + mapped at 0x1016 - 0x104a + (gdb) print foo + $6 = {int (int)} 0x1016 + + When overlay debugging is enabled, GDB can find the correct address +for functions and variables in an overlay, whether or not the overlay is +mapped. This allows most GDB commands, like 'break' and 'disassemble', +to work normally, even on unmapped code. However, GDB's breakpoint +support has some limitations: + + * You can set breakpoints in functions in unmapped overlays, as long + as GDB can write to the overlay at its load address. + * GDB can not set hardware or simulator-based breakpoints in unmapped + overlays. However, if you set a breakpoint at the end of your + overlay manager (and tell GDB which overlays are now mapped, if you + are using manual overlay management), GDB will re-set its + breakpoints properly. + + +File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays + +14.3 Automatic Overlay Debugging +================================ + +GDB can automatically track which overlays are mapped and which are not, +given some simple co-operation from the overlay manager in the inferior. +If you enable automatic overlay debugging with the 'overlay auto' +command (*note Overlay Commands::), GDB looks in the inferior's memory +for certain variables describing the current state of the overlays. + + Here are the variables your overlay manager must define to support +GDB's automatic overlay debugging: + +'_ovly_table': + This variable must be an array of the following structures: + + struct + { + /* The overlay's mapped address. */ + unsigned long vma; + + /* The size of the overlay, in bytes. */ + unsigned long size; + + /* The overlay's load address. */ + unsigned long lma; + + /* Non-zero if the overlay is currently mapped; + zero otherwise. */ + unsigned long mapped; + } + +'_novlys': + This variable must be a four-byte signed integer, holding the total + number of elements in '_ovly_table'. + + To decide whether a particular overlay is mapped or not, GDB looks +for an entry in '_ovly_table' whose 'vma' and 'lma' members equal the +VMA and LMA of the overlay's section in the executable file. When GDB +finds a matching entry, it consults the entry's 'mapped' member to +determine whether the overlay is currently mapped. + + In addition, your overlay manager may define a function called +'_ovly_debug_event'. If this function is defined, GDB will silently set +a breakpoint there. If the overlay manager then calls this function +whenever it has changed the overlay table, this will enable GDB to +accurately keep track of which overlays are in program memory, and +update any breakpoints that may be set in overlays. This will allow +breakpoints to work even if the overlays are kept in ROM or other +non-writable memory while they are not being executed. + + +File: gdb.info, Node: Overlay Sample Program, Prev: Automatic Overlay Debugging, Up: Overlays + +14.4 Overlay Sample Program +=========================== + +When linking a program which uses overlays, you must place the overlays +at their load addresses, while relocating them to run at their mapped +addresses. To do this, you must write a linker script (*note +(ld.info)Overlay Description::). Unfortunately, since linker scripts +are specific to a particular host system, target architecture, and +target memory layout, this manual cannot provide portable sample code +demonstrating GDB's overlay support. + + However, the GDB source distribution does contain an overlaid +program, with linker scripts for a few systems, as part of its test +suite. The program consists of the following files from +'gdb/testsuite/gdb.base': + +'overlays.c' + The main program file. +'ovlymgr.c' + A simple overlay manager, used by 'overlays.c'. +'foo.c' +'bar.c' +'baz.c' +'grbx.c' + Overlay modules, loaded and used by 'overlays.c'. +'d10v.ld' +'m32r.ld' + Linker scripts for linking the test program on the 'd10v-elf' and + 'm32r-elf' targets. + + You can build the test program using the 'd10v-elf' GCC +cross-compiler like this: + + $ d10v-elf-gcc -g -c overlays.c + $ d10v-elf-gcc -g -c ovlymgr.c + $ d10v-elf-gcc -g -c foo.c + $ d10v-elf-gcc -g -c bar.c + $ d10v-elf-gcc -g -c baz.c + $ d10v-elf-gcc -g -c grbx.c + $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ + baz.o grbx.o -Wl,-Td10v.ld -o overlays + + The build process is identical for any other architecture, except +that you must substitute the appropriate compiler and linker script for +the target system for 'd10v-elf-gcc' and 'd10v.ld'. + + +File: gdb.info, Node: Languages, Next: Symbols, Prev: Overlays, Up: Top + +15 Using GDB with Different Languages +************************************* + +Although programming languages generally have common aspects, they are +rarely expressed in the same manner. For instance, in ANSI C, +dereferencing a pointer 'p' is accomplished by '*p', but in Modula-2, it +is accomplished by 'p^'. Values can also be represented (and displayed) +differently. Hex numbers in C appear as '0x1ae', while in Modula-2 they +appear as '1AEH'. + + Language-specific information is built into GDB for some languages, +allowing you to express operations like the above in your program's +native language, and allowing GDB to output values in a manner +consistent with the syntax of your program's native language. The +language you use to build expressions is called the "working language". + +* Menu: + +* Setting:: Switching between source languages +* Show:: Displaying the language +* Checks:: Type and range checks +* Supported Languages:: Supported languages +* Unsupported Languages:: Unsupported languages + + +File: gdb.info, Node: Setting, Next: Show, Up: Languages + +15.1 Switching Between Source Languages +======================================= + +There are two ways to control the working language--either have GDB set +it automatically, or select it manually yourself. You can use the 'set +language' command for either purpose. On startup, GDB defaults to +setting the language automatically. The working language is used to +determine how expressions you type are interpreted, how values are +printed, etc. + + In addition to the working language, every source file that GDB knows +about has its own working language. For some object file formats, the +compiler might indicate which language a particular source file is in. +However, most of the time GDB infers the language from the name of the +file. The language of a source file controls whether C++ names are +demangled--this way 'backtrace' can show each frame appropriately for +its own language. There is no way to set the language of a source file +from within GDB, but you can set the language associated with a filename +extension. *Note Displaying the Language: Show. + + This is most commonly a problem when you use a program, such as +'cfront' or 'f2c', that generates C but is written in another language. +In that case, make the program use '#line' directives in its C output; +that way GDB will know the correct language of the source code of the +original program, and will display that source code, not the generated C +code. + +* Menu: + +* Filenames:: Filename extensions and languages. +* Manually:: Setting the working language manually +* Automatically:: Having GDB infer the source language + + +File: gdb.info, Node: Filenames, Next: Manually, Up: Setting + +15.1.1 List of Filename Extensions and Languages +------------------------------------------------ + +If a source file name ends in one of the following extensions, then GDB +infers that its language is the one indicated. + +'.ada' +'.ads' +'.adb' +'.a' + Ada source file. + +'.c' + C source file + +'.C' +'.cc' +'.cp' +'.cpp' +'.cxx' +'.c++' + C++ source file + +'.d' + D source file + +'.m' + Objective-C source file + +'.f' +'.F' + Fortran source file + +'.mod' + Modula-2 source file + +'.s' +'.S' + Assembler source file. This actually behaves almost like C, but + GDB does not skip over function prologues when stepping. + + In addition, you may set the language associated with a filename +extension. *Note Displaying the Language: Show. + + +File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting + +15.1.2 Setting the Working Language +----------------------------------- + +If you allow GDB to set the language automatically, expressions are +interpreted the same way in your debugging session and your program. + + If you wish, you may set the language manually. To do this, issue +the command 'set language LANG', where LANG is the name of a language, +such as 'c' or 'modula-2'. For a list of the supported languages, type +'set language'. + + Setting the language manually prevents GDB from updating the working +language automatically. This can lead to confusion if you try to debug +a program when the working language is not the same as the source +language, when an expression is acceptable to both languages--but means +different things. For instance, if the current source file were written +in C, and GDB was parsing Modula-2, a command such as: + + print a = b + c + +might not have the effect you intended. In C, this means to add 'b' and +'c' and place the result in 'a'. The result printed would be the value +of 'a'. In Modula-2, this means to compare 'a' to the result of 'b+c', +yielding a 'BOOLEAN' value. + + +File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting + +15.1.3 Having GDB Infer the Source Language +------------------------------------------- + +To have GDB set the working language automatically, use 'set language +local' or 'set language auto'. GDB then infers the working language. +That is, when your program stops in a frame (usually by encountering a +breakpoint), GDB sets the working language to the language recorded for +the function in that frame. If the language for a frame is unknown +(that is, if the function or block corresponding to the frame was +defined in a source file that does not have a recognized extension), the +current working language is not changed, and GDB issues a warning. + + This may not seem necessary for most programs, which are written +entirely in one source language. However, program modules and libraries +written in one source language can be used by a main program written in +a different source language. Using 'set language auto' in this case +frees you from having to set the working language manually. + + +File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages + +15.2 Displaying the Language +============================ + +The following commands help you find out which language is the working +language, and also what language source files were written in. + +'show language' + Display the current working language. This is the language you can + use with commands such as 'print' to build and compute expressions + that may involve variables in your program. + +'info frame' + Display the source language for this frame. This language becomes + the working language if you use an identifier from this frame. + *Note Information about a Frame: Frame Info, to identify the other + information listed here. + +'info source' + Display the source language of this source file. *Note Examining + the Symbol Table: Symbols, to identify the other information listed + here. + + In unusual circumstances, you may have source files with extensions +not in the standard list. You can then set the extension associated +with a language explicitly: + +'set extension-language EXT LANGUAGE' + Tell GDB that source files with extension EXT are to be assumed as + written in the source language LANGUAGE. + +'info extensions' + List all the filename extensions and the associated languages. + + +File: gdb.info, Node: Checks, Next: Supported Languages, Prev: Show, Up: Languages + +15.3 Type and Range Checking +============================ + +Some languages are designed to guard you against making seemingly common +errors through a series of compile- and run-time checks. These include +checking the type of arguments to functions and operators and making +sure mathematical overflows are caught at run time. Checks such as +these help to ensure a program's correctness once it has been compiled +by eliminating type mismatches and providing active checks for range +errors when your program is running. + + By default GDB checks for these errors according to the rules of the +current source language. Although GDB does not check the statements in +your program, it can check expressions entered directly into GDB for +evaluation via the 'print' command, for example. + +* Menu: + +* Type Checking:: An overview of type checking +* Range Checking:: An overview of range checking + + +File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks + +15.3.1 An Overview of Type Checking +----------------------------------- + +Some languages, such as C and C++, are strongly typed, meaning that the +arguments to operators and functions have to be of the correct type, +otherwise an error occurs. These checks prevent type mismatch errors +from ever causing any run-time problems. For example, + + int klass::my_method(char *b) { return b ? 1 : 2; } + + (gdb) print obj.my_method (0) + $1 = 2 +but + (gdb) print obj.my_method (0x1234) + Cannot resolve method klass::my_method to any overloaded instance + + The second example fails because in C++ the integer constant '0x1234' +is not type-compatible with the pointer parameter type. + + For the expressions you use in GDB commands, you can tell GDB to not +enforce strict type checking or to treat any mismatches as errors and +abandon the expression; When type checking is disabled, GDB successfully +evaluates expressions like the second example above. + + Even if type checking is off, there may be other reasons related to +type that prevent GDB from evaluating an expression. For instance, GDB +does not know how to add an 'int' and a 'struct foo'. These particular +type errors have nothing to do with the language in use and usually +arise from expressions which make little sense to evaluate anyway. + + GDB provides some additional commands for controlling type checking: + +'set check type on' +'set check type off' + Set strict type checking on or off. If any type mismatches occur + in evaluating an expression while type checking is on, GDB prints a + message and aborts evaluation of the expression. + +'show check type' + Show the current setting of type checking and whether GDB is + enforcing strict type checking rules. + + +File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks + +15.3.2 An Overview of Range Checking +------------------------------------ + +In some languages (such as Modula-2), it is an error to exceed the +bounds of a type; this is enforced with run-time checks. Such range +checking is meant to ensure program correctness by making sure +computations do not overflow, or indices on an array element access do +not exceed the bounds of the array. + + For expressions you use in GDB commands, you can tell GDB to treat +range errors in one of three ways: ignore them, always treat them as +errors and abandon the expression, or issue warnings but evaluate the +expression anyway. + + A range error can result from numerical overflow, from exceeding an +array index bound, or when you type a constant that is not a member of +any type. Some languages, however, do not treat overflows as an error. +In many implementations of C, mathematical overflow causes the result to +"wrap around" to lower values--for example, if M is the largest integer +value, and S is the smallest, then + + M + 1 => S + + This, too, is specific to individual languages, and in some cases +specific to individual compilers or machines. *Note Supported +Languages: Supported Languages, for further details on specific +languages. + + GDB provides some additional commands for controlling the range +checker: + +'set check range auto' + Set range checking on or off based on the current working language. + *Note Supported Languages: Supported Languages, for the default + settings for each language. + +'set check range on' +'set check range off' + Set range checking on or off, overriding the default setting for + the current working language. A warning is issued if the setting + does not match the language default. If a range error occurs and + range checking is on, then a message is printed and evaluation of + the expression is aborted. + +'set check range warn' + Output messages when the GDB range checker detects a range error, + but attempt to evaluate the expression anyway. Evaluating the + expression may still be impossible for other reasons, such as + accessing memory that the process does not own (a typical example + from many Unix systems). + +'show range' + Show the current setting of the range checker, and whether or not + it is being set automatically by GDB. + + +File: gdb.info, Node: Supported Languages, Next: Unsupported Languages, Prev: Checks, Up: Languages + +15.4 Supported Languages +======================== + +GDB supports C, C++, D, Go, Objective-C, Fortran, Java, OpenCL C, +Pascal, assembly, Modula-2, and Ada. Some GDB features may be used in +expressions regardless of the language you use: the GDB '@' and '::' +operators, and the '{type}addr' construct (*note Expressions: +Expressions.) can be used with the constructs of any supported language. + + The following sections detail to what degree each source language is +supported by GDB. These sections are not meant to be language tutorials +or references, but serve only as a reference guide to what the GDB +expression parser accepts, and what input and output formats should look +like for different languages. There are many good books written on each +of these languages; please look to these for a language reference or +tutorial. + +* Menu: + +* C:: C and C++ +* D:: D +* Go:: Go +* Objective-C:: Objective-C +* OpenCL C:: OpenCL C +* Fortran:: Fortran +* Pascal:: Pascal +* Modula-2:: Modula-2 +* Ada:: Ada + + +File: gdb.info, Node: C, Next: D, Up: Supported Languages + +15.4.1 C and C++ +---------------- + +Since C and C++ are so closely related, many features of GDB apply to +both languages. Whenever this is the case, we discuss those languages +together. + + The C++ debugging facilities are jointly implemented by the C++ +compiler and GDB. Therefore, to debug your C++ code effectively, you +must compile your C++ programs with a supported C++ compiler, such as +GNU 'g++', or the HP ANSI C++ compiler ('aCC'). + +* Menu: + +* C Operators:: C and C++ operators +* C Constants:: C and C++ constants +* C Plus Plus Expressions:: C++ expressions +* C Defaults:: Default settings for C and C++ +* C Checks:: C and C++ type and range checks +* Debugging C:: GDB and C +* Debugging C Plus Plus:: GDB features for C++ +* Decimal Floating Point:: Numbers in Decimal Floating Point format + + +File: gdb.info, Node: C Operators, Next: C Constants, Up: C + +15.4.1.1 C and C++ Operators +............................ + +Operators must be defined on values of specific types. For instance, +'+' is defined on numbers, but not on structures. Operators are often +defined on groups of types. + + For the purposes of C and C++, the following definitions hold: + + * _Integral types_ include 'int' with any of its storage-class + specifiers; 'char'; 'enum'; and, for C++, 'bool'. + + * _Floating-point types_ include 'float', 'double', and 'long double' + (if supported by the target platform). + + * _Pointer types_ include all types defined as '(TYPE *)'. + + * _Scalar types_ include all of the above. + +The following operators are supported. They are listed here in order of +increasing precedence: + +',' + The comma or sequencing operator. Expressions in a comma-separated + list are evaluated from left to right, with the result of the + entire expression being the last expression evaluated. + +'=' + Assignment. The value of an assignment expression is the value + assigned. Defined on scalar types. + +'OP=' + Used in an expression of the form 'A OP= B', and translated to + 'A = A OP B'. 'OP=' and '=' have the same precedence. OP is any + one of the operators '|', '^', '&', '<<', '>>', '+', '-', '*', '/', + '%'. + +'?:' + The ternary operator. 'A ? B : C' can be thought of as: if A then + B else C. A should be of an integral type. + +'||' + Logical OR. Defined on integral types. + +'&&' + Logical AND. Defined on integral types. + +'|' + Bitwise OR. Defined on integral types. + +'^' + Bitwise exclusive-OR. Defined on integral types. + +'&' + Bitwise AND. Defined on integral types. + +'==, !=' + Equality and inequality. Defined on scalar types. The value of + these expressions is 0 for false and non-zero for true. + +'<, >, <=, >=' + Less than, greater than, less than or equal, greater than or equal. + Defined on scalar types. The value of these expressions is 0 for + false and non-zero for true. + +'<<, >>' + left shift, and right shift. Defined on integral types. + +'@' + The GDB "artificial array" operator (*note Expressions: + Expressions.). + +'+, -' + Addition and subtraction. Defined on integral types, + floating-point types and pointer types. + +'*, /, %' + Multiplication, division, and modulus. Multiplication and division + are defined on integral and floating-point types. Modulus is + defined on integral types. + +'++, --' + Increment and decrement. When appearing before a variable, the + operation is performed before the variable is used in an + expression; when appearing after it, the variable's value is used + before the operation takes place. + +'*' + Pointer dereferencing. Defined on pointer types. Same precedence + as '++'. + +'&' + Address operator. Defined on variables. Same precedence as '++'. + + For debugging C++, GDB implements a use of '&' beyond what is + allowed in the C++ language itself: you can use '&(&REF)' to + examine the address where a C++ reference variable (declared with + '&REF') is stored. + +'-' + Negative. Defined on integral and floating-point types. Same + precedence as '++'. + +'!' + Logical negation. Defined on integral types. Same precedence as + '++'. + +'~' + Bitwise complement operator. Defined on integral types. Same + precedence as '++'. + +'., ->' + Structure member, and pointer-to-structure member. For + convenience, GDB regards the two as equivalent, choosing whether to + dereference a pointer based on the stored type information. + Defined on 'struct' and 'union' data. + +'.*, ->*' + Dereferences of pointers to members. + +'[]' + Array indexing. 'A[I]' is defined as '*(A+I)'. Same precedence as + '->'. + +'()' + Function parameter list. Same precedence as '->'. + +'::' + C++ scope resolution operator. Defined on 'struct', 'union', and + 'class' types. + +'::' + Doubled colons also represent the GDB scope operator (*note + Expressions: Expressions.). Same precedence as '::', above. + + If an operator is redefined in the user code, GDB usually attempts to +invoke the redefined version instead of using the operator's predefined +meaning. + + +File: gdb.info, Node: C Constants, Next: C Plus Plus Expressions, Prev: C Operators, Up: C + +15.4.1.2 C and C++ Constants +............................ + +GDB allows you to express the constants of C and C++ in the following +ways: + + * Integer constants are a sequence of digits. Octal constants are + specified by a leading '0' (i.e. zero), and hexadecimal constants + by a leading '0x' or '0X'. Constants may also end with a letter + 'l', specifying that the constant should be treated as a 'long' + value. + + * Floating point constants are a sequence of digits, followed by a + decimal point, followed by a sequence of digits, and optionally + followed by an exponent. An exponent is of the form: + 'e[[+]|-]NNN', where NNN is another sequence of digits. The '+' is + optional for positive exponents. A floating-point constant may + also end with a letter 'f' or 'F', specifying that the constant + should be treated as being of the 'float' (as opposed to the + default 'double') type; or with a letter 'l' or 'L', which + specifies a 'long double' constant. + + * Enumerated constants consist of enumerated identifiers, or their + integral equivalents. + + * Character constants are a single character surrounded by single + quotes ('''), or a number--the ordinal value of the corresponding + character (usually its ASCII value). Within quotes, the single + character may be represented by a letter or by "escape sequences", + which are of the form '\NNN', where NNN is the octal representation + of the character's ordinal value; or of the form '\X', where 'X' is + a predefined special character--for example, '\n' for newline. + + Wide character constants can be written by prefixing a character + constant with 'L', as in C. For example, 'L'x'' is the wide form of + 'x'. The target wide character set is used when computing the + value of this constant (*note Character Sets::). + + * String constants are a sequence of character constants surrounded + by double quotes ('"'). Any valid character constant (as described + above) may appear. Double quotes within the string must be + preceded by a backslash, so for instance '"a\"b'c"' is a string of + five characters. + + Wide string constants can be written by prefixing a string constant + with 'L', as in C. The target wide character set is used when + computing the value of this constant (*note Character Sets::). + + * Pointer constants are an integral value. You can also write + pointers to constants using the C operator '&'. + + * Array constants are comma-separated lists surrounded by braces '{' + and '}'; for example, '{1,2,3}' is a three-element array of + integers, '{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and + '{&"hi", &"there", &"fred"}' is a three-element array of pointers. + + +File: gdb.info, Node: C Plus Plus Expressions, Next: C Defaults, Prev: C Constants, Up: C + +15.4.1.3 C++ Expressions +........................ + +GDB expression handling can interpret most C++ expressions. + + _Warning:_ GDB can only debug C++ code if you use the proper + compiler and the proper debug format. Currently, GDB works best + when debugging C++ code that is compiled with the most recent + version of GCC possible. The DWARF debugging format is preferred; + GCC defaults to this on most popular platforms. Other compilers + and/or debug formats are likely to work badly or not at all when + using GDB to debug C++ code. *Note Compilation::. + + 1. Member function calls are allowed; you can use expressions like + + count = aml->GetOriginal(x, y) + + 2. While a member function is active (in the selected stack frame), + your expressions have the same namespace available as the member + function; that is, GDB allows implicit references to the class + instance pointer 'this' following the same rules as C++. 'using' + declarations in the current scope are also respected by GDB. + + 3. You can call overloaded functions; GDB resolves the function call + to the right definition, with some restrictions. GDB does not + perform overload resolution involving user-defined type + conversions, calls to constructors, or instantiations of templates + that do not exist in the program. It also cannot handle ellipsis + argument lists or default arguments. + + It does perform integral conversions and promotions, floating-point + promotions, arithmetic conversions, pointer conversions, + conversions of class objects to base classes, and standard + conversions such as those of functions or arrays to pointers; it + requires an exact match on the number of function arguments. + + Overload resolution is always performed, unless you have specified + 'set overload-resolution off'. *Note GDB Features for C++: + Debugging C Plus Plus. + + You must specify 'set overload-resolution off' in order to use an + explicit function signature to call an overloaded function, as in + p 'foo(char,int)'('x', 13) + + The GDB command-completion facility can simplify this; see *note + Command Completion: Completion. + + 4. GDB understands variables declared as C++ references; you can use + them in expressions just as you do in C++ source--they are + automatically dereferenced. + + In the parameter list shown when GDB displays a frame, the values + of reference variables are not displayed (unlike other variables); + this avoids clutter, since references are often used for large + structures. The _address_ of a reference variable is always shown, + unless you have specified 'set print address off'. + + 5. GDB supports the C++ name resolution operator '::'--your + expressions can use it just as expressions in your program do. + Since one scope may be defined in another, you can use '::' + repeatedly if necessary, for example in an expression like + 'SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by + reference to source files, in both C and C++ debugging (*note + Program Variables: Variables.). + + 6. GDB performs argument-dependent lookup, following the C++ + specification. + + +File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C Plus Plus Expressions, Up: C + +15.4.1.4 C and C++ Defaults +........................... + +If you allow GDB to set range checking automatically, it defaults to +'off' whenever the working language changes to C or C++. This happens +regardless of whether you or GDB selects the working language. + + If you allow GDB to set the language automatically, it recognizes +source files whose names end with '.c', '.C', or '.cc', etc, and when +GDB enters code compiled from one of these files, it sets the working +language to C or C++. *Note Having GDB Infer the Source Language: +Automatically, for further details. + + +File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C + +15.4.1.5 C and C++ Type and Range Checks +........................................ + +By default, when GDB parses C or C++ expressions, strict type checking +is used. However, if you turn type checking off, GDB will allow certain +non-standard conversions, such as promoting integer constants to +pointers. + + Range checking, if turned on, is done on mathematical operations. +Array indices are not checked, since they are often used to index a +pointer that is not itself an array. + + +File: gdb.info, Node: Debugging C, Next: Debugging C Plus Plus, Prev: C Checks, Up: C + +15.4.1.6 GDB and C +.................. + +The 'set print union' and 'show print union' commands apply to the +'union' type. When set to 'on', any 'union' that is inside a 'struct' +or 'class' is also printed. Otherwise, it appears as '{...}'. + + The '@' operator aids in the debugging of dynamic arrays, formed with +pointers and a memory allocation function. *Note Expressions: +Expressions. + + +File: gdb.info, Node: Debugging C Plus Plus, Next: Decimal Floating Point, Prev: Debugging C, Up: C + +15.4.1.7 GDB Features for C++ +............................. + +Some GDB commands are particularly useful with C++, and some are +designed specifically for use with C++. Here is a summary: + +'breakpoint menus' + When you want a breakpoint in a function whose name is overloaded, + GDB has the capability to display a menu of possible breakpoint + locations to help you specify which function definition you want. + *Note Ambiguous Expressions: Ambiguous Expressions. + +'rbreak REGEX' + Setting breakpoints using regular expressions is helpful for + setting breakpoints on overloaded functions that are not members of + any special classes. *Note Setting Breakpoints: Set Breaks. + +'catch throw' +'catch rethrow' +'catch catch' + Debug C++ exception handling using these commands. *Note Setting + Catchpoints: Set Catchpoints. + +'ptype TYPENAME' + Print inheritance relationships as well as other information for + type TYPENAME. *Note Examining the Symbol Table: Symbols. + +'info vtbl EXPRESSION.' + The 'info vtbl' command can be used to display the virtual method + tables of the object computed by EXPRESSION. This shows one entry + per virtual table; there may be multiple virtual tables when + multiple inheritance is in use. + +'set print demangle' +'show print demangle' +'set print asm-demangle' +'show print asm-demangle' + Control whether C++ symbols display in their source form, both when + displaying code as C++ source and when displaying disassemblies. + *Note Print Settings: Print Settings. + +'set print object' +'show print object' + Choose whether to print derived (actual) or declared types of + objects. *Note Print Settings: Print Settings. + +'set print vtbl' +'show print vtbl' + Control the format for printing virtual function tables. *Note + Print Settings: Print Settings. (The 'vtbl' commands do not work + on programs compiled with the HP ANSI C++ compiler ('aCC').) + +'set overload-resolution on' + Enable overload resolution for C++ expression evaluation. The + default is on. For overloaded functions, GDB evaluates the + arguments and searches for a function whose signature matches the + argument types, using the standard C++ conversion rules (see *note + C++ Expressions: C Plus Plus Expressions, for details). If it + cannot find a match, it emits a message. + +'set overload-resolution off' + Disable overload resolution for C++ expression evaluation. For + overloaded functions that are not class member functions, GDB + chooses the first function of the specified name that it finds in + the symbol table, whether or not its arguments are of the correct + type. For overloaded functions that are class member functions, + GDB searches for a function whose signature _exactly_ matches the + argument types. + +'show overload-resolution' + Show the current setting of overload resolution. + +'Overloaded symbol names' + You can specify a particular definition of an overloaded symbol, + using the same notation that is used to declare such symbols in + C++: type 'SYMBOL(TYPES)' rather than just SYMBOL. You can also + use the GDB command-line word completion facilities to list the + available choices, or to finish the type list for you. *Note + Command Completion: Completion, for details on how to do this. + + +File: gdb.info, Node: Decimal Floating Point, Prev: Debugging C Plus Plus, Up: C + +15.4.1.8 Decimal Floating Point format +...................................... + +GDB can examine, set and perform computations with numbers in decimal +floating point format, which in the C language correspond to the +'_Decimal32', '_Decimal64' and '_Decimal128' types as specified by the +extension to support decimal floating-point arithmetic. + + There are two encodings in use, depending on the architecture: BID +(Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed +Decimal) for PowerPC and S/390. GDB will use the appropriate encoding +for the configured target. + + Because of a limitation in 'libdecnumber', the library used by GDB to +manipulate decimal floating point numbers, it is not possible to convert +(using a cast, for example) integers wider than 32-bit to decimal float. + + In addition, in order to imitate GDB's behaviour with binary floating +point computations, error checking in decimal float operations ignores +underflow, overflow and divide by zero exceptions. + + In the PowerPC architecture, GDB provides a set of pseudo-registers +to inspect '_Decimal128' values stored in floating point registers. See +*note PowerPC: PowerPC. for more details. + + +File: gdb.info, Node: D, Next: Go, Prev: C, Up: Supported Languages + +15.4.2 D +-------- + +GDB can be used to debug programs written in D and compiled with GDC, +LDC or DMD compilers. Currently GDB supports only one D specific +feature -- dynamic arrays. + + +File: gdb.info, Node: Go, Next: Objective-C, Prev: D, Up: Supported Languages + +15.4.3 Go +--------- + +GDB can be used to debug programs written in Go and compiled with +'gccgo' or '6g' compilers. + + Here is a summary of the Go-specific features and restrictions: + +'The current Go package' + The name of the current package does not need to be specified when + specifying global variables and functions. + + For example, given the program: + + package main + var myglob = "Shall we?" + func main () { + // ... + } + + When stopped inside 'main' either of these work: + + (gdb) p myglob + (gdb) p main.myglob + +'Builtin Go types' + The 'string' type is recognized by GDB and is printed as a string. + +'Builtin Go functions' + The GDB expression parser recognizes the 'unsafe.Sizeof' function + and handles it internally. + +'Restrictions on Go expressions' + All Go operators are supported except '&^'. The Go '_' "blank + identifier" is not supported. Automatic dereferencing of pointers + is not supported. + + +File: gdb.info, Node: Objective-C, Next: OpenCL C, Prev: Go, Up: Supported Languages + +15.4.4 Objective-C +------------------ + +This section provides information about some commands and command +options that are useful for debugging Objective-C code. See also *note +info classes: Symbols, and *note info selectors: Symbols, for a few more +commands specific to Objective-C support. + +* Menu: + +* Method Names in Commands:: +* The Print Command with Objective-C:: + + +File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Up: Objective-C + +15.4.4.1 Method Names in Commands +................................. + +The following commands have been extended to accept Objective-C method +names as line specifications: + + * 'clear' + * 'break' + * 'info line' + * 'jump' + * 'list' + + A fully qualified Objective-C method name is specified as + + -[CLASS METHODNAME] + + where the minus sign is used to indicate an instance method and a +plus sign (not shown) is used to indicate a class method. The class +name CLASS and method name METHODNAME are enclosed in brackets, similar +to the way messages are specified in Objective-C source code. For +example, to set a breakpoint at the 'create' instance method of class +'Fruit' in the program currently being debugged, enter: + + break -[Fruit create] + + To list ten program lines around the 'initialize' class method, +enter: + + list +[NSText initialize] + + In the current version of GDB, the plus or minus sign is required. +In future versions of GDB, the plus or minus sign will be optional, but +you can use it to narrow the search. It is also possible to specify +just a method name: + + break create + + You must specify the complete method name, including any colons. If +your program's source files contain more than one 'create' method, +you'll be presented with a numbered list of classes that implement that +method. Indicate your choice by number, or type '0' to exit if none +apply. + + As another example, to clear a breakpoint established at the +'makeKeyAndOrderFront:' method of the 'NSWindow' class, enter: + + clear -[NSWindow makeKeyAndOrderFront:] + + +File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C + +15.4.4.2 The Print Command With Objective-C +........................................... + +The print command has also been extended to accept methods. For +example: + + print -[OBJECT hash] + +will tell GDB to send the 'hash' message to OBJECT and print the result. +Also, an additional command has been added, 'print-object' or 'po' for +short, which is meant to print the description of an object. However, +this command may only work with certain Objective-C libraries that have +a particular hook function, '_NSPrintForDebugger', defined. + + +File: gdb.info, Node: OpenCL C, Next: Fortran, Prev: Objective-C, Up: Supported Languages + +15.4.5 OpenCL C +--------------- + +This section provides information about GDBs OpenCL C support. + +* Menu: + +* OpenCL C Datatypes:: +* OpenCL C Expressions:: +* OpenCL C Operators:: + + +File: gdb.info, Node: OpenCL C Datatypes, Next: OpenCL C Expressions, Up: OpenCL C + +15.4.5.1 OpenCL C Datatypes +........................... + +GDB supports the builtin scalar and vector datatypes specified by OpenCL +1.1. In addition the half- and double-precision floating point data +types of the 'cl_khr_fp16' and 'cl_khr_fp64' OpenCL extensions are also +known to GDB. + + +File: gdb.info, Node: OpenCL C Expressions, Next: OpenCL C Operators, Prev: OpenCL C Datatypes, Up: OpenCL C + +15.4.5.2 OpenCL C Expressions +............................. + +GDB supports accesses to vector components including the access as +lvalue where possible. Since OpenCL C is based on C99 most C +expressions supported by GDB can be used as well. + + +File: gdb.info, Node: OpenCL C Operators, Prev: OpenCL C Expressions, Up: OpenCL C + +15.4.5.3 OpenCL C Operators +........................... + +GDB supports the operators specified by OpenCL 1.1 for scalar and vector +data types. + + +File: gdb.info, Node: Fortran, Next: Pascal, Prev: OpenCL C, Up: Supported Languages + +15.4.6 Fortran +-------------- + +GDB can be used to debug programs written in Fortran, but it currently +supports only the features of Fortran 77 language. + + Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers among +them) append an underscore to the names of variables and functions. +When you debug programs compiled by those compilers, you will need to +refer to variables and functions with a trailing underscore. + +* Menu: + +* Fortran Operators:: Fortran operators and expressions +* Fortran Defaults:: Default settings for Fortran +* Special Fortran Commands:: Special GDB commands for Fortran + + +File: gdb.info, Node: Fortran Operators, Next: Fortran Defaults, Up: Fortran + +15.4.6.1 Fortran Operators and Expressions +.......................................... + +Operators must be defined on values of specific types. For instance, +'+' is defined on numbers, but not on characters or other non- +arithmetic types. Operators are often defined on groups of types. + +'**' + The exponentiation operator. It raises the first operand to the + power of the second one. + +':' + The range operator. Normally used in the form of array(low:high) + to represent a section of array. + +'%' + The access component operator. Normally used to access elements in + derived types. Also suitable for unions. As unions aren't part of + regular Fortran, this can only happen when accessing a register + that uses a gdbarch-defined union type. + + +File: gdb.info, Node: Fortran Defaults, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran + +15.4.6.2 Fortran Defaults +......................... + +Fortran symbols are usually case-insensitive, so GDB by default uses +case-insensitive matches for Fortran symbols. You can change that with +the 'set case-insensitive' command, see *note Symbols::, for the +details. + + +File: gdb.info, Node: Special Fortran Commands, Prev: Fortran Defaults, Up: Fortran + +15.4.6.3 Special Fortran Commands +................................. + +GDB has some commands to support Fortran-specific features, such as +displaying common blocks. + +'info common [COMMON-NAME]' + This command prints the values contained in the Fortran 'COMMON' + block whose name is COMMON-NAME. With no argument, the names of + all 'COMMON' blocks visible at the current program location are + printed. + + +File: gdb.info, Node: Pascal, Next: Modula-2, Prev: Fortran, Up: Supported Languages + +15.4.7 Pascal +------------- + +Debugging Pascal programs which use sets, subranges, file variables, or +nested functions does not currently work. GDB does not support entering +expressions, printing values, or similar features using Pascal syntax. + + The Pascal-specific command 'set print pascal_static-members' +controls whether static members of Pascal objects are displayed. *Note +pascal_static-members: Print Settings. + + +File: gdb.info, Node: Modula-2, Next: Ada, Prev: Pascal, Up: Supported Languages + +15.4.8 Modula-2 +--------------- + +The extensions made to GDB to support Modula-2 only support output from +the GNU Modula-2 compiler (which is currently being developed). Other +Modula-2 compilers are not currently supported, and attempting to debug +executables produced by them is most likely to give an error as GDB +reads in the executable's symbol table. + +* Menu: + +* M2 Operators:: Built-in operators +* Built-In Func/Proc:: Built-in functions and procedures +* M2 Constants:: Modula-2 constants +* M2 Types:: Modula-2 types +* M2 Defaults:: Default settings for Modula-2 +* Deviations:: Deviations from standard Modula-2 +* M2 Checks:: Modula-2 type and range checks +* M2 Scope:: The scope operators '::' and '.' +* GDB/M2:: GDB and Modula-2 + + +File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 + +15.4.8.1 Operators +.................. + +Operators must be defined on values of specific types. For instance, +'+' is defined on numbers, but not on structures. Operators are often +defined on groups of types. For the purposes of Modula-2, the following +definitions hold: + + * _Integral types_ consist of 'INTEGER', 'CARDINAL', and their + subranges. + + * _Character types_ consist of 'CHAR' and its subranges. + + * _Floating-point types_ consist of 'REAL'. + + * _Pointer types_ consist of anything declared as 'POINTER TO TYPE'. + + * _Scalar types_ consist of all of the above. + + * _Set types_ consist of 'SET' and 'BITSET' types. + + * _Boolean types_ consist of 'BOOLEAN'. + +The following operators are supported, and appear in order of increasing +precedence: + +',' + Function argument or array index separator. + +':=' + Assignment. The value of VAR ':=' VALUE is VALUE. + +'<, >' + Less than, greater than on integral, floating-point, or enumerated + types. + +'<=, >=' + Less than or equal to, greater than or equal to on integral, + floating-point and enumerated types, or set inclusion on set types. + Same precedence as '<'. + +'=, <>, #' + Equality and two ways of expressing inequality, valid on scalar + types. Same precedence as '<'. In GDB scripts, only '<>' is + available for inequality, since '#' conflicts with the script + comment character. + +'IN' + Set membership. Defined on set types and the types of their + members. Same precedence as '<'. + +'OR' + Boolean disjunction. Defined on boolean types. + +'AND, &' + Boolean conjunction. Defined on boolean types. + +'@' + The GDB "artificial array" operator (*note Expressions: + Expressions.). + +'+, -' + Addition and subtraction on integral and floating-point types, or + union and difference on set types. + +'*' + Multiplication on integral and floating-point types, or set + intersection on set types. + +'/' + Division on floating-point types, or symmetric set difference on + set types. Same precedence as '*'. + +'DIV, MOD' + Integer division and remainder. Defined on integral types. Same + precedence as '*'. + +'-' + Negative. Defined on 'INTEGER' and 'REAL' data. + +'^' + Pointer dereferencing. Defined on pointer types. + +'NOT' + Boolean negation. Defined on boolean types. Same precedence as + '^'. + +'.' + 'RECORD' field selector. Defined on 'RECORD' data. Same + precedence as '^'. + +'[]' + Array indexing. Defined on 'ARRAY' data. Same precedence as '^'. + +'()' + Procedure argument list. Defined on 'PROCEDURE' objects. Same + precedence as '^'. + +'::, .' + GDB and Modula-2 scope operators. + + _Warning:_ Set expressions and their operations are not yet + supported, so GDB treats the use of the operator 'IN', or the use + of operators '+', '-', '*', '/', '=', , '<>', '#', '<=', and '>=' + on sets as an error. + + +File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 + +15.4.8.2 Built-in Functions and Procedures +.......................................... + +Modula-2 also makes available several built-in procedures and functions. +In describing these, the following metavariables are used: + +A + represents an 'ARRAY' variable. + +C + represents a 'CHAR' constant or variable. + +I + represents a variable or constant of integral type. + +M + represents an identifier that belongs to a set. Generally used in + the same function with the metavariable S. The type of S should be + 'SET OF MTYPE' (where MTYPE is the type of M). + +N + represents a variable or constant of integral or floating-point + type. + +R + represents a variable or constant of floating-point type. + +T + represents a type. + +V + represents a variable. + +X + represents a variable or constant of one of many types. See the + explanation of the function for details. + + All Modula-2 built-in procedures also return a result, described +below. + +'ABS(N)' + Returns the absolute value of N. + +'CAP(C)' + If C is a lower case letter, it returns its upper case equivalent, + otherwise it returns its argument. + +'CHR(I)' + Returns the character whose ordinal value is I. + +'DEC(V)' + Decrements the value in the variable V by one. Returns the new + value. + +'DEC(V,I)' + Decrements the value in the variable V by I. Returns the new + value. + +'EXCL(M,S)' + Removes the element M from the set S. Returns the new set. + +'FLOAT(I)' + Returns the floating point equivalent of the integer I. + +'HIGH(A)' + Returns the index of the last member of A. + +'INC(V)' + Increments the value in the variable V by one. Returns the new + value. + +'INC(V,I)' + Increments the value in the variable V by I. Returns the new + value. + +'INCL(M,S)' + Adds the element M to the set S if it is not already there. + Returns the new set. + +'MAX(T)' + Returns the maximum value of the type T. + +'MIN(T)' + Returns the minimum value of the type T. + +'ODD(I)' + Returns boolean TRUE if I is an odd number. + +'ORD(X)' + Returns the ordinal value of its argument. For example, the + ordinal value of a character is its ASCII value (on machines + supporting the ASCII character set). X must be of an ordered type, + which include integral, character and enumerated types. + +'SIZE(X)' + Returns the size of its argument. X can be a variable or a type. + +'TRUNC(R)' + Returns the integral part of R. + +'TSIZE(X)' + Returns the size of its argument. X can be a variable or a type. + +'VAL(T,I)' + Returns the member of the type T whose ordinal value is I. + + _Warning:_ Sets and their operations are not yet supported, so GDB + treats the use of procedures 'INCL' and 'EXCL' as an error. + + +File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2 + +15.4.8.3 Constants +.................. + +GDB allows you to express the constants of Modula-2 in the following +ways: + + * Integer constants are simply a sequence of digits. When used in an + expression, a constant is interpreted to be type-compatible with + the rest of the expression. Hexadecimal integers are specified by + a trailing 'H', and octal integers by a trailing 'B'. + + * Floating point constants appear as a sequence of digits, followed + by a decimal point and another sequence of digits. An optional + exponent can then be specified, in the form 'E[+|-]NNN', where + '[+|-]NNN' is the desired exponent. All of the digits of the + floating point constant must be valid decimal (base 10) digits. + + * Character constants consist of a single character enclosed by a + pair of like quotes, either single (''') or double ('"'). They may + also be expressed by their ordinal value (their ASCII value, + usually) followed by a 'C'. + + * String constants consist of a sequence of characters enclosed by a + pair of like quotes, either single (''') or double ('"'). Escape + sequences in the style of C are also allowed. *Note C and C++ + Constants: C Constants, for a brief explanation of escape + sequences. + + * Enumerated constants consist of an enumerated identifier. + + * Boolean constants consist of the identifiers 'TRUE' and 'FALSE'. + + * Pointer constants consist of integral values only. + + * Set constants are not yet supported. + + +File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2 + +15.4.8.4 Modula-2 Types +....................... + +Currently GDB can print the following data types in Modula-2 syntax: +array types, record types, set types, pointer types, procedure types, +enumerated types, subrange types and base types. You can also print the +contents of variables declared using these type. This section gives a +number of simple source code examples together with sample GDB sessions. + + The first example contains the following section of code: + + VAR + s: SET OF CHAR ; + r: [20..40] ; + +and you can request GDB to interrogate the type and value of 'r' and +'s'. + + (gdb) print s + {'A'..'C', 'Z'} + (gdb) ptype s + SET OF CHAR + (gdb) print r + 21 + (gdb) ptype r + [20..40] + +Likewise if your source code declares 's' as: + + VAR + s: SET ['A'..'Z'] ; + +then you may query the type of 's' by: + + (gdb) ptype s + type = SET ['A'..'Z'] + +Note that at present you cannot interactively manipulate set expressions +using the debugger. + + The following example shows how you might declare an array in +Modula-2 and how you can interact with GDB to print its type and +contents: + + VAR + s: ARRAY [-10..10] OF CHAR ; + + (gdb) ptype s + ARRAY [-10..10] OF CHAR + + Note that the array handling is not yet complete and although the +type is printed correctly, expression handling still assumes that all +arrays have a lower bound of zero and not '-10' as in the example above. + + Here are some more type related Modula-2 examples: + + TYPE + colour = (blue, red, yellow, green) ; + t = [blue..yellow] ; + VAR + s: t ; + BEGIN + s := blue ; + +The GDB interaction shows how you can query the data type and value of a +variable. + + (gdb) print s + $1 = blue + (gdb) ptype t + type = [blue..yellow] + +In this example a Modula-2 array is declared and its contents displayed. +Observe that the contents are written in the same way as their 'C' +counterparts. + + VAR + s: ARRAY [1..5] OF CARDINAL ; + BEGIN + s[1] := 1 ; + + (gdb) print s + $1 = {1, 0, 0, 0, 0} + (gdb) ptype s + type = ARRAY [1..5] OF CARDINAL + + The Modula-2 language interface to GDB also understands pointer types +as shown in this example: + + VAR + s: POINTER TO ARRAY [1..5] OF CARDINAL ; + BEGIN + NEW(s) ; + s^[1] := 1 ; + +and you can request that GDB describes the type of 's'. + + (gdb) ptype s + type = POINTER TO ARRAY [1..5] OF CARDINAL + + GDB handles compound types as we can see in this example. Here we +combine array types, record types, pointer types and subrange types: + + TYPE + foo = RECORD + f1: CARDINAL ; + f2: CHAR ; + f3: myarray ; + END ; + + myarray = ARRAY myrange OF CARDINAL ; + myrange = [-2..2] ; + VAR + s: POINTER TO ARRAY myrange OF foo ; + +and you can ask GDB to describe the type of 's' as shown below. + + (gdb) ptype s + type = POINTER TO ARRAY [-2..2] OF foo = RECORD + f1 : CARDINAL; + f2 : CHAR; + f3 : ARRAY [-2..2] OF CARDINAL; + END + + +File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2 + +15.4.8.5 Modula-2 Defaults +.......................... + +If type and range checking are set automatically by GDB, they both +default to 'on' whenever the working language changes to Modula-2. This +happens regardless of whether you or GDB selected the working language. + + If you allow GDB to set the language automatically, then entering +code compiled from a file whose name ends with '.mod' sets the working +language to Modula-2. *Note Having GDB Infer the Source Language: +Automatically, for further details. + + +File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 + +15.4.8.6 Deviations from Standard Modula-2 +.......................................... + +A few changes have been made to make Modula-2 programs easier to debug. +This is done primarily via loosening its type strictness: + + * Unlike in standard Modula-2, pointer constants can be formed by + integers. This allows you to modify pointer variables during + debugging. (In standard Modula-2, the actual address contained in + a pointer variable is hidden from you; it can only be modified + through direct assignment to another pointer variable or expression + that returned a pointer.) + + * C escape sequences can be used in strings and characters to + represent non-printable characters. GDB prints out strings with + these escape sequences embedded. Single non-printable characters + are printed using the 'CHR(NNN)' format. + + * The assignment operator (':=') returns the value of its right-hand + argument. + + * All built-in procedures both modify _and_ return their argument. + + +File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 + +15.4.8.7 Modula-2 Type and Range Checks +....................................... + + _Warning:_ in this release, GDB does not yet perform type or range + checking. + + GDB considers two Modula-2 variables type equivalent if: + + * They are of types that have been declared equivalent via a 'TYPE T1 + = T2' statement + + * They have been declared on the same line. (Note: This is true of + the GNU Modula-2 compiler, but it may not be true of other + compilers.) + + As long as type checking is enabled, any attempt to combine variables +whose types are not equivalent is an error. + + Range checking is done on all mathematical operations, assignment, +array index bounds, and all built-in functions and procedures. + + +File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 + +15.4.8.8 The Scope Operators '::' and '.' +......................................... + +There are a few subtle differences between the Modula-2 scope operator +('.') and the GDB scope operator ('::'). The two have similar syntax: + + + MODULE . ID + SCOPE :: ID + +where SCOPE is the name of a module or a procedure, MODULE the name of a +module, and ID is any declared identifier within your program, except +another module. + + Using the '::' operator makes GDB search the scope specified by SCOPE +for the identifier ID. If it is not found in the specified scope, then +GDB searches all scopes enclosing the one specified by SCOPE. + + Using the '.' operator makes GDB search the current scope for the +identifier specified by ID that was imported from the definition module +specified by MODULE. With this operator, it is an error if the +identifier ID was not imported from definition module MODULE, or if ID +is not an identifier in MODULE. + + +File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 + +15.4.8.9 GDB and Modula-2 +......................... + +Some GDB commands have little use when debugging Modula-2 programs. +Five subcommands of 'set print' and 'show print' apply specifically to C +and C++: 'vtbl', 'demangle', 'asm-demangle', 'object', and 'union'. The +first four apply to C++, and the last to the C 'union' type, which has +no direct analogue in Modula-2. + + The '@' operator (*note Expressions: Expressions.), while available +with any language, is not useful with Modula-2. Its intent is to aid +the debugging of "dynamic arrays", which cannot be created in Modula-2 +as they can in C or C++. However, because an address can be specified +by an integral constant, the construct '{TYPE}ADREXP' is still useful. + + In GDB scripts, the Modula-2 inequality operator '#' is interpreted +as the beginning of a comment. Use '<>' instead. + + +File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages + +15.4.9 Ada +---------- + +The extensions made to GDB for Ada only support output from the GNU Ada +(GNAT) compiler. Other Ada compilers are not currently supported, and +attempting to debug executables produced by them is most likely to be +difficult. + +* Menu: + +* Ada Mode Intro:: General remarks on the Ada syntax + and semantics supported by Ada mode + in GDB. +* Omissions from Ada:: Restrictions on the Ada expression syntax. +* Additions to Ada:: Extensions of the Ada expression syntax. +* Stopping Before Main Program:: Debugging the program during elaboration. +* Ada Exceptions:: Ada Exceptions +* Ada Tasks:: Listing and setting breakpoints in tasks. +* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files +* Ravenscar Profile:: Tasking Support when using the Ravenscar + Profile +* Ada Glitches:: Known peculiarities of Ada mode. + + +File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada + +15.4.9.1 Introduction +..................... + +The Ada mode of GDB supports a fairly large subset of Ada expression +syntax, with some extensions. The philosophy behind the design of this +subset is + + * That GDB should provide basic literals and access to operations for + arithmetic, dereferencing, field selection, indexing, and + subprogram calls, leaving more sophisticated computations to + subprograms written into the program (which therefore may be called + from GDB). + + * That type safety and strict adherence to Ada language restrictions + are not particularly important to the GDB user. + + * That brevity is important to the GDB user. + + Thus, for brevity, the debugger acts as if all names declared in +user-written packages are directly visible, even if they are not visible +according to Ada rules, thus making it unnecessary to fully qualify most +names with their packages, regardless of context. Where this causes +ambiguity, GDB asks the user's intent. + + The debugger will start in Ada mode if it detects an Ada main +program. As for other languages, it will enter Ada mode when stopped in +a program that was translated from an Ada source file. + + While in Ada mode, you may use '--' for comments. This is useful +mostly for documenting command files. The standard GDB comment ('#') +still works at the beginning of a line in Ada mode, but not in the +middle (to allow based literals). + + The debugger supports limited overloading. Given a subprogram call +in which the function symbol has multiple definitions, it will use the +number of actual parameters and some information about their types to +attempt to narrow the set of definitions. It also makes very limited +use of context, preferring procedures to functions in the context of the +'call' command, and functions to procedures elsewhere. + + +File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada + +15.4.9.2 Omissions from Ada +........................... + +Here are the notable omissions from the subset: + + * Only a subset of the attributes are supported: + + - 'First, 'Last, and 'Length on array objects (not on types and + subtypes). + + - 'Min and 'Max. + + - 'Pos and 'Val. + + - 'Tag. + + - 'Range on array objects (not subtypes), but only as the right + operand of the membership ('in') operator. + + - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT + extension). + + - 'Address. + + * The names in 'Characters.Latin_1' are not available and + concatenation is not implemented. Thus, escape characters in + strings are not currently available. + + * Equality tests ('=' and '/=') on arrays test for bitwise equality + of representations. They will generally work correctly for strings + and arrays whose elements have integer or enumeration types. They + may not work correctly for arrays whose element types have + user-defined equality, for arrays of real values (in particular, + IEEE-conformant floating point, because of negative zeroes and + NaNs), and for arrays whose elements contain unused bits with + indeterminate values. + + * The other component-by-component array operations ('and', 'or', + 'xor', 'not', and relational tests other than equality) are not + implemented. + + * There is limited support for array and record aggregates. They are + permitted only on the right sides of assignments, as in these + examples: + + (gdb) set An_Array := (1, 2, 3, 4, 5, 6) + (gdb) set An_Array := (1, others => 0) + (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) + (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) + (gdb) set A_Record := (1, "Peter", True); + (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True) + + Changing a discriminant's value by assigning an aggregate has an + undefined effect if that discriminant is used within the record. + However, you can first modify discriminants by directly assigning + to them (which normally would not be allowed in Ada), and then + performing an aggregate assignment. For example, given a variable + 'A_Rec' declared to have a type such as: + + type Rec (Len : Small_Integer := 0) is record + Id : Integer; + Vals : IntArray (1 .. Len); + end record; + + you can assign a value with a different size of 'Vals' with two + assignments: + + (gdb) set A_Rec.Len := 4 + (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) + + As this example also illustrates, GDB is very loose about the usual + rules concerning aggregates. You may leave out some of the + components of an array or record aggregate (such as the 'Len' + component in the assignment to 'A_Rec' above); they will retain + their original values upon assignment. You may freely use dynamic + values as indices in component associations. You may even use + overlapping or redundant component associations, although which + component values are assigned in such cases is not defined. + + * Calls to dispatching subprograms are not implemented. + + * The overloading algorithm is much more limited (i.e., less + selective) than that of real Ada. It makes only limited use of the + context in which a subexpression appears to resolve its meaning, + and it is much looser in its rules for allowing type matches. As a + result, some function calls will be ambiguous, and the user will be + asked to choose the proper resolution. + + * The 'new' operator is not implemented. + + * Entry calls are not implemented. + + * Aside from printing, arithmetic operations on the native VAX + floating-point formats are not supported. + + * It is not possible to slice a packed array. + + * The names 'True' and 'False', when not part of a qualified name, + are interpreted as if implicitly prefixed by 'Standard', regardless + of context. Should your program redefine these names in a package + or procedure (at best a dubious practice), you will have to use + fully qualified names to access their new definitions. + + +File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada + +15.4.9.3 Additions to Ada +......................... + +As it does for other languages, GDB makes certain generic extensions to +Ada (*note Expressions::): + + * If the expression E is a variable residing in memory (typically a + local variable or array element) and N is a positive integer, then + 'E@N' displays the values of E and the N-1 adjacent variables + following it in memory as an array. In Ada, this operator is + generally not necessary, since its prime use is in displaying parts + of an array, and slicing will usually do this in Ada. However, + there are occasional uses when debugging programs in which certain + debugging information has been optimized away. + + * 'B::VAR' means "the variable named VAR that appears in function or + file B." When B is a file name, you must typically surround it in + single quotes. + + * The expression '{TYPE} ADDR' means "the variable of type TYPE that + appears at address ADDR." + + * A name starting with '$' is a convenience variable (*note + Convenience Vars::) or a machine register (*note Registers::). + + In addition, GDB provides a few other shortcuts and outright +additions specific to Ada: + + * The assignment statement is allowed as an expression, returning its + right-hand operand as its value. Thus, you may enter + + (gdb) set x := y + 3 + (gdb) print A(tmp := y + 1) + + * The semicolon is allowed as an "operator," returning as its value + the value of its right-hand operand. This allows, for example, + complex conditional breaks: + + (gdb) break f + (gdb) condition 1 (report(i); k += 1; A(k) > 100) + + * Rather than use catenation and symbolic character names to + introduce special characters into strings, one may instead use a + special bracket notation, which is also used to print strings. A + sequence of characters of the form '["XX"]' within a string or + character literal denotes the (single) character whose numeric + encoding is XX in hexadecimal. The sequence of characters '["""]' + also denotes a single quotation mark in strings. For example, + "One line.["0a"]Next line.["0a"]" + contains an ASCII newline character ('Ada.Characters.Latin_1.LF') + after each period. + + * The subtype used as a prefix for the attributes 'Pos, 'Min, and + 'Max is optional (and is ignored in any case). For example, it is + valid to write + + (gdb) print 'max(x, y) + + * When printing arrays, GDB uses positional notation when the array + has a lower bound of 1, and uses a modified named notation + otherwise. For example, a one-dimensional array of three integers + with a lower bound of 3 might print as + + (3 => 10, 17, 1) + + That is, in contrast to valid Ada, only the first component has a + '=>' clause. + + * You may abbreviate attributes in expressions with any unique, + multi-character subsequence of their names (an exact match gets + preference). For example, you may use a'len, a'gth, or a'lh in + place of a'length. + + * Since Ada is case-insensitive, the debugger normally maps + identifiers you type to lower case. The GNAT compiler uses + upper-case characters for some of its internal identifiers, which + are normally of no interest to users. For the rare occasions when + you actually have to look at them, enclose them in angle brackets + to avoid the lower-case mapping. For example, + (gdb) print [0] + + * Printing an object of class-wide type or dereferencing an + access-to-class-wide value will display all the components of the + object's specific type (as indicated by its run-time tag). + Likewise, component selection on such a value will operate on the + specific type of the object. + + +File: gdb.info, Node: Stopping Before Main Program, Next: Ada Exceptions, Prev: Additions to Ada, Up: Ada + +15.4.9.4 Stopping at the Very Beginning +....................................... + +It is sometimes necessary to debug the program during elaboration, and +before reaching the main procedure. As defined in the Ada Reference +Manual, the elaboration code is invoked from a procedure called +'adainit'. To run your program up to the beginning of elaboration, +simply use the following two commands: 'tbreak adainit' and 'run'. + + +File: gdb.info, Node: Ada Exceptions, Next: Ada Tasks, Prev: Stopping Before Main Program, Up: Ada + +15.4.9.5 Ada Exceptions +....................... + +A command is provided to list all Ada exceptions: + +'info exceptions' +'info exceptions REGEXP' + The 'info exceptions' command allows you to list all Ada exceptions + defined within the program being debugged, as well as their + addresses. With a regular expression, REGEXP, as argument, only + those exceptions whose names match REGEXP are listed. + + Below is a small example, showing how the command can be used, first +without argument, and next with a regular expression passed as an +argument. + + (gdb) info exceptions + All defined Ada exceptions: + constraint_error: 0x613da0 + program_error: 0x613d20 + storage_error: 0x613ce0 + tasking_error: 0x613ca0 + const.aint_global_e: 0x613b00 + (gdb) info exceptions const.aint + All Ada exceptions matching regular expression "const.aint": + constraint_error: 0x613da0 + const.aint_global_e: 0x613b00 + + It is also possible to ask GDB to stop your program's execution when +an exception is raised. For more details, see *note Set Catchpoints::. + + +File: gdb.info, Node: Ada Tasks, Next: Ada Tasks and Core Files, Prev: Ada Exceptions, Up: Ada + +15.4.9.6 Extensions for Ada Tasks +................................. + +Support for Ada tasks is analogous to that for threads (*note +Threads::). GDB provides the following task-related commands: + +'info tasks' + This command shows a list of current Ada tasks, as in the following + example: + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8088000 0 15 Child Activation Wait main_task + 2 80a4000 1 15 Accept Statement b + 3 809a800 1 15 Child Activation Wait a + * 4 80ae800 3 15 Runnable c + + In this listing, the asterisk before the last task indicates it to + be the task currently being inspected. + + ID + Represents GDB's internal task number. + + TID + The Ada task ID. + + P-ID + The parent's task ID (GDB's internal task number). + + Pri + The base priority of the task. + + State + Current state of the task. + + 'Unactivated' + The task has been created but has not been activated. It + cannot be executing. + + 'Runnable' + The task is not blocked for any reason known to Ada. (It + may be waiting for a mutex, though.) It is conceptually + "executing" in normal mode. + + 'Terminated' + The task is terminated, in the sense of ARM 9.3 (5). Any + dependents that were waiting on terminate alternatives + have been awakened and have terminated themselves. + + 'Child Activation Wait' + The task is waiting for created tasks to complete + activation. + + 'Accept Statement' + The task is waiting on an accept or selective wait + statement. + + 'Waiting on entry call' + The task is waiting on an entry call. + + 'Async Select Wait' + The task is waiting to start the abortable part of an + asynchronous select statement. + + 'Delay Sleep' + The task is waiting on a select statement with only a + delay alternative open. + + 'Child Termination Wait' + The task is sleeping having completed a master within + itself, and is waiting for the tasks dependent on that + master to become terminated or waiting on a terminate + Phase. + + 'Wait Child in Term Alt' + The task is sleeping waiting for tasks on terminate + alternatives to finish terminating. + + 'Accepting RV with TASKNO' + The task is accepting a rendez-vous with the task TASKNO. + + Name + Name of the task in the program. + +'info task TASKNO' + This command shows detailled informations on the specified task, as + in the following example: + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8077880 0 15 Child Activation Wait main_task + * 2 807c468 1 15 Runnable task_1 + (gdb) info task 2 + Ada Task: 0x807c468 + Name: task_1 + Thread: 0x807f378 + Parent: 1 (main_task) + Base Priority: 15 + State: Runnable + +'task' + This command prints the ID of the current task. + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8077870 0 15 Child Activation Wait main_task + * 2 807c458 1 15 Runnable t + (gdb) task + [Current task is 2] + +'task TASKNO' + This command is like the 'thread THREADNO' command (*note + Threads::). It switches the context of debugging from the current + task to the given task. + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8077870 0 15 Child Activation Wait main_task + * 2 807c458 1 15 Runnable t + (gdb) task 1 + [Switching to task 1] + #0 0x8067726 in pthread_cond_wait () + (gdb) bt + #0 0x8067726 in pthread_cond_wait () + #1 0x8056714 in system.os_interface.pthread_cond_wait () + #2 0x805cb63 in system.task_primitives.operations.sleep () + #3 0x806153e in system.tasking.stages.activate_tasks () + #4 0x804aacc in un () at un.adb:5 + +'break LINESPEC task TASKNO' +'break LINESPEC task TASKNO if ...' + These commands are like the 'break ... thread ...' command (*note + Thread Stops::). LINESPEC specifies source lines, as described in + *note Specify Location::. + + Use the qualifier 'task TASKNO' with a breakpoint command to + specify that you only want GDB to stop the program when a + particular Ada task reaches this breakpoint. TASKNO is one of the + numeric task identifiers assigned by GDB, shown in the first column + of the 'info tasks' display. + + If you do not specify 'task TASKNO' when you set a breakpoint, the + breakpoint applies to _all_ tasks of your program. + + You can use the 'task' qualifier on conditional breakpoints as + well; in this case, place 'task TASKNO' before the breakpoint + condition (before the 'if'). + + For example, + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 140022020 0 15 Child Activation Wait main_task + 2 140045060 1 15 Accept/Select Wait t2 + 3 140044840 1 15 Runnable t1 + * 4 140056040 1 15 Runnable t3 + (gdb) b 15 task 2 + Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. + (gdb) cont + Continuing. + task # 1 running + task # 2 running + + Breakpoint 5, test_task_debug () at test_task_debug.adb:15 + 15 flush; + (gdb) info tasks + ID TID P-ID Pri State Name + 1 140022020 0 15 Child Activation Wait main_task + * 2 140045060 1 15 Runnable t2 + 3 140044840 1 15 Runnable t1 + 4 140056040 1 15 Delay Sleep t3 + + +File: gdb.info, Node: Ada Tasks and Core Files, Next: Ravenscar Profile, Prev: Ada Tasks, Up: Ada + +15.4.9.7 Tasking Support when Debugging Core Files +.................................................. + +When inspecting a core file, as opposed to debugging a live program, +tasking support may be limited or even unavailable, depending on the +platform being used. For instance, on x86-linux, the list of tasks is +available, but task switching is not supported. On Tru64, however, task +switching will work as usual. + + On certain platforms, including Tru64, the debugger needs to perform +some memory writes in order to provide Ada tasking support. When +inspecting a core file, this means that the core file must be opened +with read-write privileges, using the command '"set write on"' (*note +Patching::). Under these circumstances, you should make a backup copy +of the core file before inspecting it with GDB. + + +File: gdb.info, Node: Ravenscar Profile, Next: Ada Glitches, Prev: Ada Tasks and Core Files, Up: Ada + +15.4.9.8 Tasking Support when using the Ravenscar Profile +......................................................... + +The "Ravenscar Profile" is a subset of the Ada tasking features, +specifically designed for systems with safety-critical real-time +requirements. + +'set ravenscar task-switching on' + Allows task switching when debugging a program that uses the + Ravenscar Profile. This is the default. + +'set ravenscar task-switching off' + Turn off task switching when debugging a program that uses the + Ravenscar Profile. This is mostly intended to disable the code + that adds support for the Ravenscar Profile, in case a bug in + either GDB or in the Ravenscar runtime is preventing GDB from + working properly. To be effective, this command should be run + before the program is started. + +'show ravenscar task-switching' + Show whether it is possible to switch from task to task in a + program using the Ravenscar Profile. + + +File: gdb.info, Node: Ada Glitches, Prev: Ravenscar Profile, Up: Ada + +15.4.9.9 Known Peculiarities of Ada Mode +........................................ + +Besides the omissions listed previously (*note Omissions from Ada::), we +know of several problems with and limitations of Ada mode in GDB, some +of which will be fixed with planned future releases of the debugger and +the GNU Ada compiler. + + * Static constants that the compiler chooses not to materialize as + objects in storage are invisible to the debugger. + + * Named parameter associations in function argument lists are ignored + (the argument lists are treated as positional). + + * Many useful library packages are currently invisible to the + debugger. + + * Fixed-point arithmetic, conversions, input, and output is carried + out using floating-point arithmetic, and may give results that only + approximate those on the host machine. + + * The GNAT compiler never generates the prefix 'Standard' for any of + the standard symbols defined by the Ada language. GDB knows about + this: it will strip the prefix from names when you use it, and will + never look for a name you have so qualified among local symbols, + nor match against symbols in other packages or subprograms. If you + have defined entities anywhere in your program other than + parameters and local variables whose simple names match names in + 'Standard', GNAT's lack of qualification here can cause confusion. + When this happens, you can usually resolve the confusion by + qualifying the problematic names with package 'Standard' + explicitly. + + Older versions of the compiler sometimes generate erroneous debugging +information, resulting in the debugger incorrectly printing the value of +affected entities. In some cases, the debugger is able to work around +an issue automatically. In other cases, the debugger is able to work +around the issue, but the work-around has to be specifically enabled. + +'set ada trust-PAD-over-XVS on' + Configure GDB to strictly follow the GNAT encoding when computing + the value of Ada entities, particularly when 'PAD' and 'PAD___XVS' + types are involved (see 'ada/exp_dbug.ads' in the GCC sources for a + complete description of the encoding used by the GNAT compiler). + This is the default. + +'set ada trust-PAD-over-XVS off' + This is related to the encoding using by the GNAT compiler. If GDB + sometimes prints the wrong value for certain entities, changing + 'ada trust-PAD-over-XVS' to 'off' activates a work-around which may + fix the issue. It is always safe to set 'ada trust-PAD-over-XVS' + to 'off', but this incurs a slight performance penalty, so it is + recommended to leave this setting to 'on' unless necessary. + + +File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages + +15.5 Unsupported Languages +========================== + +In addition to the other fully-supported programming languages, GDB also +provides a pseudo-language, called 'minimal'. It does not represent a +real programming language, but provides a set of capabilities close to +what the C or assembly languages provide. This should allow most simple +operations to be performed while debugging an application that uses a +language currently not supported by GDB. + + If the language is set to 'auto', GDB will automatically select this +language if the current frame corresponds to an unsupported language. + + +File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top + +16 Examining the Symbol Table +***************************** + +The commands described in this chapter allow you to inquire about the +symbols (names of variables, functions and types) defined in your +program. This information is inherent in the text of your program and +does not change as your program executes. GDB finds it in your +program's symbol table, in the file indicated when you started GDB +(*note Choosing Files: File Options.), or by one of the file-management +commands (*note Commands to Specify Files: Files.). + + Occasionally, you may need to refer to symbols that contain unusual +characters, which GDB ordinarily treats as word delimiters. The most +frequent case is in referring to static variables in other source files +(*note Program Variables: Variables.). File names are recorded in +object files as debugging symbols, but GDB would ordinarily parse a +typical file name, like 'foo.c', as the three words 'foo' '.' 'c'. To +allow GDB to recognize 'foo.c' as a single symbol, enclose it in single +quotes; for example, + + p 'foo.c'::x + +looks up the value of 'x' in the scope of the file 'foo.c'. + +'set case-sensitive on' +'set case-sensitive off' +'set case-sensitive auto' + Normally, when GDB looks up symbols, it matches their names with + case sensitivity determined by the current source language. + Occasionally, you may wish to control that. The command 'set + case-sensitive' lets you do that by specifying 'on' for + case-sensitive matches or 'off' for case-insensitive ones. If you + specify 'auto', case sensitivity is reset to the default suitable + for the source language. The default is case-sensitive matches for + all languages except for Fortran, for which the default is + case-insensitive matches. + +'show case-sensitive' + This command shows the current setting of case sensitivity for + symbols lookups. + +'set print type methods' +'set print type methods on' +'set print type methods off' + Normally, when GDB prints a class, it displays any methods declared + in that class. You can control this behavior either by passing the + appropriate flag to 'ptype', or using 'set print type methods'. + Specifying 'on' will cause GDB to display the methods; this is the + default. Specifying 'off' will cause GDB to omit the methods. + +'show print type methods' + This command shows the current setting of method display when + printing classes. + +'set print type typedefs' +'set print type typedefs on' +'set print type typedefs off' + + Normally, when GDB prints a class, it displays any typedefs defined + in that class. You can control this behavior either by passing the + appropriate flag to 'ptype', or using 'set print type typedefs'. + Specifying 'on' will cause GDB to display the typedef definitions; + this is the default. Specifying 'off' will cause GDB to omit the + typedef definitions. Note that this controls whether the typedef + definition itself is printed, not whether typedef names are + substituted when printing other types. + +'show print type typedefs' + This command shows the current setting of typedef display when + printing classes. + +'info address SYMBOL' + Describe where the data for SYMBOL is stored. For a register + variable, this says which register it is kept in. For a + non-register local variable, this prints the stack-frame offset at + which the variable is always stored. + + Note the contrast with 'print &SYMBOL', which does not work at all + for a register variable, and for a stack local variable prints the + exact address of the current instantiation of the variable. + +'info symbol ADDR' + Print the name of a symbol which is stored at the address ADDR. If + no symbol is stored exactly at ADDR, GDB prints the nearest symbol + and an offset from it: + + (gdb) info symbol 0x54320 + _initialize_vx + 396 in section .text + + This is the opposite of the 'info address' command. You can use it + to find out the name of a variable or a function given its address. + + For dynamically linked executables, the name of executable or + shared library containing the symbol is also printed: + + (gdb) info symbol 0x400225 + _start + 5 in section .text of /tmp/a.out + (gdb) info symbol 0x2aaaac2811cf + __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 + +'whatis[/FLAGS] [ARG]' + Print the data type of ARG, which can be either an expression or a + name of a data type. With no argument, print the data type of '$', + the last value in the value history. + + If ARG is an expression (*note Expressions: Expressions.), it is + not actually evaluated, and any side-effecting operations (such as + assignments or function calls) inside it do not take place. + + If ARG is a variable or an expression, 'whatis' prints its literal + type as it is used in the source code. If the type was defined + using a 'typedef', 'whatis' will _not_ print the data type + underlying the 'typedef'. If the type of the variable or the + expression is a compound data type, such as 'struct' or 'class', + 'whatis' never prints their fields or methods. It just prints the + 'struct'/'class' name (a.k.a. its "tag"). If you want to see the + members of such a compound data type, use 'ptype'. + + If ARG is a type name that was defined using 'typedef', 'whatis' + "unrolls" only one level of that 'typedef'. Unrolling means that + 'whatis' will show the underlying type used in the 'typedef' + declaration of ARG. However, if that underlying type is also a + 'typedef', 'whatis' will not unroll it. + + For C code, the type names may also have the form 'class + CLASS-NAME', 'struct STRUCT-TAG', 'union UNION-TAG' or 'enum + ENUM-TAG'. + + FLAGS can be used to modify how the type is displayed. Available + flags are: + + 'r' + Display in "raw" form. Normally, GDB substitutes template + parameters and typedefs defined in a class when printing the + class' members. The '/r' flag disables this. + + 'm' + Do not print methods defined in the class. + + 'M' + Print methods defined in the class. This is the default, but + the flag exists in case you change the default with 'set print + type methods'. + + 't' + Do not print typedefs defined in the class. Note that this + controls whether the typedef definition itself is printed, not + whether typedef names are substituted when printing other + types. + + 'T' + Print typedefs defined in the class. This is the default, but + the flag exists in case you change the default with 'set print + type typedefs'. + +'ptype[/FLAGS] [ARG]' + 'ptype' accepts the same arguments as 'whatis', but prints a + detailed description of the type, instead of just the name of the + type. *Note Expressions: Expressions. + + Contrary to 'whatis', 'ptype' always unrolls any 'typedef's in its + argument declaration, whether the argument is a variable, + expression, or a data type. This means that 'ptype' of a variable + or an expression will not print literally its type as present in + the source code--use 'whatis' for that. 'typedef's at the pointer + or reference targets are also unrolled. Only 'typedef's of fields, + methods and inner 'class typedef's of 'struct's, 'class'es and + 'union's are not unrolled even with 'ptype'. + + For example, for this variable declaration: + + typedef double real_t; + struct complex { real_t real; double imag; }; + typedef struct complex complex_t; + complex_t var; + real_t *real_pointer_var; + + the two commands give this output: + + (gdb) whatis var + type = complex_t + (gdb) ptype var + type = struct complex { + real_t real; + double imag; + } + (gdb) whatis complex_t + type = struct complex + (gdb) whatis struct complex + type = struct complex + (gdb) ptype struct complex + type = struct complex { + real_t real; + double imag; + } + (gdb) whatis real_pointer_var + type = real_t * + (gdb) ptype real_pointer_var + type = double * + + As with 'whatis', using 'ptype' without an argument refers to the + type of '$', the last value in the value history. + + Sometimes, programs use opaque data types or incomplete + specifications of complex data structure. If the debug information + included in the program does not allow GDB to display a full + declaration of the data type, it will say ''. For + example, given these declarations: + + struct foo; + struct foo *fooptr; + + but no definition for 'struct foo' itself, GDB will say: + + (gdb) ptype foo + $1 = + + "Incomplete type" is C terminology for data types that are not + completely specified. + +'info types REGEXP' +'info types' + Print a brief description of all types whose names match the + regular expression REGEXP (or all types in your program, if you + supply no argument). Each complete typename is matched as though + it were a complete line; thus, 'i type value' gives information on + all types in your program whose names include the string 'value', + but 'i type ^value$' gives information only on types whose complete + name is 'value'. + + This command differs from 'ptype' in two ways: first, like + 'whatis', it does not print a detailed description; second, it + lists all source files where a type is defined. + +'info type-printers' + Versions of GDB that ship with Python scripting enabled may have + "type printers" available. When using 'ptype' or 'whatis', these + printers are consulted when the name of a type is needed. *Note + Type Printing API::, for more information on writing type printers. + + 'info type-printers' displays all the available type printers. + +'enable type-printer NAME...' +'disable type-printer NAME...' + These commands can be used to enable or disable type printers. + +'info scope LOCATION' + List all the variables local to a particular scope. This command + accepts a LOCATION argument--a function name, a source line, or an + address preceded by a '*', and prints all the variables local to + the scope defined by that location. (*Note Specify Location::, for + details about supported forms of LOCATION.) For example: + + (gdb) info scope command_line_handler + Scope for command_line_handler: + Symbol rl is an argument at stack/frame offset 8, length 4. + Symbol linebuffer is in static storage at address 0x150a18, length 4. + Symbol linelength is in static storage at address 0x150a1c, length 4. + Symbol p is a local variable in register $esi, length 4. + Symbol p1 is a local variable in register $ebx, length 4. + Symbol nline is a local variable in register $edx, length 4. + Symbol repeat is a local variable at frame offset -8, length 4. + + This command is especially useful for determining what data to + collect during a "trace experiment", see *note collect: Tracepoint + Actions. + +'info source' + Show information about the current source file--that is, the source + file for the function containing the current point of execution: + * the name of the source file, and the directory containing it, + * the directory it was compiled in, + * its length, in lines, + * which programming language it is written in, + * whether the executable includes debugging information for that + file, and if so, what format the information is in (e.g., + STABS, Dwarf 2, etc.), and + * whether the debugging information includes information about + preprocessor macros. + +'info sources' + Print the names of all source files in your program for which there + is debugging information, organized into two lists: files whose + symbols have already been read, and files whose symbols will be + read when needed. + +'info functions' + Print the names and data types of all defined functions. + +'info functions REGEXP' + Print the names and data types of all defined functions whose names + contain a match for regular expression REGEXP. Thus, 'info fun + step' finds all functions whose names include 'step'; 'info fun + ^step' finds those whose names start with 'step'. If a function + name contains characters that conflict with the regular expression + language (e.g. 'operator*()'), they may be quoted with a backslash. + +'info variables' + Print the names and data types of all variables that are defined + outside of functions (i.e. excluding local variables). + +'info variables REGEXP' + Print the names and data types of all variables (except for local + variables) whose names contain a match for regular expression + REGEXP. + +'info classes' +'info classes REGEXP' + Display all Objective-C classes in your program, or (with the + REGEXP argument) all those matching a particular regular + expression. + +'info selectors' +'info selectors REGEXP' + Display all Objective-C selectors in your program, or (with the + REGEXP argument) all those matching a particular regular + expression. + +'set opaque-type-resolution on' + Tell GDB to resolve opaque types. An opaque type is a type + declared as a pointer to a 'struct', 'class', or 'union'--for + example, 'struct MyType *'--that is used in one source file + although the full declaration of 'struct MyType' is in another + source file. The default is on. + + A change in the setting of this subcommand will not take effect + until the next time symbols for a file are loaded. + +'set opaque-type-resolution off' + Tell GDB not to resolve opaque types. In this case, the type is + printed as follows: + {} + +'show opaque-type-resolution' + Show whether opaque types are resolved or not. + +'maint print symbols FILENAME' +'maint print psymbols FILENAME' +'maint print msymbols FILENAME' + Write a dump of debugging symbol data into the file FILENAME. + These commands are used to debug the GDB symbol-reading code. Only + symbols with debugging data are included. If you use 'maint print + symbols', GDB includes all the symbols for which it has already + collected full details: that is, FILENAME reflects symbols for only + those files whose symbols GDB has read. You can use the command + 'info sources' to find out which files these are. If you use + 'maint print psymbols' instead, the dump shows information about + symbols that GDB only knows partially--that is, symbols defined in + files that GDB has skimmed, but not yet read completely. Finally, + 'maint print msymbols' dumps just the minimal symbol information + required for each object file from which GDB has read some symbols. + *Note Commands to Specify Files: Files, for a discussion of how GDB + reads symbols (in the description of 'symbol-file'). + +'maint info symtabs [ REGEXP ]' +'maint info psymtabs [ REGEXP ]' + + List the 'struct symtab' or 'struct partial_symtab' structures + whose names match REGEXP. If REGEXP is not given, list them all. + The output includes expressions which you can copy into a GDB + debugging this one to examine a particular structure in more + detail. For example: + + (gdb) maint info psymtabs dwarf2read + { objfile /home/gnu/build/gdb/gdb + ((struct objfile *) 0x82e69d0) + { psymtab /home/gnu/src/gdb/dwarf2read.c + ((struct partial_symtab *) 0x8474b10) + readin no + fullname (null) + text addresses 0x814d3c8 -- 0x8158074 + globals (* (struct partial_symbol **) 0x8507a08 @ 9) + statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) + dependencies (none) + } + } + (gdb) maint info symtabs + (gdb) + We see that there is one partial symbol table whose filename + contains the string 'dwarf2read', belonging to the 'gdb' + executable; and we see that GDB has not read in any symtabs yet at + all. If we set a breakpoint on a function, that will cause GDB to + read the symtab for the compilation unit containing that function: + + (gdb) break dwarf2_psymtab_to_symtab + Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, + line 1574. + (gdb) maint info symtabs + { objfile /home/gnu/build/gdb/gdb + ((struct objfile *) 0x82e69d0) + { symtab /home/gnu/src/gdb/dwarf2read.c + ((struct symtab *) 0x86c1f38) + dirname (null) + fullname (null) + blockvector ((struct blockvector *) 0x86c1bd0) (primary) + linetable ((struct linetable *) 0x8370fa0) + debugformat DWARF 2 + } + } + (gdb) + + +File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top + +17 Altering Execution +********************* + +Once you think you have found an error in your program, you might want +to find out for certain whether correcting the apparent error would lead +to correct results in the rest of the run. You can find the answer by +experiment, using the GDB features for altering execution of the +program. + + For example, you can store new values into variables or memory +locations, give your program a signal, restart it at a different +address, or even return prematurely from a function. + +* Menu: + +* Assignment:: Assignment to variables +* Jumping:: Continuing at a different address +* Signaling:: Giving your program a signal +* Returning:: Returning from a function +* Calling:: Calling your program's functions +* Patching:: Patching your program + + +File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering + +17.1 Assignment to Variables +============================ + +To alter the value of a variable, evaluate an assignment expression. +*Note Expressions: Expressions. For example, + + print x=4 + +stores the value 4 into the variable 'x', and then prints the value of +the assignment expression (which is 4). *Note Using GDB with Different +Languages: Languages, for more information on operators in supported +languages. + + If you are not interested in seeing the value of the assignment, use +the 'set' command instead of the 'print' command. 'set' is really the +same as 'print' except that the expression's value is not printed and is +not put in the value history (*note Value History: Value History.). The +expression is evaluated only for its effects. + + If the beginning of the argument string of the 'set' command appears +identical to a 'set' subcommand, use the 'set variable' command instead +of just 'set'. This command is identical to 'set' except for its lack +of subcommands. For example, if your program has a variable 'width', +you get an error if you try to set a new value with just 'set width=13', +because GDB has the command 'set width': + + (gdb) whatis width + type = double + (gdb) p width + $4 = 13 + (gdb) set width=47 + Invalid syntax in expression. + +The invalid expression, of course, is '=47'. In order to actually set +the program's variable 'width', use + + (gdb) set var width=47 + + Because the 'set' command has many subcommands that can conflict with +the names of program variables, it is a good idea to use the 'set +variable' command instead of just 'set'. For example, if your program +has a variable 'g', you run into problems if you try to set a new value +with just 'set g=4', because GDB has the command 'set gnutarget', +abbreviated 'set g': + + (gdb) whatis g + type = double + (gdb) p g + $1 = 1 + (gdb) set g=4 + (gdb) p g + $2 = 1 + (gdb) r + The program being debugged has been started already. + Start it from the beginning? (y or n) y + Starting program: /home/smith/cc_progs/a.out + "/home/smith/cc_progs/a.out": can't open to read symbols: + Invalid bfd target. + (gdb) show g + The current BFD target is "=4". + +The program variable 'g' did not change, and you silently set the +'gnutarget' to an invalid value. In order to set the variable 'g', use + + (gdb) set var g=4 + + GDB allows more implicit conversions in assignments than C; you can +freely store an integer value into a pointer variable or vice versa, and +you can convert any structure to any other structure that is the same +length or shorter. + + To store values into arbitrary places in memory, use the '{...}' +construct to generate a value of specified type at a specified address +(*note Expressions: Expressions.). For example, '{int}0x83040' refers +to memory location '0x83040' as an integer (which implies a certain size +and representation in memory), and + + set {int}0x83040 = 4 + +stores the value 4 into that memory location. + + +File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering + +17.2 Continuing at a Different Address +====================================== + +Ordinarily, when you continue your program, you do so at the place where +it stopped, with the 'continue' command. You can instead continue at an +address of your own choosing, with the following commands: + +'jump LINESPEC' +'j LINESPEC' +'jump LOCATION' +'j LOCATION' + Resume execution at line LINESPEC or at address given by LOCATION. + Execution stops again immediately if there is a breakpoint there. + *Note Specify Location::, for a description of the different forms + of LINESPEC and LOCATION. It is common practice to use the + 'tbreak' command in conjunction with 'jump'. *Note Setting + Breakpoints: Set Breaks. + + The 'jump' command does not change the current stack frame, or the + stack pointer, or the contents of any memory location or any + register other than the program counter. If line LINESPEC is in a + different function from the one currently executing, the results + may be bizarre if the two functions expect different patterns of + arguments or of local variables. For this reason, the 'jump' + command requests confirmation if the specified line is not in the + function currently executing. However, even bizarre results are + predictable if you are well acquainted with the machine-language + code of your program. + + On many systems, you can get much the same effect as the 'jump' +command by storing a new value into the register '$pc'. The difference +is that this does not start your program running; it only changes the +address of where it _will_ run when you continue. For example, + + set $pc = 0x485 + +makes the next 'continue' command or stepping command execute at address +'0x485', rather than at the address where your program stopped. *Note +Continuing and Stepping: Continuing and Stepping. + + The most common occasion to use the 'jump' command is to back +up--perhaps with more breakpoints set--over a portion of a program that +has already executed, in order to examine its execution in more detail. + + +File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering + +17.3 Giving your Program a Signal +================================= + +'signal SIGNAL' + Resume execution where your program stopped, but immediately give + it the signal SIGNAL. SIGNAL can be the name or the number of a + signal. For example, on many systems 'signal 2' and 'signal + SIGINT' are both ways of sending an interrupt signal. + + Alternatively, if SIGNAL is zero, continue execution without giving + a signal. This is useful when your program stopped on account of a + signal and would ordinarily see the signal when resumed with the + 'continue' command; 'signal 0' causes it to resume without a + signal. + + 'signal' does not repeat when you press a second time after + executing the command. + + Invoking the 'signal' command is not the same as invoking the 'kill' +utility from the shell. Sending a signal with 'kill' causes GDB to +decide what to do with the signal depending on the signal handling +tables (*note Signals::). The 'signal' command passes the signal +directly to your program. + + +File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering + +17.4 Returning from a Function +============================== + +'return' +'return EXPRESSION' + You can cancel execution of a function call with the 'return' + command. If you give an EXPRESSION argument, its value is used as + the function's return value. + + When you use 'return', GDB discards the selected stack frame (and all +frames within it). You can think of this as making the discarded frame +return prematurely. If you wish to specify a value to be returned, give +that value as the argument to 'return'. + + This pops the selected stack frame (*note Selecting a Frame: +Selection.), and any other frames inside of it, leaving its caller as +the innermost remaining frame. That frame becomes selected. The +specified value is stored in the registers used for returning values of +functions. + + The 'return' command does not resume execution; it leaves the program +stopped in the state that would exist if the function had just returned. +In contrast, the 'finish' command (*note Continuing and Stepping: +Continuing and Stepping.) resumes execution until the selected stack +frame returns naturally. + + GDB needs to know how the EXPRESSION argument should be set for the +inferior. The concrete registers assignment depends on the OS ABI and +the type being returned by the selected stack frame. For example it is +common for OS ABI to return floating point values in FPU registers while +integer values in CPU registers. Still some ABIs return even floating +point values in CPU registers. Larger integer widths (such as 'long +long int') also have specific placement rules. GDB already knows the OS +ABI from its current target so it needs to find out also the type being +returned to make the assignment into the right register(s). + + Normally, the selected stack frame has debug info. GDB will always +use the debug info instead of the implicit type of EXPRESSION when the +debug info is available. For example, if you type 'return -1', and the +function in the current stack frame is declared to return a 'long long +int', GDB transparently converts the implicit 'int' value of -1 into a +'long long int': + + Breakpoint 1, func () at gdb.base/return-nodebug.c:29 + 29 return 31; + (gdb) return -1 + Make func return now? (y or n) y + #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 + 43 printf ("result=%lld\n", func ()); + (gdb) + + However, if the selected stack frame does not have a debug info, +e.g., if the function was compiled without debug info, GDB has to find +out the type to return from user. Specifying a different type by +mistake may set the value in different inferior registers than the +caller code expects. For example, typing 'return -1' with its implicit +type 'int' would set only a part of a 'long long int' result for a debug +info less function (on 32-bit architectures). Therefore the user is +required to specify the return type by an appropriate cast explicitly: + + Breakpoint 2, 0x0040050b in func () + (gdb) return -1 + Return value type not available for selected stack frame. + Please use an explicit cast of the value to return. + (gdb) return (long long int) -1 + Make selected stack frame return now? (y or n) y + #0 0x00400526 in main () + (gdb) + + +File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering + +17.5 Calling Program Functions +============================== + +'print EXPR' + Evaluate the expression EXPR and display the resulting value. EXPR + may include calls to functions in the program being debugged. + +'call EXPR' + Evaluate the expression EXPR without displaying 'void' returned + values. + + You can use this variant of the 'print' command if you want to + execute a function from your program that does not return anything + (a.k.a. "a void function"), but without cluttering the output with + 'void' returned values that GDB will otherwise print. If the + result is not void, it is printed and saved in the value history. + + It is possible for the function you call via the 'print' or 'call' +command to generate a signal (e.g., if there's a bug in the function, or +if you passed it incorrect arguments). What happens in that case is +controlled by the 'set unwindonsignal' command. + + Similarly, with a C++ program it is possible for the function you +call via the 'print' or 'call' command to generate an exception that is +not handled due to the constraints of the dummy frame. In this case, +any exception that is raised in the frame, but has an out-of-frame +exception handler will not be found. GDB builds a dummy-frame for the +inferior function call, and the unwinder cannot seek for exception +handlers outside of this dummy-frame. What happens in that case is +controlled by the 'set unwind-on-terminating-exception' command. + +'set unwindonsignal' + Set unwinding of the stack if a signal is received while in a + function that GDB called in the program being debugged. If set to + on, GDB unwinds the stack it created for the call and restores the + context to what it was before the call. If set to off (the + default), GDB stops in the frame where the signal was received. + +'show unwindonsignal' + Show the current setting of stack unwinding in the functions called + by GDB. + +'set unwind-on-terminating-exception' + Set unwinding of the stack if a C++ exception is raised, but left + unhandled while in a function that GDB called in the program being + debugged. If set to on (the default), GDB unwinds the stack it + created for the call and restores the context to what it was before + the call. If set to off, GDB the exception is delivered to the + default C++ exception handler and the inferior terminated. + +'show unwind-on-terminating-exception' + Show the current setting of stack unwinding in the functions called + by GDB. + + Sometimes, a function you wish to call is actually a "weak alias" for +another function. In such case, GDB might not pick up the type +information, including the types of the function arguments, which causes +GDB to call the inferior function incorrectly. As a result, the called +function will function erroneously and may even crash. A solution to +that is to use the name of the aliased function instead. + + +File: gdb.info, Node: Patching, Prev: Calling, Up: Altering + +17.6 Patching Programs +====================== + +By default, GDB opens the file containing your program's executable code +(or the corefile) read-only. This prevents accidental alterations to +machine code; but it also prevents you from intentionally patching your +program's binary. + + If you'd like to be able to patch the binary, you can specify that +explicitly with the 'set write' command. For example, you might want to +turn on internal debugging flags, or even to make emergency repairs. + +'set write on' +'set write off' + If you specify 'set write on', GDB opens executable and core files + for both reading and writing; if you specify 'set write off' (the + default), GDB opens them read-only. + + If you have already loaded a file, you must load it again (using + the 'exec-file' or 'core-file' command) after changing 'set write', + for your new setting to take effect. + +'show write' + Display whether executable files and core files are opened for + writing as well as reading. + + +File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top + +18 GDB Files +************ + +GDB needs to know the file name of the program to be debugged, both in +order to read its symbol table and in order to start your program. To +debug a core dump of a previous run, you must also tell GDB the name of +the core dump file. + +* Menu: + +* Files:: Commands to specify files +* Separate Debug Files:: Debugging information in separate files +* MiniDebugInfo:: Debugging information in a special section +* Index Files:: Index files speed up GDB +* Symbol Errors:: Errors reading symbol files +* Data Files:: GDB data files + + +File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files + +18.1 Commands to Specify Files +============================== + +You may want to specify executable and core dump file names. The usual +way to do this is at start-up time, using the arguments to GDB's +start-up commands (*note Getting In and Out of GDB: Invocation.). + + Occasionally it is necessary to change to a different file during a +GDB session. Or you may run GDB and forget to specify a file you want +to use. Or you are debugging a remote target via 'gdbserver' (*note +file: Server.). In these situations the GDB commands to specify new +files are useful. + +'file FILENAME' + Use FILENAME as the program to be debugged. It is read for its + symbols and for the contents of pure memory. It is also the + program executed when you use the 'run' command. If you do not + specify a directory and the file is not found in the GDB working + directory, GDB uses the environment variable 'PATH' as a list of + directories to search, just as the shell does when looking for a + program to run. You can change the value of this variable, for + both GDB and your program, using the 'path' command. + + You can load unlinked object '.o' files into GDB using the 'file' + command. You will not be able to "run" an object file, but you can + disassemble functions and inspect variables. Also, if the + underlying BFD functionality supports it, you could use 'gdb + -write' to patch object files using this technique. Note that GDB + can neither interpret nor modify relocations in this case, so + branches and some initialized variables will appear to go to the + wrong place. But this feature is still handy from time to time. + +'file' + 'file' with no argument makes GDB discard any information it has on + both executable file and the symbol table. + +'exec-file [ FILENAME ]' + Specify that the program to be run (but not the symbol table) is + found in FILENAME. GDB searches the environment variable 'PATH' if + necessary to locate your program. Omitting FILENAME means to + discard information on the executable file. + +'symbol-file [ FILENAME ]' + Read symbol table information from file FILENAME. 'PATH' is + searched when necessary. Use the 'file' command to get both symbol + table and program to run from the same file. + + 'symbol-file' with no argument clears out GDB information on your + program's symbol table. + + The 'symbol-file' command causes GDB to forget the contents of some + breakpoints and auto-display expressions. This is because they may + contain pointers to the internal data recording symbols and data + types, which are part of the old symbol table data being discarded + inside GDB. + + 'symbol-file' does not repeat if you press again after + executing it once. + + When GDB is configured for a particular environment, it understands + debugging information in whatever format is the standard generated + for that environment; you may use either a GNU compiler, or other + compilers that adhere to the local conventions. Best results are + usually obtained from GNU compilers; for example, using 'GCC' you + can generate debugging information for optimized code. + + For most kinds of object files, with the exception of old SVR3 + systems using COFF, the 'symbol-file' command does not normally + read the symbol table in full right away. Instead, it scans the + symbol table quickly to find which source files and which symbols + are present. The details are read later, one source file at a + time, as they are needed. + + The purpose of this two-stage reading strategy is to make GDB start + up faster. For the most part, it is invisible except for + occasional pauses while the symbol table details for a particular + source file are being read. (The 'set verbose' command can turn + these pauses into messages if desired. *Note Optional Warnings and + Messages: Messages/Warnings.) + + We have not implemented the two-stage strategy for COFF yet. When + the symbol table is stored in COFF format, 'symbol-file' reads the + symbol table data in full right away. Note that "stabs-in-COFF" + still does the two-stage strategy, since the debug info is actually + in stabs format. + +'symbol-file [ -readnow ] FILENAME' +'file [ -readnow ] FILENAME' + You can override the GDB two-stage strategy for reading symbol + tables by using the '-readnow' option with any of the commands that + load symbol table information, if you want to be sure GDB has the + entire symbol table available. + +'core-file [FILENAME]' +'core' + Specify the whereabouts of a core dump file to be used as the + "contents of memory". Traditionally, core files contain only some + parts of the address space of the process that generated them; GDB + can access the executable file itself for other parts. + + 'core-file' with no argument specifies that no core file is to be + used. + + Note that the core file is ignored when your program is actually + running under GDB. So, if you have been running your program and + you wish to debug a core file instead, you must kill the subprocess + in which the program is running. To do this, use the 'kill' + command (*note Killing the Child Process: Kill Process.). + +'add-symbol-file FILENAME ADDRESS' +'add-symbol-file FILENAME ADDRESS [ -readnow ]' +'add-symbol-file FILENAME ADDRESS -s SECTION ADDRESS ...' + The 'add-symbol-file' command reads additional symbol table + information from the file FILENAME. You would use this command + when FILENAME has been dynamically loaded (by some other means) + into the program that is running. ADDRESS should be the memory + address at which the file has been loaded; GDB cannot figure this + out for itself. You can additionally specify an arbitrary number + of '-s SECTION ADDRESS' pairs, to give an explicit section name and + base address for that section. You can specify any ADDRESS as an + expression. + + The symbol table of the file FILENAME is added to the symbol table + originally read with the 'symbol-file' command. You can use the + 'add-symbol-file' command any number of times; the new symbol data + thus read is kept in addition to the old. + + Changes can be reverted using the command 'remove-symbol-file'. + + Although FILENAME is typically a shared library file, an executable + file, or some other object file which has been fully relocated for + loading into a process, you can also load symbolic information from + relocatable '.o' files, as long as: + + * the file's symbolic information refers only to linker symbols + defined in that file, not to symbols defined by other object + files, + * every section the file's symbolic information refers to has + actually been loaded into the inferior, as it appears in the + file, and + * you can determine the address at which every section was + loaded, and provide these to the 'add-symbol-file' command. + + Some embedded operating systems, like Sun Chorus and VxWorks, can + load relocatable files into an already running program; such + systems typically make the requirements above easy to meet. + However, it's important to recognize that many native systems use + complex link procedures ('.linkonce' section factoring and C++ + constructor table assembly, for example) that make the requirements + difficult to meet. In general, one cannot assume that using + 'add-symbol-file' to read a relocatable object file's symbolic + information will have the same effect as linking the relocatable + object file into the program in the normal way. + + 'add-symbol-file' does not repeat if you press after using + it. + +'remove-symbol-file FILENAME' +'remove-symbol-file -a ADDRESS' + Remove a symbol file added via the 'add-symbol-file' command. The + file to remove can be identified by its FILENAME or by an ADDRESS + that lies within the boundaries of this symbol file in memory. + Example: + + (gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480 + add symbol table from file "/home/user/gdb/mylib.so" at + .text_addr = 0x7ffff7ff9480 + (y or n) y + Reading symbols from /home/user/gdb/mylib.so...done. + (gdb) remove-symbol-file -a 0x7ffff7ff9480 + Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y + (gdb) + + 'remove-symbol-file' does not repeat if you press after using + it. + +'add-symbol-file-from-memory ADDRESS' + Load symbols from the given ADDRESS in a dynamically loaded object + file whose image is mapped directly into the inferior's memory. + For example, the Linux kernel maps a 'syscall DSO' into each + process's address space; this DSO provides kernel-specific code for + some system calls. The argument can be any expression whose + evaluation yields the address of the file's shared object file + header. For this command to work, you must have used 'symbol-file' + or 'exec-file' commands in advance. + +'add-shared-symbol-files LIBRARY-FILE' +'assf LIBRARY-FILE' + The 'add-shared-symbol-files' command can currently be used only in + the Cygwin build of GDB on MS-Windows OS, where it is an alias for + the 'dll-symbols' command (*note Cygwin Native::). GDB + automatically looks for shared libraries, however if GDB does not + find yours, you can invoke 'add-shared-symbol-files'. It takes one + argument: the shared library's file name. 'assf' is a shorthand + alias for 'add-shared-symbol-files'. + +'section SECTION ADDR' + The 'section' command changes the base address of the named SECTION + of the exec file to ADDR. This can be used if the exec file does + not contain section addresses, (such as in the 'a.out' format), or + when the addresses specified in the file itself are wrong. Each + section must be changed separately. The 'info files' command, + described below, lists all the sections and their addresses. + +'info files' +'info target' + 'info files' and 'info target' are synonymous; both print the + current target (*note Specifying a Debugging Target: Targets.), + including the names of the executable and core dump files currently + in use by GDB, and the files from which symbols were loaded. The + command 'help target' lists all possible targets rather than + current ones. + +'maint info sections' + Another command that can give you extra information about program + sections is 'maint info sections'. In addition to the section + information displayed by 'info files', this command displays the + flags and file offset of each section in the executable and core + dump files. In addition, 'maint info sections' provides the + following command options (which may be arbitrarily combined): + + 'ALLOBJ' + Display sections for all loaded object files, including shared + libraries. + 'SECTIONS' + Display info only for named SECTIONS. + 'SECTION-FLAGS' + Display info only for sections for which SECTION-FLAGS are + true. The section flags that GDB currently knows about are: + 'ALLOC' + Section will have space allocated in the process when + loaded. Set for all sections except those containing + debug information. + 'LOAD' + Section will be loaded from the file into the child + process memory. Set for pre-initialized code and data, + clear for '.bss' sections. + 'RELOC' + Section needs to be relocated before loading. + 'READONLY' + Section cannot be modified by the child process. + 'CODE' + Section contains executable code only. + 'DATA' + Section contains data only (no executable code). + 'ROM' + Section will reside in ROM. + 'CONSTRUCTOR' + Section contains data for constructor/destructor lists. + 'HAS_CONTENTS' + Section is not empty. + 'NEVER_LOAD' + An instruction to the linker to not output the section. + 'COFF_SHARED_LIBRARY' + A notification to the linker that the section contains + COFF shared library information. + 'IS_COMMON' + Section contains common symbols. +'set trust-readonly-sections on' + Tell GDB that readonly sections in your object file really are + read-only (i.e. that their contents will not change). In that + case, GDB can fetch values from these sections out of the object + file, rather than from the target program. For some targets + (notably embedded ones), this can be a significant enhancement to + debugging performance. + + The default is off. + +'set trust-readonly-sections off' + Tell GDB not to trust readonly sections. This means that the + contents of the section might change while the program is running, + and must therefore be fetched from the target when needed. + +'show trust-readonly-sections' + Show the current setting of trusting readonly sections. + + All file-specifying commands allow both absolute and relative file +names as arguments. GDB always converts the file name to an absolute +file name and remembers it that way. + + GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and IBM +RS/6000 AIX shared libraries. + + On MS-Windows GDB must be linked with the Expat library to support +shared libraries. *Note Expat::. + + GDB automatically loads symbol definitions from shared libraries when +you use the 'run' command, or when you examine a core file. (Before you +issue the 'run' command, GDB does not understand references to a +function in a shared library, however--unless you are debugging a core +file). + + On HP-UX, if the program loads a library explicitly, GDB +automatically loads the symbols at the time of the 'shl_load' call. + + There are times, however, when you may wish to not automatically load +symbol definitions from shared libraries, such as when they are +particularly large or there are many of them. + + To control the automatic loading of shared library symbols, use the +commands: + +'set auto-solib-add MODE' + If MODE is 'on', symbols from all shared object libraries will be + loaded automatically when the inferior begins execution, you attach + to an independently started inferior, or when the dynamic linker + informs GDB that a new library has been loaded. If MODE is 'off', + symbols must be loaded manually, using the 'sharedlibrary' command. + The default value is 'on'. + + If your program uses lots of shared libraries with debug info that + takes large amounts of memory, you can decrease the GDB memory + footprint by preventing it from automatically loading the symbols + from shared libraries. To that end, type 'set auto-solib-add off' + before running the inferior, then load each library whose debug + symbols you do need with 'sharedlibrary REGEXP', where REGEXP is a + regular expression that matches the libraries whose symbols you + want to be loaded. + +'show auto-solib-add' + Display the current autoloading mode. + + To explicitly load shared library symbols, use the 'sharedlibrary' +command: + +'info share REGEX' +'info sharedlibrary REGEX' + Print the names of the shared libraries which are currently loaded + that match REGEX. If REGEX is omitted then print all shared + libraries that are loaded. + +'sharedlibrary REGEX' +'share REGEX' + Load shared object library symbols for files matching a Unix + regular expression. As with files loaded automatically, it only + loads shared libraries required by your program for a core file or + after typing 'run'. If REGEX is omitted all shared libraries + required by your program are loaded. + +'nosharedlibrary' + Unload all shared object library symbols. This discards all + symbols that have been loaded from all shared libraries. Symbols + from shared libraries that were loaded by explicit user requests + are not discarded. + + Sometimes you may wish that GDB stops and gives you control when any +of shared library events happen. The best way to do this is to use +'catch load' and 'catch unload' (*note Set Catchpoints::). + + GDB also supports the the 'set stop-on-solib-events' command for +this. This command exists for historical reasons. It is less useful +than setting a catchpoint, because it does not allow for conditions or +commands as a catchpoint does. + +'set stop-on-solib-events' + This command controls whether GDB should give you control when the + dynamic linker notifies it about some shared library event. The + most common event of interest is loading or unloading of a new + shared library. + +'show stop-on-solib-events' + Show whether GDB stops and gives you control when shared library + events happen. + + Shared libraries are also supported in many cross or remote debugging +configurations. GDB needs to have access to the target's libraries; +this can be accomplished either by providing copies of the libraries on +the host system, or by asking GDB to automatically retrieve the +libraries from the target. If copies of the target libraries are +provided, they need to be the same as the target libraries, although the +copies on the target can be stripped as long as the copies on the host +are not. + + For remote debugging, you need to tell GDB where the target libraries +are, so that it can load the correct copies--otherwise, it may try to +load the host's libraries. GDB has two variables to specify the search +directories for target libraries. + +'set sysroot PATH' + Use PATH as the system root for the program being debugged. Any + absolute shared library paths will be prefixed with PATH; many + runtime loaders store the absolute paths to the shared library in + the target program's memory. If you use 'set sysroot' to find + shared libraries, they need to be laid out in the same way that + they are on the target, with e.g. a '/lib' and '/usr/lib' hierarchy + under PATH. + + If PATH starts with the sequence 'remote:', GDB will retrieve the + target libraries from the remote system. This is only supported + when using a remote target that supports the 'remote get' command + (*note Sending files to a remote system: File Transfer.). The part + of PATH following the initial 'remote:' (if present) is used as + system root prefix on the remote file system. (1) + + For targets with an MS-DOS based filesystem, such as MS-Windows and + SymbianOS, GDB tries prefixing a few variants of the target + absolute file name with PATH. But first, on Unix hosts, GDB + converts all backslash directory separators into forward slashes, + because the backslash is not a directory separator on Unix: + + c:\foo\bar.dll => c:/foo/bar.dll + + Then, GDB attempts prefixing the target file name with PATH, and + looks for the resulting file name in the host file system: + + c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll + + If that does not find the shared library, GDB tries removing the + ':' character from the drive spec, both for convenience, and, for + the case of the host file system not supporting file names with + colons: + + c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll + + This makes it possible to have a system root that mirrors a target + with more than one drive. E.g., you may want to setup your local + copies of the target system shared libraries like so (note 'c' vs + 'z'): + + /path/to/sysroot/c/sys/bin/foo.dll + /path/to/sysroot/c/sys/bin/bar.dll + /path/to/sysroot/z/sys/bin/bar.dll + + and point the system root at '/path/to/sysroot', so that GDB can + find the correct copies of both 'c:\sys\bin\foo.dll', and + 'z:\sys\bin\bar.dll'. + + If that still does not find the shared library, GDB tries removing + the whole drive spec from the target file name: + + c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll + + This last lookup makes it possible to not care about the drive + name, if you don't want or need to. + + The 'set solib-absolute-prefix' command is an alias for 'set + sysroot'. + + You can set the default system root by using the configure-time + '--with-sysroot' option. If the system root is inside GDB's + configured binary prefix (set with '--prefix' or '--exec-prefix'), + then the default system root will be updated automatically if the + installed GDB is moved to a new location. + +'show sysroot' + Display the current shared library prefix. + +'set solib-search-path PATH' + If this variable is set, PATH is a colon-separated list of + directories to search for shared libraries. 'solib-search-path' is + used after 'sysroot' fails to locate the library, or if the path to + the library is relative instead of absolute. If you want to use + 'solib-search-path' instead of 'sysroot', be sure to set 'sysroot' + to a nonexistent directory to prevent GDB from finding your host's + libraries. 'sysroot' is preferred; setting it to a nonexistent + directory may interfere with automatic loading of shared library + symbols. + +'show solib-search-path' + Display the current shared library search path. + +'set target-file-system-kind KIND' + Set assumed file system kind for target reported file names. + + Shared library file names as reported by the target system may not + make sense as is on the system GDB is running on. For example, + when remote debugging a target that has MS-DOS based file system + semantics, from a Unix host, the target may be reporting to GDB a + list of loaded shared libraries with file names such as + 'c:\Windows\kernel32.dll'. On Unix hosts, there's no concept of + drive letters, so the 'c:\' prefix is not normally understood as + indicating an absolute file name, and neither is the backslash + normally considered a directory separator character. In that case, + the native file system would interpret this whole absolute file + name as a relative file name with no directory components. This + would make it impossible to point GDB at a copy of the remote + target's shared libraries on the host using 'set sysroot', and + impractical with 'set solib-search-path'. Setting + 'target-file-system-kind' to 'dos-based' tells GDB to interpret + such file names similarly to how the target would, and to map them + to file names valid on GDB's native file system semantics. The + value of KIND can be '"auto"', in addition to one of the supported + file system kinds. In that case, GDB tries to determine the + appropriate file system variant based on the current target's + operating system (*note Configuring the Current ABI: ABI.). The + supported file system settings are: + + 'unix' + Instruct GDB to assume the target file system is of Unix kind. + Only file names starting the forward slash ('/') character are + considered absolute, and the directory separator character is + also the forward slash. + + 'dos-based' + Instruct GDB to assume the target file system is DOS based. + File names starting with either a forward slash, or a drive + letter followed by a colon (e.g., 'c:'), are considered + absolute, and both the slash ('/') and the backslash ('\\') + characters are considered directory separators. + + 'auto' + Instruct GDB to use the file system kind associated with the + target operating system (*note Configuring the Current ABI: + ABI.). This is the default. + + When processing file names provided by the user, GDB frequently needs +to compare them to the file names recorded in the program's debug info. +Normally, GDB compares just the "base names" of the files as strings, +which is reasonably fast even for very large programs. (The base name +of a file is the last portion of its name, after stripping all the +leading directories.) This shortcut in comparison is based upon the +assumption that files cannot have more than one base name. This is +usually true, but references to files that use symlinks or similar +filesystem facilities violate that assumption. If your program records +files using such facilities, or if you provide file names to GDB using +symlinks etc., you can set 'basenames-may-differ' to 'true' to instruct +GDB to completely canonicalize each pair of file names it needs to +compare. This will make file-name comparisons accurate, but at a price +of a significant slowdown. + +'set basenames-may-differ' + Set whether a source file may have multiple base names. + +'show basenames-may-differ' + Show whether a source file may have multiple base names. + + ---------- Footnotes ---------- + + (1) If you want to specify a local system root using a directory that +happens to be named 'remote:', you need to use some equivalent variant +of the name like './remote:'. + diff --git a/util/X86MAC64/share/info/gdb.info-3 b/util/X86MAC64/share/info/gdb.info-3 new file mode 100644 index 0000000000..4a22ea816c --- /dev/null +++ b/util/X86MAC64/share/info/gdb.info-3 @@ -0,0 +1,7000 @@ +This is gdb.info, produced by makeinfo version 5.1 from gdb.texinfo. + +Copyright (C) 1988-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + +File: gdb.info, Node: Separate Debug Files, Next: MiniDebugInfo, Prev: Files, Up: GDB Files + +18.2 Debugging Information in Separate Files +============================================ + +GDB allows you to put a program's debugging information in a file +separate from the executable itself, in a way that allows GDB to find +and load the debugging information automatically. Since debugging +information can be very large--sometimes larger than the executable code +itself--some systems distribute debugging information for their +executables in separate files, which users can install only when they +need to debug a problem. + + GDB supports two ways of specifying the separate debug info file: + + * The executable contains a "debug link" that specifies the name of + the separate debug info file. The separate debug file's name is + usually 'EXECUTABLE.debug', where EXECUTABLE is the name of the + corresponding executable file without leading directories (e.g., + 'ls.debug' for '/usr/bin/ls'). In addition, the debug link + specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for the + debug file, which GDB uses to validate that the executable and the + debug file came from the same build. + + * The executable contains a "build ID", a unique bit string that is + also present in the corresponding debug info file. (This is + supported only on some operating systems, notably those which use + the ELF format for binary files and the GNU Binutils.) For more + details about this feature, see the description of the '--build-id' + command-line option in *note Command Line Options: + (ld.info)Options. The debug info file's name is not specified + explicitly by the build ID, but can be computed from the build ID, + see below. + + Depending on the way the debug info file is specified, GDB uses two +different methods of looking for the debug file: + + * For the "debug link" method, GDB looks up the named file in the + directory of the executable file, then in a subdirectory of that + directory named '.debug', and finally under each one of the global + debug directories, in a subdirectory whose name is identical to the + leading directories of the executable's absolute file name. + + * For the "build ID" method, GDB looks in the '.build-id' + subdirectory of each one of the global debug directories for a file + named 'NN/NNNNNNNN.debug', where NN are the first 2 hex characters + of the build ID bit string, and NNNNNNNN are the rest of the bit + string. (Real build ID strings are 32 or more hex characters, not + 10.) + + So, for example, suppose you ask GDB to debug '/usr/bin/ls', which +has a debug link that specifies the file 'ls.debug', and a build ID +whose value in hex is 'abcdef1234'. If the list of the global debug +directories includes '/usr/lib/debug', then GDB will look for the +following debug information files, in the indicated order: + + - '/usr/lib/debug/.build-id/ab/cdef1234.debug' + - '/usr/bin/ls.debug' + - '/usr/bin/.debug/ls.debug' + - '/usr/lib/debug/usr/bin/ls.debug'. + + Global debugging info directories default to what is set by GDB +configure option '--with-separate-debug-dir'. During GDB run you can +also set the global debugging info directories, and view the list GDB is +currently using. + +'set debug-file-directory DIRECTORIES' + Set the directories which GDB searches for separate debugging + information files to DIRECTORY. Multiple path components can be + set concatenating them by a path separator. + +'show debug-file-directory' + Show the directories GDB searches for separate debugging + information files. + + A debug link is a special section of the executable file named +'.gnu_debuglink'. The section must contain: + + * A filename, with any leading directory components removed, followed + by a zero byte, + * zero to three bytes of padding, as needed to reach the next + four-byte boundary within the section, and + * a four-byte CRC checksum, stored in the same endianness used for + the executable file itself. The checksum is computed on the + debugging information file's full contents by the function given + below, passing zero as the CRC argument. + + Any executable file format can carry a debug link, as long as it can +contain a section named '.gnu_debuglink' with the contents described +above. + + The build ID is a special section in the executable file (and in +other ELF binary files that GDB may consider). This section is often +named '.note.gnu.build-id', but that name is not mandatory. It contains +unique identification for the built files--the ID remains the same +across multiple builds of the same build tree. The default algorithm +SHA1 produces 160 bits (40 hexadecimal characters) of the content for +the build ID string. The same section with an identical value is +present in the original built binary with symbols, in its stripped +variant, and in the separate debugging information file. + + The debugging information file itself should be an ordinary +executable, containing a full set of linker symbols, sections, and +debugging information. The sections of the debugging information file +should have the same names, addresses, and sizes as the original file, +but they need not contain any data--much like a '.bss' section in an +ordinary executable. + + The GNU binary utilities (Binutils) package includes the 'objcopy' +utility that can produce the separated executable / debugging +information file pairs using the following commands: + + objcopy --only-keep-debug foo foo.debug + strip -g foo + +These commands remove the debugging information from the executable file +'foo' and place it in the file 'foo.debug'. You can use the first, +second or both methods to link the two files: + + * The debug link method needs the following additional command to + also leave behind a debug link in 'foo': + + objcopy --add-gnu-debuglink=foo.debug foo + + Ulrich Drepper's 'elfutils' package, starting with version 0.53, + contains a version of the 'strip' command such that the command + 'strip foo -f foo.debug' has the same functionality as the two + 'objcopy' commands and the 'ln -s' command above, together. + + * Build ID gets embedded into the main executable using 'ld + --build-id' or the GCC counterpart 'gcc -Wl,--build-id'. Build ID + support plus compatibility fixes for debug files separation are + present in GNU binary utilities (Binutils) package since version + 2.18. + + The CRC used in '.gnu_debuglink' is the CRC-32 defined in IEEE 802.3 +using the polynomial: + + x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11} + + x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1 + + The function is computed byte at a time, taking the least significant +bit of each byte first. The initial pattern '0xffffffff' is used, to +ensure leading zeros affect the CRC and the final result is inverted to +ensure trailing zeros also affect the CRC. + + _Note:_ This is the same CRC polynomial as used in handling the +"Remote Serial Protocol" 'qCRC' packet (*note GDB Remote Serial +Protocol: Remote Protocol.). However in the case of the Remote Serial +Protocol, the CRC is computed _most_ significant bit first, and the +result is not inverted, so trailing zeros have no effect on the CRC +value. + + To complete the description, we show below the code of the function +which produces the CRC used in '.gnu_debuglink'. Inverting the +initially supplied 'crc' argument means that an initial call to this +function passing in zero will start computing the CRC using +'0xffffffff'. + + unsigned long + gnu_debuglink_crc32 (unsigned long crc, + unsigned char *buf, size_t len) + { + static const unsigned long crc32_table[256] = + { + 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, + 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, + 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, + 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, + 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, + 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, + 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, + 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, + 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, + 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, + 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, + 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, + 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, + 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, + 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, + 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, + 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, + 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, + 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, + 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, + 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, + 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, + 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, + 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, + 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, + 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, + 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, + 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, + 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, + 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, + 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, + 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, + 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, + 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, + 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, + 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, + 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, + 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, + 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, + 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, + 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, + 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, + 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, + 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, + 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, + 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, + 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, + 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, + 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, + 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, + 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, + 0x2d02ef8d + }; + unsigned char *end; + + crc = ~crc & 0xffffffff; + for (end = buf + len; buf < end; ++buf) + crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); + return ~crc & 0xffffffff; + } + +This computation does not apply to the "build ID" method. + + +File: gdb.info, Node: MiniDebugInfo, Next: Index Files, Prev: Separate Debug Files, Up: GDB Files + +18.3 Debugging information in a special section +=============================================== + +Some systems ship pre-built executables and libraries that have a +special '.gnu_debugdata' section. This feature is called +"MiniDebugInfo". This section holds an LZMA-compressed object and is +used to supply extra symbols for backtraces. + + The intent of this section is to provide extra minimal debugging +information for use in simple backtraces. It is not intended to be a +replacement for full separate debugging information (*note Separate +Debug Files::). The example below shows the intended use; however, GDB +does not currently put restrictions on what sort of debugging +information might be included in the section. + + GDB has support for this extension. If the section exists, then it +is used provided that no other source of debugging information can be +found, and that GDB was configured with LZMA support. + + This section can be easily created using 'objcopy' and other standard +utilities: + + # Extract the dynamic symbols from the main binary, there is no need + # to also have these in the normal symbol table. + nm -D BINARY --format=posix --defined-only \ + | awk '{ print $1 }' | sort > dynsyms + + # Extract all the text (i.e. function) symbols from the debuginfo. + # (Note that we actually also accept "D" symbols, for the benefit + # of platforms like PowerPC64 that use function descriptors.) + nm BINARY --format=posix --defined-only \ + | awk '{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 }' \ + | sort > funcsyms + + # Keep all the function symbols not already in the dynamic symbol + # table. + comm -13 dynsyms funcsyms > keep_symbols + + # Separate full debug info into debug binary. + objcopy --only-keep-debug BINARY debug + + # Copy the full debuginfo, keeping only a minimal set of symbols and + # removing some unnecessary sections. + objcopy -S --remove-section .gdb_index --remove-section .comment \ + --keep-symbols=keep_symbols debug mini_debuginfo + + # Drop the full debug info from the original binary. + strip --strip-all -R .comment BINARY + + # Inject the compressed data into the .gnu_debugdata section of the + # original binary. + xz mini_debuginfo + objcopy --add-section .gnu_debugdata=mini_debuginfo.xz BINARY + + +File: gdb.info, Node: Index Files, Next: Symbol Errors, Prev: MiniDebugInfo, Up: GDB Files + +18.4 Index Files Speed Up GDB +============================= + +When GDB finds a symbol file, it scans the symbols in the file in order +to construct an internal symbol table. This lets most GDB operations +work quickly--at the cost of a delay early on. For large programs, this +delay can be quite lengthy, so GDB provides a way to build an index, +which speeds up startup. + + The index is stored as a section in the symbol file. GDB can write +the index to a file, then you can put it into the symbol file using +'objcopy'. + + To create an index file, use the 'save gdb-index' command: + +'save gdb-index DIRECTORY' + Create an index file for each symbol file currently known by GDB. + Each file is named after its corresponding symbol file, with + '.gdb-index' appended, and is written into the given DIRECTORY. + + Once you have created an index file you can merge it into your symbol +file, here named 'symfile', using 'objcopy': + + $ objcopy --add-section .gdb_index=symfile.gdb-index \ + --set-section-flags .gdb_index=readonly symfile symfile + + GDB will normally ignore older versions of '.gdb_index' sections that +have been deprecated. Usually they are deprecated because they are +missing a new feature or have performance issues. To tell GDB to use a +deprecated index section anyway specify 'set +use-deprecated-index-sections on'. The default is 'off'. This can +speed up startup, but may result in some functionality being lost. +*Note Index Section Format::. + + _Warning:_ Setting 'use-deprecated-index-sections' to 'on' must be +done before gdb reads the file. The following will not work: + + $ gdb -ex "set use-deprecated-index-sections on" + + Instead you must do, for example, + + $ gdb -iex "set use-deprecated-index-sections on" + + There are currently some limitation on indices. They only work when +for DWARF debugging information, not stabs. And, they do not currently +work for programs using Ada. + + +File: gdb.info, Node: Symbol Errors, Next: Data Files, Prev: Index Files, Up: GDB Files + +18.5 Errors Reading Symbol Files +================================ + +While reading a symbol file, GDB occasionally encounters problems, such +as symbol types it does not recognize, or known bugs in compiler output. +By default, GDB does not notify you of such problems, since they are +relatively common and primarily of interest to people debugging +compilers. If you are interested in seeing information about +ill-constructed symbol tables, you can either ask GDB to print only one +message about each such type of problem, no matter how many times the +problem occurs; or you can ask GDB to print more messages, to see how +many times the problems occur, with the 'set complaints' command (*note +Optional Warnings and Messages: Messages/Warnings.). + + The messages currently printed, and their meanings, include: + +'inner block not inside outer block in SYMBOL' + + The symbol information shows where symbol scopes begin and end + (such as at the start of a function or a block of statements). + This error indicates that an inner scope block is not fully + contained in its outer scope blocks. + + GDB circumvents the problem by treating the inner block as if it + had the same scope as the outer block. In the error message, + SYMBOL may be shown as "'(don't know)'" if the outer block is not a + function. + +'block at ADDRESS out of order' + + The symbol information for symbol scope blocks should occur in + order of increasing addresses. This error indicates that it does + not do so. + + GDB does not circumvent this problem, and has trouble locating + symbols in the source file whose symbols it is reading. (You can + often determine what source file is affected by specifying 'set + verbose on'. *Note Optional Warnings and Messages: + Messages/Warnings.) + +'bad block start address patched' + + The symbol information for a symbol scope block has a start address + smaller than the address of the preceding source line. This is + known to occur in the SunOS 4.1.1 (and earlier) C compiler. + + GDB circumvents the problem by treating the symbol scope block as + starting on the previous source line. + +'bad string table offset in symbol N' + + Symbol number N contains a pointer into the string table which is + larger than the size of the string table. + + GDB circumvents the problem by considering the symbol to have the + name 'foo', which may cause other problems if many symbols end up + with this name. + +'unknown symbol type 0xNN' + + The symbol information contains new data types that GDB does not + yet know how to read. '0xNN' is the symbol type of the + uncomprehended information, in hexadecimal. + + GDB circumvents the error by ignoring this symbol information. + This usually allows you to debug your program, though certain + symbols are not accessible. If you encounter such a problem and + feel like debugging it, you can debug 'gdb' with itself, breakpoint + on 'complain', then go up to the function 'read_dbx_symtab' and + examine '*bufp' to see the symbol. + +'stub type has NULL name' + + GDB could not find the full definition for a struct or class. + +'const/volatile indicator missing (ok if using g++ v1.x), got...' + The symbol information for a C++ member function is missing some + information that recent versions of the compiler should have output + for it. + +'info mismatch between compiler and debugger' + + GDB could not parse a type specification output by the compiler. + + +File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files + +18.6 GDB Data Files +=================== + +GDB will sometimes read an auxiliary data file. These files are kept in +a directory known as the "data directory". + + You can set the data directory's name, and view the name GDB is +currently using. + +'set data-directory DIRECTORY' + Set the directory which GDB searches for auxiliary data files to + DIRECTORY. + +'show data-directory' + Show the directory GDB searches for auxiliary data files. + + You can set the default data directory by using the configure-time +'--with-gdb-datadir' option. If the data directory is inside GDB's +configured binary prefix (set with '--prefix' or '--exec-prefix'), then +the default data directory will be updated automatically if the +installed GDB is moved to a new location. + + The data directory may also be specified with the '--data-directory' +command line option. *Note Mode Options::. + + +File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top + +19 Specifying a Debugging Target +******************************** + +A "target" is the execution environment occupied by your program. + + Often, GDB runs in the same host environment as your program; in that +case, the debugging target is specified as a side effect when you use +the 'file' or 'core' commands. When you need more flexibility--for +example, running GDB on a physically separate host, or controlling a +standalone system over a serial port or a realtime system over a TCP/IP +connection--you can use the 'target' command to specify one of the +target types configured for GDB (*note Commands for Managing Targets: +Target Commands.). + + It is possible to build GDB for several different "target +architectures". When GDB is built like that, you can choose one of the +available architectures with the 'set architecture' command. + +'set architecture ARCH' + This command sets the current target architecture to ARCH. The + value of ARCH can be '"auto"', in addition to one of the supported + architectures. + +'show architecture' + Show the current target architecture. + +'set processor' +'processor' + These are alias commands for, respectively, 'set architecture' and + 'show architecture'. + +* Menu: + +* Active Targets:: Active targets +* Target Commands:: Commands for managing targets +* Byte Order:: Choosing target byte order + + +File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets + +19.1 Active Targets +=================== + +There are multiple classes of targets such as: processes, executable +files or recording sessions. Core files belong to the process class, +making core file and process mutually exclusive. Otherwise, GDB can +work concurrently on multiple active targets, one in each class. This +allows you to (for example) start a process and inspect its activity, +while still having access to the executable file after the process +finishes. Or if you start process recording (*note Reverse Execution::) +and 'reverse-step' there, you are presented a virtual layer of the +recording target, while the process target remains stopped at the +chronologically last point of the process execution. + + Use the 'core-file' and 'exec-file' commands to select a new core +file or executable target (*note Commands to Specify Files: Files.). To +specify as a target a process that is already running, use the 'attach' +command (*note Debugging an Already-running Process: Attach.). + + +File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets + +19.2 Commands for Managing Targets +================================== + +'target TYPE PARAMETERS' + Connects the GDB host environment to a target machine or process. + A target is typically a protocol for talking to debugging + facilities. You use the argument TYPE to specify the type or + protocol of the target machine. + + Further PARAMETERS are interpreted by the target protocol, but + typically include things like device names or host names to connect + with, process numbers, and baud rates. + + The 'target' command does not repeat if you press again after + executing the command. + +'help target' + Displays the names of all targets available. To display targets + currently selected, use either 'info target' or 'info files' (*note + Commands to Specify Files: Files.). + +'help target NAME' + Describe a particular target, including any parameters necessary to + select it. + +'set gnutarget ARGS' + GDB uses its own library BFD to read your files. GDB knows whether + it is reading an "executable", a "core", or a ".o" file; however, + you can specify the file format with the 'set gnutarget' command. + Unlike most 'target' commands, with 'gnutarget' the 'target' refers + to a program, not a machine. + + _Warning:_ To specify a file format with 'set gnutarget', you + must know the actual BFD name. + + *Note Commands to Specify Files: Files. + +'show gnutarget' + Use the 'show gnutarget' command to display what file format + 'gnutarget' is set to read. If you have not set 'gnutarget', GDB + will determine the file format for each file automatically, and + 'show gnutarget' displays 'The current BFD target is "auto"'. + + Here are some common targets (available, or not, depending on the GDB +configuration): + +'target exec PROGRAM' + An executable file. 'target exec PROGRAM' is the same as + 'exec-file PROGRAM'. + +'target core FILENAME' + A core dump file. 'target core FILENAME' is the same as 'core-file + FILENAME'. + +'target remote MEDIUM' + A remote system connected to GDB via a serial line or network + connection. This command tells GDB to use its own remote protocol + over MEDIUM for debugging. *Note Remote Debugging::. + + For example, if you have a board connected to '/dev/ttya' on the + machine running GDB, you could say: + + target remote /dev/ttya + + 'target remote' supports the 'load' command. This is only useful + if you have some other way of getting the stub to the target + system, and you can put it somewhere in memory where it won't get + clobbered by the download. + +'target sim [SIMARGS] ...' + Builtin CPU simulator. GDB includes simulators for most + architectures. In general, + target sim + load + run + works; however, you cannot assume that a specific memory map, + device drivers, or even basic I/O is available, although some + simulators do provide these. For info about any processor-specific + simulator details, see the appropriate section in *note Embedded + Processors: Embedded Processors. + + Different targets are available on different configurations of GDB; +your configuration may have more or fewer targets. + + Many remote targets require you to download the executable's code +once you've successfully established a connection. You may wish to +control various aspects of this process. + +'set hash' + This command controls whether a hash mark '#' is displayed while + downloading a file to the remote monitor. If on, a hash mark is + displayed after each S-record is successfully downloaded to the + monitor. + +'show hash' + Show the current status of displaying the hash mark. + +'set debug monitor' + Enable or disable display of communications messages between GDB + and the remote monitor. + +'show debug monitor' + Show the current status of displaying communications between GDB + and the remote monitor. + +'load FILENAME' + Depending on what remote debugging facilities are configured into + GDB, the 'load' command may be available. Where it exists, it is + meant to make FILENAME (an executable) available for debugging on + the remote system--by downloading, or dynamic linking, for example. + 'load' also records the FILENAME symbol table in GDB, like the + 'add-symbol-file' command. + + If your GDB does not have a 'load' command, attempting to execute + it gets the error message "'You can't do that when your target is + ...'" + + The file is loaded at whatever address is specified in the + executable. For some object file formats, you can specify the load + address when you link the program; for other formats, like a.out, + the object file format specifies a fixed address. + + Depending on the remote side capabilities, GDB may be able to load + programs into flash memory. + + 'load' does not repeat if you press again after using it. + + +File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets + +19.3 Choosing Target Byte Order +=============================== + +Some types of processors, such as the MIPS, PowerPC, and Renesas SH, +offer the ability to run either big-endian or little-endian byte orders. +Usually the executable or symbol will include a bit to designate the +endian-ness, and you will not need to worry about which to use. +However, you may still find it useful to adjust GDB's idea of processor +endian-ness manually. + +'set endian big' + Instruct GDB to assume the target is big-endian. + +'set endian little' + Instruct GDB to assume the target is little-endian. + +'set endian auto' + Instruct GDB to use the byte order associated with the executable. + +'show endian' + Display GDB's current idea of the target byte order. + + Note that these commands merely adjust interpretation of symbolic +data on the host, and that they have absolutely no effect on the target +system. + + +File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top + +20 Debugging Remote Programs +**************************** + +If you are trying to debug a program running on a machine that cannot +run GDB in the usual way, it is often useful to use remote debugging. +For example, you might use remote debugging on an operating system +kernel, or on a small system which does not have a general purpose +operating system powerful enough to run a full-featured debugger. + + Some configurations of GDB have special serial or TCP/IP interfaces +to make this work with particular debugging targets. In addition, GDB +comes with a generic serial protocol (specific to GDB, but not specific +to any particular target system) which you can use if you write the +remote stubs--the code that runs on the remote system to communicate +with GDB. + + Other remote targets may be available in your configuration of GDB; +use 'help target' to list them. + +* Menu: + +* Connecting:: Connecting to a remote target +* File Transfer:: Sending files to a remote system +* Server:: Using the gdbserver program +* Remote Configuration:: Remote configuration +* Remote Stub:: Implementing a remote stub + + +File: gdb.info, Node: Connecting, Next: File Transfer, Up: Remote Debugging + +20.1 Connecting to a Remote Target +================================== + +On the GDB host machine, you will need an unstripped copy of your +program, since GDB needs symbol and debugging information. Start up GDB +as usual, using the name of the local copy of your program as the first +argument. + + GDB can communicate with the target over a serial line, or over an IP +network using TCP or UDP. In each case, GDB uses the same protocol for +debugging your program; only the medium carrying the debugging packets +varies. The 'target remote' command establishes a connection to the +target. Its arguments indicate which medium to use: + +'target remote SERIAL-DEVICE' + Use SERIAL-DEVICE to communicate with the target. For example, to + use a serial line connected to the device named '/dev/ttyb': + + target remote /dev/ttyb + + If you're using a serial line, you may want to give GDB the + '--baud' option, or use the 'set serial baud' command (*note set + serial baud: Remote Configuration.) before the 'target' command. + +'target remote HOST:PORT' +'target remote tcp:HOST:PORT' + Debug using a TCP connection to PORT on HOST. The HOST may be + either a host name or a numeric IP address; PORT must be a decimal + number. The HOST could be the target machine itself, if it is + directly connected to the net, or it might be a terminal server + which in turn has a serial line to the target. + + For example, to connect to port 2828 on a terminal server named + 'manyfarms': + + target remote manyfarms:2828 + + If your remote target is actually running on the same machine as + your debugger session (e.g. a simulator for your target running on + the same host), you can omit the hostname. For example, to connect + to port 1234 on your local machine: + + target remote :1234 + + Note that the colon is still required here. + +'target remote udp:HOST:PORT' + Debug using UDP packets to PORT on HOST. For example, to connect + to UDP port 2828 on a terminal server named 'manyfarms': + + target remote udp:manyfarms:2828 + + When using a UDP connection for remote debugging, you should keep + in mind that the 'U' stands for "Unreliable". UDP can silently + drop packets on busy or unreliable networks, which will cause havoc + with your debugging session. + +'target remote | COMMAND' + Run COMMAND in the background and communicate with it using a pipe. + The COMMAND is a shell command, to be parsed and expanded by the + system's command shell, '/bin/sh'; it should expect remote protocol + packets on its standard input, and send replies on its standard + output. You could use this to run a stand-alone simulator that + speaks the remote debugging protocol, to make net connections using + programs like 'ssh', or for other similar tricks. + + If COMMAND closes its standard output (perhaps by exiting), GDB + will try to send it a 'SIGTERM' signal. (If the program has + already exited, this will have no effect.) + + Once the connection has been established, you can use all the usual +commands to examine and change data. The remote program is already +running; you can use 'step' and 'continue', and you do not need to use +'run'. + + Whenever GDB is waiting for the remote program, if you type the +interrupt character (often 'Ctrl-c'), GDB attempts to stop the program. +This may or may not succeed, depending in part on the hardware and the +serial drivers the remote system uses. If you type the interrupt +character once again, GDB displays this prompt: + + Interrupted while waiting for the program. + Give up (and stop debugging it)? (y or n) + + If you type 'y', GDB abandons the remote debugging session. (If you +decide you want to try again later, you can use 'target remote' again to +connect once more.) If you type 'n', GDB goes back to waiting. + +'detach' + When you have finished debugging the remote program, you can use + the 'detach' command to release it from GDB control. Detaching + from the target normally resumes its execution, but the results + will depend on your particular remote stub. After the 'detach' + command, GDB is free to connect to another target. + +'disconnect' + The 'disconnect' command behaves like 'detach', except that the + target is generally not resumed. It will wait for GDB (this + instance or another one) to connect and continue debugging. After + the 'disconnect' command, GDB is again free to connect to another + target. + +'monitor CMD' + This command allows you to send arbitrary commands directly to the + remote monitor. Since GDB doesn't care about the commands it sends + like this, this command is the way to extend GDB--you can add new + commands that only the external monitor will understand and + implement. + + +File: gdb.info, Node: File Transfer, Next: Server, Prev: Connecting, Up: Remote Debugging + +20.2 Sending files to a remote system +===================================== + +Some remote targets offer the ability to transfer files over the same +connection used to communicate with GDB. This is convenient for targets +accessible through other means, e.g. GNU/Linux systems running +'gdbserver' over a network interface. For other targets, e.g. embedded +devices with only a single serial port, this may be the only way to +upload or download files. + + Not all remote targets support these commands. + +'remote put HOSTFILE TARGETFILE' + Copy file HOSTFILE from the host system (the machine running GDB) + to TARGETFILE on the target system. + +'remote get TARGETFILE HOSTFILE' + Copy file TARGETFILE from the target system to HOSTFILE on the host + system. + +'remote delete TARGETFILE' + Delete TARGETFILE from the target system. + + +File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer, Up: Remote Debugging + +20.3 Using the 'gdbserver' Program +================================== + +'gdbserver' is a control program for Unix-like systems, which allows you +to connect your program with a remote GDB via 'target remote'--but +without linking in the usual debugging stub. + + 'gdbserver' is not a complete replacement for the debugging stubs, +because it requires essentially the same operating-system facilities +that GDB itself does. In fact, a system that can run 'gdbserver' to +connect to a remote GDB could also run GDB locally! 'gdbserver' is +sometimes useful nevertheless, because it is a much smaller program than +GDB itself. It is also easier to port than all of GDB, so you may be +able to get started more quickly on a new system by using 'gdbserver'. +Finally, if you develop code for real-time systems, you may find that +the tradeoffs involved in real-time operation make it more convenient to +do as much development work as possible on another system, for example +by cross-compiling. You can use 'gdbserver' to make a similar choice +for debugging. + + GDB and 'gdbserver' communicate via either a serial line or a TCP +connection, using the standard GDB remote serial protocol. + + _Warning:_ 'gdbserver' does not have any built-in security. Do not + run 'gdbserver' connected to any public network; a GDB connection + to 'gdbserver' provides access to the target system with the same + privileges as the user running 'gdbserver'. + +20.3.1 Running 'gdbserver' +-------------------------- + +Run 'gdbserver' on the target system. You need a copy of the program +you want to debug, including any libraries it requires. 'gdbserver' +does not need your program's symbol table, so you can strip the program +if necessary to save space. GDB on the host system does all the symbol +handling. + + To use the server, you must tell it how to communicate with GDB; the +name of your program; and the arguments for your program. The usual +syntax is: + + target> gdbserver COMM PROGRAM [ ARGS ... ] + + COMM is either a device name (to use a serial line), or a TCP +hostname and portnumber, or '-' or 'stdio' to use stdin/stdout of +'gdbserver'. For example, to debug Emacs with the argument 'foo.txt' +and communicate with GDB over the serial port '/dev/com1': + + target> gdbserver /dev/com1 emacs foo.txt + + 'gdbserver' waits passively for the host GDB to communicate with it. + + To use a TCP connection instead of a serial line: + + target> gdbserver host:2345 emacs foo.txt + + The only difference from the previous example is the first argument, +specifying that you are communicating with the host GDB via TCP. The +'host:2345' argument means that 'gdbserver' is to expect a TCP +connection from machine 'host' to local TCP port 2345. (Currently, the +'host' part is ignored.) You can choose any number you want for the +port number as long as it does not conflict with any TCP ports already +in use on the target system (for example, '23' is reserved for +'telnet').(1) You must use the same port number with the host GDB +'target remote' command. + + The 'stdio' connection is useful when starting 'gdbserver' with ssh: + + (gdb) target remote | ssh -T hostname gdbserver - hello + + The '-T' option to ssh is provided because we don't need a remote +pty, and we don't want escape-character handling. Ssh does this by +default when a command is provided, the flag is provided to make it +explicit. You could elide it if you want to. + + Programs started with stdio-connected gdbserver have '/dev/null' for +'stdin', and 'stdout','stderr' are sent back to gdb for display through +a pipe connected to gdbserver. Both 'stdout' and 'stderr' use the same +pipe. + +20.3.1.1 Attaching to a Running Program +....................................... + +On some targets, 'gdbserver' can also attach to running programs. This +is accomplished via the '--attach' argument. The syntax is: + + target> gdbserver --attach COMM PID + + PID is the process ID of a currently running process. It isn't +necessary to point 'gdbserver' at a binary for the running process. + + You can debug processes by name instead of process ID if your target +has the 'pidof' utility: + + target> gdbserver --attach COMM `pidof PROGRAM` + + In case more than one copy of PROGRAM is running, or PROGRAM has +multiple threads, most versions of 'pidof' support the '-s' option to +only return the first process ID. + +20.3.1.2 Multi-Process Mode for 'gdbserver' +........................................... + +When you connect to 'gdbserver' using 'target remote', 'gdbserver' +debugs the specified program only once. When the program exits, or you +detach from it, GDB closes the connection and 'gdbserver' exits. + + If you connect using 'target extended-remote', 'gdbserver' enters +multi-process mode. When the debugged program exits, or you detach from +it, GDB stays connected to 'gdbserver' even though no program is +running. The 'run' and 'attach' commands instruct 'gdbserver' to run or +attach to a new program. The 'run' command uses 'set remote exec-file' +(*note set remote exec-file::) to select the program to run. Command +line arguments are supported, except for wildcard expansion and I/O +redirection (*note Arguments::). + + To start 'gdbserver' without supplying an initial command to run or +process ID to attach, use the '--multi' command line option. Then you +can connect using 'target extended-remote' and start the program you +want to debug. + + In multi-process mode 'gdbserver' does not automatically exit unless +you use the option '--once'. You can terminate it by using 'monitor +exit' (*note Monitor Commands for gdbserver::). Note that the +conditions under which 'gdbserver' terminates depend on how GDB connects +to it ('target remote' or 'target extended-remote'). The '--multi' +option to 'gdbserver' has no influence on that. + +20.3.1.3 TCP port allocation lifecycle of 'gdbserver' +..................................................... + +This section applies only when 'gdbserver' is run to listen on a TCP +port. + + 'gdbserver' normally terminates after all of its debugged processes +have terminated in 'target remote' mode. On the other hand, for 'target +extended-remote', 'gdbserver' stays running even with no processes left. +GDB normally terminates the spawned debugged process on its exit, which +normally also terminates 'gdbserver' in the 'target remote' mode. +Therefore, when the connection drops unexpectedly, and GDB cannot ask +'gdbserver' to kill its debugged processes, 'gdbserver' stays running +even in the 'target remote' mode. + + When 'gdbserver' stays running, GDB can connect to it again later. +Such reconnecting is useful for features like *note disconnected +tracing::. For completeness, at most one GDB can be connected at a +time. + + By default, 'gdbserver' keeps the listening TCP port open, so that +subsequent connections are possible. However, if you start 'gdbserver' +with the '--once' option, it will stop listening for any further +connection attempts after connecting to the first GDB session. This +means no further connections to 'gdbserver' will be possible after the +first one. It also means 'gdbserver' will terminate after the first +connection with remote GDB has closed, even for unexpectedly closed +connections and even in the 'target extended-remote' mode. The '--once' +option allows reusing the same port number for connecting to multiple +instances of 'gdbserver' running on the same host, since each instance +closes its port after the first connection. + +20.3.1.4 Other Command-Line Arguments for 'gdbserver' +..................................................... + +The '--debug' option tells 'gdbserver' to display extra status +information about the debugging process. The '--remote-debug' option +tells 'gdbserver' to display remote protocol debug output. These +options are intended for 'gdbserver' development and for bug reports to +the developers. + + The '--wrapper' option specifies a wrapper to launch programs for +debugging. The option should be followed by the name of the wrapper, +then any command-line arguments to pass to the wrapper, then '--' +indicating the end of the wrapper arguments. + + 'gdbserver' runs the specified wrapper program with a combined +command line including the wrapper arguments, then the name of the +program to debug, then any arguments to the program. The wrapper runs +until it executes your program, and then GDB gains control. + + You can use any program that eventually calls 'execve' with its +arguments as a wrapper. Several standard Unix utilities do this, e.g. +'env' and 'nohup'. Any Unix shell script ending with 'exec "$@"' will +also work. + + For example, you can use 'env' to pass an environment variable to the +debugged program, without setting the variable in 'gdbserver''s +environment: + + $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog + +20.3.2 Connecting to 'gdbserver' +-------------------------------- + +Run GDB on the host system. + + First make sure you have the necessary symbol files. Load symbols +for your application using the 'file' command before you connect. Use +'set sysroot' to locate target libraries (unless your GDB was compiled +with the correct sysroot using '--with-sysroot'). + + The symbol file and target libraries must exactly match the +executable and libraries on the target, with one exception: the files on +the host system should not be stripped, even if the files on the target +system are. Mismatched or missing files will lead to confusing results +during debugging. On GNU/Linux targets, mismatched or missing files may +also prevent 'gdbserver' from debugging multi-threaded programs. + + Connect to your target (*note Connecting to a Remote Target: +Connecting.). For TCP connections, you must start up 'gdbserver' prior +to using the 'target remote' command. Otherwise you may get an error +whose text depends on the host system, but which usually looks something +like 'Connection refused'. Don't use the 'load' command in GDB when +using 'gdbserver', since the program is already on the target. + +20.3.3 Monitor Commands for 'gdbserver' +--------------------------------------- + +During a GDB session using 'gdbserver', you can use the 'monitor' +command to send special requests to 'gdbserver'. Here are the available +commands. + +'monitor help' + List the available monitor commands. + +'monitor set debug 0' +'monitor set debug 1' + Disable or enable general debugging messages. + +'monitor set remote-debug 0' +'monitor set remote-debug 1' + Disable or enable specific debugging messages associated with the + remote protocol (*note Remote Protocol::). + +'monitor set libthread-db-search-path [PATH]' + When this command is issued, PATH is a colon-separated list of + directories to search for 'libthread_db' (*note set + libthread-db-search-path: Threads.). If you omit PATH, + 'libthread-db-search-path' will be reset to its default value. + + The special entry '$pdir' for 'libthread-db-search-path' is not + supported in 'gdbserver'. + +'monitor exit' + Tell gdbserver to exit immediately. This command should be + followed by 'disconnect' to close the debugging session. + 'gdbserver' will detach from any attached processes and kill any + processes it created. Use 'monitor exit' to terminate 'gdbserver' + at the end of a multi-process mode debug session. + +20.3.4 Tracepoints support in 'gdbserver' +----------------------------------------- + +On some targets, 'gdbserver' supports tracepoints, fast tracepoints and +static tracepoints. + + For fast or static tracepoints to work, a special library called the +"in-process agent" (IPA), must be loaded in the inferior process. This +library is built and distributed as an integral part of 'gdbserver'. In +addition, support for static tracepoints requires building the +in-process agent library with static tracepoints support. At present, +the UST (LTTng Userspace Tracer, ) tracing engine +is supported. This support is automatically available if UST +development headers are found in the standard include path when +'gdbserver' is built, or if 'gdbserver' was explicitly configured using +'--with-ust' to point at such headers. You can explicitly disable the +support using '--with-ust=no'. + + There are several ways to load the in-process agent in your program: + +'Specifying it as dependency at link time' + + You can link your program dynamically with the in-process agent + library. On most systems, this is accomplished by adding + '-linproctrace' to the link command. + +'Using the system's preloading mechanisms' + + You can force loading the in-process agent at startup time by using + your system's support for preloading shared libraries. Many Unixes + support the concept of preloading user defined libraries. In most + cases, you do that by specifying 'LD_PRELOAD=libinproctrace.so' in + the environment. See also the description of 'gdbserver''s + '--wrapper' command line option. + +'Using GDB to force loading the agent at run time' + + On some systems, you can force the inferior to load a shared + library, by calling a dynamic loader function in the inferior that + takes care of dynamically looking up and loading a shared library. + On most Unix systems, the function is 'dlopen'. You'll use the + 'call' command for that. For example: + + (gdb) call dlopen ("libinproctrace.so", ...) + + Note that on most Unix systems, for the 'dlopen' function to be + available, the program needs to be linked with '-ldl'. + + On systems that have a userspace dynamic loader, like most Unix +systems, when you connect to 'gdbserver' using 'target remote', you'll +find that the program is stopped at the dynamic loader's entry point, +and no shared library has been loaded in the program's address space +yet, including the in-process agent. In that case, before being able to +use any of the fast or static tracepoints features, you need to let the +loader run and load the shared libraries. The simplest way to do that +is to run the program to the main procedure. E.g., if debugging a C or +C++ program, start 'gdbserver' like so: + + $ gdbserver :9999 myprogram + + Start GDB and connect to 'gdbserver' like so, and run to main: + + $ gdb myprogram + (gdb) target remote myhost:9999 + 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 + (gdb) b main + (gdb) continue + + The in-process tracing agent library should now be loaded into the +process; you can confirm it with the 'info sharedlibrary' command, which +will list 'libinproctrace.so' as loaded in the process. You are now +ready to install fast tracepoints, list static tracepoint markers, probe +static tracepoints markers, and start tracing. + + ---------- Footnotes ---------- + + (1) If you choose a port number that conflicts with another service, +'gdbserver' prints an error message and exits. + + +File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server, Up: Remote Debugging + +20.4 Remote Configuration +========================= + +This section documents the configuration options available when +debugging remote programs. For the options related to the File I/O +extensions of the remote protocol, see *note system-call-allowed: +system. + +'set remoteaddresssize BITS' + Set the maximum size of address in a memory packet to the specified + number of bits. GDB will mask off the address bits above that + number, when it passes addresses to the remote target. The default + value is the number of bits in the target's address. + +'show remoteaddresssize' + Show the current value of remote address size in bits. + +'set serial baud N' + Set the baud rate for the remote serial I/O to N baud. The value + is used to set the speed of the serial port used for debugging + remote targets. + +'show serial baud' + Show the current speed of the remote connection. + +'set remotebreak' + If set to on, GDB sends a 'BREAK' signal to the remote when you + type 'Ctrl-c' to interrupt the program running on the remote. If + set to off, GDB sends the 'Ctrl-C' character instead. The default + is off, since most remote systems expect to see 'Ctrl-C' as the + interrupt signal. + +'show remotebreak' + Show whether GDB sends 'BREAK' or 'Ctrl-C' to interrupt the remote + program. + +'set remoteflow on' +'set remoteflow off' + Enable or disable hardware flow control ('RTS'/'CTS') on the serial + port used to communicate to the remote target. + +'show remoteflow' + Show the current setting of hardware flow control. + +'set remotelogbase BASE' + Set the base (a.k.a. radix) of logging serial protocol + communications to BASE. Supported values of BASE are: 'ascii', + 'octal', and 'hex'. The default is 'ascii'. + +'show remotelogbase' + Show the current setting of the radix for logging remote serial + protocol. + +'set remotelogfile FILE' + Record remote serial communications on the named FILE. The default + is not to record at all. + +'show remotelogfile.' + Show the current setting of the file name on which to record the + serial communications. + +'set remotetimeout NUM' + Set the timeout limit to wait for the remote target to respond to + NUM seconds. The default is 2 seconds. + +'show remotetimeout' + Show the current number of seconds to wait for the remote target + responses. + +'set remote hardware-watchpoint-limit LIMIT' +'set remote hardware-breakpoint-limit LIMIT' + Restrict GDB to using LIMIT remote hardware breakpoint or + watchpoints. A limit of -1, the default, is treated as unlimited. + +'set remote hardware-watchpoint-length-limit LIMIT' + Restrict GDB to using LIMIT bytes for the maximum length of a + remote hardware watchpoint. A limit of -1, the default, is treated + as unlimited. + +'show remote hardware-watchpoint-length-limit' + Show the current limit (in bytes) of the maximum length of a remote + hardware watchpoint. + +'set remote exec-file FILENAME' +'show remote exec-file' + Select the file used for 'run' with 'target extended-remote'. This + should be set to a filename valid on the target system. If it is + not set, the target will use a default filename (e.g. the last + program run). + +'set remote interrupt-sequence' + Allow the user to select one of 'Ctrl-C', a 'BREAK' or 'BREAK-g' as + the sequence to the remote target in order to interrupt the + execution. 'Ctrl-C' is a default. Some system prefers 'BREAK' + which is high level of serial line for some certain time. Linux + kernel prefers 'BREAK-g', a.k.a Magic SysRq g. It is 'BREAK' + signal followed by character 'g'. + +'show interrupt-sequence' + Show which of 'Ctrl-C', 'BREAK' or 'BREAK-g' is sent by GDB to + interrupt the remote program. 'BREAK-g' is BREAK signal followed + by 'g' and also known as Magic SysRq g. + +'set remote interrupt-on-connect' + Specify whether interrupt-sequence is sent to remote target when + GDB connects to it. This is mostly needed when you debug Linux + kernel. Linux kernel expects 'BREAK' followed by 'g' which is + known as Magic SysRq g in order to connect GDB. + +'show interrupt-on-connect' + Show whether interrupt-sequence is sent to remote target when GDB + connects to it. + +'set tcp auto-retry on' + Enable auto-retry for remote TCP connections. This is useful if + the remote debugging agent is launched in parallel with GDB; there + is a race condition because the agent may not become ready to + accept the connection before GDB attempts to connect. When + auto-retry is enabled, if the initial attempt to connect fails, GDB + reattempts to establish the connection using the timeout specified + by 'set tcp connect-timeout'. + +'set tcp auto-retry off' + Do not auto-retry failed TCP connections. + +'show tcp auto-retry' + Show the current auto-retry setting. + +'set tcp connect-timeout SECONDS' +'set tcp connect-timeout unlimited' + Set the timeout for establishing a TCP connection to the remote + target to SECONDS. The timeout affects both polling to retry + failed connections (enabled by 'set tcp auto-retry on') and waiting + for connections that are merely slow to complete, and represents an + approximate cumulative value. If SECONDS is 'unlimited', there is + no timeout and GDB will keep attempting to establish a connection + forever, unless interrupted with 'Ctrl-c'. The default is 15 + seconds. + +'show tcp connect-timeout' + Show the current connection timeout setting. + + The GDB remote protocol autodetects the packets supported by your +debugging stub. If you need to override the autodetection, you can use +these commands to enable or disable individual packets. Each packet can +be set to 'on' (the remote target supports this packet), 'off' (the +remote target does not support this packet), or 'auto' (detect remote +target support for this packet). They all default to 'auto'. For more +information about each packet, see *note Remote Protocol::. + + During normal use, you should not have to use any of these commands. +If you do, that may be a bug in your remote debugging stub, or a bug in +GDB. You may want to report the problem to the GDB developers. + + For each packet NAME, the command to enable or disable the packet is +'set remote NAME-packet'. The available settings are: + +Command Name Remote Packet Related Features + +'fetch-register' 'p' 'info registers' + +'set-register' 'P' 'set' + +'binary-download' 'X' 'load', 'set' + +'read-aux-vector' 'qXfer:auxv:read' 'info auxv' + +'symbol-lookup' 'qSymbol' Detecting + multiple threads + +'attach' 'vAttach' 'attach' + +'verbose-resume' 'vCont' Stepping or + resuming + multiple threads + +'run' 'vRun' 'run' + +'software-breakpoint''Z0' 'break' + +'hardware-breakpoint''Z1' 'hbreak' + +'write-watchpoint' 'Z2' 'watch' + +'read-watchpoint' 'Z3' 'rwatch' + +'access-watchpoint' 'Z4' 'awatch' + +'target-features' 'qXfer:features:read' 'set + architecture' + +'library-info' 'qXfer:libraries:read' 'info + sharedlibrary' + +'memory-map' 'qXfer:memory-map:read' 'info mem' + +'read-sdata-object' 'qXfer:sdata:read' 'print $_sdata' + +'read-spu-object' 'qXfer:spu:read' 'info spu' + +'write-spu-object' 'qXfer:spu:write' 'info spu' + +'read-siginfo-object''qXfer:siginfo:read' 'print + $_siginfo' + +'write-siginfo-object''qXfer:siginfo:write' 'set $_siginfo' + +'threads' 'qXfer:threads:read' 'info threads' + +'get-thread-local- 'qGetTLSAddr' Displaying +storage-address' '__thread' + variables + +'get-thread-information-block-address''qGetTIBAddr'Display + MS-Windows + Thread + Information + Block. + +'search-memory' 'qSearch:memory' 'find' + +'supported-packets' 'qSupported' Remote + communications + parameters + +'pass-signals' 'QPassSignals' 'handle SIGNAL' + +'program-signals' 'QProgramSignals' 'handle SIGNAL' + +'hostio-close-packet''vFile:close' 'remote get', + 'remote put' + +'hostio-open-packet' 'vFile:open' 'remote get', + 'remote put' + +'hostio-pread-packet''vFile:pread' 'remote get', + 'remote put' + +'hostio-pwrite-packet''vFile:pwrite' 'remote get', + 'remote put' + +'hostio-unlink-packet''vFile:unlink' 'remote delete' + +'hostio-readlink-packet''vFile:readlink' Host I/O + +'noack-packet' 'QStartNoAckMode' Packet + acknowledgment + +'osdata' 'qXfer:osdata:read' 'info os' + +'query-attached' 'qAttached' Querying remote + process attach + state. + +'trace-buffer-size' 'QTBuffer:size' 'set + trace-buffer-size' + +'trace-status' 'qTStatus' 'tstatus' + +'traceframe-info' 'qXfer:traceframe-info:read'Traceframe info + +'install-in-trace' 'InstallInTrace' Install + tracepoint in + tracing + +'disable-randomization''QDisableRandomization''set + disable-randomization' + +'conditional-breakpoints-packet''Z0 and Z1' 'Support for + target-side + breakpoint + condition + evaluation' + + +File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging + +20.5 Implementing a Remote Stub +=============================== + +The stub files provided with GDB implement the target side of the +communication protocol, and the GDB side is implemented in the GDB +source file 'remote.c'. Normally, you can simply allow these +subroutines to communicate, and ignore the details. (If you're +implementing your own stub file, you can still ignore the details: start +with one of the existing stub files. 'sparc-stub.c' is the best +organized, and therefore the easiest to read.) + + To debug a program running on another machine (the debugging "target" +machine), you must first arrange for all the usual prerequisites for the +program to run by itself. For example, for a C program, you need: + + 1. A startup routine to set up the C runtime environment; these + usually have a name like 'crt0'. The startup routine may be + supplied by your hardware supplier, or you may have to write your + own. + + 2. A C subroutine library to support your program's subroutine calls, + notably managing input and output. + + 3. A way of getting your program to the other machine--for example, a + download program. These are often supplied by the hardware + manufacturer, but you may have to write your own from hardware + documentation. + + The next step is to arrange for your program to use a serial port to +communicate with the machine where GDB is running (the "host" machine). +In general terms, the scheme looks like this: + +_On the host,_ + GDB already understands how to use this protocol; when everything + else is set up, you can simply use the 'target remote' command + (*note Specifying a Debugging Target: Targets.). + +_On the target,_ + you must link with your program a few special-purpose subroutines + that implement the GDB remote serial protocol. The file containing + these subroutines is called a "debugging stub". + + On certain remote targets, you can use an auxiliary program + 'gdbserver' instead of linking a stub into your program. *Note + Using the 'gdbserver' Program: Server, for details. + + The debugging stub is specific to the architecture of the remote +machine; for example, use 'sparc-stub.c' to debug programs on SPARC +boards. + + These working remote stubs are distributed with GDB: + +'i386-stub.c' + For Intel 386 and compatible architectures. + +'m68k-stub.c' + For Motorola 680x0 architectures. + +'sh-stub.c' + For Renesas SH architectures. + +'sparc-stub.c' + For SPARC architectures. + +'sparcl-stub.c' + For Fujitsu SPARCLITE architectures. + + The 'README' file in the GDB distribution may list other recently +added stubs. + +* Menu: + +* Stub Contents:: What the stub can do for you +* Bootstrapping:: What you must do for the stub +* Debug Session:: Putting it all together + + +File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub + +20.5.1 What the Stub Can Do for You +----------------------------------- + +The debugging stub for your architecture supplies these three +subroutines: + +'set_debug_traps' + This routine arranges for 'handle_exception' to run when your + program stops. You must call this subroutine explicitly in your + program's startup code. + +'handle_exception' + This is the central workhorse, but your program never calls it + explicitly--the setup code arranges for 'handle_exception' to run + when a trap is triggered. + + 'handle_exception' takes control when your program stops during + execution (for example, on a breakpoint), and mediates + communications with GDB on the host machine. This is where the + communications protocol is implemented; 'handle_exception' acts as + the GDB representative on the target machine. It begins by sending + summary information on the state of your program, then continues to + execute, retrieving and transmitting any information GDB needs, + until you execute a GDB command that makes your program resume; at + that point, 'handle_exception' returns control to your own code on + the target machine. + +'breakpoint' + Use this auxiliary subroutine to make your program contain a + breakpoint. Depending on the particular situation, this may be the + only way for GDB to get control. For instance, if your target + machine has some sort of interrupt button, you won't need to call + this; pressing the interrupt button transfers control to + 'handle_exception'--in effect, to GDB. On some machines, simply + receiving characters on the serial port may also trigger a trap; + again, in that situation, you don't need to call 'breakpoint' from + your own program--simply running 'target remote' from the host GDB + session gets control. + + Call 'breakpoint' if none of these is true, or if you simply want + to make certain your program stops at a predetermined point for the + start of your debugging session. + + +File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Stub + +20.5.2 What You Must Do for the Stub +------------------------------------ + +The debugging stubs that come with GDB are set up for a particular chip +architecture, but they have no information about the rest of your +debugging target machine. + + First of all you need to tell the stub how to communicate with the +serial port. + +'int getDebugChar()' + Write this subroutine to read a single character from the serial + port. It may be identical to 'getchar' for your target system; a + different name is used to allow you to distinguish the two if you + wish. + +'void putDebugChar(int)' + Write this subroutine to write a single character to the serial + port. It may be identical to 'putchar' for your target system; a + different name is used to allow you to distinguish the two if you + wish. + + If you want GDB to be able to stop your program while it is running, +you need to use an interrupt-driven serial driver, and arrange for it to +stop when it receives a '^C' ('\003', the control-C character). That is +the character which GDB uses to tell the remote system to stop. + + Getting the debugging target to return the proper status to GDB +probably requires changes to the standard stub; one quick and dirty way +is to just execute a breakpoint instruction (the "dirty" part is that +GDB reports a 'SIGTRAP' instead of a 'SIGINT'). + + Other routines you need to supply are: + +'void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' + Write this function to install EXCEPTION_ADDRESS in the exception + handling tables. You need to do this because the stub does not + have any way of knowing what the exception handling tables on your + target system are like (for example, the processor's table might be + in ROM, containing entries which point to a table in RAM). + EXCEPTION_NUMBER is the exception number which should be changed; + its meaning is architecture-dependent (for example, different + numbers might represent divide by zero, misaligned access, etc). + When this exception occurs, control should be transferred directly + to EXCEPTION_ADDRESS, and the processor state (stack, registers, + and so on) should be just as it is when a processor exception + occurs. So if you want to use a jump instruction to reach + EXCEPTION_ADDRESS, it should be a simple jump, not a jump to + subroutine. + + For the 386, EXCEPTION_ADDRESS should be installed as an interrupt + gate so that interrupts are masked while the handler runs. The + gate should be at privilege level 0 (the most privileged level). + The SPARC and 68k stubs are able to mask interrupts themselves + without help from 'exceptionHandler'. + +'void flush_i_cache()' + On SPARC and SPARCLITE only, write this subroutine to flush the + instruction cache, if any, on your target machine. If there is no + instruction cache, this subroutine may be a no-op. + + On target machines that have instruction caches, GDB requires this + function to make certain that the state of your program is stable. + +You must also make sure this library routine is available: + +'void *memset(void *, int, int)' + This is the standard library function 'memset' that sets an area of + memory to a known value. If you have one of the free versions of + 'libc.a', 'memset' can be found there; otherwise, you must either + obtain it from your hardware manufacturer, or write your own. + + If you do not use the GNU C compiler, you may need other standard +library subroutines as well; this varies from one stub to another, but +in general the stubs are likely to use any of the common library +subroutines which 'GCC' generates as inline code. + + +File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: Remote Stub + +20.5.3 Putting it All Together +------------------------------ + +In summary, when your program is ready to debug, you must follow these +steps. + + 1. Make sure you have defined the supporting low-level routines (*note + What You Must Do for the Stub: Bootstrapping.): + 'getDebugChar', 'putDebugChar', + 'flush_i_cache', 'memset', 'exceptionHandler'. + + 2. Insert these lines in your program's startup code, before the main + procedure is called: + + set_debug_traps(); + breakpoint(); + + On some machines, when a breakpoint trap is raised, the hardware + automatically makes the PC point to the instruction after the + breakpoint. If your machine doesn't do that, you may need to + adjust 'handle_exception' to arrange for it to return to the + instruction after the breakpoint on this first invocation, so that + your program doesn't keep hitting the initial breakpoint instead of + making progress. + + 3. For the 680x0 stub only, you need to provide a variable called + 'exceptionHook'. Normally you just use: + + void (*exceptionHook)() = 0; + + but if before calling 'set_debug_traps', you set it to point to a + function in your program, that function is called when 'GDB' + continues after stopping on a trap (for example, bus error). The + function indicated by 'exceptionHook' is called with one parameter: + an 'int' which is the exception number. + + 4. Compile and link together: your program, the GDB debugging stub for + your target architecture, and the supporting subroutines. + + 5. Make sure you have a serial connection between your target machine + and the GDB host, and identify the serial port on the host. + + 6. Download your program to your target machine (or get it there by + whatever means the manufacturer provides), and start it. + + 7. Start GDB on the host, and connect to the target (*note Connecting + to a Remote Target: Connecting.). + + +File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top + +21 Configuration-Specific Information +************************************* + +While nearly all GDB commands are available for all native and cross +versions of the debugger, there are some exceptions. This chapter +describes things that are only available in certain configurations. + + There are three major categories of configurations: native +configurations, where the host and target are the same, embedded +operating system configurations, which are usually the same for several +different processor architectures, and bare embedded processors, which +are quite different from each other. + +* Menu: + +* Native:: +* Embedded OS:: +* Embedded Processors:: +* Architectures:: + + +File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations + +21.1 Native +=========== + +This section describes details specific to particular native +configurations. + +* Menu: + +* HP-UX:: HP-UX +* BSD libkvm Interface:: Debugging BSD kernel memory images +* SVR4 Process Information:: SVR4 process information +* DJGPP Native:: Features specific to the DJGPP port +* Cygwin Native:: Features specific to the Cygwin port +* Hurd Native:: Features specific to GNU Hurd +* Darwin:: Features specific to Darwin + + +File: gdb.info, Node: HP-UX, Next: BSD libkvm Interface, Up: Native + +21.1.1 HP-UX +------------ + +On HP-UX systems, if you refer to a function or variable name that +begins with a dollar sign, GDB searches for a user or system name first, +before it searches for a convenience variable. + + +File: gdb.info, Node: BSD libkvm Interface, Next: SVR4 Process Information, Prev: HP-UX, Up: Native + +21.1.2 BSD libkvm Interface +--------------------------- + +BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory +interface that provides a uniform interface for accessing kernel virtual +memory images, including live systems and crash dumps. GDB uses this +interface to allow you to debug live kernels and kernel crash dumps on +many native BSD configurations. This is implemented as a special 'kvm' +debugging target. For debugging a live system, load the currently +running kernel into GDB and connect to the 'kvm' target: + + (gdb) target kvm + + For debugging crash dumps, provide the file name of the crash dump as +an argument: + + (gdb) target kvm /var/crash/bsd.0 + + Once connected to the 'kvm' target, the following commands are +available: + +'kvm pcb' + Set current context from the "Process Control Block" (PCB) address. + +'kvm proc' + Set current context from proc address. This command isn't + available on modern FreeBSD systems. + + +File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native + +21.1.3 SVR4 Process Information +------------------------------- + +Many versions of SVR4 and compatible systems provide a facility called +'/proc' that can be used to examine the image of a running process using +file-system subroutines. + + If GDB is configured for an operating system with this facility, the +command 'info proc' is available to report information about the process +running your program, or about any process running on your system. This +includes, as of this writing, GNU/Linux, OSF/1 (Digital Unix), Solaris, +and Irix, but not HP-UX, for example. + + This command may also work on core files that were created on a +system that has the '/proc' facility. + +'info proc' +'info proc PROCESS-ID' + Summarize available information about any running process. If a + process ID is specified by PROCESS-ID, display information about + that process; otherwise display information about the program being + debugged. The summary includes the debugged process ID, the + command line used to invoke it, its current working directory, and + its executable file's absolute file name. + + On some systems, PROCESS-ID can be of the form '[PID]/TID' which + specifies a certain thread ID within a process. If the optional + PID part is missing, it means a thread from the process being + debugged (the leading '/' still needs to be present, or else GDB + will interpret the number as a process ID rather than a thread ID). + +'info proc cmdline' + Show the original command line of the process. This command is + specific to GNU/Linux. + +'info proc cwd' + Show the current working directory of the process. This command is + specific to GNU/Linux. + +'info proc exe' + Show the name of executable of the process. This command is + specific to GNU/Linux. + +'info proc mappings' + Report the memory address space ranges accessible in the program, + with information on whether the process has read, write, or execute + access rights to each range. On GNU/Linux systems, each memory + range includes the object file which is mapped to that range, + instead of the memory access rights to that range. + +'info proc stat' +'info proc status' + These subcommands are specific to GNU/Linux systems. They show the + process-related information, including the user ID and group ID; + how many threads are there in the process; its virtual memory + usage; the signals that are pending, blocked, and ignored; its TTY; + its consumption of system and user time; its stack size; its 'nice' + value; etc. For more information, see the 'proc' man page (type + 'man 5 proc' from your shell prompt). + +'info proc all' + Show all the information about the process described under all of + the above 'info proc' subcommands. + +'set procfs-trace' + This command enables and disables tracing of 'procfs' API calls. + +'show procfs-trace' + Show the current state of 'procfs' API call tracing. + +'set procfs-file FILE' + Tell GDB to write 'procfs' API trace to the named FILE. GDB + appends the trace info to the previous contents of the file. The + default is to display the trace on the standard output. + +'show procfs-file' + Show the file to which 'procfs' API trace is written. + +'proc-trace-entry' +'proc-trace-exit' +'proc-untrace-entry' +'proc-untrace-exit' + These commands enable and disable tracing of entries into and exits + from the 'syscall' interface. + +'info pidlist' + For QNX Neutrino only, this command displays the list of all the + processes and all the threads within each process. + +'info meminfo' + For QNX Neutrino only, this command displays the list of all + mapinfos. + + +File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native + +21.1.4 Features for Debugging DJGPP Programs +-------------------------------------------- + +DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows. +DJGPP programs are 32-bit protected-mode programs that use the "DPMI" +(DOS Protected-Mode Interface) API to run on top of real-mode DOS +systems and their emulations. + + GDB supports native debugging of DJGPP programs, and defines a few +commands specific to the DJGPP port. This subsection describes those +commands. + +'info dos' + This is a prefix of DJGPP-specific commands which print information + about the target system and important OS structures. + +'info dos sysinfo' + This command displays assorted information about the underlying + platform: the CPU type and features, the OS version and flavor, the + DPMI version, and the available conventional and DPMI memory. + +'info dos gdt' +'info dos ldt' +'info dos idt' + These 3 commands display entries from, respectively, Global, Local, + and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor + tables are data structures which store a descriptor for each + segment that is currently in use. The segment's selector is an + index into a descriptor table; the table entry for that index holds + the descriptor's base address and limit, and its attributes and + access rights. + + A typical DJGPP program uses 3 segments: a code segment, a data + segment (used for both data and the stack), and a DOS segment + (which allows access to DOS/BIOS data structures and absolute + addresses in conventional memory). However, the DPMI host will + usually define additional segments in order to support the DPMI + environment. + + These commands allow to display entries from the descriptor tables. + Without an argument, all entries from the specified table are + displayed. An argument, which should be an integer expression, + means display a single entry whose index is given by the argument. + For example, here's a convenient way to display information about + the debugged program's data segment: + + (gdb) info dos ldt $ds + 0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up) + + This comes in handy when you want to see whether a pointer is + outside the data segment's limit (i.e. "garbled"). + +'info dos pde' +'info dos pte' + These two commands display entries from, respectively, the Page + Directory and the Page Tables. Page Directories and Page Tables + are data structures which control how virtual memory addresses are + mapped into physical addresses. A Page Table includes an entry for + every page of memory that is mapped into the program's address + space; there may be several Page Tables, each one holding up to + 4096 entries. A Page Directory has up to 4096 entries, one each + for every Page Table that is currently in use. + + Without an argument, 'info dos pde' displays the entire Page + Directory, and 'info dos pte' displays all the entries in all of + the Page Tables. An argument, an integer expression, given to the + 'info dos pde' command means display only that entry from the Page + Directory table. An argument given to the 'info dos pte' command + means display entries from a single Page Table, the one pointed to + by the specified entry in the Page Directory. + + These commands are useful when your program uses "DMA" (Direct + Memory Access), which needs physical addresses to program the DMA + controller. + + These commands are supported only with some DPMI servers. + +'info dos address-pte ADDR' + This command displays the Page Table entry for a specified linear + address. The argument ADDR is a linear address which should + already have the appropriate segment's base address added to it, + because this command accepts addresses which may belong to _any_ + segment. For example, here's how to display the Page Table entry + for the page where a variable 'i' is stored: + + (gdb) info dos address-pte __djgpp_base_address + (char *)&i + Page Table entry for address 0x11a00d30: + Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30 + + This says that 'i' is stored at offset '0xd30' from the page whose + physical base address is '0x02698000', and shows all the attributes + of that page. + + Note that you must cast the addresses of variables to a 'char *', + since otherwise the value of '__djgpp_base_address', the base + address of all variables and functions in a DJGPP program, will be + added using the rules of C pointer arithmetics: if 'i' is declared + an 'int', GDB will add 4 times the value of '__djgpp_base_address' + to the address of 'i'. + + Here's another example, it displays the Page Table entry for the + transfer buffer: + + (gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3) + Page Table entry for address 0x29110: + Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110 + + (The '+ 3' offset is because the transfer buffer's address is the + 3rd member of the '_go32_info_block' structure.) The output + clearly shows that this DPMI server maps the addresses in + conventional memory 1:1, i.e. the physical ('0x00029000' + '0x110') + and linear ('0x29110') addresses are identical. + + This command is supported only with some DPMI servers. + + In addition to native debugging, the DJGPP port supports remote +debugging via a serial data link. The following commands are specific +to remote serial debugging in the DJGPP port of GDB. + +'set com1base ADDR' + This command sets the base I/O port address of the 'COM1' serial + port. + +'set com1irq IRQ' + This command sets the "Interrupt Request" ('IRQ') line to use for + the 'COM1' serial port. + + There are similar commands 'set com2base', 'set com3irq', etc. for + setting the port address and the 'IRQ' lines for the other 3 COM + ports. + + The related commands 'show com1base', 'show com1irq' etc. display + the current settings of the base address and the 'IRQ' lines used + by the COM ports. + +'info serial' + This command prints the status of the 4 DOS serial ports. For each + port, it prints whether it's active or not, its I/O base address + and IRQ number, whether it uses a 16550-style FIFO, its baudrate, + and the counts of various errors encountered so far. + + +File: gdb.info, Node: Cygwin Native, Next: Hurd Native, Prev: DJGPP Native, Up: Native + +21.1.5 Features for Debugging MS Windows PE Executables +------------------------------------------------------- + +GDB supports native debugging of MS Windows programs, including DLLs +with and without symbolic debugging information. + + MS-Windows programs that call 'SetConsoleMode' to switch off the +special meaning of the 'Ctrl-C' keystroke cannot be interrupted by +typing 'C-c'. For this reason, GDB on MS-Windows supports 'C-' +as an alternative interrupt key sequence, which can be used to interrupt +the debuggee even if it ignores 'C-c'. + + There are various additional Cygwin-specific commands, described in +this section. Working with DLLs that have no debugging symbols is +described in *note Non-debug DLL Symbols::. + +'info w32' + This is a prefix of MS Windows-specific commands which print + information about the target system and important OS structures. + +'info w32 selector' + This command displays information returned by the Win32 API + 'GetThreadSelectorEntry' function. It takes an optional argument + that is evaluated to a long value to give the information about + this given selector. Without argument, this command displays + information about the six segment registers. + +'info w32 thread-information-block' + This command displays thread specific information stored in the + Thread Information Block (readable on the X86 CPU family using + '$fs' selector for 32-bit programs and '$gs' for 64-bit programs). + +'info dll' + This is a Cygwin-specific alias of 'info shared'. + +'dll-symbols' + This command loads symbols from a dll similarly to add-sym command + but without the need to specify a base address. + +'set cygwin-exceptions MODE' + If MODE is 'on', GDB will break on exceptions that happen inside + the Cygwin DLL. If MODE is 'off', GDB will delay recognition of + exceptions, and may ignore some exceptions which seem to be caused + by internal Cygwin DLL "bookkeeping". This option is meant + primarily for debugging the Cygwin DLL itself; the default value is + 'off' to avoid annoying GDB users with false 'SIGSEGV' signals. + +'show cygwin-exceptions' + Displays whether GDB will break on exceptions that happen inside + the Cygwin DLL itself. + +'set new-console MODE' + If MODE is 'on' the debuggee will be started in a new console on + next start. If MODE is 'off', the debuggee will be started in the + same console as the debugger. + +'show new-console' + Displays whether a new console is used when the debuggee is + started. + +'set new-group MODE' + This boolean value controls whether the debuggee should start a new + group or stay in the same group as the debugger. This affects the + way the Windows OS handles 'Ctrl-C'. + +'show new-group' + Displays current value of new-group boolean. + +'set debugevents' + This boolean value adds debug output concerning kernel events + related to the debuggee seen by the debugger. This includes events + that signal thread and process creation and exit, DLL loading and + unloading, console interrupts, and debugging messages produced by + the Windows 'OutputDebugString' API call. + +'set debugexec' + This boolean value adds debug output concerning execute events + (such as resume thread) seen by the debugger. + +'set debugexceptions' + This boolean value adds debug output concerning exceptions in the + debuggee seen by the debugger. + +'set debugmemory' + This boolean value adds debug output concerning debuggee memory + reads and writes by the debugger. + +'set shell' + This boolean values specifies whether the debuggee is called via a + shell or directly (default value is on). + +'show shell' + Displays if the debuggee will be started with a shell. + +* Menu: + +* Non-debug DLL Symbols:: Support for DLLs without debugging symbols + + +File: gdb.info, Node: Non-debug DLL Symbols, Up: Cygwin Native + +21.1.5.1 Support for DLLs without Debugging Symbols +................................................... + +Very often on windows, some of the DLLs that your program relies on do +not include symbolic debugging information (for example, +'kernel32.dll'). When GDB doesn't recognize any debugging symbols in a +DLL, it relies on the minimal amount of symbolic information contained +in the DLL's export table. This section describes working with such +symbols, known internally to GDB as "minimal symbols". + + Note that before the debugged program has started execution, no DLLs +will have been loaded. The easiest way around this problem is simply to +start the program -- either by setting a breakpoint or letting the +program run once to completion. It is also possible to force GDB to +load a particular DLL before starting the executable -- see the shared +library information in *note Files::, or the 'dll-symbols' command in +*note Cygwin Native::. Currently, explicitly loading symbols from a DLL +with no debugging information will cause the symbol names to be +duplicated in GDB's lookup table, which may adversely affect symbol +lookup performance. + +21.1.5.2 DLL Name Prefixes +.......................... + +In keeping with the naming conventions used by the Microsoft debugging +tools, DLL export symbols are made available with a prefix based on the +DLL name, for instance 'KERNEL32!CreateFileA'. The plain name is also +entered into the symbol table, so 'CreateFileA' is often sufficient. In +some cases there will be name clashes within a program (particularly if +the executable itself includes full debugging symbols) necessitating the +use of the fully qualified name when referring to the contents of the +DLL. Use single-quotes around the name to avoid the exclamation mark +("!") being interpreted as a language operator. + + Note that the internal name of the DLL may be all upper-case, even +though the file name of the DLL is lower-case, or vice-versa. Since +symbols within GDB are _case-sensitive_ this may cause some confusion. +If in doubt, try the 'info functions' and 'info variables' commands or +even 'maint print msymbols' (*note Symbols::). Here's an example: + + (gdb) info function CreateFileA + All functions matching regular expression "CreateFileA": + + Non-debugging symbols: + 0x77e885f4 CreateFileA + 0x77e885f4 KERNEL32!CreateFileA + + (gdb) info function ! + All functions matching regular expression "!": + + Non-debugging symbols: + 0x6100114c cygwin1!__assert + 0x61004034 cygwin1!_dll_crt0@0 + 0x61004240 cygwin1!dll_crt0(per_process *) + [etc...] + +21.1.5.3 Working with Minimal Symbols +..................................... + +Symbols extracted from a DLL's export table do not contain very much +type information. All that GDB can do is guess whether a symbol refers +to a function or variable depending on the linker section that contains +the symbol. Also note that the actual contents of the memory contained +in a DLL are not available unless the program is running. This means +that you cannot examine the contents of a variable or disassemble a +function within a DLL without a running program. + + Variables are generally treated as pointers and dereferenced +automatically. For this reason, it is often necessary to prefix a +variable name with the address-of operator ("&") and provide explicit +type information in the command. Here's an example of the type of +problem: + + (gdb) print 'cygwin1!__argv' + $1 = 268572168 + + (gdb) x 'cygwin1!__argv' + 0x10021610: "\230y\"" + + And two possible solutions: + + (gdb) print ((char **)'cygwin1!__argv')[0] + $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" + + (gdb) x/2x &'cygwin1!__argv' + 0x610c0aa8 : 0x10021608 0x00000000 + (gdb) x/x 0x10021608 + 0x10021608: 0x0022fd98 + (gdb) x/s 0x0022fd98 + 0x22fd98: "/cygdrive/c/mydirectory/myprogram" + + Setting a break point within a DLL is possible even before the +program starts execution. However, under these circumstances, GDB can't +examine the initial instructions of the function in order to skip the +function's frame set-up code. You can work around this by using "*&" to +set the breakpoint at a raw memory address: + + (gdb) break *&'python22!PyOS_Readline' + Breakpoint 1 at 0x1e04eff0 + + The author of these extensions is not entirely convinced that setting +a break point within a shared DLL like 'kernel32.dll' is completely +safe. + + +File: gdb.info, Node: Hurd Native, Next: Darwin, Prev: Cygwin Native, Up: Native + +21.1.6 Commands Specific to GNU Hurd Systems +-------------------------------------------- + +This subsection describes GDB commands specific to the GNU Hurd native +debugging. + +'set signals' +'set sigs' + This command toggles the state of inferior signal interception by + GDB. Mach exceptions, such as breakpoint traps, are not affected + by this command. 'sigs' is a shorthand alias for 'signals'. + +'show signals' +'show sigs' + Show the current state of intercepting inferior's signals. + +'set signal-thread' +'set sigthread' + This command tells GDB which thread is the 'libc' signal thread. + That thread is run when a signal is delivered to a running process. + 'set sigthread' is the shorthand alias of 'set signal-thread'. + +'show signal-thread' +'show sigthread' + These two commands show which thread will run when the inferior is + delivered a signal. + +'set stopped' + This commands tells GDB that the inferior process is stopped, as + with the 'SIGSTOP' signal. The stopped process can be continued by + delivering a signal to it. + +'show stopped' + This command shows whether GDB thinks the debuggee is stopped. + +'set exceptions' + Use this command to turn off trapping of exceptions in the + inferior. When exception trapping is off, neither breakpoints nor + single-stepping will work. To restore the default, set exception + trapping on. + +'show exceptions' + Show the current state of trapping exceptions in the inferior. + +'set task pause' + This command toggles task suspension when GDB has control. Setting + it to on takes effect immediately, and the task is suspended + whenever GDB gets control. Setting it to off will take effect the + next time the inferior is continued. If this option is set to off, + you can use 'set thread default pause on' or 'set thread pause on' + (see below) to pause individual threads. + +'show task pause' + Show the current state of task suspension. + +'set task detach-suspend-count' + This command sets the suspend count the task will be left with when + GDB detaches from it. + +'show task detach-suspend-count' + Show the suspend count the task will be left with when detaching. + +'set task exception-port' +'set task excp' + This command sets the task exception port to which GDB will forward + exceptions. The argument should be the value of the "send rights" + of the task. 'set task excp' is a shorthand alias. + +'set noninvasive' + This command switches GDB to a mode that is the least invasive as + far as interfering with the inferior is concerned. This is the + same as using 'set task pause', 'set exceptions', and 'set signals' + to values opposite to the defaults. + +'info send-rights' +'info receive-rights' +'info port-rights' +'info port-sets' +'info dead-names' +'info ports' +'info psets' + These commands display information about, respectively, send + rights, receive rights, port rights, port sets, and dead names of a + task. There are also shorthand aliases: 'info ports' for 'info + port-rights' and 'info psets' for 'info port-sets'. + +'set thread pause' + This command toggles current thread suspension when GDB has + control. Setting it to on takes effect immediately, and the + current thread is suspended whenever GDB gets control. Setting it + to off will take effect the next time the inferior is continued. + Normally, this command has no effect, since when GDB has control, + the whole task is suspended. However, if you used 'set task pause + off' (see above), this command comes in handy to suspend only the + current thread. + +'show thread pause' + This command shows the state of current thread suspension. + +'set thread run' + This command sets whether the current thread is allowed to run. + +'show thread run' + Show whether the current thread is allowed to run. + +'set thread detach-suspend-count' + This command sets the suspend count GDB will leave on a thread when + detaching. This number is relative to the suspend count found by + GDB when it notices the thread; use 'set thread + takeover-suspend-count' to force it to an absolute value. + +'show thread detach-suspend-count' + Show the suspend count GDB will leave on the thread when detaching. + +'set thread exception-port' +'set thread excp' + Set the thread exception port to which to forward exceptions. This + overrides the port set by 'set task exception-port' (see above). + 'set thread excp' is the shorthand alias. + +'set thread takeover-suspend-count' + Normally, GDB's thread suspend counts are relative to the value GDB + finds when it notices each thread. This command changes the + suspend counts to be absolute instead. + +'set thread default' +'show thread default' + Each of the above 'set thread' commands has a 'set thread default' + counterpart (e.g., 'set thread default pause', 'set thread default + exception-port', etc.). The 'thread default' variety of commands + sets the default thread properties for all threads; you can then + change the properties of individual threads with the non-default + commands. + + +File: gdb.info, Node: Darwin, Prev: Hurd Native, Up: Native + +21.1.7 Darwin +------------- + +GDB provides the following commands specific to the Darwin target: + +'set debug darwin NUM' + When set to a non zero value, enables debugging messages specific + to the Darwin support. Higher values produce more verbose output. + +'show debug darwin' + Show the current state of Darwin messages. + +'set debug mach-o NUM' + When set to a non zero value, enables debugging messages while GDB + is reading Darwin object files. ("Mach-O" is the file format used + on Darwin for object and executable files.) Higher values produce + more verbose output. This is a command to diagnose problems + internal to GDB and should not be needed in normal usage. + +'show debug mach-o' + Show the current state of Mach-O file messages. + +'set mach-exceptions on' +'set mach-exceptions off' + On Darwin, faults are first reported as a Mach exception and are + then mapped to a Posix signal. Use this command to turn on + trapping of Mach exceptions in the inferior. This might be + sometimes useful to better understand the cause of a fault. The + default is off. + +'show mach-exceptions' + Show the current state of exceptions trapping. + + +File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations + +21.2 Embedded Operating Systems +=============================== + +This section describes configurations involving the debugging of +embedded operating systems that are available for several different +architectures. + +* Menu: + +* VxWorks:: Using GDB with VxWorks + + GDB includes the ability to debug programs running on various +real-time operating systems. + + +File: gdb.info, Node: VxWorks, Up: Embedded OS + +21.2.1 Using GDB with VxWorks +----------------------------- + +'target vxworks MACHINENAME' + A VxWorks system, attached via TCP/IP. The argument MACHINENAME is + the target system's machine name or IP address. + + On VxWorks, 'load' links FILENAME dynamically on the current target +system as well as adding its symbols in GDB. + + GDB enables developers to spawn and debug tasks running on networked +VxWorks targets from a Unix host. Already-running tasks spawned from +the VxWorks shell can also be debugged. GDB uses code that runs on both +the Unix host and on the VxWorks target. The program 'gdb' is installed +and executed on the Unix host. (It may be installed with the name +'vxgdb', to distinguish it from a GDB for debugging programs on the host +itself.) + +'VxWorks-timeout ARGS' + All VxWorks-based targets now support the option 'vxworks-timeout'. + This option is set by the user, and ARGS represents the number of + seconds GDB waits for responses to rpc's. You might use this if + your VxWorks target is a slow software simulator or is on the far + side of a thin network line. + + The following information on connecting to VxWorks was current when +this manual was produced; newer releases of VxWorks may use revised +procedures. + + To use GDB with VxWorks, you must rebuild your VxWorks kernel to +include the remote debugging interface routines in the VxWorks library +'rdb.a'. To do this, define 'INCLUDE_RDB' in the VxWorks configuration +file 'configAll.h' and rebuild your VxWorks kernel. The resulting +kernel contains 'rdb.a', and spawns the source debugging task 'tRdbTask' +when VxWorks is booted. For more information on configuring and +remaking VxWorks, see the manufacturer's manual. + + Once you have included 'rdb.a' in your VxWorks system image and set +your Unix execution search path to find GDB, you are ready to run GDB. +From your Unix host, run 'gdb' (or 'vxgdb', depending on your +installation). + + GDB comes up showing the prompt: + + (vxgdb) + +* Menu: + +* VxWorks Connection:: Connecting to VxWorks +* VxWorks Download:: VxWorks download +* VxWorks Attach:: Running tasks + + +File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks + +21.2.1.1 Connecting to VxWorks +.............................. + +The GDB command 'target' lets you connect to a VxWorks target on the +network. To connect to a target whose host name is "'tt'", type: + + (vxgdb) target vxworks tt + + GDB displays messages like these: + + Attaching remote machine across net... + Connected to tt. + + GDB then attempts to read the symbol tables of any object modules +loaded into the VxWorks target since it was last booted. GDB locates +these files by searching the directories listed in the command search +path (*note Your Program's Environment: Environment.); if it fails to +find an object file, it displays a message such as: + + prog.o: No such file or directory. + + When this happens, add the appropriate directory to the search path +with the GDB command 'path', and execute the 'target' command again. + + +File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks + +21.2.1.2 VxWorks Download +......................... + +If you have connected to the VxWorks target and you want to debug an +object that has not yet been loaded, you can use the GDB 'load' command +to download a file from Unix to VxWorks incrementally. The object file +given as an argument to the 'load' command is actually opened twice: +first by the VxWorks target in order to download the code, then by GDB +in order to read the symbol table. This can lead to problems if the +current working directories on the two systems differ. If both systems +have NFS mounted the same filesystems, you can avoid these problems by +using absolute paths. Otherwise, it is simplest to set the working +directory on both systems to the directory in which the object file +resides, and then to reference the file by its name, without any path. +For instance, a program 'prog.o' may reside in 'VXPATH/vw/demo/rdb' in +VxWorks and in 'HOSTPATH/vw/demo/rdb' on the host. To load this +program, type this on VxWorks: + + -> cd "VXPATH/vw/demo/rdb" + +Then, in GDB, type: + + (vxgdb) cd HOSTPATH/vw/demo/rdb + (vxgdb) load prog.o + + GDB displays a response similar to this: + + Reading symbol data from wherever/vw/demo/rdb/prog.o... done. + + You can also use the 'load' command to reload an object module after +editing and recompiling the corresponding source file. Note that this +makes GDB delete all currently-defined breakpoints, auto-displays, and +convenience variables, and to clear the value history. (This is +necessary in order to preserve the integrity of debugger's data +structures that reference the target system's symbol table.) + + +File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks + +21.2.1.3 Running Tasks +...................... + +You can also attach to an existing task using the 'attach' command as +follows: + + (vxgdb) attach TASK + +where TASK is the VxWorks hexadecimal task ID. The task can be running +or suspended when you attach to it. Running tasks are suspended at the +time of attachment. + + +File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations + +21.3 Embedded Processors +======================== + +This section goes into details specific to particular embedded +configurations. + + Whenever a specific embedded processor has a simulator, GDB allows to +send an arbitrary command to the simulator. + +'sim COMMAND' + Send an arbitrary COMMAND string to the simulator. Consult the + documentation for the specific simulator in use for information + about acceptable commands. + +* Menu: + +* ARM:: ARM RDI +* M32R/D:: Renesas M32R/D +* M68K:: Motorola M68K +* MicroBlaze:: Xilinx MicroBlaze +* MIPS Embedded:: MIPS Embedded +* PowerPC Embedded:: PowerPC Embedded +* PA:: HP PA Embedded +* Sparclet:: Tsqware Sparclet +* Sparclite:: Fujitsu Sparclite +* Z8000:: Zilog Z8000 +* AVR:: Atmel AVR +* CRIS:: CRIS +* Super-H:: Renesas Super-H + + +File: gdb.info, Node: ARM, Next: M32R/D, Up: Embedded Processors + +21.3.1 ARM +---------- + +'target rdi DEV' + ARM Angel monitor, via RDI library interface to ADP protocol. You + may use this target to communicate with both boards running the + Angel monitor, or with the EmbeddedICE JTAG debug device. + +'target rdp DEV' + ARM Demon monitor. + + GDB provides the following ARM-specific commands: + +'set arm disassembler' + This commands selects from a list of disassembly styles. The + '"std"' style is the standard style. + +'show arm disassembler' + Show the current disassembly style. + +'set arm apcs32' + This command toggles ARM operation mode between 32-bit and 26-bit. + +'show arm apcs32' + Display the current usage of the ARM 32-bit mode. + +'set arm fpu FPUTYPE' + This command sets the ARM floating-point unit (FPU) type. The + argument FPUTYPE can be one of these: + + 'auto' + Determine the FPU type by querying the OS ABI. + 'softfpa' + Software FPU, with mixed-endian doubles on little-endian ARM + processors. + 'fpa' + GCC-compiled FPA co-processor. + 'softvfp' + Software FPU with pure-endian doubles. + 'vfp' + VFP co-processor. + +'show arm fpu' + Show the current type of the FPU. + +'set arm abi' + This command forces GDB to use the specified ABI. + +'show arm abi' + Show the currently used ABI. + +'set arm fallback-mode (arm|thumb|auto)' + GDB uses the symbol table, when available, to determine whether + instructions are ARM or Thumb. This command controls GDB's default + behavior when the symbol table is not available. The default is + 'auto', which causes GDB to use the current execution mode (from + the 'T' bit in the 'CPSR' register). + +'show arm fallback-mode' + Show the current fallback instruction mode. + +'set arm force-mode (arm|thumb|auto)' + This command overrides use of the symbol table to determine whether + instructions are ARM or Thumb. The default is 'auto', which causes + GDB to use the symbol table and then the setting of 'set arm + fallback-mode'. + +'show arm force-mode' + Show the current forced instruction mode. + +'set debug arm' + Toggle whether to display ARM-specific debugging messages from the + ARM target support subsystem. + +'show debug arm' + Show whether ARM-specific debugging messages are enabled. + + The following commands are available when an ARM target is debugged +using the RDI interface: + +'rdilogfile [FILE]' + Set the filename for the ADP (Angel Debugger Protocol) packet log. + With an argument, sets the log file to the specified FILE. With no + argument, show the current log file name. The default log file is + 'rdi.log'. + +'rdilogenable [ARG]' + Control logging of ADP packets. With an argument of 1 or '"yes"' + enables logging, with an argument 0 or '"no"' disables it. With no + arguments displays the current setting. When logging is enabled, + ADP packets exchanged between GDB and the RDI target device are + logged to a file. + +'set rdiromatzero' + Tell GDB whether the target has ROM at address 0. If on, vector + catching is disabled, so that zero address can be used. If off + (the default), vector catching is enabled. For this command to + take effect, it needs to be invoked prior to the 'target rdi' + command. + +'show rdiromatzero' + Show the current setting of ROM at zero address. + +'set rdiheartbeat' + Enable or disable RDI heartbeat packets. It is not recommended to + turn on this option, since it confuses ARM and EPI JTAG interface, + as well as the Angel monitor. + +'show rdiheartbeat' + Show the setting of RDI heartbeat packets. + +'target sim [SIMARGS] ...' + The GDB ARM simulator accepts the following optional arguments. + + '--swi-support=TYPE' + Tell the simulator which SWI interfaces to support. TYPE may + be a comma separated list of the following values. The + default value is 'all'. + + 'none' + 'demon' + 'angel' + 'redboot' + 'all' + + +File: gdb.info, Node: M32R/D, Next: M68K, Prev: ARM, Up: Embedded Processors + +21.3.2 Renesas M32R/D and M32R/SDI +---------------------------------- + +'target m32r DEV' + Renesas M32R/D ROM monitor. + +'target m32rsdi DEV' + Renesas M32R SDI server, connected via parallel port to the board. + + The following GDB commands are specific to the M32R monitor: + +'set download-path PATH' + Set the default path for finding downloadable SREC files. + +'show download-path' + Show the default path for downloadable SREC files. + +'set board-address ADDR' + Set the IP address for the M32R-EVA target board. + +'show board-address' + Show the current IP address of the target board. + +'set server-address ADDR' + Set the IP address for the download server, which is the GDB's host + machine. + +'show server-address' + Display the IP address of the download server. + +'upload [FILE]' + Upload the specified SREC FILE via the monitor's Ethernet upload + capability. If no FILE argument is given, the current executable + file is uploaded. + +'tload [FILE]' + Test the 'upload' command. + + The following commands are available for M32R/SDI: + +'sdireset' + This command resets the SDI connection. + +'sdistatus' + This command shows the SDI connection status. + +'debug_chaos' + Instructs the remote that M32R/Chaos debugging is to be used. + +'use_debug_dma' + Instructs the remote to use the DEBUG_DMA method of accessing + memory. + +'use_mon_code' + Instructs the remote to use the MON_CODE method of accessing + memory. + +'use_ib_break' + Instructs the remote to set breakpoints by IB break. + +'use_dbt_break' + Instructs the remote to set breakpoints by DBT. + + +File: gdb.info, Node: M68K, Next: MicroBlaze, Prev: M32R/D, Up: Embedded Processors + +21.3.3 M68k +----------- + +The Motorola m68k configuration includes ColdFire support, and a target +command for the following ROM monitor. + +'target dbug DEV' + dBUG ROM monitor for Motorola ColdFire. + + +File: gdb.info, Node: MicroBlaze, Next: MIPS Embedded, Prev: M68K, Up: Embedded Processors + +21.3.4 MicroBlaze +----------------- + +The MicroBlaze is a soft-core processor supported on various Xilinx +FPGAs, such as Spartan or Virtex series. Boards with these processors +usually have JTAG ports which connect to a host system running the +Xilinx Embedded Development Kit (EDK) or Software Development Kit (SDK). +This host system is used to download the configuration bitstream to the +target FPGA. The Xilinx Microprocessor Debugger (XMD) program +communicates with the target board using the JTAG interface and presents +a 'gdbserver' interface to the board. By default 'xmd' uses port +'1234'. (While it is possible to change this default port, it requires +the use of undocumented 'xmd' commands. Contact Xilinx support if you +need to do this.) + + Use these GDB commands to connect to the MicroBlaze target processor. + +'target remote :1234' + Use this command to connect to the target if you are running GDB on + the same system as 'xmd'. + +'target remote XMD-HOST:1234' + Use this command to connect to the target if it is connected to + 'xmd' running on a different system named XMD-HOST. + +'load' + Use this command to download a program to the MicroBlaze target. + +'set debug microblaze N' + Enable MicroBlaze-specific debugging messages if non-zero. + +'show debug microblaze N' + Show MicroBlaze-specific debugging level. + + +File: gdb.info, Node: MIPS Embedded, Next: PowerPC Embedded, Prev: MicroBlaze, Up: Embedded Processors + +21.3.5 MIPS Embedded +-------------------- + +GDB can use the MIPS remote debugging protocol to talk to a MIPS board +attached to a serial line. This is available when you configure GDB +with '--target=mips-elf'. + + Use these GDB commands to specify the connection to your target +board: + +'target mips PORT' + To run a program on the board, start up 'gdb' with the name of your + program as the argument. To connect to the board, use the command + 'target mips PORT', where PORT is the name of the serial port + connected to the board. If the program has not already been + downloaded to the board, you may use the 'load' command to download + it. You can then use all the usual GDB commands. + + For example, this sequence connects to the target board through a + serial port, and loads and runs a program called PROG through the + debugger: + + host$ gdb PROG + GDB is free software and ... + (gdb) target mips /dev/ttyb + (gdb) load PROG + (gdb) run + +'target mips HOSTNAME:PORTNUMBER' + On some GDB host configurations, you can specify a TCP connection + (for instance, to a serial line managed by a terminal concentrator) + instead of a serial port, using the syntax 'HOSTNAME:PORTNUMBER'. + +'target pmon PORT' + PMON ROM monitor. + +'target ddb PORT' + NEC's DDB variant of PMON for Vr4300. + +'target lsi PORT' + LSI variant of PMON. + +'target r3900 DEV' + Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. + +'target array DEV' + Array Tech LSI33K RAID controller board. + +GDB also supports these special commands for MIPS targets: + +'set mipsfpu double' +'set mipsfpu single' +'set mipsfpu none' +'set mipsfpu auto' +'show mipsfpu' + If your target board does not support the MIPS floating point + coprocessor, you should use the command 'set mipsfpu none' (if you + need this, you may wish to put the command in your GDB init file). + This tells GDB how to find the return value of functions which + return floating point values. It also allows GDB to avoid saving + the floating point registers when calling functions on the board. + If you are using a floating point coprocessor with only single + precision floating point support, as on the R4650 processor, use + the command 'set mipsfpu single'. The default double precision + floating point coprocessor may be selected using 'set mipsfpu + double'. + + In previous versions the only choices were double precision or no + floating point, so 'set mipsfpu on' will select double precision + and 'set mipsfpu off' will select no floating point. + + As usual, you can inquire about the 'mipsfpu' variable with 'show + mipsfpu'. + +'set timeout SECONDS' +'set retransmit-timeout SECONDS' +'show timeout' +'show retransmit-timeout' + You can control the timeout used while waiting for a packet, in the + MIPS remote protocol, with the 'set timeout SECONDS' command. The + default is 5 seconds. Similarly, you can control the timeout used + while waiting for an acknowledgment of a packet with the 'set + retransmit-timeout SECONDS' command. The default is 3 seconds. + You can inspect both values with 'show timeout' and 'show + retransmit-timeout'. (These commands are _only_ available when GDB + is configured for '--target=mips-elf'.) + + The timeout set by 'set timeout' does not apply when GDB is waiting + for your program to stop. In that case, GDB waits forever because + it has no way of knowing how long the program is going to run + before stopping. + +'set syn-garbage-limit NUM' + Limit the maximum number of characters GDB should ignore when it + tries to synchronize with the remote target. The default is 10 + characters. Setting the limit to -1 means there's no limit. + +'show syn-garbage-limit' + Show the current limit on the number of characters to ignore when + trying to synchronize with the remote system. + +'set monitor-prompt PROMPT' + Tell GDB to expect the specified PROMPT string from the remote + monitor. The default depends on the target: + pmon target + 'PMON' + ddb target + 'NEC010' + lsi target + 'PMON>' + +'show monitor-prompt' + Show the current strings GDB expects as the prompt from the remote + monitor. + +'set monitor-warnings' + Enable or disable monitor warnings about hardware breakpoints. + This has effect only for the 'lsi' target. When on, GDB will + display warning messages whose codes are returned by the 'lsi' PMON + monitor for breakpoint commands. + +'show monitor-warnings' + Show the current setting of printing monitor warnings. + +'pmon COMMAND' + This command allows sending an arbitrary COMMAND string to the + monitor. The monitor must be in debug mode for this to work. + + +File: gdb.info, Node: PowerPC Embedded, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors + +21.3.6 PowerPC Embedded +----------------------- + +GDB supports using the DVC (Data Value Compare) register to implement in +hardware simple hardware watchpoint conditions of the form: + + (gdb) watch ADDRESS|VARIABLE \ + if ADDRESS|VARIABLE == CONSTANT EXPRESSION + + The DVC register will be automatically used when GDB detects such +pattern in a condition expression, and the created watchpoint uses one +debug register (either the 'exact-watchpoints' option is on and the +variable is scalar, or the variable has a length of one byte). This +feature is available in native GDB running on a Linux kernel version +2.6.34 or newer. + + When running on PowerPC embedded processors, GDB automatically uses +ranged hardware watchpoints, unless the 'exact-watchpoints' option is +on, in which case watchpoints using only one debug register are created +when watching variables of scalar types. + + You can create an artificial array to watch an arbitrary memory +region using one of the following commands (*note Expressions::): + + (gdb) watch *((char *) ADDRESS)@LENGTH + (gdb) watch {char[LENGTH]} ADDRESS + + PowerPC embedded processors support masked watchpoints. See the +discussion about the 'mask' argument in *note Set Watchpoints::. + + PowerPC embedded processors support hardware accelerated "ranged +breakpoints". A ranged breakpoint stops execution of the inferior +whenever it executes an instruction at any address within the range it +specifies. To set a ranged breakpoint in GDB, use the 'break-range' +command. + + GDB provides the following PowerPC-specific commands: + +'break-range START-LOCATION, END-LOCATION' + Set a breakpoint for an address range. START-LOCATION and + END-LOCATION can specify a function name, a line number, an offset + of lines from the current line or from the start location, or an + address of an instruction (see *note Specify Location::, for a list + of all the possible ways to specify a LOCATION.) The breakpoint + will stop execution of the inferior whenever it executes an + instruction at any address within the specified range, (including + START-LOCATION and END-LOCATION.) + +'set powerpc soft-float' +'show powerpc soft-float' + Force GDB to use (or not use) a software floating point calling + convention. By default, GDB selects the calling convention based + on the selected architecture and the provided executable file. + +'set powerpc vector-abi' +'show powerpc vector-abi' + Force GDB to use the specified calling convention for vector + arguments and return values. The valid options are 'auto'; + 'generic', to avoid vector registers even if they are present; + 'altivec', to use AltiVec registers; and 'spe' to use SPE + registers. By default, GDB selects the calling convention based on + the selected architecture and the provided executable file. + +'set powerpc exact-watchpoints' +'show powerpc exact-watchpoints' + Allow GDB to use only one debug register when watching a variable + of scalar type, thus assuming that the variable is accessed through + the address of its first byte. + +'target dink32 DEV' + DINK32 ROM monitor. + +'target ppcbug DEV' +'target ppcbug1 DEV' + PPCBUG ROM monitor for PowerPC. + +'target sds DEV' + SDS monitor, running on a PowerPC board (such as Motorola's ADS). + + The following commands specific to the SDS protocol are supported by +GDB: + +'set sdstimeout NSEC' + Set the timeout for SDS protocol reads to be NSEC seconds. The + default is 2 seconds. + +'show sdstimeout' + Show the current value of the SDS timeout. + +'sds COMMAND' + Send the specified COMMAND string to the SDS monitor. + + +File: gdb.info, Node: PA, Next: Sparclet, Prev: PowerPC Embedded, Up: Embedded Processors + +21.3.7 HP PA Embedded +--------------------- + +'target op50n DEV' + OP50N monitor, running on an OKI HPPA board. + +'target w89k DEV' + W89K monitor, running on a Winbond HPPA board. + + +File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PA, Up: Embedded Processors + +21.3.8 Tsqware Sparclet +----------------------- + +GDB enables developers to debug tasks running on Sparclet targets from a +Unix host. GDB uses code that runs on both the Unix host and on the +Sparclet target. The program 'gdb' is installed and executed on the +Unix host. + +'remotetimeout ARGS' + GDB supports the option 'remotetimeout'. This option is set by the + user, and ARGS represents the number of seconds GDB waits for + responses. + + When compiling for debugging, include the options '-g' to get debug +information and '-Ttext' to relocate the program to where you wish to +load it on the target. You may also want to add the options '-n' or +'-N' in order to reduce the size of the sections. Example: + + sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N + + You can use 'objdump' to verify that the addresses are what you +intended: + + sparclet-aout-objdump --headers --syms prog + + Once you have set your Unix execution search path to find GDB, you +are ready to run GDB. From your Unix host, run 'gdb' (or +'sparclet-aout-gdb', depending on your installation). + + GDB comes up showing the prompt: + + (gdbslet) + +* Menu: + +* Sparclet File:: Setting the file to debug +* Sparclet Connection:: Connecting to Sparclet +* Sparclet Download:: Sparclet download +* Sparclet Execution:: Running and debugging + + +File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet + +21.3.8.1 Setting File to Debug +.............................. + +The GDB command 'file' lets you choose with program to debug. + + (gdbslet) file prog + + GDB then attempts to read the symbol table of 'prog'. GDB locates +the file by searching the directories listed in the command search path. +If the file was compiled with debug information (option '-g'), source +files will be searched as well. GDB locates the source files by +searching the directories listed in the directory search path (*note +Your Program's Environment: Environment.). If it fails to find a file, +it displays a message such as: + + prog: No such file or directory. + + When this happens, add the appropriate directories to the search +paths with the GDB commands 'path' and 'dir', and execute the 'target' +command again. + + +File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet + +21.3.8.2 Connecting to Sparclet +............................... + +The GDB command 'target' lets you connect to a Sparclet target. To +connect to a target on serial port "'ttya'", type: + + (gdbslet) target sparclet /dev/ttya + Remote target sparclet connected to /dev/ttya + main () at ../prog.c:3 + + GDB displays messages like these: + + Connected to ttya. + + +File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet + +21.3.8.3 Sparclet Download +.......................... + +Once connected to the Sparclet target, you can use the GDB 'load' +command to download the file from the host to the target. The file name +and load offset should be given as arguments to the 'load' command. +Since the file format is aout, the program must be loaded to the +starting address. You can use 'objdump' to find out what this value is. +The load offset is an offset which is added to the VMA (virtual memory +address) of each of the file's sections. For instance, if the program +'prog' was linked to text address 0x1201000, with data at 0x12010160 and +bss at 0x12010170, in GDB, type: + + (gdbslet) load prog 0x12010000 + Loading section .text, size 0xdb0 vma 0x12010000 + + If the code is loaded at a different address then what the program +was linked to, you may need to use the 'section' and 'add-symbol-file' +commands to tell GDB where to map the symbol table. + + +File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet + +21.3.8.4 Running and Debugging +.............................. + +You can now begin debugging the task using GDB's execution control +commands, 'b', 'step', 'run', etc. See the GDB manual for the list of +commands. + + (gdbslet) b main + Breakpoint 1 at 0x12010000: file prog.c, line 3. + (gdbslet) run + Starting program: prog + Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 + 3 char *symarg = 0; + (gdbslet) step + 4 char *execarg = "hello!"; + (gdbslet) + + +File: gdb.info, Node: Sparclite, Next: Z8000, Prev: Sparclet, Up: Embedded Processors + +21.3.9 Fujitsu Sparclite +------------------------ + +'target sparclite DEV' + Fujitsu sparclite boards, used only for the purpose of loading. + You must use an additional command to debug the program. For + example: target remote DEV using GDB standard remote protocol. + + +File: gdb.info, Node: Z8000, Next: AVR, Prev: Sparclite, Up: Embedded Processors + +21.3.10 Zilog Z8000 +------------------- + +When configured for debugging Zilog Z8000 targets, GDB includes a Z8000 +simulator. + + For the Z8000 family, 'target sim' simulates either the Z8002 (the +unsegmented variant of the Z8000 architecture) or the Z8001 (the +segmented variant). The simulator recognizes which architecture is +appropriate by inspecting the object code. + +'target sim ARGS' + Debug programs on a simulated CPU. If the simulator supports setup + options, specify them via ARGS. + +After specifying this target, you can debug programs for the simulated +CPU in the same style as programs for your host computer; use the 'file' +command to load a new program image, the 'run' command to run your +program, and so on. + + As well as making available all the usual machine registers (*note +Registers: Registers.), the Z8000 simulator provides three additional +items of information as specially named registers: + +'cycles' + Counts clock-ticks in the simulator. + +'insts' + Counts instructions run in the simulator. + +'time' + Execution time in 60ths of a second. + + You can refer to these values in GDB expressions with the usual +conventions; for example, 'b fputc if $cycles>5000' sets a conditional +breakpoint that suspends only after at least 5000 simulated clock ticks. + + +File: gdb.info, Node: AVR, Next: CRIS, Prev: Z8000, Up: Embedded Processors + +21.3.11 Atmel AVR +----------------- + +When configured for debugging the Atmel AVR, GDB supports the following +AVR-specific commands: + +'info io_registers' + This command displays information about the AVR I/O registers. For + each register, GDB prints its number and value. + + +File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors + +21.3.12 CRIS +------------ + +When configured for debugging CRIS, GDB provides the following +CRIS-specific commands: + +'set cris-version VER' + Set the current CRIS version to VER, either '10' or '32'. The CRIS + version affects register names and sizes. This command is useful + in case autodetection of the CRIS version fails. + +'show cris-version' + Show the current CRIS version. + +'set cris-dwarf2-cfi' + Set the usage of DWARF-2 CFI for CRIS debugging. The default is + 'on'. Change to 'off' when using 'gcc-cris' whose version is below + 'R59'. + +'show cris-dwarf2-cfi' + Show the current state of using DWARF-2 CFI. + +'set cris-mode MODE' + Set the current CRIS mode to MODE. It should only be changed when + debugging in guru mode, in which case it should be set to 'guru' + (the default is 'normal'). + +'show cris-mode' + Show the current CRIS mode. + + +File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors + +21.3.13 Renesas Super-H +----------------------- + +For the Renesas Super-H processor, GDB provides these commands: + +'set sh calling-convention CONVENTION' + Set the calling-convention used when calling functions from GDB. + Allowed values are 'gcc', which is the default setting, and + 'renesas'. With the 'gcc' setting, functions are called using the + GCC calling convention. If the DWARF-2 information of the called + function specifies that the function follows the Renesas calling + convention, the function is called using the Renesas calling + convention. If the calling convention is set to 'renesas', the + Renesas calling convention is always used, regardless of the + DWARF-2 information. This can be used to override the default of + 'gcc' if debug information is missing, or the compiler does not + emit the DWARF-2 calling convention entry for a function. + +'show sh calling-convention' + Show the current calling convention setting. + + +File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations + +21.4 Architectures +================== + +This section describes characteristics of architectures that affect all +uses of GDB with the architecture, both native and cross. + +* Menu: + +* AArch64:: +* i386:: +* Alpha:: +* MIPS:: +* HPPA:: HP PA architecture +* SPU:: Cell Broadband Engine SPU architecture +* PowerPC:: +* Nios II:: + + +File: gdb.info, Node: AArch64, Next: i386, Up: Architectures + +21.4.1 AArch64 +-------------- + +When GDB is debugging the AArch64 architecture, it provides the +following special commands: + +'set debug aarch64' + This command determines whether AArch64 architecture-specific + debugging messages are to be displayed. + +'show debug aarch64' + Show whether AArch64 debugging messages are displayed. + + +File: gdb.info, Node: i386, Next: Alpha, Prev: AArch64, Up: Architectures + +21.4.2 x86 Architecture-specific Issues +--------------------------------------- + +'set struct-convention MODE' + Set the convention used by the inferior to return 'struct's and + 'union's from functions to MODE. Possible values of MODE are + '"pcc"', '"reg"', and '"default"' (the default). '"default"' or + '"pcc"' means that 'struct's are returned on the stack, while + '"reg"' means that a 'struct' or a 'union' whose size is 1, 2, 4, + or 8 bytes will be returned in a register. + +'show struct-convention' + Show the current setting of the convention to return 'struct's from + functions. + +21.4.2.1 Intel(R) "Memory Protection Extensions" (MPX). +....................................................... + +Memory Protection Extension (MPX) adds the bound registers 'BND0' (1) +through 'BND3'. Bound registers store a pair of 64-bit values which are +the lower bound and upper bound. Bounds are effective addresses or +memory locations. The upper bounds are architecturally represented in +1's complement form. A bound having lower bound = 0, and upper bound = +0 (1's complement of all bits set) will allow access to the entire +address space. + + 'BND0' through 'BND3' are represented in GDB as 'bnd0raw' through +'bnd3raw'. Pseudo registers 'bnd0' through 'bnd3' display the upper +bound performing the complement of one operation on the upper bound +value, i.e. when upper bound in 'bnd0raw' is 0 in the GDB 'bnd0' it will +be '0xfff...'. In this sense it can also be noted that the upper bounds +are inclusive. + + As an example, assume that the register BND0 holds bounds for a +pointer having access allowed for the range between 0x32 and 0x71. The +values present on bnd0raw and bnd registers are presented as follows: + + bnd0raw = {0x32, 0xffffffff8e} + bnd0 = {lbound = 0x32, ubound = 0x71} : size 64 + + This way the raw value can be accessed via bnd0raw...bnd3raw. Any +change on bnd0...bnd3 or bnd0raw...bnd3raw is reflect on its +counterpart. When the bnd0...bnd3 registers are displayed via Python, +the display includes the memory size, in bits, accessible to the +pointer. + + ---------- Footnotes ---------- + + (1) The register named with capital letters represent the +architecture registers. + + +File: gdb.info, Node: Alpha, Next: MIPS, Prev: i386, Up: Architectures + +21.4.3 Alpha +------------ + +See the following section. + + +File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures + +21.4.4 MIPS +----------- + +Alpha- and MIPS-based computers use an unusual stack frame, which +sometimes requires GDB to search backward in the object code to find the +beginning of a function. + + To improve response time (especially for embedded applications, where +GDB may be restricted to a slow serial line for this search) you may +want to limit the size of this search, using one of these commands: + +'set heuristic-fence-post LIMIT' + Restrict GDB to examining at most LIMIT bytes in its search for the + beginning of a function. A value of 0 (the default) means there is + no limit. However, except for 0, the larger the limit the more + bytes 'heuristic-fence-post' must search and therefore the longer + it takes to run. You should only need to use this command when + debugging a stripped executable. + +'show heuristic-fence-post' + Display the current limit. + +These commands are available _only_ when GDB is configured for debugging +programs on Alpha or MIPS processors. + + Several MIPS-specific commands are available when debugging MIPS +programs: + +'set mips abi ARG' + Tell GDB which MIPS ABI is used by the inferior. Possible values + of ARG are: + + 'auto' + The default ABI associated with the current binary (this is + the default). + 'o32' + 'o64' + 'n32' + 'n64' + 'eabi32' + 'eabi64' + +'show mips abi' + Show the MIPS ABI used by GDB to debug the inferior. + +'set mips compression ARG' + Tell GDB which MIPS compressed ISA (Instruction Set Architecture) + encoding is used by the inferior. GDB uses this for code + disassembly and other internal interpretation purposes. This + setting is only referred to when no executable has been associated + with the debugging session or the executable does not provide + information about the encoding it uses. Otherwise this setting is + automatically updated from information provided by the executable. + + Possible values of ARG are 'mips16' and 'micromips'. The default + compressed ISA encoding is 'mips16', as executables containing + MIPS16 code frequently are not identified as such. + + This setting is "sticky"; that is, it retains its value across + debugging sessions until reset either explicitly with this command + or implicitly from an executable. + + The compiler and/or assembler typically add symbol table + annotations to identify functions compiled for the MIPS16 or + microMIPS ISAs. If these function-scope annotations are present, + GDB uses them in preference to the global compressed ISA encoding + setting. + +'show mips compression' + Show the MIPS compressed ISA encoding used by GDB to debug the + inferior. + +'set mipsfpu' +'show mipsfpu' + *Note set mipsfpu: MIPS Embedded. + +'set mips mask-address ARG' + This command determines whether the most-significant 32 bits of + 64-bit MIPS addresses are masked off. The argument ARG can be + 'on', 'off', or 'auto'. The latter is the default setting, which + lets GDB determine the correct value. + +'show mips mask-address' + Show whether the upper 32 bits of MIPS addresses are masked off or + not. + +'set remote-mips64-transfers-32bit-regs' + This command controls compatibility with 64-bit MIPS targets that + transfer data in 32-bit quantities. If you have an old MIPS 64 + target that transfers 32 bits for some registers, like SR and FSR, + and 64 bits for other registers, set this option to 'on'. + +'show remote-mips64-transfers-32bit-regs' + Show the current setting of compatibility with older MIPS 64 + targets. + +'set debug mips' + This command turns on and off debugging messages for the + MIPS-specific target code in GDB. + +'show debug mips' + Show the current setting of MIPS debugging messages. + + +File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures + +21.4.5 HPPA +----------- + +When GDB is debugging the HP PA architecture, it provides the following +special commands: + +'set debug hppa' + This command determines whether HPPA architecture-specific + debugging messages are to be displayed. + +'show debug hppa' + Show whether HPPA debugging messages are displayed. + +'maint print unwind ADDRESS' + This command displays the contents of the unwind table entry at the + given ADDRESS. + + +File: gdb.info, Node: SPU, Next: PowerPC, Prev: HPPA, Up: Architectures + +21.4.6 Cell Broadband Engine SPU architecture +--------------------------------------------- + +When GDB is debugging the Cell Broadband Engine SPU architecture, it +provides the following special commands: + +'info spu event' + Display SPU event facility status. Shows current event mask and + pending event status. + +'info spu signal' + Display SPU signal notification facility status. Shows pending + signal-control word and signal notification mode of both signal + notification channels. + +'info spu mailbox' + Display SPU mailbox facility status. Shows all pending entries, in + order of processing, in each of the SPU Write Outbound, SPU Write + Outbound Interrupt, and SPU Read Inbound mailboxes. + +'info spu dma' + Display MFC DMA status. Shows all pending commands in the MFC DMA + queue. For each entry, opcode, tag, class IDs, effective and local + store addresses and transfer size are shown. + +'info spu proxydma' + Display MFC Proxy-DMA status. Shows all pending commands in the + MFC Proxy-DMA queue. For each entry, opcode, tag, class IDs, + effective and local store addresses and transfer size are shown. + + When GDB is debugging a combined PowerPC/SPU application on the Cell +Broadband Engine, it provides in addition the following special +commands: + +'set spu stop-on-load ARG' + Set whether to stop for new SPE threads. When set to 'on', GDB + will give control to the user when a new SPE thread enters its + 'main' function. The default is 'off'. + +'show spu stop-on-load' + Show whether to stop for new SPE threads. + +'set spu auto-flush-cache ARG' + Set whether to automatically flush the software-managed cache. + When set to 'on', GDB will automatically cause the SPE + software-managed cache to be flushed whenever SPE execution stops. + This provides a consistent view of PowerPC memory that is accessed + via the cache. If an application does not use the software-managed + cache, this option has no effect. + +'show spu auto-flush-cache' + Show whether to automatically flush the software-managed cache. + + +File: gdb.info, Node: PowerPC, Next: Nios II, Prev: SPU, Up: Architectures + +21.4.7 PowerPC +-------------- + +When GDB is debugging the PowerPC architecture, it provides a set of +pseudo-registers to enable inspection of 128-bit wide Decimal Floating +Point numbers stored in the floating point registers. These values must +be stored in two consecutive registers, always starting at an even +register like 'f0' or 'f2'. + + The pseudo-registers go from '$dl0' through '$dl15', and are formed +by joining the even/odd register pairs 'f0' and 'f1' for '$dl0', 'f2' +and 'f3' for '$dl1' and so on. + + For POWER7 processors, GDB provides a set of pseudo-registers, the +64-bit wide Extended Floating Point Registers ('f32' through 'f63'). + + +File: gdb.info, Node: Nios II, Prev: PowerPC, Up: Architectures + +21.4.8 Nios II +-------------- + +When GDB is debugging the Nios II architecture, it provides the +following special commands: + +'set debug nios2' + This command turns on and off debugging messages for the Nios II + target code in GDB. + +'show debug nios2' + Show the current setting of Nios II debugging messages. + + +File: gdb.info, Node: Controlling GDB, Next: Extending GDB, Prev: Configurations, Up: Top + +22 Controlling GDB +****************** + +You can alter the way GDB interacts with you by using the 'set' command. +For commands controlling how GDB displays data, see *note Print +Settings: Print Settings. Other settings are described here. + +* Menu: + +* Prompt:: Prompt +* Editing:: Command editing +* Command History:: Command history +* Screen Size:: Screen size +* Numbers:: Numbers +* ABI:: Configuring the current ABI +* Auto-loading:: Automatically loading associated files +* Messages/Warnings:: Optional warnings and messages +* Debugging Output:: Optional messages about internal happenings +* Other Misc Settings:: Other Miscellaneous Settings + + +File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB + +22.1 Prompt +=========== + +GDB indicates its readiness to read a command by printing a string +called the "prompt". This string is normally '(gdb)'. You can change +the prompt string with the 'set prompt' command. For instance, when +debugging GDB with GDB, it is useful to change the prompt in one of the +GDB sessions so that you can always tell which one you are talking to. + + _Note:_ 'set prompt' does not add a space for you after the prompt +you set. This allows you to set a prompt which ends in a space or a +prompt that does not. + +'set prompt NEWPROMPT' + Directs GDB to use NEWPROMPT as its prompt string henceforth. + +'show prompt' + Prints a line of the form: 'Gdb's prompt is: YOUR-PROMPT' + + Versions of GDB that ship with Python scripting enabled have prompt +extensions. The commands for interacting with these extensions are: + +'set extended-prompt PROMPT' + Set an extended prompt that allows for substitutions. *Note + gdb.prompt::, for a list of escape sequences that can be used for + substitution. Any escape sequences specified as part of the prompt + string are replaced with the corresponding strings each time the + prompt is displayed. + + For example: + + set extended-prompt Current working directory: \w (gdb) + + Note that when an extended-prompt is set, it takes control of the + PROMPT_HOOK hook. *Note prompt_hook::, for further information. + +'show extended-prompt' + Prints the extended prompt. Any escape sequences specified as part + of the prompt string with 'set extended-prompt', are replaced with + the corresponding strings each time the prompt is displayed. + + +File: gdb.info, Node: Editing, Next: Command History, Prev: Prompt, Up: Controlling GDB + +22.2 Command Editing +==================== + +GDB reads its input commands via the "Readline" interface. This GNU +library provides consistent behavior for programs which provide a +command line interface to the user. Advantages are GNU Emacs-style or +"vi"-style inline editing of commands, 'csh'-like history substitution, +and a storage and recall of command history across debugging sessions. + + You may control the behavior of command line editing in GDB with the +command 'set'. + +'set editing' +'set editing on' + Enable command line editing (enabled by default). + +'set editing off' + Disable command line editing. + +'show editing' + Show whether command line editing is enabled. + + *Note Command Line Editing::, for more details about the Readline +interface. Users unfamiliar with GNU Emacs or 'vi' are encouraged to +read that chapter. + + +File: gdb.info, Node: Command History, Next: Screen Size, Prev: Editing, Up: Controlling GDB + +22.3 Command History +==================== + +GDB can keep track of the commands you type during your debugging +sessions, so that you can be certain of precisely what happened. Use +these commands to manage the GDB command history facility. + + GDB uses the GNU History library, a part of the Readline package, to +provide the history facility. *Note Using History Interactively::, for +the detailed description of the History library. + + To issue a command to GDB without affecting certain aspects of the +state which is seen by users, prefix it with 'server ' (*note Server +Prefix::). This means that this command will not affect the command +history, nor will it affect GDB's notion of which command to repeat if + is pressed on a line by itself. + + The server prefix does not affect the recording of values into the +value history; to print a value without recording it into the value +history, use the 'output' command instead of the 'print' command. + + Here is the description of GDB commands related to command history. + +'set history filename FNAME' + Set the name of the GDB command history file to FNAME. This is the + file where GDB reads an initial command history list, and where it + writes the command history from this session when it exits. You + can access this list through history expansion or through the + history command editing characters listed below. This file + defaults to the value of the environment variable 'GDBHISTFILE', or + to './.gdb_history' ('./_gdb_history' on MS-DOS) if this variable + is not set. + +'set history save' +'set history save on' + Record command history in a file, whose name may be specified with + the 'set history filename' command. By default, this option is + disabled. + +'set history save off' + Stop recording command history in a file. + +'set history size SIZE' +'set history size unlimited' + Set the number of commands which GDB keeps in its history list. + This defaults to the value of the environment variable 'HISTSIZE', + or to 256 if this variable is not set. If SIZE is 'unlimited', the + number of commands GDB keeps in the history list is unlimited. + + History expansion assigns special meaning to the character '!'. +*Note Event Designators::, for more details. + + Since '!' is also the logical not operator in C, history expansion is +off by default. If you decide to enable history expansion with the 'set +history expansion on' command, you may sometimes need to follow '!' +(when it is used as logical not, in an expression) with a space or a tab +to prevent it from being expanded. The readline history facilities do +not attempt substitution on the strings '!=' and '!(', even when history +expansion is enabled. + + The commands to control history expansion are: + +'set history expansion on' +'set history expansion' + Enable history expansion. History expansion is off by default. + +'set history expansion off' + Disable history expansion. + +'show history' +'show history filename' +'show history save' +'show history size' +'show history expansion' + These commands display the state of the GDB history parameters. + 'show history' by itself displays all four states. + +'show commands' + Display the last ten commands in the command history. + +'show commands N' + Print ten commands centered on command number N. + +'show commands +' + Print ten commands just after the commands last printed. + + +File: gdb.info, Node: Screen Size, Next: Numbers, Prev: Command History, Up: Controlling GDB + +22.4 Screen Size +================ + +Certain commands to GDB may produce large amounts of information output +to the screen. To help you read all of it, GDB pauses and asks you for +input at the end of each page of output. Type when you want to +continue the output, or 'q' to discard the remaining output. Also, the +screen width setting determines when to wrap lines of output. Depending +on what is being printed, GDB tries to break the line at a readable +place, rather than simply letting it overflow onto the following line. + + Normally GDB knows the size of the screen from the terminal driver +software. For example, on Unix GDB uses the termcap data base together +with the value of the 'TERM' environment variable and the 'stty rows' +and 'stty cols' settings. If this is not correct, you can override it +with the 'set height' and 'set width' commands: + +'set height LPP' +'set height unlimited' +'show height' +'set width CPL' +'set width unlimited' +'show width' + These 'set' commands specify a screen height of LPP lines and a + screen width of CPL characters. The associated 'show' commands + display the current settings. + + If you specify a height of either 'unlimited' or zero lines, GDB + does not pause during output no matter how long the output is. + This is useful if output is to a file or to an editor buffer. + + Likewise, you can specify 'set width unlimited' or 'set width 0' to + prevent GDB from wrapping its output. + +'set pagination on' +'set pagination off' + Turn the output pagination on or off; the default is on. Turning + pagination off is the alternative to 'set height unlimited'. Note + that running GDB with the '--batch' option (*note -batch: Mode + Options.) also automatically disables pagination. + +'show pagination' + Show the current pagination mode. + + +File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB + +22.5 Numbers +============ + +You can always enter numbers in octal, decimal, or hexadecimal in GDB by +the usual conventions: octal numbers begin with '0', decimal numbers end +with '.', and hexadecimal numbers begin with '0x'. Numbers that neither +begin with '0' or '0x', nor end with a '.' are, by default, entered in +base 10; likewise, the default display for numbers--when no particular +format is specified--is base 10. You can change the default base for +both input and output with the commands described below. + +'set input-radix BASE' + Set the default base for numeric input. Supported choices for BASE + are decimal 8, 10, or 16. BASE must itself be specified either + unambiguously or using the current input radix; for example, any of + + set input-radix 012 + set input-radix 10. + set input-radix 0xa + + sets the input base to decimal. On the other hand, 'set + input-radix 10' leaves the input radix unchanged, no matter what it + was, since '10', being without any leading or trailing signs of its + base, is interpreted in the current radix. Thus, if the current + radix is 16, '10' is interpreted in hex, i.e. as 16 decimal, which + doesn't change the radix. + +'set output-radix BASE' + Set the default base for numeric display. Supported choices for + BASE are decimal 8, 10, or 16. BASE must itself be specified + either unambiguously or using the current input radix. + +'show input-radix' + Display the current default base for numeric input. + +'show output-radix' + Display the current default base for numeric display. + +'set radix [BASE]' +'show radix' + These commands set and show the default base for both input and + output of numbers. 'set radix' sets the radix of input and output + to the same base; without an argument, it resets the radix back to + its default value of 10. + + +File: gdb.info, Node: ABI, Next: Auto-loading, Prev: Numbers, Up: Controlling GDB + +22.6 Configuring the Current ABI +================================ + +GDB can determine the "ABI" (Application Binary Interface) of your +application automatically. However, sometimes you need to override its +conclusions. Use these commands to manage GDB's view of the current +ABI. + + One GDB configuration can debug binaries for multiple operating +system targets, either via remote debugging or native emulation. GDB +will autodetect the "OS ABI" (Operating System ABI) in use, but you can +override its conclusion using the 'set osabi' command. One example +where this is useful is in debugging of binaries which use an alternate +C library (e.g. UCLIBC for GNU/Linux) which does not have the same +identifying marks that the standard C library for your platform +provides. + + When GDB is debugging the AArch64 architecture, it provides a +"Newlib" OS ABI. This is useful for handling 'setjmp' and 'longjmp' when +debugging binaries that use the NEWLIB C library. The "Newlib" OS ABI +can be selected by 'set osabi Newlib'. + +'show osabi' + Show the OS ABI currently in use. + +'set osabi' + With no argument, show the list of registered available OS ABI's. + +'set osabi ABI' + Set the current OS ABI to ABI. + + Generally, the way that an argument of type 'float' is passed to a +function depends on whether the function is prototyped. For a +prototyped (i.e. ANSI/ISO style) function, 'float' arguments are passed +unchanged, according to the architecture's convention for 'float'. For +unprototyped (i.e. K&R style) functions, 'float' arguments are first +promoted to type 'double' and then passed. + + Unfortunately, some forms of debug information do not reliably +indicate whether a function is prototyped. If GDB calls a function that +is not marked as prototyped, it consults 'set coerce-float-to-double'. + +'set coerce-float-to-double' +'set coerce-float-to-double on' + Arguments of type 'float' will be promoted to 'double' when passed + to an unprototyped function. This is the default setting. + +'set coerce-float-to-double off' + Arguments of type 'float' will be passed directly to unprototyped + functions. + +'show coerce-float-to-double' + Show the current setting of promoting 'float' to 'double'. + + GDB needs to know the ABI used for your program's C++ objects. The +correct C++ ABI depends on which C++ compiler was used to build your +application. GDB only fully supports programs with a single C++ ABI; if +your program contains code using multiple C++ ABI's or if GDB can not +identify your program's ABI correctly, you can tell GDB which ABI to +use. Currently supported ABI's include "gnu-v2", for 'g++' versions +before 3.0, "gnu-v3", for 'g++' versions 3.0 and later, and "hpaCC" for +the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or +"gnu-v3" ABI's as well. The default setting is "auto". + +'show cp-abi' + Show the C++ ABI currently in use. + +'set cp-abi' + With no argument, show the list of supported C++ ABI's. + +'set cp-abi ABI' +'set cp-abi auto' + Set the current C++ ABI to ABI, or return to automatic detection. + + +File: gdb.info, Node: Auto-loading, Next: Messages/Warnings, Prev: ABI, Up: Controlling GDB + +22.7 Automatically loading associated files +=========================================== + +GDB sometimes reads files with commands and settings automatically, +without being explicitly told so by the user. We call this feature +"auto-loading". While auto-loading is useful for automatically adapting +GDB to the needs of your project, it can sometimes produce unexpected +results or introduce security risks (e.g., if the file comes from +untrusted sources). + +* Menu: + +* Init File in the Current Directory:: 'set/show/info auto-load local-gdbinit' +* libthread_db.so.1 file:: 'set/show/info auto-load libthread-db' + +* Auto-loading safe path:: 'set/show/info auto-load safe-path' +* Auto-loading verbose mode:: 'set/show debug auto-load' + + There are various kinds of files GDB can automatically load. In +addition to these files, GDB supports auto-loading code written in +various extension languages. *Note Auto-loading extensions::. + + Note that loading of these associated files (including the local +'.gdbinit' file) requires accordingly configured 'auto-load safe-path' +(*note Auto-loading safe path::). + + For these reasons, GDB includes commands and options to let you +control when to auto-load files and which files should be auto-loaded. + +'set auto-load off' + Globally disable loading of all auto-loaded files. You may want to + use this command with the '-iex' option (*note Option + -init-eval-command::) such as: + $ gdb -iex "set auto-load off" untrusted-executable corefile + + Be aware that system init file (*note System-wide configuration::) + and init files from your home directory (*note Home Directory Init + File::) still get read (as they come from generally trusted + directories). To prevent GDB from auto-loading even those init + files, use the '-nx' option (*note Mode Options::), in addition to + 'set auto-load no'. + +'show auto-load' + Show whether auto-loading of each specific 'auto-load' file(s) is + enabled or disabled. + + (gdb) show auto-load + gdb-scripts: Auto-loading of canned sequences of commands scripts is on. + libthread-db: Auto-loading of inferior specific libthread_db is on. + local-gdbinit: Auto-loading of .gdbinit script from current directory + is on. + python-scripts: Auto-loading of Python scripts is on. + safe-path: List of directories from which it is safe to auto-load files + is $debugdir:$datadir/auto-load. + scripts-directory: List of directories from which to load auto-loaded scripts + is $debugdir:$datadir/auto-load. + +'info auto-load' + Print whether each specific 'auto-load' file(s) have been + auto-loaded or not. + + (gdb) info auto-load + gdb-scripts: + Loaded Script + Yes /home/user/gdb/gdb-gdb.gdb + libthread-db: No auto-loaded libthread-db. + local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been + loaded. + python-scripts: + Loaded Script + Yes /home/user/gdb/gdb-gdb.py + + These are GDB control commands for the auto-loading: + +*Note set auto-load off::. Disable auto-loading globally. +*Note show auto-load::. Show setting of all kinds of + files. +*Note info auto-load::. Show state of all kinds of files. +*Note set auto-load gdb-scripts::. Control for GDB command scripts. +*Note show auto-load Show setting of GDB command +gdb-scripts::. scripts. +*Note info auto-load Show state of GDB command scripts. +gdb-scripts::. +*Note set auto-load Control for GDB Python scripts. +python-scripts::. +*Note show auto-load Show setting of GDB Python +python-scripts::. scripts. +*Note info auto-load Show state of GDB Python scripts. +python-scripts::. +*Note set auto-load Control for GDB auto-loaded +scripts-directory::. scripts location. +*Note show auto-load Show GDB auto-loaded scripts +scripts-directory::. location. +*Note set auto-load Control for init file in the +local-gdbinit::. current directory. +*Note show auto-load Show setting of init file in the +local-gdbinit::. current directory. +*Note info auto-load Show state of init file in the +local-gdbinit::. current directory. +*Note set auto-load Control for thread debugging +libthread-db::. library. +*Note show auto-load Show setting of thread debugging +libthread-db::. library. +*Note info auto-load Show state of thread debugging +libthread-db::. library. +*Note set auto-load safe-path::. Control directories trusted for + automatic loading. +*Note show auto-load safe-path::. Show directories trusted for + automatic loading. +*Note add-auto-load-safe-path::. Add directory trusted for + automatic loading. + + +File: gdb.info, Node: Init File in the Current Directory, Next: libthread_db.so.1 file, Up: Auto-loading + +22.7.1 Automatically loading init file in the current directory +--------------------------------------------------------------- + +By default, GDB reads and executes the canned sequences of commands from +init file (if any) in the current working directory, see *note Init File +in the Current Directory during Startup::. + + Note that loading of this local '.gdbinit' file also requires +accordingly configured 'auto-load safe-path' (*note Auto-loading safe +path::). + +'set auto-load local-gdbinit [on|off]' + Enable or disable the auto-loading of canned sequences of commands + (*note Sequences::) found in init file in the current directory. + +'show auto-load local-gdbinit' + Show whether auto-loading of canned sequences of commands from init + file in the current directory is enabled or disabled. + +'info auto-load local-gdbinit' + Print whether canned sequences of commands from init file in the + current directory have been auto-loaded. + + +File: gdb.info, Node: libthread_db.so.1 file, Next: Auto-loading safe path, Prev: Init File in the Current Directory, Up: Auto-loading + +22.7.2 Automatically loading thread debugging library +----------------------------------------------------- + +This feature is currently present only on GNU/Linux native hosts. + + GDB reads in some cases thread debugging library from places specific +to the inferior (*note set libthread-db-search-path::). + + The special 'libthread-db-search-path' entry '$sdir' is processed +without checking this 'set auto-load libthread-db' switch as system +libraries have to be trusted in general. In all other cases of +'libthread-db-search-path' entries GDB checks first if 'set auto-load +libthread-db' is enabled before trying to open such thread debugging +library. + + Note that loading of this debugging library also requires accordingly +configured 'auto-load safe-path' (*note Auto-loading safe path::). + +'set auto-load libthread-db [on|off]' + Enable or disable the auto-loading of inferior specific thread + debugging library. + +'show auto-load libthread-db' + Show whether auto-loading of inferior specific thread debugging + library is enabled or disabled. + +'info auto-load libthread-db' + Print the list of all loaded inferior specific thread debugging + libraries and for each such library print list of inferior PIDs + using it. + + +File: gdb.info, Node: Auto-loading safe path, Next: Auto-loading verbose mode, Prev: libthread_db.so.1 file, Up: Auto-loading + +22.7.3 Security restriction for auto-loading +-------------------------------------------- + +As the files of inferior can come from untrusted source (such as +submitted by an application user) GDB does not always load any files +automatically. GDB provides the 'set auto-load safe-path' setting to +list directories trusted for loading files not explicitly requested by +user. Each directory can also be a shell wildcard pattern. + + If the path is not set properly you will see a warning and the file +will not get loaded: + + $ ./gdb -q ./gdb + Reading symbols from /home/user/gdb/gdb...done. + warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been + declined by your `auto-load safe-path' set + to "$debugdir:$datadir/auto-load". + warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been + declined by your `auto-load safe-path' set + to "$debugdir:$datadir/auto-load". + +To instruct GDB to go ahead and use the init files anyway, invoke GDB +like this: + + $ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb + + The list of trusted directories is controlled by the following +commands: + +'set auto-load safe-path [DIRECTORIES]' + Set the list of directories (and their subdirectories) trusted for + automatic loading and execution of scripts. You can also enter a + specific trusted file. Each directory can also be a shell wildcard + pattern; wildcards do not match directory separator - see + 'FNM_PATHNAME' for system function 'fnmatch' (*note fnmatch: + (libc)Wildcard Matching.). If you omit DIRECTORIES, 'auto-load + safe-path' will be reset to its default value as specified during + GDB compilation. + + The list of directories uses path separator (':' on GNU and Unix + systems, ';' on MS-Windows and MS-DOS) to separate directories, + similarly to the 'PATH' environment variable. + +'show auto-load safe-path' + Show the list of directories trusted for automatic loading and + execution of scripts. + +'add-auto-load-safe-path' + Add an entry (or list of entries) the list of directories trusted + for automatic loading and execution of scripts. Multiple entries + may be delimited by the host platform path separator in use. + + This variable defaults to what '--with-auto-load-dir' has been +configured to (*note with-auto-load-dir::). '$debugdir' and '$datadir' +substitution applies the same as for *note set auto-load +scripts-directory::. The default 'set auto-load safe-path' value can be +also overriden by GDB configuration option '--with-auto-load-safe-path'. + + Setting this variable to '/' disables this security protection, +corresponding GDB configuration option is +'--without-auto-load-safe-path'. This variable is supposed to be set to +the system directories writable by the system superuser only. Users can +add their source directories in init files in their home directories +(*note Home Directory Init File::). See also deprecated init file in +the current directory (*note Init File in the Current Directory during +Startup::). + + To force GDB to load the files it declined to load in the previous +example, you could use one of the following ways: + +'~/.gdbinit': 'add-auto-load-safe-path ~/src/gdb' + Specify this trusted directory (or a file) as additional component + of the list. You have to specify also any existing directories + displayed by by 'show auto-load safe-path' (such as '/usr:/bin' in + this example). + +'gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" ...' + Specify this directory as in the previous case but just for a + single GDB session. + +'gdb -iex "set auto-load safe-path /" ...' + Disable auto-loading safety for a single GDB session. This assumes + all the files you debug during this GDB session will come from + trusted sources. + +'./configure --without-auto-load-safe-path' + During compilation of GDB you may disable any auto-loading safety. + This assumes all the files you will ever debug with this GDB come + from trusted sources. + + On the other hand you can also explicitly forbid automatic files +loading which also suppresses any such warning messages: + +'gdb -iex "set auto-load no" ...' + You can use GDB command-line option for a single GDB session. + +'~/.gdbinit': 'set auto-load no' + Disable auto-loading globally for the user (*note Home Directory + Init File::). While it is improbable, you could also use system + init file instead (*note System-wide configuration::). + + This setting applies to the file names as entered by user. If no +entry matches GDB tries as a last resort to also resolve all the file +names into their canonical form (typically resolving symbolic links) and +compare the entries again. GDB already canonicalizes most of the +filenames on its own before starting the comparison so a canonical form +of directories is recommended to be entered. + + +File: gdb.info, Node: Auto-loading verbose mode, Prev: Auto-loading safe path, Up: Auto-loading + +22.7.4 Displaying files tried for auto-load +------------------------------------------- + +For better visibility of all the file locations where you can place +scripts to be auto-loaded with inferior -- or to protect yourself +against accidental execution of untrusted scripts -- GDB provides a +feature for printing all the files attempted to be loaded. Both +existing and non-existing files may be printed. + + For example the list of directories from which it is safe to +auto-load files (*note Auto-loading safe path::) applies also to +canonicalized filenames which may not be too obvious while setting it +up. + + (gdb) set debug auto-load on + (gdb) file ~/src/t/true + auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" + for objfile "/tmp/true". + auto-load: Updating directories of "/usr:/opt". + auto-load: Using directory "/usr". + auto-load: Using directory "/opt". + warning: File "/tmp/true-gdb.gdb" auto-loading has been declined + by your `auto-load safe-path' set to "/usr:/opt". + +'set debug auto-load [on|off]' + Set whether to print the filenames attempted to be auto-loaded. + +'show debug auto-load' + Show whether printing of the filenames attempted to be auto-loaded + is turned on or off. + + +File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: Auto-loading, Up: Controlling GDB + +22.8 Optional Warnings and Messages +=================================== + +By default, GDB is silent about its inner workings. If you are running +on a slow machine, you may want to use the 'set verbose' command. This +makes GDB tell you when it does a lengthy internal operation, so you +will not think it has crashed. + + Currently, the messages controlled by 'set verbose' are those which +announce that the symbol table for a source file is being read; see +'symbol-file' in *note Commands to Specify Files: Files. + +'set verbose on' + Enables GDB output of certain informational messages. + +'set verbose off' + Disables GDB output of certain informational messages. + +'show verbose' + Displays whether 'set verbose' is on or off. + + By default, if GDB encounters bugs in the symbol table of an object +file, it is silent; but if you are debugging a compiler, you may find +this information useful (*note Errors Reading Symbol Files: Symbol +Errors.). + +'set complaints LIMIT' + Permits GDB to output LIMIT complaints about each type of unusual + symbols before becoming silent about the problem. Set LIMIT to + zero to suppress all complaints; set it to a large number to + prevent complaints from being suppressed. + +'show complaints' + Displays how many symbol complaints GDB is permitted to produce. + + By default, GDB is cautious, and asks what sometimes seems to be a +lot of stupid questions to confirm certain commands. For example, if +you try to run a program which is already running: + + (gdb) run + The program being debugged has been started already. + Start it from the beginning? (y or n) + + If you are willing to unflinchingly face the consequences of your own +commands, you can disable this "feature": + +'set confirm off' + Disables confirmation requests. Note that running GDB with the + '--batch' option (*note -batch: Mode Options.) also automatically + disables confirmation requests. + +'set confirm on' + Enables confirmation requests (the default). + +'show confirm' + Displays state of confirmation requests. + + If you need to debug user-defined commands or sourced files you may +find it useful to enable "command tracing". In this mode each command +will be printed as it is executed, prefixed with one or more '+' +symbols, the quantity denoting the call depth of each command. + +'set trace-commands on' + Enable command tracing. +'set trace-commands off' + Disable command tracing. +'show trace-commands' + Display the current state of command tracing. + + +File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Messages/Warnings, Up: Controlling GDB + +22.9 Optional Messages about Internal Happenings +================================================ + +GDB has commands that enable optional debugging messages from various +GDB subsystems; normally these commands are of interest to GDB +maintainers, or when reporting a bug. This section documents those +commands. + +'set exec-done-display' + Turns on or off the notification of asynchronous commands' + completion. When on, GDB will print a message when an asynchronous + command finishes its execution. The default is off. +'show exec-done-display' + Displays the current setting of asynchronous command completion + notification. +'set debug aarch64' + Turns on or off display of debugging messages related to ARM + AArch64. The default is off. +'show debug aarch64' + Displays the current state of displaying debugging messages related + to ARM AArch64. +'set debug arch' + Turns on or off display of gdbarch debugging info. The default is + off +'show debug arch' + Displays the current state of displaying gdbarch debugging info. +'set debug aix-solib' + Control display of debugging messages from the AIX shared library + support module. The default is off. +'show debug aix-thread' + Show the current state of displaying AIX shared library debugging + messages. +'set debug aix-thread' + Display debugging messages about inner workings of the AIX thread + module. +'show debug aix-thread' + Show the current state of AIX thread debugging info display. +'set debug check-physname' + Check the results of the "physname" computation. When reading + DWARF debugging information for C++, GDB attempts to compute each + entity's name. GDB can do this computation in two different ways, + depending on exactly what information is present. When enabled, + this setting causes GDB to compute the names both ways and display + any discrepancies. +'show debug check-physname' + Show the current state of "physname" checking. +'set debug coff-pe-read' + Control display of debugging messages related to reading of COFF/PE + exported symbols. The default is off. +'show debug coff-pe-read' + Displays the current state of displaying debugging messages related + to reading of COFF/PE exported symbols. +'set debug dwarf2-die' + Dump DWARF2 DIEs after they are read in. The value is the number + of nesting levels to print. A value of zero turns off the display. +'show debug dwarf2-die' + Show the current state of DWARF2 DIE debugging. +'set debug dwarf2-read' + Turns on or off display of debugging messages related to reading + DWARF debug info. The default is 0 (off). A value of 1 provides + basic information. A value greater than 1 provides more verbose + information. +'show debug dwarf2-read' + Show the current state of DWARF2 reader debugging. +'set debug displaced' + Turns on or off display of GDB debugging info for the displaced + stepping support. The default is off. +'show debug displaced' + Displays the current state of displaying GDB debugging info related + to displaced stepping. +'set debug event' + Turns on or off display of GDB event debugging info. The default + is off. +'show debug event' + Displays the current state of displaying GDB event debugging info. +'set debug expression' + Turns on or off display of debugging info about GDB expression + parsing. The default is off. +'show debug expression' + Displays the current state of displaying debugging info about GDB + expression parsing. +'set debug frame' + Turns on or off display of GDB frame debugging info. The default + is off. +'show debug frame' + Displays the current state of displaying GDB frame debugging info. +'set debug gnu-nat' + Turns on or off debugging messages from the GNU/Hurd debug support. +'show debug gnu-nat' + Show the current state of GNU/Hurd debugging messages. +'set debug infrun' + Turns on or off display of GDB debugging info for running the + inferior. The default is off. 'infrun.c' contains GDB's runtime + state machine used for implementing operations such as + single-stepping the inferior. +'show debug infrun' + Displays the current state of GDB inferior debugging. +'set debug jit' + Turns on or off debugging messages from JIT debug support. +'show debug jit' + Displays the current state of GDB JIT debugging. +'set debug lin-lwp' + Turns on or off debugging messages from the Linux LWP debug + support. +'show debug lin-lwp' + Show the current state of Linux LWP debugging messages. +'set debug mach-o' + Control display of debugging messages related to Mach-O symbols + processing. The default is off. +'show debug mach-o' + Displays the current state of displaying debugging messages related + to reading of COFF/PE exported symbols. +'set debug notification' + Turns on or off debugging messages about remote async notification. + The default is off. +'show debug notification' + Displays the current state of remote async notification debugging + messages. +'set debug observer' + Turns on or off display of GDB observer debugging. This includes + info such as the notification of observable events. +'show debug observer' + Displays the current state of observer debugging. +'set debug overload' + Turns on or off display of GDB C++ overload debugging info. This + includes info such as ranking of functions, etc. The default is + off. +'show debug overload' + Displays the current state of displaying GDB C++ overload debugging + info. +'set debug parser' + Turns on or off the display of expression parser debugging output. + Internally, this sets the 'yydebug' variable in the expression + parser. *Note Tracing Your Parser: (bison)Tracing, for details. + The default is off. +'show debug parser' + Show the current state of expression parser debugging. +'set debug remote' + Turns on or off display of reports on all packets sent back and + forth across the serial line to the remote machine. The info is + printed on the GDB standard output stream. The default is off. +'show debug remote' + Displays the state of display of remote packets. +'set debug serial' + Turns on or off display of GDB serial debugging info. The default + is off. +'show debug serial' + Displays the current state of displaying GDB serial debugging info. +'set debug solib-frv' + Turns on or off debugging messages for FR-V shared-library code. +'show debug solib-frv' + Display the current state of FR-V shared-library code debugging + messages. +'set debug symfile' + Turns on or off display of debugging messages related to symbol + file functions. The default is off. *Note Files::. +'show debug symfile' + Show the current state of symbol file debugging messages. +'set debug symtab-create' + Turns on or off display of debugging messages related to symbol + table creation. The default is 0 (off). A value of 1 provides + basic information. A value greater than 1 provides more verbose + information. +'show debug symtab-create' + Show the current state of symbol table creation debugging. +'set debug target' + Turns on or off display of GDB target debugging info. This info + includes what is going on at the target level of GDB, as it + happens. The default is 0. Set it to 1 to track events, and to 2 + to also track the value of large memory transfers. Changes to this + flag do not take effect until the next time you connect to a target + or use the 'run' command. +'show debug target' + Displays the current state of displaying GDB target debugging info. +'set debug timestamp' + Turns on or off display of timestamps with GDB debugging info. + When enabled, seconds and microseconds are displayed before each + debugging message. +'show debug timestamp' + Displays the current state of displaying timestamps with GDB + debugging info. +'set debugvarobj' + Turns on or off display of GDB variable object debugging info. The + default is off. +'show debugvarobj' + Displays the current state of displaying GDB variable object + debugging info. +'set debug xml' + Turns on or off debugging messages for built-in XML parsers. +'show debug xml' + Displays the current state of XML debugging messages. + + +File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Controlling GDB + +22.10 Other Miscellaneous Settings +================================== + +'set interactive-mode' + If 'on', forces GDB to assume that GDB was started in a terminal. + In practice, this means that GDB should wait for the user to answer + queries generated by commands entered at the command prompt. If + 'off', forces GDB to operate in the opposite mode, and it uses the + default answers to all queries. If 'auto' (the default), GDB tries + to determine whether its standard input is a terminal, and works in + interactive-mode if it is, non-interactively otherwise. + + In the vast majority of cases, the debugger should be able to guess + correctly which mode should be used. But this setting can be + useful in certain specific cases, such as running a MinGW GDB + inside a cygwin window. + +'show interactive-mode' + Displays whether the debugger is operating in interactive mode or + not. + + +File: gdb.info, Node: Extending GDB, Next: Interpreters, Prev: Controlling GDB, Up: Top + +23 Extending GDB +**************** + +GDB provides several mechanisms for extension. GDB also provides the +ability to automatically load extensions when it reads a file for +debugging. This allows the user to automatically customize GDB for the +program being debugged. + +* Menu: + +* Sequences:: Canned Sequences of GDB Commands +* Python:: Extending GDB using Python +* Auto-loading extensions:: Automatically loading extensions +* Aliases:: Creating new spellings of existing commands + + To facilitate the use of extension languages, GDB is capable of +evaluating the contents of a file. When doing so, GDB can recognize +which extension language is being used by looking at the filename +extension. Files with an unrecognized filename extension are always +treated as a GDB Command Files. *Note Command files: Command Files. + + You can control how GDB evaluates these files with the following +setting: + +'set script-extension off' + All scripts are always evaluated as GDB Command Files. + +'set script-extension soft' + The debugger determines the scripting language based on filename + extension. If this scripting language is supported, GDB evaluates + the script using that language. Otherwise, it evaluates the file + as a GDB Command File. + +'set script-extension strict' + The debugger determines the scripting language based on filename + extension, and evaluates the script using that language. If the + language is not supported, then the evaluation fails. + +'show script-extension' + Display the current value of the 'script-extension' option. + + +File: gdb.info, Node: Sequences, Next: Python, Up: Extending GDB + +23.1 Canned Sequences of Commands +================================= + +Aside from breakpoint commands (*note Breakpoint Command Lists: Break +Commands.), GDB provides two ways to store sequences of commands for +execution as a unit: user-defined commands and command files. + +* Menu: + +* Define:: How to define your own commands +* Hooks:: Hooks for user-defined commands +* Command Files:: How to write scripts of commands to be stored in a file +* Output:: Commands for controlled output +* Auto-loading sequences:: Controlling auto-loaded command files + + +File: gdb.info, Node: Define, Next: Hooks, Up: Sequences + +23.1.1 User-defined Commands +---------------------------- + +A "user-defined command" is a sequence of GDB commands to which you +assign a new name as a command. This is done with the 'define' command. +User commands may accept up to 10 arguments separated by whitespace. +Arguments are accessed within the user command via '$arg0...$arg9'. A +trivial example: + + define adder + print $arg0 + $arg1 + $arg2 + end + +To execute the command use: + + adder 1 2 3 + +This defines the command 'adder', which prints the sum of its three +arguments. Note the arguments are text substitutions, so they may +reference variables, use complex expressions, or even perform inferior +functions calls. + + In addition, '$argc' may be used to find out how many arguments have +been passed. This expands to a number in the range 0...10. + + define adder + if $argc == 2 + print $arg0 + $arg1 + end + if $argc == 3 + print $arg0 + $arg1 + $arg2 + end + end + +'define COMMANDNAME' + Define a command named COMMANDNAME. If there is already a command + by that name, you are asked to confirm that you want to redefine + it. COMMANDNAME may be a bare command name consisting of letters, + numbers, dashes, and underscores. It may also start with any + predefined prefix command. For example, 'define target my-target' + creates a user-defined 'target my-target' command. + + The definition of the command is made up of other GDB command + lines, which are given following the 'define' command. The end of + these commands is marked by a line containing 'end'. + +'document COMMANDNAME' + Document the user-defined command COMMANDNAME, so that it can be + accessed by 'help'. The command COMMANDNAME must already be + defined. This command reads lines of documentation just as + 'define' reads the lines of the command definition, ending with + 'end'. After the 'document' command is finished, 'help' on command + COMMANDNAME displays the documentation you have written. + + You may use the 'document' command again to change the + documentation of a command. Redefining the command with 'define' + does not change the documentation. + +'dont-repeat' + Used inside a user-defined command, this tells GDB that this + command should not be repeated when the user hits (*note + repeat last command: Command Syntax.). + +'help user-defined' + List all user-defined commands and all python commands defined in + class COMAND_USER. The first line of the documentation or docstring + is included (if any). + +'show user' +'show user COMMANDNAME' + Display the GDB commands used to define COMMANDNAME (but not its + documentation). If no COMMANDNAME is given, display the + definitions for all user-defined commands. This does not work for + user-defined python commands. + +'show max-user-call-depth' +'set max-user-call-depth' + The value of 'max-user-call-depth' controls how many recursion + levels are allowed in user-defined commands before GDB suspects an + infinite recursion and aborts the command. This does not apply to + user-defined python commands. + + In addition to the above commands, user-defined commands frequently +use control flow commands, described in *note Command Files::. + + When user-defined commands are executed, the commands of the +definition are not printed. An error in any command stops execution of +the user-defined command. + + If used interactively, commands that would ask for confirmation +proceed without asking when used inside a user-defined command. Many +GDB commands that normally print messages to say what they are doing +omit the messages when used in a user-defined command. + + +File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences + +23.1.2 User-defined Command Hooks +--------------------------------- + +You may define "hooks", which are a special kind of user-defined +command. Whenever you run the command 'foo', if the user-defined +command 'hook-foo' exists, it is executed (with no arguments) before +that command. + + A hook may also be defined which is run after the command you +executed. Whenever you run the command 'foo', if the user-defined +command 'hookpost-foo' exists, it is executed (with no arguments) after +that command. Post-execution hooks may exist simultaneously with +pre-execution hooks, for the same command. + + It is valid for a hook to call the command which it hooks. If this +occurs, the hook is not re-executed, thereby avoiding infinite +recursion. + + In addition, a pseudo-command, 'stop' exists. Defining ('hook-stop') +makes the associated commands execute every time execution stops in your +program: before breakpoint commands are run, displays are printed, or +the stack frame is printed. + + For example, to ignore 'SIGALRM' signals while single-stepping, but +treat them normally during normal execution, you could define: + + define hook-stop + handle SIGALRM nopass + end + + define hook-run + handle SIGALRM pass + end + + define hook-continue + handle SIGALRM pass + end + + As a further example, to hook at the beginning and end of the 'echo' +command, and to add extra text to the beginning and end of the message, +you could define: + + define hook-echo + echo <<<--- + end + + define hookpost-echo + echo --->>>\n + end + + (gdb) echo Hello World + <<<---Hello World--->>> + (gdb) + + You can define a hook for any single-word command in GDB, but not for +command aliases; you should define a hook for the basic command name, +e.g. 'backtrace' rather than 'bt'. You can hook a multi-word command by +adding 'hook-' or 'hookpost-' to the last word of the command, e.g. +'define target hook-remote' to add a hook to 'target remote'. + + If an error occurs during the execution of your hook, execution of +GDB commands stops and GDB issues a prompt (before the command that you +actually typed had a chance to run). + + If you try to define a hook which does not match any known command, +you get a warning from the 'define' command. + + +File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences + +23.1.3 Command Files +-------------------- + +A command file for GDB is a text file made of lines that are GDB +commands. Comments (lines starting with '#') may also be included. An +empty line in a command file does nothing; it does not mean to repeat +the last command, as it would from the terminal. + + You can request the execution of a command file with the 'source' +command. Note that the 'source' command is also used to evaluate +scripts that are not Command Files. The exact behavior can be +configured using the 'script-extension' setting. *Note Extending GDB: +Extending GDB. + +'source [-s] [-v] FILENAME' + Execute the command file FILENAME. + + The lines in a command file are generally executed sequentially, +unless the order of execution is changed by one of the _flow-control +commands_ described below. The commands are not printed as they are +executed. An error in any command terminates execution of the command +file and control is returned to the console. + + GDB first searches for FILENAME in the current directory. If the +file is not found there, and FILENAME does not specify a directory, then +GDB also looks for the file on the source search path (specified with +the 'directory' command); except that '$cdir' is not searched because +the compilation directory is not relevant to scripts. + + If '-s' is specified, then GDB searches for FILENAME on the search +path even if FILENAME specifies a directory. The search is done by +appending FILENAME to each element of the search path. So, for example, +if FILENAME is 'mylib/myscript' and the search path contains +'/home/user' then GDB will look for the script +'/home/user/mylib/myscript'. The search is also done if FILENAME is an +absolute path. For example, if FILENAME is '/tmp/myscript' and the +search path contains '/home/user' then GDB will look for the script +'/home/user/tmp/myscript'. For DOS-like systems, if FILENAME contains a +drive specification, it is stripped before concatenation. For example, +if FILENAME is 'd:myscript' and the search path contains 'c:/tmp' then +GDB will look for the script 'c:/tmp/myscript'. + + If '-v', for verbose mode, is given then GDB displays each command as +it is executed. The option must be given before FILENAME, and is +interpreted as part of the filename anywhere else. + + Commands that would ask for confirmation if used interactively +proceed without asking when used in a command file. Many GDB commands +that normally print messages to say what they are doing omit the +messages when called from command files. + + GDB also accepts command input from standard input. In this mode, +normal output goes to standard output and error output goes to standard +error. Errors in a command file supplied on standard input do not +terminate execution of the command file--execution continues with the +next command. + + gdb < cmds > log 2>&1 + + (The syntax above will vary depending on the shell used.) This +example will execute commands from the file 'cmds'. All output and +errors would be directed to 'log'. + + Since commands stored on command files tend to be more general than +commands typed interactively, they frequently need to deal with +complicated situations, such as different or unexpected values of +variables and symbols, changes in how the program being debugged is +built, etc. GDB provides a set of flow-control commands to deal with +these complexities. Using these commands, you can write complex scripts +that loop over data structures, execute commands conditionally, etc. + +'if' +'else' + This command allows to include in your script conditionally + executed commands. The 'if' command takes a single argument, which + is an expression to evaluate. It is followed by a series of + commands that are executed only if the expression is true (its + value is nonzero). There can then optionally be an 'else' line, + followed by a series of commands that are only executed if the + expression was false. The end of the list is marked by a line + containing 'end'. + +'while' + This command allows to write loops. Its syntax is similar to 'if': + the command takes a single argument, which is an expression to + evaluate, and must be followed by the commands to execute, one per + line, terminated by an 'end'. These commands are called the "body" + of the loop. The commands in the body of 'while' are executed + repeatedly as long as the expression evaluates to true. + +'loop_break' + This command exits the 'while' loop in whose body it is included. + Execution of the script continues after that 'while's 'end' line. + +'loop_continue' + This command skips the execution of the rest of the body of + commands in the 'while' loop in whose body it is included. + Execution branches to the beginning of the 'while' loop, where it + evaluates the controlling expression. + +'end' + Terminate the block of commands that are the body of 'if', 'else', + or 'while' flow-control commands. + + +File: gdb.info, Node: Output, Next: Auto-loading sequences, Prev: Command Files, Up: Sequences + +23.1.4 Commands for Controlled Output +------------------------------------- + +During the execution of a command file or a user-defined command, normal +GDB output is suppressed; the only output that appears is what is +explicitly printed by the commands in the definition. This section +describes three commands useful for generating exactly the output you +want. + +'echo TEXT' + Print TEXT. Nonprinting characters can be included in TEXT using C + escape sequences, such as '\n' to print a newline. *No newline is + printed unless you specify one.* In addition to the standard C + escape sequences, a backslash followed by a space stands for a + space. This is useful for displaying a string with spaces at the + beginning or the end, since leading and trailing spaces are + otherwise trimmed from all arguments. To print ' and foo = ', use + the command 'echo \ and foo = \ '. + + A backslash at the end of TEXT can be used, as in C, to continue + the command onto subsequent lines. For example, + + echo This is some text\n\ + which is continued\n\ + onto several lines.\n + + produces the same output as + + echo This is some text\n + echo which is continued\n + echo onto several lines.\n + +'output EXPRESSION' + Print the value of EXPRESSION and nothing but that value: no + newlines, no '$NN = '. The value is not entered in the value + history either. *Note Expressions: Expressions, for more + information on expressions. + +'output/FMT EXPRESSION' + Print the value of EXPRESSION in format FMT. You can use the same + formats as for 'print'. *Note Output Formats: Output Formats, for + more information. + +'printf TEMPLATE, EXPRESSIONS...' + Print the values of one or more EXPRESSIONS under the control of + the string TEMPLATE. To print several values, make EXPRESSIONS be + a comma-separated list of individual expressions, which may be + either numbers or pointers. Their values are printed as specified + by TEMPLATE, exactly as a C program would do by executing the code + below: + + printf (TEMPLATE, EXPRESSIONS...); + + As in 'C' 'printf', ordinary characters in TEMPLATE are printed + verbatim, while "conversion specification" introduced by the '%' + character cause subsequent EXPRESSIONS to be evaluated, their + values converted and formatted according to type and style + information encoded in the conversion specifications, and then + printed. + + For example, you can print two values in hex like this: + + printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo + + 'printf' supports all the standard 'C' conversion specifications, + including the flags and modifiers between the '%' character and the + conversion letter, with the following exceptions: + + * The argument-ordering modifiers, such as '2$', are not + supported. + + * The modifier '*' is not supported for specifying precision or + width. + + * The ''' flag (for separation of digits into groups according + to 'LC_NUMERIC'') is not supported. + + * The type modifiers 'hh', 'j', 't', and 'z' are not supported. + + * The conversion letter 'n' (as in '%n') is not supported. + + * The conversion letters 'a' and 'A' are not supported. + + Note that the 'll' type modifier is supported only if the + underlying 'C' implementation used to build GDB supports the 'long + long int' type, and the 'L' type modifier is supported only if + 'long double' type is available. + + As in 'C', 'printf' supports simple backslash-escape sequences, + such as '\n', '\t', '\\', '\"', '\a', and '\f', that consist of + backslash followed by a single character. Octal and hexadecimal + escape sequences are not supported. + + Additionally, 'printf' supports conversion specifications for DFP + ("Decimal Floating Point") types using the following length + modifiers together with a floating point specifier. letters: + + * 'H' for printing 'Decimal32' types. + + * 'D' for printing 'Decimal64' types. + + * 'DD' for printing 'Decimal128' types. + + If the underlying 'C' implementation used to build GDB has support + for the three length modifiers for DFP types, other modifiers such + as width and precision will also be available for GDB to use. + + In case there is no such 'C' support, no additional modifiers will + be available and the value will be printed in the standard way. + + Here's an example of printing DFP types using the above conversion + letters: + printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl + +'eval TEMPLATE, EXPRESSIONS...' + Convert the values of one or more EXPRESSIONS under the control of + the string TEMPLATE to a command line, and call it. + + +File: gdb.info, Node: Auto-loading sequences, Prev: Output, Up: Sequences + +23.1.5 Controlling auto-loading native GDB scripts +-------------------------------------------------- + +When a new object file is read (for example, due to the 'file' command, +or because the inferior has loaded a shared library), GDB will look for +the command file 'OBJFILE-gdb.gdb'. *Note Auto-loading extensions::. + + Auto-loading can be enabled or disabled, and the list of auto-loaded +scripts can be printed. + +'set auto-load gdb-scripts [on|off]' + Enable or disable the auto-loading of canned sequences of commands + scripts. + +'show auto-load gdb-scripts' + Show whether auto-loading of canned sequences of commands scripts + is enabled or disabled. + +'info auto-load gdb-scripts [REGEXP]' + Print the list of all canned sequences of commands scripts that GDB + auto-loaded. + + If REGEXP is supplied only canned sequences of commands scripts with +matching names are printed. + + +File: gdb.info, Node: Python, Next: Auto-loading extensions, Prev: Sequences, Up: Extending GDB + +23.2 Extending GDB using Python +=============================== + +You can extend GDB using the Python programming language +(http://www.python.org/). This feature is available only if GDB was +configured using '--with-python'. + + Python scripts used by GDB should be installed in +'DATA-DIRECTORY/python', where DATA-DIRECTORY is the data directory as +determined at GDB startup (*note Data Files::). This directory, known +as the "python directory", is automatically added to the Python Search +Path in order to allow the Python interpreter to locate all scripts +installed at this location. + + Additionally, GDB commands and convenience functions which are +written in Python and are located in the +'DATA-DIRECTORY/python/gdb/command' or +'DATA-DIRECTORY/python/gdb/function' directories are automatically +imported when GDB starts. + +* Menu: + +* Python Commands:: Accessing Python from GDB. +* Python API:: Accessing GDB from Python. +* Python Auto-loading:: Automatically loading Python code. +* Python modules:: Python modules provided by GDB. + + +File: gdb.info, Node: Python Commands, Next: Python API, Up: Python + +23.2.1 Python Commands +---------------------- + +GDB provides two commands for accessing the Python interpreter, and one +related setting: + +'python-interactive [COMMAND]' +'pi [COMMAND]' + Without an argument, the 'python-interactive' command can be used + to start an interactive Python prompt. To return to GDB, type the + 'EOF' character (e.g., 'Ctrl-D' on an empty prompt). + + Alternatively, a single-line Python command can be given as an + argument and evaluated. If the command is an expression, the + result will be printed; otherwise, nothing will be printed. For + example: + + (gdb) python-interactive 2 + 3 + 5 + +'python [COMMAND]' +'py [COMMAND]' + The 'python' command can be used to evaluate Python code. + + If given an argument, the 'python' command will evaluate the + argument as a Python command. For example: + + (gdb) python print 23 + 23 + + If you do not provide an argument to 'python', it will act as a + multi-line command, like 'define'. In this case, the Python script + is made up of subsequent command lines, given after the 'python' + command. This command list is terminated using a line containing + 'end'. For example: + + (gdb) python + Type python script + End with a line saying just "end". + >print 23 + >end + 23 + +'set python print-stack' + By default, GDB will print only the message component of a Python + exception when an error occurs in a Python script. This can be + controlled using 'set python print-stack': if 'full', then full + Python stack printing is enabled; if 'none', then Python stack and + message printing is disabled; if 'message', the default, only the + message component of the error is printed. + + It is also possible to execute a Python script from the GDB +interpreter: + +'source script-name' + The script name must end with '.py' and GDB must be configured to + recognize the script language based on filename extension using the + 'script-extension' setting. *Note Extending GDB: Extending GDB. + +'python execfile ("script-name")' + This method is based on the 'execfile' Python built-in function, + and thus is always available. + + +File: gdb.info, Node: Python API, Next: Python Auto-loading, Prev: Python Commands, Up: Python + +23.2.2 Python API +----------------- + +You can get quick online help for GDB's Python API by issuing the +command 'python help (gdb)'. + + Functions and methods which have two or more optional arguments allow +them to be specified using keyword syntax. This allows passing some +optional arguments while skipping others. Example: +'gdb.some_function ('foo', bar = 1, baz = 2)'. + +* Menu: + +* Basic Python:: Basic Python Functions. +* Exception Handling:: How Python exceptions are translated. +* Values From Inferior:: Python representation of values. +* Types In Python:: Python representation of types. +* Pretty Printing API:: Pretty-printing values. +* Selecting Pretty-Printers:: How GDB chooses a pretty-printer. +* Writing a Pretty-Printer:: Writing a Pretty-Printer. +* Type Printing API:: Pretty-printing types. +* Frame Filter API:: Filtering Frames. +* Frame Decorator API:: Decorating Frames. +* Writing a Frame Filter:: Writing a Frame Filter. +* Inferiors In Python:: Python representation of inferiors (processes) +* Events In Python:: Listening for events from GDB. +* Threads In Python:: Accessing inferior threads from Python. +* Commands In Python:: Implementing new commands in Python. +* Parameters In Python:: Adding new GDB parameters. +* Functions In Python:: Writing new convenience functions. +* Progspaces In Python:: Program spaces. +* Objfiles In Python:: Object files. +* Frames In Python:: Accessing inferior stack frames from Python. +* Blocks In Python:: Accessing blocks from Python. +* Symbols In Python:: Python representation of symbols. +* Symbol Tables In Python:: Python representation of symbol tables. +* Line Tables In Python:: Python representation of line tables. +* Breakpoints In Python:: Manipulating breakpoints using Python. +* Finish Breakpoints in Python:: Setting Breakpoints on function return + using Python. +* Lazy Strings In Python:: Python representation of lazy strings. +* Architectures In Python:: Python representation of architectures. + + +File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API + +23.2.2.1 Basic Python +..................... + +At startup, GDB overrides Python's 'sys.stdout' and 'sys.stderr' to +print using GDB's output-paging streams. A Python program which outputs +to one of these streams may have its output interrupted by the user +(*note Screen Size::). In this situation, a Python 'KeyboardInterrupt' +exception is thrown. + + Some care must be taken when writing Python code to run in GDB. Two +things worth noting in particular: + + * GDB install handlers for 'SIGCHLD' and 'SIGINT'. Python code must + not override these, or even change the options using 'sigaction'. + If your program changes the handling of these signals, GDB will + most likely stop working correctly. Note that it is unfortunately + common for GUI toolkits to install a 'SIGCHLD' handler. + + * GDB takes care to mark its internal file descriptors as + close-on-exec. However, this cannot be done in a thread-safe way + on all platforms. Your Python programs should be aware of this and + should both create new file descriptors with the close-on-exec flag + set and arrange to close unneeded file descriptors before starting + a child process. + + GDB introduces a new Python module, named 'gdb'. All methods and +classes added by GDB are placed in this module. GDB automatically +'import's the 'gdb' module for use in all scripts evaluated by the +'python' command. + + -- Variable: gdb.PYTHONDIR + A string containing the python directory (*note Python::). + + -- Function: gdb.execute (command [, from_tty [, to_string]]) + Evaluate COMMAND, a string, as a GDB CLI command. If a GDB + exception happens while COMMAND runs, it is translated as described + in *note Exception Handling: Exception Handling. + + FROM_TTY specifies whether GDB ought to consider this command as + having originated from the user invoking it interactively. It must + be a boolean value. If omitted, it defaults to 'False'. + + By default, any output produced by COMMAND is sent to GDB's + standard output. If the TO_STRING parameter is 'True', then output + will be collected by 'gdb.execute' and returned as a string. The + default is 'False', in which case the return value is 'None'. If + TO_STRING is 'True', the GDB virtual terminal will be temporarily + set to unlimited width and height, and its pagination will be + disabled; *note Screen Size::. + + -- Function: gdb.breakpoints () + Return a sequence holding all of GDB's breakpoints. *Note + Breakpoints In Python::, for more information. + + -- Function: gdb.parameter (parameter) + Return the value of a GDB parameter. PARAMETER is a string naming + the parameter to look up; PARAMETER may contain spaces if the + parameter has a multi-part name. For example, 'print object' is a + valid parameter name. + + If the named parameter does not exist, this function throws a + 'gdb.error' (*note Exception Handling::). Otherwise, the + parameter's value is converted to a Python value of the appropriate + type, and returned. + + -- Function: gdb.history (number) + Return a value from GDB's value history (*note Value History::). + NUMBER indicates which history element to return. If NUMBER is + negative, then GDB will take its absolute value and count backward + from the last element (i.e., the most recent element) to find the + value to return. If NUMBER is zero, then GDB will return the most + recent element. If the element specified by NUMBER doesn't exist + in the value history, a 'gdb.error' exception will be raised. + + If no exception is raised, the return value is always an instance + of 'gdb.Value' (*note Values From Inferior::). + + -- Function: gdb.parse_and_eval (expression) + Parse EXPRESSION as an expression in the current language, evaluate + it, and return the result as a 'gdb.Value'. EXPRESSION must be a + string. + + This function can be useful when implementing a new command (*note + Commands In Python::), as it provides a way to parse the command's + argument as an expression. It is also useful simply to compute + values, for example, it is the only way to get the value of a + convenience variable (*note Convenience Vars::) as a 'gdb.Value'. + + -- Function: gdb.find_pc_line (pc) + Return the 'gdb.Symtab_and_line' object corresponding to the PC + value. *Note Symbol Tables In Python::. If an invalid value of PC + is passed as an argument, then the 'symtab' and 'line' attributes + of the returned 'gdb.Symtab_and_line' object will be 'None' and 0 + respectively. + + -- Function: gdb.post_event (event) + Put EVENT, a callable object taking no arguments, into GDB's + internal event queue. This callable will be invoked at some later + point, during GDB's event processing. Events posted using + 'post_event' will be run in the order in which they were posted; + however, there is no way to know when they will be processed + relative to other events inside GDB. + + GDB is not thread-safe. If your Python program uses multiple + threads, you must be careful to only call GDB-specific functions in + the main GDB thread. 'post_event' ensures this. For example: + + (gdb) python + >import threading + > + >class Writer(): + > def __init__(self, message): + > self.message = message; + > def __call__(self): + > gdb.write(self.message) + > + >class MyThread1 (threading.Thread): + > def run (self): + > gdb.post_event(Writer("Hello ")) + > + >class MyThread2 (threading.Thread): + > def run (self): + > gdb.post_event(Writer("World\n")) + > + >MyThread1().start() + >MyThread2().start() + >end + (gdb) Hello World + + -- Function: gdb.write (string [, stream]) + Print a string to GDB's paginated output stream. The optional + STREAM determines the stream to print to. The default stream is + GDB's standard output stream. Possible stream values are: + + 'gdb.STDOUT' + GDB's standard output stream. + + 'gdb.STDERR' + GDB's standard error stream. + + 'gdb.STDLOG' + GDB's log stream (*note Logging Output::). + + Writing to 'sys.stdout' or 'sys.stderr' will automatically call + this function and will automatically direct the output to the + relevant stream. + + -- Function: gdb.flush () + Flush the buffer of a GDB paginated stream so that the contents are + displayed immediately. GDB will flush the contents of a stream + automatically when it encounters a newline in the buffer. The + optional STREAM determines the stream to flush. The default stream + is GDB's standard output stream. Possible stream values are: + + 'gdb.STDOUT' + GDB's standard output stream. + + 'gdb.STDERR' + GDB's standard error stream. + + 'gdb.STDLOG' + GDB's log stream (*note Logging Output::). + + Flushing 'sys.stdout' or 'sys.stderr' will automatically call this + function for the relevant stream. + + -- Function: gdb.target_charset () + Return the name of the current target character set (*note + Character Sets::). This differs from + 'gdb.parameter('target-charset')' in that 'auto' is never returned. + + -- Function: gdb.target_wide_charset () + Return the name of the current target wide character set (*note + Character Sets::). This differs from + 'gdb.parameter('target-wide-charset')' in that 'auto' is never + returned. + + -- Function: gdb.solib_name (address) + Return the name of the shared library holding the given ADDRESS as + a string, or 'None'. + + -- Function: gdb.decode_line [expression] + Return locations of the line specified by EXPRESSION, or of the + current line if no argument was given. This function returns a + Python tuple containing two elements. The first element contains a + string holding any unparsed section of EXPRESSION (or 'None' if the + expression has been fully parsed). The second element contains + either 'None' or another tuple that contains all the locations that + match the expression represented as 'gdb.Symtab_and_line' objects + (*note Symbol Tables In Python::). If EXPRESSION is provided, it + is decoded the way that GDB's inbuilt 'break' or 'edit' commands do + (*note Specify Location::). + + -- Function: gdb.prompt_hook (current_prompt) + + If PROMPT_HOOK is callable, GDB will call the method assigned to + this operation before a prompt is displayed by GDB. + + The parameter 'current_prompt' contains the current GDB prompt. + This method must return a Python string, or 'None'. If a string is + returned, the GDB prompt will be set to that string. If 'None' is + returned, GDB will continue to use the current prompt. + + Some prompts cannot be substituted in GDB. Secondary prompts such + as those used by readline for command input, and annotation related + prompts are prohibited from being changed. + + +File: gdb.info, Node: Exception Handling, Next: Values From Inferior, Prev: Basic Python, Up: Python API + +23.2.2.2 Exception Handling +........................... + +When executing the 'python' command, Python exceptions uncaught within +the Python code are translated to calls to GDB error-reporting +mechanism. If the command that called 'python' does not handle the +error, GDB will terminate it and print an error message containing the +Python exception name, the associated value, and the Python call stack +backtrace at the point where the exception was raised. Example: + + (gdb) python print foo + Traceback (most recent call last): + File "", line 1, in + NameError: name 'foo' is not defined + + GDB errors that happen in GDB commands invoked by Python code are +converted to Python exceptions. The type of the Python exception +depends on the error. + +'gdb.error' + This is the base class for most exceptions generated by GDB. It is + derived from 'RuntimeError', for compatibility with earlier + versions of GDB. + + If an error occurring in GDB does not fit into some more specific + category, then the generated exception will have this type. + +'gdb.MemoryError' + This is a subclass of 'gdb.error' which is thrown when an operation + tried to access invalid memory in the inferior. + +'KeyboardInterrupt' + User interrupt (via 'C-c' or by typing 'q' at a pagination prompt) + is translated to a Python 'KeyboardInterrupt' exception. + + In all cases, your exception handler will see the GDB error message +as its value and the Python call stack backtrace at the Python statement +closest to where the GDB error occured as the traceback. + + When implementing GDB commands in Python via 'gdb.Command', it is +useful to be able to throw an exception that doesn't cause a traceback +to be printed. For example, the user may have invoked the command +incorrectly. Use the 'gdb.GdbError' exception to handle this case. +Example: + + (gdb) python + >class HelloWorld (gdb.Command): + > """Greet the whole world.""" + > def __init__ (self): + > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) + > def invoke (self, args, from_tty): + > argv = gdb.string_to_argv (args) + > if len (argv) != 0: + > raise gdb.GdbError ("hello-world takes no arguments") + > print "Hello, World!" + >HelloWorld () + >end + (gdb) hello-world 42 + hello-world takes no arguments + + +File: gdb.info, Node: Values From Inferior, Next: Types In Python, Prev: Exception Handling, Up: Python API + +23.2.2.3 Values From Inferior +............................. + +GDB provides values it obtains from the inferior program in an object of +type 'gdb.Value'. GDB uses this object for its internal bookkeeping of +the inferior's values, and for fetching values when necessary. + + Inferior values that are simple scalars can be used directly in +Python expressions that are valid for the value's data type. Here's an +example for an integer or floating-point value 'some_val': + + bar = some_val + 2 + +As result of this, 'bar' will also be a 'gdb.Value' object whose values +are of the same type as those of 'some_val'. + + Inferior values that are structures or instances of some class can be +accessed using the Python "dictionary syntax". For example, if +'some_val' is a 'gdb.Value' instance holding a structure, you can access +its 'foo' element with: + + bar = some_val['foo'] + + Again, 'bar' will also be a 'gdb.Value' object. Structure elements +can also be accessed by using 'gdb.Field' objects as subscripts (*note +Types In Python::, for more information on 'gdb.Field' objects). For +example, if 'foo_field' is a 'gdb.Field' object corresponding to element +'foo' of the above structure, then 'bar' can also be accessed as +follows: + + bar = some_val[foo_field] + + A 'gdb.Value' that represents a function can be executed via inferior +function call. Any arguments provided to the call must match the +function's prototype, and must be provided in the order specified by +that prototype. + + For example, 'some_val' is a 'gdb.Value' instance representing a +function that takes two integers as arguments. To execute this +function, call it like so: + + result = some_val (10,20) + + Any values returned from a function call will be stored as a +'gdb.Value'. + + The following attributes are provided: + + -- Variable: Value.address + If this object is addressable, this read-only attribute holds a + 'gdb.Value' object representing the address. Otherwise, this + attribute holds 'None'. + + -- Variable: Value.is_optimized_out + This read-only boolean attribute is true if the compiler optimized + out this value, thus it is not available for fetching from the + inferior. + + -- Variable: Value.type + The type of this 'gdb.Value'. The value of this attribute is a + 'gdb.Type' object (*note Types In Python::). + + -- Variable: Value.dynamic_type + The dynamic type of this 'gdb.Value'. This uses C++ run-time type + information (RTTI) to determine the dynamic type of the value. If + this value is of class type, it will return the class in which the + value is embedded, if any. If this value is of pointer or + reference to a class type, it will compute the dynamic type of the + referenced object, and return a pointer or reference to that type, + respectively. In all other cases, it will return the value's + static type. + + Note that this feature will only work when debugging a C++ program + that includes RTTI for the object in question. Otherwise, it will + just return the static type of the value as in 'ptype foo' (*note + ptype: Symbols.). + + -- Variable: Value.is_lazy + The value of this read-only boolean attribute is 'True' if this + 'gdb.Value' has not yet been fetched from the inferior. GDB does + not fetch values until necessary, for efficiency. For example: + + myval = gdb.parse_and_eval ('somevar') + + The value of 'somevar' is not fetched at this time. It will be + fetched when the value is needed, or when the 'fetch_lazy' method + is invoked. + + The following methods are provided: + + -- Function: Value.__init__ (VAL) + Many Python values can be converted directly to a 'gdb.Value' via + this object initializer. Specifically: + + Python boolean + A Python boolean is converted to the boolean type from the + current language. + + Python integer + A Python integer is converted to the C 'long' type for the + current architecture. + + Python long + A Python long is converted to the C 'long long' type for the + current architecture. + + Python float + A Python float is converted to the C 'double' type for the + current architecture. + + Python string + A Python string is converted to a target string, using the + current target encoding. + + 'gdb.Value' + If 'val' is a 'gdb.Value', then a copy of the value is made. + + 'gdb.LazyString' + If 'val' is a 'gdb.LazyString' (*note Lazy Strings In + Python::), then the lazy string's 'value' method is called, + and its result is used. + + -- Function: Value.cast (type) + Return a new instance of 'gdb.Value' that is the result of casting + this instance to the type described by TYPE, which must be a + 'gdb.Type' object. If the cast cannot be performed for some + reason, this method throws an exception. + + -- Function: Value.dereference () + For pointer data types, this method returns a new 'gdb.Value' + object whose contents is the object pointed to by the pointer. For + example, if 'foo' is a C pointer to an 'int', declared in your C + program as + + int *foo; + + then you can use the corresponding 'gdb.Value' to access what 'foo' + points to like this: + + bar = foo.dereference () + + The result 'bar' will be a 'gdb.Value' object holding the value + pointed to by 'foo'. + + A similar function 'Value.referenced_value' exists which also + returns 'gdb.Value' objects corresonding to the values pointed to + by pointer values (and additionally, values referenced by reference + values). However, the behavior of 'Value.dereference' differs from + 'Value.referenced_value' by the fact that the behavior of + 'Value.dereference' is identical to applying the C unary operator + '*' on a given value. For example, consider a reference to a + pointer 'ptrref', declared in your C++ program as + + typedef int *intptr; + ... + int val = 10; + intptr ptr = &val; + intptr &ptrref = ptr; + + Though 'ptrref' is a reference value, one can apply the method + 'Value.dereference' to the 'gdb.Value' object corresponding to it + and obtain a 'gdb.Value' which is identical to that corresponding + to 'val'. However, if you apply the method + 'Value.referenced_value', the result would be a 'gdb.Value' object + identical to that corresponding to 'ptr'. + + py_ptrref = gdb.parse_and_eval ("ptrref") + py_val = py_ptrref.dereference () + py_ptr = py_ptrref.referenced_value () + + The 'gdb.Value' object 'py_val' is identical to that corresponding + to 'val', and 'py_ptr' is identical to that corresponding to 'ptr'. + In general, 'Value.dereference' can be applied whenever the C unary + operator '*' can be applied to the corresponding C value. For + those cases where applying both 'Value.dereference' and + 'Value.referenced_value' is allowed, the results obtained need not + be identical (as we have seen in the above example). The results + are however identical when applied on 'gdb.Value' objects + corresponding to pointers ('gdb.Value' objects with type code + 'TYPE_CODE_PTR') in a C/C++ program. + + -- Function: Value.referenced_value () + For pointer or reference data types, this method returns a new + 'gdb.Value' object corresponding to the value referenced by the + pointer/reference value. For pointer data types, + 'Value.dereference' and 'Value.referenced_value' produce identical + results. The difference between these methods is that + 'Value.dereference' cannot get the values referenced by reference + values. For example, consider a reference to an 'int', declared in + your C++ program as + + int val = 10; + int &ref = val; + + then applying 'Value.dereference' to the 'gdb.Value' object + corresponding to 'ref' will result in an error, while applying + 'Value.referenced_value' will result in a 'gdb.Value' object + identical to that corresponding to 'val'. + + py_ref = gdb.parse_and_eval ("ref") + er_ref = py_ref.dereference () # Results in error + py_val = py_ref.referenced_value () # Returns the referenced value + + The 'gdb.Value' object 'py_val' is identical to that corresponding + to 'val'. + + -- Function: Value.dynamic_cast (type) + Like 'Value.cast', but works as if the C++ 'dynamic_cast' operator + were used. Consult a C++ reference for details. + + -- Function: Value.reinterpret_cast (type) + Like 'Value.cast', but works as if the C++ 'reinterpret_cast' + operator were used. Consult a C++ reference for details. + + -- Function: Value.string ([encoding[, errors[, length]]]) + If this 'gdb.Value' represents a string, then this method converts + the contents to a Python string. Otherwise, this method will throw + an exception. + + Strings are recognized in a language-specific way; whether a given + 'gdb.Value' represents a string is determined by the current + language. + + For C-like languages, a value is a string if it is a pointer to or + an array of characters or ints. The string is assumed to be + terminated by a zero of the appropriate width. However if the + optional length argument is given, the string will be converted to + that given length, ignoring any embedded zeros that the string may + contain. + + If the optional ENCODING argument is given, it must be a string + naming the encoding of the string in the 'gdb.Value', such as + '"ascii"', '"iso-8859-6"' or '"utf-8"'. It accepts the same + encodings as the corresponding argument to Python's 'string.decode' + method, and the Python codec machinery will be used to convert the + string. If ENCODING is not given, or if ENCODING is the empty + string, then either the 'target-charset' (*note Character Sets::) + will be used, or a language-specific encoding will be used, if the + current language is able to supply one. + + The optional ERRORS argument is the same as the corresponding + argument to Python's 'string.decode' method. + + If the optional LENGTH argument is given, the string will be + fetched and converted to the given length. + + -- Function: Value.lazy_string ([encoding [, length]]) + If this 'gdb.Value' represents a string, then this method converts + the contents to a 'gdb.LazyString' (*note Lazy Strings In + Python::). Otherwise, this method will throw an exception. + + If the optional ENCODING argument is given, it must be a string + naming the encoding of the 'gdb.LazyString'. Some examples are: + 'ascii', 'iso-8859-6' or 'utf-8'. If the ENCODING argument is an + encoding that GDB does recognize, GDB will raise an error. + + When a lazy string is printed, the GDB encoding machinery is used + to convert the string during printing. If the optional ENCODING + argument is not provided, or is an empty string, GDB will + automatically select the encoding most suitable for the string + type. For further information on encoding in GDB please see *note + Character Sets::. + + If the optional LENGTH argument is given, the string will be + fetched and encoded to the length of characters specified. If the + LENGTH argument is not provided, the string will be fetched and + encoded until a null of appropriate width is found. + + -- Function: Value.fetch_lazy () + If the 'gdb.Value' object is currently a lazy value + ('gdb.Value.is_lazy' is 'True'), then the value is fetched from the + inferior. Any errors that occur in the process will produce a + Python exception. + + If the 'gdb.Value' object is not a lazy value, this method has no + effect. + + This method does not return a value. + + +File: gdb.info, Node: Types In Python, Next: Pretty Printing API, Prev: Values From Inferior, Up: Python API + +23.2.2.4 Types In Python +........................ + +GDB represents types from the inferior using the class 'gdb.Type'. + + The following type-related functions are available in the 'gdb' +module: + + -- Function: gdb.lookup_type (name [, block]) + This function looks up a type by name. NAME is the name of the + type to look up. It must be a string. + + If BLOCK is given, then NAME is looked up in that scope. + Otherwise, it is searched for globally. + + Ordinarily, this function will return an instance of 'gdb.Type'. + If the named type cannot be found, it will throw an exception. + + If the type is a structure or class type, or an enum type, the fields +of that type can be accessed using the Python "dictionary syntax". For +example, if 'some_type' is a 'gdb.Type' instance holding a structure +type, you can access its 'foo' field with: + + bar = some_type['foo'] + + 'bar' will be a 'gdb.Field' object; see below under the description +of the 'Type.fields' method for a description of the 'gdb.Field' class. + + An instance of 'Type' has the following attributes: + + -- Variable: Type.code + The type code for this type. The type code will be one of the + 'TYPE_CODE_' constants defined below. + + -- Variable: Type.name + The name of this type. If this type has no name, then 'None' is + returned. + + -- Variable: Type.sizeof + The size of this type, in target 'char' units. Usually, a target's + 'char' type will be an 8-bit byte. However, on some unusual + platforms, this type may have a different size. + + -- Variable: Type.tag + The tag name for this type. The tag name is the name after + 'struct', 'union', or 'enum' in C and C++; not all languages have + this concept. If this type has no tag name, then 'None' is + returned. + + The following methods are provided: + + -- Function: Type.fields () + For structure and union types, this method returns the fields. + Range types have two fields, the minimum and maximum values. Enum + types have one field per enum constant. Function and method types + have one field per parameter. The base types of C++ classes are + also represented as fields. If the type has no fields, or does not + fit into one of these categories, an empty sequence will be + returned. + + Each field is a 'gdb.Field' object, with some pre-defined + attributes: + 'bitpos' + This attribute is not available for 'enum' or 'static' (as in + C++ or Java) fields. The value is the position, counting in + bits, from the start of the containing type. + + 'enumval' + This attribute is only available for 'enum' fields, and its + value is the enumeration member's integer representation. + + 'name' + The name of the field, or 'None' for anonymous fields. + + 'artificial' + This is 'True' if the field is artificial, usually meaning + that it was provided by the compiler and not the user. This + attribute is always provided, and is 'False' if the field is + not artificial. + + 'is_base_class' + This is 'True' if the field represents a base class of a C++ + structure. This attribute is always provided, and is 'False' + if the field is not a base class of the type that is the + argument of 'fields', or if that type was not a C++ class. + + 'bitsize' + If the field is packed, or is a bitfield, then this will have + a non-zero value, which is the size of the field in bits. + Otherwise, this will be zero; in this case the field's size is + given by its type. + + 'type' + The type of the field. This is usually an instance of 'Type', + but it can be 'None' in some situations. + + 'parent_type' + The type which contains this field. This is an instance of + 'gdb.Type'. + + -- Function: Type.array (N1 [, N2]) + Return a new 'gdb.Type' object which represents an array of this + type. If one argument is given, it is the inclusive upper bound of + the array; in this case the lower bound is zero. If two arguments + are given, the first argument is the lower bound of the array, and + the second argument is the upper bound of the array. An array's + length must not be negative, but the bounds can be. + + -- Function: Type.vector (N1 [, N2]) + Return a new 'gdb.Type' object which represents a vector of this + type. If one argument is given, it is the inclusive upper bound of + the vector; in this case the lower bound is zero. If two arguments + are given, the first argument is the lower bound of the vector, and + the second argument is the upper bound of the vector. A vector's + length must not be negative, but the bounds can be. + + The difference between an 'array' and a 'vector' is that arrays + behave like in C: when used in expressions they decay to a pointer + to the first element whereas vectors are treated as first class + values. + + -- Function: Type.const () + Return a new 'gdb.Type' object which represents a 'const'-qualified + variant of this type. + + -- Function: Type.volatile () + Return a new 'gdb.Type' object which represents a + 'volatile'-qualified variant of this type. + + -- Function: Type.unqualified () + Return a new 'gdb.Type' object which represents an unqualified + variant of this type. That is, the result is neither 'const' nor + 'volatile'. + + -- Function: Type.range () + Return a Python 'Tuple' object that contains two elements: the low + bound of the argument type and the high bound of that type. If the + type does not have a range, GDB will raise a 'gdb.error' exception + (*note Exception Handling::). + + -- Function: Type.reference () + Return a new 'gdb.Type' object which represents a reference to this + type. + + -- Function: Type.pointer () + Return a new 'gdb.Type' object which represents a pointer to this + type. + + -- Function: Type.strip_typedefs () + Return a new 'gdb.Type' that represents the real type, after + removing all layers of typedefs. + + -- Function: Type.target () + Return a new 'gdb.Type' object which represents the target type of + this type. + + For a pointer type, the target type is the type of the pointed-to + object. For an array type (meaning C-like arrays), the target type + is the type of the elements of the array. For a function or method + type, the target type is the type of the return value. For a + complex type, the target type is the type of the elements. For a + typedef, the target type is the aliased type. + + If the type does not have a target, this method will throw an + exception. + + -- Function: Type.template_argument (n [, block]) + If this 'gdb.Type' is an instantiation of a template, this will + return a new 'gdb.Type' which represents the type of the Nth + template argument. + + If this 'gdb.Type' is not a template type, this will throw an + exception. Ordinarily, only C++ code will have template types. + + If BLOCK is given, then NAME is looked up in that scope. + Otherwise, it is searched for globally. + + Each type has a code, which indicates what category this type falls +into. The available type categories are represented by constants +defined in the 'gdb' module: + +'gdb.TYPE_CODE_PTR' + The type is a pointer. + +'gdb.TYPE_CODE_ARRAY' + The type is an array. + +'gdb.TYPE_CODE_STRUCT' + The type is a structure. + +'gdb.TYPE_CODE_UNION' + The type is a union. + +'gdb.TYPE_CODE_ENUM' + The type is an enum. + +'gdb.TYPE_CODE_FLAGS' + A bit flags type, used for things such as status registers. + +'gdb.TYPE_CODE_FUNC' + The type is a function. + +'gdb.TYPE_CODE_INT' + The type is an integer type. + +'gdb.TYPE_CODE_FLT' + A floating point type. + +'gdb.TYPE_CODE_VOID' + The special type 'void'. + +'gdb.TYPE_CODE_SET' + A Pascal set type. + +'gdb.TYPE_CODE_RANGE' + A range type, that is, an integer type with bounds. + +'gdb.TYPE_CODE_STRING' + A string type. Note that this is only used for certain languages + with language-defined string types; C strings are not represented + this way. + +'gdb.TYPE_CODE_BITSTRING' + A string of bits. It is deprecated. + +'gdb.TYPE_CODE_ERROR' + An unknown or erroneous type. + +'gdb.TYPE_CODE_METHOD' + A method type, as found in C++ or Java. + +'gdb.TYPE_CODE_METHODPTR' + A pointer-to-member-function. + +'gdb.TYPE_CODE_MEMBERPTR' + A pointer-to-member. + +'gdb.TYPE_CODE_REF' + A reference type. + +'gdb.TYPE_CODE_CHAR' + A character type. + +'gdb.TYPE_CODE_BOOL' + A boolean type. + +'gdb.TYPE_CODE_COMPLEX' + A complex float type. + +'gdb.TYPE_CODE_TYPEDEF' + A typedef to some other type. + +'gdb.TYPE_CODE_NAMESPACE' + A C++ namespace. + +'gdb.TYPE_CODE_DECFLOAT' + A decimal floating point type. + +'gdb.TYPE_CODE_INTERNAL_FUNCTION' + A function internal to GDB. This is the type used to represent + convenience functions. + + Further support for types is provided in the 'gdb.types' Python +module (*note gdb.types::). + + +File: gdb.info, Node: Pretty Printing API, Next: Selecting Pretty-Printers, Prev: Types In Python, Up: Python API + +23.2.2.5 Pretty Printing API +............................ + +An example output is provided (*note Pretty Printing::). + + A pretty-printer is just an object that holds a value and implements +a specific interface, defined here. + + -- Function: pretty_printer.children (self) + GDB will call this method on a pretty-printer to compute the + children of the pretty-printer's value. + + This method must return an object conforming to the Python iterator + protocol. Each item returned by the iterator must be a tuple + holding two elements. The first element is the "name" of the + child; the second element is the child's value. The value can be + any Python object which is convertible to a GDB value. + + This method is optional. If it does not exist, GDB will act as + though the value has no children. + + -- Function: pretty_printer.display_hint (self) + The CLI may call this method and use its result to change the + formatting of a value. The result will also be supplied to an MI + consumer as a 'displayhint' attribute of the variable being + printed. + + This method is optional. If it does exist, this method must return + a string. + + Some display hints are predefined by GDB: + + 'array' + Indicate that the object being printed is "array-like". The + CLI uses this to respect parameters such as 'set print + elements' and 'set print array'. + + 'map' + Indicate that the object being printed is "map-like", and that + the children of this value can be assumed to alternate between + keys and values. + + 'string' + Indicate that the object being printed is "string-like". If + the printer's 'to_string' method returns a Python string of + some kind, then GDB will call its internal language-specific + string-printing function to format the string. For the CLI + this means adding quotation marks, possibly escaping some + characters, respecting 'set print elements', and the like. + + -- Function: pretty_printer.to_string (self) + GDB will call this method to display the string representation of + the value passed to the object's constructor. + + When printing from the CLI, if the 'to_string' method exists, then + GDB will prepend its result to the values returned by 'children'. + Exactly how this formatting is done is dependent on the display + hint, and may change as more hints are added. Also, depending on + the print settings (*note Print Settings::), the CLI may print just + the result of 'to_string' in a stack trace, omitting the result of + 'children'. + + If this method returns a string, it is printed verbatim. + + Otherwise, if this method returns an instance of 'gdb.Value', then + GDB prints this value. This may result in a call to another + pretty-printer. + + If instead the method returns a Python value which is convertible + to a 'gdb.Value', then GDB performs the conversion and prints the + resulting value. Again, this may result in a call to another + pretty-printer. Python scalars (integers, floats, and booleans) + and strings are convertible to 'gdb.Value'; other types are not. + + Finally, if this method returns 'None' then no further operations + are peformed in this method and nothing is printed. + + If the result is not one of these types, an exception is raised. + + GDB provides a function which can be used to look up the default +pretty-printer for a 'gdb.Value': + + -- Function: gdb.default_visualizer (value) + This function takes a 'gdb.Value' object as an argument. If a + pretty-printer for this value exists, then it is returned. If no + such printer exists, then this returns 'None'. + + +File: gdb.info, Node: Selecting Pretty-Printers, Next: Writing a Pretty-Printer, Prev: Pretty Printing API, Up: Python API + +23.2.2.6 Selecting Pretty-Printers +.................................. + +The Python list 'gdb.pretty_printers' contains an array of functions or +callable objects that have been registered via addition as a +pretty-printer. Printers in this list are called 'global' printers, +they're available when debugging all inferiors. Each 'gdb.Progspace' +contains a 'pretty_printers' attribute. Each 'gdb.Objfile' also +contains a 'pretty_printers' attribute. + + Each function on these lists is passed a single 'gdb.Value' argument +and should return a pretty-printer object conforming to the interface +definition above (*note Pretty Printing API::). If a function cannot +create a pretty-printer for the value, it should return 'None'. + + GDB first checks the 'pretty_printers' attribute of each +'gdb.Objfile' in the current program space and iteratively calls each +enabled lookup routine in the list for that 'gdb.Objfile' until it +receives a pretty-printer object. If no pretty-printer is found in the +objfile lists, GDB then searches the pretty-printer list of the current +program space, calling each enabled function until an object is +returned. After these lists have been exhausted, it tries the global +'gdb.pretty_printers' list, again calling each enabled function until an +object is returned. + + The order in which the objfiles are searched is not specified. For a +given list, functions are always invoked from the head of the list, and +iterated over sequentially until the end of the list, or a printer +object is returned. + + For various reasons a pretty-printer may not work. For example, the +underlying data structure may have changed and the pretty-printer is out +of date. + + The consequences of a broken pretty-printer are severe enough that +GDB provides support for enabling and disabling individual printers. +For example, if 'print frame-arguments' is on, a backtrace can become +highly illegible if any argument is printed with a broken printer. + + Pretty-printers are enabled and disabled by attaching an 'enabled' +attribute to the registered function or callable object. If this +attribute is present and its value is 'False', the printer is disabled, +otherwise the printer is enabled. + + +File: gdb.info, Node: Writing a Pretty-Printer, Next: Type Printing API, Prev: Selecting Pretty-Printers, Up: Python API + +23.2.2.7 Writing a Pretty-Printer +................................. + +A pretty-printer consists of two parts: a lookup function to detect if +the type is supported, and the printer itself. + + Here is an example showing how a 'std::string' printer might be +written. *Note Pretty Printing API::, for details on the API this class +must provide. + + class StdStringPrinter(object): + "Print a std::string" + + def __init__(self, val): + self.val = val + + def to_string(self): + return self.val['_M_dataplus']['_M_p'] + + def display_hint(self): + return 'string' + + And here is an example showing how a lookup function for the printer +example above might be written. + + def str_lookup_function(val): + lookup_tag = val.type.tag + if lookup_tag == None: + return None + regex = re.compile("^std::basic_string$") + if regex.match(lookup_tag): + return StdStringPrinter(val) + return None + + The example lookup function extracts the value's type, and attempts +to match it to a type that it can pretty-print. If it is a type the +printer can pretty-print, it will return a printer object. If not, it +returns 'None'. + + We recommend that you put your core pretty-printers into a Python +package. If your pretty-printers are for use with a library, we further +recommend embedding a version number into the package name. This +practice will enable GDB to load multiple versions of your +pretty-printers at the same time, because they will have different +names. + + You should write auto-loaded code (*note Python Auto-loading::) such +that it can be evaluated multiple times without changing its meaning. +An ideal auto-load file will consist solely of 'import's of your printer +modules, followed by a call to a register pretty-printers with the +current objfile. + + Taken as a whole, this approach will scale nicely to multiple +inferiors, each potentially using a different library version. +Embedding a version number in the Python package name will ensure that +GDB is able to load both sets of printers simultaneously. Then, because +the search for pretty-printers is done by objfile, and because your +auto-loaded code took care to register your library's printers with a +specific objfile, GDB will find the correct printers for the specific +version of the library used by each inferior. + + To continue the 'std::string' example (*note Pretty Printing API::), +this code might appear in 'gdb.libstdcxx.v6': + + def register_printers(objfile): + objfile.pretty_printers.append(str_lookup_function) + +And then the corresponding contents of the auto-load file would be: + + import gdb.libstdcxx.v6 + gdb.libstdcxx.v6.register_printers(gdb.current_objfile()) + + The previous example illustrates a basic pretty-printer. There are a +few things that can be improved on. The printer doesn't have a name, +making it hard to identify in a list of installed printers. The lookup +function has a name, but lookup functions can have arbitrary, even +identical, names. + + Second, the printer only handles one type, whereas a library +typically has several types. One could install a lookup function for +each desired type in the library, but one could also have a single +lookup function recognize several types. The latter is the conventional +way this is handled. If a pretty-printer can handle multiple data +types, then its "subprinters" are the printers for the individual data +types. + + The 'gdb.printing' module provides a formal way of solving these +problems (*note gdb.printing::). Here is another example that handles +multiple types. + + These are the types we are going to pretty-print: + + struct foo { int a, b; }; + struct bar { struct foo x, y; }; + + Here are the printers: + + class fooPrinter: + """Print a foo object.""" + + def __init__(self, val): + self.val = val + + def to_string(self): + return ("a=<" + str(self.val["a"]) + + "> b=<" + str(self.val["b"]) + ">") + + class barPrinter: + """Print a bar object.""" + + def __init__(self, val): + self.val = val + + def to_string(self): + return ("x=<" + str(self.val["x"]) + + "> y=<" + str(self.val["y"]) + ">") + + This example doesn't need a lookup function, that is handled by the +'gdb.printing' module. Instead a function is provided to build up the +object that handles the lookup. + + import gdb.printing + + def build_pretty_printer(): + pp = gdb.printing.RegexpCollectionPrettyPrinter( + "my_library") + pp.add_printer('foo', '^foo$', fooPrinter) + pp.add_printer('bar', '^bar$', barPrinter) + return pp + + And here is the autoload support: + + import gdb.printing + import my_library + gdb.printing.register_pretty_printer( + gdb.current_objfile(), + my_library.build_pretty_printer()) + + Finally, when this printer is loaded into GDB, here is the +corresponding output of 'info pretty-printer': + + (gdb) info pretty-printer + my_library.so: + my_library + foo + bar + + +File: gdb.info, Node: Type Printing API, Next: Frame Filter API, Prev: Writing a Pretty-Printer, Up: Python API + +23.2.2.8 Type Printing API +.......................... + +GDB provides a way for Python code to customize type display. This is +mainly useful for substituting canonical typedef names for types. + + A "type printer" is just a Python object conforming to a certain +protocol. A simple base class implementing the protocol is provided; +see *note gdb.types::. A type printer must supply at least: + + -- Instance Variable of type_printer: enabled + A boolean which is True if the printer is enabled, and False + otherwise. This is manipulated by the 'enable type-printer' and + 'disable type-printer' commands. + + -- Instance Variable of type_printer: name + The name of the type printer. This must be a string. This is used + by the 'enable type-printer' and 'disable type-printer' commands. + + -- Method on type_printer: instantiate (self) + This is called by GDB at the start of type-printing. It is only + called if the type printer is enabled. This method must return a + new object that supplies a 'recognize' method, as described below. + + When displaying a type, say via the 'ptype' command, GDB will compute +a list of type recognizers. This is done by iterating first over the +per-objfile type printers (*note Objfiles In Python::), followed by the +per-progspace type printers (*note Progspaces In Python::), and finally +the global type printers. + + GDB will call the 'instantiate' method of each enabled type printer. +If this method returns 'None', then the result is ignored; otherwise, it +is appended to the list of recognizers. + + Then, when GDB is going to display a type name, it iterates over the +list of recognizers. For each one, it calls the recognition function, +stopping if the function returns a non-'None' value. The recognition +function is defined as: + + -- Method on type_recognizer: recognize (self, type) + If TYPE is not recognized, return 'None'. Otherwise, return a + string which is to be printed as the name of TYPE. TYPE will be an + instance of 'gdb.Type' (*note Types In Python::). + + GDB uses this two-pass approach so that type printers can efficiently +cache information without holding on to it too long. For example, it +can be convenient to look up type information in a type printer and hold +it for a recognizer's lifetime; if a single pass were done then type +printers would have to make use of the event system in order to avoid +holding information that could become stale as the inferior changed. + + +File: gdb.info, Node: Frame Filter API, Next: Frame Decorator API, Prev: Type Printing API, Up: Python API + +23.2.2.9 Filtering Frames. +.......................... + +Frame filters are Python objects that manipulate the visibility of a +frame or frames when a backtrace (*note Backtrace::) is printed by GDB. + + Only commands that print a backtrace, or, in the case of GDB/MI +commands (*note GDB/MI::), those that return a collection of frames are +affected. The commands that work with frame filters are: + + 'backtrace' (*note The backtrace command: backtrace-command.), +'-stack-list-frames' (*note The -stack-list-frames command: +-stack-list-frames.), '-stack-list-variables' (*note The +-stack-list-variables command: -stack-list-variables.), +'-stack-list-arguments' *note The -stack-list-arguments command: +-stack-list-arguments.) and '-stack-list-locals' (*note The +-stack-list-locals command: -stack-list-locals.). + + A frame filter works by taking an iterator as an argument, applying +actions to the contents of that iterator, and returning another iterator +(or, possibly, the same iterator it was provided in the case where the +filter does not perform any operations). Typically, frame filters +utilize tools such as the Python's 'itertools' module to work with and +create new iterators from the source iterator. Regardless of how a +filter chooses to apply actions, it must not alter the underlying GDB +frame or frames, or attempt to alter the call-stack within GDB. This +preserves data integrity within GDB. Frame filters are executed on a +priority basis and care should be taken that some frame filters may have +been executed before, and that some frame filters will be executed +after. + + An important consideration when designing frame filters, and well +worth reflecting upon, is that frame filters should avoid unwinding the +call stack if possible. Some stacks can run very deep, into the tens of +thousands in some cases. To search every frame when a frame filter +executes may be too expensive at that step. The frame filter cannot +know how many frames it has to iterate over, and it may have to iterate +through them all. This ends up duplicating effort as GDB performs this +iteration when it prints the frames. If the filter can defer unwinding +frames until frame decorators are executed, after the last filter has +executed, it should. *Note Frame Decorator API::, for more information +on decorators. Also, there are examples for both frame decorators and +filters in later chapters. *Note Writing a Frame Filter::, for more +information. + + The Python dictionary 'gdb.frame_filters' contains key/object +pairings that comprise a frame filter. Frame filters in this dictionary +are called 'global' frame filters, and they are available when debugging +all inferiors. These frame filters must register with the dictionary +directly. In addition to the 'global' dictionary, there are other +dictionaries that are loaded with different inferiors via auto-loading +(*note Python Auto-loading::). The two other areas where frame filter +dictionaries can be found are: 'gdb.Progspace' which contains a +'frame_filters' dictionary attribute, and each 'gdb.Objfile' object +which also contains a 'frame_filters' dictionary attribute. + + When a command is executed from GDB that is compatible with frame +filters, GDB combines the 'global', 'gdb.Progspace' and all +'gdb.Objfile' dictionaries currently loaded. All of the 'gdb.Objfile' +dictionaries are combined, as several frames, and thus several object +files, might be in use. GDB then prunes any frame filter whose +'enabled' attribute is 'False'. This pruned list is then sorted +according to the 'priority' attribute in each filter. + + Once the dictionaries are combined, pruned and sorted, GDB creates an +iterator which wraps each frame in the call stack in a 'FrameDecorator' +object, and calls each filter in order. The output from the previous +filter will always be the input to the next filter, and so on. + + Frame filters have a mandatory interface which each frame filter must +implement, defined here: + + -- Function: FrameFilter.filter (iterator) + GDB will call this method on a frame filter when it has reached the + order in the priority list for that filter. + + For example, if there are four frame filters: + + Name Priority + + Filter1 5 + Filter2 10 + Filter3 100 + Filter4 1 + + The order that the frame filters will be called is: + + Filter3 -> Filter2 -> Filter1 -> Filter4 + + Note that the output from 'Filter3' is passed to the input of + 'Filter2', and so on. + + This 'filter' method is passed a Python iterator. This iterator + contains a sequence of frame decorators that wrap each 'gdb.Frame', + or a frame decorator that wraps another frame decorator. The first + filter that is executed in the sequence of frame filters will + receive an iterator entirely comprised of default 'FrameDecorator' + objects. However, after each frame filter is executed, the + previous frame filter may have wrapped some or all of the frame + decorators with their own frame decorator. As frame decorators + must also conform to a mandatory interface, these decorators can be + assumed to act in a uniform manner (*note Frame Decorator API::). + + This method must return an object conforming to the Python iterator + protocol. Each item in the iterator must be an object conforming + to the frame decorator interface. If a frame filter does not wish + to perform any operations on this iterator, it should return that + iterator untouched. + + This method is not optional. If it does not exist, GDB will raise + and print an error. + + -- Variable: FrameFilter.name + The 'name' attribute must be Python string which contains the name + of the filter displayed by GDB (*note Frame Filter Management::). + This attribute may contain any combination of letters or numbers. + Care should be taken to ensure that it is unique. This attribute + is mandatory. + + -- Variable: FrameFilter.enabled + The 'enabled' attribute must be Python boolean. This attribute + indicates to GDB whether the frame filter is enabled, and should be + considered when frame filters are executed. If 'enabled' is + 'True', then the frame filter will be executed when any of the + backtrace commands detailed earlier in this chapter are executed. + If 'enabled' is 'False', then the frame filter will not be + executed. This attribute is mandatory. + + -- Variable: FrameFilter.priority + The 'priority' attribute must be Python integer. This attribute + controls the order of execution in relation to other frame filters. + There are no imposed limits on the range of 'priority' other than + it must be a valid integer. The higher the 'priority' attribute, + the sooner the frame filter will be executed in relation to other + frame filters. Although 'priority' can be negative, it is + recommended practice to assume zero is the lowest priority that a + frame filter can be assigned. Frame filters that have the same + priority are executed in unsorted order in that priority slot. + This attribute is mandatory. + + +File: gdb.info, Node: Frame Decorator API, Next: Writing a Frame Filter, Prev: Frame Filter API, Up: Python API + +23.2.2.10 Decorating Frames. +............................ + +Frame decorators are sister objects to frame filters (*note Frame Filter +API::). Frame decorators are applied by a frame filter and can only be +used in conjunction with frame filters. + + The purpose of a frame decorator is to customize the printed content +of each 'gdb.Frame' in commands where frame filters are executed. This +concept is called decorating a frame. Frame decorators decorate a +'gdb.Frame' with Python code contained within each API call. This +separates the actual data contained in a 'gdb.Frame' from the decorated +data produced by a frame decorator. This abstraction is necessary to +maintain integrity of the data contained in each 'gdb.Frame'. + + Frame decorators have a mandatory interface, defined below. + + GDB already contains a frame decorator called 'FrameDecorator'. This +contains substantial amounts of boilerplate code to decorate the content +of a 'gdb.Frame'. It is recommended that other frame decorators inherit +and extend this object, and only to override the methods needed. + + -- Function: FrameDecorator.elided (self) + + The 'elided' method groups frames together in a hierarchical + system. An example would be an interpreter, where multiple + low-level frames make up a single call in the interpreted language. + In this example, the frame filter would elide the low-level frames + and present a single high-level frame, representing the call in the + interpreted language, to the user. + + The 'elided' function must return an iterable and this iterable + must contain the frames that are being elided wrapped in a suitable + frame decorator. If no frames are being elided this function may + return an empty iterable, or 'None'. Elided frames are indented + from normal frames in a 'CLI' backtrace, or in the case of + 'GDB/MI', are placed in the 'children' field of the eliding frame. + + It is the frame filter's task to also filter out the elided frames + from the source iterator. This will avoid printing the frame + twice. + + -- Function: FrameDecorator.function (self) + + This method returns the name of the function in the frame that is + to be printed. + + This method must return a Python string describing the function, or + 'None'. + + If this function returns 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.address (self) + + This method returns the address of the frame that is to be printed. + + This method must return a Python numeric integer type of sufficient + size to describe the address of the frame, or 'None'. + + If this function returns a 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.filename (self) + + This method returns the filename and path associated with this + frame. + + This method must return a Python string containing the filename and + the path to the object file backing the frame, or 'None'. + + If this function returns a 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.line (self): + + This method returns the line number associated with the current + position within the function addressed by this frame. + + This method must return a Python integer type, or 'None'. + + If this function returns a 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.frame_args (self) + + This method must return an iterable, or 'None'. Returning an empty + iterable, or 'None' means frame arguments will not be printed for + this frame. This iterable must contain objects that implement two + methods, described here. + + This object must implement a 'argument' method which takes a single + 'self' parameter and must return a 'gdb.Symbol' (*note Symbols In + Python::), or a Python string. The object must also implement a + 'value' method which takes a single 'self' parameter and must + return a 'gdb.Value' (*note Values From Inferior::), a Python + value, or 'None'. If the 'value' method returns 'None', and the + 'argument' method returns a 'gdb.Symbol', GDB will look-up and + print the value of the 'gdb.Symbol' automatically. + + A brief example: + + class SymValueWrapper(): + + def __init__(self, symbol, value): + self.sym = symbol + self.val = value + + def value(self): + return self.val + + def symbol(self): + return self.sym + + class SomeFrameDecorator() + ... + ... + def frame_args(self): + args = [] + try: + block = self.inferior_frame.block() + except: + return None + + # Iterate over all symbols in a block. Only add + # symbols that are arguments. + for sym in block: + if not sym.is_argument: + continue + args.append(SymValueWrapper(sym,None)) + + # Add example synthetic argument. + args.append(SymValueWrapper(``foo'', 42)) + + return args + + -- Function: FrameDecorator.frame_locals (self) + + This method must return an iterable or 'None'. Returning an empty + iterable, or 'None' means frame local arguments will not be printed + for this frame. + + The object interface, the description of the various strategies for + reading frame locals, and the example are largely similar to those + described in the 'frame_args' function, (*note The frame filter + frame_args function: frame_args.). Below is a modified example: + + class SomeFrameDecorator() + ... + ... + def frame_locals(self): + vars = [] + try: + block = self.inferior_frame.block() + except: + return None + + # Iterate over all symbols in a block. Add all + # symbols, except arguments. + for sym in block: + if sym.is_argument: + continue + vars.append(SymValueWrapper(sym,None)) + + # Add an example of a synthetic local variable. + vars.append(SymValueWrapper(``bar'', 99)) + + return vars + + -- Function: FrameDecorator.inferior_frame (self): + + This method must return the underlying 'gdb.Frame' that this frame + decorator is decorating. GDB requires the underlying frame for + internal frame information to determine how to print certain values + when printing a frame. + + +File: gdb.info, Node: Writing a Frame Filter, Next: Inferiors In Python, Prev: Frame Decorator API, Up: Python API + +23.2.2.11 Writing a Frame Filter +................................ + +There are three basic elements that a frame filter must implement: it +must correctly implement the documented interface (*note Frame Filter +API::), it must register itself with GDB, and finally, it must decide if +it is to work on the data provided by GDB. In all cases, whether it +works on the iterator or not, each frame filter must return an iterator. +A bare-bones frame filter follows the pattern in the following example. + + import gdb + + class FrameFilter(): + + def __init__(self): + # Frame filter attribute creation. + # + # 'name' is the name of the filter that GDB will display. + # + # 'priority' is the priority of the filter relative to other + # filters. + # + # 'enabled' is a boolean that indicates whether this filter is + # enabled and should be executed. + + self.name = "Foo" + self.priority = 100 + self.enabled = True + + # Register this frame filter with the global frame_filters + # dictionary. + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + # Just return the iterator. + return frame_iter + + The frame filter in the example above implements the three +requirements for all frame filters. It implements the API, self +registers, and makes a decision on the iterator (in this case, it just +returns the iterator untouched). + + The first step is attribute creation and assignment, and as shown in +the comments the filter assigns the following attributes: 'name', +'priority' and whether the filter should be enabled with the 'enabled' +attribute. + + The second step is registering the frame filter with the dictionary +or dictionaries that the frame filter has interest in. As shown in the +comments, this filter just registers itself with the global dictionary +'gdb.frame_filters'. As noted earlier, 'gdb.frame_filters' is a +dictionary that is initialized in the 'gdb' module when GDB starts. +What dictionary a filter registers with is an important consideration. +Generally, if a filter is specific to a set of code, it should be +registered either in the 'objfile' or 'progspace' dictionaries as they +are specific to the program currently loaded in GDB. The global +dictionary is always present in GDB and is never unloaded. Any filters +registered with the global dictionary will exist until GDB exits. To +avoid filters that may conflict, it is generally better to register +frame filters against the dictionaries that more closely align with the +usage of the filter currently in question. *Note Python Auto-loading::, +for further information on auto-loading Python scripts. + + GDB takes a hands-off approach to frame filter registration, +therefore it is the frame filter's responsibility to ensure registration +has occurred, and that any exceptions are handled appropriately. In +particular, you may wish to handle exceptions relating to Python +dictionary key uniqueness. It is mandatory that the dictionary key is +the same as frame filter's 'name' attribute. When a user manages frame +filters (*note Frame Filter Management::), the names GDB will display +are those contained in the 'name' attribute. + + The final step of this example is the implementation of the 'filter' +method. As shown in the example comments, we define the 'filter' method +and note that the method must take an iterator, and also must return an +iterator. In this bare-bones example, the frame filter is not very +useful as it just returns the iterator untouched. However this is a +valid operation for frame filters that have the 'enabled' attribute set, +but decide not to operate on any frames. + + In the next example, the frame filter operates on all frames and +utilizes a frame decorator to perform some work on the frames. *Note +Frame Decorator API::, for further information on the frame decorator +interface. + + This example works on inlined frames. It highlights frames which are +inlined by tagging them with an "[inlined]" tag. By applying a frame +decorator to all frames with the Python 'itertools imap' method, the +example defers actions to the frame decorator. Frame decorators are +only processed when GDB prints the backtrace. + + This introduces a new decision making topic: whether to perform +decision making operations at the filtering step, or at the printing +step. In this example's approach, it does not perform any filtering +decisions at the filtering step beyond mapping a frame decorator to each +frame. This allows the actual decision making to be performed when each +frame is printed. This is an important consideration, and well worth +reflecting upon when designing a frame filter. An issue that frame +filters should avoid is unwinding the stack if possible. Some stacks +can run very deep, into the tens of thousands in some cases. To search +every frame to determine if it is inlined ahead of time may be too +expensive at the filtering step. The frame filter cannot know how many +frames it has to iterate over, and it would have to iterate through them +all. This ends up duplicating effort as GDB performs this iteration +when it prints the frames. + + In this example decision making can be deferred to the printing step. +As each frame is printed, the frame decorator can examine each frame in +turn when GDB iterates. From a performance viewpoint, this is the most +appropriate decision to make as it avoids duplicating the effort that +the printing step would undertake anyway. Also, if there are many frame +filters unwinding the stack during filtering, it can substantially delay +the printing of the backtrace which will result in large memory usage, +and a poor user experience. + + class InlineFilter(): + + def __init__(self): + self.name = "InlinedFrameFilter" + self.priority = 100 + self.enabled = True + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + frame_iter = itertools.imap(InlinedFrameDecorator, + frame_iter) + return frame_iter + + This frame filter is somewhat similar to the earlier example, except +that the 'filter' method applies a frame decorator object called +'InlinedFrameDecorator' to each element in the iterator. The 'imap' +Python method is light-weight. It does not proactively iterate over the +iterator, but rather creates a new iterator which wraps the existing +one. + + Below is the frame decorator for this example. + + class InlinedFrameDecorator(FrameDecorator): + + def __init__(self, fobj): + super(InlinedFrameDecorator, self).__init__(fobj) + + def function(self): + frame = fobj.inferior_frame() + name = str(frame.name()) + + if frame.type() == gdb.INLINE_FRAME: + name = name + " [inlined]" + + return name + + This frame decorator only defines and overrides the 'function' +method. It lets the supplied 'FrameDecorator', which is shipped with +GDB, perform the other work associated with printing this frame. + + The combination of these two objects create this output from a +backtrace: + + #0 0x004004e0 in bar () at inline.c:11 + #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21 + #2 0x00400566 in main () at inline.c:31 + + So in the case of this example, a frame decorator is applied to all +frames, regardless of whether they may be inlined or not. As GDB +iterates over the iterator produced by the frame filters, GDB executes +each frame decorator which then makes a decision on what to print in the +'function' callback. Using a strategy like this is a way to defer +decisions on the frame content to printing time. + +Eliding Frames +-------------- + +It might be that the above example is not desirable for representing +inlined frames, and a hierarchical approach may be preferred. If we +want to hierarchically represent frames, the 'elided' frame decorator +interface might be preferable. + + This example approaches the issue with the 'elided' method. This +example is quite long, but very simplistic. It is out-of-scope for this +section to write a complete example that comprehensively covers all +approaches of finding and printing inlined frames. However, this +example illustrates the approach an author might use. + + This example comprises of three sections. + + class InlineFrameFilter(): + + def __init__(self): + self.name = "InlinedFrameFilter" + self.priority = 100 + self.enabled = True + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + return ElidingInlineIterator(frame_iter) + + This frame filter is very similar to the other examples. The only +difference is this frame filter is wrapping the iterator provided to it +('frame_iter') with a custom iterator called 'ElidingInlineIterator'. +This again defers actions to when GDB prints the backtrace, as the +iterator is not traversed until printing. + + The iterator for this example is as follows. It is in this section +of the example where decisions are made on the content of the backtrace. + + class ElidingInlineIterator: + def __init__(self, ii): + self.input_iterator = ii + + def __iter__(self): + return self + + def next(self): + frame = next(self.input_iterator) + + if frame.inferior_frame().type() != gdb.INLINE_FRAME: + return frame + + try: + eliding_frame = next(self.input_iterator) + except StopIteration: + return frame + return ElidingFrameDecorator(eliding_frame, [frame]) + + This iterator implements the Python iterator protocol. When the +'next' function is called (when GDB prints each frame), the iterator +checks if this frame decorator, 'frame', is wrapping an inlined frame. +If it is not, it returns the existing frame decorator untouched. If it +is wrapping an inlined frame, it assumes that the inlined frame was +contained within the next oldest frame, 'eliding_frame', which it +fetches. It then creates and returns a frame decorator, +'ElidingFrameDecorator', which contains both the elided frame, and the +eliding frame. + + class ElidingInlineDecorator(FrameDecorator): + + def __init__(self, frame, elided_frames): + super(ElidingInlineDecorator, self).__init__(frame) + self.frame = frame + self.elided_frames = elided_frames + + def elided(self): + return iter(self.elided_frames) + + This frame decorator overrides one function and returns the inlined +frame in the 'elided' method. As before it lets 'FrameDecorator' do the +rest of the work involved in printing this frame. This produces the +following output. + + #0 0x004004e0 in bar () at inline.c:11 + #2 0x00400529 in main () at inline.c:25 + #1 0x00400529 in max (b=6, a=12) at inline.c:15 + + In that output, 'max' which has been inlined into 'main' is printed +hierarchically. Another approach would be to combine the 'function' +method, and the 'elided' method to both print a marker in the inlined +frame, and also show the hierarchical relationship. + diff --git a/util/X86MAC64/share/info/gdb.info-4 b/util/X86MAC64/share/info/gdb.info-4 new file mode 100644 index 0000000000..7d7a8fe1d1 --- /dev/null +++ b/util/X86MAC64/share/info/gdb.info-4 @@ -0,0 +1,8774 @@ +This is gdb.info, produced by makeinfo version 5.1 from gdb.texinfo. + +Copyright (C) 1988-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + +File: gdb.info, Node: Inferiors In Python, Next: Events In Python, Prev: Writing a Frame Filter, Up: Python API + +23.2.2.12 Inferiors In Python +............................. + +Programs which are being run under GDB are called inferiors (*note +Inferiors and Programs::). Python scripts can access information about +and manipulate inferiors controlled by GDB via objects of the +'gdb.Inferior' class. + + The following inferior-related functions are available in the 'gdb' +module: + + -- Function: gdb.inferiors () + Return a tuple containing all inferior objects. + + -- Function: gdb.selected_inferior () + Return an object representing the current inferior. + + A 'gdb.Inferior' object has the following attributes: + + -- Variable: Inferior.num + ID of inferior, as assigned by GDB. + + -- Variable: Inferior.pid + Process ID of the inferior, as assigned by the underlying operating + system. + + -- Variable: Inferior.was_attached + Boolean signaling whether the inferior was created using 'attach', + or started by GDB itself. + + A 'gdb.Inferior' object has the following methods: + + -- Function: Inferior.is_valid () + Returns 'True' if the 'gdb.Inferior' object is valid, 'False' if + not. A 'gdb.Inferior' object will become invalid if the inferior + no longer exists within GDB. All other 'gdb.Inferior' methods will + throw an exception if it is invalid at the time the method is + called. + + -- Function: Inferior.threads () + This method returns a tuple holding all the threads which are valid + when it is called. If there are no valid threads, the method will + return an empty tuple. + + -- Function: Inferior.read_memory (address, length) + Read LENGTH bytes of memory from the inferior, starting at ADDRESS. + Returns a buffer object, which behaves much like an array or a + string. It can be modified and given to the + 'Inferior.write_memory' function. In 'Python' 3, the return value + is a 'memoryview' object. + + -- Function: Inferior.write_memory (address, buffer [, length]) + Write the contents of BUFFER to the inferior, starting at ADDRESS. + The BUFFER parameter must be a Python object which supports the + buffer protocol, i.e., a string, an array or the object returned + from 'Inferior.read_memory'. If given, LENGTH determines the + number of bytes from BUFFER to be written. + + -- Function: Inferior.search_memory (address, length, pattern) + Search a region of the inferior memory starting at ADDRESS with the + given LENGTH using the search pattern supplied in PATTERN. The + PATTERN parameter must be a Python object which supports the buffer + protocol, i.e., a string, an array or the object returned from + 'gdb.read_memory'. Returns a Python 'Long' containing the address + where the pattern was found, or 'None' if the pattern could not be + found. + + +File: gdb.info, Node: Events In Python, Next: Threads In Python, Prev: Inferiors In Python, Up: Python API + +23.2.2.13 Events In Python +.......................... + +GDB provides a general event facility so that Python code can be +notified of various state changes, particularly changes that occur in +the inferior. + + An "event" is just an object that describes some state change. The +type of the object and its attributes will vary depending on the details +of the change. All the existing events are described below. + + In order to be notified of an event, you must register an event +handler with an "event registry". An event registry is an object in the +'gdb.events' module which dispatches particular events. A registry +provides methods to register and unregister event handlers: + + -- Function: EventRegistry.connect (object) + Add the given callable OBJECT to the registry. This object will be + called when an event corresponding to this registry occurs. + + -- Function: EventRegistry.disconnect (object) + Remove the given OBJECT from the registry. Once removed, the + object will no longer receive notifications of events. + + Here is an example: + + def exit_handler (event): + print "event type: exit" + print "exit code: %d" % (event.exit_code) + + gdb.events.exited.connect (exit_handler) + + In the above example we connect our handler 'exit_handler' to the +registry 'events.exited'. Once connected, 'exit_handler' gets called +when the inferior exits. The argument "event" in this example is of +type 'gdb.ExitedEvent'. As you can see in the example the 'ExitedEvent' +object has an attribute which indicates the exit code of the inferior. + + The following is a listing of the event registries that are available +and details of the events they emit: + +'events.cont' + Emits 'gdb.ThreadEvent'. + + Some events can be thread specific when GDB is running in non-stop + mode. When represented in Python, these events all extend + 'gdb.ThreadEvent'. Note, this event is not emitted directly; + instead, events which are emitted by this or other modules might + extend this event. Examples of these events are + 'gdb.BreakpointEvent' and 'gdb.ContinueEvent'. + + -- Variable: ThreadEvent.inferior_thread + In non-stop mode this attribute will be set to the specific + thread which was involved in the emitted event. Otherwise, it + will be set to 'None'. + + Emits 'gdb.ContinueEvent' which extends 'gdb.ThreadEvent'. + + This event indicates that the inferior has been continued after a + stop. For inherited attribute refer to 'gdb.ThreadEvent' above. + +'events.exited' + Emits 'events.ExitedEvent' which indicates that the inferior has + exited. 'events.ExitedEvent' has two attributes: + -- Variable: ExitedEvent.exit_code + An integer representing the exit code, if available, which the + inferior has returned. (The exit code could be unavailable + if, for example, GDB detaches from the inferior.) If the exit + code is unavailable, the attribute does not exist. + -- Variable: ExitedEvent inferior + A reference to the inferior which triggered the 'exited' + event. + +'events.stop' + Emits 'gdb.StopEvent' which extends 'gdb.ThreadEvent'. + + Indicates that the inferior has stopped. All events emitted by + this registry extend StopEvent. As a child of 'gdb.ThreadEvent', + 'gdb.StopEvent' will indicate the stopped thread when GDB is + running in non-stop mode. Refer to 'gdb.ThreadEvent' above for + more details. + + Emits 'gdb.SignalEvent' which extends 'gdb.StopEvent'. + + This event indicates that the inferior or one of its threads has + received as signal. 'gdb.SignalEvent' has the following + attributes: + + -- Variable: SignalEvent.stop_signal + A string representing the signal received by the inferior. A + list of possible signal values can be obtained by running the + command 'info signals' in the GDB command prompt. + + Also emits 'gdb.BreakpointEvent' which extends 'gdb.StopEvent'. + + 'gdb.BreakpointEvent' event indicates that one or more breakpoints + have been hit, and has the following attributes: + + -- Variable: BreakpointEvent.breakpoints + A sequence containing references to all the breakpoints (type + 'gdb.Breakpoint') that were hit. *Note Breakpoints In + Python::, for details of the 'gdb.Breakpoint' object. + -- Variable: BreakpointEvent.breakpoint + A reference to the first breakpoint that was hit. This + function is maintained for backward compatibility and is now + deprecated in favor of the 'gdb.BreakpointEvent.breakpoints' + attribute. + +'events.new_objfile' + Emits 'gdb.NewObjFileEvent' which indicates that a new object file + has been loaded by GDB. 'gdb.NewObjFileEvent' has one attribute: + + -- Variable: NewObjFileEvent.new_objfile + A reference to the object file ('gdb.Objfile') which has been + loaded. *Note Objfiles In Python::, for details of the + 'gdb.Objfile' object. + + +File: gdb.info, Node: Threads In Python, Next: Commands In Python, Prev: Events In Python, Up: Python API + +23.2.2.14 Threads In Python +........................... + +Python scripts can access information about, and manipulate inferior +threads controlled by GDB, via objects of the 'gdb.InferiorThread' +class. + + The following thread-related functions are available in the 'gdb' +module: + + -- Function: gdb.selected_thread () + This function returns the thread object for the selected thread. + If there is no selected thread, this will return 'None'. + + A 'gdb.InferiorThread' object has the following attributes: + + -- Variable: InferiorThread.name + The name of the thread. If the user specified a name using 'thread + name', then this returns that name. Otherwise, if an OS-supplied + name is available, then it is returned. Otherwise, this returns + 'None'. + + This attribute can be assigned to. The new value must be a string + object, which sets the new name, or 'None', which removes any + user-specified thread name. + + -- Variable: InferiorThread.num + ID of the thread, as assigned by GDB. + + -- Variable: InferiorThread.ptid + ID of the thread, as assigned by the operating system. This + attribute is a tuple containing three integers. The first is the + Process ID (PID); the second is the Lightweight Process ID (LWPID), + and the third is the Thread ID (TID). Either the LWPID or TID may + be 0, which indicates that the operating system does not use that + identifier. + + A 'gdb.InferiorThread' object has the following methods: + + -- Function: InferiorThread.is_valid () + Returns 'True' if the 'gdb.InferiorThread' object is valid, 'False' + if not. A 'gdb.InferiorThread' object will become invalid if the + thread exits, or the inferior that the thread belongs is deleted. + All other 'gdb.InferiorThread' methods will throw an exception if + it is invalid at the time the method is called. + + -- Function: InferiorThread.switch () + This changes GDB's currently selected thread to the one represented + by this object. + + -- Function: InferiorThread.is_stopped () + Return a Boolean indicating whether the thread is stopped. + + -- Function: InferiorThread.is_running () + Return a Boolean indicating whether the thread is running. + + -- Function: InferiorThread.is_exited () + Return a Boolean indicating whether the thread is exited. + + +File: gdb.info, Node: Commands In Python, Next: Parameters In Python, Prev: Threads In Python, Up: Python API + +23.2.2.15 Commands In Python +............................ + +You can implement new GDB CLI commands in Python. A CLI command is +implemented using an instance of the 'gdb.Command' class, most commonly +using a subclass. + + -- Function: Command.__init__ (name, COMMAND_CLASS [, COMPLETER_CLASS + [, PREFIX]]) + The object initializer for 'Command' registers the new command with + GDB. This initializer is normally invoked from the subclass' own + '__init__' method. + + NAME is the name of the command. If NAME consists of multiple + words, then the initial words are looked for as prefix commands. + In this case, if one of the prefix commands does not exist, an + exception is raised. + + There is no support for multi-line commands. + + COMMAND_CLASS should be one of the 'COMMAND_' constants defined + below. This argument tells GDB how to categorize the new command + in the help system. + + COMPLETER_CLASS is an optional argument. If given, it should be + one of the 'COMPLETE_' constants defined below. This argument + tells GDB how to perform completion for this command. If not + given, GDB will attempt to complete using the object's 'complete' + method (see below); if no such method is found, an error will occur + when completion is attempted. + + PREFIX is an optional argument. If 'True', then the new command is + a prefix command; sub-commands of this command may be registered. + + The help text for the new command is taken from the Python + documentation string for the command's class, if there is one. If + no documentation string is provided, the default value "This + command is not documented." is used. + + -- Function: Command.dont_repeat () + By default, a GDB command is repeated when the user enters a blank + line at the command prompt. A command can suppress this behavior + by invoking the 'dont_repeat' method. This is similar to the user + command 'dont-repeat', see *note dont-repeat: Define. + + -- Function: Command.invoke (argument, from_tty) + This method is called by GDB when this command is invoked. + + ARGUMENT is a string. It is the argument to the command, after + leading and trailing whitespace has been stripped. + + FROM_TTY is a boolean argument. When true, this means that the + command was entered by the user at the terminal; when false it + means that the command came from elsewhere. + + If this method throws an exception, it is turned into a GDB 'error' + call. Otherwise, the return value is ignored. + + To break ARGUMENT up into an argv-like string use + 'gdb.string_to_argv'. This function behaves identically to GDB's + internal argument lexer 'buildargv'. It is recommended to use this + for consistency. Arguments are separated by spaces and may be + quoted. Example: + + print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") + ['1', '2 "3', '4 "5', "6 '7"] + + -- Function: Command.complete (text, word) + This method is called by GDB when the user attempts completion on + this command. All forms of completion are handled by this method, + that is, the and key bindings (*note Completion::), and + the 'complete' command (*note complete: Help.). + + The arguments TEXT and WORD are both strings. TEXT holds the + complete command line up to the cursor's location. WORD holds the + last word of the command line; this is computed using a + word-breaking heuristic. + + The 'complete' method can return several values: + * If the return value is a sequence, the contents of the + sequence are used as the completions. It is up to 'complete' + to ensure that the contents actually do complete the word. A + zero-length sequence is allowed, it means that there were no + completions available. Only string elements of the sequence + are used; other elements in the sequence are ignored. + + * If the return value is one of the 'COMPLETE_' constants + defined below, then the corresponding GDB-internal completion + function is invoked, and its result is used. + + * All other results are treated as though there were no + available completions. + + When a new command is registered, it must be declared as a member of +some general class of commands. This is used to classify top-level +commands in the on-line help system; note that prefix commands are not +listed under their own category but rather that of their top-level +command. The available classifications are represented by constants +defined in the 'gdb' module: + +'gdb.COMMAND_NONE' + The command does not belong to any particular class. A command in + this category will not be displayed in any of the help categories. + +'gdb.COMMAND_RUNNING' + The command is related to running the inferior. For example, + 'start', 'step', and 'continue' are in this category. Type 'help + running' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_DATA' + The command is related to data or variables. For example, 'call', + 'find', and 'print' are in this category. Type 'help data' at the + GDB prompt to see a list of commands in this category. + +'gdb.COMMAND_STACK' + The command has to do with manipulation of the stack. For example, + 'backtrace', 'frame', and 'return' are in this category. Type + 'help stack' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_FILES' + This class is used for file-related commands. For example, 'file', + 'list' and 'section' are in this category. Type 'help files' at + the GDB prompt to see a list of commands in this category. + +'gdb.COMMAND_SUPPORT' + This should be used for "support facilities", generally meaning + things that are useful to the user when interacting with GDB, but + not related to the state of the inferior. For example, 'help', + 'make', and 'shell' are in this category. Type 'help support' at + the GDB prompt to see a list of commands in this category. + +'gdb.COMMAND_STATUS' + The command is an 'info'-related command, that is, related to the + state of GDB itself. For example, 'info', 'macro', and 'show' are + in this category. Type 'help status' at the GDB prompt to see a + list of commands in this category. + +'gdb.COMMAND_BREAKPOINTS' + The command has to do with breakpoints. For example, 'break', + 'clear', and 'delete' are in this category. Type 'help + breakpoints' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_TRACEPOINTS' + The command has to do with tracepoints. For example, 'trace', + 'actions', and 'tfind' are in this category. Type 'help + tracepoints' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_USER' + The command is a general purpose command for the user, and + typically does not fit in one of the other categories. Type 'help + user-defined' at the GDB prompt to see a list of commands in this + category, as well as the list of gdb macros (*note Sequences::). + +'gdb.COMMAND_OBSCURE' + The command is only used in unusual circumstances, or is not of + general interest to users. For example, 'checkpoint', 'fork', and + 'stop' are in this category. Type 'help obscure' at the GDB prompt + to see a list of commands in this category. + +'gdb.COMMAND_MAINTENANCE' + The command is only useful to GDB maintainers. The 'maintenance' + and 'flushregs' commands are in this category. Type 'help + internals' at the GDB prompt to see a list of commands in this + category. + + A new command can use a predefined completion function, either by +specifying it via an argument at initialization, or by returning it from +the 'complete' method. These predefined completion constants are all +defined in the 'gdb' module: + +'gdb.COMPLETE_NONE' + This constant means that no completion should be done. + +'gdb.COMPLETE_FILENAME' + This constant means that filename completion should be performed. + +'gdb.COMPLETE_LOCATION' + This constant means that location completion should be done. *Note + Specify Location::. + +'gdb.COMPLETE_COMMAND' + This constant means that completion should examine GDB command + names. + +'gdb.COMPLETE_SYMBOL' + This constant means that completion should be done using symbol + names as the source. + +'gdb.COMPLETE_EXPRESSION' + This constant means that completion should be done on expressions. + Often this means completing on symbol names, but some language + parsers also have support for completing on field names. + + The following code snippet shows how a trivial CLI command can be +implemented in Python: + + class HelloWorld (gdb.Command): + """Greet the whole world.""" + + def __init__ (self): + super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) + + def invoke (self, arg, from_tty): + print "Hello, World!" + + HelloWorld () + + The last line instantiates the class, and is necessary to trigger the +registration of the command with GDB. Depending on how the Python code +is read into GDB, you may need to import the 'gdb' module explicitly. + + +File: gdb.info, Node: Parameters In Python, Next: Functions In Python, Prev: Commands In Python, Up: Python API + +23.2.2.16 Parameters In Python +.............................. + +You can implement new GDB parameters using Python. A new parameter is +implemented as an instance of the 'gdb.Parameter' class. + + Parameters are exposed to the user via the 'set' and 'show' commands. +*Note Help::. + + There are many parameters that already exist and can be set in GDB. +Two examples are: 'set follow fork' and 'set charset'. Setting these +parameters influences certain behavior in GDB. Similarly, you can +define parameters that can be used to influence behavior in custom +Python scripts and commands. + + -- Function: Parameter.__init__ (name, COMMAND-CLASS, PARAMETER-CLASS + [, ENUM-SEQUENCE]) + The object initializer for 'Parameter' registers the new parameter + with GDB. This initializer is normally invoked from the subclass' + own '__init__' method. + + NAME is the name of the new parameter. If NAME consists of + multiple words, then the initial words are looked for as prefix + parameters. An example of this can be illustrated with the 'set + print' set of parameters. If NAME is 'print foo', then 'print' + will be searched as the prefix parameter. In this case the + parameter can subsequently be accessed in GDB as 'set print foo'. + + If NAME consists of multiple words, and no prefix parameter group + can be found, an exception is raised. + + COMMAND-CLASS should be one of the 'COMMAND_' constants (*note + Commands In Python::). This argument tells GDB how to categorize + the new parameter in the help system. + + PARAMETER-CLASS should be one of the 'PARAM_' constants defined + below. This argument tells GDB the type of the new parameter; this + information is used for input validation and completion. + + If PARAMETER-CLASS is 'PARAM_ENUM', then ENUM-SEQUENCE must be a + sequence of strings. These strings represent the possible values + for the parameter. + + If PARAMETER-CLASS is not 'PARAM_ENUM', then the presence of a + fourth argument will cause an exception to be thrown. + + The help text for the new parameter is taken from the Python + documentation string for the parameter's class, if there is one. + If there is no documentation string, a default value is used. + + -- Variable: Parameter.set_doc + If this attribute exists, and is a string, then its value is used + as the help text for this parameter's 'set' command. The value is + examined when 'Parameter.__init__' is invoked; subsequent changes + have no effect. + + -- Variable: Parameter.show_doc + If this attribute exists, and is a string, then its value is used + as the help text for this parameter's 'show' command. The value is + examined when 'Parameter.__init__' is invoked; subsequent changes + have no effect. + + -- Variable: Parameter.value + The 'value' attribute holds the underlying value of the parameter. + It can be read and assigned to just as any other attribute. GDB + does validation when assignments are made. + + There are two methods that should be implemented in any 'Parameter' +class. These are: + + -- Function: Parameter.get_set_string (self) + GDB will call this method when a PARAMETER's value has been changed + via the 'set' API (for example, 'set foo off'). The 'value' + attribute has already been populated with the new value and may be + used in output. This method must return a string. + + -- Function: Parameter.get_show_string (self, svalue) + GDB will call this method when a PARAMETER's 'show' API has been + invoked (for example, 'show foo'). The argument 'svalue' receives + the string representation of the current value. This method must + return a string. + + When a new parameter is defined, its type must be specified. The +available types are represented by constants defined in the 'gdb' +module: + +'gdb.PARAM_BOOLEAN' + The value is a plain boolean. The Python boolean values, 'True' + and 'False' are the only valid values. + +'gdb.PARAM_AUTO_BOOLEAN' + The value has three possible states: true, false, and 'auto'. In + Python, true and false are represented using boolean constants, and + 'auto' is represented using 'None'. + +'gdb.PARAM_UINTEGER' + The value is an unsigned integer. The value of 0 should be + interpreted to mean "unlimited". + +'gdb.PARAM_INTEGER' + The value is a signed integer. The value of 0 should be + interpreted to mean "unlimited". + +'gdb.PARAM_STRING' + The value is a string. When the user modifies the string, any + escape sequences, such as '\t', '\f', and octal escapes, are + translated into corresponding characters and encoded into the + current host charset. + +'gdb.PARAM_STRING_NOESCAPE' + The value is a string. When the user modifies the string, escapes + are passed through untranslated. + +'gdb.PARAM_OPTIONAL_FILENAME' + The value is a either a filename (a string), or 'None'. + +'gdb.PARAM_FILENAME' + The value is a filename. This is just like + 'PARAM_STRING_NOESCAPE', but uses file names for completion. + +'gdb.PARAM_ZINTEGER' + The value is an integer. This is like 'PARAM_INTEGER', except 0 is + interpreted as itself. + +'gdb.PARAM_ENUM' + The value is a string, which must be one of a collection string + constants provided when the parameter is created. + + +File: gdb.info, Node: Functions In Python, Next: Progspaces In Python, Prev: Parameters In Python, Up: Python API + +23.2.2.17 Writing new convenience functions +........................................... + +You can implement new convenience functions (*note Convenience Vars::) +in Python. A convenience function is an instance of a subclass of the +class 'gdb.Function'. + + -- Function: Function.__init__ (name) + The initializer for 'Function' registers the new function with GDB. + The argument NAME is the name of the function, a string. The + function will be visible to the user as a convenience variable of + type 'internal function', whose name is the same as the given NAME. + + The documentation for the new function is taken from the + documentation string for the new class. + + -- Function: Function.invoke (*ARGS) + When a convenience function is evaluated, its arguments are + converted to instances of 'gdb.Value', and then the function's + 'invoke' method is called. Note that GDB does not predetermine the + arity of convenience functions. Instead, all available arguments + are passed to 'invoke', following the standard Python calling + convention. In particular, a convenience function can have default + values for parameters without ill effect. + + The return value of this method is used as its value in the + enclosing expression. If an ordinary Python value is returned, it + is converted to a 'gdb.Value' following the usual rules. + + The following code snippet shows how a trivial convenience function +can be implemented in Python: + + class Greet (gdb.Function): + """Return string to greet someone. + Takes a name as argument.""" + + def __init__ (self): + super (Greet, self).__init__ ("greet") + + def invoke (self, name): + return "Hello, %s!" % name.string () + + Greet () + + The last line instantiates the class, and is necessary to trigger the +registration of the function with GDB. Depending on how the Python code +is read into GDB, you may need to import the 'gdb' module explicitly. + + Now you can use the function in an expression: + + (gdb) print $greet("Bob") + $1 = "Hello, Bob!" + + +File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API + +23.2.2.18 Program Spaces In Python +.................................. + +A program space, or "progspace", represents a symbolic view of an +address space. It consists of all of the objfiles of the program. +*Note Objfiles In Python::. *Note program spaces: Inferiors and +Programs, for more details about program spaces. + + The following progspace-related functions are available in the 'gdb' +module: + + -- Function: gdb.current_progspace () + This function returns the program space of the currently selected + inferior. *Note Inferiors and Programs::. + + -- Function: gdb.progspaces () + Return a sequence of all the progspaces currently known to GDB. + + Each progspace is represented by an instance of the 'gdb.Progspace' +class. + + -- Variable: Progspace.filename + The file name of the progspace as a string. + + -- Variable: Progspace.pretty_printers + The 'pretty_printers' attribute is a list of functions. It is used + to look up pretty-printers. A 'Value' is passed to each function + in order; if the function returns 'None', then the search + continues. Otherwise, the return value should be an object which + is used to format the value. *Note Pretty Printing API::, for more + information. + + -- Variable: Progspace.type_printers + The 'type_printers' attribute is a list of type printer objects. + *Note Type Printing API::, for more information. + + -- Variable: Progspace.frame_filters + The 'frame_filters' attribute is a dictionary of frame filter + objects. *Note Frame Filter API::, for more information. + + +File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API + +23.2.2.19 Objfiles In Python +............................ + +GDB loads symbols for an inferior from various symbol-containing files +(*note Files::). These include the primary executable file, any shared +libraries used by the inferior, and any separate debug info files (*note +Separate Debug Files::). GDB calls these symbol-containing files +"objfiles". + + The following objfile-related functions are available in the 'gdb' +module: + + -- Function: gdb.current_objfile () + When auto-loading a Python script (*note Python Auto-loading::), + GDB sets the "current objfile" to the corresponding objfile. This + function returns the current objfile. If there is no current + objfile, this function returns 'None'. + + -- Function: gdb.objfiles () + Return a sequence of all the objfiles current known to GDB. *Note + Objfiles In Python::. + + Each objfile is represented by an instance of the 'gdb.Objfile' +class. + + -- Variable: Objfile.filename + The file name of the objfile as a string. + + -- Variable: Objfile.pretty_printers + The 'pretty_printers' attribute is a list of functions. It is used + to look up pretty-printers. A 'Value' is passed to each function + in order; if the function returns 'None', then the search + continues. Otherwise, the return value should be an object which + is used to format the value. *Note Pretty Printing API::, for more + information. + + -- Variable: Objfile.type_printers + The 'type_printers' attribute is a list of type printer objects. + *Note Type Printing API::, for more information. + + -- Variable: Objfile.frame_filters + The 'frame_filters' attribute is a dictionary of frame filter + objects. *Note Frame Filter API::, for more information. + + A 'gdb.Objfile' object has the following methods: + + -- Function: Objfile.is_valid () + Returns 'True' if the 'gdb.Objfile' object is valid, 'False' if + not. A 'gdb.Objfile' object can become invalid if the object file + it refers to is not loaded in GDB any longer. All other + 'gdb.Objfile' methods will throw an exception if it is invalid at + the time the method is called. + + +File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API + +23.2.2.20 Accessing inferior stack frames from Python. +...................................................... + +When the debugged program stops, GDB is able to analyze its call stack +(*note Stack frames: Frames.). The 'gdb.Frame' class represents a frame +in the stack. A 'gdb.Frame' object is only valid while its +corresponding frame exists in the inferior's stack. If you try to use +an invalid frame object, GDB will throw a 'gdb.error' exception (*note +Exception Handling::). + + Two 'gdb.Frame' objects can be compared for equality with the '==' +operator, like: + + (gdb) python print gdb.newest_frame() == gdb.selected_frame () + True + + The following frame-related functions are available in the 'gdb' +module: + + -- Function: gdb.selected_frame () + Return the selected frame object. (*note Selecting a Frame: + Selection.). + + -- Function: gdb.newest_frame () + Return the newest frame object for the selected thread. + + -- Function: gdb.frame_stop_reason_string (reason) + Return a string explaining the reason why GDB stopped unwinding + frames, as expressed by the given REASON code (an integer, see the + 'unwind_stop_reason' method further down in this section). + + A 'gdb.Frame' object has the following methods: + + -- Function: Frame.is_valid () + Returns true if the 'gdb.Frame' object is valid, false if not. A + frame object can become invalid if the frame it refers to doesn't + exist anymore in the inferior. All 'gdb.Frame' methods will throw + an exception if it is invalid at the time the method is called. + + -- Function: Frame.name () + Returns the function name of the frame, or 'None' if it can't be + obtained. + + -- Function: Frame.architecture () + Returns the 'gdb.Architecture' object corresponding to the frame's + architecture. *Note Architectures In Python::. + + -- Function: Frame.type () + Returns the type of the frame. The value can be one of: + 'gdb.NORMAL_FRAME' + An ordinary stack frame. + + 'gdb.DUMMY_FRAME' + A fake stack frame that was created by GDB when performing an + inferior function call. + + 'gdb.INLINE_FRAME' + A frame representing an inlined function. The function was + inlined into a 'gdb.NORMAL_FRAME' that is older than this one. + + 'gdb.TAILCALL_FRAME' + A frame representing a tail call. *Note Tail Call Frames::. + + 'gdb.SIGTRAMP_FRAME' + A signal trampoline frame. This is the frame created by the + OS when it calls into a signal handler. + + 'gdb.ARCH_FRAME' + A fake stack frame representing a cross-architecture call. + + 'gdb.SENTINEL_FRAME' + This is like 'gdb.NORMAL_FRAME', but it is only used for the + newest frame. + + -- Function: Frame.unwind_stop_reason () + Return an integer representing the reason why it's not possible to + find more frames toward the outermost frame. Use + 'gdb.frame_stop_reason_string' to convert the value returned by + this function to a string. The value can be one of: + + 'gdb.FRAME_UNWIND_NO_REASON' + No particular reason (older frames should be available). + + 'gdb.FRAME_UNWIND_NULL_ID' + The previous frame's analyzer returns an invalid result. This + is no longer used by GDB, and is kept only for backward + compatibility. + + 'gdb.FRAME_UNWIND_OUTERMOST' + This frame is the outermost. + + 'gdb.FRAME_UNWIND_UNAVAILABLE' + Cannot unwind further, because that would require knowing the + values of registers or memory that have not been collected. + + 'gdb.FRAME_UNWIND_INNER_ID' + This frame ID looks like it ought to belong to a NEXT frame, + but we got it for a PREV frame. Normally, this is a sign of + unwinder failure. It could also indicate stack corruption. + + 'gdb.FRAME_UNWIND_SAME_ID' + This frame has the same ID as the previous one. That means + that unwinding further would almost certainly give us another + frame with exactly the same ID, so break the chain. Normally, + this is a sign of unwinder failure. It could also indicate + stack corruption. + + 'gdb.FRAME_UNWIND_NO_SAVED_PC' + The frame unwinder did not find any saved PC, but we needed + one to unwind further. + + 'gdb.FRAME_UNWIND_FIRST_ERROR' + Any stop reason greater or equal to this value indicates some + kind of error. This special value facilitates writing code + that tests for errors in unwinding in a way that will work + correctly even if the list of the other values is modified in + future GDB versions. Using it, you could write: + reason = gdb.selected_frame().unwind_stop_reason () + reason_str = gdb.frame_stop_reason_string (reason) + if reason >= gdb.FRAME_UNWIND_FIRST_ERROR: + print "An error occured: %s" % reason_str + + -- Function: Frame.pc () + Returns the frame's resume address. + + -- Function: Frame.block () + Return the frame's code block. *Note Blocks In Python::. + + -- Function: Frame.function () + Return the symbol for the function corresponding to this frame. + *Note Symbols In Python::. + + -- Function: Frame.older () + Return the frame that called this frame. + + -- Function: Frame.newer () + Return the frame called by this frame. + + -- Function: Frame.find_sal () + Return the frame's symtab and line object. *Note Symbol Tables In + Python::. + + -- Function: Frame.read_var (variable [, block]) + Return the value of VARIABLE in this frame. If the optional + argument BLOCK is provided, search for the variable from that + block; otherwise start at the frame's current block (which is + determined by the frame's current program counter). VARIABLE must + be a string or a 'gdb.Symbol' object. BLOCK must be a 'gdb.Block' + object. + + -- Function: Frame.select () + Set this frame to be the selected frame. *Note Examining the + Stack: Stack. + + +File: gdb.info, Node: Blocks In Python, Next: Symbols In Python, Prev: Frames In Python, Up: Python API + +23.2.2.21 Accessing blocks from Python. +....................................... + +In GDB, symbols are stored in blocks. A block corresponds roughly to a +scope in the source code. Blocks are organized hierarchically, and are +represented individually in Python as a 'gdb.Block'. Blocks rely on +debugging information being available. + + A frame has a block. Please see *note Frames In Python::, for a more +in-depth discussion of frames. + + The outermost block is known as the "global block". The global block +typically holds public global variables and functions. + + The block nested just inside the global block is the "static block". +The static block typically holds file-scoped variables and functions. + + GDB provides a method to get a block's superblock, but there is +currently no way to examine the sub-blocks of a block, or to iterate +over all the blocks in a symbol table (*note Symbol Tables In Python::). + + Here is a short example that should help explain blocks: + + /* This is in the global block. */ + int global; + + /* This is in the static block. */ + static int file_scope; + + /* 'function' is in the global block, and 'argument' is + in a block nested inside of 'function'. */ + int function (int argument) + { + /* 'local' is in a block inside 'function'. It may or may + not be in the same block as 'argument'. */ + int local; + + { + /* 'inner' is in a block whose superblock is the one holding + 'local'. */ + int inner; + + /* If this call is expanded by the compiler, you may see + a nested block here whose function is 'inline_function' + and whose superblock is the one holding 'inner'. */ + inline_function (); + } + } + + A 'gdb.Block' is iterable. The iterator returns the symbols (*note +Symbols In Python::) local to the block. Python programs should not +assume that a specific block object will always contain a given symbol, +since changes in GDB features and infrastructure may cause symbols move +across blocks in a symbol table. + + The following block-related functions are available in the 'gdb' +module: + + -- Function: gdb.block_for_pc (pc) + Return the innermost 'gdb.Block' containing the given PC value. If + the block cannot be found for the PC value specified, the function + will return 'None'. + + A 'gdb.Block' object has the following methods: + + -- Function: Block.is_valid () + Returns 'True' if the 'gdb.Block' object is valid, 'False' if not. + A block object can become invalid if the block it refers to doesn't + exist anymore in the inferior. All other 'gdb.Block' methods will + throw an exception if it is invalid at the time the method is + called. The block's validity is also checked during iteration over + symbols of the block. + + A 'gdb.Block' object has the following attributes: + + -- Variable: Block.start + The start address of the block. This attribute is not writable. + + -- Variable: Block.end + The end address of the block. This attribute is not writable. + + -- Variable: Block.function + The name of the block represented as a 'gdb.Symbol'. If the block + is not named, then this attribute holds 'None'. This attribute is + not writable. + + For ordinary function blocks, the superblock is the static block. + However, you should note that it is possible for a function block + to have a superblock that is not the static block - for instance + this happens for an inlined function. + + -- Variable: Block.superblock + The block containing this block. If this parent block does not + exist, this attribute holds 'None'. This attribute is not + writable. + + -- Variable: Block.global_block + The global block associated with this block. This attribute is not + writable. + + -- Variable: Block.static_block + The static block associated with this block. This attribute is not + writable. + + -- Variable: Block.is_global + 'True' if the 'gdb.Block' object is a global block, 'False' if not. + This attribute is not writable. + + -- Variable: Block.is_static + 'True' if the 'gdb.Block' object is a static block, 'False' if not. + This attribute is not writable. + + +File: gdb.info, Node: Symbols In Python, Next: Symbol Tables In Python, Prev: Blocks In Python, Up: Python API + +23.2.2.22 Python representation of Symbols. +........................................... + +GDB represents every variable, function and type as an entry in a symbol +table. *Note Examining the Symbol Table: Symbols. Similarly, Python +represents these symbols in GDB with the 'gdb.Symbol' object. + + The following symbol-related functions are available in the 'gdb' +module: + + -- Function: gdb.lookup_symbol (name [, block [, domain]]) + This function searches for a symbol by name. The search scope can + be restricted to the parameters defined in the optional domain and + block arguments. + + NAME is the name of the symbol. It must be a string. The optional + BLOCK argument restricts the search to symbols visible in that + BLOCK. The BLOCK argument must be a 'gdb.Block' object. If + omitted, the block for the current frame is used. The optional + DOMAIN argument restricts the search to the domain type. The + DOMAIN argument must be a domain constant defined in the 'gdb' + module and described later in this chapter. + + The result is a tuple of two elements. The first element is a + 'gdb.Symbol' object or 'None' if the symbol is not found. If the + symbol is found, the second element is 'True' if the symbol is a + field of a method's object (e.g., 'this' in C++), otherwise it is + 'False'. If the symbol is not found, the second element is + 'False'. + + -- Function: gdb.lookup_global_symbol (name [, domain]) + This function searches for a global symbol by name. The search + scope can be restricted to by the domain argument. + + NAME is the name of the symbol. It must be a string. The optional + DOMAIN argument restricts the search to the domain type. The + DOMAIN argument must be a domain constant defined in the 'gdb' + module and described later in this chapter. + + The result is a 'gdb.Symbol' object or 'None' if the symbol is not + found. + + A 'gdb.Symbol' object has the following attributes: + + -- Variable: Symbol.type + The type of the symbol or 'None' if no type is recorded. This + attribute is represented as a 'gdb.Type' object. *Note Types In + Python::. This attribute is not writable. + + -- Variable: Symbol.symtab + The symbol table in which the symbol appears. This attribute is + represented as a 'gdb.Symtab' object. *Note Symbol Tables In + Python::. This attribute is not writable. + + -- Variable: Symbol.line + The line number in the source code at which the symbol was defined. + This is an integer. + + -- Variable: Symbol.name + The name of the symbol as a string. This attribute is not + writable. + + -- Variable: Symbol.linkage_name + The name of the symbol, as used by the linker (i.e., may be + mangled). This attribute is not writable. + + -- Variable: Symbol.print_name + The name of the symbol in a form suitable for output. This is + either 'name' or 'linkage_name', depending on whether the user + asked GDB to display demangled or mangled names. + + -- Variable: Symbol.addr_class + The address class of the symbol. This classifies how to find the + value of a symbol. Each address class is a constant defined in the + 'gdb' module and described later in this chapter. + + -- Variable: Symbol.needs_frame + This is 'True' if evaluating this symbol's value requires a frame + (*note Frames In Python::) and 'False' otherwise. Typically, local + variables will require a frame, but other symbols will not. + + -- Variable: Symbol.is_argument + 'True' if the symbol is an argument of a function. + + -- Variable: Symbol.is_constant + 'True' if the symbol is a constant. + + -- Variable: Symbol.is_function + 'True' if the symbol is a function or a method. + + -- Variable: Symbol.is_variable + 'True' if the symbol is a variable. + + A 'gdb.Symbol' object has the following methods: + + -- Function: Symbol.is_valid () + Returns 'True' if the 'gdb.Symbol' object is valid, 'False' if not. + A 'gdb.Symbol' object can become invalid if the symbol it refers to + does not exist in GDB any longer. All other 'gdb.Symbol' methods + will throw an exception if it is invalid at the time the method is + called. + + -- Function: Symbol.value ([frame]) + Compute the value of the symbol, as a 'gdb.Value'. For functions, + this computes the address of the function, cast to the appropriate + type. If the symbol requires a frame in order to compute its + value, then FRAME must be given. If FRAME is not given, or if + FRAME is invalid, then this method will throw an exception. + + The available domain categories in 'gdb.Symbol' are represented as +constants in the 'gdb' module: + +'gdb.SYMBOL_UNDEF_DOMAIN' + This is used when a domain has not been discovered or none of the + following domains apply. This usually indicates an error either in + the symbol information or in GDB's handling of symbols. +'gdb.SYMBOL_VAR_DOMAIN' + This domain contains variables, function names, typedef names and + enum type values. +'gdb.SYMBOL_STRUCT_DOMAIN' + This domain holds struct, union and enum type names. +'gdb.SYMBOL_LABEL_DOMAIN' + This domain contains names of labels (for gotos). +'gdb.SYMBOL_VARIABLES_DOMAIN' + This domain holds a subset of the 'SYMBOLS_VAR_DOMAIN'; it contains + everything minus functions and types. +'gdb.SYMBOL_FUNCTION_DOMAIN' + This domain contains all functions. +'gdb.SYMBOL_TYPES_DOMAIN' + This domain contains all types. + + The available address class categories in 'gdb.Symbol' are +represented as constants in the 'gdb' module: + +'gdb.SYMBOL_LOC_UNDEF' + If this is returned by address class, it indicates an error either + in the symbol information or in GDB's handling of symbols. +'gdb.SYMBOL_LOC_CONST' + Value is constant int. +'gdb.SYMBOL_LOC_STATIC' + Value is at a fixed address. +'gdb.SYMBOL_LOC_REGISTER' + Value is in a register. +'gdb.SYMBOL_LOC_ARG' + Value is an argument. This value is at the offset stored within + the symbol inside the frame's argument list. +'gdb.SYMBOL_LOC_REF_ARG' + Value address is stored in the frame's argument list. Just like + 'LOC_ARG' except that the value's address is stored at the offset, + not the value itself. +'gdb.SYMBOL_LOC_REGPARM_ADDR' + Value is a specified register. Just like 'LOC_REGISTER' except the + register holds the address of the argument instead of the argument + itself. +'gdb.SYMBOL_LOC_LOCAL' + Value is a local variable. +'gdb.SYMBOL_LOC_TYPEDEF' + Value not used. Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all + have this class. +'gdb.SYMBOL_LOC_BLOCK' + Value is a block. +'gdb.SYMBOL_LOC_CONST_BYTES' + Value is a byte-sequence. +'gdb.SYMBOL_LOC_UNRESOLVED' + Value is at a fixed address, but the address of the variable has to + be determined from the minimal symbol table whenever the variable + is referenced. +'gdb.SYMBOL_LOC_OPTIMIZED_OUT' + The value does not actually exist in the program. +'gdb.SYMBOL_LOC_COMPUTED' + The value's address is a computed location. + + +File: gdb.info, Node: Symbol Tables In Python, Next: Line Tables In Python, Prev: Symbols In Python, Up: Python API + +23.2.2.23 Symbol table representation in Python. +................................................ + +Access to symbol table data maintained by GDB on the inferior is exposed +to Python via two objects: 'gdb.Symtab_and_line' and 'gdb.Symtab'. +Symbol table and line data for a frame is returned from the 'find_sal' +method in 'gdb.Frame' object. *Note Frames In Python::. + + For more information on GDB's symbol table management, see *note +Examining the Symbol Table: Symbols, for more information. + + A 'gdb.Symtab_and_line' object has the following attributes: + + -- Variable: Symtab_and_line.symtab + The symbol table object ('gdb.Symtab') for this frame. This + attribute is not writable. + + -- Variable: Symtab_and_line.pc + Indicates the start of the address range occupied by code for the + current source line. This attribute is not writable. + + -- Variable: Symtab_and_line.last + Indicates the end of the address range occupied by code for the + current source line. This attribute is not writable. + + -- Variable: Symtab_and_line.line + Indicates the current line number for this object. This attribute + is not writable. + + A 'gdb.Symtab_and_line' object has the following methods: + + -- Function: Symtab_and_line.is_valid () + Returns 'True' if the 'gdb.Symtab_and_line' object is valid, + 'False' if not. A 'gdb.Symtab_and_line' object can become invalid + if the Symbol table and line object it refers to does not exist in + GDB any longer. All other 'gdb.Symtab_and_line' methods will throw + an exception if it is invalid at the time the method is called. + + A 'gdb.Symtab' object has the following attributes: + + -- Variable: Symtab.filename + The symbol table's source filename. This attribute is not + writable. + + -- Variable: Symtab.objfile + The symbol table's backing object file. *Note Objfiles In + Python::. This attribute is not writable. + + A 'gdb.Symtab' object has the following methods: + + -- Function: Symtab.is_valid () + Returns 'True' if the 'gdb.Symtab' object is valid, 'False' if not. + A 'gdb.Symtab' object can become invalid if the symbol table it + refers to does not exist in GDB any longer. All other 'gdb.Symtab' + methods will throw an exception if it is invalid at the time the + method is called. + + -- Function: Symtab.fullname () + Return the symbol table's source absolute file name. + + -- Function: Symtab.global_block () + Return the global block of the underlying symbol table. *Note + Blocks In Python::. + + -- Function: Symtab.static_block () + Return the static block of the underlying symbol table. *Note + Blocks In Python::. + + -- Function: Symtab.linetable () + Return the line table associated with the symbol table. *Note Line + Tables In Python::. + + +File: gdb.info, Node: Line Tables In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API + +23.2.2.24 Manipulating line tables using Python +............................................... + +Python code can request and inspect line table information from a symbol +table that is loaded in GDB. A line table is a mapping of source lines +to their executable locations in memory. To acquire the line table +information for a particular symbol table, use the 'linetable' function +(*note Symbol Tables In Python::). + + A 'gdb.LineTable' is iterable. The iterator returns 'LineTableEntry' +objects that correspond to the source line and address for each line +table entry. 'LineTableEntry' objects have the following attributes: + + -- Variable: LineTableEntry.line + The source line number for this line table entry. This number + corresponds to the actual line of source. This attribute is not + writable. + + -- Variable: LineTableEntry.pc + The address that is associated with the line table entry where the + executable code for that source line resides in memory. This + attribute is not writable. + + As there can be multiple addresses for a single source line, you may +receive multiple 'LineTableEntry' objects with matching 'line' +attributes, but with different 'pc' attributes. The iterator is sorted +in ascending 'pc' order. Here is a small example illustrating iterating +over a line table. + + symtab = gdb.selected_frame().find_sal().symtab + linetable = symtab.linetable() + for line in linetable: + print "Line: "+str(line.line)+" Address: "+hex(line.pc) + + This will have the following output: + + Line: 33 Address: 0x4005c8L + Line: 37 Address: 0x4005caL + Line: 39 Address: 0x4005d2L + Line: 40 Address: 0x4005f8L + Line: 42 Address: 0x4005ffL + Line: 44 Address: 0x400608L + Line: 42 Address: 0x40060cL + Line: 45 Address: 0x400615L + + In addition to being able to iterate over a 'LineTable', it also has +the following direct access methods: + + -- Function: LineTable.line (line) + Return a Python 'Tuple' of 'LineTableEntry' objects for any entries + in the line table for the given LINE. LINE refers to the source + code line. If there are no entries for that source code LINE, the + Python 'None' is returned. + + -- Function: LineTable.has_line (line) + Return a Python 'Boolean' indicating whether there is an entry in + the line table for this source line. Return 'True' if an entry is + found, or 'False' if not. + + -- Function: LineTable.source_lines () + Return a Python 'List' of the source line numbers in the symbol + table. Only lines with executable code locations are returned. + The contents of the 'List' will just be the source line entries + represented as Python 'Long' values. + + +File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Python, Prev: Line Tables In Python, Up: Python API + +23.2.2.25 Manipulating breakpoints using Python +............................................... + +Python code can manipulate breakpoints via the 'gdb.Breakpoint' class. + + -- Function: Breakpoint.__init__ (spec [, type [, wp_class [,internal + [,temporary]]]]) + Create a new breakpoint. SPEC is a string naming the location of + the breakpoint, or an expression that defines a watchpoint. The + contents can be any location recognized by the 'break' command, or + in the case of a watchpoint, by the 'watch' command. The optional + TYPE denotes the breakpoint to create from the types defined later + in this chapter. This argument can be either: 'gdb.BP_BREAKPOINT' + or 'gdb.BP_WATCHPOINT'. TYPE defaults to 'gdb.BP_BREAKPOINT'. The + optional INTERNAL argument allows the breakpoint to become + invisible to the user. The breakpoint will neither be reported + when created, nor will it be listed in the output from 'info + breakpoints' (but will be listed with the 'maint info breakpoints' + command). The optional TEMPORARY argument makes the breakpoint a + temporary breakpoint. Temporary breakpoints are deleted after they + have been hit. Any further access to the Python breakpoint after + it has been hit will result in a runtime error (as that breakpoint + has now been automatically deleted). The optional WP_CLASS + argument defines the class of watchpoint to create, if TYPE is + 'gdb.BP_WATCHPOINT'. If a watchpoint class is not provided, it is + assumed to be a 'gdb.WP_WRITE' class. + + -- Function: Breakpoint.stop (self) + The 'gdb.Breakpoint' class can be sub-classed and, in particular, + you may choose to implement the 'stop' method. If this method is + defined in a sub-class of 'gdb.Breakpoint', it will be called when + the inferior reaches any location of a breakpoint which + instantiates that sub-class. If the method returns 'True', the + inferior will be stopped at the location of the breakpoint, + otherwise the inferior will continue. + + If there are multiple breakpoints at the same location with a + 'stop' method, each one will be called regardless of the return + status of the previous. This ensures that all 'stop' methods have + a chance to execute at that location. In this scenario if one of + the methods returns 'True' but the others return 'False', the + inferior will still be stopped. + + You should not alter the execution state of the inferior (i.e., + step, next, etc.), alter the current frame context (i.e., change + the current active frame), or alter, add or delete any breakpoint. + As a general rule, you should not alter any data within GDB or the + inferior at this time. + + Example 'stop' implementation: + + class MyBreakpoint (gdb.Breakpoint): + def stop (self): + inf_val = gdb.parse_and_eval("foo") + if inf_val == 3: + return True + return False + + The available watchpoint types represented by constants are defined +in the 'gdb' module: + +'gdb.WP_READ' + Read only watchpoint. + +'gdb.WP_WRITE' + Write only watchpoint. + +'gdb.WP_ACCESS' + Read/Write watchpoint. + + -- Function: Breakpoint.is_valid () + Return 'True' if this 'Breakpoint' object is valid, 'False' + otherwise. A 'Breakpoint' object can become invalid if the user + deletes the breakpoint. In this case, the object still exists, but + the underlying breakpoint does not. In the cases of watchpoint + scope, the watchpoint remains valid even if execution of the + inferior leaves the scope of that watchpoint. + + -- Function: Breakpoint.delete + Permanently deletes the GDB breakpoint. This also invalidates the + Python 'Breakpoint' object. Any further access to this object's + attributes or methods will raise an error. + + -- Variable: Breakpoint.enabled + This attribute is 'True' if the breakpoint is enabled, and 'False' + otherwise. This attribute is writable. + + -- Variable: Breakpoint.silent + This attribute is 'True' if the breakpoint is silent, and 'False' + otherwise. This attribute is writable. + + Note that a breakpoint can also be silent if it has commands and + the first command is 'silent'. This is not reported by the + 'silent' attribute. + + -- Variable: Breakpoint.thread + If the breakpoint is thread-specific, this attribute holds the + thread id. If the breakpoint is not thread-specific, this + attribute is 'None'. This attribute is writable. + + -- Variable: Breakpoint.task + If the breakpoint is Ada task-specific, this attribute holds the + Ada task id. If the breakpoint is not task-specific (or the + underlying language is not Ada), this attribute is 'None'. This + attribute is writable. + + -- Variable: Breakpoint.ignore_count + This attribute holds the ignore count for the breakpoint, an + integer. This attribute is writable. + + -- Variable: Breakpoint.number + This attribute holds the breakpoint's number -- the identifier used + by the user to manipulate the breakpoint. This attribute is not + writable. + + -- Variable: Breakpoint.type + This attribute holds the breakpoint's type -- the identifier used + to determine the actual breakpoint type or use-case. This + attribute is not writable. + + -- Variable: Breakpoint.visible + This attribute tells whether the breakpoint is visible to the user + when set, or when the 'info breakpoints' command is run. This + attribute is not writable. + + -- Variable: Breakpoint.temporary + This attribute indicates whether the breakpoint was created as a + temporary breakpoint. Temporary breakpoints are automatically + deleted after that breakpoint has been hit. Access to this + attribute, and all other attributes and functions other than the + 'is_valid' function, will result in an error after the breakpoint + has been hit (as it has been automatically deleted). This + attribute is not writable. + + The available types are represented by constants defined in the 'gdb' +module: + +'gdb.BP_BREAKPOINT' + Normal code breakpoint. + +'gdb.BP_WATCHPOINT' + Watchpoint breakpoint. + +'gdb.BP_HARDWARE_WATCHPOINT' + Hardware assisted watchpoint. + +'gdb.BP_READ_WATCHPOINT' + Hardware assisted read watchpoint. + +'gdb.BP_ACCESS_WATCHPOINT' + Hardware assisted access watchpoint. + + -- Variable: Breakpoint.hit_count + This attribute holds the hit count for the breakpoint, an integer. + This attribute is writable, but currently it can only be set to + zero. + + -- Variable: Breakpoint.location + This attribute holds the location of the breakpoint, as specified + by the user. It is a string. If the breakpoint does not have a + location (that is, it is a watchpoint) the attribute's value is + 'None'. This attribute is not writable. + + -- Variable: Breakpoint.expression + This attribute holds a breakpoint expression, as specified by the + user. It is a string. If the breakpoint does not have an + expression (the breakpoint is not a watchpoint) the attribute's + value is 'None'. This attribute is not writable. + + -- Variable: Breakpoint.condition + This attribute holds the condition of the breakpoint, as specified + by the user. It is a string. If there is no condition, this + attribute's value is 'None'. This attribute is writable. + + -- Variable: Breakpoint.commands + This attribute holds the commands attached to the breakpoint. If + there are commands, this attribute's value is a string holding all + the commands, separated by newlines. If there are no commands, + this attribute is 'None'. This attribute is not writable. + + +File: gdb.info, Node: Finish Breakpoints in Python, Next: Lazy Strings In Python, Prev: Breakpoints In Python, Up: Python API + +23.2.2.26 Finish Breakpoints +............................ + +A finish breakpoint is a temporary breakpoint set at the return address +of a frame, based on the 'finish' command. 'gdb.FinishBreakpoint' +extends 'gdb.Breakpoint'. The underlying breakpoint will be disabled +and deleted when the execution will run out of the breakpoint scope +(i.e. 'Breakpoint.stop' or 'FinishBreakpoint.out_of_scope' triggered). +Finish breakpoints are thread specific and must be create with the right +thread selected. + + -- Function: FinishBreakpoint.__init__ ([frame] [, internal]) + Create a finish breakpoint at the return address of the 'gdb.Frame' + object FRAME. If FRAME is not provided, this defaults to the + newest frame. The optional INTERNAL argument allows the breakpoint + to become invisible to the user. *Note Breakpoints In Python::, + for further details about this argument. + + -- Function: FinishBreakpoint.out_of_scope (self) + In some circumstances (e.g. 'longjmp', C++ exceptions, GDB 'return' + command, ...), a function may not properly terminate, and thus + never hit the finish breakpoint. When GDB notices such a + situation, the 'out_of_scope' callback will be triggered. + + You may want to sub-class 'gdb.FinishBreakpoint' and override this + method: + + class MyFinishBreakpoint (gdb.FinishBreakpoint) + def stop (self): + print "normal finish" + return True + + def out_of_scope (): + print "abnormal finish" + + -- Variable: FinishBreakpoint.return_value + When GDB is stopped at a finish breakpoint and the frame used to + build the 'gdb.FinishBreakpoint' object had debug symbols, this + attribute will contain a 'gdb.Value' object corresponding to the + return value of the function. The value will be 'None' if the + function return type is 'void' or if the return value was not + computable. This attribute is not writable. + + +File: gdb.info, Node: Lazy Strings In Python, Next: Architectures In Python, Prev: Finish Breakpoints in Python, Up: Python API + +23.2.2.27 Python representation of lazy strings. +................................................ + +A "lazy string" is a string whose contents is not retrieved or encoded +until it is needed. + + A 'gdb.LazyString' is represented in GDB as an 'address' that points +to a region of memory, an 'encoding' that will be used to encode that +region of memory, and a 'length' to delimit the region of memory that +represents the string. The difference between a 'gdb.LazyString' and a +string wrapped within a 'gdb.Value' is that a 'gdb.LazyString' will be +treated differently by GDB when printing. A 'gdb.LazyString' is +retrieved and encoded during printing, while a 'gdb.Value' wrapping a +string is immediately retrieved and encoded on creation. + + A 'gdb.LazyString' object has the following functions: + + -- Function: LazyString.value () + Convert the 'gdb.LazyString' to a 'gdb.Value'. This value will + point to the string in memory, but will lose all the delayed + retrieval, encoding and handling that GDB applies to a + 'gdb.LazyString'. + + -- Variable: LazyString.address + This attribute holds the address of the string. This attribute is + not writable. + + -- Variable: LazyString.length + This attribute holds the length of the string in characters. If + the length is -1, then the string will be fetched and encoded up to + the first null of appropriate width. This attribute is not + writable. + + -- Variable: LazyString.encoding + This attribute holds the encoding that will be applied to the + string when the string is printed by GDB. If the encoding is not + set, or contains an empty string, then GDB will select the most + appropriate encoding when the string is printed. This attribute is + not writable. + + -- Variable: LazyString.type + This attribute holds the type that is represented by the lazy + string's type. For a lazy string this will always be a pointer + type. To resolve this to the lazy string's character type, use the + type's 'target' method. *Note Types In Python::. This attribute + is not writable. + + +File: gdb.info, Node: Architectures In Python, Prev: Lazy Strings In Python, Up: Python API + +23.2.2.28 Python representation of architectures +................................................ + +GDB uses architecture specific parameters and artifacts in a number of +its various computations. An architecture is represented by an instance +of the 'gdb.Architecture' class. + + A 'gdb.Architecture' class has the following methods: + + -- Function: Architecture.name () + Return the name (string value) of the architecture. + + -- Function: Architecture.disassemble (START_PC [, END_PC [, COUNT]]) + Return a list of disassembled instructions starting from the memory + address START_PC. The optional arguments END_PC and COUNT + determine the number of instructions in the returned list. If both + the optional arguments END_PC and COUNT are specified, then a list + of at most COUNT disassembled instructions whose start address + falls in the closed memory address interval from START_PC to END_PC + are returned. If END_PC is not specified, but COUNT is specified, + then COUNT number of instructions starting from the address + START_PC are returned. If COUNT is not specified but END_PC is + specified, then all instructions whose start address falls in the + closed memory address interval from START_PC to END_PC are + returned. If neither END_PC nor COUNT are specified, then a single + instruction at START_PC is returned. For all of these cases, each + element of the returned list is a Python 'dict' with the following + string keys: + + 'addr' + The value corresponding to this key is a Python long integer + capturing the memory address of the instruction. + + 'asm' + The value corresponding to this key is a string value which + represents the instruction with assembly language mnemonics. + The assembly language flavor used is the same as that + specified by the current CLI variable 'disassembly-flavor'. + *Note Machine Code::. + + 'length' + The value corresponding to this key is the length (integer + value) of the instruction in bytes. + + +File: gdb.info, Node: Python Auto-loading, Next: Python modules, Prev: Python API, Up: Python + +23.2.3 Python Auto-loading +-------------------------- + +When a new object file is read (for example, due to the 'file' command, +or because the inferior has loaded a shared library), GDB will look for +Python support scripts in several ways: 'OBJFILE-gdb.py' and +'.debug_gdb_scripts' section. *Note Auto-loading extensions::. + + The auto-loading feature is useful for supplying application-specific +debugging commands and scripts. + + Auto-loading can be enabled or disabled, and the list of auto-loaded +scripts can be printed. + +'set auto-load python-scripts [on|off]' + Enable or disable the auto-loading of Python scripts. + +'show auto-load python-scripts' + Show whether auto-loading of Python scripts is enabled or disabled. + +'info auto-load python-scripts [REGEXP]' + Print the list of all Python scripts that GDB auto-loaded. + + Also printed is the list of Python scripts that were mentioned in + the '.debug_gdb_scripts' section and were not found (*note + dotdebug_gdb_scripts section::). This is useful because their + names are not printed when GDB tries to load them and fails. There + may be many of them, and printing an error message for each one is + problematic. + + If REGEXP is supplied only Python scripts with matching names are + printed. + + Example: + + (gdb) info auto-load python-scripts + Loaded Script + Yes py-section-script.py + full name: /tmp/py-section-script.py + No my-foo-pretty-printers.py + + When reading an auto-loaded file, GDB sets the "current objfile". +This is available via the 'gdb.current_objfile' function (*note Objfiles +In Python::). This can be useful for registering objfile-specific +pretty-printers and frame-filters. + + +File: gdb.info, Node: Python modules, Prev: Python Auto-loading, Up: Python + +23.2.4 Python modules +--------------------- + +GDB comes with several modules to assist writing Python code. + +* Menu: + +* gdb.printing:: Building and registering pretty-printers. +* gdb.types:: Utilities for working with types. +* gdb.prompt:: Utilities for prompt value substitution. + + +File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules + +23.2.4.1 gdb.printing +..................... + +This module provides a collection of utilities for working with +pretty-printers. + +'PrettyPrinter (NAME, SUBPRINTERS=None)' + This class specifies the API that makes 'info pretty-printer', + 'enable pretty-printer' and 'disable pretty-printer' work. + Pretty-printers should generally inherit from this class. + +'SubPrettyPrinter (NAME)' + For printers that handle multiple types, this class specifies the + corresponding API for the subprinters. + +'RegexpCollectionPrettyPrinter (NAME)' + Utility class for handling multiple printers, all recognized via + regular expressions. *Note Writing a Pretty-Printer::, for an + example. + +'FlagEnumerationPrinter (NAME)' + A pretty-printer which handles printing of 'enum' values. Unlike + GDB's built-in 'enum' printing, this printer attempts to work + properly when there is some overlap between the enumeration + constants. NAME is the name of the printer and also the name of + the 'enum' type to look up. + +'register_pretty_printer (OBJ, PRINTER, REPLACE=False)' + Register PRINTER with the pretty-printer list of OBJ. If REPLACE + is 'True' then any existing copy of the printer is replaced. + Otherwise a 'RuntimeError' exception is raised if a printer with + the same name already exists. + + +File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: Python modules + +23.2.4.2 gdb.types +.................. + +This module provides a collection of utilities for working with +'gdb.Type' objects. + +'get_basic_type (TYPE)' + Return TYPE with const and volatile qualifiers stripped, and with + typedefs and C++ references converted to the underlying type. + + C++ example: + + typedef const int const_int; + const_int foo (3); + const_int& foo_ref (foo); + int main () { return 0; } + + Then in gdb: + + (gdb) start + (gdb) python import gdb.types + (gdb) python foo_ref = gdb.parse_and_eval("foo_ref") + (gdb) python print gdb.types.get_basic_type(foo_ref.type) + int + +'has_field (TYPE, FIELD)' + Return 'True' if TYPE, assumed to be a type with fields (e.g., a + structure or union), has field FIELD. + +'make_enum_dict (ENUM_TYPE)' + Return a Python 'dictionary' type produced from ENUM_TYPE. + +'deep_items (TYPE)' + Returns a Python iterator similar to the standard + 'gdb.Type.iteritems' method, except that the iterator returned by + 'deep_items' will recursively traverse anonymous struct or union + fields. For example: + + struct A + { + int a; + union { + int b0; + int b1; + }; + }; + + Then in GDB: + (gdb) python import gdb.types + (gdb) python struct_a = gdb.lookup_type("struct A") + (gdb) python print struct_a.keys () + {['a', '']} + (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)] + {['a', 'b0', 'b1']} + +'get_type_recognizers ()' + Return a list of the enabled type recognizers for the current + context. This is called by GDB during the type-printing process + (*note Type Printing API::). + +'apply_type_recognizers (recognizers, type_obj)' + Apply the type recognizers, RECOGNIZERS, to the type object + TYPE_OBJ. If any recognizer returns a string, return that string. + Otherwise, return 'None'. This is called by GDB during the + type-printing process (*note Type Printing API::). + +'register_type_printer (locus, printer)' + This is a convenience function to register a type printer. PRINTER + is the type printer to register. It must implement the type + printer protocol. LOCUS is either a 'gdb.Objfile', in which case + the printer is registered with that objfile; a 'gdb.Progspace', in + which case the printer is registered with that progspace; or + 'None', in which case the printer is registered globally. + +'TypePrinter' + This is a base class that implements the type printer protocol. + Type printers are encouraged, but not required, to derive from this + class. It defines a constructor: + + -- Method on TypePrinter: __init__ (self, name) + Initialize the type printer with the given name. The new + printer starts in the enabled state. + + +File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules + +23.2.4.3 gdb.prompt +................... + +This module provides a method for prompt value-substitution. + +'substitute_prompt (STRING)' + Return STRING with escape sequences substituted by values. Some + escape sequences take arguments. You can specify arguments inside + "{}" immediately following the escape sequence. + + The escape sequences you can pass to this function are: + + '\\' + Substitute a backslash. + '\e' + Substitute an ESC character. + '\f' + Substitute the selected frame; an argument names a frame + parameter. + '\n' + Substitute a newline. + '\p' + Substitute a parameter's value; the argument names the + parameter. + '\r' + Substitute a carriage return. + '\t' + Substitute the selected thread; an argument names a thread + parameter. + '\v' + Substitute the version of GDB. + '\w' + Substitute the current working directory. + '\[' + Begin a sequence of non-printing characters. These sequences + are typically used with the ESC character, and are not counted + in the string length. Example: "\[\e[0;34m\](gdb)\[\e[0m\]" + will return a blue-colored "(gdb)" prompt where the length is + five. + '\]' + End a sequence of non-printing characters. + + For example: + + substitute_prompt (``frame: \f, + print arguments: \p{print frame-arguments}'') + +will return the string: + + "frame: main, print arguments: scalars" + + +File: gdb.info, Node: Auto-loading extensions, Next: Aliases, Prev: Python, Up: Extending GDB + +23.3 Auto-loading extensions +============================ + +GDB provides two mechanisms for automatically loading extensions when a +new object file is read (for example, due to the 'file' command, or +because the inferior has loaded a shared library): 'OBJFILE-gdb.EXT' and +the '.debug_gdb_scripts' section of modern file formats like ELF. + +* Menu: + +* objfile-gdb.ext file: objfile-gdbdotext file. The 'OBJFILE-gdb.EXT' file +* .debug_gdb_scripts section: dotdebug_gdb_scripts section. The '.debug_gdb_scripts' section +* Which flavor to choose?:: + + The auto-loading feature is useful for supplying application-specific +debugging commands and features. + + Auto-loading can be enabled or disabled, and the list of auto-loaded +scripts can be printed. See the 'auto-loading' section of each +extension language for more information. For GDB command files see +*note Auto-loading sequences::. For Python files see *note Python +Auto-loading::. + + Note that loading of this script file also requires accordingly +configured 'auto-load safe-path' (*note Auto-loading safe path::). + + +File: gdb.info, Node: objfile-gdbdotext file, Next: dotdebug_gdb_scripts section, Up: Auto-loading extensions + +23.3.1 The 'OBJFILE-gdb.EXT' file +--------------------------------- + +When a new object file is read, GDB looks for a file named +'OBJFILE-gdb.EXT' (we call it SCRIPT-NAME below), where OBJFILE is the +object file's name and where EXT is the file extension for the extension +language: + +'OBJFILE-gdb.gdb' + GDB's own command language +'OBJFILE-gdb.py' + Python + + SCRIPT-NAME is formed by ensuring that the file name of OBJFILE is +absolute, following all symlinks, and resolving '.' and '..' components, +and appending the '-gdb.EXT' suffix. If this file exists and is +readable, GDB will evaluate it as a script in the specified extension +language. + + If this file does not exist, then GDB will look for SCRIPT-NAME file +in all of the directories as specified below. + + Note that loading of these files requires an accordingly configured +'auto-load safe-path' (*note Auto-loading safe path::). + + For object files using '.exe' suffix GDB tries to load first the +scripts normally according to its '.exe' filename. But if no scripts +are found GDB also tries script filenames matching the object file +without its '.exe' suffix. This '.exe' stripping is case insensitive +and it is attempted on any platform. This makes the script filenames +compatible between Unix and MS-Windows hosts. + +'set auto-load scripts-directory [DIRECTORIES]' + Control GDB auto-loaded scripts location. Multiple directory + entries may be delimited by the host platform path separator in use + (':' on Unix, ';' on MS-Windows and MS-DOS). + + Each entry here needs to be covered also by the security setting + 'set auto-load safe-path' (*note set auto-load safe-path::). + + This variable defaults to '$debugdir:$datadir/auto-load'. The + default 'set auto-load safe-path' value can be also overriden by + GDB configuration option '--with-auto-load-dir'. + + Any reference to '$debugdir' will get replaced by + DEBUG-FILE-DIRECTORY value (*note Separate Debug Files::) and any + reference to '$datadir' will get replaced by DATA-DIRECTORY which + is determined at GDB startup (*note Data Files::). '$debugdir' and + '$datadir' must be placed as a directory component -- either alone + or delimited by '/' or '\' directory separators, depending on the + host platform. + + The list of directories uses path separator (':' on GNU and Unix + systems, ';' on MS-Windows and MS-DOS) to separate directories, + similarly to the 'PATH' environment variable. + +'show auto-load scripts-directory' + Show GDB auto-loaded scripts location. + + GDB does not track which files it has already auto-loaded this way. +GDB will load the associated script every time the corresponding OBJFILE +is opened. So your '-gdb.EXT' file should be careful to avoid errors if +it is evaluated more than once. + + +File: gdb.info, Node: dotdebug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdbdotext file, Up: Auto-loading extensions + +23.3.2 The '.debug_gdb_scripts' section +--------------------------------------- + +For systems using file formats like ELF and COFF, when GDB loads a new +object file it will look for a special section named +'.debug_gdb_scripts'. If this section exists, its contents is a list of +NUL-terminated names of scripts to load. Each entry begins with a +non-NULL prefix byte that specifies the kind of entry, typically the +extension language. + + GDB will look for each specified script file first in the current +directory and then along the source search path (*note Specifying Source +Directories: Source Path.), except that '$cdir' is not searched, since +the compilation directory is not relevant to scripts. + + Entries can be placed in section '.debug_gdb_scripts' with, for +example, this GCC macro for Python scripts. + + /* Note: The "MS" section flags are to remove duplicates. */ + #define DEFINE_GDB_PY_SCRIPT(script_name) \ + asm("\ + .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\ + .byte 1 /* Python */\n\ + .asciz \"" script_name "\"\n\ + .popsection \n\ + "); + +Then one can reference the macro in a header or source file like this: + + DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py") + + The script name may include directories if desired. + + Note that loading of this script file also requires accordingly +configured 'auto-load safe-path' (*note Auto-loading safe path::). + + If the macro invocation is put in a header, any application or +library using this header will get a reference to the specified script, +and with the use of '"MS"' attributes on the section, the linker will +remove duplicates. + + +File: gdb.info, Node: Which flavor to choose?, Prev: dotdebug_gdb_scripts section, Up: Auto-loading extensions + +23.3.3 Which flavor to choose? +------------------------------ + +Given the multiple ways of auto-loading extensions, it might not always +be clear which one to choose. This section provides some guidance. + +Benefits of the '-gdb.EXT' way: + + * Can be used with file formats that don't support multiple sections. + + * Ease of finding scripts for public libraries. + + Scripts specified in the '.debug_gdb_scripts' section are searched + for in the source search path. For publicly installed libraries, + e.g., 'libstdc++', there typically isn't a source directory in + which to find the script. + + * Doesn't require source code additions. + +Benefits of the '.debug_gdb_scripts' way: + + * Works with static linking. + + Scripts for libraries done the '-gdb.EXT' way require an objfile to + trigger their loading. When an application is statically linked + the only objfile available is the executable, and it is cumbersome + to attach all the scripts from all the input libraries to the + executable's '-gdb.EXT' script. + + * Works with classes that are entirely inlined. + + Some classes can be entirely inlined, and thus there may not be an + associated shared library to attach a '-gdb.EXT' script to. + + * Scripts needn't be copied out of the source tree. + + In some circumstances, apps can be built out of large collections + of internal libraries, and the build infrastructure necessary to + install the '-gdb.EXT' scripts in a place where GDB can find them + is cumbersome. It may be easier to specify the scripts in the + '.debug_gdb_scripts' section as relative paths, and add a path to + the top of the source tree to the source search path. + + +File: gdb.info, Node: Aliases, Prev: Auto-loading extensions, Up: Extending GDB + +23.4 Creating new spellings of existing commands +================================================ + +It is often useful to define alternate spellings of existing commands. +For example, if a new GDB command defined in Python has a long name to +type, it is handy to have an abbreviated version of it that involves +less typing. + + GDB itself uses aliases. For example 's' is an alias of the 'step' +command even though it is otherwise an ambiguous abbreviation of other +commands like 'set' and 'show'. + + Aliases are also used to provide shortened or more common versions of +multi-word commands. For example, GDB provides the 'tty' alias of the +'set inferior-tty' command. + + You can define a new alias with the 'alias' command. + +'alias [-a] [--] ALIAS = COMMAND' + + ALIAS specifies the name of the new alias. Each word of ALIAS must +consist of letters, numbers, dashes and underscores. + + COMMAND specifies the name of an existing command that is being +aliased. + + The '-a' option specifies that the new alias is an abbreviation of +the command. Abbreviations are not shown in command lists displayed by +the 'help' command. + + The '--' option specifies the end of options, and is useful when +ALIAS begins with a dash. + + Here is a simple example showing how to make an abbreviation of a +command so that there is less to type. Suppose you were tired of typing +'disas', the current shortest unambiguous abbreviation of the +'disassemble' command and you wanted an even shorter version named 'di'. +The following will accomplish this. + + (gdb) alias -a di = disas + + Note that aliases are different from user-defined commands. With a +user-defined command, you also need to write documentation for it with +the 'document' command. An alias automatically picks up the +documentation of the existing command. + + Here is an example where we make 'elms' an abbreviation of 'elements' +in the 'set print elements' command. This is to show that you can make +an abbreviation of any part of a command. + + (gdb) alias -a set print elms = set print elements + (gdb) alias -a show print elms = show print elements + (gdb) set p elms 20 + (gdb) show p elms + Limit on string chars or array elements to print is 200. + + Note that if you are defining an alias of a 'set' command, and you +want to have an alias for the corresponding 'show' command, then you +need to define the latter separately. + + Unambiguously abbreviated commands are allowed in COMMAND and ALIAS, +just as they are normally. + + (gdb) alias -a set pr elms = set p ele + + Finally, here is an example showing the creation of a one word alias +for a more complex command. This creates alias 'spe' of the command +'set print elements'. + + (gdb) alias spe = set print elements + (gdb) spe 20 + + +File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top + +24 Command Interpreters +*********************** + +GDB supports multiple command interpreters, and some command +infrastructure to allow users or user interface writers to switch +between interpreters or run commands in other interpreters. + + GDB currently supports two command interpreters, the console +interpreter (sometimes called the command-line interpreter or CLI) and +the machine interface interpreter (or GDB/MI). This manual describes +both of these interfaces in great detail. + + By default, GDB will start with the console interpreter. However, +the user may choose to start GDB with another interpreter by specifying +the '-i' or '--interpreter' startup options. Defined interpreters +include: + +'console' + The traditional console or command-line interpreter. This is the + most often used interpreter with GDB. With no interpreter + specified at runtime, GDB will use this interpreter. + +'mi' + The newest GDB/MI interface (currently 'mi2'). Used primarily by + programs wishing to use GDB as a backend for a debugger GUI or an + IDE. For more information, see *note The GDB/MI Interface: GDB/MI. + +'mi2' + The current GDB/MI interface. + +'mi1' + The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. + + The interpreter being used by GDB may not be dynamically switched at +runtime. Although possible, this could lead to a very precarious +situation. Consider an IDE using GDB/MI. If a user enters the command +"interpreter-set console" in a console view, GDB would switch to using +the console interpreter, rendering the IDE inoperable! + + Although you may only choose a single interpreter at startup, you may +execute commands in any interpreter from the current interpreter using +the appropriate command. If you are running the console interpreter, +simply use the 'interpreter-exec' command: + + interpreter-exec mi "-data-list-register-names" + + GDB/MI has a similar command, although it is only available in +versions of GDB which support GDB/MI version 2 (or greater). + + +File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top + +25 GDB Text User Interface +************************** + +* Menu: + +* TUI Overview:: TUI overview +* TUI Keys:: TUI key bindings +* TUI Single Key Mode:: TUI single key mode +* TUI Commands:: TUI-specific commands +* TUI Configuration:: TUI configuration variables + +The GDB Text User Interface (TUI) is a terminal interface which uses the +'curses' library to show the source file, the assembly output, the +program registers and GDB commands in separate text windows. The TUI +mode is supported only on platforms where a suitable version of the +'curses' library is available. + + The TUI mode is enabled by default when you invoke GDB as 'gdb -tui'. +You can also switch in and out of TUI mode while GDB runs by using +various TUI commands and key bindings, such as 'C-x C-a'. *Note TUI Key +Bindings: TUI Keys. + + +File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI + +25.1 TUI Overview +================= + +In TUI mode, GDB can display several text windows: + +_command_ + This window is the GDB command window with the GDB prompt and the + GDB output. The GDB input is still managed using readline. + +_source_ + The source window shows the source file of the program. The + current line and active breakpoints are displayed in this window. + +_assembly_ + The assembly window shows the disassembly output of the program. + +_register_ + This window shows the processor registers. Registers are + highlighted when their values change. + + The source and assembly windows show the current program position by +highlighting the current line and marking it with a '>' marker. +Breakpoints are indicated with two markers. The first marker indicates +the breakpoint type: + +'B' + Breakpoint which was hit at least once. + +'b' + Breakpoint which was never hit. + +'H' + Hardware breakpoint which was hit at least once. + +'h' + Hardware breakpoint which was never hit. + + The second marker indicates whether the breakpoint is enabled or not: + +'+' + Breakpoint is enabled. + +'-' + Breakpoint is disabled. + + The source, assembly and register windows are updated when the +current thread changes, when the frame changes, or when the program +counter changes. + + These windows are not all visible at the same time. The command +window is always visible. The others can be arranged in several +layouts: + + * source only, + + * assembly only, + + * source and assembly, + + * source and registers, or + + * assembly and registers. + + A status line above the command window shows the following +information: + +_target_ + Indicates the current GDB target. (*note Specifying a Debugging + Target: Targets.). + +_process_ + Gives the current process or thread number. When no process is + being debugged, this field is set to 'No process'. + +_function_ + Gives the current function name for the selected frame. The name + is demangled if demangling is turned on (*note Print Settings::). + When there is no symbol corresponding to the current program + counter, the string '??' is displayed. + +_line_ + Indicates the current line number for the selected frame. When the + current line number is not known, the string '??' is displayed. + +_pc_ + Indicates the current program counter address. + + +File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI + +25.2 TUI Key Bindings +===================== + +The TUI installs several key bindings in the readline keymaps (*note +Command Line Editing::). The following key bindings are installed for +both TUI mode and the GDB standard mode. + +'C-x C-a' +'C-x a' +'C-x A' + Enter or leave the TUI mode. When leaving the TUI mode, the curses + window management stops and GDB operates using its standard mode, + writing on the terminal directly. When reentering the TUI mode, + control is given back to the curses windows. The screen is then + refreshed. + +'C-x 1' + Use a TUI layout with only one window. The layout will either be + 'source' or 'assembly'. When the TUI mode is not active, it will + switch to the TUI mode. + + Think of this key binding as the Emacs 'C-x 1' binding. + +'C-x 2' + Use a TUI layout with at least two windows. When the current + layout already has two windows, the next layout with two windows is + used. When a new layout is chosen, one window will always be + common to the previous layout and the new one. + + Think of it as the Emacs 'C-x 2' binding. + +'C-x o' + Change the active window. The TUI associates several key bindings + (like scrolling and arrow keys) with the active window. This + command gives the focus to the next TUI window. + + Think of it as the Emacs 'C-x o' binding. + +'C-x s' + Switch in and out of the TUI SingleKey mode that binds single keys + to GDB commands (*note TUI Single Key Mode::). + + The following key bindings only work in the TUI mode: + + + Scroll the active window one page up. + + + Scroll the active window one page down. + + + Scroll the active window one line up. + + + Scroll the active window one line down. + + + Scroll the active window one column left. + + + Scroll the active window one column right. + +'C-L' + Refresh the screen. + + Because the arrow keys scroll the active window in the TUI mode, they +are not available for their normal use by readline unless the command +window has the focus. When another window is active, you must use other +readline key bindings such as 'C-p', 'C-n', 'C-b' and 'C-f' to control +the command window. + + +File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI + +25.3 TUI Single Key Mode +======================== + +The TUI also provides a "SingleKey" mode, which binds several frequently +used GDB commands to single keys. Type 'C-x s' to switch into this +mode, where the following key bindings are used: + +'c' + continue + +'d' + down + +'f' + finish + +'n' + next + +'q' + exit the SingleKey mode. + +'r' + run + +'s' + step + +'u' + up + +'v' + info locals + +'w' + where + + Other keys temporarily switch to the GDB command prompt. The key +that was pressed is inserted in the editing buffer so that it is +possible to type most GDB commands without interaction with the TUI +SingleKey mode. Once the command is entered the TUI SingleKey mode is +restored. The only way to permanently leave this mode is by typing 'q' +or 'C-x s'. + + +File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI + +25.4 TUI-specific Commands +========================== + +The TUI has specific commands to control the text windows. These +commands are always available, even when GDB is not in the TUI mode. +When GDB is in the standard mode, most of these commands will +automatically switch to the TUI mode. + + Note that if GDB's 'stdout' is not connected to a terminal, or GDB +has been started with the machine interface interpreter (*note The +GDB/MI Interface: GDB/MI.), most of these commands will fail with an +error, because it would not be possible or desirable to enable curses +window management. + +'info win' + List and give the size of all displayed windows. + +'layout next' + Display the next layout. + +'layout prev' + Display the previous layout. + +'layout src' + Display the source window only. + +'layout asm' + Display the assembly window only. + +'layout split' + Display the source and assembly window. + +'layout regs' + Display the register window together with the source or assembly + window. + +'focus next' + Make the next window active for scrolling. + +'focus prev' + Make the previous window active for scrolling. + +'focus src' + Make the source window active for scrolling. + +'focus asm' + Make the assembly window active for scrolling. + +'focus regs' + Make the register window active for scrolling. + +'focus cmd' + Make the command window active for scrolling. + +'refresh' + Refresh the screen. This is similar to typing 'C-L'. + +'tui reg float' + Show the floating point registers in the register window. + +'tui reg general' + Show the general registers in the register window. + +'tui reg next' + Show the next register group. The list of register groups as well + as their order is target specific. The predefined register groups + are the following: 'general', 'float', 'system', 'vector', 'all', + 'save', 'restore'. + +'tui reg system' + Show the system registers in the register window. + +'update' + Update the source window and the current execution point. + +'winheight NAME +COUNT' +'winheight NAME -COUNT' + Change the height of the window NAME by COUNT lines. Positive + counts increase the height, while negative counts decrease it. + +'tabset NCHARS' + Set the width of tab stops to be NCHARS characters. + + +File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI + +25.5 TUI Configuration Variables +================================ + +Several configuration variables control the appearance of TUI windows. + +'set tui border-kind KIND' + Select the border appearance for the source, assembly and register + windows. The possible values are the following: + 'space' + Use a space character to draw the border. + + 'ascii' + Use ASCII characters '+', '-' and '|' to draw the border. + + 'acs' + Use the Alternate Character Set to draw the border. The + border is drawn using character line graphics if the terminal + supports them. + +'set tui border-mode MODE' +'set tui active-border-mode MODE' + Select the display attributes for the borders of the inactive + windows or the active window. The MODE can be one of the + following: + 'normal' + Use normal attributes to display the border. + + 'standout' + Use standout mode. + + 'reverse' + Use reverse video mode. + + 'half' + Use half bright mode. + + 'half-standout' + Use half bright and standout mode. + + 'bold' + Use extra bright or bold mode. + + 'bold-standout' + Use extra bright or bold and standout mode. + + +File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top + +26 Using GDB under GNU Emacs +**************************** + +A special interface allows you to use GNU Emacs to view (and edit) the +source files for the program you are debugging with GDB. + + To use this interface, use the command 'M-x gdb' in Emacs. Give the +executable file you want to debug as an argument. This command starts +GDB as a subprocess of Emacs, with input and output through a newly +created Emacs buffer. + + Running GDB under Emacs can be just like running GDB normally except +for two things: + + * All "terminal" input and output goes through an Emacs buffer, + called the GUD buffer. + + This applies both to GDB commands and their output, and to the + input and output done by the program you are debugging. + + This is useful because it means that you can copy the text of + previous commands and input them again; you can even use parts of + the output in this way. + + All the facilities of Emacs' Shell mode are available for + interacting with your program. In particular, you can send signals + the usual way--for example, 'C-c C-c' for an interrupt, 'C-c C-z' + for a stop. + + * GDB displays source code through Emacs. + + Each time GDB displays a stack frame, Emacs automatically finds the + source file for that frame and puts an arrow ('=>') at the left + margin of the current line. Emacs uses a separate buffer for + source display, and splits the screen to show both your GDB session + and the source. + + Explicit GDB 'list' or search commands still produce output as + usual, but you probably have no reason to use them from Emacs. + + We call this "text command mode". Emacs 22.1, and later, also uses a +graphical mode, enabled by default, which provides further buffers that +can control the execution and describe the state of your program. *Note +(Emacs)GDB Graphical Interface::. + + If you specify an absolute file name when prompted for the 'M-x gdb' +argument, then Emacs sets your current working directory to where your +program resides. If you only specify the file name, then Emacs sets +your current working directory to the directory associated with the +previous buffer. In this case, GDB may find your program by searching +your environment's 'PATH' variable, but on some operating systems it +might not find the source. So, although the GDB input and output +session proceeds normally, the auxiliary buffer does not display the +current source and line of execution. + + The initial working directory of GDB is printed on the top line of +the GUD buffer and this serves as a default for the commands that +specify files for GDB to operate on. *Note Commands to Specify Files: +Files. + + By default, 'M-x gdb' calls the program called 'gdb'. If you need to +call GDB by a different name (for example, if you keep several +configurations around, with different names) you can customize the Emacs +variable 'gud-gdb-command-name' to run the one you want. + + In the GUD buffer, you can use these special Emacs commands in +addition to the standard Shell mode commands: + +'C-h m' + Describe the features of Emacs' GUD Mode. + +'C-c C-s' + Execute to another source line, like the GDB 'step' command; also + update the display window to show the current file and location. + +'C-c C-n' + Execute to next source line in this function, skipping all function + calls, like the GDB 'next' command. Then update the display window + to show the current file and location. + +'C-c C-i' + Execute one instruction, like the GDB 'stepi' command; update + display window accordingly. + +'C-c C-f' + Execute until exit from the selected stack frame, like the GDB + 'finish' command. + +'C-c C-r' + Continue execution of your program, like the GDB 'continue' + command. + +'C-c <' + Go up the number of frames indicated by the numeric argument (*note + Numeric Arguments: (Emacs)Arguments.), like the GDB 'up' command. + +'C-c >' + Go down the number of frames indicated by the numeric argument, + like the GDB 'down' command. + + In any source file, the Emacs command 'C-x ' ('gud-break') tells +GDB to set a breakpoint on the source line point is on. + + In text command mode, if you type 'M-x speedbar', Emacs displays a +separate frame which shows a backtrace when the GUD buffer is current. +Move point to any frame in the stack and type to make it become +the current frame and display the associated source in the source +buffer. Alternatively, click 'Mouse-2' to make the selected frame +become the current one. In graphical mode, the speedbar displays watch +expressions. + + If you accidentally delete the source-display buffer, an easy way to +get it back is to type the command 'f' in the GDB buffer, to request a +frame display; when you run under Emacs, this recreates the source +buffer if necessary to show you the context of the current frame. + + The source files displayed in Emacs are in ordinary Emacs buffers +which are visiting the source files in the usual way. You can edit the +files with these buffers if you wish; but keep in mind that GDB +communicates with Emacs in terms of line numbers. If you add or delete +lines from the text, the line numbers that GDB knows cease to correspond +properly with the code. + + A more detailed description of Emacs' interaction with GDB is given +in the Emacs manual (*note (Emacs)Debuggers::). + + +File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top + +27 The GDB/MI Interface +*********************** + +Function and Purpose +==================== + +GDB/MI is a line based machine oriented text interface to GDB and is +activated by specifying using the '--interpreter' command line option +(*note Mode Options::). It is specifically intended to support the +development of systems which use the debugger as just one small +component of a larger system. + + This chapter is a specification of the GDB/MI interface. It is +written in the form of a reference manual. + + Note that GDB/MI is still under construction, so some of the features +described below are incomplete and subject to change (*note GDB/MI +Development and Front Ends: GDB/MI Development and Front Ends.). + +Notation and Terminology +======================== + +This chapter uses the following notation: + + * '|' separates two alternatives. + + * '[ SOMETHING ]' indicates that SOMETHING is optional: it may or may + not be given. + + * '( GROUP )*' means that GROUP inside the parentheses may repeat + zero or more times. + + * '( GROUP )+' means that GROUP inside the parentheses may repeat one + or more times. + + * '"STRING"' means a literal STRING. + +* Menu: + +* GDB/MI General Design:: +* GDB/MI Command Syntax:: +* GDB/MI Compatibility with CLI:: +* GDB/MI Development and Front Ends:: +* GDB/MI Output Records:: +* GDB/MI Simple Examples:: +* GDB/MI Command Description Format:: +* GDB/MI Breakpoint Commands:: +* GDB/MI Catchpoint Commands:: +* GDB/MI Program Context:: +* GDB/MI Thread Commands:: +* GDB/MI Ada Tasking Commands:: +* GDB/MI Program Execution:: +* GDB/MI Stack Manipulation:: +* GDB/MI Variable Objects:: +* GDB/MI Data Manipulation:: +* GDB/MI Tracepoint Commands:: +* GDB/MI Symbol Query:: +* GDB/MI File Commands:: +* GDB/MI Target Manipulation:: +* GDB/MI File Transfer Commands:: +* GDB/MI Ada Exceptions Commands:: +* GDB/MI Support Commands:: +* GDB/MI Miscellaneous Commands:: + + +File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI + +27.1 GDB/MI General Design +========================== + +Interaction of a GDB/MI frontend with GDB involves three parts--commands +sent to GDB, responses to those commands and notifications. Each +command results in exactly one response, indicating either successful +completion of the command, or an error. For the commands that do not +resume the target, the response contains the requested information. For +the commands that resume the target, the response only indicates whether +the target was successfully resumed. Notifications is the mechanism for +reporting changes in the state of the target, or in GDB state, that +cannot conveniently be associated with a command and reported as part of +that command response. + + The important examples of notifications are: + + * Exec notifications. These are used to report changes in target + state--when a target is resumed, or stopped. It would not be + feasible to include this information in response of resuming + commands, because one resume commands can result in multiple events + in different threads. Also, quite some time may pass before any + event happens in the target, while a frontend needs to know whether + the resuming command itself was successfully executed. + + * Console output, and status notifications. Console output + notifications are used to report output of CLI commands, as well as + diagnostics for other commands. Status notifications are used to + report the progress of a long-running operation. Naturally, + including this information in command response would mean no output + is produced until the command is finished, which is undesirable. + + * General notifications. Commands may have various side effects on + the GDB or target state beyond their official purpose. For + example, a command may change the selected thread. Although such + changes can be included in command response, using notification + allows for more orthogonal frontend design. + + There's no guarantee that whenever an MI command reports an error, +GDB or the target are in any specific state, and especially, the state +is not reverted to the state before the MI command was processed. +Therefore, whenever an MI command results in an error, we recommend that +the frontend refreshes all the information shown in the user interface. + +* Menu: + +* Context management:: +* Asynchronous and non-stop modes:: +* Thread groups:: + + +File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design + +27.1.1 Context management +------------------------- + +27.1.1.1 Threads and Frames +........................... + +In most cases when GDB accesses the target, this access is done in +context of a specific thread and frame (*note Frames::). Often, even +when accessing global data, the target requires that a thread be +specified. The CLI interface maintains the selected thread and frame, +and supplies them to target on each command. This is convenient, +because a command line user would not want to specify that information +explicitly on each command, and because user interacts with GDB via a +single terminal, so no confusion is possible as to what thread and frame +are the current ones. + + In the case of MI, the concept of selected thread and frame is less +useful. First, a frontend can easily remember this information itself. +Second, a graphical frontend can have more than one window, each one +used for debugging a different thread, and the frontend might want to +access additional threads for internal purposes. This increases the +risk that by relying on implicitly selected thread, the frontend may be +operating on a wrong one. Therefore, each MI command should explicitly +specify which thread and frame to operate on. To make it possible, each +MI command accepts the '--thread' and '--frame' options, the value to +each is GDB identifier for thread and frame to operate on. + + Usually, each top-level window in a frontend allows the user to +select a thread and a frame, and remembers the user selection for +further operations. However, in some cases GDB may suggest that the +current thread be changed. For example, when stopping on a breakpoint +it is reasonable to switch to the thread where breakpoint is hit. For +another example, if the user issues the CLI 'thread' command via the +frontend, it is desirable to change the frontend's selected thread to +the one specified by user. GDB communicates the suggestion to change +current thread using the '=thread-selected' notification. No such +notification is available for the selected frame at the moment. + + Note that historically, MI shares the selected thread with CLI, so +frontends used the '-thread-select' to execute commands in the right +context. However, getting this to work right is cumbersome. The +simplest way is for frontend to emit '-thread-select' command before +every command. This doubles the number of commands that need to be +sent. The alternative approach is to suppress '-thread-select' if the +selected thread in GDB is supposed to be identical to the thread the +frontend wants to operate on. However, getting this optimization right +can be tricky. In particular, if the frontend sends several commands to +GDB, and one of the commands changes the selected thread, then the +behaviour of subsequent commands will change. So, a frontend should +either wait for response from such problematic commands, or explicitly +add '-thread-select' for all subsequent commands. No frontend is known +to do this exactly right, so it is suggested to just always pass the +'--thread' and '--frame' options. + +27.1.1.2 Language +................. + +The execution of several commands depends on which language is selected. +By default, the current language (*note show language::) is used. But +for commands known to be language-sensitive, it is recommended to use +the '--language' option. This option takes one argument, which is the +name of the language to use while executing the command. For instance: + + -data-evaluate-expression --language c "sizeof (void*)" + ^done,value="4" + (gdb) + + The valid language names are the same names accepted by the 'set +language' command (*note Manually::), excluding 'auto', 'local' or +'unknown'. + + +File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design + +27.1.2 Asynchronous command execution and non-stop mode +------------------------------------------------------- + +On some targets, GDB is capable of processing MI commands even while the +target is running. This is called "asynchronous command execution" +(*note Background Execution::). The frontend may specify a preferrence +for asynchronous execution using the '-gdb-set target-async 1' command, +which should be emitted before either running the executable or +attaching to the target. After the frontend has started the executable +or attached to the target, it can find if asynchronous execution is +enabled using the '-list-target-features' command. + + Even if GDB can accept a command while target is running, many +commands that access the target do not work when the target is running. +Therefore, asynchronous command execution is most useful when combined +with non-stop mode (*note Non-Stop Mode::). Then, it is possible to +examine the state of one thread, while other threads are running. + + When a given thread is running, MI commands that try to access the +target in the context of that thread may not work, or may work only on +some targets. In particular, commands that try to operate on thread's +stack will not work, on any target. Commands that read memory, or +modify breakpoints, may work or not work, depending on the target. Note +that even commands that operate on global state, such as 'print', 'set', +and breakpoint commands, still access the target in the context of a +specific thread, so frontend should try to find a stopped thread and +perform the operation on that thread (using the '--thread' option). + + Which commands will work in the context of a running thread is highly +target dependent. However, the two commands '-exec-interrupt', to stop +a thread, and '-thread-info', to find the state of a thread, will always +work. + + +File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design + +27.1.3 Thread groups +-------------------- + +GDB may be used to debug several processes at the same time. On some +platfroms, GDB may support debugging of several hardware systems, each +one having several cores with several different processes running on +each core. This section describes the MI mechanism to support such +debugging scenarios. + + The key observation is that regardless of the structure of the +target, MI can have a global list of threads, because most commands that +accept the '--thread' option do not need to know what process that +thread belongs to. Therefore, it is not necessary to introduce neither +additional '--process' option, nor an notion of the current process in +the MI interface. The only strictly new feature that is required is the +ability to find how the threads are grouped into processes. + + To allow the user to discover such grouping, and to support arbitrary +hierarchy of machines/cores/processes, MI introduces the concept of a +"thread group". Thread group is a collection of threads and other +thread groups. A thread group always has a string identifier, a type, +and may have additional attributes specific to the type. A new command, +'-list-thread-groups', returns the list of top-level thread groups, +which correspond to processes that GDB is debugging at the moment. By +passing an identifier of a thread group to the '-list-thread-groups' +command, it is possible to obtain the members of specific thread group. + + To allow the user to easily discover processes, and other objects, he +wishes to debug, a concept of "available thread group" is introduced. +Available thread group is an thread group that GDB is not debugging, but +that can be attached to, using the '-target-attach' command. The list +of available top-level thread groups can be obtained using +'-list-thread-groups --available'. In general, the content of a thread +group may be only retrieved only after attaching to that thread group. + + Thread groups are related to inferiors (*note Inferiors and +Programs::). Each inferior corresponds to a thread group of a special +type 'process', and some additional operations are permitted on such +thread groups. + + +File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI + +27.2 GDB/MI Command Syntax +========================== + +* Menu: + +* GDB/MI Input Syntax:: +* GDB/MI Output Syntax:: + + +File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax + +27.2.1 GDB/MI Input Syntax +-------------------------- + +'COMMAND ==>' + 'CLI-COMMAND | MI-COMMAND' + +'CLI-COMMAND ==>' + '[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB + CLI command. + +'MI-COMMAND ==>' + '[ TOKEN ] "-" OPERATION ( " " OPTION )* [ " --" ] ( " " PARAMETER + )* NL' + +'TOKEN ==>' + "any sequence of digits" + +'OPTION ==>' + '"-" PARAMETER [ " " PARAMETER ]' + +'PARAMETER ==>' + 'NON-BLANK-SEQUENCE | C-STRING' + +'OPERATION ==>' + _any of the operations described in this chapter_ + +'NON-BLANK-SEQUENCE ==>' + _anything, provided it doesn't contain special characters such as + "-", NL, """ and of course " "_ + +'C-STRING ==>' + '""" SEVEN-BIT-ISO-C-STRING-CONTENT """' + +'NL ==>' + 'CR | CR-LF' + +Notes: + + * The CLI commands are still handled by the MI interpreter; their + output is described below. + + * The 'TOKEN', when present, is passed back when the command + finishes. + + * Some MI commands accept optional arguments as part of the parameter + list. Each option is identified by a leading '-' (dash) and may be + followed by an optional argument parameter. Options occur first in + the parameter list and can be delimited from normal parameters + using '--' (this is useful when some parameters begin with a dash). + + Pragmatics: + + * We want easy access to the existing CLI syntax (for debugging). + + * We want it to be easy to spot a MI operation. + + +File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax + +27.2.2 GDB/MI Output Syntax +--------------------------- + +The output from GDB/MI consists of zero or more out-of-band records +followed, optionally, by a single result record. This result record is +for the most recent command. The sequence of output records is +terminated by '(gdb)'. + + If an input command was prefixed with a 'TOKEN' then the +corresponding output for that command will also be prefixed by that same +TOKEN. + +'OUTPUT ==>' + '( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' + +'RESULT-RECORD ==>' + ' [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' + +'OUT-OF-BAND-RECORD ==>' + 'ASYNC-RECORD | STREAM-RECORD' + +'ASYNC-RECORD ==>' + 'EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' + +'EXEC-ASYNC-OUTPUT ==>' + '[ TOKEN ] "*" ASYNC-OUTPUT' + +'STATUS-ASYNC-OUTPUT ==>' + '[ TOKEN ] "+" ASYNC-OUTPUT' + +'NOTIFY-ASYNC-OUTPUT ==>' + '[ TOKEN ] "=" ASYNC-OUTPUT' + +'ASYNC-OUTPUT ==>' + 'ASYNC-CLASS ( "," RESULT )* NL' + +'RESULT-CLASS ==>' + '"done" | "running" | "connected" | "error" | "exit"' + +'ASYNC-CLASS ==>' + '"stopped" | OTHERS' (where OTHERS will be added depending on the + needs--this is still in development). + +'RESULT ==>' + ' VARIABLE "=" VALUE' + +'VARIABLE ==>' + ' STRING ' + +'VALUE ==>' + ' CONST | TUPLE | LIST ' + +'CONST ==>' + 'C-STRING' + +'TUPLE ==>' + ' "{}" | "{" RESULT ( "," RESULT )* "}" ' + +'LIST ==>' + ' "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* + "]" ' + +'STREAM-RECORD ==>' + 'CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' + +'CONSOLE-STREAM-OUTPUT ==>' + '"~" C-STRING' + +'TARGET-STREAM-OUTPUT ==>' + '"@" C-STRING' + +'LOG-STREAM-OUTPUT ==>' + '"&" C-STRING' + +'NL ==>' + 'CR | CR-LF' + +'TOKEN ==>' + _any sequence of digits_. + +Notes: + + * All output sequences end in a single line containing a period. + + * The 'TOKEN' is from the corresponding request. Note that for all + async output, while the token is allowed by the grammar and may be + output by future versions of GDB for select async output messages, + it is generally omitted. Frontends should treat all async output + as reporting general changes in the state of the target and there + should be no need to associate async output to any prior command. + + * STATUS-ASYNC-OUTPUT contains on-going status information about the + progress of a slow operation. It can be discarded. All status + output is prefixed by '+'. + + * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target + (stopped, started, disappeared). All async output is prefixed by + '*'. + + * NOTIFY-ASYNC-OUTPUT contains supplementary information that the + client should handle (e.g., a new breakpoint information). All + notify output is prefixed by '='. + + * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in + the console. It is the textual response to a CLI command. All the + console output is prefixed by '~'. + + * TARGET-STREAM-OUTPUT is the output produced by the target program. + All the target output is prefixed by '@'. + + * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for + instance messages that should be displayed as part of an error log. + All the log output is prefixed by '&'. + + * New GDB/MI commands should only output LISTS containing VALUES. + + *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details +about the various output records. + + +File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI + +27.3 GDB/MI Compatibility with CLI +================================== + +For the developers convenience CLI commands can be entered directly, but +there may be some unexpected behaviour. For example, commands that +query the user will behave as if the user replied yes, breakpoint +command lists are not executed and some CLI commands, such as 'if', +'when' and 'define', prompt for further input with '>', which is not +valid MI output. + + This feature may be removed at some stage in the future and it is +recommended that front ends use the '-interpreter-exec' command (*note +-interpreter-exec::). + + +File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI + +27.4 GDB/MI Development and Front Ends +====================================== + +The application which takes the MI output and presents the state of the +program being debugged to the user is called a "front end". + + Although GDB/MI is still incomplete, it is currently being used by a +variety of front ends to GDB. This makes it difficult to introduce new +functionality without breaking existing usage. This section tries to +minimize the problems by describing how the protocol might change. + + Some changes in MI need not break a carefully designed front end, and +for these the MI version will remain unchanged. The following is a list +of changes that may occur within one level, so front ends should parse +MI output in a way that can handle them: + + * New MI commands may be added. + + * New fields may be added to the output of any MI command. + + * The range of values for fields with specified values, e.g., + 'in_scope' (*note -var-update::) may be extended. + + If the changes are likely to break front ends, the MI version level +will be increased by one. This will allow the front end to parse the +output according to the MI version. Apart from mi0, new versions of GDB +will not support old versions of MI and it will be the responsibility of +the front end to work with the new one. + + The best way to avoid unexpected changes in MI that might break your +front end is to make your project known to GDB developers and follow +development on and . + + +File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI + +27.5 GDB/MI Output Records +========================== + +* Menu: + +* GDB/MI Result Records:: +* GDB/MI Stream Records:: +* GDB/MI Async Records:: +* GDB/MI Breakpoint Information:: +* GDB/MI Frame Information:: +* GDB/MI Thread Information:: +* GDB/MI Ada Exception Information:: + + +File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records + +27.5.1 GDB/MI Result Records +---------------------------- + +In addition to a number of out-of-band notifications, the response to a +GDB/MI command includes one of the following result indications: + +'"^done" [ "," RESULTS ]' + The synchronous operation was successful, 'RESULTS' are the return + values. + +'"^running"' + This result record is equivalent to '^done'. Historically, it was + output instead of '^done' if the command has resumed the target. + This behaviour is maintained for backward compatibility, but all + frontends should treat '^done' and '^running' identically and rely + on the '*running' output record to determine which threads are + resumed. + +'"^connected"' + GDB has connected to a remote target. + +'"^error" "," "msg=" C-STRING [ "," "code=" C-STRING ]' + The operation failed. The 'msg=C-STRING' variable contains the + corresponding error message. + + If present, the 'code=C-STRING' variable provides an error code on + which consumers can rely on to detect the corresponding error + condition. At present, only one error code is defined: + + '"undefined-command"' + Indicates that the command causing the error does not exist. + +'"^exit"' + GDB has terminated. + + +File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records + +27.5.2 GDB/MI Stream Records +---------------------------- + +GDB internally maintains a number of output streams: the console, the +target, and the log. The output intended for each of these streams is +funneled through the GDB/MI interface using "stream records". + + Each stream record begins with a unique "prefix character" which +identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output +Syntax.). In addition to the prefix, each stream record contains a +'STRING-OUTPUT'. This is either raw text (with an implicit new line) or +a quoted C string (which does not contain an implicit newline). + +'"~" STRING-OUTPUT' + The console output stream contains text that should be displayed in + the CLI console window. It contains the textual responses to CLI + commands. + +'"@" STRING-OUTPUT' + The target output stream contains any textual output from the + running target. This is only present when GDB's event loop is + truly asynchronous, which is currently only the case for remote + targets. + +'"&" STRING-OUTPUT' + The log stream contains debugging messages being produced by GDB's + internals. + + +File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Breakpoint Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records + +27.5.3 GDB/MI Async Records +--------------------------- + +"Async" records are used to notify the GDB/MI client of additional +changes that have occurred. Those changes can either be a consequence +of GDB/MI commands (e.g., a breakpoint modified) or a result of target +activity (e.g., target stopped). + + The following is the list of possible async records: + +'*running,thread-id="THREAD"' + The target is now running. The THREAD field tells which specific + thread is now running, and can be 'all' if all threads are running. + The frontend should assume that no interaction with a running + thread is possible after this notification is produced. The + frontend should not assume that this notification is output only + once for any command. GDB may emit this notification several + times, either for different threads, because it cannot resume all + threads together, or even for a single thread, if the thread must + be stepped though some code before letting it run freely. + +'*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"' + The target has stopped. The REASON field can have one of the + following values: + + 'breakpoint-hit' + A breakpoint was reached. + 'watchpoint-trigger' + A watchpoint was triggered. + 'read-watchpoint-trigger' + A read watchpoint was triggered. + 'access-watchpoint-trigger' + An access watchpoint was triggered. + 'function-finished' + An -exec-finish or similar CLI command was accomplished. + 'location-reached' + An -exec-until or similar CLI command was accomplished. + 'watchpoint-scope' + A watchpoint has gone out of scope. + 'end-stepping-range' + An -exec-next, -exec-next-instruction, -exec-step, + -exec-step-instruction or similar CLI command was + accomplished. + 'exited-signalled' + The inferior exited because of a signal. + 'exited' + The inferior exited. + 'exited-normally' + The inferior exited normally. + 'signal-received' + A signal was received by the inferior. + 'solib-event' + The inferior has stopped due to a library being loaded or + unloaded. This can happen when 'stop-on-solib-events' (*note + Files::) is set or when a 'catch load' or 'catch unload' + catchpoint is in use (*note Set Catchpoints::). + 'fork' + The inferior has forked. This is reported when 'catch fork' + (*note Set Catchpoints::) has been used. + 'vfork' + The inferior has vforked. This is reported in when 'catch + vfork' (*note Set Catchpoints::) has been used. + 'syscall-entry' + The inferior entered a system call. This is reported when + 'catch syscall' (*note Set Catchpoints::) has been used. + 'syscall-entry' + The inferior returned from a system call. This is reported + when 'catch syscall' (*note Set Catchpoints::) has been used. + 'exec' + The inferior called 'exec'. This is reported when 'catch + exec' (*note Set Catchpoints::) has been used. + + The ID field identifies the thread that directly caused the stop - + for example by hitting a breakpoint. Depending on whether all-stop + mode is in effect (*note All-Stop Mode::), GDB may either stop all + threads, or only the thread that directly triggered the stop. If + all threads are stopped, the STOPPED field will have the value of + '"all"'. Otherwise, the value of the STOPPED field will be a list + of thread identifiers. Presently, this list will always include a + single thread, but frontend should be prepared to see several + threads in the list. The CORE field reports the processor core on + which the stop event has happened. This field may be absent if + such information is not available. + +'=thread-group-added,id="ID"' +'=thread-group-removed,id="ID"' + A thread group was either added or removed. The ID field contains + the GDB identifier of the thread group. When a thread group is + added, it generally might not be associated with a running process. + When a thread group is removed, its id becomes invalid and cannot + be used in any way. + +'=thread-group-started,id="ID",pid="PID"' + A thread group became associated with a running program, either + because the program was just started or the thread group was + attached to a program. The ID field contains the GDB identifier of + the thread group. The PID field contains process identifier, + specific to the operating system. + +'=thread-group-exited,id="ID"[,exit-code="CODE"]' + A thread group is no longer associated with a running program, + either because the program has exited, or because it was detached + from. The ID field contains the GDB identifier of the thread + group. CODE is the exit code of the inferior; it exists only when + the inferior exited with some code. + +'=thread-created,id="ID",group-id="GID"' +'=thread-exited,id="ID",group-id="GID"' + A thread either was created, or has exited. The ID field contains + the GDB identifier of the thread. The GID field identifies the + thread group this thread belongs to. + +'=thread-selected,id="ID"' + Informs that the selected thread was changed as result of the last + command. This notification is not emitted as result of + '-thread-select' command but is emitted whenever an MI command that + is not documented to change the selected thread actually changes + it. In particular, invoking, directly or indirectly (via + user-defined command), the CLI 'thread' command, will generate this + notification. + + We suggest that in response to this notification, front ends + highlight the selected thread and cause subsequent commands to + apply to that thread. + +'=library-loaded,...' + Reports that a new library file was loaded by the program. This + notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and + SYMBOLS-LOADED. The ID field is an opaque identifier of the + library. For remote debugging case, TARGET-NAME and HOST-NAME + fields give the name of the library file on the target, and on the + host respectively. For native debugging, both those fields have + the same value. The SYMBOLS-LOADED field is emitted only for + backward compatibility and should not be relied on to convey any + useful information. The THREAD-GROUP field, if present, specifies + the id of the thread group in whose context the library was loaded. + If the field is absent, it means the library was loaded in the + context of all present thread groups. + +'=library-unloaded,...' + Reports that a library was unloaded by the program. This + notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the + same meaning as for the '=library-loaded' notification. The + THREAD-GROUP field, if present, specifies the id of the thread + group in whose context the library was unloaded. If the field is + absent, it means the library was unloaded in the context of all + present thread groups. + +'=traceframe-changed,num=TFNUM,tracepoint=TPNUM' +'=traceframe-changed,end' + Reports that the trace frame was changed and its new number is + TFNUM. The number of the tracepoint associated with this trace + frame is TPNUM. + +'=tsv-created,name=NAME,initial=INITIAL' + Reports that the new trace state variable NAME is created with + initial value INITIAL. + +'=tsv-deleted,name=NAME' +'=tsv-deleted' + Reports that the trace state variable NAME is deleted or all trace + state variables are deleted. + +'=tsv-modified,name=NAME,initial=INITIAL[,current=CURRENT]' + Reports that the trace state variable NAME is modified with the + initial value INITIAL. The current value CURRENT of trace state + variable is optional and is reported if the current value of trace + state variable is known. + +'=breakpoint-created,bkpt={...}' +'=breakpoint-modified,bkpt={...}' +'=breakpoint-deleted,id=NUMBER' + Reports that a breakpoint was created, modified, or deleted, + respectively. Only user-visible breakpoints are reported to the MI + user. + + The BKPT argument is of the same form as returned by the various + breakpoint commands; *Note GDB/MI Breakpoint Commands::. The + NUMBER is the ordinal number of the breakpoint. + + Note that if a breakpoint is emitted in the result record of a + command, then it will not also be emitted in an async record. + +'=record-started,thread-group="ID"' +'=record-stopped,thread-group="ID"' + Execution log recording was either started or stopped on an + inferior. The ID is the GDB identifier of the thread group + corresponding to the affected inferior. + +'=cmd-param-changed,param=PARAM,value=VALUE' + Reports that a parameter of the command 'set PARAM' is changed to + VALUE. In the multi-word 'set' command, the PARAM is the whole + parameter list to 'set' command. For example, In command 'set + check type on', PARAM is 'check type' and VALUE is 'on'. + +'=memory-changed,thread-group=ID,addr=ADDR,len=LEN[,type="code"]' + Reports that bytes from ADDR to DATA + LEN were written in an + inferior. The ID is the identifier of the thread group + corresponding to the affected inferior. The optional 'type="code"' + part is reported if the memory written to holds executable code. + + +File: gdb.info, Node: GDB/MI Breakpoint Information, Next: GDB/MI Frame Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records + +27.5.4 GDB/MI Breakpoint Information +------------------------------------ + +When GDB reports information about a breakpoint, a tracepoint, a +watchpoint, or a catchpoint, it uses a tuple with the following fields: + +'number' + The breakpoint number. For a breakpoint that represents one + location of a multi-location breakpoint, this will be a dotted + pair, like '1.2'. + +'type' + The type of the breakpoint. For ordinary breakpoints this will be + 'breakpoint', but many values are possible. + +'catch-type' + If the type of the breakpoint is 'catchpoint', then this indicates + the exact type of catchpoint. + +'disp' + This is the breakpoint disposition--either 'del', meaning that the + breakpoint will be deleted at the next stop, or 'keep', meaning + that the breakpoint will not be deleted. + +'enabled' + This indicates whether the breakpoint is enabled, in which case the + value is 'y', or disabled, in which case the value is 'n'. Note + that this is not the same as the field 'enable'. + +'addr' + The address of the breakpoint. This may be a hexidecimal number, + giving the address; or the string '', for a pending + breakpoint; or the string '', for a breakpoint with + multiple locations. This field will not be present if no address + can be determined. For example, a watchpoint does not have an + address. + +'func' + If known, the function in which the breakpoint appears. If not + known, this field is not present. + +'filename' + The name of the source file which contains this function, if known. + If not known, this field is not present. + +'fullname' + The full file name of the source file which contains this function, + if known. If not known, this field is not present. + +'line' + The line number at which this breakpoint appears, if known. If not + known, this field is not present. + +'at' + If the source file is not known, this field may be provided. If + provided, this holds the address of the breakpoint, possibly + followed by a symbol name. + +'pending' + If this breakpoint is pending, this field is present and holds the + text used to set the breakpoint, as entered by the user. + +'evaluated-by' + Where this breakpoint's condition is evaluated, either 'host' or + 'target'. + +'thread' + If this is a thread-specific breakpoint, then this identifies the + thread in which the breakpoint can trigger. + +'task' + If this breakpoint is restricted to a particular Ada task, then + this field will hold the task identifier. + +'cond' + If the breakpoint is conditional, this is the condition expression. + +'ignore' + The ignore count of the breakpoint. + +'enable' + The enable count of the breakpoint. + +'traceframe-usage' + FIXME. + +'static-tracepoint-marker-string-id' + For a static tracepoint, the name of the static tracepoint marker. + +'mask' + For a masked watchpoint, this is the mask. + +'pass' + A tracepoint's pass count. + +'original-location' + The location of the breakpoint as originally specified by the user. + This field is optional. + +'times' + The number of times the breakpoint has been hit. + +'installed' + This field is only given for tracepoints. This is either 'y', + meaning that the tracepoint is installed, or 'n', meaning that it + is not. + +'what' + Some extra data, the exact contents of which are type-dependent. + + For example, here is what the output of '-break-insert' (*note GDB/MI +Breakpoint Commands::) might be: + + -> -break-insert main + <- ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x08048564",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], + times="0"} + <- (gdb) + + +File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Breakpoint Information, Up: GDB/MI Output Records + +27.5.5 GDB/MI Frame Information +------------------------------- + +Response from many MI commands includes an information about stack +frame. This information is a tuple that may have the following fields: + +'level' + The level of the stack frame. The innermost frame has the level of + zero. This field is always present. + +'func' + The name of the function corresponding to the frame. This field + may be absent if GDB is unable to determine the function name. + +'addr' + The code address for the frame. This field is always present. + +'file' + The name of the source files that correspond to the frame's code + address. This field may be absent. + +'line' + The source line corresponding to the frames' code address. This + field may be absent. + +'from' + The name of the binary file (either executable or shared library) + the corresponds to the frame's code address. This field may be + absent. + + +File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records + +27.5.6 GDB/MI Thread Information +-------------------------------- + +Whenever GDB has to report an information about a thread, it uses a +tuple with the following fields: + +'id' + The numeric id assigned to the thread by GDB. This field is always + present. + +'target-id' + Target-specific string identifying the thread. This field is + always present. + +'details' + Additional information about the thread provided by the target. It + is supposed to be human-readable and not interpreted by the + frontend. This field is optional. + +'state' + Either 'stopped' or 'running', depending on whether the thread is + presently running. This field is always present. + +'core' + The value of this field is an integer number of the processor core + the thread was last seen on. This field is optional. + + +File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records + +27.5.7 GDB/MI Ada Exception Information +--------------------------------------- + +Whenever a '*stopped' record is emitted because the program stopped +after hitting an exception catchpoint (*note Set Catchpoints::), GDB +provides the name of the exception that was raised via the +'exception-name' field. + + +File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI + +27.6 Simple Examples of GDB/MI Interaction +========================================== + +This subsection presents several simple examples of interaction using +the GDB/MI interface. In these examples, '->' means that the following +line is passed to GDB/MI as input, while '<-' means the output received +from GDB/MI. + + Note the line breaks shown in the examples are here only for +readability, they don't appear in the real output. + +Setting a Breakpoint +-------------------- + +Setting a breakpoint generates synchronous output which contains +detailed information of the breakpoint. + + -> -break-insert main + <- ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x08048564",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], + times="0"} + <- (gdb) + +Program Execution +----------------- + +Program execution generates asynchronous records and MI gives the reason +that execution stopped. + + -> -exec-run + <- ^running + <- (gdb) + <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", + frame={addr="0x08048564",func="main", + args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}], + file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"} + <- (gdb) + -> -exec-continue + <- ^running + <- (gdb) + <- *stopped,reason="exited-normally" + <- (gdb) + +Quitting GDB +------------ + +Quitting GDB just prints the result class '^exit'. + + -> (gdb) + <- -gdb-exit + <- ^exit + + Please note that '^exit' is printed immediately, but it might take +some time for GDB to actually exit. During that time, GDB performs +necessary cleanups, including killing programs being debugged or +disconnecting from debug hardware, so the frontend should wait till GDB +exits and should only forcibly kill GDB if it fails to exit in +reasonable time. + +A Bad Command +------------- + +Here's what happens if you pass a non-existent command: + + -> -rubbish + <- ^error,msg="Undefined MI command: rubbish" + <- (gdb) + + +File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI + +27.7 GDB/MI Command Description Format +====================================== + +The remaining sections describe blocks of commands. Each block of +commands is laid out in a fashion similar to this section. + +Motivation +---------- + +The motivation for this collection of commands. + +Introduction +------------ + +A brief introduction to this collection of commands as a whole. + +Commands +-------- + +For each command in the block, the following is described: + +Synopsis +........ + + -command ARGS... + +Result +...... + +GDB Command +........... + +The corresponding GDB CLI command(s), if any. + +Example +....... + +Example(s) formatted for readability. Some of the described commands +have not been implemented yet and these are labeled N.A. (not +available). + + +File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Catchpoint Commands, Prev: GDB/MI Command Description Format, Up: GDB/MI + +27.8 GDB/MI Breakpoint Commands +=============================== + +This section documents GDB/MI commands for manipulating breakpoints. + +The '-break-after' Command +-------------------------- + +Synopsis +........ + + -break-after NUMBER COUNT + + The breakpoint number NUMBER is not in effect until it has been hit +COUNT times. To see how this is reflected in the output of the +'-break-list' command, see the description of the '-break-list' command +below. + +GDB Command +........... + +The corresponding GDB command is 'ignore'. + +Example +....... + + (gdb) + -break-insert main + ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x000100d0",func="main",file="hello.c", + fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], + times="0"} + (gdb) + -break-after 1 3 + ~ + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",thread-groups=["i1"],times="0",ignore="3"}]} + (gdb) + +The '-break-commands' Command +----------------------------- + +Synopsis +........ + + -break-commands NUMBER [ COMMAND1 ... COMMANDN ] + + Specifies the CLI commands that should be executed when breakpoint +NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands. +If no command is specified, any previously-set commands are cleared. +*Note Break Commands::. Typical use of this functionality is tracing a +program, that is, printing of values of some variables whenever +breakpoint is hit and then continuing. + +GDB Command +........... + +The corresponding GDB command is 'commands'. + +Example +....... + + (gdb) + -break-insert main + ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x000100d0",func="main",file="hello.c", + fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], + times="0"} + (gdb) + -break-commands 1 "print v" "continue" + ^done + (gdb) + +The '-break-condition' Command +------------------------------ + +Synopsis +........ + + -break-condition NUMBER EXPR + + Breakpoint NUMBER will stop the program only if the condition in EXPR +is true. The condition becomes part of the '-break-list' output (see +the description of the '-break-list' command below). + +GDB Command +........... + +The corresponding GDB command is 'condition'. + +Example +....... + + (gdb) + -break-condition 1 1 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"}]} + (gdb) + +The '-break-delete' Command +--------------------------- + +Synopsis +........ + + -break-delete ( BREAKPOINT )+ + + Delete the breakpoint(s) whose number(s) are specified in the +argument list. This is obviously reflected in the breakpoint list. + +GDB Command +........... + +The corresponding GDB command is 'delete'. + +Example +....... + + (gdb) + -break-delete 1 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="0",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[]} + (gdb) + +The '-break-disable' Command +---------------------------- + +Synopsis +........ + + -break-disable ( BREAKPOINT )+ + + Disable the named BREAKPOINT(s). The field 'enabled' in the break +list is now set to 'n' for the named BREAKPOINT(s). + +GDB Command +........... + +The corresponding GDB command is 'disable'. + +Example +....... + + (gdb) + -break-disable 2 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",thread-groups=["i1"],times="0"}]} + (gdb) + +The '-break-enable' Command +--------------------------- + +Synopsis +........ + + -break-enable ( BREAKPOINT )+ + + Enable (previously disabled) BREAKPOINT(s). + +GDB Command +........... + +The corresponding GDB command is 'enable'. + +Example +....... + + (gdb) + -break-enable 2 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",thread-groups=["i1"],times="0"}]} + (gdb) + +The '-break-info' Command +------------------------- + +Synopsis +........ + + -break-info BREAKPOINT + + Get information about a single breakpoint. + + The result is a table of breakpoints. *Note GDB/MI Breakpoint +Information::, for details on the format of each breakpoint in the +table. + +GDB Command +........... + +The corresponding GDB command is 'info break BREAKPOINT'. + +Example +....... + +N.A. + +The '-break-insert' Command +--------------------------- + +Synopsis +........ + + -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] + [ -c CONDITION ] [ -i IGNORE-COUNT ] + [ -p THREAD-ID ] [ LOCATION ] + +If specified, LOCATION, can be one of: + + * function + * filename:linenum + * filename:function + * *address + + The possible optional parameters of this command are: + +'-t' + Insert a temporary breakpoint. +'-h' + Insert a hardware breakpoint. +'-f' + If LOCATION cannot be parsed (for example if it refers to unknown + files or functions), create a pending breakpoint. Without this + flag, GDB will report an error, and won't create a breakpoint, if + LOCATION cannot be parsed. +'-d' + Create a disabled breakpoint. +'-a' + Create a tracepoint. *Note Tracepoints::. When this parameter is + used together with '-h', a fast tracepoint is created. +'-c CONDITION' + Make the breakpoint conditional on CONDITION. +'-i IGNORE-COUNT' + Initialize the IGNORE-COUNT. +'-p THREAD-ID' + Restrict the breakpoint to the specified THREAD-ID. + +Result +...... + +*Note GDB/MI Breakpoint Information::, for details on the format of the +resulting breakpoint. + + Note: this format is open to change. + +GDB Command +........... + +The corresponding GDB commands are 'break', 'tbreak', 'hbreak', and +'thbreak'. + +Example +....... + + (gdb) + -break-insert main + ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", + fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"], + times="0"} + (gdb) + -break-insert -t foo + ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", + fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"], + times="0"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x0001072c", func="main",file="recursive2.c", + fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"], + times="0"}, + bkpt={number="2",type="breakpoint",disp="del",enabled="y", + addr="0x00010774",func="foo",file="recursive2.c", + fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"], + times="0"}]} + (gdb) + +The '-dprintf-insert' Command +----------------------------- + +Synopsis +........ + + -dprintf-insert [ -t ] [ -f ] [ -d ] + [ -c CONDITION ] [ -i IGNORE-COUNT ] + [ -p THREAD-ID ] [ LOCATION ] [ FORMAT ] + [ ARGUMENT ] + +If specified, LOCATION, can be one of: + + * FUNCTION + * FILENAME:LINENUM + * FILENAME:function + * *ADDRESS + + The possible optional parameters of this command are: + +'-t' + Insert a temporary breakpoint. +'-f' + If LOCATION cannot be parsed (for example, if it refers to unknown + files or functions), create a pending breakpoint. Without this + flag, GDB will report an error, and won't create a breakpoint, if + LOCATION cannot be parsed. +'-d' + Create a disabled breakpoint. +'-c CONDITION' + Make the breakpoint conditional on CONDITION. +'-i IGNORE-COUNT' + Set the ignore count of the breakpoint (*note ignore count: + Conditions.) to IGNORE-COUNT. +'-p THREAD-ID' + Restrict the breakpoint to the specified THREAD-ID. + +Result +...... + +*Note GDB/MI Breakpoint Information::, for details on the format of the +resulting breakpoint. + +GDB Command +........... + +The corresponding GDB command is 'dprintf'. + +Example +....... + + (gdb) + 4-dprintf-insert foo "At foo entry\n" + 4^done,bkpt={number="1",type="dprintf",disp="keep",enabled="y", + addr="0x000000000040061b",func="foo",file="mi-dprintf.c", + fullname="mi-dprintf.c",line="25",thread-groups=["i1"], + times="0",script={"printf \"At foo entry\\n\"","continue"}, + original-location="foo"} + (gdb) + 5-dprintf-insert 26 "arg=%d, g=%d\n" arg g + 5^done,bkpt={number="2",type="dprintf",disp="keep",enabled="y", + addr="0x000000000040062a",func="foo",file="mi-dprintf.c", + fullname="mi-dprintf.c",line="26",thread-groups=["i1"], + times="0",script={"printf \"arg=%d, g=%d\\n\", arg, g","continue"}, + original-location="mi-dprintf.c:26"} + (gdb) + +The '-break-list' Command +------------------------- + +Synopsis +........ + + -break-list + + Displays the list of inserted breakpoints, showing the following +fields: + +'Number' + number of the breakpoint +'Type' + type of the breakpoint: 'breakpoint' or 'watchpoint' +'Disposition' + should the breakpoint be deleted or disabled when it is hit: 'keep' + or 'nokeep' +'Enabled' + is the breakpoint enabled or no: 'y' or 'n' +'Address' + memory location at which the breakpoint is set +'What' + logical location of the breakpoint, expressed by function name, + file name, line number +'Thread-groups' + list of thread groups to which this breakpoint applies +'Times' + number of times the breakpoint has been hit + + If there are no breakpoints or watchpoints, the 'BreakpointTable' +'body' field is an empty list. + +GDB Command +........... + +The corresponding GDB command is 'info break'. + +Example +....... + + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"], + times="0"}, + bkpt={number="2",type="breakpoint",disp="keep",enabled="y", + addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", + line="13",thread-groups=["i1"],times="0"}]} + (gdb) + + Here's an example of the result when there are no breakpoints: + + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="0",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[]} + (gdb) + +The '-break-passcount' Command +------------------------------ + +Synopsis +........ + + -break-passcount TRACEPOINT-NUMBER PASSCOUNT + + Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If +the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint, +error is emitted. This corresponds to CLI command 'passcount'. + +The '-break-watch' Command +-------------------------- + +Synopsis +........ + + -break-watch [ -a | -r ] + + Create a watchpoint. With the '-a' option it will create an "access" +watchpoint, i.e., a watchpoint that triggers either on a read from or on +a write to the memory location. With the '-r' option, the watchpoint +created is a "read" watchpoint, i.e., it will trigger only when the +memory location is accessed for reading. Without either of the options, +the watchpoint created is a regular watchpoint, i.e., it will trigger +when the memory location is accessed for writing. *Note Setting +Watchpoints: Set Watchpoints. + + Note that '-break-list' will report a single list of watchpoints and +breakpoints inserted. + +GDB Command +........... + +The corresponding GDB commands are 'watch', 'awatch', and 'rwatch'. + +Example +....... + +Setting a watchpoint on a variable in the 'main' function: + + (gdb) + -break-watch x + ^done,wpt={number="2",exp="x"} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"}, + value={old="-268439212",new="55"}, + frame={func="main",args=[],file="recursive2.c", + fullname="/home/foo/bar/recursive2.c",line="5"} + (gdb) + + Setting a watchpoint on a variable local to a function. GDB will +stop the program execution twice: first for the variable changing value, +then for the watchpoint going out of scope. + + (gdb) + -break-watch C + ^done,wpt={number="5",exp="C"} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-trigger", + wpt={number="5",exp="C"},value={old="-276895068",new="3"}, + frame={func="callee4",args=[], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-scope",wpnum="5", + frame={func="callee3",args=[{name="strarg", + value="0x11940 \"A string argument.\""}], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} + (gdb) + + Listing breakpoints and watchpoints, at different points in the +program execution. Note that once the watchpoint goes out of scope, it +is deleted. + + (gdb) + -break-watch C + ^done,wpt={number="2",exp="C"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"], + times="1"}, + bkpt={number="2",type="watchpoint",disp="keep", + enabled="y",addr="",what="C",thread-groups=["i1"],times="0"}]} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"}, + value={old="-276895068",new="3"}, + frame={func="callee4",args=[], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"], + times="1"}, + bkpt={number="2",type="watchpoint",disp="keep", + enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"}]} + (gdb) + -exec-continue + ^running + ^done,reason="watchpoint-scope",wpnum="2", + frame={func="callee3",args=[{name="strarg", + value="0x11940 \"A string argument.\""}], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", + thread-groups=["i1"],times="1"}]} + (gdb) + + +File: gdb.info, Node: GDB/MI Catchpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI + +27.9 GDB/MI Catchpoint Commands +=============================== + +This section documents GDB/MI commands for manipulating catchpoints. + +* Menu: + +* Shared Library GDB/MI Catchpoint Commands:: +* Ada Exception GDB/MI Catchpoint Commands:: + + +File: gdb.info, Node: Shared Library GDB/MI Catchpoint Commands, Next: Ada Exception GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands + +27.9.1 Shared Library GDB/MI Catchpoints +---------------------------------------- + +The '-catch-load' Command +------------------------- + +Synopsis +........ + + -catch-load [ -t ] [ -d ] REGEXP + + Add a catchpoint for library load events. If the '-t' option is +used, the catchpoint is a temporary one (*note Setting Breakpoints: Set +Breaks.). If the '-d' option is used, the catchpoint is created in a +disabled state. The 'regexp' argument is a regular expression used to +match the name of the loaded library. + +GDB Command +........... + +The corresponding GDB command is 'catch load'. + +Example +....... + + -catch-load -t foo.so + ^done,bkpt={number="1",type="catchpoint",disp="del",enabled="y", + what="load of library matching foo.so",catch-type="load",times="0"} + (gdb) + +The '-catch-unload' Command +--------------------------- + +Synopsis +........ + + -catch-unload [ -t ] [ -d ] REGEXP + + Add a catchpoint for library unload events. If the '-t' option is +used, the catchpoint is a temporary one (*note Setting Breakpoints: Set +Breaks.). If the '-d' option is used, the catchpoint is created in a +disabled state. The 'regexp' argument is a regular expression used to +match the name of the unloaded library. + +GDB Command +........... + +The corresponding GDB command is 'catch unload'. + +Example +....... + + -catch-unload -d bar.so + ^done,bkpt={number="2",type="catchpoint",disp="keep",enabled="n", + what="load of library matching bar.so",catch-type="unload",times="0"} + (gdb) + + +File: gdb.info, Node: Ada Exception GDB/MI Catchpoint Commands, Prev: Shared Library GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands + +27.9.2 Ada Exception GDB/MI Catchpoints +--------------------------------------- + +The following GDB/MI commands can be used to create catchpoints that +stop the execution when Ada exceptions are being raised. + +The '-catch-assert' Command +--------------------------- + +Synopsis +........ + + -catch-assert [ -c CONDITION] [ -d ] [ -t ] + + Add a catchpoint for failed Ada assertions. + + The possible optional parameters for this command are: + +'-c CONDITION' + Make the catchpoint conditional on CONDITION. +'-d' + Create a disabled catchpoint. +'-t' + Create a temporary catchpoint. + +GDB Command +........... + +The corresponding GDB command is 'catch assert'. + +Example +....... + + -catch-assert + ^done,bkptno="5",bkpt={number="5",type="breakpoint",disp="keep", + enabled="y",addr="0x0000000000404888",what="failed Ada assertions", + thread-groups=["i1"],times="0", + original-location="__gnat_debug_raise_assert_failure"} + (gdb) + +The '-catch-exception' Command +------------------------------ + +Synopsis +........ + + -catch-exception [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ] + [ -t ] [ -u ] + + Add a catchpoint stopping when Ada exceptions are raised. By +default, the command stops the program when any Ada exception gets +raised. But it is also possible, by using some of the optional +parameters described below, to create more selective catchpoints. + + The possible optional parameters for this command are: + +'-c CONDITION' + Make the catchpoint conditional on CONDITION. +'-d' + Create a disabled catchpoint. +'-e EXCEPTION-NAME' + Only stop when EXCEPTION-NAME is raised. This option cannot be + used combined with '-u'. +'-t' + Create a temporary catchpoint. +'-u' + Stop only when an unhandled exception gets raised. This option + cannot be used combined with '-e'. + +GDB Command +........... + +The corresponding GDB commands are 'catch exception' and 'catch +exception unhandled'. + +Example +....... + + -catch-exception -e Program_Error + ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep", + enabled="y",addr="0x0000000000404874", + what="`Program_Error' Ada exception", thread-groups=["i1"], + times="0",original-location="__gnat_debug_raise_exception"} + (gdb) + + +File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Catchpoint Commands, Up: GDB/MI + +27.10 GDB/MI Program Context +============================ + +The '-exec-arguments' Command +----------------------------- + +Synopsis +........ + + -exec-arguments ARGS + + Set the inferior program arguments, to be used in the next +'-exec-run'. + +GDB Command +........... + +The corresponding GDB command is 'set args'. + +Example +....... + + (gdb) + -exec-arguments -v word + ^done + (gdb) + +The '-environment-cd' Command +----------------------------- + +Synopsis +........ + + -environment-cd PATHDIR + + Set GDB's working directory. + +GDB Command +........... + +The corresponding GDB command is 'cd'. + +Example +....... + + (gdb) + -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb + ^done + (gdb) + +The '-environment-directory' Command +------------------------------------ + +Synopsis +........ + + -environment-directory [ -r ] [ PATHDIR ]+ + + Add directories PATHDIR to beginning of search path for source files. +If the '-r' option is used, the search path is reset to the default +search path. If directories PATHDIR are supplied in addition to the +'-r' option, the search path is first reset and then addition occurs as +normal. Multiple directories may be specified, separated by blanks. +Specifying multiple directories in a single command results in the +directories added to the beginning of the search path in the same order +they were presented in the command. If blanks are needed as part of a +directory name, double-quotes should be used around the name. In the +command output, the path will show up separated by the system +directory-separator character. The directory-separator character must +not be used in any directory name. If no directories are specified, the +current search path is displayed. + +GDB Command +........... + +The corresponding GDB command is 'dir'. + +Example +....... + + (gdb) + -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb + ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" + (gdb) + -environment-directory "" + ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" + (gdb) + -environment-directory -r /home/jjohnstn/src/gdb /usr/src + ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" + (gdb) + -environment-directory -r + ^done,source-path="$cdir:$cwd" + (gdb) + +The '-environment-path' Command +------------------------------- + +Synopsis +........ + + -environment-path [ -r ] [ PATHDIR ]+ + + Add directories PATHDIR to beginning of search path for object files. +If the '-r' option is used, the search path is reset to the original +search path that existed at gdb start-up. If directories PATHDIR are +supplied in addition to the '-r' option, the search path is first reset +and then addition occurs as normal. Multiple directories may be +specified, separated by blanks. Specifying multiple directories in a +single command results in the directories added to the beginning of the +search path in the same order they were presented in the command. If +blanks are needed as part of a directory name, double-quotes should be +used around the name. In the command output, the path will show up +separated by the system directory-separator character. The +directory-separator character must not be used in any directory name. +If no directories are specified, the current path is displayed. + +GDB Command +........... + +The corresponding GDB command is 'path'. + +Example +....... + + (gdb) + -environment-path + ^done,path="/usr/bin" + (gdb) + -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin + ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" + (gdb) + -environment-path -r /usr/local/bin + ^done,path="/usr/local/bin:/usr/bin" + (gdb) + +The '-environment-pwd' Command +------------------------------ + +Synopsis +........ + + -environment-pwd + + Show the current working directory. + +GDB Command +........... + +The corresponding GDB command is 'pwd'. + +Example +....... + + (gdb) + -environment-pwd + ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" + (gdb) + + +File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Ada Tasking Commands, Prev: GDB/MI Program Context, Up: GDB/MI + +27.11 GDB/MI Thread Commands +============================ + +The '-thread-info' Command +-------------------------- + +Synopsis +........ + + -thread-info [ THREAD-ID ] + + Reports information about either a specific thread, if the THREAD-ID +parameter is present, or about all threads. When printing information +about all threads, also reports the current thread. + +GDB Command +........... + +The 'info thread' command prints the same information about all threads. + +Result +...... + +The result is a list of threads. The following attributes are defined +for a given thread: + +'current' + This field exists only for the current thread. It has the value + '*'. + +'id' + The identifier that GDB uses to refer to the thread. + +'target-id' + The identifier that the target uses to refer to the thread. + +'details' + Extra information about the thread, in a target-specific format. + This field is optional. + +'name' + The name of the thread. If the user specified a name using the + 'thread name' command, then this name is given. Otherwise, if GDB + can extract the thread name from the target, then that name is + given. If GDB cannot find the thread name, then this field is + omitted. + +'frame' + The stack frame currently executing in the thread. + +'state' + The thread's state. The 'state' field may have the following + values: + + 'stopped' + The thread is stopped. Frame information is available for + stopped threads. + + 'running' + The thread is running. There's no frame information for + running threads. + +'core' + If GDB can find the CPU core on which this thread is running, then + this field is the core identifier. This field is optional. + +Example +....... + + -thread-info + ^done,threads=[ + {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", + frame={level="0",addr="0xffffe410",func="__kernel_vsyscall", + args=[]},state="running"}, + {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", + frame={level="0",addr="0x0804891f",func="foo", + args=[{name="i",value="10"}], + file="/tmp/a.c",fullname="/tmp/a.c",line="158"}, + state="running"}], + current-thread-id="1" + (gdb) + +The '-thread-list-ids' Command +------------------------------ + +Synopsis +........ + + -thread-list-ids + + Produces a list of the currently known GDB thread ids. At the end of +the list it also prints the total number of such threads. + + This command is retained for historical reasons, the '-thread-info' +command should be used instead. + +GDB Command +........... + +Part of 'info threads' supplies the same information. + +Example +....... + + (gdb) + -thread-list-ids + ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, + current-thread-id="1",number-of-threads="3" + (gdb) + +The '-thread-select' Command +---------------------------- + +Synopsis +........ + + -thread-select THREADNUM + + Make THREADNUM the current thread. It prints the number of the new +current thread, and the topmost frame for that thread. + + This command is deprecated in favor of explicitly using the +'--thread' option to each command. + +GDB Command +........... + +The corresponding GDB command is 'thread'. + +Example +....... + + (gdb) + -exec-next + ^running + (gdb) + *stopped,reason="end-stepping-range",thread-id="2",line="187", + file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" + (gdb) + -thread-list-ids + ^done, + thread-ids={thread-id="3",thread-id="2",thread-id="1"}, + number-of-threads="3" + (gdb) + -thread-select 3 + ^done,new-thread-id="3", + frame={level="0",func="vprintf", + args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, + {name="arg",value="0x2"}],file="vprintf.c",line="31"} + (gdb) + + +File: gdb.info, Node: GDB/MI Ada Tasking Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Thread Commands, Up: GDB/MI + +27.12 GDB/MI Ada Tasking Commands +================================= + +The '-ada-task-info' Command +---------------------------- + +Synopsis +........ + + -ada-task-info [ TASK-ID ] + + Reports information about either a specific Ada task, if the TASK-ID +parameter is present, or about all Ada tasks. + +GDB Command +........... + +The 'info tasks' command prints the same information about all Ada tasks +(*note Ada Tasks::). + +Result +...... + +The result is a table of Ada tasks. The following columns are defined +for each Ada task: + +'current' + This field exists only for the current thread. It has the value + '*'. + +'id' + The identifier that GDB uses to refer to the Ada task. + +'task-id' + The identifier that the target uses to refer to the Ada task. + +'thread-id' + The identifier of the thread corresponding to the Ada task. + + This field should always exist, as Ada tasks are always implemented + on top of a thread. But if GDB cannot find this corresponding + thread for any reason, the field is omitted. + +'parent-id' + This field exists only when the task was created by another task. + In this case, it provides the ID of the parent task. + +'priority' + The base priority of the task. + +'state' + The current state of the task. For a detailed description of the + possible states, see *note Ada Tasks::. + +'name' + The name of the task. + +Example +....... + + -ada-task-info + ^done,tasks={nr_rows="3",nr_cols="8", + hdr=[{width="1",alignment="-1",col_name="current",colhdr=""}, + {width="3",alignment="1",col_name="id",colhdr="ID"}, + {width="9",alignment="1",col_name="task-id",colhdr="TID"}, + {width="4",alignment="1",col_name="thread-id",colhdr=""}, + {width="4",alignment="1",col_name="parent-id",colhdr="P-ID"}, + {width="3",alignment="1",col_name="priority",colhdr="Pri"}, + {width="22",alignment="-1",col_name="state",colhdr="State"}, + {width="1",alignment="2",col_name="name",colhdr="Name"}], + body=[{current="*",id="1",task-id=" 644010",thread-id="1",priority="48", + state="Child Termination Wait",name="main_task"}]} + (gdb) + + +File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Ada Tasking Commands, Up: GDB/MI + +27.13 GDB/MI Program Execution +============================== + +These are the asynchronous commands which generate the out-of-band +record '*stopped'. Currently GDB only really executes asynchronously +with remote targets and this interaction is mimicked in other cases. + +The '-exec-continue' Command +---------------------------- + +Synopsis +........ + + -exec-continue [--reverse] [--all|--thread-group N] + + Resumes the execution of the inferior program, which will continue to +execute until it reaches a debugger stop event. If the '--reverse' +option is specified, execution resumes in reverse until it reaches a +stop event. Stop events may include + * breakpoints or watchpoints + * signals or exceptions + * the end of the process (or its beginning under '--reverse') + * the end or beginning of a replay log if one is being used. + In all-stop mode (*note All-Stop Mode::), may resume only one thread, +or all threads, depending on the value of the 'scheduler-locking' +variable. If '--all' is specified, all threads (in all inferiors) will +be resumed. The '--all' option is ignored in all-stop mode. If the +'--thread-group' options is specified, then all threads in that thread +group are resumed. + +GDB Command +........... + +The corresponding GDB corresponding is 'continue'. + +Example +....... + + -exec-continue + ^running + (gdb) + @Hello world + *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={ + func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", + line="13"} + (gdb) + +The '-exec-finish' Command +-------------------------- + +Synopsis +........ + + -exec-finish [--reverse] + + Resumes the execution of the inferior program until the current +function is exited. Displays the results returned by the function. If +the '--reverse' option is specified, resumes the reverse execution of +the inferior program until the point where current function was called. + +GDB Command +........... + +The corresponding GDB command is 'finish'. + +Example +....... + +Function returning 'void'. + + -exec-finish + ^running + (gdb) + @hello from foo + *stopped,reason="function-finished",frame={func="main",args=[], + file="hello.c",fullname="/home/foo/bar/hello.c",line="7"} + (gdb) + + Function returning other than 'void'. The name of the internal GDB +variable storing the result is printed, together with the value itself. + + -exec-finish + ^running + (gdb) + *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", + args=[{name="a",value="1"],{name="b",value="9"}}, + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + gdb-result-var="$1",return-value="0" + (gdb) + +The '-exec-interrupt' Command +----------------------------- + +Synopsis +........ + + -exec-interrupt [--all|--thread-group N] + + Interrupts the background execution of the target. Note how the +token associated with the stop message is the one for the execution +command that has been interrupted. The token for the interrupt itself +only appears in the '^done' output. If the user is trying to interrupt +a non-running program, an error message will be printed. + + Note that when asynchronous execution is enabled, this command is +asynchronous just like other execution commands. That is, first the +'^done' response will be printed, and the target stop will be reported +after that using the '*stopped' notification. + + In non-stop mode, only the context thread is interrupted by default. +All threads (in all inferiors) will be interrupted if the '--all' option +is specified. If the '--thread-group' option is specified, all threads +in that group will be interrupted. + +GDB Command +........... + +The corresponding GDB command is 'interrupt'. + +Example +....... + + (gdb) + 111-exec-continue + 111^running + + (gdb) + 222-exec-interrupt + 222^done + (gdb) + 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", + frame={addr="0x00010140",func="foo",args=[],file="try.c", + fullname="/home/foo/bar/try.c",line="13"} + (gdb) + + (gdb) + -exec-interrupt + ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." + (gdb) + +The '-exec-jump' Command +------------------------ + +Synopsis +........ + + -exec-jump LOCATION + + Resumes execution of the inferior program at the location specified +by parameter. *Note Specify Location::, for a description of the +different forms of LOCATION. + +GDB Command +........... + +The corresponding GDB command is 'jump'. + +Example +....... + + -exec-jump foo.c:10 + *running,thread-id="all" + ^running + +The '-exec-next' Command +------------------------ + +Synopsis +........ + + -exec-next [--reverse] + + Resumes execution of the inferior program, stopping when the +beginning of the next source line is reached. + + If the '--reverse' option is specified, resumes reverse execution of +the inferior program, stopping at the beginning of the previous source +line. If you issue this command on the first line of a function, it +will take you back to the caller of that function, to the source line +where the function was called. + +GDB Command +........... + +The corresponding GDB command is 'next'. + +Example +....... + + -exec-next + ^running + (gdb) + *stopped,reason="end-stepping-range",line="8",file="hello.c" + (gdb) + +The '-exec-next-instruction' Command +------------------------------------ + +Synopsis +........ + + -exec-next-instruction [--reverse] + + Executes one machine instruction. If the instruction is a function +call, continues until the function returns. If the program stops at an +instruction in the middle of a source line, the address will be printed +as well. + + If the '--reverse' option is specified, resumes reverse execution of +the inferior program, stopping at the previous instruction. If the +previously executed instruction was a return from another function, it +will continue to execute in reverse until the call to that function +(from the current stack frame) is reached. + +GDB Command +........... + +The corresponding GDB command is 'nexti'. + +Example +....... + + (gdb) + -exec-next-instruction + ^running + + (gdb) + *stopped,reason="end-stepping-range", + addr="0x000100d4",line="5",file="hello.c" + (gdb) + +The '-exec-return' Command +-------------------------- + +Synopsis +........ + + -exec-return + + Makes current function return immediately. Doesn't execute the +inferior. Displays the new current frame. + +GDB Command +........... + +The corresponding GDB command is 'return'. + +Example +....... + + (gdb) + 200-break-insert callee4 + 200^done,bkpt={number="1",addr="0x00010734", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} + (gdb) + 000-exec-run + 000^running + (gdb) + 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", + frame={func="callee4",args=[], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"} + (gdb) + 205-break-delete + 205^done + (gdb) + 111-exec-return + 111^done,frame={level="0",func="callee3", + args=[{name="strarg", + value="0x11940 \"A string argument.\""}], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} + (gdb) + +The '-exec-run' Command +----------------------- + +Synopsis +........ + + -exec-run [ --all | --thread-group N ] [ --start ] + + Starts execution of the inferior from the beginning. The inferior +executes until either a breakpoint is encountered or the program exits. +In the latter case the output will include an exit code, if the program +has exited exceptionally. + + When neither the '--all' nor the '--thread-group' option is +specified, the current inferior is started. If the '--thread-group' +option is specified, it should refer to a thread group of type +'process', and that thread group will be started. If the '--all' option +is specified, then all inferiors will be started. + + Using the '--start' option instructs the debugger to stop the +execution at the start of the inferior's main subprogram, following the +same behavior as the 'start' command (*note Starting::). + +GDB Command +........... + +The corresponding GDB command is 'run'. + +Examples +........ + + (gdb) + -break-insert main + ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} + (gdb) + -exec-run + ^running + (gdb) + *stopped,reason="breakpoint-hit",disp="keep",bkptno="1", + frame={func="main",args=[],file="recursive2.c", + fullname="/home/foo/bar/recursive2.c",line="4"} + (gdb) + +Program exited normally: + + (gdb) + -exec-run + ^running + (gdb) + x = 55 + *stopped,reason="exited-normally" + (gdb) + +Program exited exceptionally: + + (gdb) + -exec-run + ^running + (gdb) + x = 55 + *stopped,reason="exited",exit-code="01" + (gdb) + + Another way the program can terminate is if it receives a signal such +as 'SIGINT'. In this case, GDB/MI displays this: + + (gdb) + *stopped,reason="exited-signalled",signal-name="SIGINT", + signal-meaning="Interrupt" + +The '-exec-step' Command +------------------------ + +Synopsis +........ + + -exec-step [--reverse] + + Resumes execution of the inferior program, stopping when the +beginning of the next source line is reached, if the next source line is +not a function call. If it is, stop at the first instruction of the +called function. If the '--reverse' option is specified, resumes +reverse execution of the inferior program, stopping at the beginning of +the previously executed source line. + +GDB Command +........... + +The corresponding GDB command is 'step'. + +Example +....... + +Stepping into a function: + + -exec-step + ^running + (gdb) + *stopped,reason="end-stepping-range", + frame={func="foo",args=[{name="a",value="10"}, + {name="b",value="0"}],file="recursive2.c", + fullname="/home/foo/bar/recursive2.c",line="11"} + (gdb) + + Regular stepping: + + -exec-step + ^running + (gdb) + *stopped,reason="end-stepping-range",line="14",file="recursive2.c" + (gdb) + +The '-exec-step-instruction' Command +------------------------------------ + +Synopsis +........ + + -exec-step-instruction [--reverse] + + Resumes the inferior which executes one machine instruction. If the +'--reverse' option is specified, resumes reverse execution of the +inferior program, stopping at the previously executed instruction. The +output, once GDB has stopped, will vary depending on whether we have +stopped in the middle of a source line or not. In the former case, the +address at which the program stopped will be printed as well. + +GDB Command +........... + +The corresponding GDB command is 'stepi'. + +Example +....... + + (gdb) + -exec-step-instruction + ^running + + (gdb) + *stopped,reason="end-stepping-range", + frame={func="foo",args=[],file="try.c", + fullname="/home/foo/bar/try.c",line="10"} + (gdb) + -exec-step-instruction + ^running + + (gdb) + *stopped,reason="end-stepping-range", + frame={addr="0x000100f4",func="foo",args=[],file="try.c", + fullname="/home/foo/bar/try.c",line="10"} + (gdb) + +The '-exec-until' Command +------------------------- + +Synopsis +........ + + -exec-until [ LOCATION ] + + Executes the inferior until the LOCATION specified in the argument is +reached. If there is no argument, the inferior executes until a source +line greater than the current one is reached. The reason for stopping +in this case will be 'location-reached'. + +GDB Command +........... + +The corresponding GDB command is 'until'. + +Example +....... + + (gdb) + -exec-until recursive2.c:6 + ^running + (gdb) + x = 55 + *stopped,reason="location-reached",frame={func="main",args=[], + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"} + (gdb) + + +File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI + +27.14 GDB/MI Stack Manipulation Commands +======================================== + +The '-enable-frame-filters' Command +----------------------------------- + + -enable-frame-filters + + GDB allows Python-based frame filters to affect the output of the MI +commands relating to stack traces. As there is no way to implement this +in a fully backward-compatible way, a front end must request that this +functionality be enabled. + + Once enabled, this feature cannot be disabled. + + Note that if Python support has not been compiled into GDB, this +command will still succeed (and do nothing). + +The '-stack-info-frame' Command +------------------------------- + +Synopsis +........ + + -stack-info-frame + + Get info on the selected frame. + +GDB Command +........... + +The corresponding GDB command is 'info frame' or 'frame' (without +arguments). + +Example +....... + + (gdb) + -stack-info-frame + ^done,frame={level="1",addr="0x0001076c",func="callee3", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"} + (gdb) + +The '-stack-info-depth' Command +------------------------------- + +Synopsis +........ + + -stack-info-depth [ MAX-DEPTH ] + + Return the depth of the stack. If the integer argument MAX-DEPTH is +specified, do not count beyond MAX-DEPTH frames. + +GDB Command +........... + +There's no equivalent GDB command. + +Example +....... + +For a stack with frame levels 0 through 11: + + (gdb) + -stack-info-depth + ^done,depth="12" + (gdb) + -stack-info-depth 4 + ^done,depth="4" + (gdb) + -stack-info-depth 12 + ^done,depth="12" + (gdb) + -stack-info-depth 11 + ^done,depth="11" + (gdb) + -stack-info-depth 13 + ^done,depth="12" + (gdb) + +The '-stack-list-arguments' Command +----------------------------------- + +Synopsis +........ + + -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES + [ LOW-FRAME HIGH-FRAME ] + + Display a list of the arguments for the frames between LOW-FRAME and +HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, +list the arguments for the whole call stack. If the two arguments are +equal, show the single frame at the corresponding level. It is an error +if LOW-FRAME is larger than the actual number of frames. On the other +hand, HIGH-FRAME may be larger than the actual number of frames, in +which case only existing frames will be returned. + + If PRINT-VALUES is 0 or '--no-values', print only the names of the +variables; if it is 1 or '--all-values', print also their values; and if +it is 2 or '--simple-values', print the name, type and value for simple +data types, and the name and type for arrays, structures and unions. If +the option '--no-frame-filters' is supplied, then Python frame filters +will not be executed. + + If the '--skip-unavailable' option is specified, arguments that are +not available are not listed. Partially available arguments are still +displayed, however. + + Use of this command to obtain arguments in a single frame is +deprecated in favor of the '-stack-list-variables' command. + +GDB Command +........... + +GDB does not have an equivalent command. 'gdbtk' has a 'gdb_get_args' +command which partially overlaps with the functionality of +'-stack-list-arguments'. + +Example +....... + + (gdb) + -stack-list-frames + ^done, + stack=[ + frame={level="0",addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, + frame={level="1",addr="0x0001076c",func="callee3", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, + frame={level="2",addr="0x0001078c",func="callee2", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, + frame={level="3",addr="0x000107b4",func="callee1", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, + frame={level="4",addr="0x000107e0",func="main", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] + (gdb) + -stack-list-arguments 0 + ^done, + stack-args=[ + frame={level="0",args=[]}, + frame={level="1",args=[name="strarg"]}, + frame={level="2",args=[name="intarg",name="strarg"]}, + frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, + frame={level="4",args=[]}] + (gdb) + -stack-list-arguments 1 + ^done, + stack-args=[ + frame={level="0",args=[]}, + frame={level="1", + args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, + frame={level="2",args=[ + {name="intarg",value="2"}, + {name="strarg",value="0x11940 \"A string argument.\""}]}, + {frame={level="3",args=[ + {name="intarg",value="2"}, + {name="strarg",value="0x11940 \"A string argument.\""}, + {name="fltarg",value="3.5"}]}, + frame={level="4",args=[]}] + (gdb) + -stack-list-arguments 0 2 2 + ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] + (gdb) + -stack-list-arguments 1 2 2 + ^done,stack-args=[frame={level="2", + args=[{name="intarg",value="2"}, + {name="strarg",value="0x11940 \"A string argument.\""}]}] + (gdb) + +The '-stack-list-frames' Command +-------------------------------- + +Synopsis +........ + + -stack-list-frames [ --no-frame-filters LOW-FRAME HIGH-FRAME ] + + List the frames currently on the stack. For each frame it displays +the following info: + +'LEVEL' + The frame number, 0 being the topmost frame, i.e., the innermost + function. +'ADDR' + The '$pc' value for that frame. +'FUNC' + Function name. +'FILE' + File name of the source file where the function lives. +'FULLNAME' + The full file name of the source file where the function lives. +'LINE' + Line number corresponding to the '$pc'. +'FROM' + The shared library where this function is defined. This is only + given if the frame's function is not known. + + If invoked without arguments, this command prints a backtrace for the +whole stack. If given two integer arguments, it shows the frames whose +levels are between the two arguments (inclusive). If the two arguments +are equal, it shows the single frame at the corresponding level. It is +an error if LOW-FRAME is larger than the actual number of frames. On +the other hand, HIGH-FRAME may be larger than the actual number of +frames, in which case only existing frames will be returned. If the +option '--no-frame-filters' is supplied, then Python frame filters will +not be executed. + +GDB Command +........... + +The corresponding GDB commands are 'backtrace' and 'where'. + +Example +....... + +Full stack backtrace: + + (gdb) + -stack-list-frames + ^done,stack= + [frame={level="0",addr="0x0001076c",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"}, + frame={level="1",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="2",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="4",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="5",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="6",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="7",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="8",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="9",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="10",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="11",addr="0x00010738",func="main", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}] + (gdb) + + Show frames between LOW_FRAME and HIGH_FRAME: + + (gdb) + -stack-list-frames 3 5 + ^done,stack= + [frame={level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="4",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, + frame={level="5",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] + (gdb) + + Show a single frame: + + (gdb) + -stack-list-frames 3 3 + ^done,stack= + [frame={level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] + (gdb) + +The '-stack-list-locals' Command +-------------------------------- + +Synopsis +........ + + -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES + + Display the local variable names for the selected frame. If +PRINT-VALUES is 0 or '--no-values', print only the names of the +variables; if it is 1 or '--all-values', print also their values; and if +it is 2 or '--simple-values', print the name, type and value for simple +data types, and the name and type for arrays, structures and unions. In +this last case, a frontend can immediately display the value of simple +data types and create variable objects for other data types when the +user wishes to explore their values in more detail. If the option +'--no-frame-filters' is supplied, then Python frame filters will not be +executed. + + If the '--skip-unavailable' option is specified, local variables that +are not available are not listed. Partially available local variables +are still displayed, however. + + This command is deprecated in favor of the '-stack-list-variables' +command. + +GDB Command +........... + +'info locals' in GDB, 'gdb_get_locals' in 'gdbtk'. + +Example +....... + + (gdb) + -stack-list-locals 0 + ^done,locals=[name="A",name="B",name="C"] + (gdb) + -stack-list-locals --all-values + ^done,locals=[{name="A",value="1"},{name="B",value="2"}, + {name="C",value="{1, 2, 3}"}] + -stack-list-locals --simple-values + ^done,locals=[{name="A",type="int",value="1"}, + {name="B",type="int",value="2"},{name="C",type="int [3]"}] + (gdb) + +The '-stack-list-variables' Command +----------------------------------- + +Synopsis +........ + + -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES + + Display the names of local variables and function arguments for the +selected frame. If PRINT-VALUES is 0 or '--no-values', print only the +names of the variables; if it is 1 or '--all-values', print also their +values; and if it is 2 or '--simple-values', print the name, type and +value for simple data types, and the name and type for arrays, +structures and unions. If the option '--no-frame-filters' is supplied, +then Python frame filters will not be executed. + + If the '--skip-unavailable' option is specified, local variables and +arguments that are not available are not listed. Partially available +arguments and local variables are still displayed, however. + +Example +....... + + (gdb) + -stack-list-variables --thread 1 --frame 0 --all-values + ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}] + (gdb) + +The '-stack-select-frame' Command +--------------------------------- + +Synopsis +........ + + -stack-select-frame FRAMENUM + + Change the selected frame. Select a different frame FRAMENUM on the +stack. + + This command in deprecated in favor of passing the '--frame' option +to every command. + +GDB Command +........... + +The corresponding GDB commands are 'frame', 'up', 'down', +'select-frame', 'up-silent', and 'down-silent'. + +Example +....... + + (gdb) + -stack-select-frame 2 + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI + +27.15 GDB/MI Variable Objects +============================= + +Introduction to Variable Objects +-------------------------------- + +Variable objects are "object-oriented" MI interface for examining and +changing values of expressions. Unlike some other MI interfaces that +work with expressions, variable objects are specifically designed for +simple and efficient presentation in the frontend. A variable object is +identified by string name. When a variable object is created, the +frontend specifies the expression for that variable object. The +expression can be a simple variable, or it can be an arbitrary complex +expression, and can even involve CPU registers. After creating a +variable object, the frontend can invoke other variable object +operations--for example to obtain or change the value of a variable +object, or to change display format. + + Variable objects have hierarchical tree structure. Any variable +object that corresponds to a composite type, such as structure in C, has +a number of child variable objects, for example corresponding to each +element of a structure. A child variable object can itself have +children, recursively. Recursion ends when we reach leaf variable +objects, which always have built-in types. Child variable objects are +created only by explicit request, so if a frontend is not interested in +the children of a particular variable object, no child will be created. + + For a leaf variable object it is possible to obtain its value as a +string, or set the value from a string. String value can be also +obtained for a non-leaf variable object, but it's generally a string +that only indicates the type of the object, and does not list its +contents. Assignment to a non-leaf variable object is not allowed. + + A frontend does not need to read the values of all variable objects +each time the program stops. Instead, MI provides an update command +that lists all variable objects whose values has changed since the last +update operation. This considerably reduces the amount of data that +must be transferred to the frontend. As noted above, children variable +objects are created on demand, and only leaf variable objects have a +real value. As result, gdb will read target memory only for leaf +variables that frontend has created. + + The automatic update is not always desirable. For example, a +frontend might want to keep a value of some expression for future +reference, and never update it. For another example, fetching memory is +relatively slow for embedded targets, so a frontend might want to +disable automatic update for the variables that are either not visible +on the screen, or "closed". This is possible using so called "frozen +variable objects". Such variable objects are never implicitly updated. + + Variable objects can be either "fixed" or "floating". For the fixed +variable object, the expression is parsed when the variable object is +created, including associating identifiers to specific variables. The +meaning of expression never changes. For a floating variable object the +values of variables whose names appear in the expressions are +re-evaluated every time in the context of the current frame. Consider +this example: + + void do_work(...) + { + struct work_state state; + + if (...) + do_work(...); + } + + If a fixed variable object for the 'state' variable is created in +this function, and we enter the recursive call, the variable object will +report the value of 'state' in the top-level 'do_work' invocation. On +the other hand, a floating variable object will report the value of +'state' in the current frame. + + If an expression specified when creating a fixed variable object +refers to a local variable, the variable object becomes bound to the +thread and frame in which the variable object is created. When such +variable object is updated, GDB makes sure that the thread/frame +combination the variable object is bound to still exists, and +re-evaluates the variable object in context of that thread/frame. + + The following is the complete set of GDB/MI operations defined to +access this functionality: + +*Operation* *Description* + +'-enable-pretty-printing' enable Python-based pretty-printing +'-var-create' create a variable object +'-var-delete' delete the variable object and/or its + children +'-var-set-format' set the display format of this variable +'-var-show-format' show the display format of this variable +'-var-info-num-children' tells how many children this object has +'-var-list-children' return a list of the object's children +'-var-info-type' show the type of this variable object +'-var-info-expression' print parent-relative expression that + this variable object represents +'-var-info-path-expression' print full expression that this variable + object represents +'-var-show-attributes' is this variable editable? does it exist + here? +'-var-evaluate-expression' get the value of this variable +'-var-assign' set the value of this variable +'-var-update' update the variable and its children +'-var-set-frozen' set frozeness attribute +'-var-set-update-range' set range of children to display on + update + + In the next subsection we describe each operation in detail and +suggest how it can be used. + +Description And Use of Operations on Variable Objects +----------------------------------------------------- + +The '-enable-pretty-printing' Command +------------------------------------- + + -enable-pretty-printing + + GDB allows Python-based visualizers to affect the output of the MI +variable object commands. However, because there was no way to +implement this in a fully backward-compatible way, a front end must +request that this functionality be enabled. + + Once enabled, this feature cannot be disabled. + + Note that if Python support has not been compiled into GDB, this +command will still succeed (and do nothing). + + This feature is currently (as of GDB 7.0) experimental, and may work +differently in future versions of GDB. + +The '-var-create' Command +------------------------- + +Synopsis +........ + + -var-create {NAME | "-"} + {FRAME-ADDR | "*" | "@"} EXPRESSION + + This operation creates a variable object, which allows the monitoring +of a variable, the result of an expression, a memory cell or a CPU +register. + + The NAME parameter is the string by which the object can be +referenced. It must be unique. If '-' is specified, the varobj system +will generate a string "varNNNNNN" automatically. It will be unique +provided that one does not specify NAME of that format. The command +fails if a duplicate name is found. + + The frame under which the expression should be evaluated can be +specified by FRAME-ADDR. A '*' indicates that the current frame should +be used. A '@' indicates that a floating variable object must be +created. + + EXPRESSION is any expression valid on the current language set (must +not begin with a '*'), or one of the following: + + * '*ADDR', where ADDR is the address of a memory cell + + * '*ADDR-ADDR' -- a memory address range (TBD) + + * '$REGNAME' -- a CPU register name + + A varobj's contents may be provided by a Python-based pretty-printer. +In this case the varobj is known as a "dynamic varobj". Dynamic varobjs +have slightly different semantics in some cases. If the +'-enable-pretty-printing' command is not sent, then GDB will never +create a dynamic varobj. This ensures backward compatibility for +existing clients. + +Result +...... + +This operation returns attributes of the newly-created varobj. These +are: + +'name' + The name of the varobj. + +'numchild' + The number of children of the varobj. This number is not + necessarily reliable for a dynamic varobj. Instead, you must + examine the 'has_more' attribute. + +'value' + The varobj's scalar value. For a varobj whose type is some sort of + aggregate (e.g., a 'struct'), or for a dynamic varobj, this value + will not be interesting. + +'type' + The varobj's type. This is a string representation of the type, as + would be printed by the GDB CLI. If 'print object' (*note set print + object: Print Settings.) is set to 'on', the _actual_ (derived) + type of the object is shown rather than the _declared_ one. + +'thread-id' + If a variable object is bound to a specific thread, then this is + the thread's identifier. + +'has_more' + For a dynamic varobj, this indicates whether there appear to be any + children available. For a non-dynamic varobj, this will be 0. + +'dynamic' + This attribute will be present and have the value '1' if the varobj + is a dynamic varobj. If the varobj is not a dynamic varobj, then + this attribute will not be present. + +'displayhint' + A dynamic varobj can supply a display hint to the front end. The + value comes directly from the Python pretty-printer object's + 'display_hint' method. *Note Pretty Printing API::. + + Typical output will look like this: + + name="NAME",numchild="N",type="TYPE",thread-id="M", + has_more="HAS_MORE" + +The '-var-delete' Command +------------------------- + +Synopsis +........ + + -var-delete [ -c ] NAME + + Deletes a previously created variable object and all of its children. +With the '-c' option, just deletes the children. + + Returns an error if the object NAME is not found. + +The '-var-set-format' Command +----------------------------- + +Synopsis +........ + + -var-set-format NAME FORMAT-SPEC + + Sets the output format for the value of the object NAME to be +FORMAT-SPEC. + + The syntax for the FORMAT-SPEC is as follows: + + FORMAT-SPEC ==> + {binary | decimal | hexadecimal | octal | natural} + + The natural format is the default format choosen automatically based +on the variable type (like decimal for an 'int', hex for pointers, +etc.). + + For a variable with children, the format is set only on the variable +itself, and the children are not affected. + +The '-var-show-format' Command +------------------------------ + +Synopsis +........ + + -var-show-format NAME + + Returns the format used to display the value of the object NAME. + + FORMAT ==> + FORMAT-SPEC + +The '-var-info-num-children' Command +------------------------------------ + +Synopsis +........ + + -var-info-num-children NAME + + Returns the number of children of a variable object NAME: + + numchild=N + + Note that this number is not completely reliable for a dynamic +varobj. It will return the current number of children, but more +children may be available. + +The '-var-list-children' Command +-------------------------------- + +Synopsis +........ + + -var-list-children [PRINT-VALUES] NAME [FROM TO] + + Return a list of the children of the specified variable object and +create variable objects for them, if they do not already exist. With a +single argument or if PRINT-VALUES has a value of 0 or '--no-values', +print only the names of the variables; if PRINT-VALUES is 1 or +'--all-values', also print their values; and if it is 2 or +'--simple-values' print the name and value for simple data types and +just the name for arrays, structures and unions. + + FROM and TO, if specified, indicate the range of children to report. +If FROM or TO is less than zero, the range is reset and all children +will be reported. Otherwise, children starting at FROM (zero-based) and +up to and excluding TO will be reported. + + If a child range is requested, it will only affect the current call +to '-var-list-children', but not future calls to '-var-update'. For +this, you must instead use '-var-set-update-range'. The intent of this +approach is to enable a front end to implement any update approach it +likes; for example, scrolling a view may cause the front end to request +more children with '-var-list-children', and then the front end could +call '-var-set-update-range' with a different range to ensure that +future updates are restricted to just the visible items. + + For each child the following results are returned: + +NAME + Name of the variable object created for this child. + +EXP + The expression to be shown to the user by the front end to + designate this child. For example this may be the name of a + structure member. + + For a dynamic varobj, this value cannot be used to form an + expression. There is no way to do this at all with a dynamic + varobj. + + For C/C++ structures there are several pseudo children returned to + designate access qualifiers. For these pseudo children EXP is + 'public', 'private', or 'protected'. In this case the type and + value are not present. + + A dynamic varobj will not report the access qualifying + pseudo-children, regardless of the language. This information is + not available at all with a dynamic varobj. + +NUMCHILD + Number of children this child has. For a dynamic varobj, this will + be 0. + +TYPE + The type of the child. If 'print object' (*note set print object: + Print Settings.) is set to 'on', the _actual_ (derived) type of the + object is shown rather than the _declared_ one. + +VALUE + If values were requested, this is the value. + +THREAD-ID + If this variable object is associated with a thread, this is the + thread id. Otherwise this result is not present. + +FROZEN + If the variable object is frozen, this variable will be present + with a value of 1. + +DISPLAYHINT + A dynamic varobj can supply a display hint to the front end. The + value comes directly from the Python pretty-printer object's + 'display_hint' method. *Note Pretty Printing API::. + +DYNAMIC + This attribute will be present and have the value '1' if the varobj + is a dynamic varobj. If the varobj is not a dynamic varobj, then + this attribute will not be present. + + The result may have its own attributes: + +'displayhint' + A dynamic varobj can supply a display hint to the front end. The + value comes directly from the Python pretty-printer object's + 'display_hint' method. *Note Pretty Printing API::. + +'has_more' + This is an integer attribute which is nonzero if there are children + remaining after the end of the selected range. + +Example +....... + + (gdb) + -var-list-children n + ^done,numchild=N,children=[child={name=NAME,exp=EXP, + numchild=N,type=TYPE},(repeats N times)] + (gdb) + -var-list-children --all-values n + ^done,numchild=N,children=[child={name=NAME,exp=EXP, + numchild=N,value=VALUE,type=TYPE},(repeats N times)] + +The '-var-info-type' Command +---------------------------- + +Synopsis +........ + + -var-info-type NAME + + Returns the type of the specified variable NAME. The type is +returned as a string in the same format as it is output by the GDB CLI: + + type=TYPENAME + +The '-var-info-expression' Command +---------------------------------- + +Synopsis +........ + + -var-info-expression NAME + + Returns a string that is suitable for presenting this variable object +in user interface. The string is generally not valid expression in the +current language, and cannot be evaluated. + + For example, if 'a' is an array, and variable object 'A' was created +for 'a', then we'll get this output: + + (gdb) -var-info-expression A.1 + ^done,lang="C",exp="1" + +Here, the value of 'lang' is the language name, which can be found in +*note Supported Languages::. + + Note that the output of the '-var-list-children' command also +includes those expressions, so the '-var-info-expression' command is of +limited use. + +The '-var-info-path-expression' Command +--------------------------------------- + +Synopsis +........ + + -var-info-path-expression NAME + + Returns an expression that can be evaluated in the current context +and will yield the same value that a variable object has. Compare this +with the '-var-info-expression' command, which result can be used only +for UI presentation. Typical use of the '-var-info-path-expression' +command is creating a watchpoint from a variable object. + + This command is currently not valid for children of a dynamic varobj, +and will give an error when invoked on one. + + For example, suppose 'C' is a C++ class, derived from class 'Base', +and that the 'Base' class has a member called 'm_size'. Assume a +variable 'c' is has the type of 'C' and a variable object 'C' was +created for variable 'c'. Then, we'll get this output: + (gdb) -var-info-path-expression C.Base.public.m_size + ^done,path_expr=((Base)c).m_size) + +The '-var-show-attributes' Command +---------------------------------- + +Synopsis +........ + + -var-show-attributes NAME + + List attributes of the specified variable object NAME: + + status=ATTR [ ( ,ATTR )* ] + +where ATTR is '{ { editable | noneditable } | TBD }'. + +The '-var-evaluate-expression' Command +-------------------------------------- + +Synopsis +........ + + -var-evaluate-expression [-f FORMAT-SPEC] NAME + + Evaluates the expression that is represented by the specified +variable object and returns its value as a string. The format of the +string can be specified with the '-f' option. The possible values of +this option are the same as for '-var-set-format' (*note +-var-set-format::). If the '-f' option is not specified, the current +display format will be used. The current display format can be changed +using the '-var-set-format' command. + + value=VALUE + + Note that one must invoke '-var-list-children' for a variable before +the value of a child variable can be evaluated. + +The '-var-assign' Command +------------------------- + +Synopsis +........ + + -var-assign NAME EXPRESSION + + Assigns the value of EXPRESSION to the variable object specified by +NAME. The object must be 'editable'. If the variable's value is +altered by the assign, the variable will show up in any subsequent +'-var-update' list. + +Example +....... + + (gdb) + -var-assign var1 3 + ^done,value="3" + (gdb) + -var-update * + ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] + (gdb) + +The '-var-update' Command +------------------------- + +Synopsis +........ + + -var-update [PRINT-VALUES] {NAME | "*"} + + Reevaluate the expressions corresponding to the variable object NAME +and all its direct and indirect children, and return the list of +variable objects whose values have changed; NAME must be a root variable +object. Here, "changed" means that the result of +'-var-evaluate-expression' before and after the '-var-update' is +different. If '*' is used as the variable object names, all existing +variable objects are updated, except for frozen ones (*note +-var-set-frozen::). The option PRINT-VALUES determines whether both +names and values, or just names are printed. The possible values of +this option are the same as for '-var-list-children' (*note +-var-list-children::). It is recommended to use the '--all-values' +option, to reduce the number of MI commands needed on each program stop. + + With the '*' parameter, if a variable object is bound to a currently +running thread, it will not be updated, without any diagnostic. + + If '-var-set-update-range' was previously used on a varobj, then only +the selected range of children will be reported. + + '-var-update' reports all the changed varobjs in a tuple named +'changelist'. + + Each item in the change list is itself a tuple holding: + +'name' + The name of the varobj. + +'value' + If values were requested for this update, then this field will be + present and will hold the value of the varobj. + +'in_scope' + This field is a string which may take one of three values: + + '"true"' + The variable object's current value is valid. + + '"false"' + The variable object does not currently hold a valid value but + it may hold one in the future if its associated expression + comes back into scope. + + '"invalid"' + The variable object no longer holds a valid value. This can + occur when the executable file being debugged has changed, + either through recompilation or by using the GDB 'file' + command. The front end should normally choose to delete these + variable objects. + + In the future new values may be added to this list so the front + should be prepared for this possibility. *Note GDB/MI Development + and Front Ends: GDB/MI Development and Front Ends. + +'type_changed' + This is only present if the varobj is still valid. If the type + changed, then this will be the string 'true'; otherwise it will be + 'false'. + + When a varobj's type changes, its children are also likely to have + become incorrect. Therefore, the varobj's children are + automatically deleted when this attribute is 'true'. Also, the + varobj's update range, when set using the '-var-set-update-range' + command, is unset. + +'new_type' + If the varobj's type changed, then this field will be present and + will hold the new type. + +'new_num_children' + For a dynamic varobj, if the number of children changed, or if the + type changed, this will be the new number of children. + + The 'numchild' field in other varobj responses is generally not + valid for a dynamic varobj - it will show the number of children + that GDB knows about, but because dynamic varobjs lazily + instantiate their children, this will not reflect the number of + children which may be available. + + The 'new_num_children' attribute only reports changes to the number + of children known by GDB. This is the only way to detect whether + an update has removed children (which necessarily can only happen + at the end of the update range). + +'displayhint' + The display hint, if any. + +'has_more' + This is an integer value, which will be 1 if there are more + children available outside the varobj's update range. + +'dynamic' + This attribute will be present and have the value '1' if the varobj + is a dynamic varobj. If the varobj is not a dynamic varobj, then + this attribute will not be present. + +'new_children' + If new children were added to a dynamic varobj within the selected + update range (as set by '-var-set-update-range'), then they will be + listed in this attribute. + +Example +....... + + (gdb) + -var-assign var1 3 + ^done,value="3" + (gdb) + -var-update --all-values var1 + ^done,changelist=[{name="var1",value="3",in_scope="true", + type_changed="false"}] + (gdb) + +The '-var-set-frozen' Command +----------------------------- + +Synopsis +........ + + -var-set-frozen NAME FLAG + + Set the frozenness flag on the variable object NAME. The FLAG +parameter should be either '1' to make the variable frozen or '0' to +make it unfrozen. If a variable object is frozen, then neither itself, +nor any of its children, are implicitly updated by '-var-update' of a +parent variable or by '-var-update *'. Only '-var-update' of the +variable itself will update its value and values of its children. After +a variable object is unfrozen, it is implicitly updated by all +subsequent '-var-update' operations. Unfreezing a variable does not +update it, only subsequent '-var-update' does. + +Example +....... + + (gdb) + -var-set-frozen V 1 + ^done + (gdb) + +The '-var-set-update-range' command +----------------------------------- + +Synopsis +........ + + -var-set-update-range NAME FROM TO + + Set the range of children to be returned by future invocations of +'-var-update'. + + FROM and TO indicate the range of children to report. If FROM or TO +is less than zero, the range is reset and all children will be reported. +Otherwise, children starting at FROM (zero-based) and up to and +excluding TO will be reported. + +Example +....... + + (gdb) + -var-set-update-range V 1 2 + ^done + +The '-var-set-visualizer' command +--------------------------------- + +Synopsis +........ + + -var-set-visualizer NAME VISUALIZER + + Set a visualizer for the variable object NAME. + + VISUALIZER is the visualizer to use. The special value 'None' means +to disable any visualizer in use. + + If not 'None', VISUALIZER must be a Python expression. This +expression must evaluate to a callable object which accepts a single +argument. GDB will call this object with the value of the varobj NAME +as an argument (this is done so that the same Python pretty-printing +code can be used for both the CLI and MI). When called, this object must +return an object which conforms to the pretty-printing interface (*note +Pretty Printing API::). + + The pre-defined function 'gdb.default_visualizer' may be used to +select a visualizer by following the built-in process (*note Selecting +Pretty-Printers::). This is done automatically when a varobj is +created, and so ordinarily is not needed. + + This feature is only available if Python support is enabled. The MI +command '-list-features' (*note GDB/MI Support Commands::) can be used +to check this. + +Example +....... + +Resetting the visualizer: + + (gdb) + -var-set-visualizer V None + ^done + + Reselecting the default (type-based) visualizer: + + (gdb) + -var-set-visualizer V gdb.default_visualizer + ^done + + Suppose 'SomeClass' is a visualizer class. A lambda expression can +be used to instantiate this class for a varobj: + + (gdb) + -var-set-visualizer V "lambda val: SomeClass()" + ^done + + +File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI + +27.16 GDB/MI Data Manipulation +============================== + +This section describes the GDB/MI commands that manipulate data: examine +memory and registers, evaluate expressions, etc. + +The '-data-disassemble' Command +------------------------------- + +Synopsis +........ + + -data-disassemble + [ -s START-ADDR -e END-ADDR ] + | [ -f FILENAME -l LINENUM [ -n LINES ] ] + -- MODE + +Where: + +'START-ADDR' + is the beginning address (or '$pc') +'END-ADDR' + is the end address +'FILENAME' + is the name of the file to disassemble +'LINENUM' + is the line number to disassemble around +'LINES' + is the number of disassembly lines to be produced. If it is -1, + the whole function will be disassembled, in case no END-ADDR is + specified. If END-ADDR is specified as a non-zero value, and LINES + is lower than the number of disassembly lines between START-ADDR + and END-ADDR, only LINES lines are displayed; if LINES is higher + than the number of lines between START-ADDR and END-ADDR, only the + lines up to END-ADDR are displayed. +'MODE' + is either 0 (meaning only disassembly), 1 (meaning mixed source and + disassembly), 2 (meaning disassembly with raw opcodes), or 3 + (meaning mixed source and disassembly with raw opcodes). + +Result +...... + +The result of the '-data-disassemble' command will be a list named +'asm_insns', the contents of this list depend on the MODE used with the +'-data-disassemble' command. + + For modes 0 and 2 the 'asm_insns' list contains tuples with the +following fields: + +'address' + The address at which this instruction was disassembled. + +'func-name' + The name of the function this instruction is within. + +'offset' + The decimal offset in bytes from the start of 'func-name'. + +'inst' + The text disassembly for this 'address'. + +'opcodes' + This field is only present for mode 2. This contains the raw + opcode bytes for the 'inst' field. + + For modes 1 and 3 the 'asm_insns' list contains tuples named +'src_and_asm_line', each of which has the following fields: + +'line' + The line number within 'file'. + +'file' + The file name from the compilation unit. This might be an absolute + file name or a relative file name depending on the compile command + used. + +'fullname' + Absolute file name of 'file'. It is converted to a canonical form + using the source file search path (*note Specifying Source + Directories: Source Path.) and after resolving all the symbolic + links. + + If the source file is not found this field will contain the path as + present in the debug information. + +'line_asm_insn' + This is a list of tuples containing the disassembly for 'line' in + 'file'. The fields of each tuple are the same as for + '-data-disassemble' in MODE 0 and 2, so 'address', 'func-name', + 'offset', 'inst', and optionally 'opcodes'. + + Note that whatever included in the 'inst' field, is not manipulated +directly by GDB/MI, i.e., it is not possible to adjust its format. + +GDB Command +........... + +The corresponding GDB command is 'disassemble'. + +Example +....... + +Disassemble from the current value of '$pc' to '$pc + 20': + + (gdb) + -data-disassemble -s $pc -e "$pc + 20" -- 0 + ^done, + asm_insns=[ + {address="0x000107c0",func-name="main",offset="4", + inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}, + {address="0x000107c8",func-name="main",offset="12", + inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, + {address="0x000107cc",func-name="main",offset="16", + inst="sethi %hi(0x11800), %o2"}, + {address="0x000107d0",func-name="main",offset="20", + inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] + (gdb) + + Disassemble the whole 'main' function. Line 32 is part of 'main'. + + -data-disassemble -f basics.c -l 32 -- 0 + ^done,asm_insns=[ + {address="0x000107bc",func-name="main",offset="0", + inst="save %sp, -112, %sp"}, + {address="0x000107c0",func-name="main",offset="4", + inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}, + [...] + {address="0x0001081c",func-name="main",offset="96",inst="ret "}, + {address="0x00010820",func-name="main",offset="100",inst="restore "}] + (gdb) + + Disassemble 3 instructions from the start of 'main': + + (gdb) + -data-disassemble -f basics.c -l 32 -n 3 -- 0 + ^done,asm_insns=[ + {address="0x000107bc",func-name="main",offset="0", + inst="save %sp, -112, %sp"}, + {address="0x000107c0",func-name="main",offset="4", + inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}] + (gdb) + + Disassemble 3 instructions from the start of 'main' in mixed mode: + + (gdb) + -data-disassemble -f basics.c -l 32 -n 3 -- 1 + ^done,asm_insns=[ + src_and_asm_line={line="31", + file="../../../src/gdb/testsuite/gdb.mi/basics.c", + fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", + line_asm_insn=[{address="0x000107bc", + func-name="main",offset="0",inst="save %sp, -112, %sp"}]}, + src_and_asm_line={line="32", + file="../../../src/gdb/testsuite/gdb.mi/basics.c", + fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", + line_asm_insn=[{address="0x000107c0", + func-name="main",offset="4",inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}]}] + (gdb) + +The '-data-evaluate-expression' Command +--------------------------------------- + +Synopsis +........ + + -data-evaluate-expression EXPR + + Evaluate EXPR as an expression. The expression could contain an +inferior function call. The function call will execute synchronously. +If the expression contains spaces, it must be enclosed in double quotes. + +GDB Command +........... + +The corresponding GDB commands are 'print', 'output', and 'call'. In +'gdbtk' only, there's a corresponding 'gdb_eval' command. + +Example +....... + +In the following example, the numbers that precede the commands are the +"tokens" described in *note GDB/MI Command Syntax: GDB/MI Command +Syntax. Notice how GDB/MI returns the same tokens in its output. + + 211-data-evaluate-expression A + 211^done,value="1" + (gdb) + 311-data-evaluate-expression &A + 311^done,value="0xefffeb7c" + (gdb) + 411-data-evaluate-expression A+3 + 411^done,value="4" + (gdb) + 511-data-evaluate-expression "A + 3" + 511^done,value="4" + (gdb) + +The '-data-list-changed-registers' Command +------------------------------------------ + +Synopsis +........ + + -data-list-changed-registers + + Display a list of the registers that have changed. + +GDB Command +........... + +GDB doesn't have a direct analog for this command; 'gdbtk' has the +corresponding command 'gdb_changed_register_list'. + +Example +....... + +On a PPC MBX board: + + (gdb) + -exec-continue + ^running + + (gdb) + *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={ + func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", + line="5"} + (gdb) + -data-list-changed-registers + ^done,changed-registers=["0","1","2","4","5","6","7","8","9", + "10","11","13","14","15","16","17","18","19","20","21","22","23", + "24","25","26","27","28","30","31","64","65","66","67","69"] + (gdb) + +The '-data-list-register-names' Command +--------------------------------------- + +Synopsis +........ + + -data-list-register-names [ ( REGNO )+ ] + + Show a list of register names for the current target. If no +arguments are given, it shows a list of the names of all the registers. +If integer numbers are given as arguments, it will print a list of the +names of the registers corresponding to the arguments. To ensure +consistency between a register name and its number, the output list may +include empty register names. + +GDB Command +........... + +GDB does not have a command which corresponds to +'-data-list-register-names'. In 'gdbtk' there is a corresponding +command 'gdb_regnames'. + +Example +....... + +For the PPC MBX board: + (gdb) + -data-list-register-names + ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", + "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", + "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", + "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", + "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", + "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", + "", "pc","ps","cr","lr","ctr","xer"] + (gdb) + -data-list-register-names 1 2 3 + ^done,register-names=["r1","r2","r3"] + (gdb) + +The '-data-list-register-values' Command +---------------------------------------- + +Synopsis +........ + + -data-list-register-values + [ --skip-unavailable ] FMT [ ( REGNO )*] + + Display the registers' contents. FMT is the format according to +which the registers' contents are to be returned, followed by an +optional list of numbers specifying the registers to display. A missing +list of numbers indicates that the contents of all the registers must be +returned. The '--skip-unavailable' option indicates that only the +available registers are to be returned. + + Allowed formats for FMT are: + +'x' + Hexadecimal +'o' + Octal +'t' + Binary +'d' + Decimal +'r' + Raw +'N' + Natural + +GDB Command +........... + +The corresponding GDB commands are 'info reg', 'info all-reg', and (in +'gdbtk') 'gdb_fetch_registers'. + +Example +....... + +For a PPC MBX board (note: line breaks are for readability only, they +don't appear in the actual output): + + (gdb) + -data-list-register-values r 64 65 + ^done,register-values=[{number="64",value="0xfe00a300"}, + {number="65",value="0x00029002"}] + (gdb) + -data-list-register-values x + ^done,register-values=[{number="0",value="0xfe0043c8"}, + {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, + {number="3",value="0x0"},{number="4",value="0xa"}, + {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, + {number="7",value="0xfe011e98"},{number="8",value="0x2"}, + {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, + {number="11",value="0x1"},{number="12",value="0x0"}, + {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, + {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, + {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, + {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, + {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, + {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, + {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, + {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, + {number="29",value="0x0"},{number="30",value="0xfe010000"}, + {number="31",value="0x0"},{number="32",value="0x0"}, + {number="33",value="0x0"},{number="34",value="0x0"}, + {number="35",value="0x0"},{number="36",value="0x0"}, + {number="37",value="0x0"},{number="38",value="0x0"}, + {number="39",value="0x0"},{number="40",value="0x0"}, + {number="41",value="0x0"},{number="42",value="0x0"}, + {number="43",value="0x0"},{number="44",value="0x0"}, + {number="45",value="0x0"},{number="46",value="0x0"}, + {number="47",value="0x0"},{number="48",value="0x0"}, + {number="49",value="0x0"},{number="50",value="0x0"}, + {number="51",value="0x0"},{number="52",value="0x0"}, + {number="53",value="0x0"},{number="54",value="0x0"}, + {number="55",value="0x0"},{number="56",value="0x0"}, + {number="57",value="0x0"},{number="58",value="0x0"}, + {number="59",value="0x0"},{number="60",value="0x0"}, + {number="61",value="0x0"},{number="62",value="0x0"}, + {number="63",value="0x0"},{number="64",value="0xfe00a300"}, + {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, + {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, + {number="69",value="0x20002b03"}] + (gdb) + +The '-data-read-memory' Command +------------------------------- + +This command is deprecated, use '-data-read-memory-bytes' instead. + +Synopsis +........ + + -data-read-memory [ -o BYTE-OFFSET ] + ADDRESS WORD-FORMAT WORD-SIZE + NR-ROWS NR-COLS [ ASCHAR ] + +where: + +'ADDRESS' + An expression specifying the address of the first memory word to be + read. Complex expressions containing embedded white space should + be quoted using the C convention. + +'WORD-FORMAT' + The format to be used to print the memory words. The notation is + the same as for GDB's 'print' command (*note Output Formats: Output + Formats.). + +'WORD-SIZE' + The size of each memory word in bytes. + +'NR-ROWS' + The number of rows in the output table. + +'NR-COLS' + The number of columns in the output table. + +'ASCHAR' + If present, indicates that each row should include an ASCII dump. + The value of ASCHAR is used as a padding character when a byte is + not a member of the printable ASCII character set (printable ASCII + characters are those whose code is between 32 and 126, + inclusively). + +'BYTE-OFFSET' + An offset to add to the ADDRESS before fetching memory. + + This command displays memory contents as a table of NR-ROWS by +NR-COLS words, each word being WORD-SIZE bytes. In total, 'NR-ROWS * +NR-COLS * WORD-SIZE' bytes are read (returned as 'total-bytes'). Should +less than the requested number of bytes be returned by the target, the +missing words are identified using 'N/A'. The number of bytes read from +the target is returned in 'nr-bytes' and the starting address used to +read memory in 'addr'. + + The address of the next/previous row or page is available in +'next-row' and 'prev-row', 'next-page' and 'prev-page'. + +GDB Command +........... + +The corresponding GDB command is 'x'. 'gdbtk' has 'gdb_get_mem' memory +read command. + +Example +....... + +Read six bytes of memory starting at 'bytes+6' but then offset by '-6' +bytes. Format as three rows of two columns. One byte per word. +Display each word in hex. + + (gdb) + 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 + 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", + next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", + prev-page="0x0000138a",memory=[ + {addr="0x00001390",data=["0x00","0x01"]}, + {addr="0x00001392",data=["0x02","0x03"]}, + {addr="0x00001394",data=["0x04","0x05"]}] + (gdb) + + Read two bytes of memory starting at address 'shorts + 64' and +display as a single word formatted in decimal. + + (gdb) + 5-data-read-memory shorts+64 d 2 1 1 + 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", + next-row="0x00001512",prev-row="0x0000150e", + next-page="0x00001512",prev-page="0x0000150e",memory=[ + {addr="0x00001510",data=["128"]}] + (gdb) + + Read thirty two bytes of memory starting at 'bytes+16' and format as +eight rows of four columns. Include a string encoding with 'x' used as +the non-printable character. + + (gdb) + 4-data-read-memory bytes+16 x 1 8 4 x + 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", + next-row="0x000013c0",prev-row="0x0000139c", + next-page="0x000013c0",prev-page="0x00001380",memory=[ + {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, + {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, + {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, + {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, + {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, + {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, + {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, + {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] + (gdb) + +The '-data-read-memory-bytes' Command +------------------------------------- + +Synopsis +........ + + -data-read-memory-bytes [ -o BYTE-OFFSET ] + ADDRESS COUNT + +where: + +'ADDRESS' + An expression specifying the address of the first memory word to be + read. Complex expressions containing embedded white space should + be quoted using the C convention. + +'COUNT' + The number of bytes to read. This should be an integer literal. + +'BYTE-OFFSET' + The offsets in bytes relative to ADDRESS at which to start reading. + This should be an integer literal. This option is provided so that + a frontend is not required to first evaluate address and then + perform address arithmetics itself. + + This command attempts to read all accessible memory regions in the +specified range. First, all regions marked as unreadable in the memory +map (if one is defined) will be skipped. *Note Memory Region +Attributes::. Second, GDB will attempt to read the remaining regions. +For each one, if reading full region results in an errors, GDB will try +to read a subset of the region. + + In general, every single byte in the region may be readable or not, +and the only way to read every readable byte is to try a read at every +address, which is not practical. Therefore, GDB will attempt to read +all accessible bytes at either beginning or the end of the region, using +a binary division scheme. This heuristic works well for reading accross +a memory map boundary. Note that if a region has a readable range that +is neither at the beginning or the end, GDB will not read it. + + The result record (*note GDB/MI Result Records::) that is output of +the command includes a field named 'memory' whose content is a list of +tuples. Each tuple represent a successfully read memory block and has +the following fields: + +'begin' + The start address of the memory block, as hexadecimal literal. + +'end' + The end address of the memory block, as hexadecimal literal. + +'offset' + The offset of the memory block, as hexadecimal literal, relative to + the start address passed to '-data-read-memory-bytes'. + +'contents' + The contents of the memory block, in hex. + +GDB Command +........... + +The corresponding GDB command is 'x'. + +Example +....... + + (gdb) + -data-read-memory-bytes &a 10 + ^done,memory=[{begin="0xbffff154",offset="0x00000000", + end="0xbffff15e", + contents="01000000020000000300"}] + (gdb) + +The '-data-write-memory-bytes' Command +-------------------------------------- + +Synopsis +........ + + -data-write-memory-bytes ADDRESS CONTENTS + -data-write-memory-bytes ADDRESS CONTENTS [COUNT] + +where: + +'ADDRESS' + An expression specifying the address of the first memory word to be + read. Complex expressions containing embedded white space should + be quoted using the C convention. + +'CONTENTS' + The hex-encoded bytes to write. + +'COUNT' + Optional argument indicating the number of bytes to be written. If + COUNT is greater than CONTENTS' length, GDB will repeatedly write + CONTENTS until it fills COUNT bytes. + +GDB Command +........... + +There's no corresponding GDB command. + +Example +....... + + (gdb) + -data-write-memory-bytes &a "aabbccdd" + ^done + (gdb) + + (gdb) + -data-write-memory-bytes &a "aabbccdd" 16e + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI + +27.17 GDB/MI Tracepoint Commands +================================ + +The commands defined in this section implement MI support for +tracepoints. For detailed introduction, see *note Tracepoints::. + +The '-trace-find' Command +------------------------- + +Synopsis +........ + + -trace-find MODE [PARAMETERS...] + + Find a trace frame using criteria defined by MODE and PARAMETERS. +The following table lists permissible modes and their parameters. For +details of operation, see *note tfind::. + +'none' + No parameters are required. Stops examining trace frames. + +'frame-number' + An integer is required as parameter. Selects tracepoint frame with + that index. + +'tracepoint-number' + An integer is required as parameter. Finds next trace frame that + corresponds to tracepoint with the specified number. + +'pc' + An address is required as parameter. Finds next trace frame that + corresponds to any tracepoint at the specified address. + +'pc-inside-range' + Two addresses are required as parameters. Finds next trace frame + that corresponds to a tracepoint at an address inside the specified + range. Both bounds are considered to be inside the range. + +'pc-outside-range' + Two addresses are required as parameters. Finds next trace frame + that corresponds to a tracepoint at an address outside the + specified range. Both bounds are considered to be inside the + range. + +'line' + Line specification is required as parameter. *Note Specify + Location::. Finds next trace frame that corresponds to a + tracepoint at the specified location. + + If 'none' was passed as MODE, the response does not have fields. +Otherwise, the response may have the following fields: + +'found' + This field has either '0' or '1' as the value, depending on whether + a matching tracepoint was found. + +'traceframe' + The index of the found traceframe. This field is present iff the + 'found' field has value of '1'. + +'tracepoint' + The index of the found tracepoint. This field is present iff the + 'found' field has value of '1'. + +'frame' + The information about the frame corresponding to the found trace + frame. This field is present only if a trace frame was found. + *Note GDB/MI Frame Information::, for description of this field. + +GDB Command +........... + +The corresponding GDB command is 'tfind'. + +-trace-define-variable +---------------------- + +Synopsis +........ + + -trace-define-variable NAME [ VALUE ] + + Create trace variable NAME if it does not exist. If VALUE is +specified, sets the initial value of the specified trace variable to +that value. Note that the NAME should start with the '$' character. + +GDB Command +........... + +The corresponding GDB command is 'tvariable'. + +The '-trace-frame-collected' Command +------------------------------------ + +Synopsis +........ + + -trace-frame-collected + [--var-print-values VAR_PVAL] + [--comp-print-values COMP_PVAL] + [--registers-format REGFORMAT] + [--memory-contents] + + This command returns the set of collected objects, register names, +trace state variable names, memory ranges and computed expressions that +have been collected at a particular trace frame. The optional +parameters to the command affect the output format in different ways. +See the output description table below for more details. + + The reported names can be used in the normal manner to create varobjs +and inspect the objects themselves. The items returned by this command +are categorized so that it is clear which is a variable, which is a +register, which is a trace state variable, which is a memory range and +which is a computed expression. + + For instance, if the actions were + collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2 + collect *(int*)0xaf02bef0@40 + +the object collected in its entirety would be 'myVar'. The object +'myArray' would be partially collected, because only the element at +index 'myIndex' would be collected. The remaining objects would be +computed expressions. + + An example output would be: + + (gdb) + -trace-frame-collected + ^done, + explicit-variables=[{name="myVar",value="1"}], + computed-expressions=[{name="myArray[myIndex]",value="0"}, + {name="myObj.field",value="0"}, + {name="myPtr->field",value="1"}, + {name="myCount + 2",value="3"}, + {name="$tvar1 + 1",value="43970027"}], + registers=[{number="0",value="0x7fe2c6e79ec8"}, + {number="1",value="0x0"}, + {number="2",value="0x4"}, + ... + {number="125",value="0x0"}], + tvars=[{name="$tvar1",current="43970026"}], + memory=[{address="0x0000000000602264",length="4"}, + {address="0x0000000000615bc0",length="4"}] + (gdb) + + Where: + +'explicit-variables' + The set of objects that have been collected in their entirety (as + opposed to collecting just a few elements of an array or a few + struct members). For each object, its name and value are printed. + The '--var-print-values' option affects how or whether the value + field is output. If VAR_PVAL is 0, then print only the names; if + it is 1, print also their values; and if it is 2, print the name, + type and value for simple data types, and the name and type for + arrays, structures and unions. + +'computed-expressions' + The set of computed expressions that have been collected at the + current trace frame. The '--comp-print-values' option affects this + set like the '--var-print-values' option affects the + 'explicit-variables' set. See above. + +'registers' + The registers that have been collected at the current trace frame. + For each register collected, the name and current value are + returned. The value is formatted according to the + '--registers-format' option. See the '-data-list-register-values' + command for a list of the allowed formats. The default is 'x'. + +'tvars' + The trace state variables that have been collected at the current + trace frame. For each trace state variable collected, the name and + current value are returned. + +'memory' + The set of memory ranges that have been collected at the current + trace frame. Its content is a list of tuples. Each tuple + represents a collected memory range and has the following fields: + + 'address' + The start address of the memory range, as hexadecimal literal. + + 'length' + The length of the memory range, as decimal literal. + + 'contents' + The contents of the memory block, in hex. This field is only + present if the '--memory-contents' option is specified. + +GDB Command +........... + +There is no corresponding GDB command. + +Example +....... + +-trace-list-variables +--------------------- + +Synopsis +........ + + -trace-list-variables + + Return a table of all defined trace variables. Each element of the +table has the following fields: + +'name' + The name of the trace variable. This field is always present. + +'initial' + The initial value. This is a 64-bit signed integer. This field is + always present. + +'current' + The value the trace variable has at the moment. This is a 64-bit + signed integer. This field is absent iff current value is not + defined, for example if the trace was never run, or is presently + running. + +GDB Command +........... + +The corresponding GDB command is 'tvariables'. + +Example +....... + + (gdb) + -trace-list-variables + ^done,trace-variables={nr_rows="1",nr_cols="3", + hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"}, + {width="11",alignment="-1",col_name="initial",colhdr="Initial"}, + {width="11",alignment="-1",col_name="current",colhdr="Current"}], + body=[variable={name="$trace_timestamp",initial="0"} + variable={name="$foo",initial="10",current="15"}]} + (gdb) + +-trace-save +----------- + +Synopsis +........ + + -trace-save [-r ] FILENAME + + Saves the collected trace data to FILENAME. Without the '-r' option, +the data is downloaded from the target and saved in a local file. With +the '-r' option the target is asked to perform the save. + +GDB Command +........... + +The corresponding GDB command is 'tsave'. + +-trace-start +------------ + +Synopsis +........ + + -trace-start + + Starts a tracing experiments. The result of this command does not +have any fields. + +GDB Command +........... + +The corresponding GDB command is 'tstart'. + +-trace-status +------------- + +Synopsis +........ + + -trace-status + + Obtains the status of a tracing experiment. The result may include +the following fields: + +'supported' + May have a value of either '0', when no tracing operations are + supported, '1', when all tracing operations are supported, or + 'file' when examining trace file. In the latter case, examining of + trace frame is possible but new tracing experiement cannot be + started. This field is always present. + +'running' + May have a value of either '0' or '1' depending on whether tracing + experiement is in progress on target. This field is present if + 'supported' field is not '0'. + +'stop-reason' + Report the reason why the tracing was stopped last time. This + field may be absent iff tracing was never stopped on target yet. + The value of 'request' means the tracing was stopped as result of + the '-trace-stop' command. The value of 'overflow' means the + tracing buffer is full. The value of 'disconnection' means tracing + was automatically stopped when GDB has disconnected. The value of + 'passcount' means tracing was stopped when a tracepoint was passed + a maximal number of times for that tracepoint. This field is + present if 'supported' field is not '0'. + +'stopping-tracepoint' + The number of tracepoint whose passcount as exceeded. This field + is present iff the 'stop-reason' field has the value of + 'passcount'. + +'frames' +'frames-created' + The 'frames' field is a count of the total number of trace frames + in the trace buffer, while 'frames-created' is the total created + during the run, including ones that were discarded, such as when a + circular trace buffer filled up. Both fields are optional. + +'buffer-size' +'buffer-free' + These fields tell the current size of the tracing buffer and the + remaining space. These fields are optional. + +'circular' + The value of the circular trace buffer flag. '1' means that the + trace buffer is circular and old trace frames will be discarded if + necessary to make room, '0' means that the trace buffer is linear + and may fill up. + +'disconnected' + The value of the disconnected tracing flag. '1' means that tracing + will continue after GDB disconnects, '0' means that the trace run + will stop. + +'trace-file' + The filename of the trace file being examined. This field is + optional, and only present when examining a trace file. + +GDB Command +........... + +The corresponding GDB command is 'tstatus'. + +-trace-stop +----------- + +Synopsis +........ + + -trace-stop + + Stops a tracing experiment. The result of this command has the same +fields as '-trace-status', except that the 'supported' and 'running' +fields are not output. + +GDB Command +........... + +The corresponding GDB command is 'tstop'. + + +File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI + +27.18 GDB/MI Symbol Query Commands +================================== + +The '-symbol-list-lines' Command +-------------------------------- + +Synopsis +........ + + -symbol-list-lines FILENAME + + Print the list of lines that contain code and their associated +program addresses for the given source filename. The entries are sorted +in ascending PC order. + +GDB Command +........... + +There is no corresponding GDB command. + +Example +....... + + (gdb) + -symbol-list-lines basics.c + ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] + (gdb) + + +File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI + +27.19 GDB/MI File Commands +========================== + +This section describes the GDB/MI commands to specify executable file +names and to read in and obtain symbol table information. + +The '-file-exec-and-symbols' Command +------------------------------------ + +Synopsis +........ + + -file-exec-and-symbols FILE + + Specify the executable file to be debugged. This file is the one +from which the symbol table is also read. If no file is specified, the +command clears the executable and symbol information. If breakpoints +are set when using this command with no arguments, GDB will produce +error messages. Otherwise, no output is produced, except a completion +notification. + +GDB Command +........... + +The corresponding GDB command is 'file'. + +Example +....... + + (gdb) + -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx + ^done + (gdb) + +The '-file-exec-file' Command +----------------------------- + +Synopsis +........ + + -file-exec-file FILE + + Specify the executable file to be debugged. Unlike +'-file-exec-and-symbols', the symbol table is _not_ read from this file. +If used without argument, GDB clears the information about the +executable file. No output is produced, except a completion +notification. + +GDB Command +........... + +The corresponding GDB command is 'exec-file'. + +Example +....... + + (gdb) + -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx + ^done + (gdb) + +The '-file-list-exec-source-file' Command +----------------------------------------- + +Synopsis +........ + + -file-list-exec-source-file + + List the line number, the current source file, and the absolute path +to the current source file for the current executable. The macro +information field has a value of '1' or '0' depending on whether or not +the file includes preprocessor macro information. + +GDB Command +........... + +The GDB equivalent is 'info source' + +Example +....... + + (gdb) + 123-file-list-exec-source-file + 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" + (gdb) + +The '-file-list-exec-source-files' Command +------------------------------------------ + +Synopsis +........ + + -file-list-exec-source-files + + List the source files for the current executable. + + It will always output both the filename and fullname (absolute file +name) of a source file. + +GDB Command +........... + +The GDB equivalent is 'info sources'. 'gdbtk' has an analogous command +'gdb_listfiles'. + +Example +....... + + (gdb) + -file-list-exec-source-files + ^done,files=[ + {file=foo.c,fullname=/home/foo.c}, + {file=/home/bar.c,fullname=/home/bar.c}, + {file=gdb_could_not_find_fullpath.c}] + (gdb) + +The '-file-symbol-file' Command +------------------------------- + +Synopsis +........ + + -file-symbol-file FILE + + Read symbol table info from the specified FILE argument. When used +without arguments, clears GDB's symbol table info. No output is +produced, except for a completion notification. + +GDB Command +........... + +The corresponding GDB command is 'symbol-file'. + +Example +....... + + (gdb) + -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI + +27.20 GDB/MI Target Manipulation Commands +========================================= + +The '-target-attach' Command +---------------------------- + +Synopsis +........ + + -target-attach PID | GID | FILE + + Attach to a process PID or a file FILE outside of GDB, or a thread +group GID. If attaching to a thread group, the id previously returned +by '-list-thread-groups --available' must be used. + +GDB Command +........... + +The corresponding GDB command is 'attach'. + +Example +....... + + (gdb) + -target-attach 34 + =thread-created,id="1" + *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]} + ^done + (gdb) + +The '-target-detach' Command +---------------------------- + +Synopsis +........ + + -target-detach [ PID | GID ] + + Detach from the remote target which normally resumes its execution. +If either PID or GID is specified, detaches from either the specified +process, or specified thread group. There's no output. + +GDB Command +........... + +The corresponding GDB command is 'detach'. + +Example +....... + + (gdb) + -target-detach + ^done + (gdb) + +The '-target-disconnect' Command +-------------------------------- + +Synopsis +........ + + -target-disconnect + + Disconnect from the remote target. There's no output and the target +is generally not resumed. + +GDB Command +........... + +The corresponding GDB command is 'disconnect'. + +Example +....... + + (gdb) + -target-disconnect + ^done + (gdb) + +The '-target-download' Command +------------------------------ + +Synopsis +........ + + -target-download + + Loads the executable onto the remote target. It prints out an update +message every half second, which includes the fields: + +'section' + The name of the section. +'section-sent' + The size of what has been sent so far for that section. +'section-size' + The size of the section. +'total-sent' + The total size of what was sent so far (the current and the + previous sections). +'total-size' + The size of the overall executable to download. + +Each message is sent as status record (*note GDB/MI Output Syntax: +GDB/MI Output Syntax.). + + In addition, it prints the name and size of the sections, as they are +downloaded. These messages include the following fields: + +'section' + The name of the section. +'section-size' + The size of the section. +'total-size' + The size of the overall executable to download. + +At the end, a summary is printed. + +GDB Command +........... + +The corresponding GDB command is 'load'. + +Example +....... + +Note: each status message appears on a single line. Here the messages +have been broken down so that they can fit onto a page. + + (gdb) + -target-download + +download,{section=".text",section-size="6668",total-size="9880"} + +download,{section=".text",section-sent="512",section-size="6668", + total-sent="512",total-size="9880"} + +download,{section=".text",section-sent="1024",section-size="6668", + total-sent="1024",total-size="9880"} + +download,{section=".text",section-sent="1536",section-size="6668", + total-sent="1536",total-size="9880"} + +download,{section=".text",section-sent="2048",section-size="6668", + total-sent="2048",total-size="9880"} + +download,{section=".text",section-sent="2560",section-size="6668", + total-sent="2560",total-size="9880"} + +download,{section=".text",section-sent="3072",section-size="6668", + total-sent="3072",total-size="9880"} + +download,{section=".text",section-sent="3584",section-size="6668", + total-sent="3584",total-size="9880"} + +download,{section=".text",section-sent="4096",section-size="6668", + total-sent="4096",total-size="9880"} + +download,{section=".text",section-sent="4608",section-size="6668", + total-sent="4608",total-size="9880"} + +download,{section=".text",section-sent="5120",section-size="6668", + total-sent="5120",total-size="9880"} + +download,{section=".text",section-sent="5632",section-size="6668", + total-sent="5632",total-size="9880"} + +download,{section=".text",section-sent="6144",section-size="6668", + total-sent="6144",total-size="9880"} + +download,{section=".text",section-sent="6656",section-size="6668", + total-sent="6656",total-size="9880"} + +download,{section=".init",section-size="28",total-size="9880"} + +download,{section=".fini",section-size="28",total-size="9880"} + +download,{section=".data",section-size="3156",total-size="9880"} + +download,{section=".data",section-sent="512",section-size="3156", + total-sent="7236",total-size="9880"} + +download,{section=".data",section-sent="1024",section-size="3156", + total-sent="7748",total-size="9880"} + +download,{section=".data",section-sent="1536",section-size="3156", + total-sent="8260",total-size="9880"} + +download,{section=".data",section-sent="2048",section-size="3156", + total-sent="8772",total-size="9880"} + +download,{section=".data",section-sent="2560",section-size="3156", + total-sent="9284",total-size="9880"} + +download,{section=".data",section-sent="3072",section-size="3156", + total-sent="9796",total-size="9880"} + ^done,address="0x10004",load-size="9880",transfer-rate="6586", + write-rate="429" + (gdb) + +GDB Command +........... + +No equivalent. + +Example +....... + +N.A. + +The '-target-select' Command +---------------------------- + +Synopsis +........ + + -target-select TYPE PARAMETERS ... + + Connect GDB to the remote target. This command takes two args: + +'TYPE' + The type of target, for instance 'remote', etc. +'PARAMETERS' + Device names, host names and the like. *Note Commands for Managing + Targets: Target Commands, for more details. + + The output is a connection notification, followed by the address at +which the target program is, in the following form: + + ^connected,addr="ADDRESS",func="FUNCTION NAME", + args=[ARG LIST] + +GDB Command +........... + +The corresponding GDB command is 'target'. + +Example +....... + + (gdb) + -target-select remote /dev/ttya + ^connected,addr="0xfe00a300",func="??",args=[] + (gdb) + + +File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Ada Exceptions Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI + +27.21 GDB/MI File Transfer Commands +=================================== + +The '-target-file-put' Command +------------------------------ + +Synopsis +........ + + -target-file-put HOSTFILE TARGETFILE + + Copy file HOSTFILE from the host system (the machine running GDB) to +TARGETFILE on the target system. + +GDB Command +........... + +The corresponding GDB command is 'remote put'. + +Example +....... + + (gdb) + -target-file-put localfile remotefile + ^done + (gdb) + +The '-target-file-get' Command +------------------------------ + +Synopsis +........ + + -target-file-get TARGETFILE HOSTFILE + + Copy file TARGETFILE from the target system to HOSTFILE on the host +system. + +GDB Command +........... + +The corresponding GDB command is 'remote get'. + +Example +....... + + (gdb) + -target-file-get remotefile localfile + ^done + (gdb) + +The '-target-file-delete' Command +--------------------------------- + +Synopsis +........ + + -target-file-delete TARGETFILE + + Delete TARGETFILE from the target system. + +GDB Command +........... + +The corresponding GDB command is 'remote delete'. + +Example +....... + + (gdb) + -target-file-delete remotefile + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Ada Exceptions Commands, Next: GDB/MI Support Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI + +27.22 Ada Exceptions GDB/MI Commands +==================================== + +The '-info-ada-exceptions' Command +---------------------------------- + +Synopsis +........ + + -info-ada-exceptions [ REGEXP] + + List all Ada exceptions defined within the program being debugged. +With a regular expression REGEXP, only those exceptions whose names +match REGEXP are listed. + +GDB Command +........... + +The corresponding GDB command is 'info exceptions'. + +Result +...... + +The result is a table of Ada exceptions. The following columns are +defined for each exception: + +'name' + The name of the exception. + +'address' + The address of the exception. + +Example +....... + + -info-ada-exceptions aint + ^done,ada-exceptions={nr_rows="2",nr_cols="2", + hdr=[{width="1",alignment="-1",col_name="name",colhdr="Name"}, + {width="1",alignment="-1",col_name="address",colhdr="Address"}], + body=[{name="constraint_error",address="0x0000000000613da0"}, + {name="const.aint_global_e",address="0x0000000000613b00"}]} + +Catching Ada Exceptions +----------------------- + +The commands describing how to ask GDB to stop when a program raises an +exception are described at *note Ada Exception GDB/MI Catchpoint +Commands::. + + +File: gdb.info, Node: GDB/MI Support Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Ada Exceptions Commands, Up: GDB/MI + +27.23 GDB/MI Support Commands +============================= + +Since new commands and features get regularly added to GDB/MI, some +commands are available to help front-ends query the debugger about +support for these capabilities. Similarly, it is also possible to query +GDB about target support of certain features. + +The '-info-gdb-mi-command' Command +---------------------------------- + +Synopsis +........ + + -info-gdb-mi-command CMD_NAME + + Query support for the GDB/MI command named CMD_NAME. + + Note that the dash ('-') starting all GDB/MI commands is technically +not part of the command name (*note GDB/MI Input Syntax::), and thus +should be omitted in CMD_NAME. However, for ease of use, this command +also accepts the form with the leading dash. + +GDB Command +........... + +There is no corresponding GDB command. + +Result +...... + +The result is a tuple. There is currently only one field: + +'exists' + This field is equal to '"true"' if the GDB/MI command exists, + '"false"' otherwise. + +Example +....... + +Here is an example where the GDB/MI command does not exist: + + -info-gdb-mi-command unsupported-command + ^done,command={exists="false"} + +And here is an example where the GDB/MI command is known to the +debugger: + + -info-gdb-mi-command symbol-list-lines + ^done,command={exists="true"} + +The '-list-features' Command +---------------------------- + +Returns a list of particular features of the MI protocol that this +version of gdb implements. A feature can be a command, or a new field +in an output of some command, or even an important bugfix. While a +frontend can sometimes detect presence of a feature at runtime, it is +easier to perform detection at debugger startup. + + The command returns a list of strings, with each string naming an +available feature. Each returned string is just a name, it does not +have any internal structure. The list of possible feature names is +given below. + + Example output: + + (gdb) -list-features + ^done,result=["feature1","feature2"] + + The current list of features is: + +'frozen-varobjs' + Indicates support for the '-var-set-frozen' command, as well as + possible presense of the 'frozen' field in the output of + '-varobj-create'. +'pending-breakpoints' + Indicates support for the '-f' option to the '-break-insert' + command. +'python' + Indicates Python scripting support, Python-based pretty-printing + commands, and possible presence of the 'display_hint' field in the + output of '-var-list-children' +'thread-info' + Indicates support for the '-thread-info' command. +'data-read-memory-bytes' + Indicates support for the '-data-read-memory-bytes' and the + '-data-write-memory-bytes' commands. +'breakpoint-notifications' + Indicates that changes to breakpoints and breakpoints created via + the CLI will be announced via async records. +'ada-task-info' + Indicates support for the '-ada-task-info' command. +'language-option' + Indicates that all GDB/MI commands accept the '--language' option + (*note Context management::). +'info-gdb-mi-command' + Indicates support for the '-info-gdb-mi-command' command. +'undefined-command-error-code' + Indicates support for the "undefined-command" error code in error + result records, produced when trying to execute an undefined GDB/MI + command (*note GDB/MI Result Records::). +'exec-run-start-option' + Indicates that the '-exec-run' command supports the '--start' + option (*note GDB/MI Program Execution::). + +The '-list-target-features' Command +----------------------------------- + +Returns a list of particular features that are supported by the target. +Those features affect the permitted MI commands, but unlike the features +reported by the '-list-features' command, the features depend on which +target GDB is using at the moment. Whenever a target can change, due to +commands such as '-target-select', '-target-attach' or '-exec-run', the +list of target features may change, and the frontend should obtain it +again. Example output: + + (gdb) -list-target-features + ^done,result=["async"] + + The current list of features is: + +'async' + Indicates that the target is capable of asynchronous command + execution, which means that GDB will accept further commands while + the target is running. + +'reverse' + Indicates that the target is capable of reverse execution. *Note + Reverse Execution::, for more information. + + +File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI Support Commands, Up: GDB/MI + +27.24 Miscellaneous GDB/MI Commands +=================================== + +The '-gdb-exit' Command +----------------------- + +Synopsis +........ + + -gdb-exit + + Exit GDB immediately. + +GDB Command +........... + +Approximately corresponds to 'quit'. + +Example +....... + + (gdb) + -gdb-exit + ^exit + +The '-gdb-set' Command +---------------------- + +Synopsis +........ + + -gdb-set + + Set an internal GDB variable. + +GDB Command +........... + +The corresponding GDB command is 'set'. + +Example +....... + + (gdb) + -gdb-set $foo=3 + ^done + (gdb) + +The '-gdb-show' Command +----------------------- + +Synopsis +........ + + -gdb-show + + Show the current value of a GDB variable. + +GDB Command +........... + +The corresponding GDB command is 'show'. + +Example +....... + + (gdb) + -gdb-show annotate + ^done,value="0" + (gdb) + +The '-gdb-version' Command +-------------------------- + +Synopsis +........ + + -gdb-version + + Show version information for GDB. Used mostly in testing. + +GDB Command +........... + +The GDB equivalent is 'show version'. GDB by default shows this +information when you start an interactive session. + +Example +....... + + (gdb) + -gdb-version + ~GNU gdb 5.2.1 + ~Copyright 2000 Free Software Foundation, Inc. + ~GDB is free software, covered by the GNU General Public License, and + ~you are welcome to change it and/or distribute copies of it under + ~ certain conditions. + ~Type "show copying" to see the conditions. + ~There is absolutely no warranty for GDB. Type "show warranty" for + ~ details. + ~This GDB was configured as + "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". + ^done + (gdb) + +The '-list-thread-groups' Command +--------------------------------- + +Synopsis +-------- + + -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ] + + Lists thread groups (*note Thread groups::). When a single thread +group is passed as the argument, lists the children of that group. When +several thread group are passed, lists information about those thread +groups. Without any parameters, lists information about all top-level +thread groups. + + Normally, thread groups that are being debugged are reported. With +the '--available' option, GDB reports thread groups available on the +target. + + The output of this command may have either a 'threads' result or a +'groups' result. The 'thread' result has a list of tuples as value, +with each tuple describing a thread (*note GDB/MI Thread Information::). +The 'groups' result has a list of tuples as value, each tuple describing +a thread group. If top-level groups are requested (that is, no +parameter is passed), or when several groups are passed, the output +always has a 'groups' result. The format of the 'group' result is +described below. + + To reduce the number of roundtrips it's possible to list thread +groups together with their children, by passing the '--recurse' option +and the recursion depth. Presently, only recursion depth of 1 is +permitted. If this option is present, then every reported thread group +will also include its children, either as 'group' or 'threads' field. + + In general, any combination of option and parameters is permitted, +with the following caveats: + + * When a single thread group is passed, the output will typically be + the 'threads' result. Because threads may not contain anything, + the 'recurse' option will be ignored. + + * When the '--available' option is passed, limited information may be + available. In particular, the list of threads of a process might + be inaccessible. Further, specifying specific thread groups might + not give any performance advantage over listing all thread groups. + The frontend should assume that '-list-thread-groups --available' + is always an expensive operation and cache the results. + + The 'groups' result is a list of tuples, where each tuple may have +the following fields: + +'id' + Identifier of the thread group. This field is always present. The + identifier is an opaque string; frontends should not try to convert + it to an integer, even though it might look like one. + +'type' + The type of the thread group. At present, only 'process' is a + valid type. + +'pid' + The target-specific process identifier. This field is only present + for thread groups of type 'process' and only if the process exists. + +'num_children' + The number of children this thread group has. This field may be + absent for an available thread group. + +'threads' + This field has a list of tuples as value, each tuple describing a + thread. It may be present if the '--recurse' option is specified, + and it's actually possible to obtain the threads. + +'cores' + This field is a list of integers, each identifying a core that one + thread of the group is running on. This field may be absent if + such information is not available. + +'executable' + The name of the executable file that corresponds to this thread + group. The field is only present for thread groups of type + 'process', and only if there is a corresponding executable file. + +Example +------- + + gdb + -list-thread-groups + ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}] + -list-thread-groups 17 + ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", + frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, + {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", + frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], + file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]] + -list-thread-groups --available + ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}] + -list-thread-groups --available --recurse 1 + ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], + threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, + {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..] + -list-thread-groups --available --recurse 1 17 18 + ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], + threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, + {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...] + +The '-info-os' Command +---------------------- + +Synopsis +........ + + -info-os [ TYPE ] + + If no argument is supplied, the command returns a table of available +operating-system-specific information types. If one of these types is +supplied as an argument TYPE, then the command returns a table of data +of that type. + + The types of information available depend on the target operating +system. + +GDB Command +........... + +The corresponding GDB command is 'info os'. + +Example +....... + +When run on a GNU/Linux system, the output will look something like +this: + + gdb + -info-os + ^done,OSDataTable={nr_rows="9",nr_cols="3", + hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"}, + {width="10",alignment="-1",col_name="col1",colhdr="Description"}, + {width="10",alignment="-1",col_name="col2",colhdr="Title"}], + body=[item={col0="processes",col1="Listing of all processes", + col2="Processes"}, + item={col0="procgroups",col1="Listing of all process groups", + col2="Process groups"}, + item={col0="threads",col1="Listing of all threads", + col2="Threads"}, + item={col0="files",col1="Listing of all file descriptors", + col2="File descriptors"}, + item={col0="sockets",col1="Listing of all internet-domain sockets", + col2="Sockets"}, + item={col0="shm",col1="Listing of all shared-memory regions", + col2="Shared-memory regions"}, + item={col0="semaphores",col1="Listing of all semaphores", + col2="Semaphores"}, + item={col0="msg",col1="Listing of all message queues", + col2="Message queues"}, + item={col0="modules",col1="Listing of all loaded kernel modules", + col2="Kernel modules"}]} + gdb + -info-os processes + ^done,OSDataTable={nr_rows="190",nr_cols="4", + hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"}, + {width="10",alignment="-1",col_name="col1",colhdr="user"}, + {width="10",alignment="-1",col_name="col2",colhdr="command"}, + {width="10",alignment="-1",col_name="col3",colhdr="cores"}], + body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"}, + item={col0="2",col1="root",col2="[kthreadd]",col3="1"}, + item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"}, + ... + item={col0="26446",col1="stan",col2="bash",col3="0"}, + item={col0="28152",col1="stan",col2="bash",col3="1"}]} + (gdb) + + (Note that the MI output here includes a '"Title"' column that does +not appear in command-line 'info os'; this column is useful for MI +clients that want to enumerate the types of data, such as in a popup +menu, but is needless clutter on the command line, and 'info os' omits +it.) + +The '-add-inferior' Command +--------------------------- + +Synopsis +-------- + + -add-inferior + + Creates a new inferior (*note Inferiors and Programs::). The created +inferior is not associated with any executable. Such association may be +established with the '-file-exec-and-symbols' command (*note GDB/MI File +Commands::). The command response has a single field, 'inferior', whose +value is the identifier of the thread group corresponding to the new +inferior. + +Example +------- + + gdb + -add-inferior + ^done,inferior="i3" + +The '-interpreter-exec' Command +------------------------------- + +Synopsis +-------- + + -interpreter-exec INTERPRETER COMMAND + + Execute the specified COMMAND in the given INTERPRETER. + +GDB Command +----------- + +The corresponding GDB command is 'interpreter-exec'. + +Example +------- + + (gdb) + -interpreter-exec console "break main" + &"During symbol reading, couldn't parse type; debugger out of date?.\n" + &"During symbol reading, bad structure-type format.\n" + ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" + ^done + (gdb) + +The '-inferior-tty-set' Command +------------------------------- + +Synopsis +-------- + + -inferior-tty-set /dev/pts/1 + + Set terminal for future runs of the program being debugged. + +GDB Command +----------- + +The corresponding GDB command is 'set inferior-tty' /dev/pts/1. + +Example +------- + + (gdb) + -inferior-tty-set /dev/pts/1 + ^done + (gdb) + +The '-inferior-tty-show' Command +-------------------------------- + +Synopsis +-------- + + -inferior-tty-show + + Show terminal for future runs of program being debugged. + +GDB Command +----------- + +The corresponding GDB command is 'show inferior-tty'. + +Example +------- + + (gdb) + -inferior-tty-set /dev/pts/1 + ^done + (gdb) + -inferior-tty-show + ^done,inferior_tty_terminal="/dev/pts/1" + (gdb) + +The '-enable-timings' Command +----------------------------- + +Synopsis +-------- + + -enable-timings [yes | no] + + Toggle the printing of the wallclock, user and system times for an MI +command as a field in its output. This command is to help frontend +developers optimize the performance of their code. No argument is +equivalent to 'yes'. + +GDB Command +----------- + +No equivalent. + +Example +------- + + (gdb) + -enable-timings + ^done + (gdb) + -break-insert main + ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x080484ed",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"], + times="0"}, + time={wallclock="0.05185",user="0.00800",system="0.00000"} + (gdb) + -enable-timings no + ^done + (gdb) + -exec-run + ^running + (gdb) + *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", + frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"}, + {name="argv",value="0xbfb60364"}],file="myprog.c", + fullname="/home/nickrob/myprog.c",line="73"} + (gdb) + + +File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top + +28 GDB Annotations +****************** + +This chapter describes annotations in GDB. Annotations were designed to +interface GDB to graphical user interfaces or other similar programs +which want to interact with GDB at a relatively high level. + + The annotation mechanism has largely been superseded by GDB/MI (*note +GDB/MI::). + +* Menu: + +* Annotations Overview:: What annotations are; the general syntax. +* Server Prefix:: Issuing a command without affecting user state. +* Prompting:: Annotations marking GDB's need for input. +* Errors:: Annotations for error messages. +* Invalidation:: Some annotations describe things now invalid. +* Annotations for Running:: + Whether the program is running, how it stopped, etc. +* Source Annotations:: Annotations describing source code. + + +File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations + +28.1 What is an Annotation? +=========================== + +Annotations start with a newline character, two 'control-z' characters, +and the name of the annotation. If there is no additional information +associated with this annotation, the name of the annotation is followed +immediately by a newline. If there is additional information, the name +of the annotation is followed by a space, the additional information, +and a newline. The additional information cannot contain newline +characters. + + Any output not beginning with a newline and two 'control-z' +characters denotes literal output from GDB. Currently there is no need +for GDB to output a newline followed by two 'control-z' characters, but +if there was such a need, the annotations could be extended with an +'escape' annotation which means those three characters as output. + + The annotation LEVEL, which is specified using the '--annotate' +command line option (*note Mode Options::), controls how much +information GDB prints together with its prompt, values of expressions, +source lines, and other types of output. Level 0 is for no annotations, +level 1 is for use when GDB is run as a subprocess of GNU Emacs, level 3 +is the maximum annotation suitable for programs that control GDB, and +level 2 annotations have been made obsolete (*note Limitations of the +Annotation Interface: (annotate)Limitations.). + +'set annotate LEVEL' + The GDB command 'set annotate' sets the level of annotations to the + specified LEVEL. + +'show annotate' + Show the current annotation level. + + This chapter describes level 3 annotations. + + A simple example of starting up GDB with annotations is: + + $ gdb --annotate=3 + GNU gdb 6.0 + Copyright 2003 Free Software Foundation, Inc. + GDB is free software, covered by the GNU General Public License, + and you are welcome to change it and/or distribute copies of it + under certain conditions. + Type "show copying" to see the conditions. + There is absolutely no warranty for GDB. Type "show warranty" + for details. + This GDB was configured as "i386-pc-linux-gnu" + + ^Z^Zpre-prompt + (gdb) + ^Z^Zprompt + quit + + ^Z^Zpost-prompt + $ + + Here 'quit' is input to GDB; the rest is output from GDB. The three +lines beginning '^Z^Z' (where '^Z' denotes a 'control-z' character) are +annotations; the rest is output from GDB. + + +File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations + +28.2 The Server Prefix +====================== + +If you prefix a command with 'server ' then it will not affect the +command history, nor will it affect GDB's notion of which command to +repeat if is pressed on a line by itself. This means that +commands can be run behind a user's back by a front-end in a transparent +manner. + + The 'server ' prefix does not affect the recording of values into the +value history; to print a value without recording it into the value +history, use the 'output' command instead of the 'print' command. + + Using this prefix also disables confirmation requests (*note +confirmation requests::). + diff --git a/util/X86MAC64/share/info/gdb.info-5 b/util/X86MAC64/share/info/gdb.info-5 new file mode 100644 index 0000000000..322e520242 --- /dev/null +++ b/util/X86MAC64/share/info/gdb.info-5 @@ -0,0 +1,7968 @@ +This is gdb.info, produced by makeinfo version 5.1 from gdb.texinfo. + +Copyright (C) 1988-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + +File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations + +28.3 Annotation for GDB Input +============================= + +When GDB prompts for input, it annotates this fact so it is possible to +know when to send output, when the output from a given command is over, +etc. + + Different kinds of input each have a different "input type". Each +input type has three annotations: a 'pre-' annotation, which denotes the +beginning of any prompt which is being output, a plain annotation, which +denotes the end of the prompt, and then a 'post-' annotation which +denotes the end of any echo which may (or may not) be associated with +the input. For example, the 'prompt' input type features the following +annotations: + + ^Z^Zpre-prompt + ^Z^Zprompt + ^Z^Zpost-prompt + + The input types are + +'prompt' + When GDB is prompting for a command (the main GDB prompt). + +'commands' + When GDB prompts for a set of commands, like in the 'commands' + command. The annotations are repeated for each command which is + input. + +'overload-choice' + When GDB wants the user to select between various overloaded + functions. + +'query' + When GDB wants the user to confirm a potentially dangerous + operation. + +'prompt-for-continue' + When GDB is asking the user to press return to continue. Note: + Don't expect this to work well; instead use 'set height 0' to + disable prompting. This is because the counting of lines is buggy + in the presence of annotations. + + +File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations + +28.4 Errors +=========== + + ^Z^Zquit + + This annotation occurs right before GDB responds to an interrupt. + + ^Z^Zerror + + This annotation occurs right before GDB responds to an error. + + Quit and error annotations indicate that any annotations which GDB +was in the middle of may end abruptly. For example, if a +'value-history-begin' annotation is followed by a 'error', one cannot +expect to receive the matching 'value-history-end'. One cannot expect +not to receive it either, however; an error annotation does not +necessarily mean that GDB is immediately returning all the way to the +top level. + + A quit or error annotation may be preceded by + + ^Z^Zerror-begin + + Any output between that and the quit or error annotation is the error +message. + + Warning messages are not yet annotated. + + +File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations + +28.5 Invalidation Notices +========================= + +The following annotations say that certain pieces of state may have +changed. + +'^Z^Zframes-invalid' + + The frames (for example, output from the 'backtrace' command) may + have changed. + +'^Z^Zbreakpoints-invalid' + + The breakpoints may have changed. For example, the user just added + or deleted a breakpoint. + + +File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations + +28.6 Running the Program +======================== + +When the program starts executing due to a GDB command such as 'step' or +'continue', + + ^Z^Zstarting + + is output. When the program stops, + + ^Z^Zstopped + + is output. Before the 'stopped' annotation, a variety of annotations +describe how the program stopped. + +'^Z^Zexited EXIT-STATUS' + The program exited, and EXIT-STATUS is the exit status (zero for + successful exit, otherwise nonzero). + +'^Z^Zsignalled' + The program exited with a signal. After the '^Z^Zsignalled', the + annotation continues: + + INTRO-TEXT + ^Z^Zsignal-name + NAME + ^Z^Zsignal-name-end + MIDDLE-TEXT + ^Z^Zsignal-string + STRING + ^Z^Zsignal-string-end + END-TEXT + + where NAME is the name of the signal, such as 'SIGILL' or + 'SIGSEGV', and STRING is the explanation of the signal, such as + 'Illegal Instruction' or 'Segmentation fault'. INTRO-TEXT, + MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no + particular format. + +'^Z^Zsignal' + The syntax of this annotation is just like 'signalled', but GDB is + just saying that the program received the signal, not that it was + terminated with it. + +'^Z^Zbreakpoint NUMBER' + The program hit breakpoint number NUMBER. + +'^Z^Zwatchpoint NUMBER' + The program hit watchpoint number NUMBER. + + +File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations + +28.7 Displaying Source +====================== + +The following annotation is used instead of displaying source code: + + ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR + + where FILENAME is an absolute file name indicating which source file, +LINE is the line number within that file (where 1 is the first line in +the file), CHARACTER is the character position within the file (where 0 +is the first character in the file) (for most debug formats this will +necessarily point to the beginning of a line), MIDDLE is 'middle' if +ADDR is in the middle of the line, or 'beg' if ADDR is at the beginning +of the line, and ADDR is the address in the target program associated +with the source which is being displayed. ADDR is in the form '0x' +followed by one or more lowercase hex digits (note that this does not +depend on the language). + + +File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Annotations, Up: Top + +29 JIT Compilation Interface +**************************** + +This chapter documents GDB's "just-in-time" (JIT) compilation interface. +A JIT compiler is a program or library that generates native executable +code at runtime and executes it, usually in order to achieve good +performance while maintaining platform independence. + + Programs that use JIT compilation are normally difficult to debug +because portions of their code are generated at runtime, instead of +being loaded from object files, which is where GDB normally finds the +program's symbols and debug information. In order to debug programs +that use JIT compilation, GDB has an interface that allows the program +to register in-memory symbol files with GDB at runtime. + + If you are using GDB to debug a program that uses this interface, +then it should work transparently so long as you have not stripped the +binary. If you are developing a JIT compiler, then the interface is +documented in the rest of this chapter. At this time, the only known +client of this interface is the LLVM JIT. + + Broadly speaking, the JIT interface mirrors the dynamic loader +interface. The JIT compiler communicates with GDB by writing data into +a global variable and calling a fuction at a well-known symbol. When +GDB attaches, it reads a linked list of symbol files from the global +variable to find existing code, and puts a breakpoint in the function so +that it can find out about additional code. + +* Menu: + +* Declarations:: Relevant C struct declarations +* Registering Code:: Steps to register code +* Unregistering Code:: Steps to unregister code +* Custom Debug Info:: Emit debug information in a custom format + + +File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface + +29.1 JIT Declarations +===================== + +These are the relevant struct declarations that a C program should +include to implement the interface: + + typedef enum + { + JIT_NOACTION = 0, + JIT_REGISTER_FN, + JIT_UNREGISTER_FN + } jit_actions_t; + + struct jit_code_entry + { + struct jit_code_entry *next_entry; + struct jit_code_entry *prev_entry; + const char *symfile_addr; + uint64_t symfile_size; + }; + + struct jit_descriptor + { + uint32_t version; + /* This type should be jit_actions_t, but we use uint32_t + to be explicit about the bitwidth. */ + uint32_t action_flag; + struct jit_code_entry *relevant_entry; + struct jit_code_entry *first_entry; + }; + + /* GDB puts a breakpoint in this function. */ + void __attribute__((noinline)) __jit_debug_register_code() { }; + + /* Make sure to specify the version statically, because the + debugger may check the version before we can set it. */ + struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 }; + + If the JIT is multi-threaded, then it is important that the JIT +synchronize any modifications to this global data properly, which can +easily be done by putting a global mutex around modifications to these +structures. + + +File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface + +29.2 Registering Code +===================== + +To register code with GDB, the JIT should follow this protocol: + + * Generate an object file in memory with symbols and other desired + debug information. The file must include the virtual addresses of + the sections. + + * Create a code entry for the file, which gives the start and size of + the symbol file. + + * Add it to the linked list in the JIT descriptor. + + * Point the relevant_entry field of the descriptor at the entry. + + * Set 'action_flag' to 'JIT_REGISTER' and call + '__jit_debug_register_code'. + + When GDB is attached and the breakpoint fires, GDB uses the +'relevant_entry' pointer so it doesn't have to walk the list looking for +new code. However, the linked list must still be maintained in order to +allow GDB to attach to a running process and still find the symbol +files. + + +File: gdb.info, Node: Unregistering Code, Next: Custom Debug Info, Prev: Registering Code, Up: JIT Interface + +29.3 Unregistering Code +======================= + +If code is freed, then the JIT should use the following protocol: + + * Remove the code entry corresponding to the code from the linked + list. + + * Point the 'relevant_entry' field of the descriptor at the code + entry. + + * Set 'action_flag' to 'JIT_UNREGISTER' and call + '__jit_debug_register_code'. + + If the JIT frees or recompiles code without unregistering it, then +GDB and the JIT will leak the memory used for the associated symbol +files. + + +File: gdb.info, Node: Custom Debug Info, Prev: Unregistering Code, Up: JIT Interface + +29.4 Custom Debug Info +====================== + +Generating debug information in platform-native file formats (like ELF +or COFF) may be an overkill for JIT compilers; especially if all the +debug info is used for is displaying a meaningful backtrace. The issue +can be resolved by having the JIT writers decide on a debug info format +and also provide a reader that parses the debug info generated by the +JIT compiler. This section gives a brief overview on writing such a +parser. More specific details can be found in the source file +'gdb/jit-reader.in', which is also installed as a header at +'INCLUDEDIR/gdb/jit-reader.h' for easy inclusion. + + The reader is implemented as a shared object (so this functionality +is not available on platforms which don't allow loading shared objects +at runtime). Two GDB commands, 'jit-reader-load' and +'jit-reader-unload' are provided, to be used to load and unload the +readers from a preconfigured directory. Once loaded, the shared object +is used the parse the debug information emitted by the JIT compiler. + +* Menu: + +* Using JIT Debug Info Readers:: How to use supplied readers correctly +* Writing JIT Debug Info Readers:: Creating a debug-info reader + + +File: gdb.info, Node: Using JIT Debug Info Readers, Next: Writing JIT Debug Info Readers, Up: Custom Debug Info + +29.4.1 Using JIT Debug Info Readers +----------------------------------- + +Readers can be loaded and unloaded using the 'jit-reader-load' and +'jit-reader-unload' commands. + +'jit-reader-load READER' + Load the JIT reader named READER. READER is a shared object + specified as either an absolute or a relative file name. In the + latter case, GDB will try to load the reader from a pre-configured + directory, usually 'LIBDIR/gdb/' on a UNIX system (here LIBDIR is + the system library directory, often '/usr/local/lib'). + + Only one reader can be active at a time; trying to load a second + reader when one is already loaded will result in GDB reporting an + error. A new JIT reader can be loaded by first unloading the + current one using 'jit-reader-unload' and then invoking + 'jit-reader-load'. + +'jit-reader-unload' + Unload the currently loaded JIT reader. + + +File: gdb.info, Node: Writing JIT Debug Info Readers, Prev: Using JIT Debug Info Readers, Up: Custom Debug Info + +29.4.2 Writing JIT Debug Info Readers +------------------------------------- + +As mentioned, a reader is essentially a shared object conforming to a +certain ABI. This ABI is described in 'jit-reader.h'. + + 'jit-reader.h' defines the structures, macros and functions required +to write a reader. It is installed (along with GDB), in +'INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory. + + Readers need to be released under a GPL compatible license. A reader +can be declared as released under such a license by placing the macro +'GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file. + + The entry point for readers is the symbol 'gdb_init_reader', which is +expected to be a function with the prototype + + extern struct gdb_reader_funcs *gdb_init_reader (void); + + 'struct gdb_reader_funcs' contains a set of pointers to callback +functions. These functions are executed to read the debug info +generated by the JIT compiler ('read'), to unwind stack frames +('unwind') and to create canonical frame IDs ('get_Frame_id'). It also +has a callback that is called when the reader is being unloaded +('destroy'). The struct looks like this + + struct gdb_reader_funcs + { + /* Must be set to GDB_READER_INTERFACE_VERSION. */ + int reader_version; + + /* For use by the reader. */ + void *priv_data; + + gdb_read_debug_info *read; + gdb_unwind_frame *unwind; + gdb_get_frame_id *get_frame_id; + gdb_destroy_reader *destroy; + }; + + The callbacks are provided with another set of callbacks by GDB to do +their job. For 'read', these callbacks are passed in a 'struct +gdb_symbol_callbacks' and for 'unwind' and 'get_frame_id', in a 'struct +gdb_unwind_callbacks'. 'struct gdb_symbol_callbacks' has callbacks to +create new object files and new symbol tables inside those object files. +'struct gdb_unwind_callbacks' has callbacks to read registers off the +current frame and to write out the values of the registers in the +previous frame. Both have a callback ('target_read') to read bytes off +the target's address space. + + +File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface, Up: Top + +30 In-Process Agent +******************* + +The traditional debugging model is conceptually low-speed, but works +fine, because most bugs can be reproduced in debugging-mode execution. +However, as multi-core or many-core processors are becoming mainstream, +and multi-threaded programs become more and more popular, there should +be more and more bugs that only manifest themselves at normal-mode +execution, for example, thread races, because debugger's interference +with the program's timing may conceal the bugs. On the other hand, in +some applications, it is not feasible for the debugger to interrupt the +program's execution long enough for the developer to learn anything +helpful about its behavior. If the program's correctness depends on its +real-time behavior, delays introduced by a debugger might cause the +program to fail, even when the code itself is correct. It is useful to +be able to observe the program's behavior without interrupting it. + + Therefore, traditional debugging model is too intrusive to reproduce +some bugs. In order to reduce the interference with the program, we can +reduce the number of operations performed by debugger. The "In-Process +Agent", a shared library, is running within the same process with +inferior, and is able to perform some debugging operations itself. As a +result, debugger is only involved when necessary, and performance of +debugging can be improved accordingly. Note that interference with +program can be reduced but can't be removed completely, because the +in-process agent will still stop or slow down the program. + + The in-process agent can interpret and execute Agent Expressions +(*note Agent Expressions::) during performing debugging operations. The +agent expressions can be used for different purposes, such as collecting +data in tracepoints, and condition evaluation in breakpoints. + + You can control whether the in-process agent is used as an aid for +debugging with the following commands: + +'set agent on' + Causes the in-process agent to perform some operations on behalf of + the debugger. Just which operations requested by the user will be + done by the in-process agent depends on the its capabilities. For + example, if you request to evaluate breakpoint conditions in the + in-process agent, and the in-process agent has such capability as + well, then breakpoint conditions will be evaluated in the + in-process agent. + +'set agent off' + Disables execution of debugging operations by the in-process agent. + All of the operations will be performed by GDB. + +'show agent' + Display the current setting of execution of debugging operations by + the in-process agent. + +* Menu: + +* In-Process Agent Protocol:: + + +File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent + +30.1 In-Process Agent Protocol +============================== + +The in-process agent is able to communicate with both GDB and GDBserver +(*note In-Process Agent::). This section documents the protocol used +for communications between GDB or GDBserver and the IPA. In general, GDB +or GDBserver sends commands (*note IPA Protocol Commands::) and data to +in-process agent, and then in-process agent replies back with the return +result of the command, or some other information. The data sent to +in-process agent is composed of primitive data types, such as 4-byte or +8-byte type, and composite types, which are called objects (*note IPA +Protocol Objects::). + +* Menu: + +* IPA Protocol Objects:: +* IPA Protocol Commands:: + + +File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up: In-Process Agent Protocol + +30.1.1 IPA Protocol Objects +--------------------------- + +The commands sent to and results received from agent may contain some +complex data types called "objects". + + The in-process agent is running on the same machine with GDB or +GDBserver, so it doesn't have to handle as much differences between two +ends as remote protocol (*note Remote Protocol::) tries to handle. +However, there are still some differences of two ends in two processes: + + 1. word size. On some 64-bit machines, GDB or GDBserver can be + compiled as a 64-bit executable, while in-process agent is a 32-bit + one. + 2. ABI. Some machines may have multiple types of ABI, GDB or GDBserver + is compiled with one, and in-process agent is compiled with the + other one. + + Here are the IPA Protocol Objects: + + 1. agent expression object. It represents an agent expression (*note + Agent Expressions::). + 2. tracepoint action object. It represents a tracepoint action (*note + Tracepoint Action Lists: Tracepoint Actions.) to collect registers, + memory, static trace data and to evaluate expression. + 3. tracepoint object. It represents a tracepoint (*note + Tracepoints::). + + The following table describes important attributes of each IPA +protocol object: + +Name Size Description +--------------------------------------------------------------------------- +_agent expression +object_ +length 4 length of bytes code +byte code LENGTH contents of byte code +_tracepoint action +for collecting +memory_ +'M' 1 type of tracepoint action +addr 8 if BASEREG is '-1', ADDR is the + address of the lowest byte to + collect, otherwise ADDR is the + offset of BASEREG for memory + collecting. +len 8 length of memory for collecting +basereg 4 the register number containing the + starting memory address for + collecting. +_tracepoint action +for collecting +registers_ +'R' 1 type of tracepoint action +_tracepoint action +for collecting +static trace data_ +'L' 1 type of tracepoint action +_tracepoint action +for expression +evaluation_ +'X' 1 type of tracepoint action +agent expression length of *note agent expression object:: +_tracepoint object_ +number 4 number of tracepoint +address 8 address of tracepoint inserted on +type 4 type of tracepoint +enabled 1 enable or disable of tracepoint +step_count 8 step +pass_count 8 pass +numactions 4 number of tracepoint actions +hit count 8 hit count +trace frame usage 8 trace frame usage +compiled_cond 8 compiled condition +orig_size 8 orig size +condition 4 if zero if condition is NULL, + condition is otherwise is *note agent + NULL expression object:: + otherwise + length of + *note agent + expression + object:: +actions variable numactions number of *note + tracepoint action object:: + + +File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up: In-Process Agent Protocol + +30.1.2 IPA Protocol Commands +---------------------------- + +The spaces in each command are delimiters to ease reading this commands +specification. They don't exist in real commands. + +'FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD' + Installs a new fast tracepoint described by TRACEPOINT_OBJECT + (*note tracepoint object::). GDB_JUMP_PAD_HEAD, 8-byte long, is + the head of "jumppad", which is used to jump to data collection + routine in IPA finally. + + Replies: + 'OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP' + TARGET_ADDRESS is address of tracepoint in the inferior. + GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of + TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. FJUMP + contains a sequence of instructions jump to jumppad entry. + FJUMP_SIZE, 4-byte long, is the size of FJUMP. + 'E NN' + for an error + +'close' + Closes the in-process agent. This command is sent when GDB or + GDBserver is about to kill inferiors. + +'qTfSTM' + *Note qTfSTM::. +'qTsSTM' + *Note qTsSTM::. +'qTSTMat' + *Note qTSTMat::. +'probe_marker_at:ADDRESS' + Asks in-process agent to probe the marker at ADDRESS. + + Replies: + 'E NN' + for an error +'unprobe_marker_at:ADDRESS' + Asks in-process agent to unprobe the marker at ADDRESS. + + +File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process Agent, Up: Top + +31 Reporting Bugs in GDB +************************ + +Your bug reports play an essential role in making GDB reliable. + + Reporting a bug may help you by bringing a solution to your problem, +or it may not. But in any case the principal function of a bug report +is to help the entire community by making the next version of GDB work +better. Bug reports are your contribution to the maintenance of GDB. + + In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +* Menu: + +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs + + +File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs + +31.1 Have You Found a Bug? +========================== + +If you are not sure whether you have found a bug, here are some +guidelines: + + * If the debugger gets a fatal signal, for any input whatever, that + is a GDB bug. Reliable debuggers never crash. + + * If GDB produces an error message for valid input, that is a bug. + (Note that if you're cross debugging, the problem may also be + somewhere in the connection to the target.) + + * If GDB does not produce an error message for invalid input, that is + a bug. However, you should note that your idea of "invalid input" + might be our idea of "an extension" or "support for traditional + practice". + + * If you are an experienced user of debugging tools, your suggestions + for improvement of GDB are welcome in any case. + + +File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs + +31.2 How to Report Bugs +======================= + +A number of companies and individuals offer support for GNU products. +If you obtained GDB from a support organization, we recommend you +contact that organization first. + + You can find contact information for many support companies and +individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. + + In any event, we also recommend that you submit bug reports for GDB. +The preferred method is to submit them directly using GDB's Bugs web +page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the e-mail +gateway can be used. + + *Do not send bug reports to 'info-gdb', or to 'help-gdb', or to any +newsgroups.* Most users of GDB do not want to receive bug reports. +Those that do have arranged to receive 'bug-gdb'. + + The mailing list 'bug-gdb' has a newsgroup 'gnu.gdb.bug' which serves +as a repeater. The mailing list and the newsgroup carry exactly the +same messages. Often people think of posting bug reports to the +newsgroup instead of mailing them. This appears to work, but it has one +problem which can be crucial: a newsgroup posting often lacks a mail +path back to the sender. Thus, if we need to ask for more information, +we may be unable to reach you. For this reason, it is better to send +bug reports to the mailing list. + + The fundamental principle of reporting bugs usefully is this: *report +all the facts*. If you are not sure whether to state a fact or leave it +out, state it! + + Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of the variable you use in an example does not +matter. Well, probably it does not, but one cannot be sure. Perhaps +the bug is a stray memory reference which happens to fetch from the +location where that name is stored in memory; perhaps, if the name were +different, the contents of that location would fool the debugger into +doing the right thing despite the bug. Play it safe and give a +specific, complete example. That is the easiest thing for you to do, +and the most helpful. + + Keep in mind that the purpose of a bug report is to enable us to fix +the bug. It may be that the bug has been reported previously, but +neither you nor we can know that unless your bug report is complete and +self-contained. + + Sometimes people give a few sketchy facts and ask, "Does this ring a +bell?" Those bug reports are useless, and we urge everyone to _refuse +to respond to them_ except to chide the sender to report bugs properly. + + To enable us to fix the bug, you should include all these things: + + * The version of GDB. GDB announces it if you start with no + arguments; you can also print it at any time using 'show version'. + + Without this, we will not know whether there is any point in + looking for the bug in the current version of GDB. + + * The type of machine you are using, and the operating system name + and version number. + + * The details of the GDB build-time configuration. GDB shows these + details if you invoke it with the '--configuration' command-line + option, or if you type 'show configuration' at GDB's prompt. + + * What compiler (and its version) was used to compile GDB--e.g. + "gcc-2.8.1". + + * What compiler (and its version) was used to compile the program you + are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP C + Compiler". For GCC, you can say 'gcc --version' to get this + information; for other compilers, see the documentation for those + compilers. + + * The command arguments you gave the compiler to compile your example + and observe the bug. For example, did you use '-O'? To guarantee + you will not omit something important, list them all. A copy of + the Makefile (or the output from make) is sufficient. + + If we were to try to guess the arguments, we would probably guess + wrong and then we might not encounter the bug. + + * A complete input script, and all necessary source files, that will + reproduce the bug. + + * A description of what behavior you observe that you believe is + incorrect. For example, "It gets a fatal signal." + + Of course, if the bug is that GDB gets a fatal signal, then we will + certainly notice it. But if the bug is incorrect output, we might + not notice unless it is glaringly wrong. You might as well not + give us a chance to make a mistake. + + Even if the problem you experience is a fatal signal, you should + still say so explicitly. Suppose something strange is going on, + such as, your copy of GDB is out of synch, or you have encountered + a bug in the C library on your system. (This has happened!) Your + copy might crash and ours would not. If you told us to expect a + crash, then when ours fails to crash, we would know that the bug + was not happening for us. If you had not told us to expect a + crash, then we would not be able to draw any conclusion from our + observations. + + To collect all this information, you can use a session recording + program such as 'script', which is available on many Unix systems. + Just run your GDB session inside 'script' and then include the + 'typescript' file with your bug report. + + Another way to record a GDB session is to run GDB inside Emacs and + then save the entire buffer to a file. + + * If you wish to suggest changes to the GDB source, send us context + diffs. If you even discuss something in the GDB source, refer to + it by context, not by line number. + + The line numbers in our development sources will not match those in + your sources. Your line numbers would convey no useful information + to us. + + Here are some things that are not necessary: + + * A description of the envelope of the bug. + + Often people who encounter a bug spend a lot of time investigating + which changes to the input file will make the bug go away and which + changes will not affect it. + + This is often time consuming and not very useful, because the way + we will find the bug is by running a single example under the + debugger with breakpoints, not by pure deduction from a series of + examples. We recommend that you save your time for something else. + + Of course, if you can find a simpler example to report _instead_ of + the original one, that is a convenience for us. Errors in the + output will be easier to spot, running under the debugger will take + less time, and so on. + + However, simplification is not vital; if you do not want to do + this, report the bug anyway and send us the entire test case you + used. + + * A patch for the bug. + + A patch for the bug does help us if it is a good one. But do not + omit the necessary information, such as the test case, on the + assumption that a patch is all we need. We might see problems with + your patch and decide to fix the problem another way, or we might + not understand it at all. + + Sometimes with a program as complicated as GDB it is very hard to + construct an example that will make the program follow a certain + path through the code. If you do not send us the example, we will + not be able to construct one, so we will not be able to verify that + the bug is fixed. + + And if we cannot understand what bug you are trying to fix, or why + your patch should be an improvement, we will not install it. A + test case will help us to understand. + + * A guess about what the bug is or what it depends on. + + Such guesses are usually wrong. Even we cannot guess right about + such things without first using the debugger to find the facts. + + +File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top + +32 Command Line Editing +*********************** + +This chapter describes the basic features of the GNU command line +editing interface. + +* Menu: + +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Init File:: Customizing Readline from a user's view. +* Bindable Readline Commands:: A description of most of the Readline commands + available for binding +* Readline vi Mode:: A short description of how to make Readline + behave like the vi editor. + + +File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing + +32.1 Introduction to Line Editing +================================= + +The following paragraphs describe the notation used to represent +keystrokes. + + The text 'C-k' is read as 'Control-K' and describes the character +produced when the key is pressed while the Control key is depressed. + + The text 'M-k' is read as 'Meta-K' and describes the character +produced when the Meta key (if you have one) is depressed, and the +key is pressed. The Meta key is labeled on many keyboards. On +keyboards with two keys labeled (usually to either side of the +space bar), the on the left side is generally set to work as a +Meta key. The key on the right may also be configured to work as +a Meta key or may be configured as some other modifier, such as a +Compose key for typing accented characters. + + If you do not have a Meta or key, or another key working as a +Meta key, the identical keystroke can be generated by typing +_first_, and then typing . Either process is known as "metafying" +the key. + + The text 'M-C-k' is read as 'Meta-Control-k' and describes the +character produced by "metafying" 'C-k'. + + In addition, several keys have their own names. Specifically, , +, , , , and all stand for themselves when seen +in this text, or in an init file (*note Readline Init File::). If your +keyboard lacks a key, typing will produce the desired +character. The key may be labeled or on some +keyboards. + + +File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing + +32.2 Readline Interaction +========================= + +Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press . You do not have to be at the end of +the line to press ; the entire line is accepted regardless of the +location of the cursor within the line. + +* Menu: + +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. +* Searching:: Searching through previous lines. + + +File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction + +32.2.1 Readline Bare Essentials +------------------------------- + +In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use your erase +character to back up and delete the mistyped character. + + Sometimes you may mistype a character, and not notice the error until +you have typed several other characters. In that case, you can type +'C-b' to move the cursor to the left, and then correct your mistake. +Afterwards, you can move the cursor to the right with 'C-f'. + + When you add text in the middle of a line, you will notice that +characters to the right of the cursor are 'pushed over' to make room for +the text that you have inserted. Likewise, when you delete text behind +the cursor, characters to the right of the cursor are 'pulled back' to +fill in the blank space created by the removal of the text. A list of +the bare essentials for editing the text of an input line follows. + +'C-b' + Move back one character. +'C-f' + Move forward one character. + or + Delete the character to the left of the cursor. +'C-d' + Delete the character underneath the cursor. +Printing characters + Insert the character into the line at the cursor. +'C-_' or 'C-x C-u' + Undo the last editing command. You can undo all the way back to an + empty line. + +(Depending on your configuration, the key be set to delete +the character to the left of the cursor and the key set to delete +the character underneath the cursor, like 'C-d', rather than the +character to the left of the cursor.) + + +File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction + +32.2.2 Readline Movement Commands +--------------------------------- + +The above table describes the most basic keystrokes that you need in +order to do editing of the input line. For your convenience, many other +commands have been added in addition to 'C-b', 'C-f', 'C-d', and . +Here are some commands for moving more rapidly about the line. + +'C-a' + Move to the start of the line. +'C-e' + Move to the end of the line. +'M-f' + Move forward a word, where a word is composed of letters and + digits. +'M-b' + Move backward a word. +'C-l' + Clear the screen, reprinting the current line at the top. + + Notice how 'C-f' moves forward a character, while 'M-f' moves forward +a word. It is a loose convention that control keystrokes operate on +characters while meta keystrokes operate on words. + + +File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction + +32.2.3 Readline Killing Commands +-------------------------------- + +"Killing" text means to delete the text from the line, but to save it +away for later use, usually by "yanking" (re-inserting) it back into the +line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.) + + If the description for a command says that it 'kills' text, then you +can be sure that you can get the text back in a different (or the same) +place later. + + When you use a kill command, the text is saved in a "kill-ring". Any +number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill ring is not line +specific; the text that you killed on a previously typed line is +available to be yanked back later, when you are typing another line. + + Here is the list of commands for killing text. + +'C-k' + Kill the text from the current cursor position to the end of the + line. + +'M-d' + Kill from the cursor to the end of the current word, or, if between + words, to the end of the next word. Word boundaries are the same + as those used by 'M-f'. + +'M-' + Kill from the cursor the start of the current word, or, if between + words, to the start of the previous word. Word boundaries are the + same as those used by 'M-b'. + +'C-w' + Kill from the cursor to the previous whitespace. This is different + than 'M-' because the word boundaries differ. + + Here is how to "yank" the text back into the line. Yanking means to +copy the most-recently-killed text from the kill buffer. + +'C-y' + Yank the most recently killed text back into the buffer at the + cursor. + +'M-y' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is 'C-y' or 'M-y'. + + +File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction + +32.2.4 Readline Arguments +------------------------- + +You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the sign of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type 'M-- C-k'. + + The general way to pass numeric arguments to a command is to type +meta digits before the command. If the first 'digit' typed is a minus +sign ('-'), then the sign of the argument will be negative. Once you +have typed one meta digit to get the argument started, you can type the +remainder of the digits, and then the command. For example, to give the +'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will +delete the next ten characters on the input line. + + +File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction + +32.2.5 Searching for Commands in the History +-------------------------------------------- + +Readline provides commands for searching through the command history for +lines containing a specified string. There are two search modes: +"incremental" and "non-incremental". + + Incremental searches begin before the user has finished typing the +search string. As each character of the search string is typed, +Readline displays the next entry from the history matching the string +typed so far. An incremental search requires only as many characters as +needed to find the desired history entry. To search backward in the +history for a particular string, type 'C-r'. Typing 'C-s' searches +forward through the history. The characters present in the value of the +'isearch-terminators' variable are used to terminate an incremental +search. If that variable has not been assigned a value, the and +'C-J' characters will terminate an incremental search. 'C-g' will abort +an incremental search and restore the original line. When the search is +terminated, the history entry containing the search string becomes the +current line. + + To find other matching entries in the history list, type 'C-r' or +'C-s' as appropriate. This will search backward or forward in the +history for the next entry matching the search string typed so far. Any +other key sequence bound to a Readline command will terminate the search +and execute that command. For instance, a will terminate the +search and accept the line, thereby executing the command from the +history list. A movement command will terminate the search, make the +last line found the current line, and begin editing. + + Readline remembers the last incremental search string. If two 'C-r's +are typed without any intervening characters defining a new search +string, any remembered search string is used. + + Non-incremental searches read the entire search string before +starting to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. + + +File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing + +32.3 Readline Init File +======================= + +Although the Readline library comes with a set of Emacs-like keybindings +installed by default, it is possible to use a different set of +keybindings. Any user can customize programs that use Readline by +putting commands in an "inputrc" file, conventionally in his home +directory. The name of this file is taken from the value of the +environment variable 'INPUTRC'. If that variable is unset, the default +is '~/.inputrc'. If that file does not exist or cannot be read, the +ultimate default is '/etc/inputrc'. + + When a program which uses the Readline library starts up, the init +file is read, and the key bindings are set. + + In addition, the 'C-x C-r' command re-reads this init file, thus +incorporating any changes that you might have made to it. + +* Menu: + +* Readline Init File Syntax:: Syntax for the commands in the inputrc file. + +* Conditional Init Constructs:: Conditional key bindings in the inputrc file. + +* Sample Init File:: An example inputrc file. + + +File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File + +32.3.1 Readline Init File Syntax +-------------------------------- + +There are only a few basic constructs allowed in the Readline init file. +Blank lines are ignored. Lines beginning with a '#' are comments. +Lines beginning with a '$' indicate conditional constructs (*note +Conditional Init Constructs::). Other lines denote variable settings +and key bindings. + +Variable Settings + You can modify the run-time behavior of Readline by altering the + values of variables in Readline using the 'set' command within the + init file. The syntax is simple: + + set VARIABLE VALUE + + Here, for example, is how to change from the default Emacs-like key + binding to use 'vi' line editing commands: + + set editing-mode vi + + Variable names and values, where appropriate, are recognized + without regard to case. Unrecognized variable names are ignored. + + Boolean variables (those that can be set to on or off) are set to + on if the value is null or empty, ON (case-insensitive), or 1. Any + other value results in the variable being set to off. + + A great deal of run-time behavior is changeable with the following + variables. + + 'bell-style' + Controls what happens when Readline wants to ring the terminal + bell. If set to 'none', Readline never rings the bell. If + set to 'visible', Readline uses a visible bell if one is + available. If set to 'audible' (the default), Readline + attempts to ring the terminal's bell. + + 'bind-tty-special-chars' + If set to 'on', Readline attempts to bind the control + characters treated specially by the kernel's terminal driver + to their Readline equivalents. + + 'comment-begin' + The string to insert at the beginning of the line when the + 'insert-comment' command is executed. The default value is + '"#"'. + + 'completion-display-width' + The number of screen columns used to display possible matches + when performing completion. The value is ignored if it is + less than 0 or greater than the terminal screen width. A + value of 0 will cause matches to be displayed one per line. + The default value is -1. + + 'completion-ignore-case' + If set to 'on', Readline performs filename matching and + completion in a case-insensitive fashion. The default value + is 'off'. + + 'completion-map-case' + If set to 'on', and COMPLETION-IGNORE-CASE is enabled, + Readline treats hyphens ('-') and underscores ('_') as + equivalent when performing case-insensitive filename matching + and completion. + + 'completion-prefix-display-length' + The length in characters of the common prefix of a list of + possible completions that is displayed without modification. + When set to a value greater than zero, common prefixes longer + than this value are replaced with an ellipsis when displaying + possible completions. + + 'completion-query-items' + The number of possible completions that determines when the + user is asked whether the list of possibilities should be + displayed. If the number of possible completions is greater + than this value, Readline will ask the user whether or not he + wishes to view them; otherwise, they are simply listed. This + variable must be set to an integer value greater than or equal + to 0. A negative value means Readline should never ask. The + default limit is '100'. + + 'convert-meta' + If set to 'on', Readline will convert characters with the + eighth bit set to an ASCII key sequence by stripping the + eighth bit and prefixing an character, converting them + to a meta-prefixed key sequence. The default value is 'on'. + + 'disable-completion' + If set to 'On', Readline will inhibit word completion. + Completion characters will be inserted into the line as if + they had been mapped to 'self-insert'. The default is 'off'. + + 'editing-mode' + The 'editing-mode' variable controls which default set of key + bindings is used. By default, Readline starts up in Emacs + editing mode, where the keystrokes are most similar to Emacs. + This variable can be set to either 'emacs' or 'vi'. + + 'echo-control-characters' + When set to 'on', on operating systems that indicate they + support it, readline echoes a character corresponding to a + signal generated from the keyboard. The default is 'on'. + + 'enable-keypad' + When set to 'on', Readline will try to enable the application + keypad when it is called. Some systems need this to enable + the arrow keys. The default is 'off'. + + 'enable-meta-key' + When set to 'on', Readline will try to enable any meta + modifier key the terminal claims to support when it is called. + On many terminals, the meta key is used to send eight-bit + characters. The default is 'on'. + + 'expand-tilde' + If set to 'on', tilde expansion is performed when Readline + attempts word completion. The default is 'off'. + + 'history-preserve-point' + If set to 'on', the history code attempts to place the point + (the current cursor position) at the same location on each + history line retrieved with 'previous-history' or + 'next-history'. The default is 'off'. + + 'history-size' + Set the maximum number of history entries saved in the history + list. If set to zero, the number of entries in the history + list is not limited. + + 'horizontal-scroll-mode' + This variable can be set to either 'on' or 'off'. Setting it + to 'on' means that the text of the lines being edited will + scroll horizontally on a single screen line when they are + longer than the width of the screen, instead of wrapping onto + a new screen line. By default, this variable is set to 'off'. + + 'input-meta' + If set to 'on', Readline will enable eight-bit input (it will + not clear the eighth bit in the characters it reads), + regardless of what the terminal claims it can support. The + default value is 'off'. The name 'meta-flag' is a synonym for + this variable. + + 'isearch-terminators' + The string of characters that should terminate an incremental + search without subsequently executing the character as a + command (*note Searching::). If this variable has not been + given a value, the characters and 'C-J' will terminate + an incremental search. + + 'keymap' + Sets Readline's idea of the current keymap for key binding + commands. Acceptable 'keymap' names are 'emacs', + 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', + 'vi-command', and 'vi-insert'. 'vi' is equivalent to + 'vi-command'; 'emacs' is equivalent to 'emacs-standard'. The + default value is 'emacs'. The value of the 'editing-mode' + variable also affects the default keymap. + + 'mark-directories' + If set to 'on', completed directory names have a slash + appended. The default is 'on'. + + 'mark-modified-lines' + This variable, when set to 'on', causes Readline to display an + asterisk ('*') at the start of history lines which have been + modified. This variable is 'off' by default. + + 'mark-symlinked-directories' + If set to 'on', completed names which are symbolic links to + directories have a slash appended (subject to the value of + 'mark-directories'). The default is 'off'. + + 'match-hidden-files' + This variable, when set to 'on', causes Readline to match + files whose names begin with a '.' (hidden files) when + performing filename completion. If set to 'off', the leading + '.' must be supplied by the user in the filename to be + completed. This variable is 'on' by default. + + 'menu-complete-display-prefix' + If set to 'on', menu completion displays the common prefix of + the list of possible completions (which may be empty) before + cycling through the list. The default is 'off'. + + 'output-meta' + If set to 'on', Readline will display characters with the + eighth bit set directly rather than as a meta-prefixed escape + sequence. The default is 'off'. + + 'page-completions' + If set to 'on', Readline uses an internal 'more'-like pager to + display a screenful of possible completions at a time. This + variable is 'on' by default. + + 'print-completions-horizontally' + If set to 'on', Readline will display completions with matches + sorted horizontally in alphabetical order, rather than down + the screen. The default is 'off'. + + 'revert-all-at-newline' + If set to 'on', Readline will undo all changes to history + lines before returning when 'accept-line' is executed. By + default, history lines may be modified and retain individual + undo lists across calls to 'readline'. The default is 'off'. + + 'show-all-if-ambiguous' + This alters the default behavior of the completion functions. + If set to 'on', words which have more than one possible + completion cause the matches to be listed immediately instead + of ringing the bell. The default value is 'off'. + + 'show-all-if-unmodified' + This alters the default behavior of the completion functions + in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to + 'on', words which have more than one possible completion + without any possible partial completion (the possible + completions don't share a common prefix) cause the matches to + be listed immediately instead of ringing the bell. The + default value is 'off'. + + 'skip-completed-text' + If set to 'on', this alters the default completion behavior + when inserting a single match into the line. It's only active + when performing completion in the middle of a word. If + enabled, readline does not insert characters from the + completion that match characters after point in the word being + completed, so portions of the word following the cursor are + not duplicated. For instance, if this is enabled, attempting + completion when the cursor is after the 'e' in 'Makefile' will + result in 'Makefile' rather than 'Makefilefile', assuming + there is a single possible completion. The default value is + 'off'. + + 'visible-stats' + If set to 'on', a character denoting a file's type is appended + to the filename when listing possible completions. The + default is 'off'. + +Key Bindings + The syntax for controlling key bindings in the init file is simple. + First you need to find the name of the command that you want to + change. The following sections contain tables of the command name, + the default keybinding, if any, and a short description of what the + command does. + + Once you know the name of the command, simply place on a line in + the init file the name of the key you wish to bind the command to, + a colon, and then the name of the command. There can be no space + between the key name and the colon - that will be interpreted as + part of the key name. The name of the key can be expressed in + different ways, depending on what you find most comfortable. + + In addition to command names, readline allows keys to be bound to a + string that is inserted when the key is pressed (a MACRO). + + KEYNAME: FUNCTION-NAME or MACRO + KEYNAME is the name of a key spelled out in English. For + example: + Control-u: universal-argument + Meta-Rubout: backward-kill-word + Control-o: "> output" + + In the above example, 'C-u' is bound to the function + 'universal-argument', 'M-DEL' is bound to the function + 'backward-kill-word', and 'C-o' is bound to run the macro + expressed on the right hand side (that is, to insert the text + '> output' into the line). + + A number of symbolic character names are recognized while + processing this key binding syntax: DEL, ESC, ESCAPE, LFD, + NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. + + "KEYSEQ": FUNCTION-NAME or MACRO + KEYSEQ differs from KEYNAME above in that strings denoting an + entire key sequence can be specified, by placing the key + sequence in double quotes. Some GNU Emacs style key escapes + can be used, as in the following example, but the special + character names are not recognized. + + "\C-u": universal-argument + "\C-x\C-r": re-read-init-file + "\e[11~": "Function Key 1" + + In the above example, 'C-u' is again bound to the function + 'universal-argument' (just as it was in the first example), + ''C-x' 'C-r'' is bound to the function 're-read-init-file', + and ' <[> <1> <1> <~>' is bound to insert the text + 'Function Key 1'. + + The following GNU Emacs style escape sequences are available when + specifying key sequences: + + '\C-' + control prefix + '\M-' + meta prefix + '\e' + an escape character + '\\' + backslash + '\"' + <">, a double quotation mark + '\'' + <'>, a single quote or apostrophe + + In addition to the GNU Emacs style escape sequences, a second set + of backslash escapes is available: + + '\a' + alert (bell) + '\b' + backspace + '\d' + delete + '\f' + form feed + '\n' + newline + '\r' + carriage return + '\t' + horizontal tab + '\v' + vertical tab + '\NNN' + the eight-bit character whose value is the octal value NNN + (one to three digits) + '\xHH' + the eight-bit character whose value is the hexadecimal value + HH (one or two hex digits) + + When entering the text of a macro, single or double quotes must be + used to indicate a macro definition. Unquoted text is assumed to + be a function name. In the macro body, the backslash escapes + described above are expanded. Backslash will quote any other + character in the macro text, including '"' and '''. For example, + the following binding will make ''C-x' \' insert a single '\' into + the line: + "\C-x\\": "\\" + + +File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File + +32.3.2 Conditional Init Constructs +---------------------------------- + +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key bindings and +variable settings to be performed as the result of tests. There are +four parser directives used. + +'$if' + The '$if' construct allows bindings to be made based on the editing + mode, the terminal being used, or the application using Readline. + The text of the test extends to the end of the line; no characters + are required to isolate it. + + 'mode' + The 'mode=' form of the '$if' directive is used to test + whether Readline is in 'emacs' or 'vi' mode. This may be used + in conjunction with the 'set keymap' command, for instance, to + set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps + only if Readline is starting out in 'emacs' mode. + + 'term' + The 'term=' form may be used to include terminal-specific key + bindings, perhaps to bind the key sequences output by the + terminal's function keys. The word on the right side of the + '=' is tested against both the full name of the terminal and + the portion of the terminal name before the first '-'. This + allows 'sun' to match both 'sun' and 'sun-cmd', for instance. + + 'application' + The APPLICATION construct is used to include + application-specific settings. Each program using the + Readline library sets the APPLICATION NAME, and you can test + for a particular value. This could be used to bind key + sequences to functions useful for a specific program. For + instance, the following command adds a key sequence that + quotes the current or previous word in Bash: + $if Bash + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + $endif + +'$endif' + This command, as seen in the previous example, terminates an '$if' + command. + +'$else' + Commands in this branch of the '$if' directive are executed if the + test fails. + +'$include' + This directive takes a single filename as an argument and reads + commands and bindings from that file. For example, the following + directive reads from '/etc/inputrc': + $include /etc/inputrc + + +File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File + +32.3.3 Sample Init File +----------------------- + +Here is an example of an INPUTRC file. This illustrates key binding, +variable assignment, and conditional syntax. + + # This file controls the behaviour of line input editing for + # programs that use the GNU Readline library. Existing + # programs include FTP, Bash, and GDB. + # + # You can re-read the inputrc file with C-x C-r. + # Lines beginning with '#' are comments. + # + # First, include any systemwide bindings and variable + # assignments from /etc/Inputrc + $include /etc/Inputrc + + # + # Set various bindings for emacs mode. + + set editing-mode emacs + + $if mode=emacs + + Meta-Control-h: backward-kill-word Text after the function name is ignored + + # + # Arrow keys in keypad mode + # + #"\M-OD": backward-char + #"\M-OC": forward-char + #"\M-OA": previous-history + #"\M-OB": next-history + # + # Arrow keys in ANSI mode + # + "\M-[D": backward-char + "\M-[C": forward-char + "\M-[A": previous-history + "\M-[B": next-history + # + # Arrow keys in 8 bit keypad mode + # + #"\M-\C-OD": backward-char + #"\M-\C-OC": forward-char + #"\M-\C-OA": previous-history + #"\M-\C-OB": next-history + # + # Arrow keys in 8 bit ANSI mode + # + #"\M-\C-[D": backward-char + #"\M-\C-[C": forward-char + #"\M-\C-[A": previous-history + #"\M-\C-[B": next-history + + C-q: quoted-insert + + $endif + + # An old-style binding. This happens to be the default. + TAB: complete + + # Macros that are convenient for shell interaction + $if Bash + # edit the path + "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" + # prepare to type a quoted word -- + # insert open and close double quotes + # and move to just after the open quote + "\C-x\"": "\"\"\C-b" + # insert a backslash (testing backslash escapes + # in sequences and macros) + "\C-x\\": "\\" + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + # Add a binding to refresh the line, which is unbound + "\C-xr": redraw-current-line + # Edit variable on current line. + "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" + $endif + + # use a visible bell if one is available + set bell-style visible + + # don't strip characters to 7 bits when reading + set input-meta on + + # allow iso-latin1 characters to be inserted rather + # than converted to prefix-meta sequences + set convert-meta off + + # display characters with the eighth bit set directly + # rather than as meta-prefixed characters + set output-meta on + + # if there are more than 150 possible completions for + # a word, ask the user if he wants to see all of them + set completion-query-items 150 + + # For FTP + $if Ftp + "\C-xg": "get \M-?" + "\C-xt": "put \M-?" + "\M-.": yank-last-arg + $endif + + +File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing + +32.4 Bindable Readline Commands +=============================== + +* Menu: + +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Keyboard Macros:: Saving and re-executing typed characters +* Miscellaneous Commands:: Other miscellaneous commands. + +This section describes Readline commands that may be bound to key +sequences. Command names without an accompanying key sequence are +unbound by default. + + In the following descriptions, "point" refers to the current cursor +position, and "mark" refers to a cursor position saved by the 'set-mark' +command. The text between the point and mark is referred to as the +"region". + + +File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands + +32.4.1 Commands For Moving +-------------------------- + +'beginning-of-line (C-a)' + Move to the start of the current line. + +'end-of-line (C-e)' + Move to the end of the line. + +'forward-char (C-f)' + Move forward a character. + +'backward-char (C-b)' + Move back a character. + +'forward-word (M-f)' + Move forward to the end of the next word. Words are composed of + letters and digits. + +'backward-word (M-b)' + Move back to the start of the current or previous word. Words are + composed of letters and digits. + +'clear-screen (C-l)' + Clear the screen and redraw the current line, leaving the current + line at the top of the screen. + +'redraw-current-line ()' + Refresh the current line. By default, this is unbound. + + +File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands + +32.4.2 Commands For Manipulating The History +-------------------------------------------- + +'accept-line (Newline or Return)' + Accept the line regardless of where the cursor is. If this line is + non-empty, it may be added to the history list for future recall + with 'add_history()'. If this line is a modified history line, the + history line is restored to its original state. + +'previous-history (C-p)' + Move 'back' through the history list, fetching the previous + command. + +'next-history (C-n)' + Move 'forward' through the history list, fetching the next command. + +'beginning-of-history (M-<)' + Move to the first line in the history. + +'end-of-history (M->)' + Move to the end of the input history, i.e., the line currently + being entered. + +'reverse-search-history (C-r)' + Search backward starting at the current line and moving 'up' + through the history as necessary. This is an incremental search. + +'forward-search-history (C-s)' + Search forward starting at the current line and moving 'down' + through the the history as necessary. This is an incremental + search. + +'non-incremental-reverse-search-history (M-p)' + Search backward starting at the current line and moving 'up' + through the history as necessary using a non-incremental search for + a string supplied by the user. + +'non-incremental-forward-search-history (M-n)' + Search forward starting at the current line and moving 'down' + through the the history as necessary using a non-incremental search + for a string supplied by the user. + +'history-search-forward ()' + Search forward through the history for the string of characters + between the start of the current line and the point. This is a + non-incremental search. By default, this command is unbound. + +'history-search-backward ()' + Search backward through the history for the string of characters + between the start of the current line and the point. This is a + non-incremental search. By default, this command is unbound. + +'yank-nth-arg (M-C-y)' + Insert the first argument to the previous command (usually the + second word on the previous line) at point. With an argument N, + insert the Nth word from the previous command (the words in the + previous command begin with word 0). A negative argument inserts + the Nth word from the end of the previous command. Once the + argument N is computed, the argument is extracted as if the '!N' + history expansion had been specified. + +'yank-last-arg (M-. or M-_)' + Insert last argument to the previous command (the last word of the + previous history entry). With a numeric argument, behave exactly + like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back + through the history list, inserting the last word (or the word + specified by the argument to the first call) of each line in turn. + Any numeric argument supplied to these successive calls determines + the direction to move through the history. A negative argument + switches the direction through the history (back or forward). The + history expansion facilities are used to extract the last argument, + as if the '!$' history expansion had been specified. + + +File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands + +32.4.3 Commands For Changing Text +--------------------------------- + +'delete-char (C-d)' + Delete the character at point. If point is at the beginning of the + line, there are no characters in the line, and the last character + typed was not bound to 'delete-char', then return EOF. + +'backward-delete-char (Rubout)' + Delete the character behind the cursor. A numeric argument means + to kill the characters instead of deleting them. + +'forward-backward-delete-char ()' + Delete the character under the cursor, unless the cursor is at the + end of the line, in which case the character behind the cursor is + deleted. By default, this is not bound to a key. + +'quoted-insert (C-q or C-v)' + Add the next character typed to the line verbatim. This is how to + insert key sequences like 'C-q', for example. + +'tab-insert (M-)' + Insert a tab character. + +'self-insert (a, b, A, 1, !, ...)' + Insert yourself. + +'transpose-chars (C-t)' + Drag the character before the cursor forward over the character at + the cursor, moving the cursor forward as well. If the insertion + point is at the end of the line, then this transposes the last two + characters of the line. Negative arguments have no effect. + +'transpose-words (M-t)' + Drag the word before point past the word after point, moving point + past that word as well. If the insertion point is at the end of + the line, this transposes the last two words on the line. + +'upcase-word (M-u)' + Uppercase the current (or following) word. With a negative + argument, uppercase the previous word, but do not move the cursor. + +'downcase-word (M-l)' + Lowercase the current (or following) word. With a negative + argument, lowercase the previous word, but do not move the cursor. + +'capitalize-word (M-c)' + Capitalize the current (or following) word. With a negative + argument, capitalize the previous word, but do not move the cursor. + +'overwrite-mode ()' + Toggle overwrite mode. With an explicit positive numeric argument, + switches to overwrite mode. With an explicit non-positive numeric + argument, switches to insert mode. This command affects only + 'emacs' mode; 'vi' mode does overwrite differently. Each call to + 'readline()' starts in insert mode. + + In overwrite mode, characters bound to 'self-insert' replace the + text at point rather than pushing the text to the right. + Characters bound to 'backward-delete-char' replace the character + before point with a space. + + By default, this command is unbound. + + +File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands + +32.4.4 Killing And Yanking +-------------------------- + +'kill-line (C-k)' + Kill the text from point to the end of the line. + +'backward-kill-line (C-x Rubout)' + Kill backward to the beginning of the line. + +'unix-line-discard (C-u)' + Kill backward from the cursor to the beginning of the current line. + +'kill-whole-line ()' + Kill all characters on the current line, no matter where point is. + By default, this is unbound. + +'kill-word (M-d)' + Kill from point to the end of the current word, or if between + words, to the end of the next word. Word boundaries are the same + as 'forward-word'. + +'backward-kill-word (M-)' + Kill the word behind point. Word boundaries are the same as + 'backward-word'. + +'unix-word-rubout (C-w)' + Kill the word behind point, using white space as a word boundary. + The killed text is saved on the kill-ring. + +'unix-filename-rubout ()' + Kill the word behind point, using white space and the slash + character as the word boundaries. The killed text is saved on the + kill-ring. + +'delete-horizontal-space ()' + Delete all spaces and tabs around point. By default, this is + unbound. + +'kill-region ()' + Kill the text in the current region. By default, this command is + unbound. + +'copy-region-as-kill ()' + Copy the text in the region to the kill buffer, so it can be yanked + right away. By default, this command is unbound. + +'copy-backward-word ()' + Copy the word before point to the kill buffer. The word boundaries + are the same as 'backward-word'. By default, this command is + unbound. + +'copy-forward-word ()' + Copy the word following point to the kill buffer. The word + boundaries are the same as 'forward-word'. By default, this + command is unbound. + +'yank (C-y)' + Yank the top of the kill ring into the buffer at point. + +'yank-pop (M-y)' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is 'yank' or 'yank-pop'. + + +File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands + +32.4.5 Specifying Numeric Arguments +----------------------------------- + +'digit-argument (M-0, M-1, ... M--)' + Add this digit to the argument already accumulating, or start a new + argument. 'M--' starts a negative argument. + +'universal-argument ()' + This is another way to specify an argument. If this command is + followed by one or more digits, optionally with a leading minus + sign, those digits define the argument. If the command is followed + by digits, executing 'universal-argument' again ends the numeric + argument, but is otherwise ignored. As a special case, if this + command is immediately followed by a character that is neither a + digit or minus sign, the argument count for the next command is + multiplied by four. The argument count is initially one, so + executing this function the first time makes the argument count + four, a second time makes the argument count sixteen, and so on. + By default, this is not bound to a key. + + +File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands + +32.4.6 Letting Readline Type For You +------------------------------------ + +'complete ()' + Attempt to perform completion on the text before point. The actual + completion performed is application-specific. The default is + filename completion. + +'possible-completions (M-?)' + List the possible completions of the text before point. When + displaying completions, Readline sets the number of columns used + for display to the value of 'completion-display-width', the value + of the environment variable 'COLUMNS', or the screen width, in that + order. + +'insert-completions (M-*)' + Insert all completions of the text before point that would have + been generated by 'possible-completions'. + +'menu-complete ()' + Similar to 'complete', but replaces the word to be completed with a + single match from the list of possible completions. Repeated + execution of 'menu-complete' steps through the list of possible + completions, inserting each match in turn. At the end of the list + of completions, the bell is rung (subject to the setting of + 'bell-style') and the original text is restored. An argument of N + moves N positions forward in the list of matches; a negative + argument may be used to move backward through the list. This + command is intended to be bound to , but is unbound by + default. + +'menu-complete-backward ()' + Identical to 'menu-complete', but moves backward through the list + of possible completions, as if 'menu-complete' had been given a + negative argument. + +'delete-char-or-list ()' + Deletes the character under the cursor if not at the beginning or + end of the line (like 'delete-char'). If at the end of the line, + behaves identically to 'possible-completions'. This command is + unbound by default. + + +File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands + +32.4.7 Keyboard Macros +---------------------- + +'start-kbd-macro (C-x ()' + Begin saving the characters typed into the current keyboard macro. + +'end-kbd-macro (C-x ))' + Stop saving the characters typed into the current keyboard macro + and save the definition. + +'call-last-kbd-macro (C-x e)' + Re-execute the last keyboard macro defined, by making the + characters in the macro appear as if typed at the keyboard. + + +File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands + +32.4.8 Some Miscellaneous Commands +---------------------------------- + +'re-read-init-file (C-x C-r)' + Read in the contents of the INPUTRC file, and incorporate any + bindings or variable assignments found there. + +'abort (C-g)' + Abort the current editing command and ring the terminal's bell + (subject to the setting of 'bell-style'). + +'do-uppercase-version (M-a, M-b, M-X, ...)' + If the metafied character X is lowercase, run the command that is + bound to the corresponding uppercase character. + +'prefix-meta ()' + Metafy the next character typed. This is for keyboards without a + meta key. Typing ' f' is equivalent to typing 'M-f'. + +'undo (C-_ or C-x C-u)' + Incremental undo, separately remembered for each line. + +'revert-line (M-r)' + Undo all changes made to this line. This is like executing the + 'undo' command enough times to get back to the beginning. + +'tilde-expand (M-~)' + Perform tilde expansion on the current word. + +'set-mark (C-@)' + Set the mark to the point. If a numeric argument is supplied, the + mark is set to that position. + +'exchange-point-and-mark (C-x C-x)' + Swap the point with the mark. The current cursor position is set + to the saved position, and the old cursor position is saved as the + mark. + +'character-search (C-])' + A character is read and point is moved to the next occurrence of + that character. A negative count searches for previous + occurrences. + +'character-search-backward (M-C-])' + A character is read and point is moved to the previous occurrence + of that character. A negative count searches for subsequent + occurrences. + +'skip-csi-sequence ()' + Read enough characters to consume a multi-key sequence such as + those defined for keys like Home and End. Such sequences begin + with a Control Sequence Indicator (CSI), usually ESC-[. If this + sequence is bound to "\e[", keys producing such sequences will have + no effect unless explicitly bound to a readline command, instead of + inserting stray characters into the editing buffer. This is + unbound by default, but usually bound to ESC-[. + +'insert-comment (M-#)' + Without a numeric argument, the value of the 'comment-begin' + variable is inserted at the beginning of the current line. If a + numeric argument is supplied, this command acts as a toggle: if the + characters at the beginning of the line do not match the value of + 'comment-begin', the value is inserted, otherwise the characters in + 'comment-begin' are deleted from the beginning of the line. In + either case, the line is accepted as if a newline had been typed. + +'dump-functions ()' + Print all of the functions and their key bindings to the Readline + output stream. If a numeric argument is supplied, the output is + formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +'dump-variables ()' + Print all of the settable variables and their values to the + Readline output stream. If a numeric argument is supplied, the + output is formatted in such a way that it can be made part of an + INPUTRC file. This command is unbound by default. + +'dump-macros ()' + Print all of the Readline key sequences bound to macros and the + strings they output. If a numeric argument is supplied, the output + is formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +'emacs-editing-mode (C-e)' + When in 'vi' command mode, this causes a switch to 'emacs' editing + mode. + +'vi-editing-mode (M-C-j)' + When in 'emacs' editing mode, this causes a switch to 'vi' editing + mode. + + +File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing + +32.5 Readline vi Mode +===================== + +While the Readline library does not have a full set of 'vi' editing +functions, it does contain enough to allow simple editing of the line. +The Readline 'vi' mode behaves as specified in the POSIX standard. + + In order to switch interactively between 'emacs' and 'vi' editing +modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi' +mode and to vi-editing-mode in 'emacs' mode). The Readline default is +'emacs' mode. + + When you enter a line in 'vi' mode, you are already placed in +'insertion' mode, as if you had typed an 'i'. Pressing switches +you into 'command' mode, where you can edit the text of the line with +the standard 'vi' movement keys, move to previous history lines with 'k' +and subsequent lines with 'j', and so forth. + + +File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top + +33 Using History Interactively +****************************** + +This chapter describes how to use the GNU History Library interactively, +from a user's standpoint. It should be considered a user's guide. For +information on using the GNU History Library in your own programs, *note +(history)Programming with GNU History::. + +* Menu: + +* History Interaction:: What it feels like using History as a user. + + +File: gdb.info, Node: History Interaction, Up: Using History Interactively + +33.1 History Expansion +====================== + +The History library provides a history expansion feature that is similar +to the history expansion provided by 'csh'. This section describes the +syntax used to manipulate the history information. + + History expansions introduce words from the history list into the +input stream, making it easy to repeat commands, insert the arguments to +a previous command into the current input line, or fix errors in +previous commands quickly. + + History expansion takes place in two parts. The first is to +determine which line from the history list should be used during +substitution. The second is to select portions of that line for +inclusion into the current one. The line selected from the history is +called the "event", and the portions of that line that are acted upon +are called "words". Various "modifiers" are available to manipulate the +selected words. The line is broken into words in the same fashion that +Bash does, so that several words surrounded by quotes are considered one +word. History expansions are introduced by the appearance of the +history expansion character, which is '!' by default. + +* Menu: + +* Event Designators:: How to specify which history line to use. +* Word Designators:: Specifying which words are of interest. +* Modifiers:: Modifying the results of substitution. + + +File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction + +33.1.1 Event Designators +------------------------ + +An event designator is a reference to a command line entry in the +history list. Unless the reference is absolute, events are relative to +the current position in the history list. + +'!' + Start a history substitution, except when followed by a space, tab, + the end of the line, or '='. + +'!N' + Refer to command line N. + +'!-N' + Refer to the command N lines back. + +'!!' + Refer to the previous command. This is a synonym for '!-1'. + +'!STRING' + Refer to the most recent command preceding the current position in + the history list starting with STRING. + +'!?STRING[?]' + Refer to the most recent command preceding the current position in + the history list containing STRING. The trailing '?' may be + omitted if the STRING is followed immediately by a newline. + +'^STRING1^STRING2^' + Quick Substitution. Repeat the last command, replacing STRING1 + with STRING2. Equivalent to '!!:s/STRING1/STRING2/'. + +'!#' + The entire command line typed so far. + + +File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction + +33.1.2 Word Designators +----------------------- + +Word designators are used to select desired words from the event. A ':' +separates the event specification from the word designator. It may be +omitted if the word designator begins with a '^', '$', '*', '-', or '%'. +Words are numbered from the beginning of the line, with the first word +being denoted by 0 (zero). Words are inserted into the current line +separated by single spaces. + + For example, + +'!!' + designates the preceding command. When you type this, the + preceding command is repeated in toto. + +'!!:$' + designates the last argument of the preceding command. This may be + shortened to '!$'. + +'!fi:2' + designates the second argument of the most recent command starting + with the letters 'fi'. + + Here are the word designators: + +'0 (zero)' + The '0'th word. For many applications, this is the command word. + +'N' + The Nth word. + +'^' + The first argument; that is, word 1. + +'$' + The last argument. + +'%' + The word matched by the most recent '?STRING?' search. + +'X-Y' + A range of words; '-Y' abbreviates '0-Y'. + +'*' + All of the words, except the '0'th. This is a synonym for '1-$'. + It is not an error to use '*' if there is just one word in the + event; the empty string is returned in that case. + +'X*' + Abbreviates 'X-$' + +'X-' + Abbreviates 'X-$' like 'X*', but omits the last word. + + If a word designator is supplied without an event specification, the +previous command is used as the event. + + +File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction + +33.1.3 Modifiers +---------------- + +After the optional word designator, you can add a sequence of one or +more of the following modifiers, each preceded by a ':'. + +'h' + Remove a trailing pathname component, leaving only the head. + +'t' + Remove all leading pathname components, leaving the tail. + +'r' + Remove a trailing suffix of the form '.SUFFIX', leaving the + basename. + +'e' + Remove all but the trailing suffix. + +'p' + Print the new command but do not execute it. + +'s/OLD/NEW/' + Substitute NEW for the first occurrence of OLD in the event line. + Any delimiter may be used in place of '/'. The delimiter may be + quoted in OLD and NEW with a single backslash. If '&' appears in + NEW, it is replaced by OLD. A single backslash will quote the '&'. + The final delimiter is optional if it is the last character on the + input line. + +'&' + Repeat the previous substitution. + +'g' +'a' + Cause changes to be applied over the entire event line. Used in + conjunction with 's', as in 'gs/OLD/NEW/', or with '&'. + +'G' + Apply the following 's' modifier once to each word in the event. + + +File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top + +Appendix A In Memoriam +********************** + +The GDB project mourns the loss of the following long-time contributors: + +'Fred Fish' + Fred was a long-standing contributor to GDB (1991-2006), and to + Free Software in general. Outside of GDB, he was known in the + Amiga world for his series of Fish Disks, and the GeekGadget + project. + +'Michael Snyder' + Michael was one of the Global Maintainers of the GDB project, with + contributions recorded as early as 1996, until 2011. In addition + to his day to day participation, he was a large driving force + behind adding Reverse Debugging to GDB. + + Beyond their technical contributions to the project, they were also +enjoyable members of the Free Software Community. We will miss them. + + +File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top + +Appendix B Formatting Documentation +*********************************** + +The GDB 4 release includes an already-formatted reference card, ready +for printing with PostScript or Ghostscript, in the 'gdb' subdirectory +of the main source directory(1). If you can use PostScript or +Ghostscript with your printer, you can print the reference card +immediately with 'refcard.ps'. + + The release also includes the source for the reference card. You can +format it, using TeX, by typing: + + make refcard.dvi + + The GDB reference card is designed to print in "landscape" mode on US +"letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches +high. You will need to specify this form of printing as an option to +your DVI output program. + + All the documentation for GDB comes as part of the machine-readable +distribution. The documentation is written in Texinfo format, which is +a documentation system that uses a single source file to produce both +on-line information and a printed manual. You can use one of the Info +formatting commands to create the on-line version of the documentation +and TeX (or 'texi2roff') to typeset the printed version. + + GDB includes an already formatted copy of the on-line Info version of +this manual in the 'gdb' subdirectory. The main Info file is +'gdb-7.7.1/gdb/gdb.info', and it refers to subordinate files matching +'gdb.info*' in the same directory. If necessary, you can print out +these files, or read them with any editor; but they are easier to read +using the 'info' subsystem in GNU Emacs or the standalone 'info' +program, available as part of the GNU Texinfo distribution. + + If you want to format these Info files yourself, you need one of the +Info formatting programs, such as 'texinfo-format-buffer' or 'makeinfo'. + + If you have 'makeinfo' installed, and are in the top level GDB source +directory ('gdb-7.7.1', in the case of version 7.7.1), you can make the +Info file by typing: + + cd gdb + make gdb.info + + If you want to typeset and print copies of this manual, you need TeX, +a program to print its DVI output files, and 'texinfo.tex', the Texinfo +definitions file. + + TeX is a typesetting program; it does not print files directly, but +produces output files called DVI files. To print a typeset document, +you need a program to print DVI files. If your system has TeX +installed, chances are it has such a program. The precise command to +use depends on your system; 'lpr -d' is common; another (for PostScript +devices) is 'dvips'. The DVI print command may require a file name +without any extension or a '.dvi' extension. + + TeX also requires a macro definitions file called 'texinfo.tex'. +This file tells TeX how to typeset a document written in Texinfo format. +On its own, TeX cannot either read or typeset a Texinfo file. +'texinfo.tex' is distributed with GDB and is located in the +'gdb-VERSION-NUMBER/texinfo' directory. + + If you have TeX and a DVI printer program installed, you can typeset +and print this manual. First switch to the 'gdb' subdirectory of the +main source directory (for example, to 'gdb-7.7.1/gdb') and type: + + make gdb.dvi + + Then give 'gdb.dvi' to your DVI printing program. + + ---------- Footnotes ---------- + + (1) In 'gdb-7.7.1/gdb/refcard.ps' of the version 7.7.1 release. + + +File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top + +Appendix C Installing GDB +************************* + +* Menu: + +* Requirements:: Requirements for building GDB +* Running Configure:: Invoking the GDB 'configure' script +* Separate Objdir:: Compiling GDB in another directory +* Config Names:: Specifying names for hosts and targets +* Configure Options:: Summary of options for configure +* System-wide configuration:: Having a system-wide init file + + +File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB + +C.1 Requirements for Building GDB +================================= + +Building GDB requires various tools and packages to be available. Other +packages will be used only if they are found. + +Tools/Packages Necessary for Building GDB +========================================= + +ISO C90 compiler + GDB is written in ISO C90. It should be buildable with any working + C90 compiler, e.g. GCC. + +Tools/Packages Optional for Building GDB +======================================== + +Expat + GDB can use the Expat XML parsing library. This library may be + included with your operating system distribution; if it is not, you + can get the latest version from . + The 'configure' script will search for this library in several + standard locations; if it is installed in an unusual path, you can + use the '--with-libexpat-prefix' option to specify its location. + + Expat is used for: + + * Remote protocol memory maps (*note Memory Map Format::) + * Target descriptions (*note Target Descriptions::) + * Remote shared library lists (*Note Library List Format::, or + alternatively *note Library List Format for SVR4 Targets::) + * MS-Windows shared libraries (*note Shared Libraries::) + * Traceframe info (*note Traceframe Info Format::) + * Branch trace (*note Branch Trace Format::) + +zlib + GDB will use the 'zlib' library, if available, to read compressed + debug sections. Some linkers, such as GNU gold, are capable of + producing binaries with compressed debug sections. If GDB is + compiled with 'zlib', it will be able to read the debug information + in such binaries. + + The 'zlib' library is likely included with your operating system + distribution; if it is not, you can get the latest version from + . + +iconv + GDB's features related to character sets (*note Character Sets::) + require a functioning 'iconv' implementation. If you are on a GNU + system, then this is provided by the GNU C Library. Some other + systems also provide a working 'iconv'. + + If GDB is using the 'iconv' program which is installed in a + non-standard place, you will need to tell GDB where to find it. + This is done with '--with-iconv-bin' which specifies the directory + that contains the 'iconv' program. + + On systems without 'iconv', you can install GNU Libiconv. If you + have previously installed Libiconv, you can use the + '--with-libiconv-prefix' option to configure. + + GDB's top-level 'configure' and 'Makefile' will arrange to build + Libiconv if a directory named 'libiconv' appears in the top-most + source directory. If Libiconv is built this way, and if the + operating system does not provide a suitable 'iconv' + implementation, then the just-built library will automatically be + used by GDB. One easy way to set this up is to download GNU + Libiconv, unpack it, and then rename the directory holding the + Libiconv source code to 'libiconv'. + + +File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB + +C.2 Invoking the GDB 'configure' Script +======================================= + +GDB comes with a 'configure' script that automates the process of +preparing GDB for installation; you can then use 'make' to build the +'gdb' program. + + The GDB distribution includes all the source code you need for GDB in +a single directory, whose name is usually composed by appending the +version number to 'gdb'. + + For example, the GDB version 7.7.1 distribution is in the 'gdb-7.7.1' +directory. That directory contains: + +'gdb-7.7.1/configure (and supporting files)' + script for configuring GDB and all its supporting libraries + +'gdb-7.7.1/gdb' + the source specific to GDB itself + +'gdb-7.7.1/bfd' + source for the Binary File Descriptor library + +'gdb-7.7.1/include' + GNU include files + +'gdb-7.7.1/libiberty' + source for the '-liberty' free software library + +'gdb-7.7.1/opcodes' + source for the library of opcode tables and disassemblers + +'gdb-7.7.1/readline' + source for the GNU command-line interface + +'gdb-7.7.1/glob' + source for the GNU filename pattern-matching subroutine + +'gdb-7.7.1/mmalloc' + source for the GNU memory-mapped malloc package + + The simplest way to configure and build GDB is to run 'configure' +from the 'gdb-VERSION-NUMBER' source directory, which in this example is +the 'gdb-7.7.1' directory. + + First switch to the 'gdb-VERSION-NUMBER' source directory if you are +not already in it; then run 'configure'. Pass the identifier for the +platform on which GDB will run as an argument. + + For example: + + cd gdb-7.7.1 + ./configure HOST + make + +where HOST is an identifier such as 'sun4' or 'decstation', that +identifies the platform where GDB will run. (You can often leave off +HOST; 'configure' tries to guess the correct value by examining your +system.) + + Running 'configure HOST' and then running 'make' builds the 'bfd', +'readline', 'mmalloc', and 'libiberty' libraries, then 'gdb' itself. +The configured source files, and the binaries, are left in the +corresponding source directories. + + 'configure' is a Bourne-shell ('/bin/sh') script; if your system does +not recognize this automatically when you run a different shell, you may +need to run 'sh' on it explicitly: + + sh configure HOST + + If you run 'configure' from a directory that contains source +directories for multiple libraries or programs, such as the 'gdb-7.7.1' +source directory for version 7.7.1, 'configure' creates configuration +files for every directory level underneath (unless you tell it not to, +with the '--norecursion' option). + + You should run the 'configure' script from the top directory in the +source tree, the 'gdb-VERSION-NUMBER' directory. If you run 'configure' +from one of the subdirectories, you will configure only that +subdirectory. That is usually not what you want. In particular, if you +run the first 'configure' from the 'gdb' subdirectory of the +'gdb-VERSION-NUMBER' directory, you will omit the configuration of +'bfd', 'readline', and other sibling directories of the 'gdb' +subdirectory. This leads to build errors about missing include files +such as 'bfd/bfd.h'. + + You can install 'gdb' anywhere; it has no hardwired paths. However, +you should make sure that the shell on your path (named by the 'SHELL' +environment variable) is publicly readable. Remember that GDB uses the +shell to start your program--some systems refuse to let GDB debug child +processes whose programs are not readable. + + +File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB + +C.3 Compiling GDB in Another Directory +====================================== + +If you want to run GDB versions for several host or target machines, you +need a different 'gdb' compiled for each combination of host and target. +'configure' is designed to make this easy by allowing you to generate +each configuration in a separate subdirectory, rather than in the source +directory. If your 'make' program handles the 'VPATH' feature (GNU +'make' does), running 'make' in each of these directories builds the +'gdb' program specified there. + + To build 'gdb' in a separate directory, run 'configure' with the +'--srcdir' option to specify where to find the source. (You also need +to specify a path to find 'configure' itself from your working +directory. If the path to 'configure' would be the same as the argument +to '--srcdir', you can leave out the '--srcdir' option; it is assumed.) + + For example, with version 7.7.1, you can build GDB in a separate +directory for a Sun 4 like this: + + cd gdb-7.7.1 + mkdir ../gdb-sun4 + cd ../gdb-sun4 + ../gdb-7.7.1/configure sun4 + make + + When 'configure' builds a configuration using a remote source +directory, it creates a tree for the binaries with the same structure +(and using the same names) as the tree under the source directory. In +the example, you'd find the Sun 4 library 'libiberty.a' in the directory +'gdb-sun4/libiberty', and GDB itself in 'gdb-sun4/gdb'. + + Make sure that your path to the 'configure' script has just one +instance of 'gdb' in it. If your path to 'configure' looks like +'../gdb-7.7.1/gdb/configure', you are configuring only one subdirectory +of GDB, not the whole package. This leads to build errors about missing +include files such as 'bfd/bfd.h'. + + One popular reason to build several GDB configurations in separate +directories is to configure GDB for cross-compiling (where GDB runs on +one machine--the "host"--while debugging programs that run on another +machine--the "target"). You specify a cross-debugging target by giving +the '--target=TARGET' option to 'configure'. + + When you run 'make' to build a program or library, you must run it in +a configured directory--whatever directory you were in when you called +'configure' (or one of its subdirectories). + + The 'Makefile' that 'configure' generates in each source directory +also runs recursively. If you type 'make' in a source directory such as +'gdb-7.7.1' (or in a separate configured directory configured with +'--srcdir=DIRNAME/gdb-7.7.1'), you will build all the required +libraries, and then build GDB. + + When you have multiple hosts or targets configured in separate +directories, you can run 'make' on them in parallel (for example, if +they are NFS-mounted on each of the hosts); they will not interfere with +each other. + + +File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB + +C.4 Specifying Names for Hosts and Targets +========================================== + +The specifications used for hosts and targets in the 'configure' script +are based on a three-part naming scheme, but some short predefined +aliases are also supported. The full naming scheme encodes three pieces +of information in the following pattern: + + ARCHITECTURE-VENDOR-OS + + For example, you can use the alias 'sun4' as a HOST argument, or as +the value for TARGET in a '--target=TARGET' option. The equivalent full +name is 'sparc-sun-sunos4'. + + The 'configure' script accompanying GDB does not provide any query +facility to list all supported host and target names or aliases. +'configure' calls the Bourne shell script 'config.sub' to map +abbreviations to full names; you can read the script, if you wish, or +you can use it to test your guesses on abbreviations--for example: + + % sh config.sub i386-linux + i386-pc-linux-gnu + % sh config.sub alpha-linux + alpha-unknown-linux-gnu + % sh config.sub hp9k700 + hppa1.1-hp-hpux + % sh config.sub sun4 + sparc-sun-sunos4.1.1 + % sh config.sub sun3 + m68k-sun-sunos4.1.1 + % sh config.sub i986v + Invalid configuration `i986v': machine `i986v' not recognized + +'config.sub' is also distributed in the GDB source directory +('gdb-7.7.1', for version 7.7.1). + + +File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB + +C.5 'configure' Options +======================= + +Here is a summary of the 'configure' options and arguments that are most +often useful for building GDB. 'configure' also has several other +options not listed here. *note (configure.info)What Configure Does::, +for a full explanation of 'configure'. + + configure [--help] + [--prefix=DIR] + [--exec-prefix=DIR] + [--srcdir=DIRNAME] + [--norecursion] [--rm] + [--target=TARGET] + HOST + +You may introduce options with a single '-' rather than '--' if you +prefer; but you may abbreviate option names if you use '--'. + +'--help' + Display a quick summary of how to invoke 'configure'. + +'--prefix=DIR' + Configure the source to install programs and files under directory + 'DIR'. + +'--exec-prefix=DIR' + Configure the source to install programs under directory 'DIR'. + +'--srcdir=DIRNAME' + *Warning: using this option requires GNU 'make', or another 'make' + that implements the 'VPATH' feature.* + Use this option to make configurations in directories separate from + the GDB source directories. Among other things, you can use this + to build (or maintain) several configurations simultaneously, in + separate directories. 'configure' writes configuration-specific + files in the current directory, but arranges for them to use the + source in the directory DIRNAME. 'configure' creates directories + under the working directory in parallel to the source directories + below DIRNAME. + +'--norecursion' + Configure only the directory level where 'configure' is executed; + do not propagate configuration to subdirectories. + +'--target=TARGET' + Configure GDB for cross-debugging programs running on the specified + TARGET. Without this option, GDB is configured to debug programs + that run on the same machine (HOST) as GDB itself. + + There is no convenient way to generate a list of all available + targets. + +'HOST ...' + Configure GDB to run on the specified HOST. + + There is no convenient way to generate a list of all available + hosts. + + There are many other options available as well, but they are +generally needed for special purposes only. + + +File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB + +C.6 System-wide configuration and settings +========================================== + +GDB can be configured to have a system-wide init file; this file will be +read and executed at startup (*note What GDB does during startup: +Startup.). + + Here is the corresponding configure option: + +'--with-system-gdbinit=FILE' + Specify that the default location of the system-wide init file is + FILE. + + If GDB has been configured with the option '--prefix=$prefix', it may +be subject to relocation. Two possible cases: + + * If the default location of this init file contains '$prefix', it + will be subject to relocation. Suppose that the configure options + are '--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit'; + if GDB is moved from '$prefix' to '$install', the system init file + is looked for as '$install/etc/gdbinit' instead of + '$prefix/etc/gdbinit'. + + * By contrast, if the default location does not contain the prefix, + it will not be relocated. E.g. if GDB has been configured with + '--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit', + then GDB will always look for '/usr/share/gdb/gdbinit', wherever + GDB is installed. + + If the configured location of the system-wide init file (as given by +the '--with-system-gdbinit' option at configure time) is in the +data-directory (as specified by '--with-gdb-datadir' at configure time) +or in one of its subdirectories, then GDB will look for the system-wide +init file in the directory specified by the '--data-directory' +command-line option. Note that the system-wide init file is only read +once, during GDB initialization. If the data-directory is changed after +GDB has started with the 'set data-directory' command, the file will not +be reread. + +* Menu: + +* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts + + +File: gdb.info, Node: System-wide Configuration Scripts, Up: System-wide configuration + +C.6.1 Installed System-wide Configuration Scripts +------------------------------------------------- + +The 'system-gdbinit' directory, located inside the data-directory (as +specified by '--with-gdb-datadir' at configure time) contains a number +of scripts which can be used as system-wide init files. To +automatically source those scripts at startup, GDB should be configured +with '--with-system-gdbinit'. Otherwise, any user should be able to +source them by hand as needed. + + The following scripts are currently available: + + * 'elinos.py' This script is useful when debugging a program on an + ELinOS target. It takes advantage of the environment variables + defined in a standard ELinOS environment in order to determine the + location of the system shared libraries, and then sets the + 'solib-absolute-prefix' and 'solib-search-path' variables + appropriately. + + * 'wrs-linux.py' This script is useful when debugging a program on a + target running Wind River Linux. It expects the 'ENV_PREFIX' to be + set to the host-side sysroot used by the target system. + + +File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top + +Appendix D Maintenance Commands +******************************* + +In addition to commands intended for GDB users, GDB includes a number of +commands intended for GDB developers, that are not documented elsewhere +in this manual. These commands are provided here for reference. (For +commands that turn on debugging messages, see *note Debugging Output::.) + +'maint agent [-at LOCATION,] EXPRESSION' +'maint agent-eval [-at LOCATION,] EXPRESSION' + Translate the given EXPRESSION into remote agent bytecodes. This + command is useful for debugging the Agent Expression mechanism + (*note Agent Expressions::). The 'agent' version produces an + expression useful for data collection, such as by tracepoints, + while 'maint agent-eval' produces an expression that evaluates + directly to a result. For instance, a collection expression for + 'globa + globb' will include bytecodes to record four bytes of + memory at each of the addresses of 'globa' and 'globb', while + discarding the result of the addition, while an evaluation + expression will do the addition and return the sum. If '-at' is + given, generate remote agent bytecode for LOCATION. If not, + generate remote agent bytecode for current frame PC address. + +'maint agent-printf FORMAT,EXPR,...' + Translate the given format string and list of argument expressions + into remote agent bytecodes and display them as a disassembled + list. This command is useful for debugging the agent version of + dynamic printf (*note Dynamic Printf::). + +'maint info breakpoints' + Using the same format as 'info breakpoints', display both the + breakpoints you've set explicitly, and those GDB is using for + internal purposes. Internal breakpoints are shown with negative + breakpoint numbers. The type column identifies what kind of + breakpoint is shown: + + 'breakpoint' + Normal, explicitly set breakpoint. + + 'watchpoint' + Normal, explicitly set watchpoint. + + 'longjmp' + Internal breakpoint, used to handle correctly stepping through + 'longjmp' calls. + + 'longjmp resume' + Internal breakpoint at the target of a 'longjmp'. + + 'until' + Temporary internal breakpoint used by the GDB 'until' command. + + 'finish' + Temporary internal breakpoint used by the GDB 'finish' + command. + + 'shlib events' + Shared library events. + +'maint info bfds' + This prints information about each 'bfd' object that is known to + GDB. *Note BFD: (bfd)Top. + +'set displaced-stepping' +'show displaced-stepping' + Control whether or not GDB will do "displaced stepping" if the + target supports it. Displaced stepping is a way to single-step + over breakpoints without removing them from the inferior, by + executing an out-of-line copy of the instruction that was + originally at the breakpoint location. It is also known as + out-of-line single-stepping. + + 'set displaced-stepping on' + If the target architecture supports it, GDB will use displaced + stepping to step over breakpoints. + + 'set displaced-stepping off' + GDB will not use displaced stepping to step over breakpoints, + even if such is supported by the target architecture. + + 'set displaced-stepping auto' + This is the default mode. GDB will use displaced stepping + only if non-stop mode is active (*note Non-Stop Mode::) and + the target architecture supports displaced stepping. + +'maint check-psymtabs' + Check the consistency of currently expanded psymtabs versus + symtabs. Use this to check, for example, whether a symbol is in + one but not the other. + +'maint check-symtabs' + Check the consistency of currently expanded symtabs. + +'maint expand-symtabs [REGEXP]' + Expand symbol tables. If REGEXP is specified, only expand symbol + tables for file names matching REGEXP. + +'maint cplus first_component NAME' + Print the first C++ class/namespace component of NAME. + +'maint cplus namespace' + Print the list of possible C++ namespaces. + +'maint demangle NAME' + Demangle a C++ or Objective-C mangled NAME. + +'maint deprecate COMMAND [REPLACEMENT]' +'maint undeprecate COMMAND' + Deprecate or undeprecate the named COMMAND. Deprecated commands + cause GDB to issue a warning when you use them. The optional + argument REPLACEMENT says which newer command should be used in + favor of the deprecated one; if it is given, GDB will mention the + replacement as part of the warning. + +'maint dump-me' + Cause a fatal signal in the debugger and force it to dump its core. + This is supported only on systems which support aborting a program + with the 'SIGQUIT' signal. + +'maint internal-error [MESSAGE-TEXT]' +'maint internal-warning [MESSAGE-TEXT]' + Cause GDB to call the internal function 'internal_error' or + 'internal_warning' and hence behave as though an internal error or + internal warning has been detected. In addition to reporting the + internal problem, these functions give the user the opportunity to + either quit GDB or create a core file of the current GDB session. + + These commands take an optional parameter MESSAGE-TEXT that is used + as the text of the error or warning message. + + Here's an example of using 'internal-error': + + (gdb) maint internal-error testing, 1, 2 + .../maint.c:121: internal-error: testing, 1, 2 + A problem internal to GDB has been detected. Further + debugging may prove unreliable. + Quit this debugging session? (y or n) n + Create a core file? (y or n) n + (gdb) + +'maint set internal-error ACTION [ask|yes|no]' +'maint show internal-error ACTION' +'maint set internal-warning ACTION [ask|yes|no]' +'maint show internal-warning ACTION' + When GDB reports an internal problem (error or warning) it gives + the user the opportunity to both quit GDB and create a core file of + the current GDB session. These commands let you override the + default behaviour for each particular ACTION, described in the + table below. + + 'quit' + You can specify that GDB should always (yes) or never (no) + quit. The default is to ask the user what to do. + + 'corefile' + You can specify that GDB should always (yes) or never (no) + create a core file. The default is to ask the user what to + do. + +'maint packet TEXT' + If GDB is talking to an inferior via the serial protocol, then this + command sends the string TEXT to the inferior, and displays the + response packet. GDB supplies the initial '$' character, the + terminating '#' character, and the checksum. + +'maint print architecture [FILE]' + Print the entire architecture configuration. The optional argument + FILE names the file where the output goes. + +'maint print c-tdesc' + Print the current target description (*note Target Descriptions::) + as a C source file. The created source file can be used in GDB + when an XML parser is not available to parse the description. + +'maint print dummy-frames' + Prints the contents of GDB's internal dummy-frame stack. + + (gdb) b add + ... + (gdb) print add(2,3) + Breakpoint 2, add (a=2, b=3) at ... + 58 return (a + b); + The program being debugged stopped while in a function called from GDB. + ... + (gdb) maint print dummy-frames + 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 + top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c} + call_lo=0x01014000 call_hi=0x01014001 + (gdb) + + Takes an optional file parameter. + +'maint print registers [FILE]' +'maint print raw-registers [FILE]' +'maint print cooked-registers [FILE]' +'maint print register-groups [FILE]' +'maint print remote-registers [FILE]' + Print GDB's internal register data structures. + + The command 'maint print raw-registers' includes the contents of + the raw register cache; the command 'maint print cooked-registers' + includes the (cooked) value of all registers, including registers + which aren't available on the target nor visible to user; the + command 'maint print register-groups' includes the groups that each + register is a member of; and the command 'maint print + remote-registers' includes the remote target's register numbers and + offsets in the 'G' packets. + + These commands take an optional parameter, a file name to which to + write the information. + +'maint print reggroups [FILE]' + Print GDB's internal register group data structures. The optional + argument FILE tells to what file to write the information. + + The register groups info looks like this: + + (gdb) maint print reggroups + Group Type + general user + float user + all user + vector user + system user + save internal + restore internal + +'flushregs' + This command forces GDB to flush its internal register cache. + +'maint print objfiles [REGEXP]' + Print a dump of all known object files. If REGEXP is specified, + only print object files whose names match REGEXP. For each object + file, this command prints its name, address in memory, and all of + its psymtabs and symtabs. + +'maint print section-scripts [REGEXP]' + Print a dump of scripts specified in the '.debug_gdb_section' + section. If REGEXP is specified, only print scripts loaded by + object files matching REGEXP. For each script, this command prints + its name as specified in the objfile, and the full path if known. + *Note dotdebug_gdb_scripts section::. + +'maint print statistics' + This command prints, for each object file in the program, various + data about that object file followed by the byte cache ("bcache") + statistics for the object file. The objfile data includes the + number of minimal, partial, full, and stabs symbols, the number of + types defined by the objfile, the number of as yet unexpanded psym + tables, the number of line tables and string tables, and the amount + of memory used by the various tables. The bcache statistics + include the counts, sizes, and counts of duplicates of all and + unique objects, max, average, and median entry size, total memory + used and its overhead and savings, and various measures of the hash + table size and chain lengths. + +'maint print target-stack' + A "target" is an interface between the debugger and a particular + kind of file or process. Targets can be stacked in "strata", so + that more than one target can potentially respond to a request. In + particular, memory accesses will walk down the stack of targets + until they find a target that is interested in handling that + particular address. + + This command prints a short description of each layer that was + pushed on the "target stack", starting from the top layer down to + the bottom one. + +'maint print type EXPR' + Print the type chain for a type specified by EXPR. The argument + can be either a type name or a symbol. If it is a symbol, the type + of that symbol is described. The type chain produced by this + command is a recursive definition of the data type as stored in + GDB's data structures, including its flags and contained types. + +'maint set dwarf2 always-disassemble' +'maint show dwarf2 always-disassemble' + Control the behavior of 'info address' when using DWARF debugging + information. + + The default is 'off', which means that GDB should try to describe a + variable's location in an easily readable format. When 'on', GDB + will instead display the DWARF location expression in an + assembly-like format. Note that some locations are too complex for + GDB to describe simply; in this case you will always see the + disassembly form. + + Here is an example of the resulting disassembly: + + (gdb) info addr argc + Symbol "argc" is a complex DWARF expression: + 1: DW_OP_fbreg 0 + + For more information on these expressions, see the DWARF standard + (http://www.dwarfstd.org/). + +'maint set dwarf2 max-cache-age' +'maint show dwarf2 max-cache-age' + Control the DWARF 2 compilation unit cache. + + In object files with inter-compilation-unit references, such as + those produced by the GCC option '-feliminate-dwarf2-dups', the + DWARF 2 reader needs to frequently refer to previously read + compilation units. This setting controls how long a compilation + unit will remain in the cache if it is not referenced. A higher + limit means that cached compilation units will be stored in memory + longer, and more total memory will be used. Setting it to zero + disables caching, which will slow down GDB startup, but reduce + memory consumption. + +'maint set profile' +'maint show profile' + Control profiling of GDB. + + Profiling will be disabled until you use the 'maint set profile' + command to enable it. When you enable profiling, the system will + begin collecting timing and execution count data; when you disable + profiling or exit GDB, the results will be written to a log file. + Remember that if you use profiling, GDB will overwrite the + profiling log file (often called 'gmon.out'). If you have a record + of important profiling data in a 'gmon.out' file, be sure to move + it to a safe location. + + Configuring with '--enable-profiling' arranges for GDB to be + compiled with the '-pg' compiler option. + +'maint set show-debug-regs' +'maint show show-debug-regs' + Control whether to show variables that mirror the hardware debug + registers. Use 'on' to enable, 'off' to disable. If enabled, the + debug registers values are shown when GDB inserts or removes a + hardware breakpoint or watchpoint, and when the inferior triggers a + hardware-assisted breakpoint or watchpoint. + +'maint set show-all-tib' +'maint show show-all-tib' + Control whether to show all non zero areas within a 1k block + starting at thread local base, when using the 'info w32 + thread-information-block' command. + +'maint set per-command' +'maint show per-command' + + GDB can display the resources used by each command. This is useful + in debugging performance problems. + + 'maint set per-command space [on|off]' + 'maint show per-command space' + Enable or disable the printing of the memory used by GDB for + each command. If enabled, GDB will display how much memory + each command took, following the command's own output. This + can also be requested by invoking GDB with the '--statistics' + command-line switch (*note Mode Options::). + + 'maint set per-command time [on|off]' + 'maint show per-command time' + Enable or disable the printing of the execution time of GDB + for each command. If enabled, GDB will display how much time + it took to execute each command, following the command's own + output. Both CPU time and wallclock time are printed. + Printing both is useful when trying to determine whether the + cost is CPU or, e.g., disk/network latency. Note that the CPU + time printed is for GDB only, it does not include the + execution time of the inferior because there's no mechanism + currently to compute how much time was spent by GDB and how + much time was spent by the program been debugged. This can + also be requested by invoking GDB with the '--statistics' + command-line switch (*note Mode Options::). + + 'maint set per-command symtab [on|off]' + 'maint show per-command symtab' + Enable or disable the printing of basic symbol table + statistics for each command. If enabled, GDB will display the + following information: + + a. number of symbol tables + b. number of primary symbol tables + c. number of blocks in the blockvector + +'maint space VALUE' + An alias for 'maint set per-command space'. A non-zero value + enables it, zero disables it. + +'maint time VALUE' + An alias for 'maint set per-command time'. A non-zero value + enables it, zero disables it. + +'maint translate-address [SECTION] ADDR' + Find the symbol stored at the location specified by the address + ADDR and an optional section name SECTION. If found, GDB prints + the name of the closest symbol and an offset from the symbol's + location to the specified address. This is similar to the 'info + address' command (*note Symbols::), except that this command also + allows to find symbols in other sections. + + If section was not specified, the section in which the symbol was + found is also printed. For dynamically linked executables, the + name of executable or shared library containing the symbol is + printed as well. + + The following command is useful for non-interactive invocations of +GDB, such as in the test suite. + +'set watchdog NSEC' + Set the maximum number of seconds GDB will wait for the target + operation to finish. If this time expires, GDB reports and error + and the command is aborted. + +'show watchdog' + Show the current setting of the target wait timeout. + + +File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top + +Appendix E GDB Remote Serial Protocol +************************************* + +* Menu: + +* Overview:: +* Packets:: +* Stop Reply Packets:: +* General Query Packets:: +* Architecture-Specific Protocol Details:: +* Tracepoint Packets:: +* Host I/O Packets:: +* Interrupts:: +* Notification Packets:: +* Remote Non-Stop:: +* Packet Acknowledgment:: +* Examples:: +* File-I/O Remote Protocol Extension:: +* Library List Format:: +* Library List Format for SVR4 Targets:: +* Memory Map Format:: +* Thread List Format:: +* Traceframe Info Format:: +* Branch Trace Format:: + + +File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol + +E.1 Overview +============ + +There may be occasions when you need to know something about the +protocol--for example, if there is only one serial port to your target +machine, you might want your program to do something special if it +recognizes a packet meant for GDB. + + In the examples below, '->' and '<-' are used to indicate transmitted +and received data, respectively. + + All GDB commands and responses (other than acknowledgments and +notifications, see *note Notification Packets::) are sent as a PACKET. +A PACKET is introduced with the character '$', the actual PACKET-DATA, +and the terminating character '#' followed by a two-digit CHECKSUM: + + $PACKET-DATA#CHECKSUM + +The two-digit CHECKSUM is computed as the modulo 256 sum of all +characters between the leading '$' and the trailing '#' (an eight bit +unsigned checksum). + + Implementors should note that prior to GDB 5.0 the protocol +specification also included an optional two-digit SEQUENCE-ID: + + $SEQUENCE-ID:PACKET-DATA#CHECKSUM + +That SEQUENCE-ID was appended to the acknowledgment. GDB has never +output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 must +not accept SEQUENCE-ID. + + When either the host or the target machine receives a packet, the +first response expected is an acknowledgment: either '+' (to indicate +the package was received correctly) or '-' (to request retransmission): + + -> $PACKET-DATA#CHECKSUM + <- + + + The '+'/'-' acknowledgments can be disabled once a connection is +established. *Note Packet Acknowledgment::, for details. + + The host (GDB) sends COMMANDs, and the target (the debugging stub +incorporated in your program) sends a RESPONSE. In the case of step and +continue COMMANDs, the response is only sent when the operation has +completed, and the target has again stopped all threads in all attached +processes. This is the default all-stop mode behavior, but the remote +protocol also supports GDB's non-stop execution mode; see *note Remote +Non-Stop::, for details. + + PACKET-DATA consists of a sequence of characters with the exception +of '#' and '$' (see 'X' packet for additional exceptions). + + Fields within the packet should be separated using ',' ';' or ':'. +Except where otherwise noted all numbers are represented in HEX with +leading zeros suppressed. + + Implementors should note that prior to GDB 5.0, the character ':' +could not appear as the third character in a packet (as it would +potentially conflict with the SEQUENCE-ID). + + Binary data in most packets is encoded either as two hexadecimal +digits per byte of binary data. This allowed the traditional remote +protocol to work over connections which were only seven-bit clean. Some +packets designed more recently assume an eight-bit clean connection, and +use a more efficient encoding to send and receive binary data. + + The binary data representation uses '7d' (ASCII '}') as an escape +character. Any escaped byte is transmitted as the escape character +followed by the original character XORed with '0x20'. For example, the +byte '0x7d' would be transmitted as the two bytes '0x7d 0x5d'. The +bytes '0x23' (ASCII '#'), '0x24' (ASCII '$'), and '0x7d' (ASCII '}') +must always be escaped. Responses sent by the stub must also escape +'0x2a' (ASCII '*'), so that it is not interpreted as the start of a +run-length encoded sequence (described next). + + Response DATA can be run-length encoded to save space. Run-length +encoding replaces runs of identical characters with one instance of the +repeated character, followed by a '*' and a repeat count. The repeat +count is itself sent encoded, to avoid binary characters in DATA: a +value of N is sent as 'N+29'. For a repeat count greater or equal to 3, +this produces a printable ASCII character, e.g. a space (ASCII code 32) +for a repeat count of 3. (This is because run-length encoding starts to +win for counts 3 or more.) Thus, for example, '0* ' is a run-length +encoding of "0000": the space character after '*' means repeat the +leading '0' '32 - 29 = 3' more times. + + The printable characters '#' and '$' or with a numeric value greater +than 126 must not be used. Runs of six repeats ('#') or seven repeats +('$') can be expanded using a repeat count of only five ('"'). For +example, '00000000' can be encoded as '0*"00'. + + The error response returned for some packets includes a two character +error number. That number is not well defined. + + For any COMMAND not supported by the stub, an empty response ('$#00') +should be returned. That way it is possible to extend the protocol. A +newer GDB can tell if a packet is supported based on that response. + + At a minimum, a stub is required to support the 'g' and 'G' commands +for register access, and the 'm' and 'M' commands for memory access. +Stubs that only control single-threaded targets can implement run +control with the 'c' (continue), and 's' (step) commands. Stubs that +support multi-threading targets should support the 'vCont' command. All +other commands are optional. + + +File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol + +E.2 Packets +=========== + +The following table provides a complete list of all currently defined +COMMANDs and their corresponding response DATA. *Note File-I/O Remote +Protocol Extension::, for details about the File I/O extension of the +remote protocol. + + Each packet's description has a template showing the packet's overall +syntax, followed by an explanation of the packet's meaning. We include +spaces in some of the templates for clarity; these are not part of the +packet's syntax. No GDB packet uses spaces to separate its components. +For example, a template like 'foo BAR BAZ' describes a packet beginning +with the three ASCII bytes 'foo', followed by a BAR, followed directly +by a BAZ. GDB does not transmit a space character between the 'foo' and +the BAR, or between the BAR and the BAZ. + + Several packets and replies include a THREAD-ID field to identify a +thread. Normally these are positive numbers with a target-specific +interpretation, formatted as big-endian hex strings. A THREAD-ID can +also be a literal '-1' to indicate all threads, or '0' to pick any +thread. + + In addition, the remote protocol supports a multiprocess feature in +which the THREAD-ID syntax is extended to optionally include both +process and thread ID fields, as 'pPID.TID'. The PID (process) and TID +(thread) components each have the format described above: a positive +number with target-specific interpretation formatted as a big-endian hex +string, literal '-1' to indicate all processes or threads +(respectively), or '0' to indicate an arbitrary process or thread. +Specifying just a process, as 'pPID', is equivalent to 'pPID.-1'. It is +an error to specify all processes but a specific thread, such as +'p-1.TID'. Note that the 'p' prefix is _not_ used for those packets and +replies explicitly documented to include a process ID, rather than a +THREAD-ID. + + The multiprocess THREAD-ID syntax extensions are only used if both +GDB and the stub report support for the 'multiprocess' feature using +'qSupported'. *Note multiprocess extensions::, for more information. + + Note that all packet forms beginning with an upper- or lower-case +letter, other than those described here, are reserved for future use. + + Here are the packet descriptions. + +'!' + Enable extended mode. In extended mode, the remote server is made + persistent. The 'R' packet is used to restart the program being + debugged. + + Reply: + 'OK' + The remote target both supports and has enabled extended mode. + +'?' + Indicate the reason the target halted. The reply is the same as + for step and continue. This packet has a special interpretation + when the target is in non-stop mode; see *note Remote Non-Stop::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'A ARGLEN,ARGNUM,ARG,...' + Initialized 'argv[]' array passed into program. ARGLEN specifies + the number of bytes in the hex encoded byte stream ARG. See + 'gdbserver' for more details. + + Reply: + 'OK' + The arguments were set. + 'E NN' + An error occurred. + +'b BAUD' + (Don't use this packet; its behavior is not well-defined.) Change + the serial line speed to BAUD. + + JTC: _When does the transport layer state change? When it's + received, or after the ACK is transmitted. In either case, there + are problems if the command or the acknowledgment packet is + dropped._ + + Stan: _If people really wanted to add something like this, and get + it working for the first time, they ought to modify ser-unix.c to + send some kind of out-of-band message to a specially-setup stub and + have the switch happen "in between" packets, so that from remote + protocol's point of view, nothing actually happened._ + +'B ADDR,MODE' + Set (MODE is 'S') or clear (MODE is 'C') a breakpoint at ADDR. + + Don't use this packet. Use the 'Z' and 'z' packets instead (*note + insert breakpoint or watchpoint packet::). + +'bc' + Backward continue. Execute the target system in reverse. No + parameter. *Note Reverse Execution::, for more information. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'bs' + Backward single step. Execute one instruction in reverse. No + parameter. *Note Reverse Execution::, for more information. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'c [ADDR]' + Continue. ADDR is address to resume. If ADDR is omitted, resume + at current address. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'C SIG[;ADDR]' + Continue with signal SIG (hex signal number). If ';ADDR' is + omitted, resume at same address. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'d' + Toggle debug flag. + + Don't use this packet; instead, define a general set packet (*note + General Query Packets::). + +'D' +'D;PID' + The first form of the packet is used to detach GDB from the remote + system. It is sent to the remote target before GDB disconnects via + the 'detach' command. + + The second form, including a process ID, is used when multiprocess + protocol extensions are enabled (*note multiprocess extensions::), + to detach only a specific process. The PID is specified as a + big-endian hex string. + + Reply: + 'OK' + for success + 'E NN' + for an error + +'F RC,EE,CF;XX' + A reply from GDB to an 'F' packet sent by the target. This is part + of the File-I/O protocol extension. *Note File-I/O Remote Protocol + Extension::, for the specification. + +'g' + Read general registers. + + Reply: + 'XX...' + Each byte of register data is described by two hex digits. + The bytes with the register are transmitted in target byte + order. The size of each register and their position within + the 'g' packet are determined by the GDB internal gdbarch + functions 'DEPRECATED_REGISTER_RAW_SIZE' and + 'gdbarch_register_name'. The specification of several + standard 'g' packets is specified below. + + When reading registers from a trace frame (*note Using the + Collected Data: Analyze Collected Data.), the stub may also + return a string of literal 'x''s in place of the register data + digits, to indicate that the corresponding register has not + been collected, thus its value is unavailable. For example, + for an architecture with 4 registers of 4 bytes each, the + following reply indicates to GDB that registers 0 and 2 have + not been collected, while registers 1 and 3 have been + collected, and both have zero value: + + -> g + <- xxxxxxxx00000000xxxxxxxx00000000 + + 'E NN' + for an error. + +'G XX...' + Write general registers. *Note read registers packet::, for a + description of the XX... data. + + Reply: + 'OK' + for success + 'E NN' + for an error + +'H OP THREAD-ID' + Set thread for subsequent operations ('m', 'M', 'g', 'G', et.al.). + OP depends on the operation to be performed: it should be 'c' for + step and continue operations (note that this is deprecated, + supporting the 'vCont' command is a better option), 'g' for other + operations. The thread designator THREAD-ID has the format and + interpretation described in *note thread-id syntax::. + + Reply: + 'OK' + for success + 'E NN' + for an error + +'i [ADDR[,NNN]]' + Step the remote target by a single clock cycle. If ',NNN' is + present, cycle step NNN cycles. If ADDR is present, cycle step + starting at that address. + +'I' + Signal, then cycle step. *Note step with signal packet::. *Note + cycle step packet::. + +'k' + Kill request. + + FIXME: _There is no description of how to operate when a specific + thread context has been selected (i.e. does 'k' kill only that + thread?)_. + +'m ADDR,LENGTH' + Read LENGTH bytes of memory starting at address ADDR. Note that + ADDR may not be aligned to any particular boundary. + + The stub need not use any particular size or alignment when + gathering data from memory for the response; even if ADDR is + word-aligned and LENGTH is a multiple of the word size, the stub is + free to use byte accesses, or not. For this reason, this packet + may not be suitable for accessing memory-mapped I/O devices. + + Reply: + 'XX...' + Memory contents; each byte is transmitted as a two-digit + hexadecimal number. The reply may contain fewer bytes than + requested if the server was able to read only part of the + region of memory. + 'E NN' + NN is errno + +'M ADDR,LENGTH:XX...' + Write LENGTH bytes of memory starting at address ADDR. XX... is + the data; each byte is transmitted as a two-digit hexadecimal + number. + + Reply: + 'OK' + for success + 'E NN' + for an error (this includes the case where only part of the + data was written). + +'p N' + Read the value of register N; N is in hex. *Note read registers + packet::, for a description of how the returned register value is + encoded. + + Reply: + 'XX...' + the register's value + 'E NN' + for an error + '' + Indicating an unrecognized QUERY. + +'P N...=R...' + Write register N... with value R.... The register number N is in + hexadecimal, and R... contains two hex digits for each byte in the + register (target byte order). + + Reply: + 'OK' + for success + 'E NN' + for an error + +'q NAME PARAMS...' +'Q NAME PARAMS...' + General query ('q') and set ('Q'). These packets are described + fully in *note General Query Packets::. + +'r' + Reset the entire system. + + Don't use this packet; use the 'R' packet instead. + +'R XX' + Restart the program being debugged. XX, while needed, is ignored. + This packet is only available in extended mode (*note extended + mode::). + + The 'R' packet has no reply. + +'s [ADDR]' + Single step. ADDR is the address at which to resume. If ADDR is + omitted, resume at same address. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'S SIG[;ADDR]' + Step with signal. This is analogous to the 'C' packet, but + requests a single-step, rather than a normal resumption of + execution. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'t ADDR:PP,MM' + Search backwards starting at address ADDR for a match with pattern + PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3 + digits. + +'T THREAD-ID' + Find out if the thread THREAD-ID is alive. *Note thread-id + syntax::. + + Reply: + 'OK' + thread is still alive + 'E NN' + thread is dead + +'v' + Packets starting with 'v' are identified by a multi-letter name, up + to the first ';' or '?' (or the end of the packet). + +'vAttach;PID' + Attach to a new process with the specified process ID PID. The + process ID is a hexadecimal integer identifying the process. In + all-stop mode, all threads in the attached process are stopped; in + non-stop mode, it may be attached without being stopped if that is + supported by the target. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'E NN' + for an error + 'Any stop packet' + for success in all-stop mode (*note Stop Reply Packets::) + 'OK' + for success in non-stop mode (*note Remote Non-Stop::) + +'vCont[;ACTION[:THREAD-ID]]...' + Resume the inferior, specifying different actions for each thread. + If an action is specified with no THREAD-ID, then it is applied to + any threads that don't have a specific action specified; if no + default action is specified then other threads should remain + stopped in all-stop mode and in their current state in non-stop + mode. Specifying multiple default actions is an error; specifying + no actions is also an error. Thread IDs are specified using the + syntax described in *note thread-id syntax::. + + Currently supported actions are: + + 'c' + Continue. + 'C SIG' + Continue with signal SIG. The signal SIG should be two hex + digits. + 's' + Step. + 'S SIG' + Step with signal SIG. The signal SIG should be two hex + digits. + 't' + Stop. + 'r START,END' + Step once, and then keep stepping as long as the thread stops + at addresses between START (inclusive) and END (exclusive). + The remote stub reports a stop reply when either the thread + goes out of the range or is stopped due to an unrelated + reason, such as hitting a breakpoint. *Note range stepping::. + + If the range is empty (START == END), then the action becomes + equivalent to the 's' action. In other words, single-step + once, and report the stop (even if the stepped instruction + jumps to START). + + (A stop reply may be sent at any point even if the PC is still + within the stepping range; for example, it is valid to + implement this packet in a degenerate way as a single + instruction step operation.) + + The optional argument ADDR normally associated with the 'c', 'C', + 's', and 'S' packets is not supported in 'vCont'. + + The 't' action is only relevant in non-stop mode (*note Remote + Non-Stop::) and may be ignored by the stub otherwise. A stop reply + should be generated for any affected thread not already stopped. + When a thread is stopped by means of a 't' action, the + corresponding stop reply should indicate that the thread has + stopped with signal '0', regardless of whether the target uses some + other signal as an implementation detail. + + The stub must support 'vCont' if it reports support for + multiprocess extensions (*note multiprocess extensions::). Note + that in this case 'vCont' actions can be specified to apply to all + threads in a process by using the 'pPID.-1' form of the THREAD-ID. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'vCont?' + Request a list of actions supported by the 'vCont' packet. + + Reply: + 'vCont[;ACTION...]' + The 'vCont' packet is supported. Each ACTION is a supported + command in the 'vCont' packet. + '' + The 'vCont' packet is not supported. + +'vFile:OPERATION:PARAMETER...' + Perform a file operation on the target system. For details, see + *note Host I/O Packets::. + +'vFlashErase:ADDR,LENGTH' + Direct the stub to erase LENGTH bytes of flash starting at ADDR. + The region may enclose any number of flash blocks, but its start + and end must fall on block boundaries, as indicated by the flash + block size appearing in the memory map (*note Memory Map Format::). + GDB groups flash memory programming operations together, and sends + a 'vFlashDone' request after each group; the stub is allowed to + delay erase operation until the 'vFlashDone' packet is received. + + Reply: + 'OK' + for success + 'E NN' + for an error + +'vFlashWrite:ADDR:XX...' + Direct the stub to write data to flash address ADDR. The data is + passed in binary form using the same encoding as for the 'X' packet + (*note Binary Data::). The memory ranges specified by + 'vFlashWrite' packets preceding a 'vFlashDone' packet must not + overlap, and must appear in order of increasing addresses (although + 'vFlashErase' packets for higher addresses may already have been + received; the ordering is guaranteed only between 'vFlashWrite' + packets). If a packet writes to an address that was neither erased + by a preceding 'vFlashErase' packet nor by some other + target-specific method, the results are unpredictable. + + Reply: + 'OK' + for success + 'E.memtype' + for vFlashWrite addressing non-flash memory + 'E NN' + for an error + +'vFlashDone' + Indicate to the stub that flash programming operation is finished. + The stub is permitted to delay or batch the effects of a group of + 'vFlashErase' and 'vFlashWrite' packets until a 'vFlashDone' packet + is received. The contents of the affected regions of flash memory + are unpredictable until the 'vFlashDone' request is completed. + +'vKill;PID' + Kill the process with the specified process ID. PID is a + hexadecimal integer identifying the process. This packet is used + in preference to 'k' when multiprocess protocol extensions are + supported; see *note multiprocess extensions::. + + Reply: + 'E NN' + for an error + 'OK' + for success + +'vRun;FILENAME[;ARGUMENT]...' + Run the program FILENAME, passing it each ARGUMENT on its command + line. The file and arguments are hex-encoded strings. If FILENAME + is an empty string, the stub may use a default program (e.g. the + last program run). The program is created in the stopped state. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'E NN' + for an error + 'Any stop packet' + for success (*note Stop Reply Packets::) + +'vStopped' + *Note Notification Packets::. + +'X ADDR,LENGTH:XX...' + Write data to memory, where the data is transmitted in binary. + ADDR is address, LENGTH is number of bytes, 'XX...' is binary data + (*note Binary Data::). + + Reply: + 'OK' + for success + 'E NN' + for an error + +'z TYPE,ADDR,KIND' +'Z TYPE,ADDR,KIND' + Insert ('Z') or remove ('z') a TYPE breakpoint or watchpoint + starting at address ADDRESS of kind KIND. + + Each breakpoint and watchpoint packet TYPE is documented + separately. + + _Implementation notes: A remote target shall return an empty string + for an unrecognized breakpoint or watchpoint packet TYPE. A remote + target shall support either both or neither of a given 'ZTYPE...' + and 'zTYPE...' packet pair. To avoid potential problems with + duplicate packets, the operations should be implemented in an + idempotent way._ + +'z0,ADDR,KIND' +'Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]' + Insert ('Z0') or remove ('z0') a memory breakpoint at address ADDR + of type KIND. + + A memory breakpoint is implemented by replacing the instruction at + ADDR with a software breakpoint or trap instruction. The KIND is + target-specific and typically indicates the size of the breakpoint + in bytes that should be inserted. E.g., the ARM and MIPS can + insert either a 2 or 4 byte breakpoint. Some architectures have + additional meanings for KIND; COND_LIST is an optional list of + conditional expressions in bytecode form that should be evaluated + on the target's side. These are the conditions that should be + taken into consideration when deciding if the breakpoint trigger + should be reported back to GDBN. + + The COND_LIST parameter is comprised of a series of expressions, + concatenated without separators. Each expression has the following + form: + + 'X LEN,EXPR' + LEN is the length of the bytecode expression and EXPR is the + actual conditional expression in bytecode form. + + The optional CMD_LIST parameter introduces commands that may be run + on the target, rather than being reported back to GDB. The + parameter starts with a numeric flag PERSIST; if the flag is + nonzero, then the breakpoint may remain active and the commands + continue to be run even when GDB disconnects from the target. + Following this flag is a series of expressions concatenated with no + separators. Each expression has the following form: + + 'X LEN,EXPR' + LEN is the length of the bytecode expression and EXPR is the + actual conditional expression in bytecode form. + + see *note Architecture-Specific Protocol Details::. + + _Implementation note: It is possible for a target to copy or move + code that contains memory breakpoints (e.g., when implementing + overlays). The behavior of this packet, in the presence of such a + target, is not defined._ + + Reply: + 'OK' + success + '' + not supported + 'E NN' + for an error + +'z1,ADDR,KIND' +'Z1,ADDR,KIND[;COND_LIST...]' + Insert ('Z1') or remove ('z1') a hardware breakpoint at address + ADDR. + + A hardware breakpoint is implemented using a mechanism that is not + dependant on being able to modify the target's memory. KIND and + COND_LIST have the same meaning as in 'Z0' packets. + + _Implementation note: A hardware breakpoint is not affected by code + movement._ + + Reply: + 'OK' + success + '' + not supported + 'E NN' + for an error + +'z2,ADDR,KIND' +'Z2,ADDR,KIND' + Insert ('Z2') or remove ('z2') a write watchpoint at ADDR. KIND is + interpreted as the number of bytes to watch. + + Reply: + 'OK' + success + '' + not supported + 'E NN' + for an error + +'z3,ADDR,KIND' +'Z3,ADDR,KIND' + Insert ('Z3') or remove ('z3') a read watchpoint at ADDR. KIND is + interpreted as the number of bytes to watch. + + Reply: + 'OK' + success + '' + not supported + 'E NN' + for an error + +'z4,ADDR,KIND' +'Z4,ADDR,KIND' + Insert ('Z4') or remove ('z4') an access watchpoint at ADDR. KIND + is interpreted as the number of bytes to watch. + + Reply: + 'OK' + success + '' + not supported + 'E NN' + for an error + + +File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol + +E.3 Stop Reply Packets +====================== + +The 'C', 'c', 'S', 's', 'vCont', 'vAttach', 'vRun', 'vStopped', and '?' +packets can receive any of the below as a reply. Except for '?' and +'vStopped', that reply is only returned when the target halts. In the +below the exact meaning of "signal number" is defined by the header +'include/gdb/signals.h' in the GDB source code. + + As in the description of request packets, we include spaces in the +reply templates for clarity; these are not part of the reply packet's +syntax. No GDB stop reply packet uses spaces to separate its +components. + +'S AA' + The program received signal number AA (a two-digit hexadecimal + number). This is equivalent to a 'T' response with no N:R pairs. + +'T AA N1:R1;N2:R2;...' + The program received signal number AA (a two-digit hexadecimal + number). This is equivalent to an 'S' response, except that the + 'N:R' pairs can carry values of important registers and other + information directly in the stop reply packet, reducing round-trip + latency. Single-step and breakpoint traps are reported this way. + Each 'N:R' pair is interpreted as follows: + + * If N is a hexadecimal number, it is a register number, and the + corresponding R gives that register's value. R is a series of + bytes in target byte order, with each byte given by a + two-digit hex number. + + * If N is 'thread', then R is the THREAD-ID of the stopped + thread, as specified in *note thread-id syntax::. + + * If N is 'core', then R is the hexadecimal number of the core + on which the stop event was detected. + + * If N is a recognized "stop reason", it describes a more + specific event that stopped the target. The currently defined + stop reasons are listed below. AA should be '05', the trap + signal. At most one stop reason should be present. + + * Otherwise, GDB should ignore this 'N:R' pair and go on to the + next; this allows us to extend the protocol in the future. + + The currently defined stop reasons are: + + 'watch' + 'rwatch' + 'awatch' + The packet indicates a watchpoint hit, and R is the data + address, in hex. + + 'library' + The packet indicates that the loaded libraries have changed. + GDB should use 'qXfer:libraries:read' to fetch a new list of + loaded libraries. R is ignored. + + 'replaylog' + The packet indicates that the target cannot continue replaying + logged execution events, because it has reached the end (or + the beginning when executing backward) of the log. The value + of R will be either 'begin' or 'end'. *Note Reverse + Execution::, for more information. + +'W AA' +'W AA ; process:PID' + The process exited, and AA is the exit status. This is only + applicable to certain targets. + + The second form of the response, including the process ID of the + exited process, can be used only when GDB has reported support for + multiprocess protocol extensions; see *note multiprocess + extensions::. The PID is formatted as a big-endian hex string. + +'X AA' +'X AA ; process:PID' + The process terminated with signal AA. + + The second form of the response, including the process ID of the + terminated process, can be used only when GDB has reported support + for multiprocess protocol extensions; see *note multiprocess + extensions::. The PID is formatted as a big-endian hex string. + +'O XX...' + 'XX...' is hex encoding of ASCII data, to be written as the + program's console output. This can happen at any time while the + program is running and the debugger should continue to wait for + 'W', 'T', etc. This reply is not permitted in non-stop mode. + +'F CALL-ID,PARAMETER...' + CALL-ID is the identifier which says which host system call should + be called. This is just the name of the function. Translation + into the correct system call is only applicable as it's defined in + GDB. *Note File-I/O Remote Protocol Extension::, for a list of + implemented system calls. + + 'PARAMETER...' is a list of parameters as defined for this very + system call. + + The target replies with this packet when it expects GDB to call a + host system call on behalf of the target. GDB replies with an + appropriate 'F' packet and keeps up waiting for the next reply + packet from the target. The latest 'C', 'c', 'S' or 's' action is + expected to be continued. *Note File-I/O Remote Protocol + Extension::, for more details. + + +File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol + +E.4 General Query Packets +========================= + +Packets starting with 'q' are "general query packets"; packets starting +with 'Q' are "general set packets". General query and set packets are a +semi-unified form for retrieving and sending information to and from the +stub. + + The initial letter of a query or set packet is followed by a name +indicating what sort of thing the packet applies to. For example, GDB +may use a 'qSymbol' packet to exchange symbol definitions with the stub. +These packet names follow some conventions: + + * The name must not contain commas, colons or semicolons. + * Most GDB query and set packets have a leading upper case letter. + * The names of custom vendor packets should use a company prefix, in + lower case, followed by a period. For example, packets designed at + the Acme Corporation might begin with 'qacme.foo' (for querying + foos) or 'Qacme.bar' (for setting bars). + + The name of a query or set packet should be separated from any +parameters by a ':'; the parameters themselves should be separated by +',' or ';'. Stubs must be careful to match the full packet name, and +check for a separator or the end of the packet, in case two packet names +share a common prefix. New packets should not begin with 'qC', 'qP', or +'qL'(1). + + Like the descriptions of the other packets, each description here has +a template showing the packet's overall syntax, followed by an +explanation of the packet's meaning. We include spaces in some of the +templates for clarity; these are not part of the packet's syntax. No +GDB packet uses spaces to separate its components. + + Here are the currently defined query and set packets: + +'QAgent:1' +'QAgent:0' + Turn on or off the agent as a helper to perform some debugging + operations delegated from GDB (*note Control Agent::). + +'QAllow:OP:VAL...' + Specify which operations GDB expects to request of the target, as a + semicolon-separated list of operation name and value pairs. + Possible values for OP include 'WriteReg', 'WriteMem', + 'InsertBreak', 'InsertTrace', 'InsertFastTrace', and 'Stop'. VAL + is either 0, indicating that GDB will not request the operation, or + 1, indicating that it may. (The target can then use this to set up + its own internals optimally, for instance if the debugger never + expects to insert breakpoints, it may not need to install its own + trap handler.) + +'qC' + Return the current thread ID. + + Reply: + 'QC THREAD-ID' + Where THREAD-ID is a thread ID as documented in *note + thread-id syntax::. + '(anything else)' + Any other reply implies the old thread ID. + +'qCRC:ADDR,LENGTH' + Compute the CRC checksum of a block of memory using CRC-32 defined + in IEEE 802.3. The CRC is computed byte at a time, taking the most + significant bit of each byte first. The initial pattern code + '0xffffffff' is used to ensure leading zeros affect the CRC. + + _Note:_ This is the same CRC used in validating separate debug + files (*note Debugging Information in Separate Files: Separate + Debug Files.). However the algorithm is slightly different. When + validating separate debug files, the CRC is computed taking the + _least_ significant bit of each byte first, and the final result is + inverted to detect trailing zeros. + + Reply: + 'E NN' + An error (such as memory fault) + 'C CRC32' + The specified memory region's checksum is CRC32. + +'QDisableRandomization:VALUE' + Some target operating systems will randomize the virtual address + space of the inferior process as a security feature, but provide a + feature to disable such randomization, e.g. to allow for a more + deterministic debugging experience. On such systems, this packet + with a VALUE of 1 directs the target to disable address space + randomization for processes subsequently started via 'vRun' + packets, while a packet with a VALUE of 0 tells the target to + enable address space randomization. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'OK' + The request succeeded. + + 'E NN' + An error occurred. NN are hex digits. + + '' + An empty reply indicates that 'QDisableRandomization' is not + supported by the stub. + + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). This should only be done on targets that actually + support disabling address space randomization. + +'qfThreadInfo' +'qsThreadInfo' + Obtain a list of all active thread IDs from the target (OS). Since + there may be too many active threads to fit into one reply packet, + this query works iteratively: it may require more than one + query/reply sequence to obtain the entire list of threads. The + first query of the sequence will be the 'qfThreadInfo' query; + subsequent queries in the sequence will be the 'qsThreadInfo' + query. + + NOTE: This packet replaces the 'qL' query (see below). + + Reply: + 'm THREAD-ID' + A single thread ID + 'm THREAD-ID,THREAD-ID...' + a comma-separated list of thread IDs + 'l' + (lower case letter 'L') denotes end of list. + + In response to each query, the target will reply with a list of one + or more thread IDs, separated by commas. GDB will respond to each + reply with a request for more thread ids (using the 'qs' form of + the query), until the target responds with 'l' (lower-case ell, for + "last"). Refer to *note thread-id syntax::, for the format of the + THREAD-ID fields. + +'qGetTLSAddr:THREAD-ID,OFFSET,LM' + Fetch the address associated with thread local storage specified by + THREAD-ID, OFFSET, and LM. + + THREAD-ID is the thread ID associated with the thread for which to + fetch the TLS address. *Note thread-id syntax::. + + OFFSET is the (big endian, hex encoded) offset associated with the + thread local variable. (This offset is obtained from the debug + information associated with the variable.) + + LM is the (big endian, hex encoded) OS/ABI-specific encoding of the + load module associated with the thread local storage. For example, + a GNU/Linux system will pass the link map address of the shared + object associated with the thread local storage under + consideration. Other operating environments may choose to + represent the load module differently, so the precise meaning of + this parameter will vary. + + Reply: + 'XX...' + Hex encoded (big endian) bytes representing the address of the + thread local storage requested. + + 'E NN' + An error occurred. NN are hex digits. + + '' + An empty reply indicates that 'qGetTLSAddr' is not supported + by the stub. + +'qGetTIBAddr:THREAD-ID' + Fetch address of the Windows OS specific Thread Information Block. + + THREAD-ID is the thread ID associated with the thread. + + Reply: + 'XX...' + Hex encoded (big endian) bytes representing the linear address + of the thread information block. + + 'E NN' + An error occured. This means that either the thread was not + found, or the address could not be retrieved. + + '' + An empty reply indicates that 'qGetTIBAddr' is not supported + by the stub. + +'qL STARTFLAG THREADCOUNT NEXTTHREAD' + Obtain thread information from RTOS. Where: STARTFLAG (one hex + digit) is one to indicate the first query and zero to indicate a + subsequent query; THREADCOUNT (two hex digits) is the maximum + number of threads the response packet can contain; and NEXTTHREAD + (eight hex digits), for subsequent queries (STARTFLAG is zero), is + returned in the response as ARGTHREAD. + + Don't use this packet; use the 'qfThreadInfo' query instead (see + above). + + Reply: + 'qM COUNT DONE ARGTHREAD THREAD...' + Where: COUNT (two hex digits) is the number of threads being + returned; DONE (one hex digit) is zero to indicate more + threads and one indicates no further threads; ARGTHREADID + (eight hex digits) is NEXTTHREAD from the request packet; + THREAD... is a sequence of thread IDs from the target. + THREADID (eight hex digits). See + 'remote.c:parse_threadlist_response()'. + +'qOffsets' + Get section offsets that the target used when relocating the + downloaded image. + + Reply: + 'Text=XXX;Data=YYY[;Bss=ZZZ]' + Relocate the 'Text' section by XXX from its original address. + Relocate the 'Data' section by YYY from its original address. + If the object file format provides segment information (e.g. + ELF 'PT_LOAD' program headers), GDB will relocate entire + segments by the supplied offsets. + + _Note: while a 'Bss' offset may be included in the response, + GDB ignores this and instead applies the 'Data' offset to the + 'Bss' section._ + + 'TextSeg=XXX[;DataSeg=YYY]' + Relocate the first segment of the object file, which + conventionally contains program code, to a starting address of + XXX. If 'DataSeg' is specified, relocate the second segment, + which conventionally contains modifiable data, to a starting + address of YYY. GDB will report an error if the object file + does not contain segment information, or does not contain at + least as many segments as mentioned in the reply. Extra + segments are kept at fixed offsets relative to the last + relocated segment. + +'qP MODE THREAD-ID' + Returns information on THREAD-ID. Where: MODE is a hex encoded 32 + bit mode; THREAD-ID is a thread ID (*note thread-id syntax::). + + Don't use this packet; use the 'qThreadExtraInfo' query instead + (see below). + + Reply: see 'remote.c:remote_unpack_thread_info_response()'. + +'QNonStop:1' +'QNonStop:0' + Enter non-stop ('QNonStop:1') or all-stop ('QNonStop:0') mode. + *Note Remote Non-Stop::, for more information. + + Reply: + 'OK' + The request succeeded. + + 'E NN' + An error occurred. NN are hex digits. + + '' + An empty reply indicates that 'QNonStop' is not supported by + the stub. + + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). Use of this packet is controlled by the 'set + non-stop' command; *note Non-Stop Mode::. + +'QPassSignals: SIGNAL [;SIGNAL]...' + Each listed SIGNAL should be passed directly to the inferior + process. Signals are numbered identically to continue packets and + stop replies (*note Stop Reply Packets::). Each SIGNAL list item + should be strictly greater than the previous item. These signals + do not need to stop the inferior, or be reported to GDB. All other + signals should be reported to GDB. Multiple 'QPassSignals' packets + do not combine; any earlier 'QPassSignals' list is completely + replaced by the new list. This packet improves performance when + using 'handle SIGNAL nostop noprint pass'. + + Reply: + 'OK' + The request succeeded. + + 'E NN' + An error occurred. NN are hex digits. + + '' + An empty reply indicates that 'QPassSignals' is not supported + by the stub. + + Use of this packet is controlled by the 'set remote pass-signals' + command (*note set remote pass-signals: Remote Configuration.). + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). + +'QProgramSignals: SIGNAL [;SIGNAL]...' + Each listed SIGNAL may be delivered to the inferior process. + Others should be silently discarded. + + In some cases, the remote stub may need to decide whether to + deliver a signal to the program or not without GDB involvement. + One example of that is while detaching -- the program's threads may + have stopped for signals that haven't yet had a chance of being + reported to GDB, and so the remote stub can use the signal list + specified by this packet to know whether to deliver or ignore those + pending signals. + + This does not influence whether to deliver a signal as requested by + a resumption packet (*note vCont packet::). + + Signals are numbered identically to continue packets and stop + replies (*note Stop Reply Packets::). Each SIGNAL list item should + be strictly greater than the previous item. Multiple + 'QProgramSignals' packets do not combine; any earlier + 'QProgramSignals' list is completely replaced by the new list. + + Reply: + 'OK' + The request succeeded. + + 'E NN' + An error occurred. NN are hex digits. + + '' + An empty reply indicates that 'QProgramSignals' is not + supported by the stub. + + Use of this packet is controlled by the 'set remote + program-signals' command (*note set remote program-signals: Remote + Configuration.). This packet is not probed by default; the remote + stub must request it, by supplying an appropriate 'qSupported' + response (*note qSupported::). + +'qRcmd,COMMAND' + COMMAND (hex encoded) is passed to the local interpreter for + execution. Invalid commands should be reported using the output + string. Before the final result packet, the target may also + respond with a number of intermediate 'OOUTPUT' console output + packets. _Implementors should note that providing access to a + stubs's interpreter may have security implications_. + + Reply: + 'OK' + A command response with no output. + 'OUTPUT' + A command response with the hex encoded output string OUTPUT. + 'E NN' + Indicate a badly formed request. + '' + An empty reply indicates that 'qRcmd' is not recognized. + + (Note that the 'qRcmd' packet's name is separated from the command + by a ',', not a ':', contrary to the naming conventions above. + Please don't use this packet as a model for new packets.) + +'qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN' + Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. ADDRESS and + LENGTH are encoded in hex. SEARCH-PATTERN is a sequence of bytes, + hex encoded. + + Reply: + '0' + The pattern was not found. + '1,address' + The pattern was found at ADDRESS. + 'E NN' + A badly formed request or an error was encountered while + searching memory. + '' + An empty reply indicates that 'qSearch:memory' is not + recognized. + +'QStartNoAckMode' + Request that the remote stub disable the normal '+'/'-' protocol + acknowledgments (*note Packet Acknowledgment::). + + Reply: + 'OK' + The stub has switched to no-acknowledgment mode. GDB + acknowledges this reponse, but neither the stub nor GDB shall + send or expect further '+'/'-' acknowledgments in the current + connection. + '' + An empty reply indicates that the stub does not support + no-acknowledgment mode. + +'qSupported [:GDBFEATURE [;GDBFEATURE]... ]' + Tell the remote stub about features supported by GDB, and query the + stub for features it supports. This packet allows GDB and the + remote stub to take advantage of each others' features. + 'qSupported' also consolidates multiple feature probes at startup, + to improve GDB performance--a single larger packet performs better + than multiple smaller probe packets on high-latency links. Some + features may enable behavior which must not be on by default, e.g. + because it would confuse older clients or stubs. Other features + may describe packets which could be automatically probed for, but + are not. These features must be reported before GDB will use them. + This "default unsupported" behavior is not appropriate for all + packets, but it helps to keep the initial connection time under + control with new versions of GDB which support increasing numbers + of packets. + + Reply: + 'STUBFEATURE [;STUBFEATURE]...' + The stub supports or does not support each returned + STUBFEATURE, depending on the form of each STUBFEATURE (see + below for the possible forms). + '' + An empty reply indicates that 'qSupported' is not recognized, + or that no features needed to be reported to GDB. + + The allowed forms for each feature (either a GDBFEATURE in the + 'qSupported' packet, or a STUBFEATURE in the response) are: + + 'NAME=VALUE' + The remote protocol feature NAME is supported, and associated + with the specified VALUE. The format of VALUE depends on the + feature, but it must not include a semicolon. + 'NAME+' + The remote protocol feature NAME is supported, and does not + need an associated value. + 'NAME-' + The remote protocol feature NAME is not supported. + 'NAME?' + The remote protocol feature NAME may be supported, and GDB + should auto-detect support in some other way when it is + needed. This form will not be used for GDBFEATURE + notifications, but may be used for STUBFEATURE responses. + + Whenever the stub receives a 'qSupported' request, the supplied set + of GDB features should override any previous request. This allows + GDB to put the stub in a known state, even if the stub had + previously been communicating with a different version of GDB. + + The following values of GDBFEATURE (for the packet sent by GDB) are + defined: + + 'multiprocess' + This feature indicates whether GDB supports multiprocess + extensions to the remote protocol. GDB does not use such + extensions unless the stub also reports that it supports them + by including 'multiprocess+' in its 'qSupported' reply. *Note + multiprocess extensions::, for details. + + 'xmlRegisters' + This feature indicates that GDB supports the XML target + description. If the stub sees 'xmlRegisters=' with target + specific strings separated by a comma, it will report register + description. + + 'qRelocInsn' + This feature indicates whether GDB supports the 'qRelocInsn' + packet (*note Relocate instruction reply packet: Tracepoint + Packets.). + + Stubs should ignore any unknown values for GDBFEATURE. Any GDB + which sends a 'qSupported' packet supports receiving packets of + unlimited length (earlier versions of GDB may reject overly long + responses). Additional values for GDBFEATURE may be defined in the + future to let the stub take advantage of new features in GDB, e.g. + incompatible improvements in the remote protocol--the + 'multiprocess' feature is an example of such a feature. The stub's + reply should be independent of the GDBFEATURE entries sent by GDB; + first GDB describes all the features it supports, and then the stub + replies with all the features it supports. + + Similarly, GDB will silently ignore unrecognized stub feature + responses, as long as each response uses one of the standard forms. + + Some features are flags. A stub which supports a flag feature + should respond with a '+' form response. Other features require + values, and the stub should respond with an '=' form response. + + Each feature has a default value, which GDB will use if + 'qSupported' is not available or if the feature is not mentioned in + the 'qSupported' response. The default values are fixed; a stub is + free to omit any feature responses that match the defaults. + + Not all features can be probed, but for those which can, the + probing mechanism is useful: in some cases, a stub's internal + architecture may not allow the protocol layer to know some + information about the underlying target in advance. This is + especially common in stubs which may be configured for multiple + targets. + + These are the currently defined stub features and their properties: + + Feature Name Value Default Probe + Required Allowed + + 'PacketSize' Yes '-' No + + 'qXfer:auxv:read' No '-' Yes + + 'qXfer:btrace:read' No '-' Yes + + 'qXfer:features:read' No '-' Yes + + 'qXfer:libraries:read' No '-' Yes + + 'qXfer:libraries-svr4:read'No '-' Yes + + 'augmented-libraries-svr4-read'No '-' No + + 'qXfer:memory-map:read' No '-' Yes + + 'qXfer:sdata:read' No '-' Yes + + 'qXfer:spu:read' No '-' Yes + + 'qXfer:spu:write' No '-' Yes + + 'qXfer:siginfo:read' No '-' Yes + + 'qXfer:siginfo:write' No '-' Yes + + 'qXfer:threads:read' No '-' Yes + + 'qXfer:traceframe-info:read'No '-' Yes + + 'qXfer:uib:read' No '-' Yes + + 'qXfer:fdpic:read' No '-' Yes + + 'Qbtrace:off' Yes '-' Yes + + 'Qbtrace:bts' Yes '-' Yes + + 'QNonStop' No '-' Yes + + 'QPassSignals' No '-' Yes + + 'QStartNoAckMode' No '-' Yes + + 'multiprocess' No '-' No + + 'ConditionalBreakpoints' No '-' No + + 'ConditionalTracepoints' No '-' No + + 'ReverseContinue' No '-' No + + 'ReverseStep' No '-' No + + 'TracepointSource' No '-' No + + 'QAgent' No '-' No + + 'QAllow' No '-' No + + 'QDisableRandomization' No '-' No + + 'EnableDisableTracepoints'No '-' No + + 'QTBuffer:size' No '-' No + + 'tracenz' No '-' No + + 'BreakpointCommands' No '-' No + + + These are the currently defined stub features, in more detail: + + 'PacketSize=BYTES' + The remote stub can accept packets up to at least BYTES in + length. GDB will send packets up to this size for bulk + transfers, and will never send larger packets. This is a + limit on the data characters in the packet, including the + frame and checksum. There is no trailing NUL byte in a remote + protocol packet; if the stub stores packets in a + NUL-terminated format, it should allow an extra byte in its + buffer for the NUL. If this stub feature is not supported, GDB + guesses based on the size of the 'g' packet response. + + 'qXfer:auxv:read' + The remote stub understands the 'qXfer:auxv:read' packet + (*note qXfer auxiliary vector read::). + + 'qXfer:btrace:read' + The remote stub understands the 'qXfer:btrace:read' packet + (*note qXfer btrace read::). + + 'qXfer:features:read' + The remote stub understands the 'qXfer:features:read' packet + (*note qXfer target description read::). + + 'qXfer:libraries:read' + The remote stub understands the 'qXfer:libraries:read' packet + (*note qXfer library list read::). + + 'qXfer:libraries-svr4:read' + The remote stub understands the 'qXfer:libraries-svr4:read' + packet (*note qXfer svr4 library list read::). + + 'augmented-libraries-svr4-read' + The remote stub understands the augmented form of the + 'qXfer:libraries-svr4:read' packet (*note qXfer svr4 library + list read::). + + 'qXfer:memory-map:read' + The remote stub understands the 'qXfer:memory-map:read' packet + (*note qXfer memory map read::). + + 'qXfer:sdata:read' + The remote stub understands the 'qXfer:sdata:read' packet + (*note qXfer sdata read::). + + 'qXfer:spu:read' + The remote stub understands the 'qXfer:spu:read' packet (*note + qXfer spu read::). + + 'qXfer:spu:write' + The remote stub understands the 'qXfer:spu:write' packet + (*note qXfer spu write::). + + 'qXfer:siginfo:read' + The remote stub understands the 'qXfer:siginfo:read' packet + (*note qXfer siginfo read::). + + 'qXfer:siginfo:write' + The remote stub understands the 'qXfer:siginfo:write' packet + (*note qXfer siginfo write::). + + 'qXfer:threads:read' + The remote stub understands the 'qXfer:threads:read' packet + (*note qXfer threads read::). + + 'qXfer:traceframe-info:read' + The remote stub understands the 'qXfer:traceframe-info:read' + packet (*note qXfer traceframe info read::). + + 'qXfer:uib:read' + The remote stub understands the 'qXfer:uib:read' packet (*note + qXfer unwind info block::). + + 'qXfer:fdpic:read' + The remote stub understands the 'qXfer:fdpic:read' packet + (*note qXfer fdpic loadmap read::). + + 'QNonStop' + The remote stub understands the 'QNonStop' packet (*note + QNonStop::). + + 'QPassSignals' + The remote stub understands the 'QPassSignals' packet (*note + QPassSignals::). + + 'QStartNoAckMode' + The remote stub understands the 'QStartNoAckMode' packet and + prefers to operate in no-acknowledgment mode. *Note Packet + Acknowledgment::. + + 'multiprocess' + The remote stub understands the multiprocess extensions to the + remote protocol syntax. The multiprocess extensions affect + the syntax of thread IDs in both packets and replies (*note + thread-id syntax::), and add process IDs to the 'D' packet and + 'W' and 'X' replies. Note that reporting this feature + indicates support for the syntactic extensions only, not that + the stub necessarily supports debugging of more than one + process at a time. The stub must not use multiprocess + extensions in packet replies unless GDB has also indicated it + supports them in its 'qSupported' request. + + 'qXfer:osdata:read' + The remote stub understands the 'qXfer:osdata:read' packet + ((*note qXfer osdata read::). + + 'ConditionalBreakpoints' + The target accepts and implements evaluation of conditional + expressions defined for breakpoints. The target will only + report breakpoint triggers when such conditions are true + (*note Break Conditions: Conditions.). + + 'ConditionalTracepoints' + The remote stub accepts and implements conditional expressions + defined for tracepoints (*note Tracepoint Conditions::). + + 'ReverseContinue' + The remote stub accepts and implements the reverse continue + packet (*note bc::). + + 'ReverseStep' + The remote stub accepts and implements the reverse step packet + (*note bs::). + + 'TracepointSource' + The remote stub understands the 'QTDPsrc' packet that supplies + the source form of tracepoint definitions. + + 'QAgent' + The remote stub understands the 'QAgent' packet. + + 'QAllow' + The remote stub understands the 'QAllow' packet. + + 'QDisableRandomization' + The remote stub understands the 'QDisableRandomization' + packet. + + 'StaticTracepoint' + The remote stub supports static tracepoints. + + 'InstallInTrace' + The remote stub supports installing tracepoint in tracing. + + 'EnableDisableTracepoints' + The remote stub supports the 'QTEnable' (*note QTEnable::) and + 'QTDisable' (*note QTDisable::) packets that allow tracepoints + to be enabled and disabled while a trace experiment is + running. + + 'QTBuffer:size' + The remote stub supports the 'QTBuffer:size' (*note + QTBuffer-size::) packet that allows to change the size of the + trace buffer. + + 'tracenz' + The remote stub supports the 'tracenz' bytecode for collecting + strings. See *note Bytecode Descriptions:: for details about + the bytecode. + + 'BreakpointCommands' + The remote stub supports running a breakpoint's command list + itself, rather than reporting the hit to GDB. + + 'Qbtrace:off' + The remote stub understands the 'Qbtrace:off' packet. + + 'Qbtrace:bts' + The remote stub understands the 'Qbtrace:bts' packet. + +'qSymbol::' + Notify the target that GDB is prepared to serve symbol lookup + requests. Accept requests from the target for the values of + symbols. + + Reply: + 'OK' + The target does not need to look up any (more) symbols. + 'qSymbol:SYM_NAME' + The target requests the value of symbol SYM_NAME (hex + encoded). GDB may provide the value by using the + 'qSymbol:SYM_VALUE:SYM_NAME' message, described below. + +'qSymbol:SYM_VALUE:SYM_NAME' + Set the value of SYM_NAME to SYM_VALUE. + + SYM_NAME (hex encoded) is the name of a symbol whose value the + target has previously requested. + + SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot + supply a value for SYM_NAME, then this field will be empty. + + Reply: + 'OK' + The target does not need to look up any (more) symbols. + 'qSymbol:SYM_NAME' + The target requests the value of a new symbol SYM_NAME (hex + encoded). GDB will continue to supply the values of symbols + (if available), until the target ceases to request them. + +'qTBuffer' +'QTBuffer' +'QTDisconnected' +'QTDP' +'QTDPsrc' +'QTDV' +'qTfP' +'qTfV' +'QTFrame' +'qTMinFTPILen' + + *Note Tracepoint Packets::. + +'qThreadExtraInfo,THREAD-ID' + Obtain a printable string description of a thread's attributes from + the target OS. THREAD-ID is a thread ID; see *note thread-id + syntax::. This string may contain anything that the target OS + thinks is interesting for GDB to tell the user about the thread. + The string is displayed in GDB's 'info threads' display. Some + examples of possible thread extra info strings are 'Runnable', or + 'Blocked on Mutex'. + + Reply: + 'XX...' + Where 'XX...' is a hex encoding of ASCII data, comprising the + printable string containing the extra information about the + thread's attributes. + + (Note that the 'qThreadExtraInfo' packet's name is separated from + the command by a ',', not a ':', contrary to the naming conventions + above. Please don't use this packet as a model for new packets.) + +'QTNotes' +'qTP' +'QTSave' +'qTsP' +'qTsV' +'QTStart' +'QTStop' +'QTEnable' +'QTDisable' +'QTinit' +'QTro' +'qTStatus' +'qTV' +'qTfSTM' +'qTsSTM' +'qTSTMat' + *Note Tracepoint Packets::. + +'qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH' + Read uninterpreted bytes from the target's special data area + identified by the keyword OBJECT. Request LENGTH bytes starting at + OFFSET bytes into the data. The content and encoding of ANNEX is + specific to OBJECT; it can supply additional details about what + data to access. + + Here are the specific requests of this form defined so far. All + 'qXfer:OBJECT:read:...' requests use the same reply formats, listed + below. + + 'qXfer:auxv:read::OFFSET,LENGTH' + Access the target's "auxiliary vector". *Note auxiliary + vector: OS Information. Note ANNEX must be empty. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:btrace:read:ANNEX:OFFSET,LENGTH' + + Return a description of the current branch trace. *Note + Branch Trace Format::. The annex part of the generic 'qXfer' + packet may have one of the following values: + + 'all' + Returns all available branch trace. + + 'new' + Returns all available branch trace if the branch trace + changed since the last read request. + + This packet is not probed by default; the remote stub must + request it by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:features:read:ANNEX:OFFSET,LENGTH' + Access the "target description". *Note Target Descriptions::. + The annex specifies which XML document to access. The main + description is always loaded from the 'target.xml' annex. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:libraries:read:ANNEX:OFFSET,LENGTH' + Access the target's list of loaded libraries. *Note Library + List Format::. The annex part of the generic 'qXfer' packet + must be empty (*note qXfer read::). + + Targets which maintain a list of libraries in the program's + memory do not need to implement this packet; it is designed + for platforms where the operating system manages the list of + loaded libraries. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:libraries-svr4:read:ANNEX:OFFSET,LENGTH' + Access the target's list of loaded libraries when the target + is an SVR4 platform. *Note Library List Format for SVR4 + Targets::. The annex part of the generic 'qXfer' packet must + be empty unless the remote stub indicated it supports the + augmented form of this packet by supplying an appropriate + 'qSupported' response (*note qXfer read::, *note + qSupported::). + + This packet is optional for better performance on SVR4 + targets. GDB uses memory read packets to read the SVR4 + library list otherwise. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + If the remote stub indicates it supports the augmented form of + this packet then the annex part of the generic 'qXfer' packet + may contain a semicolon-separated list of 'NAME=VALUE' + arguments. The currently supported arguments are: + + 'start=ADDRESS' + A hexadecimal number specifying the address of the + 'struct link_map' to start reading the library list from. + If unset or zero then the first 'struct link_map' in the + library list will be chosen as the starting point. + + 'prev=ADDRESS' + A hexadecimal number specifying the address of the + 'struct link_map' immediately preceding the 'struct + link_map' specified by the 'start' argument. If unset or + zero then the remote stub will expect that no 'struct + link_map' exists prior to the starting point. + + Arguments that are not understood by the remote stub will be + silently ignored. + + 'qXfer:memory-map:read::OFFSET,LENGTH' + Access the target's "memory-map". *Note Memory Map Format::. + The annex part of the generic 'qXfer' packet must be empty + (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:sdata:read::OFFSET,LENGTH' + + Read contents of the extra collected static tracepoint marker + information. The annex part of the generic 'qXfer' packet + must be empty (*note qXfer read::). *Note Tracepoint Action + Lists: Tracepoint Actions. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:siginfo:read::OFFSET,LENGTH' + Read contents of the extra signal information on the target + system. The annex part of the generic 'qXfer' packet must be + empty (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:spu:read:ANNEX:OFFSET,LENGTH' + Read contents of an 'spufs' file on the target system. The + annex specifies which file to read; it must be of the form + 'ID/NAME', where ID specifies an SPU context ID in the target + process, and NAME identifes the 'spufs' file in that context + to be accessed. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:threads:read::OFFSET,LENGTH' + Access the list of threads on target. *Note Thread List + Format::. The annex part of the generic 'qXfer' packet must + be empty (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:traceframe-info:read::OFFSET,LENGTH' + + Return a description of the current traceframe's contents. + *Note Traceframe Info Format::. The annex part of the generic + 'qXfer' packet must be empty (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:uib:read:PC:OFFSET,LENGTH' + + Return the unwind information block for PC. This packet is + used on OpenVMS/ia64 to ask the kernel unwind information. + + This packet is not probed by default. + + 'qXfer:fdpic:read:ANNEX:OFFSET,LENGTH' + Read contents of 'loadmap's on the target system. The annex, + either 'exec' or 'interp', specifies which 'loadmap', + executable 'loadmap' or interpreter 'loadmap' to read. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:osdata:read::OFFSET,LENGTH' + Access the target's "operating system information". *Note + Operating System Information::. + + Reply: + 'm DATA' + Data DATA (*note Binary Data::) has been read from the target. + There may be more data at a higher address (although it is + permitted to return 'm' even for the last valid block of data, + as long as at least one byte of data was read). DATA may have + fewer bytes than the LENGTH in the request. + + 'l DATA' + Data DATA (*note Binary Data::) has been read from the target. + There is no more data to be read. DATA may have fewer bytes + than the LENGTH in the request. + + 'l' + The OFFSET in the request is at the end of the data. There is + no more data to be read. + + 'E00' + The request was malformed, or ANNEX was invalid. + + 'E NN' + The offset was invalid, or there was an error encountered + reading the data. NN is a hex-encoded 'errno' value. + + '' + An empty reply indicates the OBJECT string was not recognized + by the stub, or that the object does not support reading. + +'qXfer:OBJECT:write:ANNEX:OFFSET:DATA...' + Write uninterpreted bytes into the target's special data area + identified by the keyword OBJECT, starting at OFFSET bytes into the + data. DATA... is the binary-encoded data (*note Binary Data::) to + be written. The content and encoding of ANNEX is specific to + OBJECT; it can supply additional details about what data to access. + + Here are the specific requests of this form defined so far. All + 'qXfer:OBJECT:write:...' requests use the same reply formats, + listed below. + + 'qXfer:siginfo:write::OFFSET:DATA...' + Write DATA to the extra signal information on the target + system. The annex part of the generic 'qXfer' packet must be + empty (*note qXfer write::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:spu:write:ANNEX:OFFSET:DATA...' + Write DATA to an 'spufs' file on the target system. The annex + specifies which file to write; it must be of the form + 'ID/NAME', where ID specifies an SPU context ID in the target + process, and NAME identifes the 'spufs' file in that context + to be accessed. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + Reply: + 'NN' + NN (hex encoded) is the number of bytes written. This may be + fewer bytes than supplied in the request. + + 'E00' + The request was malformed, or ANNEX was invalid. + + 'E NN' + The offset was invalid, or there was an error encountered + writing the data. NN is a hex-encoded 'errno' value. + + '' + An empty reply indicates the OBJECT string was not recognized + by the stub, or that the object does not support writing. + +'qXfer:OBJECT:OPERATION:...' + Requests of this form may be added in the future. When a stub does + not recognize the OBJECT keyword, or its support for OBJECT does + not recognize the OPERATION keyword, the stub must respond with an + empty packet. + +'qAttached:PID' + Return an indication of whether the remote server attached to an + existing process or created a new process. When the multiprocess + protocol extensions are supported (*note multiprocess + extensions::), PID is an integer in hexadecimal format identifying + the target process. Otherwise, GDB will omit the PID field and the + query packet will be simplified as 'qAttached'. + + This query is used, for example, to know whether the remote process + should be detached or killed when a GDB session is ended with the + 'quit' command. + + Reply: + '1' + The remote server attached to an existing process. + '0' + The remote server created a new process. + 'E NN' + A badly formed request or an error was encountered. + +'Qbtrace:bts' + Enable branch tracing for the current thread using bts tracing. + + Reply: + 'OK' + Branch tracing has been enabled. + 'E.errtext' + A badly formed request or an error was encountered. + +'Qbtrace:off' + Disable branch tracing for the current thread. + + Reply: + 'OK' + Branch tracing has been disabled. + 'E.errtext' + A badly formed request or an error was encountered. + + ---------- Footnotes ---------- + + (1) The 'qP' and 'qL' packets predate these conventions, and have +arguments without any terminator for the packet name; we suspect they +are in widespread use in places that are difficult to upgrade. The 'qC' +packet has no arguments, but some existing stubs (e.g. RedBoot) are +known to not check for the end of the packet. + + +File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol + +E.5 Architecture-Specific Protocol Details +========================================== + +This section describes how the remote protocol is applied to specific +target architectures. Also see *note Standard Target Features::, for +details of XML target descriptions for each architecture. + +* Menu: + +* ARM-Specific Protocol Details:: +* MIPS-Specific Protocol Details:: + + +File: gdb.info, Node: ARM-Specific Protocol Details, Next: MIPS-Specific Protocol Details, Up: Architecture-Specific Protocol Details + +E.5.1 ARM-specific Protocol Details +----------------------------------- + +* Menu: + +* ARM Breakpoint Kinds:: + + +File: gdb.info, Node: ARM Breakpoint Kinds, Up: ARM-Specific Protocol Details + +E.5.1.1 ARM Breakpoint Kinds +............................ + +These breakpoint kinds are defined for the 'Z0' and 'Z1' packets. + +2 + 16-bit Thumb mode breakpoint. + +3 + 32-bit Thumb mode (Thumb-2) breakpoint. + +4 + 32-bit ARM mode breakpoint. + + +File: gdb.info, Node: MIPS-Specific Protocol Details, Prev: ARM-Specific Protocol Details, Up: Architecture-Specific Protocol Details + +E.5.2 MIPS-specific Protocol Details +------------------------------------ + +* Menu: + +* MIPS Register packet Format:: +* MIPS Breakpoint Kinds:: + + +File: gdb.info, Node: MIPS Register packet Format, Next: MIPS Breakpoint Kinds, Up: MIPS-Specific Protocol Details + +E.5.2.1 MIPS Register Packet Format +................................... + +The following 'g'/'G' packets have previously been defined. In the +below, some thirty-two bit registers are transferred as sixty-four bits. +Those registers should be zero/sign extended (which?) to fill the space +allocated. Register bytes are transferred in target byte order. The +two nibbles within a register byte are transferred most-significant - +least-significant. + +MIPS32 + All registers are transferred as thirty-two bit quantities in the + order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 + floating-point registers; fsr; fir; fp. + +MIPS64 + All registers are transferred as sixty-four bit quantities + (including thirty-two bit registers such as 'sr'). The ordering is + the same as 'MIPS32'. + + +File: gdb.info, Node: MIPS Breakpoint Kinds, Prev: MIPS Register packet Format, Up: MIPS-Specific Protocol Details + +E.5.2.2 MIPS Breakpoint Kinds +............................. + +These breakpoint kinds are defined for the 'Z0' and 'Z1' packets. + +2 + 16-bit MIPS16 mode breakpoint. + +3 + 16-bit microMIPS mode breakpoint. + +4 + 32-bit standard MIPS mode breakpoint. + +5 + 32-bit microMIPS mode breakpoint. + + +File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol + +E.6 Tracepoint Packets +====================== + +Here we describe the packets GDB uses to implement tracepoints (*note +Tracepoints::). + +'QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]' + Create a new tracepoint, number N, at ADDR. If ENA is 'E', then + the tracepoint is enabled; if it is 'D', then the tracepoint is + disabled. STEP is the tracepoint's step count, and PASS is its + pass count. If an 'F' is present, then the tracepoint is to be a + fast tracepoint, and the FLEN is the number of bytes that the + target should copy elsewhere to make room for the tracepoint. If + an 'X' is present, it introduces a tracepoint condition, which + consists of a hexadecimal length, followed by a comma and + hex-encoded bytes, in a manner similar to action encodings as + described below. If the trailing '-' is present, further 'QTDP' + packets will follow to specify this tracepoint's actions. + + Replies: + 'OK' + The packet was understood and carried out. + 'qRelocInsn' + *Note Relocate instruction reply packet: Tracepoint Packets. + '' + The packet was not recognized. + +'QTDP:-N:ADDR:[S]ACTION...[-]' + Define actions to be taken when a tracepoint is hit. N and ADDR + must be the same as in the initial 'QTDP' packet for this + tracepoint. This packet may only be sent immediately after another + 'QTDP' packet that ended with a '-'. If the trailing '-' is + present, further 'QTDP' packets will follow, specifying more + actions for this tracepoint. + + In the series of action packets for a given tracepoint, at most one + can have an 'S' before its first ACTION. If such a packet is sent, + it and the following packets define "while-stepping" actions. Any + prior packets define ordinary actions -- that is, those taken when + the tracepoint is first hit. If no action packet has an 'S', then + all the packets in the series specify ordinary tracepoint actions. + + The 'ACTION...' portion of the packet is a series of actions, + concatenated without separators. Each action has one of the + following forms: + + 'R MASK' + Collect the registers whose bits are set in MASK. MASK is a + hexadecimal number whose I'th bit is set if register number I + should be collected. (The least significant bit is numbered + zero.) Note that MASK may be any number of digits long; it + may not fit in a 32-bit word. + + 'M BASEREG,OFFSET,LEN' + Collect LEN bytes of memory starting at the address in + register number BASEREG, plus OFFSET. If BASEREG is '-1', + then the range has a fixed address: OFFSET is the address of + the lowest byte to collect. The BASEREG, OFFSET, and LEN + parameters are all unsigned hexadecimal values (the '-1' value + for BASEREG is a special case). + + 'X LEN,EXPR' + Evaluate EXPR, whose length is LEN, and collect memory as it + directs. EXPR is an agent expression, as described in *note + Agent Expressions::. Each byte of the expression is encoded + as a two-digit hex number in the packet; LEN is the number of + bytes in the expression (and thus one-half the number of hex + digits in the packet). + + Any number of actions may be packed together in a single 'QTDP' + packet, as long as the packet does not exceed the maximum packet + length (400 bytes, for many stubs). There may be only one 'R' + action per tracepoint, and it must precede any 'M' or 'X' actions. + Any registers referred to by 'M' and 'X' actions must be collected + by a preceding 'R' action. (The "while-stepping" actions are + treated as if they were attached to a separate tracepoint, as far + as these restrictions are concerned.) + + Replies: + 'OK' + The packet was understood and carried out. + 'qRelocInsn' + *Note Relocate instruction reply packet: Tracepoint Packets. + '' + The packet was not recognized. + +'QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES' + Specify a source string of tracepoint N at address ADDR. This is + useful to get accurate reproduction of the tracepoints originally + downloaded at the beginning of the trace run. TYPE is the name of + the tracepoint part, such as 'cond' for the tracepoint's + conditional expression (see below for a list of types), while BYTES + is the string, encoded in hexadecimal. + + START is the offset of the BYTES within the overall source string, + while SLEN is the total length of the source string. This is + intended for handling source strings that are longer than will fit + in a single packet. + + The available string types are 'at' for the location, 'cond' for + the conditional, and 'cmd' for an action command. GDB sends a + separate packet for each command in the action list, in the same + order in which the commands are stored in the list. + + The target does not need to do anything with source strings except + report them back as part of the replies to the 'qTfP'/'qTsP' query + packets. + + Although this packet is optional, and GDB will only send it if the + target replies with 'TracepointSource' *Note General Query + Packets::, it makes both disconnected tracing and trace files much + easier to use. Otherwise the user must be careful that the + tracepoints in effect while looking at trace frames are identical + to the ones in effect during the trace run; even a small + discrepancy could cause 'tdump' not to work, or a particular trace + frame not be found. + +'QTDV:N:VALUE' + Create a new trace state variable, number N, with an initial value + of VALUE, which is a 64-bit signed integer. Both N and VALUE are + encoded as hexadecimal values. GDB has the option of not using + this packet for initial values of zero; the target should simply + create the trace state variables as they are mentioned in + expressions. + +'QTFrame:N' + Select the N'th tracepoint frame from the buffer, and use the + register and memory contents recorded there to answer subsequent + request packets from GDB. + + A successful reply from the stub indicates that the stub has found + the requested frame. The response is a series of parts, + concatenated without separators, describing the frame we selected. + Each part has one of the following forms: + + 'F F' + The selected frame is number N in the trace frame buffer; F is + a hexadecimal number. If F is '-1', then there was no frame + matching the criteria in the request packet. + + 'T T' + The selected trace frame records a hit of tracepoint number T; + T is a hexadecimal number. + +'QTFrame:pc:ADDR' + Like 'QTFrame:N', but select the first tracepoint frame after the + currently selected frame whose PC is ADDR; ADDR is a hexadecimal + number. + +'QTFrame:tdp:T' + Like 'QTFrame:N', but select the first tracepoint frame after the + currently selected frame that is a hit of tracepoint T; T is a + hexadecimal number. + +'QTFrame:range:START:END' + Like 'QTFrame:N', but select the first tracepoint frame after the + currently selected frame whose PC is between START (inclusive) and + END (inclusive); START and END are hexadecimal numbers. + +'QTFrame:outside:START:END' + Like 'QTFrame:range:START:END', but select the first frame + _outside_ the given range of addresses (exclusive). + +'qTMinFTPILen' + This packet requests the minimum length of instruction at which a + fast tracepoint (*note Set Tracepoints::) may be placed. For + instance, on the 32-bit x86 architecture, it is possible to use a + 4-byte jump, but it depends on the target system being able to + create trampolines in the first 64K of memory, which might or might + not be possible for that system. So the reply to this packet will + be 4 if it is able to arrange for that. + + Replies: + + '0' + The minimum instruction length is currently unknown. + 'LENGTH' + The minimum instruction length is LENGTH, where LENGTH is + greater or equal to 1. LENGTH is a hexadecimal number. A + reply of 1 means that a fast tracepoint may be placed on any + instruction regardless of size. + 'E' + An error has occurred. + '' + An empty reply indicates that the request is not supported by + the stub. + +'QTStart' + Begin the tracepoint experiment. Begin collecting data from + tracepoint hits in the trace frame buffer. This packet supports + the 'qRelocInsn' reply (*note Relocate instruction reply packet: + Tracepoint Packets.). + +'QTStop' + End the tracepoint experiment. Stop collecting trace frames. + +'QTEnable:N:ADDR' + Enable tracepoint N at address ADDR in a started tracepoint + experiment. If the tracepoint was previously disabled, then + collection of data from it will resume. + +'QTDisable:N:ADDR' + Disable tracepoint N at address ADDR in a started tracepoint + experiment. No more data will be collected from the tracepoint + unless 'QTEnable:N:ADDR' is subsequently issued. + +'QTinit' + Clear the table of tracepoints, and empty the trace frame buffer. + +'QTro:START1,END1:START2,END2:...' + Establish the given ranges of memory as "transparent". The stub + will answer requests for these ranges from memory's current + contents, if they were not collected as part of the tracepoint hit. + + GDB uses this to mark read-only regions of memory, like those + containing program code. Since these areas never change, they + should still have the same contents they did when the tracepoint + was hit, so there's no reason for the stub to refuse to provide + their contents. + +'QTDisconnected:VALUE' + Set the choice to what to do with the tracing run when GDB + disconnects from the target. A VALUE of 1 directs the target to + continue the tracing run, while 0 tells the target to stop tracing + if GDB is no longer in the picture. + +'qTStatus' + Ask the stub if there is a trace experiment running right now. + + The reply has the form: + + 'TRUNNING[;FIELD]...' + RUNNING is a single digit '1' if the trace is presently + running, or '0' if not. It is followed by semicolon-separated + optional fields that an agent may use to report additional + status. + + If the trace is not running, the agent may report any of several + explanations as one of the optional fields: + + 'tnotrun:0' + No trace has been run yet. + + 'tstop[:TEXT]:0' + The trace was stopped by a user-originated stop command. The + optional TEXT field is a user-supplied string supplied as part + of the stop command (for instance, an explanation of why the + trace was stopped manually). It is hex-encoded. + + 'tfull:0' + The trace stopped because the trace buffer filled up. + + 'tdisconnected:0' + The trace stopped because GDB disconnected from the target. + + 'tpasscount:TPNUM' + The trace stopped because tracepoint TPNUM exceeded its pass + count. + + 'terror:TEXT:TPNUM' + The trace stopped because tracepoint TPNUM had an error. The + string TEXT is available to describe the nature of the error + (for instance, a divide by zero in the condition expression). + TEXT is hex encoded. + + 'tunknown:0' + The trace stopped for some other reason. + + Additional optional fields supply statistical and other + information. Although not required, they are extremely useful for + users monitoring the progress of a trace run. If a trace has + stopped, and these numbers are reported, they must reflect the + state of the just-stopped trace. + + 'tframes:N' + The number of trace frames in the buffer. + + 'tcreated:N' + The total number of trace frames created during the run. This + may be larger than the trace frame count, if the buffer is + circular. + + 'tsize:N' + The total size of the trace buffer, in bytes. + + 'tfree:N' + The number of bytes still unused in the buffer. + + 'circular:N' + The value of the circular trace buffer flag. '1' means that + the trace buffer is circular and old trace frames will be + discarded if necessary to make room, '0' means that the trace + buffer is linear and may fill up. + + 'disconn:N' + The value of the disconnected tracing flag. '1' means that + tracing will continue after GDB disconnects, '0' means that + the trace run will stop. + +'qTP:TP:ADDR' + Ask the stub for the current state of tracepoint number TP at + address ADDR. + + Replies: + 'VHITS:USAGE' + The tracepoint has been hit HITS times so far during the trace + run, and accounts for USAGE in the trace buffer. Note that + 'while-stepping' steps are not counted as separate hits, but + the steps' space consumption is added into the usage number. + +'qTV:VAR' + Ask the stub for the value of the trace state variable number VAR. + + Replies: + 'VVALUE' + The value of the variable is VALUE. This will be the current + value of the variable if the user is examining a running + target, or a saved value if the variable was collected in the + trace frame that the user is looking at. Note that multiple + requests may result in different reply values, such as when + requesting values while the program is running. + + 'U' + The value of the variable is unknown. This would occur, for + example, if the user is examining a trace frame in which the + requested variable was not collected. + +'qTfP' +'qTsP' + These packets request data about tracepoints that are being used by + the target. GDB sends 'qTfP' to get the first piece of data, and + multiple 'qTsP' to get additional pieces. Replies to these packets + generally take the form of the 'QTDP' packets that define + tracepoints. (FIXME add detailed syntax) + +'qTfV' +'qTsV' + These packets request data about trace state variables that are on + the target. GDB sends 'qTfV' to get the first vari of data, and + multiple 'qTsV' to get additional variables. Replies to these + packets follow the syntax of the 'QTDV' packets that define trace + state variables. + +'qTfSTM' +'qTsSTM' + These packets request data about static tracepoint markers that + exist in the target program. GDB sends 'qTfSTM' to get the first + piece of data, and multiple 'qTsSTM' to get additional pieces. + Replies to these packets take the following form: + + Reply: + 'm ADDRESS:ID:EXTRA' + A single marker + 'm ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...' + a comma-separated list of markers + 'l' + (lower case letter 'L') denotes end of list. + 'E NN' + An error occurred. NN are hex digits. + '' + An empty reply indicates that the request is not supported by + the stub. + + ADDRESS is encoded in hex. ID and EXTRA are strings encoded in + hex. + + In response to each query, the target will reply with a list of one + or more markers, separated by commas. GDB will respond to each + reply with a request for more markers (using the 'qs' form of the + query), until the target responds with 'l' (lower-case ell, for + "last"). + +'qTSTMat:ADDRESS' + This packets requests data about static tracepoint markers in the + target program at ADDRESS. Replies to this packet follow the + syntax of the 'qTfSTM' and 'qTsSTM' packets that list static + tracepoint markers. + +'QTSave:FILENAME' + This packet directs the target to save trace data to the file name + FILENAME in the target's filesystem. FILENAME is encoded as a hex + string; the interpretation of the file name (relative vs absolute, + wild cards, etc) is up to the target. + +'qTBuffer:OFFSET,LEN' + Return up to LEN bytes of the current contents of trace buffer, + starting at OFFSET. The trace buffer is treated as if it were a + contiguous collection of traceframes, as per the trace file format. + The reply consists as many hex-encoded bytes as the target can + deliver in a packet; it is not an error to return fewer than were + asked for. A reply consisting of just 'l' indicates that no bytes + are available. + +'QTBuffer:circular:VALUE' + This packet directs the target to use a circular trace buffer if + VALUE is 1, or a linear buffer if the value is 0. + +'QTBuffer:size:SIZE' + This packet directs the target to make the trace buffer be of size + SIZE if possible. A value of '-1' tells the target to use whatever + size it prefers. + +'QTNotes:[TYPE:TEXT][;TYPE:TEXT]...' + This packet adds optional textual notes to the trace run. + Allowable types include 'user', 'notes', and 'tstop', the TEXT + fields are arbitrary strings, hex-encoded. + +E.6.1 Relocate instruction reply packet +--------------------------------------- + +When installing fast tracepoints in memory, the target may need to +relocate the instruction currently at the tracepoint address to a +different address in memory. For most instructions, a simple copy is +enough, but, for example, call instructions that implicitly push the +return address on the stack, and relative branches or other PC-relative +instructions require offset adjustment, so that the effect of executing +the instruction at a different address is the same as if it had executed +in the original location. + + In response to several of the tracepoint packets, the target may also +respond with a number of intermediate 'qRelocInsn' request packets +before the final result packet, to have GDB handle this relocation +operation. If a packet supports this mechanism, its documentation will +explicitly say so. See for example the above descriptions for the +'QTStart' and 'QTDP' packets. The format of the request is: + +'qRelocInsn:FROM;TO' + + This requests GDB to copy instruction at address FROM to address + TO, possibly adjusted so that executing the instruction at TO has + the same effect as executing it at FROM. GDB writes the adjusted + instruction to target memory starting at TO. + + Replies: +'qRelocInsn:ADJUSTED_SIZE' + Informs the stub the relocation is complete. ADJUSTED_SIZE is the + length in bytes of resulting relocated instruction sequence. +'E NN' + A badly formed request was detected, or an error was encountered + while relocating the instruction. + + +File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol + +E.7 Host I/O Packets +==================== + +The "Host I/O" packets allow GDB to perform I/O operations on the far +side of a remote link. For example, Host I/O is used to upload and +download files to a remote target with its own filesystem. Host I/O +uses the same constant values and data structure layout as the +target-initiated File-I/O protocol. However, the Host I/O packets are +structured differently. The target-initiated protocol relies on target +memory to store parameters and buffers. Host I/O requests are initiated +by GDB, and the target's memory is not involved. *Note File-I/O Remote +Protocol Extension::, for more details on the target-initiated protocol. + + The Host I/O request packets all encode a single operation along with +its arguments. They have this format: + +'vFile:OPERATION: PARAMETER...' + OPERATION is the name of the particular request; the target should + compare the entire packet name up to the second colon when checking + for a supported operation. The format of PARAMETER depends on the + operation. Numbers are always passed in hexadecimal. Negative + numbers have an explicit minus sign (i.e. two's complement is not + used). Strings (e.g. filenames) are encoded as a series of + hexadecimal bytes. The last argument to a system call may be a + buffer of escaped binary data (*note Binary Data::). + + The valid responses to Host I/O packets are: + +'F RESULT [, ERRNO] [; ATTACHMENT]' + RESULT is the integer value returned by this operation, usually + non-negative for success and -1 for errors. If an error has + occured, ERRNO will be included in the result. ERRNO will have a + value defined by the File-I/O protocol (*note Errno Values::). For + operations which return data, ATTACHMENT supplies the data as a + binary buffer. Binary buffers in response packets are escaped in + the normal way (*note Binary Data::). See the individual packet + documentation for the interpretation of RESULT and ATTACHMENT. + +'' + An empty response indicates that this operation is not recognized. + + These are the supported Host I/O operations: + +'vFile:open: PATHNAME, FLAGS, MODE' + Open a file at PATHNAME and return a file descriptor for it, or + return -1 if an error occurs. PATHNAME is a string, FLAGS is an + integer indicating a mask of open flags (*note Open Flags::), and + MODE is an integer indicating a mask of mode bits to use if the + file is created (*note mode_t Values::). *Note open::, for details + of the open flags and mode values. + +'vFile:close: FD' + Close the open file corresponding to FD and return 0, or -1 if an + error occurs. + +'vFile:pread: FD, COUNT, OFFSET' + Read data from the open file corresponding to FD. Up to COUNT + bytes will be read from the file, starting at OFFSET relative to + the start of the file. The target may read fewer bytes; common + reasons include packet size limits and an end-of-file condition. + The number of bytes read is returned. Zero should only be returned + for a successful read at the end of the file, or if COUNT was zero. + + The data read should be returned as a binary attachment on success. + If zero bytes were read, the response should include an empty + binary attachment (i.e. a trailing semicolon). The return value is + the number of target bytes read; the binary attachment may be + longer if some characters were escaped. + +'vFile:pwrite: FD, OFFSET, DATA' + Write DATA (a binary buffer) to the open file corresponding to FD. + Start the write at OFFSET from the start of the file. Unlike many + 'write' system calls, there is no separate COUNT argument; the + length of DATA in the packet is used. 'vFile:write' returns the + number of bytes written, which may be shorter than the length of + DATA, or -1 if an error occurred. + +'vFile:unlink: PATHNAME' + Delete the file at PATHNAME on the target. Return 0, or -1 if an + error occurs. PATHNAME is a string. + +'vFile:readlink: FILENAME' + Read value of symbolic link FILENAME on the target. Return the + number of bytes read, or -1 if an error occurs. + + The data read should be returned as a binary attachment on success. + If zero bytes were read, the response should include an empty + binary attachment (i.e. a trailing semicolon). The return value is + the number of target bytes read; the binary attachment may be + longer if some characters were escaped. + + +File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol + +E.8 Interrupts +============== + +When a program on the remote target is running, GDB may attempt to +interrupt it by sending a 'Ctrl-C', 'BREAK' or a 'BREAK' followed by +'g', control of which is specified via GDB's 'interrupt-sequence'. + + The precise meaning of 'BREAK' is defined by the transport mechanism +and may, in fact, be undefined. GDB does not currently define a 'BREAK' +mechanism for any of the network interfaces except for TCP, in which +case GDB sends the 'telnet' BREAK sequence. + + 'Ctrl-C', on the other hand, is defined and implemented for all +transport mechanisms. It is represented by sending the single byte +'0x03' without any of the usual packet overhead described in the +Overview section (*note Overview::). When a '0x03' byte is transmitted +as part of a packet, it is considered to be packet data and does _not_ +represent an interrupt. E.g., an 'X' packet (*note X packet::), used +for binary downloads, may include an unescaped '0x03' as part of its +packet. + + 'BREAK' followed by 'g' is also known as Magic SysRq g. When Linux +kernel receives this sequence from serial port, it stops execution and +connects to gdb. + + Stubs are not required to recognize these interrupt mechanisms and +the precise meaning associated with receipt of the interrupt is +implementation defined. If the target supports debugging of multiple +threads and/or processes, it should attempt to interrupt all +currently-executing threads and processes. If the stub is successful at +interrupting the running program, it should send one of the stop reply +packets (*note Stop Reply Packets::) to GDB as a result of successfully +stopping the program in all-stop mode, and a stop reply for each stopped +thread in non-stop mode. Interrupts received while the program is +stopped are discarded. + + +File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol + +E.9 Notification Packets +======================== + +The GDB remote serial protocol includes "notifications", packets that +require no acknowledgment. Both the GDB and the stub may send +notifications (although the only notifications defined at present are +sent by the stub). Notifications carry information without incurring +the round-trip latency of an acknowledgment, and so are useful for +low-impact communications where occasional packet loss is not a problem. + + A notification packet has the form '% DATA # CHECKSUM', where DATA is +the content of the notification, and CHECKSUM is a checksum of DATA, +computed and formatted as for ordinary GDB packets. A notification's +DATA never contains '$', '%' or '#' characters. Upon receiving a +notification, the recipient sends no '+' or '-' to acknowledge the +notification's receipt or to report its corruption. + + Every notification's DATA begins with a name, which contains no colon +characters, followed by a colon character. + + Recipients should silently ignore corrupted notifications and +notifications they do not understand. Recipients should restart timeout +periods on receipt of a well-formed notification, whether or not they +understand it. + + Senders should only send the notifications described here when this +protocol description specifies that they are permitted. In the future, +we may extend the protocol to permit existing notifications in new +contexts; this rule helps older senders avoid confusing newer +recipients. + + (Older versions of GDB ignore bytes received until they see the '$' +byte that begins an ordinary packet, so new stubs may transmit +notifications without fear of confusing older clients. There are no +notifications defined for GDB to send at the moment, but we assume that +most older stubs would ignore them, as well.) + + Each notification is comprised of three parts: +'NAME:EVENT' + The notification packet is sent by the side that initiates the + exchange (currently, only the stub does that), with EVENT carrying + the specific information about the notification. NAME is the name + of the notification. +'ACK' + The acknowledge sent by the other side, usually GDB, to acknowledge + the exchange and request the event. + + The purpose of an asynchronous notification mechanism is to report to +GDB that something interesting happened in the remote stub. + + The remote stub may send notification NAME:EVENT at any time, but GDB +acknowledges the notification when appropriate. The notification event +is pending before GDB acknowledges. Only one notification at a time may +be pending; if additional events occur before GDB has acknowledged the +previous notification, they must be queued by the stub for later +synchronous transmission in response to ACK packets from GDB. Because +the notification mechanism is unreliable, the stub is permitted to +resend a notification if it believes GDB may not have received it. + + Specifically, notifications may appear when GDB is not otherwise +reading input from the stub, or when GDB is expecting to read a normal +synchronous response or a '+'/'-' acknowledgment to a packet it has +sent. Notification packets are distinct from any other communication +from the stub so there is no ambiguity. + + After receiving a notification, GDB shall acknowledge it by sending a +ACK packet as a regular, synchronous request to the stub. Such +acknowledgment is not required to happen immediately, as GDB is +permitted to send other, unrelated packets to the stub first, which the +stub should process normally. + + Upon receiving a ACK packet, if the stub has other queued events to +report to GDB, it shall respond by sending a normal EVENT. GDB shall +then send another ACK packet to solicit further responses; again, it is +permitted to send other, unrelated packets as well which the stub should +process normally. + + If the stub receives a ACK packet and there are no additional EVENT +to report, the stub shall return an 'OK' response. At this point, GDB +has finished processing a notification and the stub has completed +sending any queued events. GDB won't accept any new notifications until +the final 'OK' is received . If further notification events occur, the +stub shall send a new notification, GDB shall accept the notification, +and the process shall be repeated. + + The process of asynchronous notification can be illustrated by the +following example: + <- %%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0; + ... + -> vStopped + <- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0; + -> vStopped + <- T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0; + -> vStopped + <- OK + + The following notifications are defined: + +NotificationAck Event Description + +Stop vStopped REPLY. The REPLY has the Report an asynchronous + form of a stop reply, as stop event in non-stop + described in *note Stop mode. + Reply Packets::. Refer + to *note Remote + Non-Stop::, for + information on how these + notifications are + acknowledged by GDB. + + +File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol + +E.10 Remote Protocol Support for Non-Stop Mode +============================================== + +GDB's remote protocol supports non-stop debugging of multi-threaded +programs, as described in *note Non-Stop Mode::. If the stub supports +non-stop mode, it should report that to GDB by including 'QNonStop+' in +its 'qSupported' response (*note qSupported::). + + GDB typically sends a 'QNonStop' packet only when establishing a new +connection with the stub. Entering non-stop mode does not alter the +state of any currently-running threads, but targets must stop all +threads in any already-attached processes when entering all-stop mode. +GDB uses the '?' packet as necessary to probe the target state after a +mode change. + + In non-stop mode, when an attached process encounters an event that +would otherwise be reported with a stop reply, it uses the asynchronous +notification mechanism (*note Notification Packets::) to inform GDB. In +contrast to all-stop mode, where all threads in all processes are +stopped when a stop reply is sent, in non-stop mode only the thread +reporting the stop event is stopped. That is, when reporting a 'S' or +'T' response to indicate completion of a step operation, hitting a +breakpoint, or a fault, only the affected thread is stopped; any other +still-running threads continue to run. When reporting a 'W' or 'X' +response, all running threads belonging to other attached processes +continue to run. + + In non-stop mode, the target shall respond to the '?' packet as +follows. First, any incomplete stop reply notification/'vStopped' +sequence in progress is abandoned. The target must begin a new sequence +reporting stop events for all stopped threads, whether or not it has +previously reported those events to GDB. The first stop reply is sent +as a synchronous reply to the '?' packet, and subsequent stop replies +are sent as responses to 'vStopped' packets using the mechanism +described above. The target must not send asynchronous stop reply +notifications until the sequence is complete. If all threads are +running when the target receives the '?' packet, or if the target is not +attached to any process, it shall respond 'OK'. + + +File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol + +E.11 Packet Acknowledgment +========================== + +By default, when either the host or the target machine receives a +packet, the first response expected is an acknowledgment: either '+' (to +indicate the package was received correctly) or '-' (to request +retransmission). This mechanism allows the GDB remote protocol to +operate over unreliable transport mechanisms, such as a serial line. + + In cases where the transport mechanism is itself reliable (such as a +pipe or TCP connection), the '+'/'-' acknowledgments are redundant. It +may be desirable to disable them in that case to reduce communication +overhead, or for other reasons. This can be accomplished by means of +the 'QStartNoAckMode' packet; *note QStartNoAckMode::. + + When in no-acknowledgment mode, neither the stub nor GDB shall send +or expect '+'/'-' protocol acknowledgments. The packet and response +format still includes the normal checksum, as described in *note +Overview::, but the checksum may be ignored by the receiver. + + If the stub supports 'QStartNoAckMode' and prefers to operate in +no-acknowledgment mode, it should report that to GDB by including +'QStartNoAckMode+' in its response to 'qSupported'; *note qSupported::. +If GDB also supports 'QStartNoAckMode' and it has not been disabled via +the 'set remote noack-packet off' command (*note Remote +Configuration::), GDB may then send a 'QStartNoAckMode' packet to the +stub. Only then may the stub actually turn off packet acknowledgments. +GDB sends a final '+' acknowledgment of the stub's 'OK' response, which +can be safely ignored by the stub. + + Note that 'set remote noack-packet' command only affects negotiation +between GDB and the stub when subsequent connections are made; it does +not affect the protocol acknowledgment state for any current connection. +Since '+'/'-' acknowledgments are enabled by default when a new +connection is established, there is also no protocol request to +re-enable the acknowledgments for the current connection, once disabled. + + +File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol + +E.12 Examples +============= + +Example sequence of a target being re-started. Notice how the restart +does not get any direct output: + + -> R00 + <- + + _target restarts_ + -> ? + <- + + <- T001:1234123412341234 + -> + + + Example sequence of a target being stepped by a single instruction: + + -> G1445... + <- + + -> s + <- + + _time passes_ + <- T001:1234123412341234 + -> + + -> g + <- + + <- 1455... + -> + + + +File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol + +E.13 File-I/O Remote Protocol Extension +======================================= + +* Menu: + +* File-I/O Overview:: +* Protocol Basics:: +* The F Request Packet:: +* The F Reply Packet:: +* The Ctrl-C Message:: +* Console I/O:: +* List of Supported Calls:: +* Protocol-specific Representation of Datatypes:: +* Constants:: +* File-I/O Examples:: + + +File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension + +E.13.1 File-I/O Overview +------------------------ + +The "File I/O remote protocol extension" (short: File-I/O) allows the +target to use the host's file system and console I/O to perform various +system calls. System calls on the target system are translated into a +remote protocol packet to the host system, which then performs the +needed actions and returns a response packet to the target system. This +simulates file system operations even on targets that lack file systems. + + The protocol is defined to be independent of both the host and target +systems. It uses its own internal representation of datatypes and +values. Both GDB and the target's GDB stub are responsible for +translating the system-dependent value representations into the internal +protocol representations when data is transmitted. + + The communication is synchronous. A system call is possible only +when GDB is waiting for a response from the 'C', 'c', 'S' or 's' +packets. While GDB handles the request for a system call, the target is +stopped to allow deterministic access to the target's memory. Therefore +File-I/O is not interruptible by target signals. On the other hand, it +is possible to interrupt File-I/O by a user interrupt ('Ctrl-C') within +GDB. + + The target's request to perform a host system call does not finish +the latest 'C', 'c', 'S' or 's' action. That means, after finishing the +system call, the target returns to continuing the previous activity +(continue, step). No additional continue or step request from GDB is +required. + + (gdb) continue + <- target requests 'system call X' + target is stopped, GDB executes system call + -> GDB returns result + ... target continues, GDB returns to wait for the target + <- target hits breakpoint and sends a Txx packet + + The protocol only supports I/O on the console and to regular files on +the host file system. Character or block special devices, pipes, named +pipes, sockets or any other communication method on the host system are +not supported by this protocol. + + File I/O is not supported in non-stop mode. + + +File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension + +E.13.2 Protocol Basics +---------------------- + +The File-I/O protocol uses the 'F' packet as the request as well as +reply packet. Since a File-I/O system call can only occur when GDB is +waiting for a response from the continuing or stepping target, the +File-I/O request is a reply that GDB has to expect as a result of a +previous 'C', 'c', 'S' or 's' packet. This 'F' packet contains all +information needed to allow GDB to call the appropriate host system +call: + + * A unique identifier for the requested system call. + + * All parameters to the system call. Pointers are given as addresses + in the target memory address space. Pointers to strings are given + as pointer/length pair. Numerical values are given as they are. + Numerical control flags are given in a protocol-specific + representation. + + At this point, GDB has to perform the following actions. + + * If the parameters include pointer values to data needed as input to + a system call, GDB requests this data from the target with a + standard 'm' packet request. This additional communication has to + be expected by the target implementation and is handled as any + other 'm' packet. + + * GDB translates all value from protocol representation to host + representation as needed. Datatypes are coerced into the host + types. + + * GDB calls the system call. + + * It then coerces datatypes back to protocol representation. + + * If the system call is expected to return data in buffer space + specified by pointer parameters to the call, the data is + transmitted to the target using a 'M' or 'X' packet. This packet + has to be expected by the target implementation and is handled as + any other 'M' or 'X' packet. + + Eventually GDB replies with another 'F' packet which contains all +necessary information for the target to continue. This at least +contains + + * Return value. + + * 'errno', if has been changed by the system call. + + * "Ctrl-C" flag. + + After having done the needed type and value coercion, the target +continues the latest continue or step action. + + +File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension + +E.13.3 The 'F' Request Packet +----------------------------- + +The 'F' request packet has the following format: + +'FCALL-ID,PARAMETER...' + + CALL-ID is the identifier to indicate the host system call to be + called. This is just the name of the function. + + PARAMETER... are the parameters to the system call. Parameters are + hexadecimal integer values, either the actual values in case of + scalar datatypes, pointers to target buffer space in case of + compound datatypes and unspecified memory areas, or pointer/length + pairs in case of string parameters. These are appended to the + CALL-ID as a comma-delimited list. All values are transmitted in + ASCII string representation, pointer/length pairs separated by a + slash. + + +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 + +E.13.4 The 'F' Reply Packet +--------------------------- + +The 'F' reply packet has the following format: + +'FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT' + + RETCODE is the return code of the system call as hexadecimal value. + + ERRNO is the 'errno' set by the call, in protocol-specific + representation. This parameter can be omitted if the call was + successful. + + CTRL-C FLAG is only sent if the user requested a break. In this + case, ERRNO must be sent as well, even if the call was successful. + The CTRL-C FLAG itself consists of the character 'C': + + F0,0,C + + or, if the call was interrupted before the host call has been + performed: + + F-1,4,C + + assuming 4 is the protocol-specific representation of 'EINTR'. + + +File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension + +E.13.5 The 'Ctrl-C' Message +--------------------------- + +If the 'Ctrl-C' flag is set in the GDB reply packet (*note The F Reply +Packet::), the target should behave as if it had gotten a break message. +The meaning for the target is "system call interrupted by 'SIGINT'". +Consequentially, the target should actually stop (as with a break +message) and return to GDB with a 'T02' packet. + + It's important for the target to know in which state the system call +was interrupted. There are two possible cases: + + * The system call hasn't been performed on the host yet. + + * The system call on the host has been finished. + + These two states can be distinguished by the target by the value of +the returned 'errno'. If it's the protocol representation of 'EINTR', +the system call hasn't been performed. This is equivalent to the +'EINTR' handling on POSIX systems. In any other case, the target may +presume that the system call has been finished -- successfully or not -- +and should behave as if the break message arrived right after the system +call. + + GDB must behave reliably. If the system call has not been called +yet, GDB may send the 'F' reply immediately, setting 'EINTR' as 'errno' +in the packet. If the system call on the host has been finished before +the user requests a break, the full action must be finished by GDB. +This requires sending 'M' or 'X' packets as necessary. The 'F' packet +may only be sent when either nothing has happened or the full action has +been completed. + + +File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension + +E.13.6 Console I/O +------------------ + +By default and if not explicitly closed by the target system, the file +descriptors 0, 1 and 2 are connected to the GDB console. Output on the +GDB console is handled as any other file output operation ('write(1, +...)' or 'write(2, ...)'). Console input is handled by GDB so that +after the target read request from file descriptor 0 all following +typing is buffered until either one of the following conditions is met: + + * The user types 'Ctrl-c'. The behaviour is as explained above, and + the 'read' system call is treated as finished. + + * The user presses . This is treated as end of input with a + trailing newline. + + * The user types 'Ctrl-d'. This is treated as end of input. No + trailing character (neither newline nor 'Ctrl-D') is appended to + the input. + + If the user has typed more characters than fit in the buffer given to +the 'read' call, the trailing characters are buffered in GDB until +either another 'read(0, ...)' is requested by the target, or debugging +is stopped at the user's request. + + +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 + +E.13.7 List of Supported Calls +------------------------------ + +* Menu: + +* open:: +* close:: +* read:: +* write:: +* lseek:: +* rename:: +* unlink:: +* stat/fstat:: +* gettimeofday:: +* isatty:: +* system:: + + +File: gdb.info, Node: open, Next: close, Up: List of Supported Calls + +open +.... + +Synopsis: + int open(const char *pathname, int flags); + int open(const char *pathname, int flags, mode_t mode); + +Request: + 'Fopen,PATHPTR/LEN,FLAGS,MODE' + + FLAGS is the bitwise 'OR' of the following values: + + 'O_CREAT' + If the file does not exist it will be created. The host rules + apply as far as file ownership and time stamps are concerned. + + 'O_EXCL' + When used with 'O_CREAT', if the file already exists it is an + error and open() fails. + + 'O_TRUNC' + If the file already exists and the open mode allows writing + ('O_RDWR' or 'O_WRONLY' is given) it will be truncated to zero + length. + + 'O_APPEND' + The file is opened in append mode. + + 'O_RDONLY' + The file is opened for reading only. + + 'O_WRONLY' + The file is opened for writing only. + + 'O_RDWR' + The file is opened for reading and writing. + + Other bits are silently ignored. + + MODE is the bitwise 'OR' of the following values: + + 'S_IRUSR' + User has read permission. + + 'S_IWUSR' + User has write permission. + + 'S_IRGRP' + Group has read permission. + + 'S_IWGRP' + Group has write permission. + + 'S_IROTH' + Others have read permission. + + 'S_IWOTH' + Others have write permission. + + Other bits are silently ignored. + +Return value: + 'open' returns the new file descriptor or -1 if an error occurred. + +Errors: + + 'EEXIST' + PATHNAME already exists and 'O_CREAT' and 'O_EXCL' were used. + + 'EISDIR' + PATHNAME refers to a directory. + + 'EACCES' + The requested access is not allowed. + + 'ENAMETOOLONG' + PATHNAME was too long. + + 'ENOENT' + A directory component in PATHNAME does not exist. + + 'ENODEV' + PATHNAME refers to a device, pipe, named pipe or socket. + + 'EROFS' + PATHNAME refers to a file on a read-only filesystem and write + access was requested. + + 'EFAULT' + PATHNAME is an invalid pointer value. + + 'ENOSPC' + No space on device to create the file. + + 'EMFILE' + The process already has the maximum number of files open. + + 'ENFILE' + The limit on the total number of files open on the system has + been reached. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls + +close +..... + +Synopsis: + int close(int fd); + +Request: + 'Fclose,FD' + +Return value: + 'close' returns zero on success, or -1 if an error occurred. + +Errors: + + 'EBADF' + FD isn't a valid open file descriptor. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls + +read +.... + +Synopsis: + int read(int fd, void *buf, unsigned int count); + +Request: + 'Fread,FD,BUFPTR,COUNT' + +Return value: + On success, the number of bytes read is returned. Zero indicates + end of file. If count is zero, read returns zero as well. On + error, -1 is returned. + +Errors: + + 'EBADF' + FD is not a valid file descriptor or is not open for reading. + + 'EFAULT' + BUFPTR is an invalid pointer value. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls + +write +..... + +Synopsis: + int write(int fd, const void *buf, unsigned int count); + +Request: + 'Fwrite,FD,BUFPTR,COUNT' + +Return value: + On success, the number of bytes written are returned. Zero + indicates nothing was written. On error, -1 is returned. + +Errors: + + 'EBADF' + FD is not a valid file descriptor or is not open for writing. + + 'EFAULT' + BUFPTR is an invalid pointer value. + + 'EFBIG' + An attempt was made to write a file that exceeds the + host-specific maximum file size allowed. + + 'ENOSPC' + No space on device to write the data. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls + +lseek +..... + +Synopsis: + long lseek (int fd, long offset, int flag); + +Request: + 'Flseek,FD,OFFSET,FLAG' + + FLAG is one of: + + 'SEEK_SET' + The offset is set to OFFSET bytes. + + 'SEEK_CUR' + The offset is set to its current location plus OFFSET bytes. + + 'SEEK_END' + The offset is set to the size of the file plus OFFSET bytes. + +Return value: + On success, the resulting unsigned offset in bytes from the + beginning of the file is returned. Otherwise, a value of -1 is + returned. + +Errors: + + 'EBADF' + FD is not a valid open file descriptor. + + 'ESPIPE' + FD is associated with the GDB console. + + 'EINVAL' + FLAG is not a proper value. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls + +rename +...... + +Synopsis: + int rename(const char *oldpath, const char *newpath); + +Request: + 'Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN' + +Return value: + On success, zero is returned. On error, -1 is returned. + +Errors: + + 'EISDIR' + NEWPATH is an existing directory, but OLDPATH is not a + directory. + + 'EEXIST' + NEWPATH is a non-empty directory. + + 'EBUSY' + OLDPATH or NEWPATH is a directory that is in use by some + process. + + 'EINVAL' + An attempt was made to make a directory a subdirectory of + itself. + + 'ENOTDIR' + A component used as a directory in OLDPATH or new path is not + a directory. Or OLDPATH is a directory and NEWPATH exists but + is not a directory. + + 'EFAULT' + OLDPATHPTR or NEWPATHPTR are invalid pointer values. + + 'EACCES' + No access to the file or the path of the file. + + 'ENAMETOOLONG' + + OLDPATH or NEWPATH was too long. + + 'ENOENT' + A directory component in OLDPATH or NEWPATH does not exist. + + 'EROFS' + The file is on a read-only filesystem. + + 'ENOSPC' + The device containing the file has no room for the new + directory entry. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls + +unlink +...... + +Synopsis: + int unlink(const char *pathname); + +Request: + 'Funlink,PATHNAMEPTR/LEN' + +Return value: + On success, zero is returned. On error, -1 is returned. + +Errors: + + 'EACCES' + No access to the file or the path of the file. + + 'EPERM' + The system does not allow unlinking of directories. + + 'EBUSY' + The file PATHNAME cannot be unlinked because it's being used + by another process. + + 'EFAULT' + PATHNAMEPTR is an invalid pointer value. + + 'ENAMETOOLONG' + PATHNAME was too long. + + 'ENOENT' + A directory component in PATHNAME does not exist. + + 'ENOTDIR' + A component of the path is not a directory. + + 'EROFS' + The file is on a read-only filesystem. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls + +stat/fstat +.......... + +Synopsis: + int stat(const char *pathname, struct stat *buf); + int fstat(int fd, struct stat *buf); + +Request: + 'Fstat,PATHNAMEPTR/LEN,BUFPTR' + 'Ffstat,FD,BUFPTR' + +Return value: + On success, zero is returned. On error, -1 is returned. + +Errors: + + 'EBADF' + FD is not a valid open file. + + 'ENOENT' + A directory component in PATHNAME does not exist or the path + is an empty string. + + 'ENOTDIR' + A component of the path is not a directory. + + 'EFAULT' + PATHNAMEPTR is an invalid pointer value. + + 'EACCES' + No access to the file or the path of the file. + + 'ENAMETOOLONG' + PATHNAME was too long. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls + +gettimeofday +............ + +Synopsis: + int gettimeofday(struct timeval *tv, void *tz); + +Request: + 'Fgettimeofday,TVPTR,TZPTR' + +Return value: + On success, 0 is returned, -1 otherwise. + +Errors: + + 'EINVAL' + TZ is a non-NULL pointer. + + 'EFAULT' + TVPTR and/or TZPTR is an invalid pointer value. + + +File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls + +isatty +...... + +Synopsis: + int isatty(int fd); + +Request: + 'Fisatty,FD' + +Return value: + Returns 1 if FD refers to the GDB console, 0 otherwise. + +Errors: + + 'EINTR' + The call was interrupted by the user. + + Note that the 'isatty' call is treated as a special case: it returns +1 to the target if the file descriptor is attached to the GDB console, 0 +otherwise. Implementing through system calls would require implementing +'ioctl' and would be more complex than needed. + + +File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls + +system +...... + +Synopsis: + int system(const char *command); + +Request: + 'Fsystem,COMMANDPTR/LEN' + +Return value: + If LEN is zero, the return value indicates whether a shell is + available. A zero return value indicates a shell is not available. + For non-zero LEN, the value returned is -1 on error and the return + status of the command otherwise. Only the exit status of the + command is returned, which is extracted from the host's 'system' + return value by calling 'WEXITSTATUS(retval)'. In case '/bin/sh' + could not be executed, 127 is returned. + +Errors: + + 'EINTR' + The call was interrupted by the user. + + GDB takes over the full task of calling the necessary host calls to +perform the 'system' call. The return value of 'system' on the host is +simplified before it's returned to the target. Any termination signal +information from the child process is discarded, and the return value +consists entirely of the exit status of the called command. + + Due to security concerns, the 'system' call is by default refused by +GDB. The user has to allow this call explicitly with the 'set remote +system-call-allowed 1' command. + +'set remote system-call-allowed' + Control whether to allow the 'system' calls in the File I/O + protocol for the remote target. The default is zero (disabled). + +'show remote system-call-allowed' + Show whether the 'system' calls are allowed in the File I/O + protocol. + + +File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension + +E.13.8 Protocol-specific Representation of Datatypes +---------------------------------------------------- + +* Menu: + +* Integral Datatypes:: +* Pointer Values:: +* Memory Transfer:: +* struct stat:: +* struct timeval:: + + +File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes + +Integral Datatypes +.................. + +The integral datatypes used in the system calls are 'int', 'unsigned +int', 'long', 'unsigned long', 'mode_t', and 'time_t'. + + 'int', 'unsigned int', 'mode_t' and 'time_t' are implemented as 32 +bit values in this protocol. + + 'long' and 'unsigned long' are implemented as 64 bit types. + + *Note Limits::, for corresponding MIN and MAX values (similar to +those in 'limits.h') to allow range checking on host and target. + + 'time_t' datatypes are defined as seconds since the Epoch. + + All integral datatypes transferred as part of a memory read or write +of a structured datatype e.g. a 'struct stat' have to be given in big +endian byte order. + + +File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes + +Pointer Values +.............. + +Pointers to target data are transmitted as they are. An exception is +made for pointers to buffers for which the length isn't transmitted as +part of the function call, namely strings. Strings are transmitted as a +pointer/length pair, both as hex values, e.g. + + 1aaf/12 + +which is a pointer to data of length 18 bytes at position 0x1aaf. The +length is defined as the full string length in bytes, including the +trailing null byte. For example, the string '"hello world"' at address +0x123456 is transmitted as + + 123456/d + + +File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes + +Memory Transfer +............... + +Structured data which is transferred using a memory read or write (for +example, a 'struct stat') is expected to be in a protocol-specific +format with all scalar multibyte datatypes being big endian. +Translation to this representation needs to be done both by the target +before the 'F' packet is sent, and by GDB before it transfers memory to +the target. Transferred pointers to structured data should point to the +already-coerced data at any time. + + +File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes + +struct stat +........... + +The buffer of type 'struct stat' used by the target and GDB is defined +as follows: + + struct stat { + unsigned int st_dev; /* device */ + unsigned int st_ino; /* inode */ + mode_t st_mode; /* protection */ + unsigned int st_nlink; /* number of hard links */ + unsigned int st_uid; /* user ID of owner */ + unsigned int st_gid; /* group ID of owner */ + unsigned int st_rdev; /* device type (if inode device) */ + unsigned long st_size; /* total size, in bytes */ + unsigned long st_blksize; /* blocksize for filesystem I/O */ + unsigned long st_blocks; /* number of blocks allocated */ + time_t st_atime; /* time of last access */ + time_t st_mtime; /* time of last modification */ + time_t st_ctime; /* time of last change */ + }; + + The integral datatypes conform to the definitions given in the +appropriate section (see *note Integral Datatypes::, for details) so +this structure is of size 64 bytes. + + The values of several fields have a restricted meaning and/or range +of values. + +'st_dev' + A value of 0 represents a file, 1 the console. + +'st_ino' + No valid meaning for the target. Transmitted unchanged. + +'st_mode' + Valid mode bits are described in *note Constants::. Any other bits + have currently no meaning for the target. + +'st_uid' +'st_gid' +'st_rdev' + No valid meaning for the target. Transmitted unchanged. + +'st_atime' +'st_mtime' +'st_ctime' + These values have a host and file system dependent accuracy. + Especially on Windows hosts, the file system may not support exact + timing values. + + The target gets a 'struct stat' of the above representation and is +responsible for coercing it to the target representation before +continuing. + + Note that due to size differences between the host, target, and +protocol representations of 'struct stat' members, these members could +eventually get truncated on the target. + + +File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes + +struct timeval +.............. + +The buffer of type 'struct timeval' used by the File-I/O protocol is +defined as follows: + + struct timeval { + time_t tv_sec; /* second */ + long tv_usec; /* microsecond */ + }; + + The integral datatypes conform to the definitions given in the +appropriate section (see *note Integral Datatypes::, for details) so +this structure is of size 8 bytes. + + +File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension + +E.13.9 Constants +---------------- + +The following values are used for the constants inside of the protocol. +GDB and target are responsible for translating these values before and +after the call as needed. + +* Menu: + +* Open Flags:: +* mode_t Values:: +* Errno Values:: +* Lseek Flags:: +* Limits:: + + +File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants + +Open Flags +.......... + +All values are given in hexadecimal representation. + + O_RDONLY 0x0 + O_WRONLY 0x1 + O_RDWR 0x2 + O_APPEND 0x8 + O_CREAT 0x200 + O_TRUNC 0x400 + O_EXCL 0x800 + + +File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants + +mode_t Values +............. + +All values are given in octal representation. + + S_IFREG 0100000 + S_IFDIR 040000 + S_IRUSR 0400 + S_IWUSR 0200 + S_IXUSR 0100 + S_IRGRP 040 + S_IWGRP 020 + S_IXGRP 010 + S_IROTH 04 + S_IWOTH 02 + S_IXOTH 01 + + +File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants + +Errno Values +............ + +All values are given in decimal representation. + + EPERM 1 + ENOENT 2 + EINTR 4 + EBADF 9 + EACCES 13 + EFAULT 14 + EBUSY 16 + EEXIST 17 + ENODEV 19 + ENOTDIR 20 + EISDIR 21 + EINVAL 22 + ENFILE 23 + EMFILE 24 + EFBIG 27 + ENOSPC 28 + ESPIPE 29 + EROFS 30 + ENAMETOOLONG 91 + EUNKNOWN 9999 + + 'EUNKNOWN' is used as a fallback error value if a host system returns +any error value not in the list of supported error numbers. + + +File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants + +Lseek Flags +........... + + SEEK_SET 0 + SEEK_CUR 1 + SEEK_END 2 + + +File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants + +Limits +...... + +All values are given in decimal representation. + + INT_MIN -2147483648 + INT_MAX 2147483647 + UINT_MAX 4294967295 + LONG_MIN -9223372036854775808 + LONG_MAX 9223372036854775807 + ULONG_MAX 18446744073709551615 + + +File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension + +E.13.10 File-I/O Examples +------------------------- + +Example sequence of a write call, file descriptor 3, buffer is at target +address 0x1234, 6 bytes should be written: + + <- Fwrite,3,1234,6 + _request memory read from target_ + -> m1234,6 + <- XXXXXX + _return "6 bytes written"_ + -> F6 + + Example sequence of a read call, file descriptor 3, buffer is at +target address 0x1234, 6 bytes should be read: + + <- Fread,3,1234,6 + _request memory write to target_ + -> X1234,6:XXXXXX + _return "6 bytes read"_ + -> F6 + + Example sequence of a read call, call fails on the host due to +invalid file descriptor ('EBADF'): + + <- Fread,3,1234,6 + -> F-1,9 + + Example sequence of a read call, user presses 'Ctrl-c' before syscall +on host is called: + + <- Fread,3,1234,6 + -> F-1,4,C + <- T02 + + Example sequence of a read call, user presses 'Ctrl-c' after syscall +on host is called: + + <- Fread,3,1234,6 + -> X1234,6:XXXXXX + <- T02 + + +File: gdb.info, Node: Library List Format, Next: Library List Format for SVR4 Targets, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol + +E.14 Library List Format +======================== + +On some platforms, a dynamic loader (e.g. 'ld.so') runs in the same +process as your application to manage libraries. In this case, GDB can +use the loader's symbol table and normal memory operations to maintain a +list of shared libraries. On other platforms, the operating system +manages loaded libraries. GDB can not retrieve the list of currently +loaded libraries through memory operations, so it uses the +'qXfer:libraries:read' packet (*note qXfer library list read::) instead. +The remote stub queries the target's operating system and reports which +libraries are loaded. + + The 'qXfer:libraries:read' packet returns an XML document which lists +loaded libraries and their offsets. Each library has an associated name +and one or more segment or section base addresses, which report where +the library was loaded in memory. + + For the common case of libraries that are fully linked binaries, the +library should have a list of segments. If the target supports dynamic +linking of a relocatable object file, its library XML element should +instead include a list of allocated sections. The segment or section +bases are start addresses, not relocation offsets; they do not depend on +the library's link-time base addresses. + + GDB must be linked with the Expat library to support XML library +lists. *Note Expat::. + + A simple memory map, with one loaded library relocated by a single +offset, looks like this: + + + + + + + + Another simple memory map, with one loaded library with three +allocated sections (.text, .data, .bss), looks like this: + + + +
+
+
+ + + + The format of a library list is described by this DTD: + + + + + + + + + + + + In addition, segments and section descriptors cannot be mixed within +a single library element, and you must supply at least one segment or +section for each library. + + +File: gdb.info, Node: Library List Format for SVR4 Targets, Next: Memory Map Format, Prev: Library List Format, Up: Remote Protocol + +E.15 Library List Format for SVR4 Targets +========================================= + +On SVR4 platforms GDB can use the symbol table of a dynamic loader (e.g. +'ld.so') and normal memory operations to maintain a list of shared +libraries. Still a special library list provided by this packet is more +efficient for the GDB remote protocol. + + The 'qXfer:libraries-svr4:read' packet returns an XML document which +lists loaded libraries and their SVR4 linker parameters. For each +library on SVR4 target, the following parameters are reported: + + - 'name', the absolute file name from the 'l_name' field of 'struct + link_map'. + - 'lm' with address of 'struct link_map' used for TLS (Thread Local + Storage) access. + - 'l_addr', the displacement as read from the field 'l_addr' of + 'struct link_map'. For prelinked libraries this is not an absolute + memory address. It is a displacement of absolute memory address + against address the file was prelinked to during the library load. + - 'l_ld', which is memory address of the 'PT_DYNAMIC' segment + + Additionally the single 'main-lm' attribute specifies address of +'struct link_map' used for the main executable. This parameter is used +for TLS access and its presence is optional. + + GDB must be linked with the Expat library to support XML SVR4 library +lists. *Note Expat::. + + A simple memory map, with two loaded libraries (which do not use +prelink), looks like this: + + + + + + + The format of an SVR4 library list is described by this DTD: + + + + + + + + + + + + +File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format for SVR4 Targets, Up: Remote Protocol + +E.16 Memory Map Format +====================== + +To be able to write into flash memory, GDB needs to obtain a memory map +from the target. This section describes the format of the memory map. + + The memory map is obtained using the 'qXfer:memory-map:read' (*note +qXfer memory map read::) packet and is an XML document that lists memory +regions. + + GDB must be linked with the Expat library to support XML memory maps. +*Note Expat::. + + The top-level structure of the document is shown below: + + + + + region... + + + Each region can be either: + + * A region of RAM starting at ADDR and extending for LENGTH bytes + from there: + + + + * A region of read-only memory: + + + + * A region of flash memory, with erasure blocks BLOCKSIZE bytes in + length: + + + BLOCKSIZE + + + Regions must not overlap. GDB assumes that areas of memory not +covered by the memory map are RAM, and uses the ordinary 'M' and 'X' +packets to write to addresses in such ranges. + + The formal DTD for memory map format is given below: + + + + + + + + + + + + + + + + + +File: gdb.info, Node: Thread List Format, Next: Traceframe Info Format, Prev: Memory Map Format, Up: Remote Protocol + +E.17 Thread List Format +======================= + +To efficiently update the list of threads and their attributes, GDB +issues the 'qXfer:threads:read' packet (*note qXfer threads read::) and +obtains the XML document with the following structure: + + + + + ... description ... + + + + Each 'thread' element must have the 'id' attribute that identifies +the thread (*note thread-id syntax::). The 'core' attribute, if +present, specifies which processor core the thread was last executing +on. The content of the of 'thread' element is interpreted as +human-readable auxilliary information. + + +File: gdb.info, Node: Traceframe Info Format, Next: Branch Trace Format, Prev: Thread List Format, Up: Remote Protocol + +E.18 Traceframe Info Format +=========================== + +To be able to know which objects in the inferior can be examined when +inspecting a tracepoint hit, GDB needs to obtain the list of memory +ranges, registers and trace state variables that have been collected in +a traceframe. + + This list is obtained using the 'qXfer:traceframe-info:read' (*note +qXfer traceframe info read::) packet and is an XML document. + + GDB must be linked with the Expat library to support XML traceframe +info discovery. *Note Expat::. + + The top-level structure of the document is shown below: + + + + + block... + + + Each traceframe block can be either: + + * A region of collected memory starting at ADDR and extending for + LENGTH bytes from there: + + + + * A block indicating trace state variable numbered NUMBER has been + collected: + + + + The formal DTD for the traceframe info format is given below: + + + + + + + + + + +File: gdb.info, Node: Branch Trace Format, Prev: Traceframe Info Format, Up: Remote Protocol + +E.19 Branch Trace Format +======================== + +In order to display the branch trace of an inferior thread, GDB needs to +obtain the list of branches. This list is represented as list of +sequential code blocks that are connected via branches. The code in +each block has been executed sequentially. + + This list is obtained using the 'qXfer:btrace:read' (*note qXfer +btrace read::) packet and is an XML document. + + GDB must be linked with the Expat library to support XML traceframe +info discovery. *Note Expat::. + + The top-level structure of the document is shown below: + + + + + block... + + + * A block of sequentially executed instructions starting at BEGIN and + ending at END: + + + + The formal DTD for the branch trace format is given below: + + + + + + + + +File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top + +Appendix F The GDB Agent Expression Mechanism +********************************************* + +In some applications, it is not feasible for the debugger to interrupt +the program's execution long enough for the developer to learn anything +helpful about its behavior. If the program's correctness depends on its +real-time behavior, delays introduced by a debugger might cause the +program to fail, even when the code itself is correct. It is useful to +be able to observe the program's behavior without interrupting it. + + Using GDB's 'trace' and 'collect' commands, the user can specify +locations in the program, and arbitrary expressions to evaluate when +those locations are reached. Later, using the 'tfind' command, she can +examine the values those expressions had when the program hit the trace +points. The expressions may also denote objects in memory -- structures +or arrays, for example -- whose values GDB should record; while visiting +a particular tracepoint, the user may inspect those objects as if they +were in memory at that moment. However, because GDB records these +values without interacting with the user, it can do so quickly and +unobtrusively, hopefully not disturbing the program's behavior. + + When GDB is debugging a remote target, the GDB "agent" code running +on the target computes the values of the expressions itself. To avoid +having a full symbolic expression evaluator on the agent, GDB translates +expressions in the source language into a simpler bytecode language, and +then sends the bytecode to the agent; the agent then executes the +bytecode, and records the values for GDB to retrieve later. + + The bytecode language is simple; there are forty-odd opcodes, the +bulk of which are the usual vocabulary of C operands (addition, +subtraction, shifts, and so on) and various sizes of literals and memory +reference operations. The bytecode interpreter operates strictly on +machine-level values -- various sizes of integers and floating point +numbers -- and requires no information about types or symbols; thus, the +interpreter's internal data structures are simple, and each bytecode +requires only a few native machine instructions to implement it. The +interpreter is small, and strict limits on the memory and time required +to evaluate an expression are easy to determine, making it suitable for +use by the debugging agent in real-time applications. + +* Menu: + +* General Bytecode Design:: Overview of the interpreter. +* Bytecode Descriptions:: What each one does. +* Using Agent Expressions:: How agent expressions fit into the big picture. +* Varying Target Capabilities:: How to discover what the target can do. +* Rationale:: Why we did it this way. + + +File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions + +F.1 General Bytecode Design +=========================== + +The agent represents bytecode expressions as an array of bytes. Each +instruction is one byte long (thus the term "bytecode"). Some +instructions are followed by operand bytes; for example, the 'goto' +instruction is followed by a destination for the jump. + + The bytecode interpreter is a stack-based machine; most instructions +pop their operands off the stack, perform some operation, and push the +result back on the stack for the next instruction to consume. Each +element of the stack may contain either a integer or a floating point +value; these values are as many bits wide as the largest integer that +can be directly manipulated in the source language. Stack elements +carry no record of their type; bytecode could push a value as an +integer, then pop it as a floating point value. However, GDB will not +generate code which does this. In C, one might define the type of a +stack element as follows: + union agent_val { + LONGEST l; + DOUBLEST d; + }; +where 'LONGEST' and 'DOUBLEST' are 'typedef' names for the largest +integer and floating point types on the machine. + + By the time the bytecode interpreter reaches the end of the +expression, the value of the expression should be the only value left on +the stack. For tracing applications, 'trace' bytecodes in the +expression will have recorded the necessary data, and the value on the +stack may be discarded. For other applications, like conditional +breakpoints, the value may be useful. + + Separate from the stack, the interpreter has two registers: +'pc' + The address of the next bytecode to execute. + +'start' + The address of the start of the bytecode expression, necessary for + interpreting the 'goto' and 'if_goto' instructions. + +Neither of these registers is directly visible to the bytecode language +itself, but they are useful for defining the meanings of the bytecode +operations. + + There are no instructions to perform side effects on the running +program, or call the program's functions; we assume that these +expressions are only used for unobtrusive debugging, not for patching +the running code. + + Most bytecode instructions do not distinguish between the various +sizes of values, and operate on full-width values; the upper bits of the +values are simply ignored, since they do not usually make a difference +to the value computed. The exceptions to this rule are: + +memory reference instructions ('ref'N) + There are distinct instructions to fetch different word sizes from + memory. Once on the stack, however, the values are treated as + full-size integers. They may need to be sign-extended; the 'ext' + instruction exists for this purpose. + +the sign-extension instruction ('ext' N) + These clearly need to know which portion of their operand is to be + extended to occupy the full length of the word. + + If the interpreter is unable to evaluate an expression completely for +some reason (a memory location is inaccessible, or a divisor is zero, +for example), we say that interpretation "terminates with an error". +This means that the problem is reported back to the interpreter's caller +in some helpful way. In general, code using agent expressions should +assume that they may attempt to divide by zero, fetch arbitrary memory +locations, and misbehave in other ways. + + Even complicated C expressions compile to a few bytecode +instructions; for example, the expression 'x + y * z' would typically +produce code like the following, assuming that 'x' and 'y' live in +registers, and 'z' is a global variable holding a 32-bit 'int': + reg 1 + reg 2 + const32 address of z + ref32 + ext 32 + mul + add + end + + In detail, these mean: + +'reg 1' + Push the value of register 1 (presumably holding 'x') onto the + stack. + +'reg 2' + Push the value of register 2 (holding 'y'). + +'const32 address of z' + Push the address of 'z' onto the stack. + +'ref32' + Fetch a 32-bit word from the address at the top of the stack; + replace the address on the stack with the value. Thus, we replace + the address of 'z' with 'z''s value. + +'ext 32' + Sign-extend the value on the top of the stack from 32 bits to full + length. This is necessary because 'z' is a signed integer. + +'mul' + Pop the top two numbers on the stack, multiply them, and push their + product. Now the top of the stack contains the value of the + expression 'y * z'. + +'add' + Pop the top two numbers, add them, and push the sum. Now the top + of the stack contains the value of 'x + y * z'. + +'end' + Stop executing; the value left on the stack top is the value to be + recorded. + + +File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions + +F.2 Bytecode Descriptions +========================= + +Each bytecode description has the following form: + +'add' (0x02): A B => A+B + + Pop the top two stack items, A and B, as integers; push their sum, + as an integer. + + In this example, 'add' is the name of the bytecode, and '(0x02)' is +the one-byte value used to encode the bytecode, in hexadecimal. The +phrase "A B => A+B" shows the stack before and after the bytecode +executes. Beforehand, the stack must contain at least two values, A and +B; since the top of the stack is to the right, B is on the top of the +stack, and A is underneath it. After execution, the bytecode will have +popped A and B from the stack, and replaced them with a single value, +A+B. There may be other values on the stack below those shown, but the +bytecode affects only those shown. + + Here is another example: + +'const8' (0x22) N: => N + Push the 8-bit integer constant N on the stack, without sign + extension. + + In this example, the bytecode 'const8' takes an operand N directly +from the bytecode stream; the operand follows the 'const8' bytecode +itself. We write any such operands immediately after the name of the +bytecode, before the colon, and describe the exact encoding of the +operand in the bytecode stream in the body of the bytecode description. + + For the 'const8' bytecode, there are no stack items given before the +=>; this simply means that the bytecode consumes no values from the +stack. If a bytecode consumes no values, or produces no values, the +list on either side of the => may be empty. + + If a value is written as A, B, or N, then the bytecode treats it as +an integer. If a value is written is ADDR, then the bytecode treats it +as an address. + + We do not fully describe the floating point operations here; although +this design can be extended in a clean way to handle floating point +values, they are not of immediate interest to the customer, so we avoid +describing them, to save time. + +'float' (0x01): => + + Prefix for floating-point bytecodes. Not implemented yet. + +'add' (0x02): A B => A+B + Pop two integers from the stack, and push their sum, as an integer. + +'sub' (0x03): A B => A-B + Pop two integers from the stack, subtract the top value from the + next-to-top value, and push the difference. + +'mul' (0x04): A B => A*B + Pop two integers from the stack, multiply them, and push the + product on the stack. Note that, when one multiplies two N-bit + numbers yielding another N-bit number, it is irrelevant whether the + numbers are signed or not; the results are the same. + +'div_signed' (0x05): A B => A/B + Pop two signed integers from the stack; divide the next-to-top + value by the top value, and push the quotient. If the divisor is + zero, terminate with an error. + +'div_unsigned' (0x06): A B => A/B + Pop two unsigned integers from the stack; divide the next-to-top + value by the top value, and push the quotient. If the divisor is + zero, terminate with an error. + +'rem_signed' (0x07): A B => A MODULO B + Pop two signed integers from the stack; divide the next-to-top + value by the top value, and push the remainder. If the divisor is + zero, terminate with an error. + +'rem_unsigned' (0x08): A B => A MODULO B + Pop two unsigned integers from the stack; divide the next-to-top + value by the top value, and push the remainder. If the divisor is + zero, terminate with an error. + +'lsh' (0x09): A B => A< '(signed)'A>>B + Pop two integers from the stack; let A be the next-to-top value, + and B be the top value. Shift A right by B bits, inserting copies + of the top bit at the high end, and push the result. + +'rsh_unsigned' (0x0b): A B => A>>B + Pop two integers from the stack; let A be the next-to-top value, + and B be the top value. Shift A right by B bits, inserting zero + bits at the high end, and push the result. + +'log_not' (0x0e): A => !A + Pop an integer from the stack; if it is zero, push the value one; + otherwise, push the value zero. + +'bit_and' (0x0f): A B => A&B + Pop two integers from the stack, and push their bitwise 'and'. + +'bit_or' (0x10): A B => A|B + Pop two integers from the stack, and push their bitwise 'or'. + +'bit_xor' (0x11): A B => A^B + Pop two integers from the stack, and push their bitwise + exclusive-'or'. + +'bit_not' (0x12): A => ~A + Pop an integer from the stack, and push its bitwise complement. + +'equal' (0x13): A B => A=B + Pop two integers from the stack; if they are equal, push the value + one; otherwise, push the value zero. + +'less_signed' (0x14): A B => A A A, sign-extended from N bits + Pop an unsigned value from the stack; treating it as an N-bit + twos-complement value, extend it to full length. This means that + all bits to the left of bit N-1 (where the least significant bit is + bit 0) are set to the value of bit N-1. Note that N may be larger + than or equal to the width of the stack elements of the bytecode + engine; in this case, the bytecode should have no effect. + + The number of source bits to preserve, N, is encoded as a single + byte unsigned integer following the 'ext' bytecode. + +'zero_ext' (0x2a) N: A => A, zero-extended from N bits + Pop an unsigned value from the stack; zero all but the bottom N + bits. This means that all bits to the left of bit N-1 (where the + least significant bit is bit 0) are set to the value of bit N-1. + + The number of source bits to preserve, N, is encoded as a single + byte unsigned integer following the 'zero_ext' bytecode. + +'ref8' (0x17): ADDR => A +'ref16' (0x18): ADDR => A +'ref32' (0x19): ADDR => A +'ref64' (0x1a): ADDR => A + Pop an address ADDR from the stack. For bytecode 'ref'N, fetch an + N-bit value from ADDR, using the natural target endianness. Push + the fetched value as an unsigned integer. + + Note that ADDR may not be aligned in any particular way; the 'refN' + bytecodes should operate correctly for any address. + + If attempting to access memory at ADDR would cause a processor + exception of some sort, terminate with an error. + +'ref_float' (0x1b): ADDR => D +'ref_double' (0x1c): ADDR => D +'ref_long_double' (0x1d): ADDR => D +'l_to_d' (0x1e): A => D +'d_to_l' (0x1f): D => A + Not implemented yet. + +'dup' (0x28): A => A A + Push another copy of the stack's top element. + +'swap' (0x2b): A B => B A + Exchange the top two items on the stack. + +'pop' (0x29): A => + Discard the top value on the stack. + +'pick' (0x32) N: A ... B => A ... B A + Duplicate an item from the stack and push it on the top of the + stack. N, a single byte, indicates the stack item to copy. If N + is zero, this is the same as 'dup'; if N is one, it copies the item + under the top item, etc. If N exceeds the number of items on the + stack, terminate with an error. + +'rot' (0x33): A B C => C B A + Rotate the top three items on the stack. + +'if_goto' (0x20) OFFSET: A => + Pop an integer off the stack; if it is non-zero, branch to the + given offset in the bytecode string. Otherwise, continue to the + next instruction in the bytecode stream. In other words, if A is + non-zero, set the 'pc' register to 'start' + OFFSET. Thus, an + offset of zero denotes the beginning of the expression. + + The OFFSET is stored as a sixteen-bit unsigned value, stored + immediately following the 'if_goto' bytecode. It is always stored + most significant byte first, regardless of the target's normal + endianness. The offset is not guaranteed to fall at any particular + alignment within the bytecode stream; thus, on machines where + fetching a 16-bit on an unaligned address raises an exception, you + should fetch the offset one byte at a time. + +'goto' (0x21) OFFSET: => + Branch unconditionally to OFFSET; in other words, set the 'pc' + register to 'start' + OFFSET. + + The offset is stored in the same way as for the 'if_goto' bytecode. + +'const8' (0x22) N: => N +'const16' (0x23) N: => N +'const32' (0x24) N: => N +'const64' (0x25) N: => N + Push the integer constant N on the stack, without sign extension. + To produce a small negative value, push a small twos-complement + value, and then sign-extend it using the 'ext' bytecode. + + The constant N is stored in the appropriate number of bytes + following the 'const'B bytecode. The constant N is always stored + most significant byte first, regardless of the target's normal + endianness. The constant is not guaranteed to fall at any + particular alignment within the bytecode stream; thus, on machines + where fetching a 16-bit on an unaligned address raises an + exception, you should fetch N one byte at a time. + +'reg' (0x26) N: => A + Push the value of register number N, without sign extension. The + registers are numbered following GDB's conventions. + + The register number N is encoded as a 16-bit unsigned integer + immediately following the 'reg' bytecode. It is always stored most + significant byte first, regardless of the target's normal + endianness. The register number is not guaranteed to fall at any + particular alignment within the bytecode stream; thus, on machines + where fetching a 16-bit on an unaligned address raises an + exception, you should fetch the register number one byte at a time. + +'getv' (0x2c) N: => V + Push the value of trace state variable number N, without sign + extension. + + The variable number N is encoded as a 16-bit unsigned integer + immediately following the 'getv' bytecode. It is always stored + most significant byte first, regardless of the target's normal + endianness. The variable number is not guaranteed to fall at any + particular alignment within the bytecode stream; thus, on machines + where fetching a 16-bit on an unaligned address raises an + exception, you should fetch the register number one byte at a time. + +'setv' (0x2d) N: => V + Set trace state variable number N to the value found on the top of + the stack. The stack is unchanged, so that the value is readily + available if the assignment is part of a larger expression. The + handling of N is as described for 'getv'. + +'trace' (0x0c): ADDR SIZE => + Record the contents of the SIZE bytes at ADDR in a trace buffer, + for later retrieval by GDB. + +'trace_quick' (0x0d) SIZE: ADDR => ADDR + Record the contents of the SIZE bytes at ADDR in a trace buffer, + for later retrieval by GDB. SIZE is a single byte unsigned integer + following the 'trace' opcode. + + This bytecode is equivalent to the sequence 'dup const8 SIZE + trace', but we provide it anyway to save space in bytecode strings. + +'trace16' (0x30) SIZE: ADDR => ADDR + Identical to trace_quick, except that SIZE is a 16-bit big-endian + unsigned integer, not a single byte. This should probably have + been named 'trace_quick16', for consistency. + +'tracev' (0x2e) N: => A + Record the value of trace state variable number N in the trace + buffer. The handling of N is as described for 'getv'. + +'tracenz' (0x2f) ADDR SIZE => + Record the bytes at ADDR in a trace buffer, for later retrieval by + GDB. Stop at either the first zero byte, or when SIZE bytes have + been recorded, whichever occurs first. + +'printf' (0x34) NUMARGS STRING => + Do a formatted print, in the style of the C function 'printf'). + The value of NUMARGS is the number of arguments to expect on the + stack, while STRING is the format string, prefixed with a two-byte + length. The last byte of the string must be zero, and is included + in the length. The format string includes escaped sequences just + as it appears in C source, so for instance the format string + '"\t%d\n"' is six characters long, and the output will consist of a + tab character, a decimal number, and a newline. At the top of the + stack, above the values to be printed, this bytecode will pop a + "function" and "channel". If the function is nonzero, then the + target may treat it as a function and call it, passing the channel + as a first argument, as with the C function 'fprintf'. If the + function is zero, then the target may simply call a standard + formatted print function of its choice. In all, this bytecode pops + 2 + NUMARGS stack elements, and pushes nothing. + +'end' (0x27): => + Stop executing bytecode; the result should be the top element of + the stack. If the purpose of the expression was to compute an + lvalue or a range of memory, then the next-to-top of the stack is + the lvalue's address, and the top of the stack is the lvalue's + size, in bytes. + diff --git a/util/X86MAC64/share/info/gdb.info-6 b/util/X86MAC64/share/info/gdb.info-6 new file mode 100644 index 0000000000..8372a57b5f --- /dev/null +++ b/util/X86MAC64/share/info/gdb.info-6 @@ -0,0 +1,6740 @@ +This is gdb.info, produced by makeinfo version 5.1 from gdb.texinfo. + +Copyright (C) 1988-2014 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + +File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions + +F.3 Using Agent Expressions +=========================== + +Agent expressions can be used in several different ways by GDB, and the +debugger can generate different bytecode sequences as appropriate. + + One possibility is to do expression evaluation on the target rather +than the host, such as for the conditional of a conditional tracepoint. +In such a case, GDB compiles the source expression into a bytecode +sequence that simply gets values from registers or memory, does +arithmetic, and returns a result. + + Another way to use agent expressions is for tracepoint data +collection. GDB generates a different bytecode sequence for collection; +in addition to bytecodes that do the calculation, GDB adds 'trace' +bytecodes to save the pieces of memory that were used. + + * The user selects trace points in the program's code at which GDB + should collect data. + + * The user specifies expressions to evaluate at each trace point. + These expressions may denote objects in memory, in which case those + objects' contents are recorded as the program runs, or computed + values, in which case the values themselves are recorded. + + * GDB transmits the tracepoints and their associated expressions to + the GDB agent, running on the debugging target. + + * The agent arranges to be notified when a trace point is hit. + + * When execution on the target reaches a trace point, the agent + evaluates the expressions associated with that trace point, and + records the resulting values and memory ranges. + + * Later, when the user selects a given trace event and inspects the + objects and expression values recorded, GDB talks to the agent to + retrieve recorded data as necessary to meet the user's requests. + If the user asks to see an object whose contents have not been + recorded, GDB reports an error. + + +File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions + +F.4 Varying Target Capabilities +=============================== + +Some targets don't support floating-point, and some would rather not +have to deal with 'long long' operations. Also, different targets will +have different stack sizes, and different bytecode buffer lengths. + + Thus, GDB needs a way to ask the target about itself. We haven't +worked out the details yet, but in general, GDB should be able to send +the target a packet asking it to describe itself. The reply should be a +packet whose length is explicit, so we can add new information to the +packet in future revisions of the agent, without confusing old versions +of GDB, and it should contain a version number. It should contain at +least the following information: + + * whether floating point is supported + + * whether 'long long' is supported + + * maximum acceptable size of bytecode stack + + * maximum acceptable length of bytecode expressions + + * which registers are actually available for collection + + * whether the target supports disabled tracepoints + + +File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions + +F.5 Rationale +============= + +Some of the design decisions apparent above are arguable. + +What about stack overflow/underflow? + GDB should be able to query the target to discover its stack size. + Given that information, GDB can determine at translation time + whether a given expression will overflow the stack. But this spec + isn't about what kinds of error-checking GDB ought to do. + +Why are you doing everything in LONGEST? + + Speed isn't important, but agent code size is; using LONGEST brings + in a bunch of support code to do things like division, etc. So + this is a serious concern. + + First, note that you don't need different bytecodes for different + operand sizes. You can generate code without _knowing_ how big the + stack elements actually are on the target. If the target only + supports 32-bit ints, and you don't send any 64-bit bytecodes, + everything just works. The observation here is that the MIPS and + the Alpha have only fixed-size registers, and you can still get C's + semantics even though most instructions only operate on full-sized + words. You just need to make sure everything is properly + sign-extended at the right times. So there is no need for 32- and + 64-bit variants of the bytecodes. Just implement everything using + the largest size you support. + + GDB should certainly check to see what sizes the target supports, + so the user can get an error earlier, rather than later. But this + information is not necessary for correctness. + +Why don't you have '>' or '<=' operators? + I want to keep the interpreter small, and we don't need them. We + can combine the 'less_' opcodes with 'log_not', and swap the order + of the operands, yielding all four asymmetrical comparison + operators. For example, '(x <= y)' is '! (x > y)', which is '! (y + < x)'. + +Why do you have 'log_not'? +Why do you have 'ext'? +Why do you have 'zero_ext'? + These are all easily synthesized from other instructions, but I + expect them to be used frequently, and they're simple, so I include + them to keep bytecode strings short. + + 'log_not' is equivalent to 'const8 0 equal'; it's used in half the + relational operators. + + 'ext N' is equivalent to 'const8 S-N lsh const8 S-N rsh_signed', + where S is the size of the stack elements; it follows 'refM' and + REG bytecodes when the value should be signed. See the next + bulleted item. + + 'zero_ext N' is equivalent to 'constM MASK log_and'; it's used + whenever we push the value of a register, because we can't assume + the upper bits of the register aren't garbage. + +Why not have sign-extending variants of the 'ref' operators? + Because that would double the number of 'ref' operators, and we + need the 'ext' bytecode anyway for accessing bitfields. + +Why not have constant-address variants of the 'ref' operators? + Because that would double the number of 'ref' operators again, and + 'const32 ADDRESS ref32' is only one byte longer. + +Why do the 'refN' operators have to support unaligned fetches? + GDB will generate bytecode that fetches multi-byte values at + unaligned addresses whenever the executable's debugging information + tells it to. Furthermore, GDB does not know the value the pointer + will have when GDB generates the bytecode, so it cannot determine + whether a particular fetch will be aligned or not. + + In particular, structure bitfields may be several bytes long, but + follow no alignment rules; members of packed structures are not + necessarily aligned either. + + In general, there are many cases where unaligned references occur + in correct C code, either at the programmer's explicit request, or + at the compiler's discretion. Thus, it is simpler to make the GDB + agent bytecodes work correctly in all circumstances than to make + GDB guess in each case whether the compiler did the usual thing. + +Why are there no side-effecting operators? + Because our current client doesn't want them? That's a cheap + answer. I think the real answer is that I'm afraid of implementing + function calls. We should re-visit this issue after the present + contract is delivered. + +Why aren't the 'goto' ops PC-relative? + The interpreter has the base address around anyway for PC bounds + checking, and it seemed simpler. + +Why is there only one offset size for the 'goto' ops? + Offsets are currently sixteen bits. I'm not happy with this + situation either: + + Suppose we have multiple branch ops with different offset sizes. + As I generate code left-to-right, all my jumps are forward jumps + (there are no loops in expressions), so I never know the target + when I emit the jump opcode. Thus, I have to either always assume + the largest offset size, or do jump relaxation on the code after I + generate it, which seems like a big waste of time. + + I can imagine a reasonable expression being longer than 256 bytes. + I can't imagine one being longer than 64k. Thus, we need 16-bit + offsets. This kind of reasoning is so bogus, but relaxation is + pathetic. + + The other approach would be to generate code right-to-left. Then + I'd always know my offset size. That might be fun. + +Where is the function call bytecode? + + When we add side-effects, we should add this. + +Why does the 'reg' bytecode take a 16-bit register number? + + Intel's IA-64 architecture has 128 general-purpose registers, and + 128 floating-point registers, and I'm sure it has some random + control registers. + +Why do we need 'trace' and 'trace_quick'? + Because GDB needs to record all the memory contents and registers + an expression touches. If the user wants to evaluate an expression + 'x->y->z', the agent must record the values of 'x' and 'x->y' as + well as the value of 'x->y->z'. + +Don't the 'trace' bytecodes make the interpreter less general? + They do mean that the interpreter contains special-purpose code, + but that doesn't mean the interpreter can only be used for that + purpose. If an expression doesn't use the 'trace' bytecodes, they + don't get in its way. + +Why doesn't 'trace_quick' consume its arguments the way everything else does? + In general, you do want your operators to consume their arguments; + it's consistent, and generally reduces the amount of stack + rearrangement necessary. However, 'trace_quick' is a kludge to + save space; it only exists so we needn't write 'dup const8 SIZE + trace' before every memory reference. Therefore, it's okay for it + not to consume its arguments; it's meant for a specific context in + which we know exactly what it should do with the stack. If we're + going to have a kludge, it should be an effective kludge. + +Why does 'trace16' exist? + That opcode was added by the customer that contracted Cygnus for + the data tracing work. I personally think it is unnecessary; + objects that large will be quite rare, so it is okay to use 'dup + const16 SIZE trace' in those cases. + + Whatever we decide to do with 'trace16', we should at least leave + opcode 0x30 reserved, to remain compatible with the customer who + added it. + + +File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top + +Appendix G Target Descriptions +****************************** + +One of the challenges of using GDB to debug embedded systems is that +there are so many minor variants of each processor architecture in use. +It is common practice for vendors to start with a standard processor +core -- ARM, PowerPC, or MIPS, for example -- and then make changes to +adapt it to a particular market niche. Some architectures have hundreds +of variants, available from dozens of vendors. This leads to a number +of problems: + + * With so many different customized processors, it is difficult for + the GDB maintainers to keep up with the changes. + * Since individual variants may have short lifetimes or limited + audiences, it may not be worthwhile to carry information about + every variant in the GDB source tree. + * When GDB does support the architecture of the embedded system at + hand, the task of finding the correct architecture name to give the + 'set architecture' command can be error-prone. + + To address these problems, the GDB remote protocol allows a target +system to not only identify itself to GDB, but to actually describe its +own features. This lets GDB support processor variants it has never +seen before -- to the extent that the descriptions are accurate, and +that GDB understands them. + + GDB must be linked with the Expat library to support XML target +descriptions. *Note Expat::. + +* Menu: + +* Retrieving Descriptions:: How descriptions are fetched from a target. +* Target Description Format:: The contents of a target description. +* Predefined Target Types:: Standard types available for target + descriptions. +* Standard Target Features:: Features GDB knows about. + + +File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions + +G.1 Retrieving Descriptions +=========================== + +Target descriptions can be read from the target automatically, or +specified by the user manually. The default behavior is to read the +description from the target. GDB retrieves it via the remote protocol +using 'qXfer' requests (*note qXfer: General Query Packets.). The ANNEX +in the 'qXfer' packet will be 'target.xml'. The contents of the +'target.xml' annex are an XML document, of the form described in *note +Target Description Format::. + + Alternatively, you can specify a file to read for the target +description. If a file is set, the target will not be queried. The +commands to specify a file are: + +'set tdesc filename PATH' + Read the target description from PATH. + +'unset tdesc filename' + Do not read the XML target description from a file. GDB will use + the description supplied by the current target. + +'show tdesc filename' + Show the filename to read for a target description, if any. + + +File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions + +G.2 Target Description Format +============================= + +A target description annex is an XML (http://www.w3.org/XML/) document +which complies with the Document Type Definition provided in the GDB +sources in 'gdb/features/gdb-target.dtd'. This means you can use +generally available tools like 'xmllint' to check that your feature +descriptions are well-formed and valid. However, to help people +unfamiliar with XML write descriptions for their targets, we also +describe the grammar here. + + Target descriptions can identify the architecture of the remote +target and (for some architectures) provide information about custom +register sets. They can also identify the OS ABI of the remote target. +GDB can use this information to autoconfigure for your target, or to +warn you if you connect to an unsupported target. + + Here is a simple target description: + + + i386:x86-64 + + +This minimal description only says that the target uses the x86-64 +architecture. + + A target description has the following overall form, with [ ] marking +optional elements and ... marking repeatable elements. The elements are +explained further below. + + + + + [ARCHITECTURE] + [OSABI] + [COMPATIBLE] + [FEATURE...] + + +The description is generally insensitive to whitespace and line breaks, +under the usual common-sense rules. The XML version declaration and +document type declaration can generally be omitted (GDB does not require +them), but specifying them may be useful for XML validation tools. The +'version' attribute for '' may also be omitted, but we recommend +including it; if future versions of GDB use an incompatible revision of +'gdb-target.dtd', they will detect and report the version mismatch. + +G.2.1 Inclusion +--------------- + +It can sometimes be valuable to split a target description up into +several different annexes, either for organizational purposes, or to +share files between different possible target descriptions. You can +divide a description into multiple files by replacing any element of the +target description with an inclusion directive of the form: + + + +When GDB encounters an element of this form, it will retrieve the named +XML DOCUMENT, and replace the inclusion directive with the contents of +that document. If the current description was read using 'qXfer', then +so will be the included document; DOCUMENT will be interpreted as the +name of an annex. If the current description was read from a file, GDB +will look for DOCUMENT as a file in the same directory where it found +the original description. + +G.2.2 Architecture +------------------ + +An '' element has this form: + + ARCH + + ARCH is one of the architectures from the set accepted by 'set +architecture' (*note Specifying a Debugging Target: Targets.). + +G.2.3 OS ABI +------------ + +This optional field was introduced in GDB version 7.0. Previous +versions of GDB ignore it. + + An '' element has this form: + + ABI-NAME + + ABI-NAME is an OS ABI name from the same selection accepted by 'set osabi' +(*note Configuring the Current ABI: ABI.). + +G.2.4 Compatible Architecture +----------------------------- + +This optional field was introduced in GDB version 7.0. Previous +versions of GDB ignore it. + + A '' element has this form: + + ARCH + + ARCH is one of the architectures from the set accepted by 'set +architecture' (*note Specifying a Debugging Target: Targets.). + + A '' element is used to specify that the target is able +to run binaries in some other than the main target architecture given by +the '' element. For example, on the Cell Broadband +Engine, the main architecture is 'powerpc:common' or 'powerpc:common64', +but the system is able to run binaries in the 'spu' architecture as +well. The way to describe this capability with '' is as +follows: + + powerpc:common + spu + +G.2.5 Features +-------------- + +Each '' describes some logical portion of the target system. +Features are currently used to describe available CPU registers and the +types of their contents. A '' element has this form: + + + [TYPE...] + REG... + + +Each feature's name should be unique within the description. The name +of a feature does not matter unless GDB has some special knowledge of +the contents of that feature; if it does, the feature should have its +standard name. *Note Standard Target Features::. + +G.2.6 Types +----------- + +Any register's value is a collection of bits which GDB must interpret. +The default interpretation is a two's complement integer, but other +types can be requested by name in the register description. Some +predefined types are provided by GDB (*note Predefined Target Types::), +and the description can define additional composite types. + + Each type element must have an 'id' attribute, which gives a unique +(within the containing '') name to the type. Types must be +defined before they are used. + + Some targets offer vector registers, which can be treated as arrays +of scalar elements. These types are written as '' elements, +specifying the array element type, TYPE, and the number of elements, +COUNT: + + + + If a register's value is usefully viewed in multiple ways, define it +with a union type containing the useful representations. The '' +element contains one or more '' elements, each of which has a +NAME and a TYPE: + + + + ... + + + If a register's value is composed from several separate values, +define it with a structure type. There are two forms of the '' +element; a '' element must either contain only bitfields or +contain no bitfields. If the structure contains only bitfields, its +total size in bytes must be specified, each bitfield must have an +explicit start and end, and bitfields are automatically assigned an +integer type. The field's START should be less than or equal to its +END, and zero represents the least significant bit. + + + + ... + + + If the structure contains no bitfields, then each field has an +explicit type, and no implicit padding is added. + + + + ... + + + If a register's value is a series of single-bit flags, define it with +a flags type. The '' element has an explicit SIZE and contains +one or more '' elements. Each field has a NAME, a START, and an +END. Only single-bit flags are supported. + + + + ... + + +G.2.7 Registers +--------------- + +Each register is represented as an element with this form: + + + +The components are as follows: + +NAME + The register's name; it must be unique within the target + description. + +BITSIZE + The register's size, in bits. + +REGNUM + The register's number. If omitted, a register's number is one + greater than that of the previous register (either in the current + feature or in a preceding feature); the first register in the + target description defaults to zero. This register number is used + to read or write the register; e.g. it is used in the remote 'p' + and 'P' packets, and registers appear in the 'g' and 'G' packets in + order of increasing register number. + +SAVE-RESTORE + Whether the register should be preserved across inferior function + calls; this must be either 'yes' or 'no'. The default is 'yes', + which is appropriate for most registers except for some system + control registers; this is not related to the target's ABI. + +TYPE + The type of the register. TYPE may be a predefined type, a type + defined in the current feature, or one of the special types 'int' + and 'float'. 'int' is an integer type of the correct size for + BITSIZE, and 'float' is a floating point type (in the + architecture's normal floating point format) of the correct size + for BITSIZE. The default is 'int'. + +GROUP + The register group to which this register belongs. GROUP must be + either 'general', 'float', or 'vector'. If no GROUP is specified, + GDB will not display the register in 'info registers'. + + +File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions + +G.3 Predefined Target Types +=========================== + +Type definitions in the self-description can build up composite types +from basic building blocks, but can not define fundamental types. +Instead, standard identifiers are provided by GDB for the fundamental +types. The currently supported types are: + +'int8' +'int16' +'int32' +'int64' +'int128' + Signed integer types holding the specified number of bits. + +'uint8' +'uint16' +'uint32' +'uint64' +'uint128' + Unsigned integer types holding the specified number of bits. + +'code_ptr' +'data_ptr' + Pointers to unspecified code and data. The program counter and any + dedicated return address register may be marked as code pointers; + printing a code pointer converts it into a symbolic address. The + stack pointer and any dedicated address registers may be marked as + data pointers. + +'ieee_single' + Single precision IEEE floating point. + +'ieee_double' + Double precision IEEE floating point. + +'arm_fpa_ext' + The 12-byte extended precision format used by ARM FPA registers. + +'i387_ext' + The 10-byte extended precision format used by x87 registers. + +'i386_eflags' + 32bit EFLAGS register used by x86. + +'i386_mxcsr' + 32bit MXCSR register used by x86. + + +File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions + +G.4 Standard Target Features +============================ + +A target description must contain either no registers or all the +target's registers. If the description contains no registers, then GDB +will assume a default register layout, selected based on the +architecture. If the description contains any registers, the default +layout will not be used; the standard registers must be described in the +target description, in such a way that GDB can recognize them. + + This is accomplished by giving specific names to feature elements +which contain standard registers. GDB will look for features with those +names and verify that they contain the expected registers; if any known +feature is missing required registers, or if any required feature is +missing, GDB will reject the target description. You can add additional +registers to any of the standard features -- GDB will display them just +as if they were added to an unrecognized feature. + + This section lists the known features and their expected contents. +Sample XML documents for these features are included in the GDB source +tree, in the directory 'gdb/features'. + + Names recognized by GDB should include the name of the company or +organization which selected the name, and the overall architecture to +which the feature applies; so e.g. the feature containing ARM core +registers is named 'org.gnu.gdb.arm.core'. + + The names of registers are not case sensitive for the purpose of +recognizing standard features, but GDB will only display registers using +the capitalization used in the description. + +* Menu: + +* AArch64 Features:: +* ARM Features:: +* i386 Features:: +* MIPS Features:: +* M68K Features:: +* Nios II Features:: +* PowerPC Features:: +* S/390 and System z Features:: +* TIC6x Features:: + + +File: gdb.info, Node: AArch64 Features, Next: ARM Features, Up: Standard Target Features + +G.4.1 AArch64 Features +---------------------- + +The 'org.gnu.gdb.aarch64.core' feature is required for AArch64 targets. +It should contain registers 'x0' through 'x30', 'sp', 'pc', and 'cpsr'. + + The 'org.gnu.gdb.aarch64.fpu' feature is optional. If present, it +should contain registers 'v0' through 'v31', 'fpsr', and 'fpcr'. + + +File: gdb.info, Node: ARM Features, Next: i386 Features, Prev: AArch64 Features, Up: Standard Target Features + +G.4.2 ARM Features +------------------ + +The 'org.gnu.gdb.arm.core' feature is required for non-M-profile ARM +targets. It should contain registers 'r0' through 'r13', 'sp', 'lr', +'pc', and 'cpsr'. + + For M-profile targets (e.g. Cortex-M3), the 'org.gnu.gdb.arm.core' +feature is replaced by 'org.gnu.gdb.arm.m-profile'. It should contain +registers 'r0' through 'r13', 'sp', 'lr', 'pc', and 'xpsr'. + + The 'org.gnu.gdb.arm.fpa' feature is optional. If present, it should +contain registers 'f0' through 'f7' and 'fps'. + + The 'org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it +should contain at least registers 'wR0' through 'wR15' and 'wCGR0' +through 'wCGR3'. The 'wCID', 'wCon', 'wCSSF', and 'wCASF' registers are +optional. + + The 'org.gnu.gdb.arm.vfp' feature is optional. If present, it should +contain at least registers 'd0' through 'd15'. If they are present, +'d16' through 'd31' should also be included. GDB will synthesize the +single-precision registers from halves of the double-precision +registers. + + The 'org.gnu.gdb.arm.neon' feature is optional. It does not need to +contain registers; it instructs GDB to display the VFP double-precision +registers as vectors and to synthesize the quad-precision registers from +pairs of double-precision registers. If this feature is present, +'org.gnu.gdb.arm.vfp' must also be present and include 32 +double-precision registers. + + +File: gdb.info, Node: i386 Features, Next: MIPS Features, Prev: ARM Features, Up: Standard Target Features + +G.4.3 i386 Features +------------------- + +The 'org.gnu.gdb.i386.core' feature is required for i386/amd64 targets. +It should describe the following registers: + + - 'eax' through 'edi' plus 'eip' for i386 + - 'rax' through 'r15' plus 'rip' for amd64 + - 'eflags', 'cs', 'ss', 'ds', 'es', 'fs', 'gs' + - 'st0' through 'st7' + - 'fctrl', 'fstat', 'ftag', 'fiseg', 'fioff', 'foseg', 'fooff' and + 'fop' + + The register sets may be different, depending on the target. + + The 'org.gnu.gdb.i386.sse' feature is optional. It should describe +registers: + + - 'xmm0' through 'xmm7' for i386 + - 'xmm0' through 'xmm15' for amd64 + - 'mxcsr' + + The 'org.gnu.gdb.i386.avx' feature is optional and requires the +'org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits +of YMM registers: + + - 'ymm0h' through 'ymm7h' for i386 + - 'ymm0h' through 'ymm15h' for amd64 + + The 'org.gnu.gdb.i386.mpx' is an optional feature representing +Intel(R) Memory Protection Extension (MPX). It should describe the +following registers: + + - 'bnd0raw' through 'bnd3raw' for i386 and amd64. + - 'bndcfgu' and 'bndstatus' for i386 and amd64. + + The 'org.gnu.gdb.i386.linux' feature is optional. It should describe +a single register, 'orig_eax'. + + +File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: i386 Features, Up: Standard Target Features + +G.4.4 MIPS Features +------------------- + +The 'org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It +should contain registers 'r0' through 'r31', 'lo', 'hi', and 'pc'. They +may be 32-bit or 64-bit depending on the target. + + The 'org.gnu.gdb.mips.cp0' feature is also required. It should +contain at least the 'status', 'badvaddr', and 'cause' registers. They +may be 32-bit or 64-bit depending on the target. + + The 'org.gnu.gdb.mips.fpu' feature is currently required, though it +may be optional in a future version of GDB. It should contain registers +'f0' through 'f31', 'fcsr', and 'fir'. They may be 32-bit or 64-bit +depending on the target. + + The 'org.gnu.gdb.mips.dsp' feature is optional. It should contain +registers 'hi1' through 'hi3', 'lo1' through 'lo3', and 'dspctl'. The +'dspctl' register should be 32-bit and the rest may be 32-bit or 64-bit +depending on the target. + + The 'org.gnu.gdb.mips.linux' feature is optional. It should contain +a single register, 'restart', which is used by the Linux kernel to +control restartable syscalls. + + +File: gdb.info, Node: M68K Features, Next: Nios II Features, Prev: MIPS Features, Up: Standard Target Features + +G.4.5 M68K Features +------------------- + +''org.gnu.gdb.m68k.core'' +''org.gnu.gdb.coldfire.core'' +''org.gnu.gdb.fido.core'' + One of those features must be always present. The feature that is + present determines which flavor of m68k is used. The feature that + is present should contain registers 'd0' through 'd7', 'a0' through + 'a5', 'fp', 'sp', 'ps' and 'pc'. + +''org.gnu.gdb.coldfire.fp'' + This feature is optional. If present, it should contain registers + 'fp0' through 'fp7', 'fpcontrol', 'fpstatus' and 'fpiaddr'. + + +File: gdb.info, Node: Nios II Features, Next: PowerPC Features, Prev: M68K Features, Up: Standard Target Features + +G.4.6 Nios II Features +---------------------- + +The 'org.gnu.gdb.nios2.cpu' feature is required for Nios II targets. It +should contain the 32 core registers ('zero', 'at', 'r2' through 'r23', +'et' through 'ra'), 'pc', and the 16 control registers ('status' through +'mpuacc'). + + +File: gdb.info, Node: PowerPC Features, Next: S/390 and System z Features, Prev: Nios II Features, Up: Standard Target Features + +G.4.7 PowerPC Features +---------------------- + +The 'org.gnu.gdb.power.core' feature is required for PowerPC targets. +It should contain registers 'r0' through 'r31', 'pc', 'msr', 'cr', 'lr', +'ctr', and 'xer'. They may be 32-bit or 64-bit depending on the target. + + The 'org.gnu.gdb.power.fpu' feature is optional. It should contain +registers 'f0' through 'f31' and 'fpscr'. + + The 'org.gnu.gdb.power.altivec' feature is optional. It should +contain registers 'vr0' through 'vr31', 'vscr', and 'vrsave'. + + The 'org.gnu.gdb.power.vsx' feature is optional. It should contain +registers 'vs0h' through 'vs31h'. GDB will combine these registers with +the floating point registers ('f0' through 'f31') and the altivec +registers ('vr0' through 'vr31') to present the 128-bit wide registers +'vs0' through 'vs63', the set of vector registers for POWER7. + + The 'org.gnu.gdb.power.spe' feature is optional. It should contain +registers 'ev0h' through 'ev31h', 'acc', and 'spefscr'. SPE targets +should provide 32-bit registers in 'org.gnu.gdb.power.core' and provide +the upper halves in 'ev0h' through 'ev31h'. GDB will combine these to +present registers 'ev0' through 'ev31' to the user. + + +File: gdb.info, Node: S/390 and System z Features, Next: TIC6x Features, Prev: PowerPC Features, Up: Standard Target Features + +G.4.8 S/390 and System z Features +--------------------------------- + +The 'org.gnu.gdb.s390.core' feature is required for S/390 and System z +targets. It should contain the PSW and the 16 general registers. In +particular, System z targets should provide the 64-bit registers 'pswm', +'pswa', and 'r0' through 'r15'. S/390 targets should provide the 32-bit +versions of these registers. A System z target that runs in 31-bit +addressing mode should provide 32-bit versions of 'pswm' and 'pswa', as +well as the general register's upper halves 'r0h' through 'r15h', and +their lower halves 'r0l' through 'r15l'. + + The 'org.gnu.gdb.s390.fpr' feature is required. It should contain +the 64-bit registers 'f0' through 'f15', and 'fpc'. + + The 'org.gnu.gdb.s390.acr' feature is required. It should contain +the 32-bit registers 'acr0' through 'acr15'. + + The 'org.gnu.gdb.s390.linux' feature is optional. It should contain +the register 'orig_r2', which is 64-bit wide on System z targets and +32-bit otherwise. In addition, the feature may contain the 'last_break' +register, whose width depends on the addressing mode, as well as the +'system_call' register, which is always 32-bit wide. + + The 'org.gnu.gdb.s390.tdb' feature is optional. It should contain +the 64-bit registers 'tdb0', 'tac', 'tct', 'atia', and 'tr0' through +'tr15'. + + +File: gdb.info, Node: TIC6x Features, Prev: S/390 and System z Features, Up: Standard Target Features + +G.4.9 TMS320C6x Features +------------------------ + +The 'org.gnu.gdb.tic6x.core' feature is required for TMS320C6x targets. +It should contain registers 'A0' through 'A15', registers 'B0' through +'B15', 'CSR' and 'PC'. + + The 'org.gnu.gdb.tic6x.gp' feature is optional. It should contain +registers 'A16' through 'A31' and 'B16' through 'B31'. + + The 'org.gnu.gdb.tic6x.c6xp' feature is optional. It should contain +registers 'TSR', 'ILC' and 'RILC'. + + +File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top + +Appendix H Operating System Information +*************************************** + +* Menu: + +* Process list:: + +Users of GDB often wish to obtain information about the state of the +operating system running on the target--for example the list of +processes, or the list of open files. This section describes the +mechanism that makes it possible. This mechanism is similar to the +target features mechanism (*note Target Descriptions::), but focuses on +a different aspect of target. + + Operating system information is retrived from the target via the +remote protocol, using 'qXfer' requests (*note qXfer osdata read::). +The object name in the request should be 'osdata', and the ANNEX +identifies the data to be fetched. + + +File: gdb.info, Node: Process list, Up: Operating System Information + +H.1 Process list +================ + +When requesting the process list, the ANNEX field in the 'qXfer' request +should be 'processes'. The returned data is an XML document. The +formal syntax of this document is defined in 'gdb/features/osdata.dtd'. + + An example document is: + + + + + + 1 + root + /sbin/init + 1,2,3 + + + + Each item should include a column whose name is 'pid'. The value of +that column should identify the process on the target. The 'user' and +'command' columns are optional, and will be displayed by GDB. The +'cores' column, if present, should contain a comma-separated list of +cores that this process is running on. Target may provide additional +columns, which GDB currently ignores. + + +File: gdb.info, Node: Trace File Format, Next: Index Section Format, Prev: Operating System Information, Up: Top + +Appendix I Trace File Format +**************************** + +The trace file comes in three parts: a header, a textual description +section, and a trace frame section with binary data. + + The header has the form '\x7fTRACE0\n'. The first byte is '0x7f' so +as to indicate that the file contains binary data, while the '0' is a +version number that may have different values in the future. + + The description section consists of multiple lines of ASCII text +separated by newline characters ('0xa'). The lines may include a +variety of optional descriptive or context-setting information, such as +tracepoint definitions or register set size. GDB will ignore any line +that it does not recognize. An empty line marks the end of this +section. + + The trace frame section consists of a number of consecutive frames. +Each frame begins with a two-byte tracepoint number, followed by a +four-byte size giving the amount of data in the frame. The data in the +frame consists of a number of blocks, each introduced by a character +indicating its type (at least register, memory, and trace state +variable). The data in this section is raw binary, not a hexadecimal or +other encoding; its endianness matches the target's endianness. + +'R BYTES' + Register block. The number and ordering of bytes matches that of a + 'g' packet in the remote protocol. Note that these are the actual + bytes, in target order and GDB register order, not a hexadecimal + encoding. + +'M ADDRESS LENGTH BYTES...' + Memory block. This is a contiguous block of memory, at the 8-byte + address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH + bytes. + +'V NUMBER VALUE' + Trace state variable block. This records the 8-byte signed value + VALUE of trace state variable numbered NUMBER. + + Future enhancements of the trace file format may include additional +types of blocks. + + +File: gdb.info, Node: Index Section Format, Next: Man Pages, Prev: Trace File Format, Up: Top + +Appendix J '.gdb_index' section format +************************************** + +This section documents the index section that is created by 'save +gdb-index' (*note Index Files::). The index section is DWARF-specific; +some knowledge of DWARF is assumed in this description. + + The mapped index file format is designed to be directly 'mmap'able on +any architecture. In most cases, a datum is represented using a +little-endian 32-bit integer value, called an 'offset_type'. Big endian +machines must byte-swap the values before using them. Exceptions to +this rule are noted. The data is laid out such that alignment is always +respected. + + A mapped index consists of several areas, laid out in order. + + 1. The file header. This is a sequence of values, of 'offset_type' + unless otherwise noted: + + 1. The version number, currently 8. Versions 1, 2 and 3 are + obsolete. Version 4 uses a different hashing function from + versions 5 and 6. Version 6 includes symbols for inlined + functions, whereas versions 4 and 5 do not. Version 7 adds + attributes to the CU indices in the symbol table. Version 8 + specifies that symbols from DWARF type units + ('DW_TAG_type_unit') refer to the type unit's symbol table and + not the compilation unit ('DW_TAG_comp_unit') using the type. + + GDB will only read version 4, 5, or 6 indices by specifying + 'set use-deprecated-index-sections on'. GDB has a workaround + for potentially broken version 7 indices so it is currently + not flagged as deprecated. + + 2. The offset, from the start of the file, of the CU list. + + 3. The offset, from the start of the file, of the types CU list. + Note that this area can be empty, in which case this offset + will be equal to the next offset. + + 4. The offset, from the start of the file, of the address area. + + 5. The offset, from the start of the file, of the symbol table. + + 6. The offset, from the start of the file, of the constant pool. + + 2. The CU list. This is a sequence of pairs of 64-bit little-endian + values, sorted by the CU offset. The first element in each pair is + the offset of a CU in the '.debug_info' section. The second + element in each pair is the length of that CU. References to a CU + elsewhere in the map are done using a CU index, which is just the + 0-based index into this table. Note that if there are type CUs, + then conceptually CUs and type CUs form a single list for the + purposes of CU indices. + + 3. The types CU list. This is a sequence of triplets of 64-bit + little-endian values. In a triplet, the first value is the CU + offset, the second value is the type offset in the CU, and the + third value is the type signature. The types CU list is not + sorted. + + 4. The address area. The address area consists of a sequence of + address entries. Each address entry has three elements: + + 1. The low address. This is a 64-bit little-endian value. + + 2. The high address. This is a 64-bit little-endian value. Like + 'DW_AT_high_pc', the value is one byte beyond the end. + + 3. The CU index. This is an 'offset_type' value. + + 5. The symbol table. This is an open-addressed hash table. The size + of the hash table is always a power of 2. + + Each slot in the hash table consists of a pair of 'offset_type' + values. The first value is the offset of the symbol's name in the + constant pool. The second value is the offset of the CU vector in + the constant pool. + + If both values are 0, then this slot in the hash table is empty. + This is ok because while 0 is a valid constant pool index, it + cannot be a valid index for both a string and a CU vector. + + The hash value for a table entry is computed by applying an + iterative hash function to the symbol's name. Starting with an + initial value of 'r = 0', each (unsigned) character 'c' in the + string is incorporated into the hash using the formula depending on + the index version: + + Version 4 + The formula is 'r = r * 67 + c - 113'. + + Versions 5 to 7 + The formula is 'r = r * 67 + tolower (c) - 113'. + + The terminating '\0' is not incorporated into the hash. + + The step size used in the hash table is computed via '((hash * 17) + & (size - 1)) | 1', where 'hash' is the hash value, and 'size' is + the size of the hash table. The step size is used to find the next + candidate slot when handling a hash collision. + + The names of C++ symbols in the hash table are canonicalized. We + don't currently have a simple description of the canonicalization + algorithm; if you intend to create new index sections, you must + read the code. + + 6. The constant pool. This is simply a bunch of bytes. It is + organized so that alignment is correct: CU vectors are stored + first, followed by strings. + + A CU vector in the constant pool is a sequence of 'offset_type' + values. The first value is the number of CU indices in the vector. + Each subsequent value is the index and symbol attributes of a CU in + the CU list. This element in the hash table is used to indicate + which CUs define the symbol and how the symbol is used. See below + for the format of each CU index+attributes entry. + + A string in the constant pool is zero-terminated. + + Attributes were added to CU index values in '.gdb_index' version 7. +If a symbol has multiple uses within a CU then there is one CU +index+attributes value for each use. + + The format of each CU index+attributes entry is as follows (bit 0 = +LSB): + +Bits 0-23 + This is the index of the CU in the CU list. +Bits 24-27 + These bits are reserved for future purposes and must be zero. +Bits 28-30 + The kind of the symbol in the CU. + + 0 + This value is reserved and should not be used. By reserving + zero the full 'offset_type' value is backwards compatible with + previous versions of the index. + 1 + The symbol is a type. + 2 + The symbol is a variable or an enum value. + 3 + The symbol is a function. + 4 + Any other kind of symbol. + 5,6,7 + These values are reserved. + +Bit 31 + This bit is zero if the value is global and one if it is static. + + The determination of whether a symbol is global or static is + complicated. The authorative reference is the file 'dwarf2read.c' + in GDB sources. + + This pseudo-code describes the computation of a symbol's kind and +global/static attributes in the index. + + is_external = get_attribute (die, DW_AT_external); + language = get_attribute (cu_die, DW_AT_language); + switch (die->tag) + { + case DW_TAG_typedef: + case DW_TAG_base_type: + case DW_TAG_subrange_type: + kind = TYPE; + is_static = 1; + break; + case DW_TAG_enumerator: + kind = VARIABLE; + is_static = (language != CPLUS && language != JAVA); + break; + case DW_TAG_subprogram: + kind = FUNCTION; + is_static = ! (is_external || language == ADA); + break; + case DW_TAG_constant: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_variable: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_namespace: + kind = TYPE; + is_static = 0; + break; + case DW_TAG_class_type: + case DW_TAG_interface_type: + case DW_TAG_structure_type: + case DW_TAG_union_type: + case DW_TAG_enumeration_type: + kind = TYPE; + is_static = (language != CPLUS && language != JAVA); + break; + default: + assert (0); + } + + +File: gdb.info, Node: Man Pages, Next: Copying, Prev: Index Section Format, Up: Top + +Appendix K Manual pages +*********************** + +* Menu: + +* gdb man:: The GNU Debugger man page +* gdbserver man:: Remote Server for the GNU Debugger man page +* gcore man:: Generate a core file of a running program +* gdbinit man:: gdbinit scripts + + +File: gdb.info, Node: gdb man, Next: gdbserver man, Up: Man Pages + +gdb man +======= + +gdb ['-help'] ['-nh'] ['-nx'] ['-q'] ['-batch'] ['-cd='DIR] ['-f'] +['-b' BPS] ['-tty='DEV] ['-s' SYMFILE] ['-e' PROG] ['-se' PROG] +['-c' CORE] ['-p' PROCID] ['-x' CMDS] ['-d' DIR] [PROG|PROG PROCID|PROG +CORE] + + The purpose of a debugger such as GDB is to allow you to see what is +going on "inside" another program while it executes - or what another +program was doing at the moment it crashed. + + GDB can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: + + * Start your program, specifying anything that might affect its + behavior. + + * Make your program stop on specified conditions. + + * Examine what has happened, when your program has stopped. + + * Change things in your program, so you can experiment with + correcting the effects of one bug and go on to learn about another. + + You can use GDB to debug programs written in C, C++, Fortran and +Modula-2. + + GDB is invoked with the shell command 'gdb'. Once started, it reads +commands from the terminal until you tell it to exit with the GDB +command 'quit'. You can get online help from GDB itself by using the +command 'help'. + + You can run 'gdb' with no arguments or options; but the most usual +way to start GDB is with one argument or two, specifying an executable +program as the argument: + + gdb program + + You can also start with both an executable program and a core file +specified: + + gdb program core + + You can, instead, specify a process ID as a second argument, if you +want to debug a running process: + + gdb program 1234 + gdb -p 1234 + +would attach GDB to process '1234' (unless you also have a file named +'1234'; GDB does check for a core file first). With option '-p' you can +omit the PROGRAM filename. + + Here are some of the most frequently needed GDB commands: + +'break [FILE:]FUNCTIOP' + Set a breakpoint at FUNCTION (in FILE). + +'run [ARGLIST]' + Start your program (with ARGLIST, if specified). + +'bt' + Backtrace: display the program stack. + +'print EXPR' + Display the value of an expression. + +'c' + Continue running your program (after stopping, e.g. at a + breakpoint). + +'next' + Execute next program line (after stopping); step _over_ any + function calls in the line. + +'edit [FILE:]FUNCTION' + look at the program line where it is presently stopped. + +'list [FILE:]FUNCTION' + type the text of the program in the vicinity of where it is + presently stopped. + +'step' + Execute next program line (after stopping); step _into_ any + function calls in the line. + +'help [NAME]' + Show information about GDB command NAME, or general information + about using GDB. + +'quit' + Exit from GDB. + + Any arguments other than options specify an executable file and core +file (or process ID); that is, the first argument encountered with no +associated option flag is equivalent to a '-se' option, and the second, +if any, is equivalent to a '-c' option if it's the name of a file. Many +options have both long and short forms; both are shown here. The long +forms are also recognized if you truncate them, so long as enough of the +option is present to be unambiguous. (If you prefer, you can flag +option arguments with '+' rather than '-', though we illustrate the more +usual convention.) + + All the options and command line arguments you give are processed in +sequential order. The order makes a difference when the '-x' option is +used. + +'-help' +'-h' + List all options, with brief explanations. + +'-symbols=FILE' +'-s FILE' + Read symbol table from file FILE. + +'-write' + Enable writing into executable and core files. + +'-exec=FILE' +'-e FILE' + Use file FILE as the executable file to execute when appropriate, + and for examining pure data in conjunction with a core dump. + +'-se=FILE' + Read symbol table from file FILE and use it as the executable file. + +'-core=FILE' +'-c FILE' + Use file FILE as a core dump to examine. + +'-command=FILE' +'-x FILE' + Execute GDB commands from file FILE. + +'-ex COMMAND' + Execute given GDB COMMAND. + +'-directory=DIRECTORY' +'-d DIRECTORY' + Add DIRECTORY to the path to search for source files. + +'-nh' + Do not execute commands from '~/.gdbinit'. + +'-nx' +'-n' + Do not execute commands from any '.gdbinit' initialization files. + +'-quiet' +'-q' + "Quiet". Do not print the introductory and copyright messages. + These messages are also suppressed in batch mode. + +'-batch' + Run in batch mode. Exit with status '0' after processing all the + command files specified with '-x' (and '.gdbinit', if not + inhibited). Exit with nonzero status if an error occurs in + executing the GDB commands in the command files. + + Batch mode may be useful for running GDB as a filter, for example + to download and run a program on another computer; in order to make + this more useful, the message + + Program exited normally. + + (which is ordinarily issued whenever a program running under GDB + control terminates) is not issued when running in batch mode. + +'-cd=DIRECTORY' + Run GDB using DIRECTORY as its working directory, instead of the + current directory. + +'-fullname' +'-f' + Emacs sets this option when it runs GDB as a subprocess. It tells + GDB to output the full file name and line number in a standard, + recognizable fashion each time a stack frame is displayed (which + includes each time the program stops). This recognizable format + looks like two '\032' characters, followed by the file name, line + number and character position separated by colons, and a newline. + The Emacs-to-GDB interface program uses the two '\032' characters + as a signal to display the source code for the frame. + +'-b BPS' + Set the line speed (baud rate or bits per second) of any serial + interface used by GDB for remote debugging. + +'-tty=DEVICE' + Run using DEVICE for your program's standard input and output. + + +File: gdb.info, Node: gdbserver man, Next: gcore man, Prev: gdb man, Up: Man Pages + +gdbserver man +============= + +gdbserver COMM PROG [ARGS...] + +gdbserver -attach COMM PID + +gdbserver -multi COMM + + 'gdbserver' is a program that allows you to run GDB on a different +machine than the one which is running the program being debugged. + +Usage (server (target) side) +---------------------------- + +First, you need to have a copy of the program you want to debug put onto +the target system. The program can be stripped to save space if needed, +as 'gdbserver' doesn't care about symbols. All symbol handling is taken +care of by the GDB running on the host system. + + To use the server, you log on to the target system, and run the +'gdbserver' program. You must tell it (a) how to communicate with GDB, +(b) the name of your program, and (c) its arguments. The general syntax +is: + + target> gdbserver COMM PROGRAM [ARGS ...] + + For example, using a serial port, you might say: + + target> gdbserver /dev/com1 emacs foo.txt + + This tells 'gdbserver' to debug emacs with an argument of foo.txt, +and to communicate with GDB via '/dev/com1'. 'gdbserver' now waits +patiently for the host GDB to communicate with it. + + To use a TCP connection, you could say: + + target> gdbserver host:2345 emacs foo.txt + + This says pretty much the same thing as the last example, except that +we are going to communicate with the 'host' GDB via TCP. The 'host:2345' +argument means that we are expecting to see a TCP connection from 'host' +to local TCP port 2345. (Currently, the 'host' part is ignored.) You +can choose any number you want for the port number as long as it does +not conflict with any existing TCP ports on the target system. This +same port number must be used in the host GDBs 'target remote' command, +which will be described shortly. Note that if you chose a port number +that conflicts with another service, 'gdbserver' will print an error +message and exit. + + 'gdbserver' can also attach to running programs. This is +accomplished via the '--attach' argument. The syntax is: + + target> gdbserver --attach COMM PID + + PID is the process ID of a currently running process. It isn't +necessary to point 'gdbserver' at a binary for the running process. + + To start 'gdbserver' without supplying an initial command to run or +process ID to attach, use the '--multi' command line option. In such +case you should connect using 'target extended-remote' to start the +program you want to debug. + + target> gdbserver --multi COMM + +Usage (host side) +----------------- + +You need an unstripped copy of the target program on your host system, +since GDB needs to examine it's symbol tables and such. Start up GDB as +you normally would, with the target program as the first argument. (You +may need to use the '--baud' option if the serial line is running at +anything except 9600 baud.) That is 'gdb TARGET-PROG', or 'gdb --baud +BAUD TARGET-PROG'. After that, the only new command you need to know +about is 'target remote' (or 'target extended-remote'). Its argument is +either a device name (usually a serial device, like '/dev/ttyb'), or a +'HOST:PORT' descriptor. For example: + + (gdb) target remote /dev/ttyb + +communicates with the server via serial line '/dev/ttyb', and: + + (gdb) target remote the-target:2345 + +communicates via a TCP connection to port 2345 on host 'the-target', +where you previously started up 'gdbserver' with the same port number. +Note that for TCP connections, you must start up 'gdbserver' prior to +using the 'target remote' command, otherwise you may get an error that +looks something like 'Connection refused'. + + 'gdbserver' can also debug multiple inferiors at once, described in +*note Inferiors and Programs::. In such case use the 'extended-remote' +GDB command variant: + + (gdb) target extended-remote the-target:2345 + + The 'gdbserver' option '--multi' may or may not be used in such case. + + There are three different modes for invoking 'gdbserver': + + * Debug a specific program specified by its program name: + + gdbserver COMM PROG [ARGS...] + + The COMM parameter specifies how should the server communicate with + GDB; it is either a device name (to use a serial line), a TCP port + number (':1234'), or '-' or 'stdio' to use stdin/stdout of + 'gdbserver'. Specify the name of the program to debug in PROG. + Any remaining arguments will be passed to the program verbatim. + When the program exits, GDB will close the connection, and + 'gdbserver' will exit. + + * Debug a specific program by specifying the process ID of a running + program: + + gdbserver --attach COMM PID + + The COMM parameter is as described above. Supply the process ID of + a running program in PID; GDB will do everything else. Like with + the previous mode, when the process PID exits, GDB will close the + connection, and 'gdbserver' will exit. + + * Multi-process mode - debug more than one program/process: + + gdbserver --multi COMM + + In this mode, GDB can instruct 'gdbserver' which command(s) to run. + Unlike the other 2 modes, GDB will not close the connection when a + process being debugged exits, so you can debug several processes in + the same session. + + In each of the modes you may specify these options: + +'--help' + List all options, with brief explanations. + +'--version' + This option causes 'gdbserver' to print its version number and + exit. + +'--attach' + 'gdbserver' will attach to a running program. The syntax is: + + target> gdbserver --attach COMM PID + + PID is the process ID of a currently running process. It isn't + necessary to point 'gdbserver' at a binary for the running process. + +'--multi' + To start 'gdbserver' without supplying an initial command to run or + process ID to attach, use this command line option. Then you can + connect using 'target extended-remote' and start the program you + want to debug. The syntax is: + + target> gdbserver --multi COMM + +'--debug' + Instruct 'gdbserver' to display extra status information about the + debugging process. This option is intended for 'gdbserver' + development and for bug reports to the developers. + +'--remote-debug' + Instruct 'gdbserver' to display remote protocol debug output. This + option is intended for 'gdbserver' development and for bug reports + to the developers. + +'--wrapper' + Specify a wrapper to launch programs for debugging. The option + should be followed by the name of the wrapper, then any + command-line arguments to pass to the wrapper, then '--' indicating + the end of the wrapper arguments. + +'--once' + By default, 'gdbserver' keeps the listening TCP port open, so that + additional connections are possible. However, if you start + 'gdbserver' with the '--once' option, it will stop listening for + any further connection attempts after connecting to the first GDB + session. + + +File: gdb.info, Node: gcore man, Next: gdbinit man, Prev: gdbserver man, Up: Man Pages + +gcore +===== + +gcore [-o FILENAME] PID + + Generate a core dump of a running program with process ID PID. +Produced file is equivalent to a kernel produced core file as if the +process crashed (and if 'ulimit -c' were used to set up an appropriate +core dump limit). Unlike after a crash, after 'gcore' the program +remains running without any change. + +'-o FILENAME' + The optional argument FILENAME specifies the file name where to put + the core dump. If not specified, the file name defaults to + 'core.PID', where PID is the running program process ID. + + +File: gdb.info, Node: gdbinit man, Prev: gcore man, Up: Man Pages + +gdbinit +======= + + +~/.gdbinit + +./.gdbinit + + These files contain GDB commands to automatically execute during GDB +startup. The lines of contents are canned sequences of commands, +described in *note Sequences::. + + Please read more in *note Startup::. + +'(not enabled with --with-system-gdbinit during compilation)' + System-wide initialization file. It is executed unless user + specified GDB option '-nx' or '-n'. See more in *note System-wide + configuration::. + +'~/.gdbinit' + User initialization file. It is executed unless user specified GDB + options '-nx', '-n' or '-nh'. + +'./.gdbinit' + Initialization file for current directory. It may need to be + enabled with GDB security command 'set auto-load local-gdbinit'. + See more in *note Init File in the Current Directory::. + + +File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Man Pages, Up: Top + +Appendix L GNU GENERAL PUBLIC LICENSE +************************************* + + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + +Preamble +======== + +The GNU General Public License is a free, copyleft license for software +and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + +TERMS AND CONDITIONS +==================== + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public + License. + + "Copyright" also means copyright-like laws that apply to other + kinds of works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this + License. Each licensee is addressed as "you". "Licensees" and + "recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the + work in a fashion requiring copyright permission, other than the + making of an exact copy. The resulting work is called a "modified + version" of the earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work + based on the Program. + + To "propagate" a work means to do anything with it that, without + permission, would make you directly or secondarily liable for + infringement under applicable copyright law, except executing it on + a computer or modifying a private copy. Propagation includes + copying, distribution (with or without modification), making + available to the public, and in some countries other activities as + well. + + To "convey" a work means any kind of propagation that enables other + parties to make or receive copies. Mere interaction with a user + through a computer network, with no transfer of a copy, is not + conveying. + + An interactive user interface displays "Appropriate Legal Notices" + to the extent that it includes a convenient and prominently visible + feature that (1) displays an appropriate copyright notice, and (2) + tells the user that there is no warranty for the work (except to + the extent that warranties are provided), that licensees may convey + the work under this License, and how to view a copy of this + License. If the interface presents a list of user commands or + options, such as a menu, a prominent item in the list meets this + criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work + for making modifications to it. "Object code" means any non-source + form of a work. + + A "Standard Interface" means an interface that either is an + official standard defined by a recognized standards body, or, in + the case of interfaces specified for a particular programming + language, one that is widely used among developers working in that + language. + + The "System Libraries" of an executable work include anything, + other than the work as a whole, that (a) is included in the normal + form of packaging a Major Component, but which is not part of that + Major Component, and (b) serves only to enable use of the work with + that Major Component, or to implement a Standard Interface for + which an implementation is available to the public in source code + form. A "Major Component", in this context, means a major + essential component (kernel, window system, and so on) of the + specific operating system (if any) on which the executable work + runs, or a compiler used to produce the work, or an object code + interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all + the source code needed to generate, install, and (for an executable + work) run the object code and to modify the work, including scripts + to control those activities. However, it does not include the + work's System Libraries, or general-purpose tools or generally + available free programs which are used unmodified in performing + those activities but which are not part of the work. For example, + Corresponding Source includes interface definition files associated + with source files for the work, and the source code for shared + libraries and dynamically linked subprograms that the work is + specifically designed to require, such as by intimate data + communication or control flow between those subprograms and other + parts of the work. + + The Corresponding Source need not include anything that users can + regenerate automatically from other parts of the Corresponding + Source. + + The Corresponding Source for a work in source code form is that + same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of + copyright on the Program, and are irrevocable provided the stated + conditions are met. This License explicitly affirms your unlimited + permission to run the unmodified Program. The output from running + a covered work is covered by this License only if the output, given + its content, constitutes a covered work. This License acknowledges + your rights of fair use or other equivalent, as provided by + copyright law. + + You may make, run and propagate covered works that you do not + convey, without conditions so long as your license otherwise + remains in force. You may convey covered works to others for the + sole purpose of having them make modifications exclusively for you, + or provide you with facilities for running those works, provided + that you comply with the terms of this License in conveying all + material for which you do not control copyright. Those thus making + or running the covered works for you must do so exclusively on your + behalf, under your direction and control, on terms that prohibit + them from making any copies of your copyrighted material outside + their relationship with you. + + Conveying under any other circumstances is permitted solely under + the conditions stated below. Sublicensing is not allowed; section + 10 makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological + measure under any applicable law fulfilling obligations under + article 11 of the WIPO copyright treaty adopted on 20 December + 1996, or similar laws prohibiting or restricting circumvention of + such measures. + + When you convey a covered work, you waive any legal power to forbid + circumvention of technological measures to the extent such + circumvention is effected by exercising rights under this License + with respect to the covered work, and you disclaim any intention to + limit operation or modification of the work as a means of + enforcing, against the work's users, your or third parties' legal + rights to forbid circumvention of technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you + receive it, in any medium, provided that you conspicuously and + appropriately publish on each copy an appropriate copyright notice; + keep intact all notices stating that this License and any + non-permissive terms added in accord with section 7 apply to the + code; keep intact all notices of the absence of any warranty; and + give all recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, + and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to + produce it from the Program, in the form of source code under the + terms of section 4, provided that you also meet all of these + conditions: + + a. The work must carry prominent notices stating that you + modified it, and giving a relevant date. + + b. The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in + section 4 to "keep intact all notices". + + c. You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable + section 7 additional terms, to the whole of the work, and all + its parts, regardless of how they are packaged. This License + gives no permission to license the work in any other way, but + it does not invalidate such permission if you have separately + received it. + + d. If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has + interactive interfaces that do not display Appropriate Legal + Notices, your work need not make them do so. + + A compilation of a covered work with other separate and independent + works, which are not by their nature extensions of the covered + work, and which are not combined with it such as to form a larger + program, in or on a volume of a storage or distribution medium, is + called an "aggregate" if the compilation and its resulting + copyright are not used to limit the access or legal rights of the + compilation's users beyond what the individual works permit. + Inclusion of a covered work in an aggregate does not cause this + License to apply to the other parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms + of sections 4 and 5, provided that you also convey the + machine-readable Corresponding Source under the terms of this + License, in one of these ways: + + a. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that + product model, to give anyone who possesses the object code + either (1) a copy of the Corresponding Source for all the + software in the product that is covered by this License, on a + durable physical medium customarily used for software + interchange, for a price no more than your reasonable cost of + physically performing this conveying of source, or (2) access + to copy the Corresponding Source from a network server at no + charge. + + c. Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, + and only if you received the object code with such an offer, + in accord with subsection 6b. + + d. Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to + the Corresponding Source in the same way through the same + place at no further charge. You need not require recipients + to copy the Corresponding Source along with the object code. + If the place to copy the object code is a network server, the + Corresponding Source may be on a different server (operated by + you or a third party) that supports equivalent copying + facilities, provided you maintain clear directions next to the + object code saying where to find the Corresponding Source. + Regardless of what server hosts the Corresponding Source, you + remain obligated to ensure that it is available for as long as + needed to satisfy these requirements. + + e. Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the + general public at no charge under subsection 6d. + + A separable portion of the object code, whose source code is + excluded from the Corresponding Source as a System Library, need + not be included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means + any tangible personal property which is normally used for personal, + family, or household purposes, or (2) anything designed or sold for + incorporation into a dwelling. In determining whether a product is + a consumer product, doubtful cases shall be resolved in favor of + coverage. For a particular product received by a particular user, + "normally used" refers to a typical or common use of that class of + product, regardless of the status of the particular user or of the + way in which the particular user actually uses, or expects or is + expected to use, the product. A product is a consumer product + regardless of whether the product has substantial commercial, + industrial or non-consumer uses, unless such uses represent the + only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, + procedures, authorization keys, or other information required to + install and execute modified versions of a covered work in that + User Product from a modified version of its Corresponding Source. + The information must suffice to ensure that the continued + functioning of the modified object code is in no case prevented or + interfered with solely because modification has been made. + + If you convey an object code work under this section in, or with, + or specifically for use in, a User Product, and the conveying + occurs as part of a transaction in which the right of possession + and use of the User Product is transferred to the recipient in + perpetuity or for a fixed term (regardless of how the transaction + is characterized), the Corresponding Source conveyed under this + section must be accompanied by the Installation Information. But + this requirement does not apply if neither you nor any third party + retains the ability to install modified object code on the User + Product (for example, the work has been installed in ROM). + + The requirement to provide Installation Information does not + include a requirement to continue to provide support service, + warranty, or updates for a work that has been modified or installed + by the recipient, or for the User Product in which it has been + modified or installed. Access to a network may be denied when the + modification itself materially and adversely affects the operation + of the network or violates the rules and protocols for + communication across the network. + + Corresponding Source conveyed, and Installation Information + provided, in accord with this section must be in a format that is + publicly documented (and with an implementation available to the + public in source code form), and must require no special password + or key for unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of + this License by making exceptions from one or more of its + conditions. Additional permissions that are applicable to the + entire Program shall be treated as though they were included in + this License, to the extent that they are valid under applicable + law. If additional permissions apply only to part of the Program, + that part may be used separately under those permissions, but the + entire Program remains governed by this License without regard to + the additional permissions. + + When you convey a copy of a covered work, you may at your option + remove any additional permissions from that copy, or from any part + of it. (Additional permissions may be written to require their own + removal in certain cases when you modify the work.) You may place + additional permissions on material, added by you to a covered work, + for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material + you add to a covered work, you may (if authorized by the copyright + holders of that material) supplement the terms of this License with + terms: + + a. Disclaiming warranty or limiting liability differently from + the terms of sections 15 and 16 of this License; or + + b. Requiring preservation of specified reasonable legal notices + or author attributions in that material or in the Appropriate + Legal Notices displayed by works containing it; or + + c. Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be marked + in reasonable ways as different from the original version; or + + d. Limiting the use for publicity purposes of names of licensors + or authors of the material; or + + e. Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f. Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified + versions of it) with contractual assumptions of liability to + the recipient, for any liability that these contractual + assumptions directly impose on those licensors and authors. + + All other non-permissive additional terms are considered "further + restrictions" within the meaning of section 10. If the Program as + you received it, or any part of it, contains a notice stating that + it is governed by this License along with a term that is a further + restriction, you may remove that term. If a license document + contains a further restriction but permits relicensing or conveying + under this License, you may add to a covered work material governed + by the terms of that license document, provided that the further + restriction does not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you + must place, in the relevant source files, a statement of the + additional terms that apply to those files, or a notice indicating + where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in + the form of a separately written license, or stated as exceptions; + the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly + provided under this License. Any attempt otherwise to propagate or + modify it is void, and will automatically terminate your rights + under this License (including any patent licenses granted under the + third paragraph of section 11). + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, you do not qualify to receive new licenses + for the same material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or + run a copy of the Program. Ancillary propagation of a covered work + occurring solely as a consequence of using peer-to-peer + transmission to receive a copy likewise does not require + acceptance. However, nothing other than this License grants you + permission to propagate or modify any covered work. These actions + infringe copyright if you do not accept this License. Therefore, + by modifying or propagating a covered work, you indicate your + acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically + receives a license from the original licensors, to run, modify and + propagate that work, subject to this License. You are not + responsible for enforcing compliance by third parties with this + License. + + An "entity transaction" is a transaction transferring control of an + organization, or substantially all assets of one, or subdividing an + organization, or merging organizations. If propagation of a + covered work results from an entity transaction, each party to that + transaction who receives a copy of the work also receives whatever + licenses to the work the party's predecessor in interest had or + could give under the previous paragraph, plus a right to possession + of the Corresponding Source of the work from the predecessor in + interest, if the predecessor has it or can get it with reasonable + efforts. + + You may not impose any further restrictions on the exercise of the + rights granted or affirmed under this License. For example, you + may not impose a license fee, royalty, or other charge for exercise + of rights granted under this License, and you may not initiate + litigation (including a cross-claim or counterclaim in a lawsuit) + alleging that any patent claim is infringed by making, using, + selling, offering for sale, or importing the Program or any portion + of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this + License of the Program or a work on which the Program is based. + The work thus licensed is called the contributor's "contributor + version". + + A contributor's "essential patent claims" are all patent claims + owned or controlled by the contributor, whether already acquired or + hereafter acquired, that would be infringed by some manner, + permitted by this License, of making, using, or selling its + contributor version, but do not include claims that would be + infringed only as a consequence of further modification of the + contributor version. For purposes of this definition, "control" + includes the right to grant patent sublicenses in a manner + consistent with the requirements of this License. + + Each contributor grants you a non-exclusive, worldwide, + royalty-free patent license under the contributor's essential + patent claims, to make, use, sell, offer for sale, import and + otherwise run, modify and propagate the contents of its contributor + version. + + In the following three paragraphs, a "patent license" is any + express agreement or commitment, however denominated, not to + enforce a patent (such as an express permission to practice a + patent or covenant not to sue for patent infringement). To "grant" + such a patent license to a party means to make such an agreement or + commitment not to enforce a patent against the party. + + If you convey a covered work, knowingly relying on a patent + license, and the Corresponding Source of the work is not available + for anyone to copy, free of charge and under the terms of this + License, through a publicly available network server or other + readily accessible means, then you must either (1) cause the + Corresponding Source to be so available, or (2) arrange to deprive + yourself of the benefit of the patent license for this particular + work, or (3) arrange, in a manner consistent with the requirements + of this License, to extend the patent license to downstream + recipients. "Knowingly relying" means you have actual knowledge + that, but for the patent license, your conveying the covered work + in a country, or your recipient's use of the covered work in a + country, would infringe one or more identifiable patents in that + country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or + arrangement, you convey, or propagate by procuring conveyance of, a + covered work, and grant a patent license to some of the parties + receiving the covered work authorizing them to use, propagate, + modify or convey a specific copy of the covered work, then the + patent license you grant is automatically extended to all + recipients of the covered work and works based on it. + + A patent license is "discriminatory" if it does not include within + the scope of its coverage, prohibits the exercise of, or is + conditioned on the non-exercise of one or more of the rights that + are specifically granted under this License. You may not convey a + covered work if you are a party to an arrangement with a third + party that is in the business of distributing software, under which + you make payment to the third party based on the extent of your + activity of conveying the work, and under which the third party + grants, to any of the parties who would receive the covered work + from you, a discriminatory patent license (a) in connection with + copies of the covered work conveyed by you (or copies made from + those copies), or (b) primarily for and in connection with specific + products or compilations that contain the covered work, unless you + entered into that arrangement, or that patent license was granted, + prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting + any implied license or other defenses to infringement that may + otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement + or otherwise) that contradict the conditions of this License, they + do not excuse you from the conditions of this License. If you + cannot convey a covered work so as to satisfy simultaneously your + obligations under this License and any other pertinent obligations, + then as a consequence you may not convey it at all. For example, + if you agree to terms that obligate you to collect a royalty for + further conveying from those to whom you convey the Program, the + only way you could satisfy both those terms and this License would + be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have + permission to link or combine any covered work with a work licensed + under version 3 of the GNU Affero General Public License into a + single combined work, and to convey the resulting work. The terms + of this License will continue to apply to the part which is the + covered work, but the special requirements of the GNU Affero + General Public License, section 13, concerning interaction through + a network will apply to the combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new + versions of the GNU General Public License from time to time. Such + new versions will be similar in spirit to the present version, but + may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Program specifies that a certain numbered version of the GNU + General Public License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that numbered version or of any later version published by the Free + Software Foundation. If the Program does not specify a version + number of the GNU General Public License, you may choose any + version ever published by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future + versions of the GNU General Public License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Program. + + Later license versions may give you additional or different + permissions. However, no additional obligations are imposed on any + author or copyright holder as a result of your choosing to follow a + later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY + APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE + COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" + WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE + RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. + SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL + NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES + AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR + DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE + THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA + BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD + PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER + PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF + THE POSSIBILITY OF SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided + above cannot be given local legal effect according to their terms, + reviewing courts shall apply local law that most closely + approximates an absolute waiver of all civil liability in + connection with the Program, unless a warranty or assumption of + liability accompanies a copy of the Program in return for a fee. + +END OF TERMS AND CONDITIONS +=========================== + +How to Apply These Terms to Your New Programs +============================================= + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or (at + your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + + Also add information on how to contact you by electronic and paper +mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + PROGRAM Copyright (C) YEAR NAME OF AUTHOR + This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type 'show c' for details. + + The hypothetical commands 'show w' and 'show c' should show the +appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an "about box". + + You should also get your employer (if you work as a programmer) or +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. For more information on this, and how to apply and follow +the GNU GPL, see . + + The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Lesser General Public License instead of this License. But first, +please read . + + +File: gdb.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Copying, Up: Top + +Appendix M GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: gdb.info, Node: Concept Index, Next: Command and Variable Index, Prev: GNU Free Documentation License, Up: Top + +Concept Index +************* + +[index] +* Menu: + +* '!' packet: Packets. (line 49) +* "No symbol "foo" in current context": Variables. (line 122) +* '#' in Modula-2: GDB/M2. (line 18) +* '$': Value History. (line 13) +* '$$': Value History. (line 13) +* '$_' and 'info breakpoints': Set Breaks. (line 125) +* '$_' and 'info line': Machine Code. (line 30) +* '$_', '$__', and value history: Memory. (line 105) +* '--annotate': Mode Options. (line 120) +* '--args': Mode Options. (line 133) +* '--attach', 'gdbserver' option: Server. (line 86) +* '--batch': Mode Options. (line 44) +* '--batch-silent': Mode Options. (line 62) +* '--baud': Mode Options. (line 139) +* '--cd': Mode Options. (line 101) +* '--command': File Options. (line 51) +* '--configuration': Mode Options. (line 183) +* '--core': File Options. (line 43) +* '--data-directory': Mode Options. (line 105) +* '--debug', 'gdbserver' option: Server. (line 166) +* '--directory': File Options. (line 77) +* '--eval-command': File Options. (line 57) +* '--exec': File Options. (line 35) +* '--fullname': Mode Options. (line 110) +* '--init-command': File Options. (line 67) +* '--init-eval-command': File Options. (line 72) +* '--interpreter': Mode Options. (line 158) +* '--multi', 'gdbserver' option: Server. (line 119) +* '--nh': Mode Options. (line 34) +* '--nowindows': Mode Options. (line 91) +* '--nx': Mode Options. (line 11) +* '--once', 'gdbserver' option: Server. (line 151) +* '--pid': File Options. (line 47) +* '--quiet': Mode Options. (line 40) +* '--readnow': File Options. (line 81) +* '--remote-debug', 'gdbserver' option: Server. (line 167) +* '--return-child-result': Mode Options. (line 74) +* '--se': File Options. (line 39) +* '--silent': Mode Options. (line 40) +* '--statistics': Mode Options. (line 175) +* '--symbols': File Options. (line 31) +* '--tty': Mode Options. (line 148) +* '--tui': Mode Options. (line 151) +* '--version': Mode Options. (line 179) +* '--windows': Mode Options. (line 97) +* '--with-gdb-datadir': Data Files. (line 19) +* '--with-relocated-sources': Source Path. (line 88) +* '--with-sysroot': Files. (line 441) +* '--wrapper', 'gdbserver' option: Server. (line 172) +* '--write': Mode Options. (line 170) +* '-b': Mode Options. (line 139) +* '-c': File Options. (line 43) +* '-d': File Options. (line 77) +* '-e': File Options. (line 35) +* '-ex': File Options. (line 57) +* '-f': Mode Options. (line 110) +* '-iex': File Options. (line 72) +* '-info-gdb-mi-command': GDB/MI Support Commands. + (line 14) +* '-ix': File Options. (line 67) +* '-l': Mode Options. (line 143) +* '-n': Mode Options. (line 11) +* '-nw': Mode Options. (line 91) +* '-p': File Options. (line 47) +* '-q': Mode Options. (line 40) +* '-r': File Options. (line 81) +* '-s': File Options. (line 31) +* '-t': Mode Options. (line 148) +* '-w': Mode Options. (line 97) +* '-x': File Options. (line 51) +* '.', Modula-2 scope operator: M2 Scope. (line 6) +* '.build-id' directory: Separate Debug Files. + (line 6) +* '.debug' subdirectories: Separate Debug Files. + (line 6) +* '.debug_gdb_scripts' section: dotdebug_gdb_scripts section. + (line 6) +* '.gdbinit': Startup. (line 65) +* '.gdb_index' section: Index Files. (line 6) +* .gdb_index section format: Index Section Format. + (line 6) +* '.gnu_debugdata' section: MiniDebugInfo. (line 6) +* '.gnu_debuglink' sections: Separate Debug Files. + (line 76) +* '.note.gnu.build-id' sections: Separate Debug Files. + (line 92) +* '.o' files, reading symbols from: Files. (line 132) +* /proc: SVR4 Process Information. + (line 6) +* : Target Description Format. + (line 72) +* '': Target Description Format. + (line 95) +* : Target Description Format. + (line 119) +* : Target Description Format. + (line 185) +* values: Registers. (line 101) +* '': Target Description Format. + (line 82) +* : Target Description Format. + (line 198) +* : Target Description Format. + (line 163) +* : Target Description Format. + (line 153) +* : Target Description Format. + (line 146) +* '?' packet: Packets. (line 58) +* '_NSPrintForDebugger', and printing Objective-C objects: The Print Command with Objective-C. + (line 11) +* {TYPE}: Expressions. (line 41) +* 'A' packet: Packets. (line 65) +* AArch64 support: AArch64. (line 6) +* abbreviation: Command Syntax. (line 13) +* acknowledgment, for GDB remote: Packet Acknowledgment. + (line 6) +* active targets: Active Targets. (line 6) +* Ada: Ada. (line 6) +* Ada exception catching: Set Catchpoints. (line 66) +* Ada mode, general: Ada Mode Intro. (line 6) +* Ada task switching: Ada Tasks. (line 113) +* Ada tasking and core file debugging: Ada Tasks and Core Files. + (line 6) +* Ada, deviations from: Additions to Ada. (line 6) +* Ada, omissions from: Omissions from Ada. (line 6) +* Ada, problems: Ada Glitches. (line 6) +* Ada, tasking: Ada Tasks. (line 6) +* add new commands for external monitor: Connecting. (line 105) +* address of a symbol: Symbols. (line 74) +* address size for remote targets: Remote Configuration. + (line 12) +* ADP (Angel Debugger Protocol) logging: ARM. (line 84) +* aggregates (Ada): Omissions from Ada. (line 44) +* AIX shared library debugging: Debugging Output. (line 30) +* AIX threads: Debugging Output. (line 36) +* aliases for commands: Aliases. (line 6) +* alignment of remote memory accesses: Packets. (line 231) +* all-stop mode: All-Stop Mode. (line 6) +* Alpha stack: MIPS. (line 6) +* ambiguous expressions: Ambiguous Expressions. + (line 6) +* annotations: Annotations Overview. + (line 6) +* annotations for errors, warnings and interrupts: Errors. (line 6) +* annotations for invalidation messages: Invalidation. (line 6) +* annotations for prompts: Prompting. (line 6) +* annotations for running programs: Annotations for Running. + (line 6) +* annotations for source display: Source Annotations. (line 6) +* append data to a file: Dump/Restore Files. (line 6) +* apply command to several threads: Threads. (line 116) +* architecture debugging info: Debugging Output. (line 23) +* argument count in user-defined commands: Define. (line 25) +* arguments (to your program): Arguments. (line 6) +* arguments, to 'gdbserver': Server. (line 34) +* arguments, to user-defined commands: Define. (line 6) +* ARM 32-bit mode: ARM. (line 24) +* ARM AArch64: Debugging Output. (line 17) +* ARM RDI: ARM. (line 6) +* array aggregates (Ada): Omissions from Ada. (line 44) +* arrays: Arrays. (line 6) +* arrays in expressions: Expressions. (line 13) +* artificial array: Arrays. (line 6) +* assembly instructions: Machine Code. (line 36) +* assignment: Assignment. (line 6) +* async output in GDB/MI: GDB/MI Output Syntax. + (line 98) +* async records in GDB/MI: GDB/MI Async Records. + (line 6) +* asynchronous execution: Background Execution. + (line 6) +* asynchronous execution, and process record and replay: Process Record and Replay. + (line 68) +* AT&T disassembly flavor: Machine Code. (line 131) +* attach: Attach. (line 6) +* attach to a program, 'gdbserver': Server. (line 86) +* auto-loading: Auto-loading. (line 6) +* auto-loading extensions: Auto-loading extensions. + (line 6) +* auto-loading init file in the current directory: Init File in the Current Directory. + (line 6) +* auto-loading libthread_db.so.1: libthread_db.so.1 file. + (line 6) +* auto-loading safe-path: Auto-loading safe path. + (line 6) +* auto-loading verbose mode: Auto-loading verbose mode. + (line 6) +* auto-retry, for remote TCP target: Remote Configuration. + (line 117) +* automatic display: Auto Display. (line 6) +* automatic hardware breakpoints: Set Breaks. (line 287) +* automatic overlay debugging: Automatic Overlay Debugging. + (line 6) +* automatic thread selection: All-Stop Mode. (line 28) +* auxiliary vector: OS Information. (line 9) +* AVR: AVR. (line 6) +* 'b' packet: Packets. (line 76) +* 'B' packet: Packets. (line 91) +* background execution: Background Execution. + (line 6) +* backtrace beyond 'main' function: Backtrace. (line 105) +* backtrace limit: Backtrace. (line 142) +* base name differences: Files. (line 508) +* baud rate for remote targets: Remote Configuration. + (line 21) +* 'bc' packet: Packets. (line 96) +* bcache statistics: Maintenance Commands. + (line 246) +* bits in remote address: Remote Configuration. + (line 12) +* blocks in python: Blocks In Python. (line 6) +* bookmark: Checkpoint/Restart. (line 6) +* branch trace format: Branch Trace Format. + (line 6) +* break in overloaded functions: Debugging C Plus Plus. + (line 9) +* break on a system call.: Set Catchpoints. (line 95) +* break on fork/exec: Set Catchpoints. (line 90) +* BREAK signal instead of Ctrl-C: Remote Configuration. + (line 29) +* breakpoint address adjusted: Breakpoint-related Warnings. + (line 6) +* breakpoint at static probe point: Specify Location. (line 91) +* breakpoint commands: Break Commands. (line 6) +* breakpoint commands for GDB/MI: GDB/MI Breakpoint Commands. + (line 6) +* breakpoint commands, in remote protocol: General Query Packets. + (line 722) +* breakpoint conditions: Conditions. (line 6) +* breakpoint kinds, ARM: ARM Breakpoint Kinds. + (line 6) +* breakpoint kinds, MIPS: MIPS Breakpoint Kinds. + (line 6) +* breakpoint numbers: Breakpoints. (line 41) +* breakpoint on events: Breakpoints. (line 33) +* breakpoint on memory address: Breakpoints. (line 20) +* breakpoint on variable modification: Breakpoints. (line 20) +* breakpoint ranges: Breakpoints. (line 48) +* 'breakpoint' subroutine, remote: Stub Contents. (line 31) +* breakpointing Ada elaboration code: Stopping Before Main Program. + (line 6) +* breakpoints: Breakpoints. (line 6) +* breakpoints and tasks, in Ada: Ada Tasks. (line 133) +* breakpoints and threads: Thread-Specific Breakpoints. + (line 10) +* breakpoints at functions matching a regexp: Set Breaks. (line 89) +* breakpoints in overlays: Overlay Commands. (line 91) +* breakpoints in python: Breakpoints In Python. + (line 6) +* breakpoints, multiple locations: Set Breaks. (line 192) +* 'bs' packet: Packets. (line 102) +* bug criteria: Bug Criteria. (line 6) +* bug reports: Bug Reporting. (line 6) +* bugs in GDB: GDB Bugs. (line 6) +* build ID sections: Separate Debug Files. + (line 92) +* build ID, and separate debugging files: Separate Debug Files. + (line 6) +* building GDB, requirements for: Requirements. (line 6) +* built-in simulator target: Target Commands. (line 73) +* builtin Go functions: Go. (line 31) +* builtin Go types: Go. (line 28) +* C and C++: C. (line 6) +* C and C++ checks: C Checks. (line 6) +* C and C++ constants: C Constants. (line 6) +* C and C++ defaults: C Defaults. (line 6) +* C and C++ operators: C Operators. (line 6) +* 'c' packet: Packets. (line 109) +* 'C' packet: Packets. (line 118) +* C++: C. (line 10) +* C++ compilers: C Plus Plus Expressions. + (line 8) +* C++ exception handling: Debugging C Plus Plus. + (line 20) +* C++ overload debugging info: Debugging Output. (line 127) +* C++ scope resolution: Variables. (line 90) +* C++ symbol decoding style: Print Settings. (line 427) +* C++ symbol display: Debugging C Plus Plus. + (line 36) +* caching data of targets: Caching Target Data. + (line 6) +* call dummy stack unwinding: Calling. (line 35) +* call dummy stack unwinding on unhandled exception.: Calling. + (line 46) +* call overloaded functions: C Plus Plus Expressions. + (line 26) +* call stack: Stack. (line 9) +* call stack traces: Backtrace. (line 6) +* call-clobbered registers: Registers. (line 101) +* caller-saved registers: Registers. (line 101) +* calling functions: Calling. (line 6) +* calling make: Shell Commands. (line 21) +* case sensitivity in symbol names: Symbols. (line 27) +* case-insensitive symbol names: Symbols. (line 27) +* casts, in expressions: Expressions. (line 26) +* casts, to view memory: Expressions. (line 41) +* catch Ada exceptions: Set Catchpoints. (line 66) +* catchpoints: Breakpoints. (line 33) +* catchpoints, setting: Set Catchpoints. (line 6) +* Cell Broadband Engine: SPU. (line 6) +* change working directory: Working Directory. (line 16) +* character sets: Character Sets. (line 6) +* charset: Character Sets. (line 6) +* checkpoint: Checkpoint/Restart. (line 6) +* checkpoints and process id: Checkpoint/Restart. (line 76) +* checks, range: Type Checking. (line 44) +* checks, type: Checks. (line 23) +* checksum, for GDB remote: Overview. (line 21) +* choosing target byte order: Byte Order. (line 6) +* circular trace buffer: Starting and Stopping Trace Experiments. + (line 80) +* clearing breakpoints, watchpoints, catchpoints: Delete Breaks. + (line 6) +* close, file-i/o system call: close. (line 6) +* closest symbol and offset for an address: Symbols. (line 84) +* code address and its source line: Machine Code. (line 25) +* code compression, MIPS: MIPS. (line 49) +* COFF/PE exported symbols: Debugging Output. (line 50) +* collected data discarded: Starting and Stopping Trace Experiments. + (line 6) +* colon, doubled as scope operator: M2 Scope. (line 6) +* colon-colon, context for variables/functions: Variables. (line 44) +* command editing: Readline Bare Essentials. + (line 6) +* command files: Command Files. (line 6) +* command history: Command History. (line 6) +* command hooks: Hooks. (line 6) +* command interpreters: Interpreters. (line 6) +* command line editing: Editing. (line 6) +* command scripts, debugging: Messages/Warnings. (line 65) +* command tracing: Messages/Warnings. (line 60) +* commands for C++: Debugging C Plus Plus. + (line 6) +* commands in python: Commands In Python. (line 6) +* commands to access python: Python Commands. (line 6) +* comment: Command Syntax. (line 37) +* 'COMMON' blocks, Fortran: Special Fortran Commands. + (line 9) +* common targets: Target Commands. (line 46) +* compatibility, GDB/MI and CLI: GDB/MI Compatibility with CLI. + (line 6) +* compilation directory: Source Path. (line 106) +* compiling, on Sparclet: Sparclet. (line 16) +* completion: Completion. (line 6) +* completion of Python commands: Commands In Python. (line 70) +* completion of quoted strings: Completion. (line 57) +* completion of structure field names: Completion. (line 95) +* completion of union field names: Completion. (line 95) +* compressed debug sections: Requirements. (line 38) +* conditional breakpoints: Conditions. (line 6) +* conditional tracepoints: Tracepoint Conditions. + (line 6) +* configuring GDB: Running Configure. (line 6) +* confirmation: Messages/Warnings. (line 49) +* connection timeout, for remote TCP target: Remote Configuration. + (line 133) +* console i/o as part of file-i/o: Console I/O. (line 6) +* console interpreter: Interpreters. (line 21) +* console output in GDB/MI: GDB/MI Output Syntax. + (line 106) +* constants, in file-i/o protocol: Constants. (line 6) +* continuing: Continuing and Stepping. + (line 6) +* continuing threads: Thread Stops. (line 6) +* control C, and remote debugging: Bootstrapping. (line 25) +* controlling terminal: Input/Output. (line 23) +* convenience functions: Convenience Funs. (line 6) +* convenience functions in python: Functions In Python. + (line 6) +* convenience variables: Convenience Vars. (line 6) +* convenience variables for tracepoints: Tracepoint Variables. + (line 6) +* convenience variables, and trace state variables: Trace State Variables. + (line 17) +* convenience variables, initializing: Convenience Vars. (line 42) +* core dump file: Files. (line 6) +* core dump file target: Target Commands. (line 54) +* crash of debugger: Bug Criteria. (line 9) +* CRC algorithm definition: Separate Debug Files. + (line 136) +* CRC of memory block, remote request: General Query Packets. + (line 65) +* CRIS: CRIS. (line 6) +* CRIS mode: CRIS. (line 26) +* CRIS version: CRIS. (line 10) +* Ctrl-BREAK, MS-Windows: Cygwin Native. (line 9) +* ctrl-c message, in file-i/o protocol: The Ctrl-C Message. (line 6) +* current Ada task ID: Ada Tasks. (line 103) +* current directory: Source Path. (line 106) +* current Go package: Go. (line 11) +* current stack frame: Frames. (line 45) +* current thread: Threads. (line 39) +* current thread, remote request: General Query Packets. + (line 55) +* custom JIT debug info: Custom Debug Info. (line 6) +* Cygwin DLL, debugging: Cygwin Native. (line 42) +* Cygwin-specific commands: Cygwin Native. (line 6) +* D: D. (line 6) +* 'd' packet: Packets. (line 127) +* 'D' packet: Packets. (line 134) +* Darwin: Darwin. (line 6) +* data breakpoints: Breakpoints. (line 20) +* data manipulation, in GDB/MI: GDB/MI Data Manipulation. + (line 6) +* dcache line-size: Caching Target Data. + (line 60) +* dcache size: Caching Target Data. + (line 57) +* dead names, GNU Hurd: Hurd Native. (line 84) +* debug expression parser: Debugging Output. (line 132) +* debug formats and C++: C Plus Plus Expressions. + (line 8) +* debug link sections: Separate Debug Files. + (line 76) +* debug remote protocol: Debugging Output. (line 139) +* debugger crash: Bug Criteria. (line 9) +* debugging agent: In-Process Agent. (line 6) +* debugging C++ programs: C Plus Plus Expressions. + (line 8) +* debugging information directory, global: Separate Debug Files. + (line 6) +* debugging information in separate files: Separate Debug Files. + (line 6) +* debugging 'libthread_db': Threads. (line 209) +* debugging multiple processes: Forks. (line 51) +* debugging optimized code: Optimized Code. (line 6) +* debugging stub, example: Remote Stub. (line 6) +* debugging target: Targets. (line 6) +* debugging the Cygwin DLL: Cygwin Native. (line 42) +* decimal floating point format: Decimal Floating Point. + (line 6) +* default collection action: Tracepoint Actions. (line 134) +* default data directory: Data Files. (line 19) +* default source path substitution: Source Path. (line 88) +* default system root: Files. (line 441) +* define trace state variable, remote request: Tracepoint Packets. + (line 121) +* defining macros interactively: Macros. (line 59) +* definition of a macro, showing: Macros. (line 47) +* delete breakpoints: Delete Breaks. (line 41) +* deleting breakpoints, watchpoints, catchpoints: Delete Breaks. + (line 6) +* deliver a signal to a program: Signaling. (line 6) +* demangling C++ names: Print Settings. (line 408) +* deprecated commands: Maintenance Commands. + (line 109) +* derived type of an object, printing: Print Settings. (line 460) +* descriptor tables display: DJGPP Native. (line 24) +* detach from task, GNU Hurd: Hurd Native. (line 59) +* detach from thread, GNU Hurd: Hurd Native. (line 109) +* direct memory access (DMA) on MS-DOS: DJGPP Native. (line 74) +* directories for source files: Source Path. (line 6) +* directory, compilation: Source Path. (line 106) +* directory, current: Source Path. (line 106) +* disable address space randomization, remote request: General Query Packets. + (line 84) +* disconnected tracing: Starting and Stopping Trace Experiments. + (line 45) +* displaced stepping debugging info: Debugging Output. (line 68) +* displaced stepping support: Maintenance Commands. + (line 66) +* displaced stepping, and process record and replay: Process Record and Replay. + (line 63) +* display command history: Command History. (line 80) +* display derived types: Print Settings. (line 460) +* display disabled out of scope: Auto Display. (line 86) +* display GDB copyright: Help. (line 138) +* display of expressions: Auto Display. (line 6) +* display remote monitor communications: Target Commands. (line 101) +* display remote packets: Debugging Output. (line 139) +* DJGPP debugging: DJGPP Native. (line 6) +* DLLs with no debugging symbols: Non-debug DLL Symbols. + (line 6) +* do not print frame argument values: Print Settings. (line 154) +* documentation: Formatting Documentation. + (line 22) +* don't repeat command: Define. (line 61) +* don't repeat Python command: Commands In Python. (line 42) +* DOS file-name semantics of file names.: Files. (line 464) +* DOS serial data link, remote debugging: DJGPP Native. (line 118) +* DOS serial port status: DJGPP Native. (line 139) +* download server address (M32R): M32R/D. (line 27) +* download to Sparclet: Sparclet Download. (line 6) +* download to VxWorks: VxWorks Download. (line 6) +* DPMI: DJGPP Native. (line 6) +* dprintf: Dynamic Printf. (line 6) +* dump all data collected at tracepoint: tdump. (line 6) +* dump core from inferior: Core File Generation. + (line 6) +* dump data to a file: Dump/Restore Files. (line 6) +* dump/restore files: Dump/Restore Files. (line 6) +* DVC register: PowerPC Embedded. (line 6) +* DWARF 2 compilation units cache: Maintenance Commands. + (line 303) +* DWARF-2 CFI and CRIS: CRIS. (line 18) +* DWARF2 DIEs: Debugging Output. (line 56) +* DWARF2 Reading: Debugging Output. (line 61) +* dynamic linking: Files. (line 112) +* dynamic printf: Dynamic Printf. (line 6) +* dynamic varobj: GDB/MI Variable Objects. + (line 166) +* editing: Editing. (line 15) +* editing command lines: Readline Bare Essentials. + (line 6) +* editing source files: Edit. (line 6) +* eight-bit characters in strings: Print Settings. (line 353) +* elaboration phase: Starting. (line 90) +* ELinOS system-wide configuration script: System-wide Configuration Scripts. + (line 15) +* Emacs: Emacs. (line 6) +* empty response, for unsupported packets: Overview. (line 97) +* enable/disable a breakpoint: Disabling. (line 6) +* entering numbers: Numbers. (line 6) +* environment (of your program): Environment. (line 6) +* errno values, in file-i/o protocol: Errno Values. (line 6) +* error on valid input: Bug Criteria. (line 12) +* event debugging info: Debugging Output. (line 74) +* event designators: Event Designators. (line 6) +* event handling: Set Catchpoints. (line 6) +* examine process image: SVR4 Process Information. + (line 6) +* examining data: Data. (line 6) +* examining memory: Memory. (line 9) +* exception handlers: Set Catchpoints. (line 6) +* exceptions, python: Exception Handling. (line 6) +* executable file: Files. (line 16) +* executable file target: Target Commands. (line 50) +* executable file, for remote target: Remote Configuration. + (line 88) +* execute commands from a file: Command Files. (line 17) +* execute forward or backward in time: Reverse Execution. (line 86) +* execute remote command, remote request: General Query Packets. + (line 333) +* execution, foreground, background and asynchronous: Background Execution. + (line 6) +* exiting GDB: Quitting GDB. (line 6) +* expand macro once: Macros. (line 38) +* expanding preprocessor macros: Macros. (line 29) +* explore type: Data. (line 145) +* explore value: Data. (line 138) +* exploring hierarchical data structures: Data. (line 36) +* expression debugging info: Debugging Output. (line 79) +* expression parser, debugging info: Debugging Output. (line 132) +* expressions: Expressions. (line 6) +* expressions in Ada: Ada. (line 11) +* expressions in C or C++: C. (line 6) +* expressions in C++: C Plus Plus Expressions. + (line 6) +* expressions in Modula-2: Modula-2. (line 12) +* extend GDB for remote targets: Connecting. (line 105) +* extending GDB: Extending GDB. (line 6) +* extra signal information: Signals. (line 106) +* 'F' packet: Packets. (line 150) +* 'F' reply packet: The F Reply Packet. (line 6) +* 'F' request packet: The F Request Packet. + (line 6) +* fast tracepoints: Set Tracepoints. (line 24) +* fast tracepoints, setting: Create and Delete Tracepoints. + (line 51) +* fatal signal: Bug Criteria. (line 9) +* fatal signals: Signals. (line 15) +* features of the remote protocol: General Query Packets. + (line 386) +* file name canonicalization: Files. (line 508) +* file transfer: File Transfer. (line 6) +* file transfer, remote protocol: Host I/O Packets. (line 6) +* file-i/o examples: File-I/O Examples. (line 6) +* file-i/o overview: File-I/O Overview. (line 6) +* File-I/O remote protocol extension: File-I/O Remote Protocol Extension. + (line 6) +* file-i/o reply packet: The F Reply Packet. (line 6) +* file-i/o request packet: The F Request Packet. + (line 6) +* filename-display: Backtrace. (line 152) +* find downloadable SREC files (M32R): M32R/D. (line 15) +* find trace snapshot: tfind. (line 6) +* flinching: Messages/Warnings. (line 49) +* float promotion: ABI. (line 34) +* floating point: Floating Point Hardware. + (line 6) +* floating point registers: Registers. (line 15) +* floating point, MIPS remote: MIPS Embedded. (line 58) +* focus of debugging: Threads. (line 39) +* foo: Symbol Errors. (line 54) +* foreground execution: Background Execution. + (line 6) +* fork, debugging programs which call: Forks. (line 6) +* format options: Print Settings. (line 6) +* formatted output: Output Formats. (line 6) +* Fortran: Summary. (line 40) +* Fortran Defaults: Fortran Defaults. (line 6) +* Fortran operators and expressions: Fortran Operators. (line 6) +* Fortran-specific support in GDB: Fortran. (line 6) +* FR-V shared-library debugging: Debugging Output. (line 152) +* frame debugging info: Debugging Output. (line 85) +* frame decorator api: Frame Decorator API. + (line 6) +* frame filters api: Frame Filter API. (line 6) +* frame number: Frames. (line 28) +* frame pointer: Frames. (line 21) +* frame pointer register: Registers. (line 26) +* frame, definition: Frames. (line 6) +* frameless execution: Frames. (line 34) +* frames in python: Frames In Python. (line 6) +* free memory information (MS-DOS): DJGPP Native. (line 19) +* fstat, file-i/o system call: stat/fstat. (line 6) +* Fujitsu: Remote Stub. (line 68) +* full symbol tables, listing GDB's internal: Symbols. (line 357) +* function call arguments, optimized out: Backtrace. (line 83) +* function entry/exit, wrong values of variables: Variables. (line 106) +* functions without line info, and stepping: Continuing and Stepping. + (line 91) +* 'g' packet: Packets. (line 155) +* 'G' packet: Packets. (line 184) +* 'g++', GNU C++ compiler: C. (line 10) +* garbled pointers: DJGPP Native. (line 42) +* GCC and C++: C Plus Plus Expressions. + (line 8) +* GDB bugs, reporting: Bug Reporting. (line 6) +* GDB internal error: Maintenance Commands. + (line 143) +* gdb module: Basic Python. (line 28) +* GDB reference card: Formatting Documentation. + (line 6) +* GDB startup: Startup. (line 6) +* GDB version number: Help. (line 128) +* 'gdb.ini': Startup. (line 65) +* gdb.printing: gdb.printing. (line 6) +* gdb.prompt: gdb.prompt. (line 6) +* gdb.types: gdb.types. (line 6) +* 'gdb.Value': Values From Inferior. + (line 6) +* GDB/MI development: GDB/MI Development and Front Ends. + (line 6) +* GDB/MI General Design: GDB/MI General Design. + (line 6) +* GDB/MI, async records: GDB/MI Async Records. + (line 6) +* GDB/MI, breakpoint commands: GDB/MI Breakpoint Commands. + (line 6) +* GDB/MI, compatibility with CLI: GDB/MI Compatibility with CLI. + (line 6) +* GDB/MI, data manipulation: GDB/MI Data Manipulation. + (line 6) +* GDB/MI, input syntax: GDB/MI Input Syntax. + (line 6) +* GDB/MI, its purpose: GDB/MI. (line 9) +* GDB/MI, output syntax: GDB/MI Output Syntax. + (line 6) +* GDB/MI, result records: GDB/MI Result Records. + (line 6) +* GDB/MI, simple examples: GDB/MI Simple Examples. + (line 6) +* GDB/MI, stream records: GDB/MI Stream Records. + (line 6) +* gdbarch debugging info: Debugging Output. (line 23) +* 'GDBHISTFILE', environment variable: Command History. (line 26) +* 'gdbserver', command-line arguments: Server. (line 34) +* 'gdbserver', multiple processes: Server. (line 106) +* gdbserver, search path for 'libthread_db': Server. (line 237) +* GDT: DJGPP Native. (line 24) +* get thread information block address: General Query Packets. + (line 171) +* get thread-local storage address, remote request: General Query Packets. + (line 140) +* gettimeofday, file-i/o system call: gettimeofday. (line 6) +* getting structure elements using gdb.Field objects as subscripts: Values From Inferior. + (line 26) +* global debugging information directories: Separate Debug Files. + (line 6) +* GNU C++: C. (line 10) +* GNU Emacs: Emacs. (line 6) +* GNU Hurd debugging: Hurd Native. (line 6) +* GNU/Hurd debug messages: Debugging Output. (line 90) +* GNU/Linux LWP debug messages: Debugging Output. (line 105) +* Go (programming language): Go. (line 6) +* 'H' packet: Packets. (line 194) +* handling signals: Signals. (line 27) +* hardware breakpoints: Set Breaks. (line 60) +* hardware debug registers: Maintenance Commands. + (line 329) +* hardware watchpoints: Set Watchpoints. (line 31) +* hash mark while downloading: Target Commands. (line 92) +* 'heuristic-fence-post' (Alpha, MIPS): MIPS. (line 14) +* history events: Event Designators. (line 8) +* history expansion: History Interaction. + (line 6) +* history expansion, turn on/off: Command History. (line 55) +* history file: Command History. (line 26) +* history number: Value History. (line 13) +* history of values printed by GDB: Value History. (line 6) +* history size: Command History. (line 45) +* history substitution: Command History. (line 26) +* 'HISTSIZE', environment variable: Command History. (line 45) +* hooks, for commands: Hooks. (line 6) +* hooks, post-command: Hooks. (line 11) +* hooks, pre-command: Hooks. (line 6) +* host character set: Character Sets. (line 6) +* Host I/O, remote protocol: Host I/O Packets. (line 6) +* how many arguments (user-defined commands): Define. (line 25) +* HPPA support: HPPA. (line 6) +* 'i' packet: Packets. (line 208) +* 'I' packet: Packets. (line 213) +* i/o: Input/Output. (line 6) +* I/O registers (Atmel AVR): AVR. (line 10) +* i386: Remote Stub. (line 56) +* 'i386-stub.c': Remote Stub. (line 56) +* IDT: DJGPP Native. (line 24) +* ignore count (of breakpoint): Conditions. (line 79) +* in-process agent protocol: In-Process Agent Protocol. + (line 6) +* incomplete type: Symbols. (line 206) +* indentation in structure display: Print Settings. (line 329) +* index files: Index Files. (line 6) +* index section format: Index Section Format. + (line 6) +* inferior: Inferiors and Programs. + (line 13) +* inferior debugging info: Debugging Output. (line 94) +* inferior events in Python: Events In Python. (line 6) +* inferior functions, calling: Calling. (line 6) +* inferior tty: Input/Output. (line 44) +* inferiors in Python: Inferiors In Python. + (line 6) +* infinite recursion in user-defined commands: Define. (line 78) +* info for known .debug_gdb_scripts-loaded scripts: Maintenance Commands. + (line 239) +* info for known object files: Maintenance Commands. + (line 233) +* info proc cmdline: SVR4 Process Information. + (line 35) +* info proc cwd: SVR4 Process Information. + (line 39) +* info proc exe: SVR4 Process Information. + (line 43) +* information about static tracepoint markers: Listing Static Tracepoint Markers. + (line 6) +* information about tracepoints: Listing Tracepoints. + (line 6) +* inheritance: Debugging C Plus Plus. + (line 26) +* init file: Startup. (line 11) +* init file name: Startup. (line 65) +* initial frame: Frames. (line 12) +* initialization file, readline: Readline Init File. (line 6) +* inline functions, debugging: Inline Functions. (line 6) +* innermost frame: Frames. (line 12) +* input syntax for GDB/MI: GDB/MI Input Syntax. + (line 6) +* installation: Installing GDB. (line 6) +* instructions, assembly: Machine Code. (line 36) +* integral datatypes, in file-i/o protocol: Integral Datatypes. + (line 6) +* Intel: Remote Stub. (line 56) +* Intel disassembly flavor: Machine Code. (line 131) +* Intel(R) Memory Protection Extensions (MPX).: i386. (line 21) +* interaction, readline: Readline Interaction. + (line 6) +* internal commands: Maintenance Commands. + (line 6) +* internal errors, control of GDB behavior: Maintenance Commands. + (line 143) +* internal GDB breakpoints: Set Breaks. (line 373) +* interrupt: Quitting GDB. (line 13) +* interrupt debuggee on MS-Windows: Cygwin Native. (line 9) +* interrupt remote programs: Remote Configuration. + (line 29) +* interrupt remote programs <1>: Remote Configuration. + (line 94) +* interrupting remote programs: Connecting. (line 78) +* interrupting remote targets: Bootstrapping. (line 25) +* interrupts (remote protocol): Interrupts. (line 6) +* invalid input: Bug Criteria. (line 16) +* invoke another interpreter: Interpreters. (line 36) +* ipa protocol commands: IPA Protocol Commands. + (line 6) +* ipa protocol objects: IPA Protocol Objects. + (line 6) +* isatty, file-i/o system call: isatty. (line 6) +* JIT compilation interface: JIT Interface. (line 6) +* JIT debug info reader: Custom Debug Info. (line 6) +* just-in-time compilation: JIT Interface. (line 6) +* just-in-time compilation, debugging messages: Debugging Output. + (line 101) +* 'k' packet: Packets. (line 217) +* kernel crash dump: BSD libkvm Interface. + (line 6) +* kernel memory image: BSD libkvm Interface. + (line 6) +* kill ring: Readline Killing Commands. + (line 18) +* killing text: Readline Killing Commands. + (line 6) +* languages: Languages. (line 6) +* last tracepoint number: Create and Delete Tracepoints. + (line 123) +* latest breakpoint: Set Breaks. (line 6) +* lazy strings in python: Lazy Strings In Python. + (line 6) +* LDT: DJGPP Native. (line 24) +* leaving GDB: Quitting GDB. (line 6) +* libkvm: BSD libkvm Interface. + (line 6) +* library list format, remote protocol: Library List Format. + (line 6) +* library list format, remote protocol <1>: Library List Format for SVR4 Targets. + (line 6) +* limit hardware breakpoints and watchpoints: Remote Configuration. + (line 72) +* limit hardware watchpoints length: Remote Configuration. + (line 77) +* limit on number of printed array elements: Print Settings. (line 141) +* limits, in file-i/o protocol: Limits. (line 6) +* line tables in python: Line Tables In Python. + (line 6) +* linespec: Specify Location. (line 6) +* Linux lightweight processes: Debugging Output. (line 105) +* list active threads, remote request: General Query Packets. + (line 114) +* list of supported file-i/o calls: List of Supported Calls. + (line 6) +* list output in GDB/MI: GDB/MI Output Syntax. + (line 117) +* 'list', how many lines to display: List. (line 30) +* listing GDB's internal symbol tables: Symbols. (line 357) +* listing machine instructions: Machine Code. (line 36) +* listing mapped overlays: Overlay Commands. (line 60) +* load address, overlay's: How Overlays Work. (line 6) +* load shared library: Files. (line 325) +* load symbols from memory: Files. (line 179) +* local variables: Symbols. (line 249) +* locate address: Output Formats. (line 35) +* lock scheduler: All-Stop Mode. (line 37) +* log output in GDB/MI: GDB/MI Output Syntax. + (line 113) +* logging file name: Logging Output. (line 12) +* logging GDB output: Logging Output. (line 6) +* lseek flags, in file-i/o protocol: Lseek Flags. (line 6) +* lseek, file-i/o system call: lseek. (line 6) +* 'm' packet: Packets. (line 224) +* 'M' packet: Packets. (line 243) +* M32-EVA target board address: M32R/D. (line 21) +* M32R/Chaos debugging: M32R/D. (line 50) +* m680x0: Remote Stub. (line 59) +* 'm68k-stub.c': Remote Stub. (line 59) +* Mach-O symbols processing: Debugging Output. (line 110) +* machine instructions: Machine Code. (line 36) +* macro definition, showing: Macros. (line 47) +* macro expansion, showing the results of preprocessor: Macros. + (line 29) +* macros, example of debugging with: Macros. (line 83) +* macros, from debug info: Macros. (line 47) +* macros, user-defined: Macros. (line 59) +* mailing lists: GDB/MI Development and Front Ends. + (line 34) +* maintenance commands: Maintenance Commands. + (line 6) +* Man pages: Man Pages. (line 6) +* managing frame filters: Frame Filter Management. + (line 6) +* manual overlay debugging: Overlay Commands. (line 23) +* map an overlay: Overlay Commands. (line 30) +* mapinfo list, QNX Neutrino: SVR4 Process Information. + (line 93) +* mapped address: How Overlays Work. (line 6) +* mapped overlays: How Overlays Work. (line 6) +* markers, static tracepoints: Set Tracepoints. (line 28) +* maximum value for offset of closest symbol: Print Settings. + (line 70) +* member functions: C Plus Plus Expressions. + (line 16) +* memory address space mappings: SVR4 Process Information. + (line 47) +* memory map format: Memory Map Format. (line 6) +* memory region attributes: Memory Region Attributes. + (line 6) +* memory tracing: Breakpoints. (line 20) +* memory transfer, in file-i/o protocol: Memory Transfer. (line 6) +* memory used by commands: Maintenance Commands. + (line 382) +* memory used for symbol tables: Files. (line 313) +* memory, alignment and size of remote accesses: Packets. (line 231) +* memory, viewing as typed object: Expressions. (line 41) +* mi interpreter: Interpreters. (line 26) +* mi1 interpreter: Interpreters. (line 34) +* mi2 interpreter: Interpreters. (line 31) +* minimal language: Unsupported Languages. + (line 6) +* minimal symbol dump: Symbols. (line 339) +* Minimal symbols and DLLs: Non-debug DLL Symbols. + (line 6) +* MIPS addresses, masking: MIPS. (line 80) +* MIPS boards: MIPS Embedded. (line 6) +* MIPS remote floating point: MIPS Embedded. (line 58) +* MIPS stack: MIPS. (line 6) +* miscellaneous settings: Other Misc Settings. + (line 6) +* MMX registers (x86): Registers. (line 71) +* mode_t values, in file-i/o protocol: mode_t Values. (line 6) +* Modula-2: Summary. (line 29) +* Modula-2 built-ins: Built-In Func/Proc. (line 6) +* Modula-2 checks: M2 Checks. (line 6) +* Modula-2 constants: Built-In Func/Proc. (line 111) +* Modula-2 defaults: M2 Defaults. (line 6) +* Modula-2 operators: M2 Operators. (line 6) +* Modula-2 types: M2 Types. (line 6) +* Modula-2, deviations from: Deviations. (line 6) +* Modula-2, GDB support: Modula-2. (line 6) +* monitor commands, for 'gdbserver': Server. (line 220) +* Motorola 680x0: Remote Stub. (line 59) +* MS Windows debugging: Cygwin Native. (line 6) +* MS-DOS system info: DJGPP Native. (line 19) +* MS-DOS-specific commands: DJGPP Native. (line 6) +* multiple locations, breakpoints: Set Breaks. (line 192) +* multiple processes: Forks. (line 6) +* multiple processes with 'gdbserver': Server. (line 106) +* multiple targets: Active Targets. (line 6) +* multiple threads: Threads. (line 6) +* multiple threads, backtrace: Backtrace. (line 49) +* multiple-symbols menu: Ambiguous Expressions. + (line 51) +* multiprocess extensions, in remote protocol: General Query Packets. + (line 652) +* name a thread: Threads. (line 125) +* names of symbols: Symbols. (line 14) +* namespace in C++: C Plus Plus Expressions. + (line 20) +* native Cygwin debugging: Cygwin Native. (line 6) +* native DJGPP debugging: DJGPP Native. (line 6) +* native script auto-loading: Auto-loading sequences. + (line 6) +* negative breakpoint numbers: Set Breaks. (line 373) +* 'New' SYSTAG message: Threads. (line 45) +* Newlib OS ABI and its influence on the longjmp handling: ABI. + (line 11) +* Nios II architecture: Nios II. (line 6) +* non-member C++ functions, set breakpoint in: Set Breaks. (line 105) +* non-stop mode: Non-Stop Mode. (line 6) +* non-stop mode, and 'breakpoint always-inserted': Set Breaks. + (line 329) +* non-stop mode, and process record and replay: Process Record and Replay. + (line 68) +* non-stop mode, and 'set displaced-stepping': Maintenance Commands. + (line 83) +* non-stop mode, remote request: General Query Packets. + (line 247) +* noninvasive task options: Hurd Native. (line 72) +* notation, readline: Readline Bare Essentials. + (line 6) +* notational conventions, for GDB/MI: GDB/MI. (line 25) +* notification packets: Notification Packets. + (line 6) +* notify output in GDB/MI: GDB/MI Output Syntax. + (line 102) +* NULL elements in arrays: Print Settings. (line 320) +* number of array elements to print: Print Settings. (line 141) +* number representation: Numbers. (line 6) +* numbers for breakpoints: Breakpoints. (line 41) +* object files, relocatable, reading symbols from: Files. (line 132) +* Objective-C: Objective-C. (line 6) +* Objective-C, classes and selectors: Symbols. (line 309) +* Objective-C, print objects: The Print Command with Objective-C. + (line 6) +* 'OBJFILE-gdb.gdb': objfile-gdbdotext file. + (line 6) +* 'OBJFILE-gdb.py': objfile-gdbdotext file. + (line 6) +* 'OBJFILE-gdb.scm': objfile-gdbdotext file. + (line 6) +* objfiles in python: Objfiles In Python. (line 6) +* observer debugging info: Debugging Output. (line 122) +* octal escapes in strings: Print Settings. (line 353) +* online documentation: Help. (line 6) +* opaque data types: Symbols. (line 321) +* open flags, in file-i/o protocol: Open Flags. (line 6) +* open, file-i/o system call: open. (line 6) +* OpenCL C: OpenCL C. (line 6) +* OpenCL C Datatypes: OpenCL C Datatypes. (line 6) +* OpenCL C Expressions: OpenCL C Expressions. + (line 6) +* OpenCL C Operators: OpenCL C Operators. (line 6) +* operating system information: Operating System Information. + (line 6) +* operating system information, process list: Process list. (line 6) +* optimized code, debugging: Optimized Code. (line 6) +* optimized code, wrong values of variables: Variables. (line 106) +* optimized out value in Python: Values From Inferior. + (line 56) +* optimized out, in backtrace: Backtrace. (line 83) +* optional debugging messages: Debugging Output. (line 6) +* optional warnings: Messages/Warnings. (line 6) +* OS ABI: ABI. (line 11) +* OS information: OS Information. (line 6) +* out-of-line single-stepping: Maintenance Commands. + (line 66) +* outermost frame: Frames. (line 12) +* output formats: Output Formats. (line 6) +* output syntax of GDB/MI: GDB/MI Output Syntax. + (line 6) +* overlay area: How Overlays Work. (line 6) +* overlay example program: Overlay Sample Program. + (line 6) +* overlays: Overlays. (line 6) +* overlays, setting breakpoints in: Overlay Commands. (line 91) +* overloaded functions, calling: C Plus Plus Expressions. + (line 26) +* overloaded functions, overload resolution: Debugging C Plus Plus. + (line 55) +* overloading in C++: Debugging C Plus Plus. + (line 15) +* 'p' packet: Packets. (line 255) +* 'P' packet: Packets. (line 268) +* packet acknowledgment, for GDB remote: Packet Acknowledgment. + (line 6) +* packet size, remote protocol: General Query Packets. + (line 562) +* packets, notification: Notification Packets. + (line 6) +* packets, reporting on stdout: Debugging Output. (line 139) +* packets, tracepoint: Tracepoint Packets. (line 6) +* page tables display (MS-DOS): DJGPP Native. (line 55) +* parameters in python: Parameters In Python. + (line 6) +* partial symbol dump: Symbols. (line 339) +* partial symbol tables, listing GDB's internal: Symbols. (line 357) +* Pascal: Summary. (line 35) +* Pascal objects, static members display: Print Settings. (line 489) +* Pascal support in GDB, limitations: Pascal. (line 6) +* pass signals to inferior, remote request: General Query Packets. + (line 267) +* patching binaries: Patching. (line 6) +* patching object files: Files. (line 26) +* pause current task (GNU Hurd): Hurd Native. (line 48) +* pause current thread (GNU Hurd): Hurd Native. (line 90) +* pauses in output: Screen Size. (line 6) +* pending breakpoints: Set Breaks. (line 236) +* physical address from linear address: DJGPP Native. (line 80) +* physname: Debugging Output. (line 41) +* pipe, 'target remote' to: Connecting. (line 61) +* pipes: Starting. (line 62) +* pointer values, in file-i/o protocol: Pointer Values. (line 6) +* pointer, finding referent: Print Settings. (line 80) +* port rights, GNU Hurd: Hurd Native. (line 84) +* port sets, GNU Hurd: Hurd Native. (line 84) +* PowerPC architecture: PowerPC. (line 6) +* prefix for data files: Data Files. (line 6) +* prefix for shared library file names: Files. (line 381) +* premature return from system calls: Interrupted System Calls. + (line 6) +* preprocessor macro expansion, showing the results of: Macros. + (line 29) +* pretty print arrays: Print Settings. (line 115) +* pretty print C++ virtual function tables: Print Settings. (line 500) +* pretty-printer commands: Pretty-Printer Commands. + (line 6) +* print all frame argument values: Print Settings. (line 154) +* print an Objective-C object description: The Print Command with Objective-C. + (line 11) +* print array indexes: Print Settings. (line 125) +* print frame argument values for scalars only: Print Settings. + (line 154) +* print list of auto-loaded canned sequences of commands scripts: Auto-loading sequences. + (line 21) +* print list of auto-loaded Python scripts: Python Auto-loading. + (line 23) +* print messages on inferior start and exit: Inferiors and Programs. + (line 117) +* print messages on thread start and exit: Threads. (line 150) +* print settings: Print Settings. (line 6) +* print structures in indented form: Print Settings. (line 329) +* print/don't print memory addresses: Print Settings. (line 13) +* printing byte arrays: Output Formats. (line 60) +* printing data: Data. (line 6) +* printing frame argument values: Print Settings. (line 154) +* printing strings: Output Formats. (line 60) +* probe static tracepoint marker: Create and Delete Tracepoints. + (line 76) +* probing markers, static tracepoints: Set Tracepoints. (line 28) +* process detailed status information: SVR4 Process Information. + (line 55) +* process ID: SVR4 Process Information. + (line 19) +* process info via '/proc': SVR4 Process Information. + (line 6) +* process list, QNX Neutrino: SVR4 Process Information. + (line 89) +* process record and replay: Process Record and Replay. + (line 6) +* process status register: Registers. (line 26) +* processes, multiple: Forks. (line 6) +* 'procfs' API calls: SVR4 Process Information. + (line 68) +* profiling GDB: Maintenance Commands. + (line 313) +* program counter register: Registers. (line 26) +* program entry point: Backtrace. (line 105) +* programming in python: Python API. (line 6) +* progspaces in python: Progspaces In Python. + (line 6) +* prompt: Prompt. (line 6) +* protocol basics, file-i/o: Protocol Basics. (line 6) +* protocol, GDB remote serial: Overview. (line 14) +* protocol-specific representation of datatypes, in file-i/o protocol: Protocol-specific Representation of Datatypes. + (line 6) +* python api: Python API. (line 6) +* Python architectures: Architectures In Python. + (line 6) +* Python auto-loading: Python Auto-loading. + (line 6) +* python commands: Python Commands. (line 6) +* python commands <1>: Commands In Python. (line 6) +* python convenience functions: Functions In Python. + (line 6) +* python directory: Python. (line 10) +* python exceptions: Exception Handling. (line 6) +* python finish breakpoints: Finish Breakpoints in Python. + (line 6) +* python functions: Basic Python. (line 28) +* python module: Basic Python. (line 28) +* python modules: Python modules. (line 6) +* python pagination: Basic Python. (line 6) +* python parameters: Parameters In Python. + (line 6) +* python scripting: Python. (line 6) +* python stdout: Basic Python. (line 6) +* Python, working with types: Types In Python. (line 6) +* python, working with values from inferior: Values From Inferior. + (line 6) +* 'q' packet: Packets. (line 280) +* 'Q' packet: Packets. (line 280) +* 'QAllow' packet: General Query Packets. + (line 44) +* 'qAttached' packet: General Query Packets. + (line 1069) +* 'qC' packet: General Query Packets. + (line 55) +* 'qCRC' packet: General Query Packets. + (line 65) +* 'QDisableRandomization' packet: General Query Packets. + (line 84) +* 'qfThreadInfo' packet: General Query Packets. + (line 114) +* 'qGetTIBAddr' packet: General Query Packets. + (line 171) +* 'qGetTLSAddr' packet: General Query Packets. + (line 140) +* 'QNonStop' packet: General Query Packets. + (line 247) +* 'qOffsets' packet: General Query Packets. + (line 210) +* 'qP' packet: General Query Packets. + (line 237) +* 'QPassSignals' packet: General Query Packets. + (line 267) +* 'QProgramSignals' packet: General Query Packets. + (line 295) +* 'qRcmd' packet: General Query Packets. + (line 333) +* 'qSearch memory' packet: General Query Packets. + (line 355) +* 'QStartNoAckMode' packet: General Query Packets. + (line 372) +* 'qsThreadInfo' packet: General Query Packets. + (line 114) +* 'qSupported' packet: General Query Packets. + (line 386) +* 'qSymbol' packet: General Query Packets. + (line 732) +* 'qTBuffer' packet: Tracepoint Packets. (line 388) +* 'QTBuffer size' packet: Tracepoint Packets. (line 401) +* 'QTDisable' packet: Tracepoint Packets. (line 205) +* 'QTDisconnected' packet: Tracepoint Packets. (line 224) +* 'QTDP' packet: Tracepoint Packets. (line 10) +* 'QTDPsrc' packet: Tracepoint Packets. (line 90) +* 'QTDV' packet: Tracepoint Packets. (line 121) +* 'QTEnable' packet: Tracepoint Packets. (line 200) +* 'qTfP' packet: Tracepoint Packets. (line 331) +* 'QTFrame' packet: Tracepoint Packets. (line 129) +* 'qTfSTM' packet: Tracepoint Packets. (line 348) +* 'qTfV' packet: Tracepoint Packets. (line 339) +* 'qThreadExtraInfo' packet: General Query Packets. + (line 775) +* 'QTinit' packet: Tracepoint Packets. (line 210) +* 'qTMinFTPILen' packet: Tracepoint Packets. (line 167) +* 'QTNotes' packet: Tracepoint Packets. (line 406) +* 'qTP' packet: Tracepoint Packets. (line 303) +* 'QTro' packet: Tracepoint Packets. (line 213) +* 'QTSave' packet: Tracepoint Packets. (line 382) +* 'qTsP' packet: Tracepoint Packets. (line 332) +* 'qTsSTM' packet: Tracepoint Packets. (line 348) +* 'QTStart' packet: Tracepoint Packets. (line 191) +* 'qTStatus' packet: Tracepoint Packets. (line 230) +* 'qTSTMat' packet: Tracepoint Packets. (line 376) +* 'QTStop' packet: Tracepoint Packets. (line 197) +* 'qTsV' packet: Tracepoint Packets. (line 340) +* 'qTV' packet: Tracepoint Packets. (line 314) +* query attached, remote request: General Query Packets. + (line 1069) +* quotes in commands: Completion. (line 57) +* quoting Ada internal identifiers: Additions to Ada. (line 76) +* quoting names: Symbols. (line 14) +* 'qXfer' packet: General Query Packets. + (line 812) +* 'r' packet: Packets. (line 284) +* 'R' packet: Packets. (line 289) +* range checking: Type Checking. (line 45) +* range stepping: Continuing and Stepping. + (line 209) +* ranged breakpoint: PowerPC Embedded. (line 33) +* ranges of breakpoints: Breakpoints. (line 48) +* Ravenscar Profile: Ravenscar Profile. (line 6) +* raw printing: Output Formats. (line 76) +* RDI heartbeat: ARM. (line 107) +* read special object, remote request: General Query Packets. + (line 812) +* read, file-i/o system call: read. (line 6) +* read-only sections: Files. (line 261) +* reading symbols from relocatable object files: Files. (line 132) +* reading symbols immediately: Files. (line 89) +* readline: Editing. (line 6) +* receive rights, GNU Hurd: Hurd Native. (line 84) +* recent tracepoint number: Create and Delete Tracepoints. + (line 123) +* record aggregates (Ada): Omissions from Ada. (line 44) +* record mode: Process Record and Replay. + (line 19) +* record serial communications on file: Remote Configuration. + (line 57) +* recording a session script: Bug Reporting. (line 108) +* recording inferior's execution and replaying it: Process Record and Replay. + (line 6) +* redirection: Input/Output. (line 6) +* reference card: Formatting Documentation. + (line 6) +* reference declarations: C Plus Plus Expressions. + (line 50) +* register packet format, MIPS: MIPS Register packet Format. + (line 6) +* registers: Registers. (line 6) +* regular expression: Set Breaks. (line 89) +* reloading the overlay table: Overlay Commands. (line 52) +* relocatable object files, reading symbols from: Files. (line 132) +* remote async notification debugging info: Debugging Output. + (line 116) +* remote connection without stubs: Server. (line 6) +* remote debugging: Remote Debugging. (line 6) +* remote memory comparison: Memory. (line 119) +* remote monitor prompt: MIPS Embedded. (line 105) +* remote packets, enabling and disabling: Remote Configuration. + (line 145) +* remote programs, interrupting: Connecting. (line 78) +* remote protocol debugging: Debugging Output. (line 139) +* remote protocol, binary data: Overview. (line 63) +* remote protocol, field separator: Overview. (line 55) +* remote query requests: General Query Packets. + (line 6) +* remote serial debugging summary: Debug Session. (line 6) +* remote serial debugging, overview: Remote Stub. (line 14) +* remote serial protocol: Overview. (line 14) +* remote serial stub: Stub Contents. (line 6) +* remote serial stub list: Remote Stub. (line 53) +* remote serial stub, initialization: Stub Contents. (line 10) +* remote serial stub, main routine: Stub Contents. (line 15) +* remote stub, example: Remote Stub. (line 6) +* remote stub, support routines: Bootstrapping. (line 6) +* remote target: Target Commands. (line 58) +* remote target, file transfer: File Transfer. (line 6) +* remote target, limit break- and watchpoints: Remote Configuration. + (line 72) +* remote target, limit watchpoints length: Remote Configuration. + (line 77) +* remote timeout: Remote Configuration. + (line 65) +* remove actions from a tracepoint: Tracepoint Actions. (line 21) +* rename, file-i/o system call: rename. (line 6) +* Renesas: Remote Stub. (line 62) +* repeated array elements: Print Settings. (line 307) +* repeating command sequences: Command Syntax. (line 41) +* repeating commands: Command Syntax. (line 21) +* replay log events, remote reply: Stop Reply Packets. (line 61) +* replay mode: Process Record and Replay. + (line 10) +* reporting bugs in GDB: GDB Bugs. (line 6) +* reprint the last value: Data. (line 23) +* reset SDI connection, M32R: M32R/D. (line 44) +* resources used by commands: Maintenance Commands. + (line 345) +* response time, MIPS debugging: MIPS. (line 10) +* restart: Checkpoint/Restart. (line 6) +* restore data from a file: Dump/Restore Files. (line 6) +* restrictions on Go expressions: Go. (line 35) +* result records in GDB/MI: GDB/MI Result Records. + (line 6) +* resume threads of multiple processes simultaneously: All-Stop Mode. + (line 53) +* resuming execution: Continuing and Stepping. + (line 6) +* 'retransmit-timeout', MIPS protocol: MIPS Embedded. (line 81) +* returning from a function: Returning. (line 6) +* reverse execution: Reverse Execution. (line 6) +* rewind program state: Checkpoint/Restart. (line 6) +* ROM at zero address, RDI: ARM. (line 97) +* run to main procedure: Starting. (line 79) +* run until specified location: Continuing and Stepping. + (line 116) +* running: Starting. (line 6) +* running and debugging Sparclet programs: Sparclet Execution. + (line 6) +* running programs backward: Reverse Execution. (line 6) +* running VxWorks tasks: VxWorks Attach. (line 6) +* running, on Sparclet: Sparclet. (line 28) +* 's' packet: Packets. (line 296) +* 'S' packet: Packets. (line 305) +* save breakpoints to a file for future sessions: Save Breakpoints. + (line 9) +* save command history: Command History. (line 36) +* save GDB output to a file: Logging Output. (line 6) +* save tracepoints for future sessions: save tracepoints. (line 6) +* scheduler locking mode: All-Stop Mode. (line 37) +* scope: M2 Scope. (line 6) +* scripting commands: Command Files. (line 6) +* scripting with python: Python. (line 6) +* SDS protocol: PowerPC Embedded. (line 82) +* search for a thread: Threads. (line 136) +* search path for 'libthread_db': Threads. (line 171) +* searching memory: Searching Memory. (line 6) +* searching memory, in remote debugging: General Query Packets. + (line 355) +* searching source files: Search. (line 6) +* section offsets, remote request: General Query Packets. + (line 210) +* segment descriptor tables: DJGPP Native. (line 24) +* select Ctrl-C, BREAK or BREAK-g: Remote Configuration. + (line 94) +* select trace snapshot: tfind. (line 6) +* selected frame: Stack. (line 19) +* selecting frame silently: Frames. (line 51) +* semaphores on static probe points: Static Probe Points. + (line 19) +* send command to remote monitor: Connecting. (line 105) +* send command to simulator: Embedded Processors. + (line 9) +* send interrupt-sequence on start: Remote Configuration. + (line 107) +* send PMON command: MIPS Embedded. (line 128) +* send rights, GNU Hurd: Hurd Native. (line 84) +* sending files to remote systems: File Transfer. (line 6) +* separate debug sections: MiniDebugInfo. (line 6) +* separate debugging information files: Separate Debug Files. + (line 6) +* sequence-id, for GDB remote: Overview. (line 30) +* serial connections, debugging: Debugging Output. (line 139) +* serial line, 'target remote': Connecting. (line 18) +* serial protocol, GDB remote: Overview. (line 14) +* server prefix: Server Prefix. (line 6) +* 'server', command prefix: Command History. (line 20) +* set ABI for MIPS: MIPS. (line 32) +* set breakpoints in many functions: Set Breaks. (line 89) +* set breakpoints on all functions: Set Breaks. (line 109) +* set fast tracepoint: Create and Delete Tracepoints. + (line 51) +* set inferior controlling terminal: Input/Output. (line 44) +* set static tracepoint: Create and Delete Tracepoints. + (line 76) +* set tdesc filename: Retrieving Descriptions. + (line 18) +* set tracepoint: Create and Delete Tracepoints. + (line 6) +* setting variables: Assignment. (line 6) +* setting watchpoints: Set Watchpoints. (line 6) +* SH: Remote Stub. (line 62) +* 'sh-stub.c': Remote Stub. (line 62) +* shared libraries: Files. (line 283) +* shared library events, remote reply: Stop Reply Packets. (line 56) +* shell escape: Shell Commands. (line 10) +* show all convenience functions: Convenience Funs. (line 84) +* show all user variables and functions: Convenience Vars. (line 37) +* show last commands: Command History. (line 80) +* show tdesc filename: Retrieving Descriptions. + (line 25) +* signals: Signals. (line 6) +* signals the inferior may see, remote request: General Query Packets. + (line 295) +* 'SIGQUIT' signal, dump core of GDB: Maintenance Commands. + (line 118) +* simulator, Z8000: Z8000. (line 6) +* size of remote memory accesses: Packets. (line 231) +* size of screen: Screen Size. (line 6) +* skipping over functions and files: Skipping Over Functions and Files. + (line 6) +* snapshot of a process: Checkpoint/Restart. (line 6) +* software watchpoints: Set Watchpoints. (line 31) +* source file and line of a symbol: Print Settings. (line 50) +* source line and its code address: Machine Code. (line 6) +* source path: Source Path. (line 6) +* Sparc: Remote Stub. (line 65) +* 'sparc-stub.c': Remote Stub. (line 65) +* 'sparcl-stub.c': Remote Stub. (line 68) +* Sparclet: Sparclet. (line 6) +* SparcLite: Remote Stub. (line 68) +* Special Fortran commands: Special Fortran Commands. + (line 6) +* specifying location: Specify Location. (line 6) +* SPU: SPU. (line 6) +* SSE registers (x86): Registers. (line 71) +* stack frame: Frames. (line 6) +* stack on Alpha: MIPS. (line 6) +* stack on MIPS: MIPS. (line 6) +* stack pointer register: Registers. (line 26) +* stacking targets: Active Targets. (line 6) +* standard registers: Registers. (line 26) +* start a new trace experiment: Starting and Stopping Trace Experiments. + (line 6) +* starting: Starting. (line 6) +* startup code, and backtrace: Backtrace. (line 105) +* stat, file-i/o system call: stat/fstat. (line 6) +* static members of C++ objects: Print Settings. (line 478) +* static members of Pascal objects: Print Settings. (line 489) +* static probe point, SystemTap: Static Probe Points. + (line 6) +* static tracepoints: Set Tracepoints. (line 28) +* static tracepoints, in remote protocol: General Query Packets. + (line 700) +* static tracepoints, setting: Create and Delete Tracepoints. + (line 76) +* status of trace data collection: Starting and Stopping Trace Experiments. + (line 27) +* status output in GDB/MI: GDB/MI Output Syntax. + (line 94) +* stepping: Continuing and Stepping. + (line 6) +* stepping into functions with no line info: Continuing and Stepping. + (line 91) +* stop a running trace experiment: Starting and Stopping Trace Experiments. + (line 16) +* stop on C++ exceptions: Set Catchpoints. (line 16) +* stop reply packets: Stop Reply Packets. (line 6) +* stopped threads: Thread Stops. (line 6) +* stream records in GDB/MI: GDB/MI Stream Records. + (line 6) +* string tracing, in remote protocol: General Query Packets. + (line 717) +* 'struct gdb_reader_funcs': Writing JIT Debug Info Readers. + (line 22) +* 'struct gdb_symbol_callbacks': Writing JIT Debug Info Readers. + (line 43) +* 'struct gdb_unwind_callbacks': Writing JIT Debug Info Readers. + (line 43) +* struct return convention: i386. (line 7) +* struct stat, in file-i/o protocol: struct stat. (line 6) +* struct timeval, in file-i/o protocol: struct timeval. (line 6) +* struct/union returned in registers: i386. (line 7) +* structure field name completion: Completion. (line 95) +* stub example, remote debugging: Remote Stub. (line 6) +* stupid questions: Messages/Warnings. (line 49) +* Super-H: Super-H. (line 6) +* supported GDB/MI features, list: GDB/MI Support Commands. + (line 57) +* supported packets, remote query: General Query Packets. + (line 386) +* switching threads: Threads. (line 6) +* switching threads automatically: All-Stop Mode. (line 28) +* symbol decoding style, C++: Print Settings. (line 427) +* symbol dump: Symbols. (line 339) +* symbol file functions: Debugging Output. (line 157) +* symbol from address: Symbols. (line 84) +* symbol lookup, remote request: General Query Packets. + (line 732) +* symbol names: Symbols. (line 14) +* symbol table: Files. (line 6) +* symbol table creation: Debugging Output. (line 162) +* symbol tables in python: Symbol Tables In Python. + (line 6) +* symbol tables, listing GDB's internal: Symbols. (line 357) +* symbol, source file and line: Print Settings. (line 50) +* symbols in python: Symbols In Python. (line 6) +* symbols, reading from relocatable object files: Files. (line 132) +* symbols, reading immediately: Files. (line 89) +* synchronize with remote MIPS target: MIPS Embedded. (line 96) +* 'syscall DSO': Files. (line 179) +* system calls and thread breakpoints: Interrupted System Calls. + (line 6) +* system root, alternate: Files. (line 381) +* system, file-i/o system call: system. (line 6) +* system-wide configuration scripts: System-wide Configuration Scripts. + (line 6) +* system-wide init file: System-wide configuration. + (line 6) +* 't' packet: Packets. (line 315) +* 'T' packet: Packets. (line 320) +* 'T' packet reply: Stop Reply Packets. (line 22) +* tail call frames, debugging: Tail Call Frames. (line 6) +* target architecture: Targets. (line 17) +* target byte order: Byte Order. (line 6) +* target character set: Character Sets. (line 6) +* target debugging info: Debugging Output. (line 169) +* target descriptions: Target Descriptions. + (line 6) +* target descriptions, AArch64 features: AArch64 Features. (line 6) +* target descriptions, ARM features: ARM Features. (line 6) +* target descriptions, i386 features: i386 Features. (line 6) +* target descriptions, inclusion: Target Description Format. + (line 53) +* target descriptions, M68K features: M68K Features. (line 6) +* target descriptions, MIPS features: MIPS Features. (line 6) +* target descriptions, Nios II features: Nios II Features. (line 6) +* target descriptions, PowerPC features: PowerPC Features. (line 6) +* target descriptions, predefined types: Predefined Target Types. + (line 6) +* target descriptions, S/390 features: S/390 and System z Features. + (line 6) +* target descriptions, standard features: Standard Target Features. + (line 6) +* target descriptions, System z features: S/390 and System z Features. + (line 6) +* target descriptions, TIC6x features: TIC6x Features. (line 6) +* target descriptions, TMS320C6x features: TIC6x Features. (line 6) +* target descriptions, XML format: Target Description Format. + (line 6) +* target output in GDB/MI: GDB/MI Output Syntax. + (line 110) +* 'target remote': Connecting. (line 11) +* target stack description: Maintenance Commands. + (line 259) +* target-assisted range stepping: Continuing and Stepping. + (line 209) +* task attributes (GNU Hurd): Hurd Native. (line 48) +* task breakpoints, in Ada: Ada Tasks. (line 133) +* task exception port, GNU Hurd: Hurd Native. (line 67) +* task suspend count: Hurd Native. (line 59) +* task switching with program using Ravenscar Profile: Ravenscar Profile. + (line 10) +* TCP port, 'target remote': Connecting. (line 29) +* terminal: Input/Output. (line 6) +* Text User Interface: TUI. (line 6) +* thread attributes info, remote request: General Query Packets. + (line 775) +* thread breakpoints: Thread-Specific Breakpoints. + (line 10) +* thread breakpoints and system calls: Interrupted System Calls. + (line 6) +* thread default settings, GNU Hurd: Hurd Native. (line 130) +* thread identifier (GDB): Threads. (line 57) +* thread identifier (system): Threads. (line 45) +* thread info (Solaris): Threads. (line 92) +* thread information, remote request: General Query Packets. + (line 237) +* thread list format: Thread List Format. (line 6) +* thread number: Threads. (line 57) +* thread properties, GNU Hurd: Hurd Native. (line 90) +* thread suspend count, GNU Hurd: Hurd Native. (line 109) +* THREAD-ID, in remote protocol: Packets. (line 20) +* threads and watchpoints: Set Watchpoints. (line 179) +* threads in python: Threads In Python. (line 6) +* threads of execution: Threads. (line 6) +* threads, automatic switching: All-Stop Mode. (line 28) +* threads, continuing: Thread Stops. (line 6) +* threads, stopped: Thread Stops. (line 6) +* time of command execution: Maintenance Commands. + (line 386) +* timeout for commands: Maintenance Commands. + (line 407) +* timeout for serial communications: Remote Configuration. + (line 65) +* timeout, for remote target connection: Remote Configuration. + (line 133) +* 'timeout', MIPS protocol: MIPS Embedded. (line 81) +* timestampping debugging info: Debugging Output. (line 178) +* trace experiment, status of: Starting and Stopping Trace Experiments. + (line 27) +* trace file format: Trace File Format. (line 6) +* trace files: Trace Files. (line 6) +* trace state variable value, remote request: Tracepoint Packets. + (line 314) +* trace state variables: Trace State Variables. + (line 6) +* traceback: Backtrace. (line 6) +* traceframe info format: Traceframe Info Format. + (line 6) +* tracepoint actions: Tracepoint Actions. (line 6) +* tracepoint conditions: Tracepoint Conditions. + (line 6) +* tracepoint data, display: tdump. (line 6) +* tracepoint deletion: Create and Delete Tracepoints. + (line 126) +* tracepoint number: Create and Delete Tracepoints. + (line 123) +* tracepoint packets: Tracepoint Packets. (line 6) +* tracepoint pass count: Tracepoint Passcounts. + (line 6) +* tracepoint restrictions: Tracepoint Restrictions. + (line 6) +* tracepoint status, remote request: Tracepoint Packets. (line 303) +* tracepoint variables: Tracepoint Variables. + (line 6) +* tracepoints: Tracepoints. (line 6) +* tracepoints support in 'gdbserver': Server. (line 255) +* trailing underscore, in Fortran symbols: Fortran. (line 9) +* translating between character sets: Character Sets. (line 6) +* TUI: TUI. (line 6) +* TUI commands: TUI Commands. (line 6) +* TUI configuration variables: TUI Configuration. (line 6) +* TUI key bindings: TUI Keys. (line 6) +* TUI single key mode: TUI Single Key Mode. + (line 6) +* type casting memory: Expressions. (line 41) +* type chain of a data type: Maintenance Commands. + (line 271) +* type checking: Checks. (line 24) +* type conversions in C++: C Plus Plus Expressions. + (line 26) +* type printer: Type Printing API. (line 9) +* type printing API for Python: Type Printing API. (line 6) +* types in Python: Types In Python. (line 6) +* UDP port, 'target remote': Connecting. (line 50) +* union field name completion: Completion. (line 95) +* unions in structures, printing: Print Settings. (line 367) +* unknown address, locating: Output Formats. (line 35) +* unlink, file-i/o system call: unlink. (line 6) +* unlinked object files: Files. (line 26) +* unload symbols from shared libraries: Files. (line 343) +* unmap an overlay: Overlay Commands. (line 39) +* unmapped overlays: How Overlays Work. (line 6) +* unset tdesc filename: Retrieving Descriptions. + (line 21) +* unsupported languages: Unsupported Languages. + (line 6) +* unwind stack in called functions: Calling. (line 35) +* unwind stack in called functions with unhandled exceptions: Calling. + (line 46) +* use only software watchpoints: Set Watchpoints. (line 108) +* user-defined command: Define. (line 6) +* user-defined macros: Macros. (line 59) +* user-defined variables: Convenience Vars. (line 6) +* value history: Value History. (line 6) +* values from inferior, with Python: Values From Inferior. + (line 6) +* variable name conflict: Variables. (line 36) +* variable object debugging info: Debugging Output. (line 185) +* variable objects in GDB/MI: GDB/MI Variable Objects. + (line 9) +* variable values, wrong: Variables. (line 106) +* variables, readline: Readline Init File Syntax. + (line 34) +* variables, setting: Assignment. (line 16) +* 'vAttach' packet: Packets. (line 334) +* 'vCont' packet: Packets. (line 352) +* 'vCont?' packet: Packets. (line 411) +* vector unit: Vector Unit. (line 6) +* vector, auxiliary: OS Information. (line 9) +* verbose operation: Messages/Warnings. (line 6) +* verify remote memory image: Memory. (line 119) +* 'vFile' packet: Packets. (line 421) +* 'vFlashDone' packet: Packets. (line 460) +* 'vFlashErase' packet: Packets. (line 425) +* 'vFlashWrite' packet: Packets. (line 440) +* virtual functions (C++) display: Print Settings. (line 500) +* 'vKill' packet: Packets. (line 467) +* volatile registers: Registers. (line 101) +* 'vRun' packet: Packets. (line 479) +* 'vStopped' packet: Packets. (line 494) +* VTBL display: Print Settings. (line 500) +* VxWorks: VxWorks. (line 6) +* watchdog timer: Maintenance Commands. + (line 407) +* watchpoints: Breakpoints. (line 20) +* watchpoints and threads: Set Watchpoints. (line 179) +* weak alias functions: Calling. (line 57) +* where to look for shared libraries: Files. (line 376) +* wild pointer, interpreting: Print Settings. (line 80) +* Wind River Linux system-wide configuration script: System-wide Configuration Scripts. + (line 22) +* word completion: Completion. (line 6) +* working directory: Source Path. (line 106) +* working directory (of your program): Working Directory. (line 6) +* working language: Languages. (line 13) +* write data into object, remote request: General Query Packets. + (line 1016) +* write, file-i/o system call: write. (line 6) +* writing a frame filter: Writing a Frame Filter. + (line 6) +* writing a pretty-printer: Writing a Pretty-Printer. + (line 6) +* writing convenience functions: Functions In Python. + (line 6) +* writing into corefiles: Patching. (line 6) +* writing into executables: Patching. (line 6) +* writing JIT debug info readers: Writing JIT Debug Info Readers. + (line 6) +* wrong values: Variables. (line 106) +* 'x' command, default address: Machine Code. (line 30) +* 'X' packet: Packets. (line 497) +* Xilinx MicroBlaze: MicroBlaze. (line 6) +* XInclude: Target Description Format. + (line 53) +* XMD, Xilinx Microprocessor Debugger: MicroBlaze. (line 6) +* XML parser debugging: Debugging Output. (line 191) +* yanking text: Readline Killing Commands. + (line 6) +* 'z' packet: Packets. (line 509) +* 'Z' packets: Packets. (line 509) +* 'z0' packet: Packets. (line 524) +* 'Z0' packet: Packets. (line 524) +* 'z1' packet: Packets. (line 575) +* 'Z1' packet: Packets. (line 575) +* 'z2' packet: Packets. (line 595) +* 'Z2' packet: Packets. (line 595) +* 'z3' packet: Packets. (line 608) +* 'Z3' packet: Packets. (line 608) +* 'z4' packet: Packets. (line 621) +* 'Z4' packet: Packets. (line 621) +* Z8000: Z8000. (line 6) +* Zilog Z8000 simulator: Z8000. (line 6) + + +File: gdb.info, Node: Command and Variable Index, Prev: Concept Index, Up: Top + +Command, Variable, and Function Index +************************************* + +[index] +* Menu: + +* !: Shell Commands. (line 10) +* # (a comment): Command Syntax. (line 37) +* $bpnum, convenience variable: Set Breaks. (line 6) +* $cdir, convenience variable: Source Path. (line 106) +* $cwd, convenience variable: Source Path. (line 106) +* $tpnum: Create and Delete Tracepoints. + (line 123) +* $tracepoint: Tracepoint Variables. + (line 10) +* $trace_file: Tracepoint Variables. + (line 16) +* $trace_frame: Tracepoint Variables. + (line 6) +* $trace_func: Tracepoint Variables. + (line 19) +* $trace_line: Tracepoint Variables. + (line 13) +* $_, convenience variable: Convenience Vars. (line 65) +* $_exception, convenience variable: Set Catchpoints. (line 21) +* $_exitcode, convenience variable: Convenience Vars. (line 80) +* $_exitsignal, convenience variable: Convenience Vars. (line 85) +* $_isvoid, convenience function: Convenience Funs. (line 15) +* $_memeq, convenience function: Convenience Funs. (line 65) +* $_probe_arg, convenience variable: Static Probe Points. (line 46) +* $_regex, convenience function: Convenience Funs. (line 69) +* $_sdata, collect: Tracepoint Actions. (line 78) +* $_sdata, inspect, convenience variable: Convenience Vars. (line 142) +* $_siginfo, convenience variable: Convenience Vars. (line 148) +* $_streq, convenience function: Convenience Funs. (line 74) +* $_strlen, convenience function: Convenience Funs. (line 78) +* $_thread, convenience variable: Threads. (line 110) +* $_tlb, convenience variable: Convenience Vars. (line 154) +* $__, convenience variable: Convenience Vars. (line 74) +* -ada-task-info: GDB/MI Ada Tasking Commands. + (line 9) +* -add-inferior: GDB/MI Miscellaneous Commands. + (line 288) +* -break-after: GDB/MI Breakpoint Commands. + (line 11) +* -break-commands: GDB/MI Breakpoint Commands. + (line 56) +* -break-condition: GDB/MI Breakpoint Commands. + (line 90) +* -break-delete: GDB/MI Breakpoint Commands. + (line 127) +* -break-disable: GDB/MI Breakpoint Commands. + (line 161) +* -break-enable: GDB/MI Breakpoint Commands. + (line 197) +* -break-info: GDB/MI Breakpoint Commands. + (line 232) +* -break-insert: GDB/MI Breakpoint Commands. + (line 256) +* -break-list: GDB/MI Breakpoint Commands. + (line 409) +* -break-passcount: GDB/MI Breakpoint Commands. + (line 481) +* -break-watch: GDB/MI Breakpoint Commands. + (line 493) +* -catch-assert: Ada Exception GDB/MI Catchpoint Commands. + (line 12) +* -catch-exception: Ada Exception GDB/MI Catchpoint Commands. + (line 46) +* -catch-load: Shared Library GDB/MI Catchpoint Commands. + (line 9) +* -catch-unload: Shared Library GDB/MI Catchpoint Commands. + (line 36) +* -data-disassemble: GDB/MI Data Manipulation. + (line 12) +* -data-evaluate-expression: GDB/MI Data Manipulation. + (line 174) +* -data-list-changed-registers: GDB/MI Data Manipulation. + (line 212) +* -data-list-register-names: GDB/MI Data Manipulation. + (line 248) +* -data-list-register-values: GDB/MI Data Manipulation. + (line 288) +* -data-read-memory: GDB/MI Data Manipulation. + (line 375) +* -data-read-memory-bytes: GDB/MI Data Manipulation. + (line 482) +* -data-write-memory-bytes: GDB/MI Data Manipulation. + (line 555) +* -dprintf-insert: GDB/MI Breakpoint Commands. + (line 342) +* -enable-frame-filters: GDB/MI Stack Manipulation. + (line 9) +* -enable-pretty-printing: GDB/MI Variable Objects. + (line 118) +* -enable-timings: GDB/MI Miscellaneous Commands. + (line 385) +* -environment-cd: GDB/MI Program Context. + (line 33) +* -environment-directory: GDB/MI Program Context. + (line 56) +* -environment-path: GDB/MI Program Context. + (line 100) +* -environment-pwd: GDB/MI Program Context. + (line 141) +* -exec-arguments: GDB/MI Program Context. + (line 9) +* -exec-continue: GDB/MI Program Execution. + (line 13) +* -exec-finish: GDB/MI Program Execution. + (line 53) +* -exec-interrupt: GDB/MI Program Execution. + (line 96) +* -exec-jump: GDB/MI Program Execution. + (line 146) +* -exec-next: GDB/MI Program Execution. + (line 170) +* -exec-next-instruction: GDB/MI Program Execution. + (line 201) +* -exec-return: GDB/MI Program Execution. + (line 237) +* -exec-run: GDB/MI Program Execution. + (line 280) +* -exec-step: GDB/MI Program Execution. + (line 350) +* -exec-step-instruction: GDB/MI Program Execution. + (line 392) +* -exec-until: GDB/MI Program Execution. + (line 433) +* -file-exec-and-symbols: GDB/MI File Commands. + (line 12) +* -file-exec-file: GDB/MI File Commands. + (line 40) +* -file-list-exec-source-file: GDB/MI File Commands. + (line 67) +* -file-list-exec-source-files: GDB/MI File Commands. + (line 93) +* -file-symbol-file: GDB/MI File Commands. + (line 123) +* -gdb-exit: GDB/MI Miscellaneous Commands. + (line 9) +* -gdb-set: GDB/MI Miscellaneous Commands. + (line 31) +* -gdb-show: GDB/MI Miscellaneous Commands. + (line 54) +* -gdb-version: GDB/MI Miscellaneous Commands. + (line 77) +* -inferior-tty-set: GDB/MI Miscellaneous Commands. + (line 336) +* -inferior-tty-show: GDB/MI Miscellaneous Commands. + (line 359) +* -info-ada-exceptions: GDB/MI Ada Exceptions Commands. + (line 9) +* -info-gdb-mi-command: GDB/MI Support Commands. + (line 14) +* -info-os: GDB/MI Miscellaneous Commands. + (line 216) +* -interpreter-exec: GDB/MI Miscellaneous Commands. + (line 310) +* -list-features: GDB/MI Support Commands. + (line 57) +* -list-target-features: GDB/MI Support Commands. + (line 112) +* -list-thread-groups: GDB/MI Miscellaneous Commands. + (line 111) +* -stack-info-depth: GDB/MI Stack Manipulation. + (line 50) +* -stack-info-frame: GDB/MI Stack Manipulation. + (line 24) +* -stack-list-arguments: GDB/MI Stack Manipulation. + (line 88) +* -stack-list-frames: GDB/MI Stack Manipulation. + (line 182) +* -stack-list-locals: GDB/MI Stack Manipulation. + (line 281) +* -stack-list-variables: GDB/MI Stack Manipulation. + (line 327) +* -stack-select-frame: GDB/MI Stack Manipulation. + (line 355) +* -symbol-list-lines: GDB/MI Symbol Query. (line 9) +* -target-attach: GDB/MI Target Manipulation. + (line 9) +* -target-detach: GDB/MI Target Manipulation. + (line 36) +* -target-disconnect: GDB/MI Target Manipulation. + (line 61) +* -target-download: GDB/MI Target Manipulation. + (line 85) +* -target-file-delete: GDB/MI File Transfer Commands. + (line 57) +* -target-file-get: GDB/MI File Transfer Commands. + (line 33) +* -target-file-put: GDB/MI File Transfer Commands. + (line 9) +* -target-select: GDB/MI Target Manipulation. + (line 192) +* -thread-info: GDB/MI Thread Commands. + (line 9) +* -thread-list-ids: GDB/MI Thread Commands. + (line 88) +* -thread-select: GDB/MI Thread Commands. + (line 116) +* -trace-define-variable: GDB/MI Tracepoint Commands. + (line 80) +* -trace-find: GDB/MI Tracepoint Commands. + (line 12) +* -trace-frame-collected: GDB/MI Tracepoint Commands. + (line 97) +* -trace-list-variables: GDB/MI Tracepoint Commands. + (line 204) +* -trace-save: GDB/MI Tracepoint Commands. + (line 246) +* -trace-start: GDB/MI Tracepoint Commands. + (line 263) +* -trace-status: GDB/MI Tracepoint Commands. + (line 279) +* -trace-stop: GDB/MI Tracepoint Commands. + (line 350) +* -var-assign: GDB/MI Variable Objects. + (line 492) +* -var-create: GDB/MI Variable Objects. + (line 136) +* -var-delete: GDB/MI Variable Objects. + (line 224) +* -var-evaluate-expression: GDB/MI Variable Objects. + (line 471) +* -var-info-expression: GDB/MI Variable Objects. + (line 408) +* -var-info-num-children: GDB/MI Variable Objects. + (line 273) +* -var-info-path-expression: GDB/MI Variable Objects. + (line 433) +* -var-info-type: GDB/MI Variable Objects. + (line 395) +* -var-list-children: GDB/MI Variable Objects. + (line 289) +* -var-set-format: GDB/MI Variable Objects. + (line 237) +* -var-set-frozen: GDB/MI Variable Objects. + (line 636) +* -var-set-update-range: GDB/MI Variable Objects. + (line 662) +* -var-set-visualizer: GDB/MI Variable Objects. + (line 685) +* -var-show-attributes: GDB/MI Variable Objects. + (line 457) +* -var-show-format: GDB/MI Variable Objects. + (line 260) +* -var-update: GDB/MI Variable Objects. + (line 516) +* @, referencing memory as an array: Arrays. (line 6) +* ^connected: GDB/MI Result Records. + (line 22) +* ^done: GDB/MI Result Records. + (line 9) +* ^error: GDB/MI Result Records. + (line 25) +* ^exit: GDB/MI Result Records. + (line 36) +* ^running: GDB/MI Result Records. + (line 14) +* __init__ on TypePrinter: gdb.types. (line 82) +* abort (C-g): Miscellaneous Commands. + (line 10) +* accept-line (Newline or Return): Commands For History. + (line 6) +* actions: Tracepoint Actions. (line 6) +* ada-task-info: GDB/MI Support Commands. + (line 94) +* add-auto-load-safe-path: Auto-loading safe path. + (line 50) +* add-inferior: Inferiors and Programs. + (line 60) +* add-shared-symbol-files: Files. (line 189) +* add-symbol-file: Files. (line 112) +* add-symbol-file-from-memory: Files. (line 179) +* advance LOCATION: Continuing and Stepping. + (line 179) +* alias: Aliases. (line 21) +* append: Dump/Restore Files. (line 32) +* apropos: Help. (line 62) +* Architecture.disassemble: Architectures In Python. + (line 15) +* Architecture.name: Architectures In Python. + (line 12) +* assf: Files. (line 189) +* attach: Attach. (line 6) +* attach&: Background Execution. + (line 36) +* awatch: Set Watchpoints. (line 83) +* b ('break'): Set Breaks. (line 6) +* backtrace: Backtrace. (line 11) +* backward-char (C-b): Commands For Moving. (line 15) +* backward-delete-char (Rubout): Commands For Text. (line 11) +* backward-kill-line (C-x Rubout): Commands For Killing. + (line 9) +* backward-kill-word (M-): Commands For Killing. + (line 24) +* backward-word (M-b): Commands For Moving. (line 22) +* beginning-of-history (M-<): Commands For History. + (line 19) +* beginning-of-line (C-a): Commands For Moving. (line 6) +* bell-style: Readline Init File Syntax. + (line 35) +* bind-tty-special-chars: Readline Init File Syntax. + (line 42) +* Block.end: Blocks In Python. (line 81) +* Block.function: Blocks In Python. (line 84) +* Block.global_block: Blocks In Python. (line 99) +* Block.is_global: Blocks In Python. (line 107) +* Block.is_static: Blocks In Python. (line 111) +* Block.is_valid: Blocks In Python. (line 68) +* Block.start: Blocks In Python. (line 78) +* Block.static_block: Blocks In Python. (line 103) +* Block.superblock: Blocks In Python. (line 94) +* BP_ACCESS_WATCHPOINT: Breakpoints In Python. + (line 152) +* BP_BREAKPOINT: Breakpoints In Python. + (line 140) +* BP_HARDWARE_WATCHPOINT: Breakpoints In Python. + (line 146) +* BP_READ_WATCHPOINT: Breakpoints In Python. + (line 149) +* BP_WATCHPOINT: Breakpoints In Python. + (line 143) +* break: Set Breaks. (line 6) +* break ... task TASKNO (Ada): Ada Tasks. (line 133) +* break ... thread THREADNO: Thread-Specific Breakpoints. + (line 10) +* break, and Objective-C: Method Names in Commands. + (line 9) +* break-range: PowerPC Embedded. (line 41) +* breakpoint annotation: Annotations for Running. + (line 47) +* breakpoint-notifications: GDB/MI Support Commands. + (line 91) +* Breakpoint.commands: Breakpoints In Python. + (line 177) +* Breakpoint.condition: Breakpoints In Python. + (line 172) +* Breakpoint.delete: Breakpoints In Python. + (line 81) +* Breakpoint.enabled: Breakpoints In Python. + (line 86) +* Breakpoint.expression: Breakpoints In Python. + (line 166) +* Breakpoint.hit_count: Breakpoints In Python. + (line 155) +* Breakpoint.ignore_count: Breakpoints In Python. + (line 109) +* Breakpoint.is_valid: Breakpoints In Python. + (line 73) +* Breakpoint.location: Breakpoints In Python. + (line 160) +* Breakpoint.number: Breakpoints In Python. + (line 113) +* Breakpoint.silent: Breakpoints In Python. + (line 90) +* Breakpoint.stop: Breakpoints In Python. + (line 30) +* Breakpoint.task: Breakpoints In Python. + (line 103) +* Breakpoint.temporary: Breakpoints In Python. + (line 128) +* Breakpoint.thread: Breakpoints In Python. + (line 98) +* Breakpoint.type: Breakpoints In Python. + (line 118) +* Breakpoint.visible: Breakpoints In Python. + (line 123) +* Breakpoint.__init__: Breakpoints In Python. + (line 8) +* BreakpointEvent.breakpoint: Events In Python. (line 105) +* BreakpointEvent.breakpoints: Events In Python. (line 101) +* breakpoints-invalid annotation: Invalidation. (line 14) +* bt ('backtrace'): Backtrace. (line 11) +* c ('continue'): Continuing and Stepping. + (line 15) +* c (SingleKey TUI key): TUI Single Key Mode. (line 10) +* C-L: TUI Keys. (line 65) +* C-x 1: TUI Keys. (line 19) +* C-x 2: TUI Keys. (line 26) +* C-x a: TUI Keys. (line 11) +* C-x A: TUI Keys. (line 12) +* C-x C-a: TUI Keys. (line 10) +* C-x o: TUI Keys. (line 34) +* C-x s: TUI Keys. (line 41) +* call: Calling. (line 10) +* call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) +* capitalize-word (M-c): Commands For Text. (line 49) +* catch: Set Catchpoints. (line 10) +* catch assert: Set Catchpoints. (line 87) +* catch catch: Set Catchpoints. (line 16) +* catch exception: Set Catchpoints. (line 66) +* catch exception unhandled: Set Catchpoints. (line 83) +* catch exec: Set Catchpoints. (line 90) +* catch fork: Set Catchpoints. (line 212) +* catch load: Set Catchpoints. (line 221) +* catch rethrow: Set Catchpoints. (line 16) +* catch signal: Set Catchpoints. (line 226) +* catch syscall: Set Catchpoints. (line 95) +* catch throw: Set Catchpoints. (line 16) +* catch unload: Set Catchpoints. (line 221) +* catch vfork: Set Catchpoints. (line 216) +* cd: Working Directory. (line 16) +* cdir: Source Path. (line 106) +* character-search (C-]): Miscellaneous Commands. + (line 41) +* character-search-backward (M-C-]): Miscellaneous Commands. + (line 46) +* checkpoint: Checkpoint/Restart. (line 26) +* clear: Delete Breaks. (line 21) +* clear, and Objective-C: Method Names in Commands. + (line 9) +* clear-screen (C-l): Commands For Moving. (line 26) +* clone-inferior: Inferiors and Programs. + (line 67) +* collect (tracepoints): Tracepoint Actions. (line 49) +* colon-colon, in Modula-2: M2 Scope. (line 6) +* Command.complete: Commands In Python. (line 70) +* Command.dont_repeat: Commands In Python. (line 42) +* Command.invoke: Commands In Python. (line 48) +* Command.__init__: Commands In Python. (line 10) +* commands: Break Commands. (line 11) +* commands annotation: Prompting. (line 27) +* COMMAND_BREAKPOINTS: Commands In Python. (line 142) +* COMMAND_DATA: Commands In Python. (line 113) +* COMMAND_FILES: Commands In Python. (line 124) +* COMMAND_MAINTENANCE: Commands In Python. (line 166) +* COMMAND_NONE: Commands In Python. (line 103) +* COMMAND_OBSCURE: Commands In Python. (line 160) +* COMMAND_RUNNING: Commands In Python. (line 107) +* COMMAND_STACK: Commands In Python. (line 118) +* COMMAND_STATUS: Commands In Python. (line 136) +* COMMAND_SUPPORT: Commands In Python. (line 129) +* COMMAND_TRACEPOINTS: Commands In Python. (line 148) +* COMMAND_USER: Commands In Python. (line 154) +* comment-begin: Readline Init File Syntax. + (line 47) +* compare-sections: Memory. (line 125) +* complete: Help. (line 77) +* complete (): Commands For Completion. + (line 6) +* COMPLETE_COMMAND: Commands In Python. (line 187) +* COMPLETE_EXPRESSION: Commands In Python. (line 195) +* COMPLETE_FILENAME: Commands In Python. (line 180) +* COMPLETE_LOCATION: Commands In Python. (line 183) +* COMPLETE_NONE: Commands In Python. (line 177) +* COMPLETE_SYMBOL: Commands In Python. (line 191) +* completion-display-width: Readline Init File Syntax. + (line 52) +* completion-ignore-case: Readline Init File Syntax. + (line 59) +* completion-map-case: Readline Init File Syntax. + (line 64) +* completion-prefix-display-length: Readline Init File Syntax. + (line 70) +* completion-query-items: Readline Init File Syntax. + (line 77) +* condition: Conditions. (line 58) +* continue: Continuing and Stepping. + (line 15) +* continue&: Background Execution. + (line 51) +* convert-meta: Readline Init File Syntax. + (line 87) +* copy-backward-word (): Commands For Killing. + (line 49) +* copy-forward-word (): Commands For Killing. + (line 54) +* copy-region-as-kill (): Commands For Killing. + (line 45) +* core-file: Files. (line 96) +* ctf: Trace Files. (line 28) +* Ctrl-o (operate-and-get-next): Command Syntax. (line 41) +* cwd: Source Path. (line 106) +* d ('delete'): Delete Breaks. (line 41) +* d (SingleKey TUI key): TUI Single Key Mode. (line 13) +* data-read-memory-bytes: GDB/MI Support Commands. + (line 88) +* debug_chaos: M32R/D. (line 50) +* define: Define. (line 37) +* delete: Delete Breaks. (line 41) +* delete checkpoint CHECKPOINT-ID: Checkpoint/Restart. (line 53) +* delete display: Auto Display. (line 45) +* delete mem: Memory Region Attributes. + (line 34) +* delete tracepoint: Create and Delete Tracepoints. + (line 126) +* delete tvariable: Trace State Variables. + (line 42) +* delete-char (C-d): Commands For Text. (line 6) +* delete-char-or-list (): Commands For Completion. + (line 39) +* delete-horizontal-space (): Commands For Killing. + (line 37) +* detach: Attach. (line 36) +* detach (remote): Connecting. (line 91) +* detach inferiors INFNO...: Inferiors and Programs. + (line 96) +* digit-argument ('M-0', 'M-1', ... 'M--'): Numeric Arguments. + (line 6) +* dir: Source Path. (line 38) +* directory: Source Path. (line 38) +* dis ('disable'): Disabling. (line 37) +* disable: Disabling. (line 37) +* disable display: Auto Display. (line 56) +* disable frame-filter: Frame Filter Management. + (line 16) +* disable mem: Memory Region Attributes. + (line 38) +* disable pretty-printer: Pretty-Printer Commands. + (line 20) +* disable tracepoint: Enable and Disable Tracepoints. + (line 9) +* disable type-printer: Symbols. (line 245) +* disable-completion: Readline Init File Syntax. + (line 93) +* disassemble: Machine Code. (line 36) +* disconnect: Connecting. (line 98) +* display: Auto Display. (line 23) +* dll-symbols: Cygwin Native. (line 38) +* do ('down'): Selection. (line 40) +* do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. + (line 14) +* document: Define. (line 49) +* dont-repeat: Define. (line 61) +* down: Selection. (line 40) +* Down: TUI Keys. (line 56) +* down-silently: Selection. (line 64) +* downcase-word (M-l): Commands For Text. (line 45) +* dprintf: Dynamic Printf. (line 26) +* dprintf-style agent: Dynamic Printf. (line 46) +* dprintf-style call: Dynamic Printf. (line 42) +* dprintf-style gdb: Dynamic Printf. (line 39) +* dump: Dump/Restore Files. (line 13) +* dump-functions (): Miscellaneous Commands. + (line 69) +* dump-macros (): Miscellaneous Commands. + (line 81) +* dump-variables (): Miscellaneous Commands. + (line 75) +* e ('edit'): Edit. (line 6) +* echo: Output. (line 12) +* edit: Edit. (line 6) +* editing-mode: Readline Init File Syntax. + (line 98) +* else: Command Files. (line 74) +* emacs-editing-mode (C-e): Miscellaneous Commands. + (line 87) +* enable: Disabling. (line 44) +* enable display: Auto Display. (line 65) +* enable frame-filter: Frame Filter Management. + (line 26) +* enable mem: Memory Region Attributes. + (line 42) +* enable pretty-printer: Pretty-Printer Commands. + (line 25) +* enable tracepoint: Enable and Disable Tracepoints. + (line 19) +* enable type-printer: Symbols. (line 245) +* enable-keypad: Readline Init File Syntax. + (line 109) +* enabled of type_printer: Type Printing API. (line 13) +* end (breakpoint commands): Break Commands. (line 11) +* end (if/else/while commands): Command Files. (line 103) +* end (user-defined commands): Define. (line 49) +* end-kbd-macro (C-x )): Keyboard Macros. (line 9) +* end-of-history (M->): Commands For History. + (line 22) +* end-of-line (C-e): Commands For Moving. (line 9) +* error annotation: Errors. (line 10) +* error-begin annotation: Errors. (line 22) +* eval: Output. (line 117) +* EventRegistry.connect: Events In Python. (line 19) +* EventRegistry.disconnect: Events In Python. (line 23) +* exceptionHandler: Bootstrapping. (line 38) +* exchange-point-and-mark (C-x C-x): Miscellaneous Commands. + (line 36) +* exec-file: Files. (line 39) +* exec-run-start-option: GDB/MI Support Commands. + (line 105) +* exited annotation: Annotations for Running. + (line 18) +* ExitedEvent: Events In Python. (line 72) +* ExitedEvent.exit_code: Events In Python. (line 67) +* expand-tilde: Readline Init File Syntax. + (line 120) +* explore: Data. (line 36) +* f ('frame'): Selection. (line 11) +* f (SingleKey TUI key): TUI Single Key Mode. (line 16) +* fg (resume foreground execution): Continuing and Stepping. + (line 15) +* file: Files. (line 16) +* fin ('finish'): Continuing and Stepping. + (line 108) +* find: Searching Memory. (line 9) +* finish: Continuing and Stepping. + (line 108) +* finish&: Background Execution. + (line 54) +* FinishBreakpoint.out_of_scope: Finish Breakpoints in Python. + (line 21) +* FinishBreakpoint.return_value: Finish Breakpoints in Python. + (line 38) +* FinishBreakpoint.__init__: Finish Breakpoints in Python. + (line 14) +* flushregs: Maintenance Commands. + (line 230) +* flush_i_cache: Bootstrapping. (line 60) +* fo ('forward-search'): Search. (line 9) +* focus: TUI Commands. (line 40) +* forward-backward-delete-char (): Commands For Text. (line 15) +* forward-char (C-f): Commands For Moving. (line 12) +* forward-search: Search. (line 9) +* forward-search-history (C-s): Commands For History. + (line 30) +* forward-word (M-f): Commands For Moving. (line 18) +* frame, command: Frames. (line 45) +* frame, selecting: Selection. (line 11) +* Frame.architecture: Frames In Python. (line 46) +* Frame.block: Frames In Python. (line 128) +* Frame.find_sal: Frames In Python. (line 141) +* Frame.function: Frames In Python. (line 131) +* Frame.is_valid: Frames In Python. (line 36) +* Frame.name: Frames In Python. (line 42) +* Frame.newer: Frames In Python. (line 138) +* Frame.older: Frames In Python. (line 135) +* Frame.pc: Frames In Python. (line 125) +* Frame.read_var: Frames In Python. (line 145) +* Frame.select: Frames In Python. (line 153) +* Frame.type: Frames In Python. (line 50) +* Frame.unwind_stop_reason: Frames In Python. (line 77) +* FrameDecorator.address: Frame Decorator API. (line 56) +* FrameDecorator.elided: Frame Decorator API. (line 25) +* FrameDecorator.filename: Frame Decorator API. (line 66) +* FrameDecorator.frame_args: Frame Decorator API. (line 87) +* FrameDecorator.frame_locals: Frame Decorator API. (line 139) +* FrameDecorator.function: Frame Decorator API. (line 45) +* FrameDecorator.inferior_frame: Frame Decorator API. (line 172) +* FrameDecorator.line: Frame Decorator API. (line 77) +* FrameFilter.enabled: Frame Filter API. (line 122) +* FrameFilter.filter: Frame Filter API. (line 75) +* FrameFilter.name: Frame Filter API. (line 115) +* FrameFilter.priority: Frame Filter API. (line 131) +* frames-invalid annotation: Invalidation. (line 9) +* frozen-varobjs: GDB/MI Support Commands. + (line 75) +* ftrace: Create and Delete Tracepoints. + (line 51) +* Function: Functions In Python. (line 6) +* Function.invoke: Functions In Python. (line 19) +* Function.__init__: Functions In Python. (line 10) +* gcore: Core File Generation. + (line 17) +* gdb.Block: Blocks In Python. (line 6) +* gdb.block_for_pc: Blocks In Python. (line 61) +* gdb.block_for_pc <1>: Blocks In Python. (line 61) +* gdb.BP_ACCESS_WATCHPOINT: Breakpoints In Python. + (line 152) +* gdb.BP_BREAKPOINT: Breakpoints In Python. + (line 140) +* gdb.BP_HARDWARE_WATCHPOINT: Breakpoints In Python. + (line 146) +* gdb.BP_READ_WATCHPOINT: Breakpoints In Python. + (line 149) +* gdb.BP_WATCHPOINT: Breakpoints In Python. + (line 143) +* gdb.Breakpoint: Breakpoints In Python. + (line 6) +* gdb.breakpoints: Basic Python. (line 53) +* gdb.breakpoints <1>: Basic Python. (line 53) +* gdb.COMMAND_BREAKPOINTS: Commands In Python. (line 142) +* gdb.COMMAND_DATA: Commands In Python. (line 113) +* gdb.COMMAND_FILES: Commands In Python. (line 124) +* gdb.COMMAND_MAINTENANCE: Commands In Python. (line 166) +* gdb.COMMAND_NONE: Commands In Python. (line 103) +* gdb.COMMAND_OBSCURE: Commands In Python. (line 160) +* gdb.COMMAND_RUNNING: Commands In Python. (line 107) +* gdb.COMMAND_STACK: Commands In Python. (line 118) +* gdb.COMMAND_STATUS: Commands In Python. (line 136) +* gdb.COMMAND_SUPPORT: Commands In Python. (line 129) +* gdb.COMMAND_TRACEPOINTS: Commands In Python. (line 148) +* gdb.COMMAND_USER: Commands In Python. (line 154) +* gdb.COMPLETE_COMMAND: Commands In Python. (line 187) +* gdb.COMPLETE_EXPRESSION: Commands In Python. (line 195) +* gdb.COMPLETE_FILENAME: Commands In Python. (line 180) +* gdb.COMPLETE_LOCATION: Commands In Python. (line 183) +* gdb.COMPLETE_NONE: Commands In Python. (line 177) +* gdb.COMPLETE_SYMBOL: Commands In Python. (line 191) +* gdb.current_objfile: Objfiles In Python. (line 15) +* gdb.current_objfile <1>: Objfiles In Python. (line 15) +* gdb.current_progspace: Progspaces In Python. + (line 14) +* gdb.current_progspace <1>: Progspaces In Python. + (line 14) +* gdb.decode_line: Basic Python. (line 184) +* gdb.decode_line <1>: Basic Python. (line 184) +* gdb.default_visualizer: Pretty Printing API. (line 85) +* gdb.default_visualizer <1>: Pretty Printing API. (line 85) +* gdb.error: Exception Handling. (line 22) +* gdb.execute: Basic Python. (line 36) +* gdb.execute <1>: Basic Python. (line 36) +* gdb.find_pc_line: Basic Python. (line 91) +* gdb.find_pc_line <1>: Basic Python. (line 91) +* gdb.FinishBreakpoint: Finish Breakpoints in Python. + (line 6) +* gdb.flush: Basic Python. (line 150) +* gdb.flush <1>: Basic Python. (line 150) +* gdb.frame_stop_reason_string: Frames In Python. (line 29) +* gdb.Function: Functions In Python. (line 6) +* gdb.GdbError: Exception Handling. (line 42) +* gdb.history: Basic Python. (line 68) +* gdb.history <1>: Basic Python. (line 68) +* gdb.Inferior: Inferiors In Python. (line 6) +* gdb.inferiors: Inferiors In Python. (line 14) +* gdb.InferiorThread: Threads In Python. (line 6) +* gdb.LazyString: Lazy Strings In Python. + (line 6) +* gdb.LineTable: Line Tables In Python. + (line 6) +* gdb.lookup_global_symbol: Symbols In Python. (line 33) +* gdb.lookup_global_symbol <1>: Symbols In Python. (line 33) +* gdb.lookup_symbol: Symbols In Python. (line 13) +* gdb.lookup_symbol <1>: Symbols In Python. (line 13) +* gdb.lookup_type: Types In Python. (line 11) +* gdb.lookup_type <1>: Types In Python. (line 11) +* gdb.MemoryError: Exception Handling. (line 30) +* gdb.newest_frame: Frames In Python. (line 26) +* gdb.newest_frame <1>: Frames In Python. (line 26) +* gdb.Objfile: Objfiles In Python. (line 6) +* gdb.objfiles: Objfiles In Python. (line 21) +* gdb.objfiles <1>: Objfiles In Python. (line 21) +* gdb.Parameter: Parameters In Python. + (line 6) +* gdb.parameter: Basic Python. (line 57) +* gdb.parameter <1>: Basic Python. (line 57) +* gdb.PARAM_AUTO_BOOLEAN: Parameters In Python. + (line 93) +* gdb.PARAM_BOOLEAN: Parameters In Python. + (line 89) +* gdb.PARAM_ENUM: Parameters In Python. + (line 127) +* gdb.PARAM_FILENAME: Parameters In Python. + (line 119) +* gdb.PARAM_INTEGER: Parameters In Python. + (line 102) +* gdb.PARAM_OPTIONAL_FILENAME: Parameters In Python. + (line 116) +* gdb.PARAM_STRING: Parameters In Python. + (line 106) +* gdb.PARAM_STRING_NOESCAPE: Parameters In Python. + (line 112) +* gdb.PARAM_UINTEGER: Parameters In Python. + (line 98) +* gdb.PARAM_ZINTEGER: Parameters In Python. + (line 123) +* gdb.parse_and_eval: Basic Python. (line 80) +* gdb.parse_and_eval <1>: Basic Python. (line 80) +* gdb.post_event: Basic Python. (line 98) +* gdb.post_event <1>: Basic Python. (line 98) +* gdb.Progspace: Progspaces In Python. + (line 6) +* gdb.progspaces: Progspaces In Python. + (line 18) +* gdb.progspaces <1>: Progspaces In Python. + (line 18) +* gdb.prompt_hook: Basic Python. (line 196) +* gdb.PYTHONDIR: Basic Python. (line 33) +* gdb.PYTHONDIR <1>: Basic Python. (line 33) +* gdb.search_memory: Inferiors In Python. (line 61) +* gdb.selected_frame: Frames In Python. (line 22) +* gdb.selected_frame <1>: Frames In Python. (line 22) +* gdb.selected_inferior: Inferiors In Python. (line 17) +* gdb.selected_thread: Threads In Python. (line 13) +* gdb.selected_thread <1>: Threads In Python. (line 13) +* gdb.solib_name: Basic Python. (line 180) +* gdb.solib_name <1>: Basic Python. (line 180) +* gdb.STDERR: Basic Python. (line 140) +* gdb.STDERR <1>: Basic Python. (line 160) +* gdb.STDLOG: Basic Python. (line 143) +* gdb.STDLOG <1>: Basic Python. (line 163) +* gdb.STDOUT: Basic Python. (line 137) +* gdb.STDOUT <1>: Basic Python. (line 157) +* gdb.string_to_argv: Commands In Python. (line 61) +* gdb.Symbol: Symbols In Python. (line 6) +* gdb.SYMBOL_FUNCTIONS_DOMAIN: Symbols In Python. (line 128) +* gdb.SYMBOL_LABEL_DOMAIN: Symbols In Python. (line 123) +* gdb.SYMBOL_LOC_ARG: Symbols In Python. (line 145) +* gdb.SYMBOL_LOC_BLOCK: Symbols In Python. (line 161) +* gdb.SYMBOL_LOC_COMPUTED: Symbols In Python. (line 171) +* gdb.SYMBOL_LOC_CONST: Symbols In Python. (line 139) +* gdb.SYMBOL_LOC_CONST_BYTES: Symbols In Python. (line 163) +* gdb.SYMBOL_LOC_LOCAL: Symbols In Python. (line 156) +* gdb.SYMBOL_LOC_OPTIMIZED_OUT: Symbols In Python. (line 169) +* gdb.SYMBOL_LOC_REF_ARG: Symbols In Python. (line 148) +* gdb.SYMBOL_LOC_REGISTER: Symbols In Python. (line 143) +* gdb.SYMBOL_LOC_REGPARM_ADDR: Symbols In Python. (line 152) +* gdb.SYMBOL_LOC_STATIC: Symbols In Python. (line 141) +* gdb.SYMBOL_LOC_TYPEDEF: Symbols In Python. (line 158) +* gdb.SYMBOL_LOC_UNDEF: Symbols In Python. (line 137) +* gdb.SYMBOL_LOC_UNRESOLVED: Symbols In Python. (line 165) +* gdb.SYMBOL_STRUCT_DOMAIN: Symbols In Python. (line 121) +* gdb.SYMBOL_TYPES_DOMAIN: Symbols In Python. (line 130) +* gdb.SYMBOL_UNDEF_DOMAIN: Symbols In Python. (line 115) +* gdb.SYMBOL_VARIABLES_DOMAIN: Symbols In Python. (line 125) +* gdb.SYMBOL_VAR_DOMAIN: Symbols In Python. (line 118) +* gdb.Symtab: Symbol Tables In Python. + (line 6) +* gdb.Symtab_and_line: Symbol Tables In Python. + (line 6) +* gdb.target_charset: Basic Python. (line 169) +* gdb.target_charset <1>: Basic Python. (line 169) +* gdb.target_wide_charset: Basic Python. (line 174) +* gdb.target_wide_charset <1>: Basic Python. (line 174) +* gdb.Type: Types In Python. (line 6) +* gdb.TYPE_CODE_ARRAY: Types In Python. (line 187) +* gdb.TYPE_CODE_BITSTRING: Types In Python. (line 225) +* gdb.TYPE_CODE_BOOL: Types In Python. (line 246) +* gdb.TYPE_CODE_CHAR: Types In Python. (line 243) +* gdb.TYPE_CODE_COMPLEX: Types In Python. (line 249) +* gdb.TYPE_CODE_DECFLOAT: Types In Python. (line 258) +* gdb.TYPE_CODE_ENUM: Types In Python. (line 196) +* gdb.TYPE_CODE_ERROR: Types In Python. (line 228) +* gdb.TYPE_CODE_FLAGS: Types In Python. (line 199) +* gdb.TYPE_CODE_FLT: Types In Python. (line 208) +* gdb.TYPE_CODE_FUNC: Types In Python. (line 202) +* gdb.TYPE_CODE_INT: Types In Python. (line 205) +* gdb.TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 261) +* gdb.TYPE_CODE_MEMBERPTR: Types In Python. (line 237) +* gdb.TYPE_CODE_METHOD: Types In Python. (line 231) +* gdb.TYPE_CODE_METHODPTR: Types In Python. (line 234) +* gdb.TYPE_CODE_NAMESPACE: Types In Python. (line 255) +* gdb.TYPE_CODE_PTR: Types In Python. (line 184) +* gdb.TYPE_CODE_RANGE: Types In Python. (line 217) +* gdb.TYPE_CODE_REF: Types In Python. (line 240) +* gdb.TYPE_CODE_SET: Types In Python. (line 214) +* gdb.TYPE_CODE_STRING: Types In Python. (line 220) +* gdb.TYPE_CODE_STRUCT: Types In Python. (line 190) +* gdb.TYPE_CODE_TYPEDEF: Types In Python. (line 252) +* gdb.TYPE_CODE_UNION: Types In Python. (line 193) +* gdb.TYPE_CODE_VOID: Types In Python. (line 211) +* gdb.WP_ACCESS: Breakpoints In Python. + (line 70) +* gdb.WP_READ: Breakpoints In Python. + (line 64) +* gdb.WP_WRITE: Breakpoints In Python. + (line 67) +* gdb.write: Basic Python. (line 132) +* gdb.write <1>: Basic Python. (line 132) +* gdbserver: Server. (line 6) +* gdb_init_reader: Writing JIT Debug Info Readers. + (line 20) +* generate-core-file: Core File Generation. + (line 17) +* getDebugChar: Bootstrapping. (line 14) +* gnu_debuglink_crc32: Separate Debug Files. + (line 160) +* h ('help'): Help. (line 9) +* handle: Signals. (line 49) +* handle_exception: Stub Contents. (line 15) +* hbreak: Set Breaks. (line 60) +* help: Help. (line 6) +* help function: Convenience Funs. (line 84) +* help target: Target Commands. (line 19) +* help user-defined: Define. (line 66) +* history-preserve-point: Readline Init File Syntax. + (line 124) +* history-search-backward (): Commands For History. + (line 50) +* history-search-forward (): Commands For History. + (line 45) +* history-size: Readline Init File Syntax. + (line 130) +* hook: Hooks. (line 6) +* hookpost: Hooks. (line 11) +* horizontal-scroll-mode: Readline Init File Syntax. + (line 135) +* i ('info'): Help. (line 100) +* if: Command Files. (line 74) +* ignore: Conditions. (line 90) +* INCLUDE_RDB: VxWorks. (line 32) +* inferior INFNO: Inferiors and Programs. + (line 48) +* Inferior.is_valid: Inferiors In Python. (line 35) +* Inferior.num: Inferiors In Python. (line 22) +* Inferior.pid: Inferiors In Python. (line 25) +* Inferior.read_memory: Inferiors In Python. (line 47) +* Inferior.read_memory <1>: Inferiors In Python. (line 47) +* Inferior.search_memory: Inferiors In Python. (line 61) +* Inferior.threads: Inferiors In Python. (line 42) +* Inferior.was_attached: Inferiors In Python. (line 29) +* Inferior.write_memory: Inferiors In Python. (line 54) +* Inferior.write_memory <1>: Inferiors In Python. (line 54) +* InferiorThread.is_exited: Threads In Python. (line 59) +* InferiorThread.is_running: Threads In Python. (line 56) +* InferiorThread.is_stopped: Threads In Python. (line 53) +* InferiorThread.is_valid: Threads In Python. (line 42) +* InferiorThread.name: Threads In Python. (line 19) +* InferiorThread.num: Threads In Python. (line 29) +* InferiorThread.ptid: Threads In Python. (line 32) +* InferiorThread.switch: Threads In Python. (line 49) +* info: Help. (line 100) +* info address: Symbols. (line 74) +* info all-registers: Registers. (line 15) +* info args: Frame Info. (line 44) +* info auto-load: Auto-loading. (line 60) +* info auto-load gdb-scripts: Auto-loading sequences. + (line 21) +* info auto-load libthread-db: libthread_db.so.1 file. + (line 29) +* info auto-load local-gdbinit: Init File in the Current Directory. + (line 22) +* info auto-load python-scripts: Python Auto-loading. (line 23) +* info auxv: OS Information. (line 20) +* info breakpoints: Set Breaks. (line 125) +* info checkpoints: Checkpoint/Restart. (line 31) +* info classes: Symbols. (line 309) +* info common: Special Fortran Commands. + (line 9) +* info copying: Help. (line 138) +* info dcache: Caching Target Data. (line 46) +* info display: Auto Display. (line 78) +* info dll: Cygwin Native. (line 35) +* info dos: DJGPP Native. (line 15) +* info exceptions: Ada Exceptions. (line 8) +* info extensions: Show. (line 34) +* info f ('info frame'): Frame Info. (line 17) +* info files: Files. (line 207) +* info float: Floating Point Hardware. + (line 9) +* info frame: Frame Info. (line 17) +* info frame, show the source language: Show. (line 15) +* info frame-filter: Frame Filter Management. + (line 12) +* info functions: Symbols. (line 289) +* info handle: Signals. (line 33) +* info inferiors: Inferiors and Programs. + (line 25) +* info io_registers, AVR: AVR. (line 10) +* info line: Machine Code. (line 14) +* info line, and Objective-C: Method Names in Commands. + (line 9) +* info locals: Frame Info. (line 48) +* info macro: Macros. (line 47) +* info macros: Macros. (line 54) +* info mem: Memory Region Attributes. + (line 45) +* info meminfo: SVR4 Process Information. + (line 93) +* info os: OS Information. (line 37) +* info os files: OS Information. (line 69) +* info os modules: OS Information. (line 111) +* info os msg: OS Information. (line 100) +* info os processes: OS Information. (line 43) +* info os procgroups: OS Information. (line 52) +* info os semaphores: OS Information. (line 92) +* info os shm: OS Information. (line 82) +* info os sockets: OS Information. (line 75) +* info os threads: OS Information. (line 62) +* info pidlist: SVR4 Process Information. + (line 89) +* info pretty-printer: Pretty-Printer Commands. + (line 6) +* info probes: Static Probe Points. (line 30) +* info proc: SVR4 Process Information. + (line 19) +* info program: Stopping. (line 18) +* info record: Process Record and Replay. + (line 171) +* info registers: Registers. (line 11) +* info scope: Symbols. (line 249) +* info selectors: Symbols. (line 315) +* info serial: DJGPP Native. (line 139) +* info set: Help. (line 121) +* info share: Files. (line 328) +* info sharedlibrary: Files. (line 328) +* info signals: Signals. (line 33) +* info skip: Skipping Over Functions and Files. + (line 56) +* info source: Symbols. (line 270) +* info source, show the source language: Show. (line 21) +* info sources: Symbols. (line 283) +* info spu: SPU. (line 10) +* info stack: Backtrace. (line 46) +* info static-tracepoint-markers: Listing Static Tracepoint Markers. + (line 6) +* info symbol: Symbols. (line 84) +* info target: Files. (line 207) +* info task TASKNO: Ada Tasks. (line 87) +* info tasks: Ada Tasks. (line 9) +* info terminal: Input/Output. (line 12) +* info threads: Threads. (line 60) +* info tp [N...]: Listing Tracepoints. (line 6) +* info tracepoints [N...]: Listing Tracepoints. (line 6) +* info tvariables: Trace State Variables. + (line 37) +* info type-printers: Symbols. (line 237) +* info types: Symbols. (line 223) +* info variables: Symbols. (line 300) +* info vector: Vector Unit. (line 9) +* info w32: Cygwin Native. (line 19) +* info warranty: Help. (line 142) +* info watchpoints [N...]: Set Watchpoints. (line 87) +* info win: TUI Commands. (line 18) +* info-gdb-mi-command: GDB/MI Support Commands. + (line 99) +* init-if-undefined: Convenience Vars. (line 42) +* input-meta: Readline Init File Syntax. + (line 142) +* insert-comment (M-#): Miscellaneous Commands. + (line 60) +* insert-completions (M-*): Commands For Completion. + (line 18) +* inspect: Data. (line 6) +* instantiate on type_printer: Type Printing API. (line 22) +* interpreter-exec: Interpreters. (line 42) +* interrupt: Background Execution. + (line 70) +* isearch-terminators: Readline Init File Syntax. + (line 149) +* j ('jump'): Jumping. (line 10) +* jit-reader-load: Using JIT Debug Info Readers. + (line 6) +* jit-reader-unload: Using JIT Debug Info Readers. + (line 6) +* jump: Jumping. (line 10) +* jump, and Objective-C: Method Names in Commands. + (line 9) +* KeyboardInterrupt: Exception Handling. (line 34) +* keymap: Readline Init File Syntax. + (line 156) +* kill: Kill Process. (line 6) +* kill inferiors INFNO...: Inferiors and Programs. + (line 102) +* kill-line (C-k): Commands For Killing. + (line 6) +* kill-region (): Commands For Killing. + (line 41) +* kill-whole-line (): Commands For Killing. + (line 15) +* kill-word (M-d): Commands For Killing. + (line 19) +* kvm: BSD libkvm Interface. + (line 24) +* l ('list'): List. (line 6) +* language-option: GDB/MI Support Commands. + (line 96) +* layout: TUI Commands. (line 21) +* LazyString.address: Lazy Strings In Python. + (line 26) +* LazyString.encoding: Lazy Strings In Python. + (line 36) +* LazyString.length: Lazy Strings In Python. + (line 30) +* LazyString.type: Lazy Strings In Python. + (line 43) +* LazyString.value: Lazy Strings In Python. + (line 20) +* Left: TUI Keys. (line 59) +* LineTable.has_line: Line Tables In Python. + (line 57) +* LineTable.line: Line Tables In Python. + (line 51) +* LineTable.source_lines: Line Tables In Python. + (line 62) +* LineTableEntry.line: Line Tables In Python. + (line 16) +* LineTableEntry.pc: Line Tables In Python. + (line 21) +* list: List. (line 6) +* list, and Objective-C: Method Names in Commands. + (line 9) +* load FILENAME: Target Commands. (line 108) +* loop_break: Command Files. (line 93) +* loop_continue: Command Files. (line 97) +* macro define: Macros. (line 59) +* macro exp1: Macros. (line 36) +* macro expand: Macros. (line 29) +* macro list: Macros. (line 80) +* macro undef: Macros. (line 74) +* maint agent: Maintenance Commands. + (line 11) +* maint agent-eval: Maintenance Commands. + (line 11) +* maint agent-printf: Maintenance Commands. + (line 26) +* maint check-psymtabs: Maintenance Commands. + (line 88) +* maint check-symtabs: Maintenance Commands. + (line 93) +* maint cplus first_component: Maintenance Commands. + (line 100) +* maint cplus namespace: Maintenance Commands. + (line 103) +* maint demangle: Maintenance Commands. + (line 106) +* maint deprecate: Maintenance Commands. + (line 109) +* maint dump-me: Maintenance Commands. + (line 117) +* maint expand-symtabs: Maintenance Commands. + (line 96) +* maint info bfds: Maintenance Commands. + (line 62) +* maint info breakpoints: Maintenance Commands. + (line 32) +* maint info program-spaces: Inferiors and Programs. + (line 139) +* maint info psymtabs: Symbols. (line 357) +* maint info sections: Files. (line 216) +* maint info sol-threads: Threads. (line 92) +* maint info symtabs: Symbols. (line 357) +* maint internal-error: Maintenance Commands. + (line 122) +* maint internal-warning: Maintenance Commands. + (line 122) +* maint packet: Maintenance Commands. + (line 162) +* maint print architecture: Maintenance Commands. + (line 168) +* maint print c-tdesc: Maintenance Commands. + (line 172) +* maint print cooked-registers: Maintenance Commands. + (line 195) +* maint print dummy-frames: Maintenance Commands. + (line 177) +* maint print msymbols: Symbols. (line 339) +* maint print objfiles: Maintenance Commands. + (line 233) +* maint print psymbols: Symbols. (line 339) +* maint print raw-registers: Maintenance Commands. + (line 195) +* maint print reggroups: Maintenance Commands. + (line 214) +* maint print register-groups: Maintenance Commands. + (line 195) +* maint print registers: Maintenance Commands. + (line 195) +* maint print remote-registers: Maintenance Commands. + (line 195) +* maint print section-scripts: Maintenance Commands. + (line 239) +* maint print statistics: Maintenance Commands. + (line 246) +* maint print symbols: Symbols. (line 339) +* maint print target-stack: Maintenance Commands. + (line 259) +* maint print type: Maintenance Commands. + (line 271) +* maint print unwind, HPPA: HPPA. (line 17) +* maint set dwarf2 always-disassemble: Maintenance Commands. + (line 278) +* maint set dwarf2 max-cache-age: Maintenance Commands. + (line 299) +* maint set internal-error: Maintenance Commands. + (line 143) +* maint set internal-warning: Maintenance Commands. + (line 143) +* maint set per-command: Maintenance Commands. + (line 343) +* maint set profile: Maintenance Commands. + (line 313) +* maint set show-all-tib: Maintenance Commands. + (line 337) +* maint set show-debug-regs: Maintenance Commands. + (line 329) +* maint show dwarf2 always-disassemble: Maintenance Commands. + (line 278) +* maint show dwarf2 max-cache-age: Maintenance Commands. + (line 299) +* maint show internal-error: Maintenance Commands. + (line 143) +* maint show internal-warning: Maintenance Commands. + (line 143) +* maint show per-command: Maintenance Commands. + (line 343) +* maint show profile: Maintenance Commands. + (line 313) +* maint show show-all-tib: Maintenance Commands. + (line 337) +* maint show show-debug-regs: Maintenance Commands. + (line 329) +* maint space: Maintenance Commands. + (line 382) +* maint time: Maintenance Commands. + (line 386) +* maint translate-address: Maintenance Commands. + (line 390) +* maint undeprecate: Maintenance Commands. + (line 109) +* make: Shell Commands. (line 21) +* mark-modified-lines: Readline Init File Syntax. + (line 169) +* mark-symlinked-directories: Readline Init File Syntax. + (line 174) +* match-hidden-files: Readline Init File Syntax. + (line 179) +* may-insert-breakpoints: Observer Mode. (line 50) +* may-insert-fast-tracepoints: Observer Mode. (line 69) +* may-insert-tracepoints: Observer Mode. (line 59) +* may-interrupt: Observer Mode. (line 79) +* may-write-memory: Observer Mode. (line 41) +* may-write-registers: Observer Mode. (line 32) +* mem: Memory Region Attributes. + (line 22) +* memset: Bootstrapping. (line 70) +* menu-complete (): Commands For Completion. + (line 22) +* menu-complete-backward (): Commands For Completion. + (line 34) +* menu-complete-display-prefix: Readline Init File Syntax. + (line 186) +* meta-flag: Readline Init File Syntax. + (line 142) +* monitor: Connecting. (line 105) +* n ('next'): Continuing and Stepping. + (line 76) +* n (SingleKey TUI key): TUI Single Key Mode. (line 19) +* name of type_printer: Type Printing API. (line 18) +* NewObjFileEvent.new_objfile: Events In Python. (line 115) +* next: Continuing and Stepping. + (line 76) +* next&: Background Execution. + (line 45) +* next-history (C-n): Commands For History. + (line 16) +* nexti: Continuing and Stepping. + (line 201) +* nexti&: Background Execution. + (line 48) +* ni ('nexti'): Continuing and Stepping. + (line 201) +* non-incremental-forward-search-history (M-n): Commands For History. + (line 40) +* non-incremental-reverse-search-history (M-p): Commands For History. + (line 35) +* nosharedlibrary: Files. (line 343) +* Objfile: Objfiles In Python. (line 6) +* Objfile.filename: Objfiles In Python. (line 28) +* Objfile.frame_filters: Objfiles In Python. (line 43) +* Objfile.is_valid: Objfiles In Python. (line 49) +* Objfile.pretty_printers: Objfiles In Python. (line 31) +* Objfile.type_printers: Objfiles In Python. (line 39) +* observer: Observer Mode. (line 22) +* output: Output. (line 35) +* output-meta: Readline Init File Syntax. + (line 191) +* overlay: Overlay Commands. (line 17) +* overload-choice annotation: Prompting. (line 32) +* overwrite-mode (): Commands For Text. (line 53) +* page-completions: Readline Init File Syntax. + (line 196) +* Parameter: Parameters In Python. + (line 6) +* Parameter.get_set_string: Parameters In Python. + (line 73) +* Parameter.get_show_string: Parameters In Python. + (line 79) +* Parameter.set_doc: Parameters In Python. + (line 53) +* Parameter.show_doc: Parameters In Python. + (line 59) +* Parameter.value: Parameters In Python. + (line 65) +* Parameter.__init__: Parameters In Python. + (line 18) +* PARAM_AUTO_BOOLEAN: Parameters In Python. + (line 93) +* PARAM_BOOLEAN: Parameters In Python. + (line 89) +* PARAM_ENUM: Parameters In Python. + (line 127) +* PARAM_FILENAME: Parameters In Python. + (line 119) +* PARAM_INTEGER: Parameters In Python. + (line 102) +* PARAM_OPTIONAL_FILENAME: Parameters In Python. + (line 116) +* PARAM_STRING: Parameters In Python. + (line 106) +* PARAM_STRING_NOESCAPE: Parameters In Python. + (line 112) +* PARAM_UINTEGER: Parameters In Python. + (line 98) +* PARAM_ZINTEGER: Parameters In Python. + (line 123) +* passcount: Tracepoint Passcounts. + (line 6) +* path: Environment. (line 14) +* pending-breakpoints: GDB/MI Support Commands. + (line 79) +* PgDn: TUI Keys. (line 50) +* PgUp: TUI Keys. (line 47) +* pi: Python Commands. (line 9) +* pmon, MIPS remote: MIPS Embedded. (line 128) +* po ('print-object'): The Print Command with Objective-C. + (line 6) +* possible-completions (M-?): Commands For Completion. + (line 11) +* post-commands annotation: Prompting. (line 27) +* post-overload-choice annotation: Prompting. (line 32) +* post-prompt annotation: Prompting. (line 24) +* post-prompt-for-continue annotation: Prompting. (line 40) +* post-query annotation: Prompting. (line 36) +* pre-commands annotation: Prompting. (line 27) +* pre-overload-choice annotation: Prompting. (line 32) +* pre-prompt annotation: Prompting. (line 24) +* pre-prompt-for-continue annotation: Prompting. (line 40) +* pre-query annotation: Prompting. (line 36) +* prefix-meta (): Miscellaneous Commands. + (line 18) +* pretty_printer.children: Pretty Printing API. (line 11) +* pretty_printer.display_hint: Pretty Printing API. (line 24) +* pretty_printer.to_string: Pretty Printing API. (line 53) +* previous-history (C-p): Commands For History. + (line 12) +* print: Data. (line 6) +* print-object: The Print Command with Objective-C. + (line 6) +* printf: Output. (line 46) +* proc-trace-entry: SVR4 Process Information. + (line 85) +* proc-trace-exit: SVR4 Process Information. + (line 85) +* proc-untrace-entry: SVR4 Process Information. + (line 85) +* proc-untrace-exit: SVR4 Process Information. + (line 85) +* Progspace: Progspaces In Python. + (line 6) +* Progspace.filename: Progspaces In Python. + (line 24) +* Progspace.frame_filters: Progspaces In Python. + (line 39) +* Progspace.pretty_printers: Progspaces In Python. + (line 27) +* Progspace.type_printers: Progspaces In Python. + (line 35) +* prompt annotation: Prompting. (line 24) +* prompt-for-continue annotation: Prompting. (line 40) +* ptype: Symbols. (line 158) +* putDebugChar: Bootstrapping. (line 20) +* pwd: Working Directory. (line 20) +* py: Python Commands. (line 23) +* python: GDB/MI Support Commands. + (line 82) +* python <1>: Python Commands. (line 23) +* python-interactive: Python Commands. (line 9) +* q ('quit'): Quitting GDB. (line 6) +* q (SingleKey TUI key): TUI Single Key Mode. (line 22) +* query annotation: Prompting. (line 36) +* quit annotation: Errors. (line 6) +* quit [EXPRESSION]: Quitting GDB. (line 6) +* quoted-insert (C-q or C-v): Commands For Text. (line 20) +* r ('run'): Starting. (line 6) +* r (SingleKey TUI key): TUI Single Key Mode. (line 25) +* rbreak: Set Breaks. (line 89) +* rc ('reverse-continue'): Reverse Execution. (line 30) +* rdilogenable: ARM. (line 90) +* rdilogfile: ARM. (line 84) +* re-read-init-file (C-x C-r): Miscellaneous Commands. + (line 6) +* readnow: Files. (line 89) +* rec: Process Record and Replay. + (line 38) +* rec btrace: Process Record and Replay. + (line 38) +* rec del: Process Record and Replay. + (line 196) +* rec full: Process Record and Replay. + (line 38) +* rec function-call-history: Process Record and Replay. + (line 243) +* rec instruction-history: Process Record and Replay. + (line 202) +* rec s: Process Record and Replay. + (line 73) +* recognize on type_recognizer: Type Printing API. (line 42) +* record: Process Record and Replay. + (line 38) +* record btrace: Process Record and Replay. + (line 38) +* record delete: Process Record and Replay. + (line 196) +* record full: Process Record and Replay. + (line 38) +* record function-call-history: Process Record and Replay. + (line 243) +* record goto: Process Record and Replay. + (line 96) +* record instruction-history: Process Record and Replay. + (line 202) +* record restore: Process Record and Replay. + (line 117) +* record save: Process Record and Replay. + (line 110) +* record stop: Process Record and Replay. + (line 73) +* redraw-current-line (): Commands For Moving. (line 30) +* refresh: TUI Commands. (line 58) +* remote delete: File Transfer. (line 23) +* remote get: File Transfer. (line 19) +* remote put: File Transfer. (line 15) +* remotetimeout: Sparclet. (line 12) +* remove-inferiors: Inferiors and Programs. + (line 86) +* remove-symbol-file: Files. (line 160) +* restart CHECKPOINT-ID: Checkpoint/Restart. (line 41) +* restore: Dump/Restore Files. (line 38) +* RET (repeat last command): Command Syntax. (line 21) +* return: Returning. (line 6) +* reverse-continue: Reverse Execution. (line 30) +* reverse-finish: Reverse Execution. (line 77) +* reverse-next: Reverse Execution. (line 60) +* reverse-nexti: Reverse Execution. (line 69) +* reverse-search: Search. (line 16) +* reverse-search-history (C-r): Commands For History. + (line 26) +* reverse-step: Reverse Execution. (line 37) +* reverse-stepi: Reverse Execution. (line 52) +* revert-all-at-newline: Readline Init File Syntax. + (line 206) +* revert-line (M-r): Miscellaneous Commands. + (line 25) +* Right: TUI Keys. (line 62) +* rn ('reverse-next'): Reverse Execution. (line 60) +* rni ('reverse-nexti'): Reverse Execution. (line 69) +* rs ('step'): Reverse Execution. (line 37) +* rsi ('reverse-stepi'): Reverse Execution. (line 52) +* run: Starting. (line 6) +* run&: Background Execution. + (line 32) +* rwatch: Set Watchpoints. (line 79) +* s (SingleKey TUI key): TUI Single Key Mode. (line 28) +* s ('step'): Continuing and Stepping. + (line 44) +* save breakpoints: Save Breakpoints. (line 9) +* save gdb-index: Index Files. (line 19) +* save tracepoints: save tracepoints. (line 6) +* save-tracepoints: save tracepoints. (line 6) +* sdireset: M32R/D. (line 44) +* sdistatus: M32R/D. (line 47) +* sds, a command: PowerPC Embedded. (line 93) +* search: Search. (line 9) +* section: Files. (line 199) +* select-frame: Frames. (line 51) +* self-insert (a, b, A, 1, !, ...): Commands For Text. (line 27) +* set: Help. (line 109) +* set ada trust-PAD-over-XVS: Ada Glitches. (line 42) +* set agent off: In-Process Agent. (line 47) +* set agent on: In-Process Agent. (line 38) +* set annotate: Annotations Overview. + (line 29) +* set architecture: Targets. (line 21) +* set args: Arguments. (line 21) +* set arm: ARM. (line 17) +* set auto-load gdb-scripts: Auto-loading sequences. + (line 13) +* set auto-load libthread-db: libthread_db.so.1 file. + (line 21) +* set auto-load local-gdbinit: Init File in the Current Directory. + (line 14) +* set auto-load off: Auto-loading. (line 32) +* set auto-load python-scripts: Python Auto-loading. (line 17) +* set auto-load safe-path: Auto-loading safe path. + (line 32) +* set auto-load scripts-directory: objfile-gdbdotext file. + (line 35) +* set auto-solib-add: Files. (line 305) +* set backtrace: Backtrace. (line 116) +* set basenames-may-differ: Files. (line 524) +* set board-address: M32R/D. (line 21) +* set breakpoint always-inserted: Set Breaks. (line 317) +* set breakpoint auto-hw: Set Breaks. (line 297) +* set breakpoint condition-evaluation: Set Breaks. (line 345) +* set breakpoint pending: Set Breaks. (line 266) +* set can-use-hw-watchpoints: Set Watchpoints. (line 116) +* set case-sensitive: Symbols. (line 27) +* set charset: Character Sets. (line 46) +* set check range: Range Checking. (line 34) +* set check type: Type Checking. (line 35) +* set circular-trace-buffer: Starting and Stopping Trace Experiments. + (line 93) +* set code-cache: Caching Target Data. (line 36) +* set coerce-float-to-double: ABI. (line 45) +* set com1base: DJGPP Native. (line 122) +* set com1irq: DJGPP Native. (line 122) +* set com2base: DJGPP Native. (line 122) +* set com2irq: DJGPP Native. (line 122) +* set com3base: DJGPP Native. (line 122) +* set com3irq: DJGPP Native. (line 122) +* set com4base: DJGPP Native. (line 122) +* set com4irq: DJGPP Native. (line 122) +* set complaints: Messages/Warnings. (line 29) +* set confirm: Messages/Warnings. (line 49) +* set cp-abi: ABI. (line 57) +* set cygwin-exceptions: Cygwin Native. (line 42) +* set data-directory: Data Files. (line 12) +* set dcache line-size: Caching Target Data. (line 60) +* set dcache size: Caching Target Data. (line 57) +* set debug: Debugging Output. (line 17) +* set debug aarch64: AArch64. (line 10) +* set debug auto-load: Auto-loading verbose mode. + (line 27) +* set debug darwin: Darwin. (line 9) +* set debug entry-values: Tail Call Frames. (line 47) +* set debug hppa: HPPA. (line 10) +* set debug libthread-db: Threads. (line 209) +* set debug mach-o: Darwin. (line 16) +* set debug mips: MIPS. (line 100) +* set debug monitor: Target Commands. (line 101) +* set debug nios2: Nios II. (line 10) +* set debug-file-directory: Separate Debug Files. + (line 67) +* set debugevents: Cygwin Native. (line 71) +* set debugexceptions: Cygwin Native. (line 82) +* set debugexec: Cygwin Native. (line 78) +* set debugmemory: Cygwin Native. (line 86) +* set default-collect: Tracepoint Actions. (line 134) +* set demangle-style: Print Settings. (line 427) +* set detach-on-fork: Forks. (line 54) +* set directories: Source Path. (line 118) +* set disable-randomization: Starting. (line 158) +* set disassemble-next-line: Machine Code. (line 143) +* set disassembly-flavor: Machine Code. (line 131) +* set disconnected-dprintf: Dynamic Printf. (line 83) +* set disconnected-tracing: Starting and Stopping Trace Experiments. + (line 55) +* set displaced-stepping: Maintenance Commands. + (line 66) +* set download-path: M32R/D. (line 15) +* set editing: Editing. (line 15) +* set endian: Byte Order. (line 13) +* set environment: Environment. (line 39) +* set exceptions, Hurd command: Hurd Native. (line 39) +* set exec-direction: Reverse Execution. (line 83) +* set exec-done-display: Debugging Output. (line 11) +* set exec-wrapper: Starting. (line 110) +* set extended-prompt: Prompt. (line 25) +* set extension-language: Show. (line 30) +* set follow-exec-mode: Forks. (line 101) +* set follow-fork-mode: Forks. (line 35) +* set frame-filter priority: Frame Filter Management. + (line 84) +* set gnutarget: Target Commands. (line 28) +* set hash, for remote monitors: Target Commands. (line 92) +* set height: Screen Size. (line 20) +* set history expansion: Command History. (line 67) +* set history filename: Command History. (line 26) +* set history save: Command History. (line 36) +* set history size: Command History. (line 45) +* set host-charset: Character Sets. (line 33) +* set inferior-tty: Input/Output. (line 49) +* set input-radix: Numbers. (line 14) +* set interactive-mode: Other Misc Settings. (line 6) +* set language: Manually. (line 9) +* set libthread-db-search-path: Threads. (line 171) +* set listsize: List. (line 33) +* set logging: Logging Output. (line 9) +* set mach-exceptions: Darwin. (line 27) +* set max-user-call-depth: Define. (line 78) +* set mem inaccessible-by-default: Memory Region Attributes. + (line 123) +* set mips abi: MIPS. (line 32) +* set mips compression: MIPS. (line 49) +* set mips mask-address: MIPS. (line 80) +* set mipsfpu: MIPS Embedded. (line 58) +* set monitor-prompt, MIPS remote: MIPS Embedded. (line 105) +* set monitor-warnings, MIPS remote: MIPS Embedded. (line 119) +* set multiple-symbols: Ambiguous Expressions. + (line 50) +* set new-console: Cygwin Native. (line 54) +* set new-group: Cygwin Native. (line 63) +* set non-stop: Non-Stop Mode. (line 38) +* set opaque-type-resolution: Symbols. (line 321) +* set osabi: ABI. (line 11) +* set output-radix: Numbers. (line 30) +* set overload-resolution: Debugging C Plus Plus. + (line 55) +* set pagination: Screen Size. (line 39) +* set powerpc: PowerPC Embedded. (line 51) +* set print: Print Settings. (line 11) +* set print entry-values: Print Settings. (line 206) +* set print frame-arguments: Print Settings. (line 154) +* set print inferior-events: Inferiors and Programs. + (line 117) +* set print thread-events: Threads. (line 150) +* set print type methods: Symbols. (line 44) +* set print type typedefs: Symbols. (line 57) +* set processor: Targets. (line 31) +* set procfs-file: SVR4 Process Information. + (line 74) +* set procfs-trace: SVR4 Process Information. + (line 68) +* set prompt: Prompt. (line 16) +* set python print-stack: Python Commands. (line 46) +* set radix: Numbers. (line 43) +* set range-stepping: Continuing and Stepping. + (line 220) +* set ravenscar task-switching off: Ravenscar Profile. (line 14) +* set ravenscar task-switching on: Ravenscar Profile. (line 10) +* set rdiheartbeat: ARM. (line 107) +* set rdiromatzero: ARM. (line 97) +* set record: Process Record and Replay. + (line 233) +* set record full: Process Record and Replay. + (line 121) +* set remote: Remote Configuration. + (line 6) +* set remote system-call-allowed: system. (line 37) +* set remote-mips64-transfers-32bit-regs: MIPS. (line 90) +* set remotecache: Caching Target Data. (line 20) +* set remoteflow: Remote Configuration. + (line 41) +* set retransmit-timeout: MIPS Embedded. (line 81) +* set schedule-multiple: All-Stop Mode. (line 66) +* set script-extension: Extending GDB. (line 27) +* set sdstimeout: PowerPC Embedded. (line 86) +* set server-address: M32R/D. (line 27) +* set sh calling-convention: Super-H. (line 9) +* set shell: Cygwin Native. (line 90) +* set signal-thread: Hurd Native. (line 21) +* set signals, Hurd command: Hurd Native. (line 11) +* set sigs, Hurd command: Hurd Native. (line 11) +* set sigthread: Hurd Native. (line 21) +* set solib-absolute-prefix: Files. (line 381) +* set solib-search-path: Files. (line 450) +* set spu: SPU. (line 38) +* set stack-cache: Caching Target Data. (line 28) +* set startup-with-shell: Starting. (line 135) +* set step-mode: Continuing and Stepping. + (line 90) +* set stop-on-solib-events: Files. (line 358) +* set stopped, Hurd command: Hurd Native. (line 31) +* set struct-convention: i386. (line 7) +* set substitute-path: Source Path. (line 125) +* set syn-garbage-limit, MIPS remote: MIPS Embedded. (line 96) +* set sysroot: Files. (line 381) +* set target-async: Background Execution. + (line 17) +* set target-charset: Character Sets. (line 28) +* set target-file-system-kind (unix|dos-based|auto): Files. (line 464) +* set target-wide-charset: Character Sets. (line 61) +* set task, Hurd commands: Hurd Native. (line 48) +* set tcp: Remote Configuration. + (line 116) +* set thread, Hurd command: Hurd Native. (line 90) +* set timeout: MIPS Embedded. (line 81) +* set trace-buffer-size: Starting and Stopping Trace Experiments. + (line 107) +* set trace-commands: Messages/Warnings. (line 65) +* set trace-notes: Starting and Stopping Trace Experiments. + (line 126) +* set trace-stop-notes: Starting and Stopping Trace Experiments. + (line 132) +* set trace-user: Starting and Stopping Trace Experiments. + (line 122) +* set trust-readonly-sections: Files. (line 261) +* set tui active-border-mode: TUI Configuration. (line 24) +* set tui border-kind: TUI Configuration. (line 9) +* set tui border-mode: TUI Configuration. (line 23) +* set unwind-on-terminating-exception: Calling. (line 46) +* set unwindonsignal: Calling. (line 35) +* set variable: Assignment. (line 16) +* set verbose: Messages/Warnings. (line 15) +* set watchdog: Maintenance Commands. + (line 407) +* set width: Screen Size. (line 20) +* set write: Patching. (line 15) +* set-mark (C-@): Miscellaneous Commands. + (line 32) +* set_debug_traps: Stub Contents. (line 10) +* share: Files. (line 334) +* sharedlibrary: Files. (line 334) +* shell: Shell Commands. (line 10) +* show: Help. (line 114) +* show ada trust-PAD-over-XVS: Ada Glitches. (line 42) +* show agent: In-Process Agent. (line 51) +* show annotate: Annotations Overview. + (line 34) +* show architecture: Targets. (line 21) +* show args: Arguments. (line 28) +* show arm: ARM. (line 21) +* show auto-load: Auto-loading. (line 45) +* show auto-load gdb-scripts: Auto-loading sequences. + (line 17) +* show auto-load libthread-db: libthread_db.so.1 file. + (line 25) +* show auto-load local-gdbinit: Init File in the Current Directory. + (line 18) +* show auto-load python-scripts: Python Auto-loading. (line 20) +* show auto-load safe-path: Auto-loading safe path. + (line 46) +* show auto-load scripts-directory: objfile-gdbdotext file. + (line 59) +* show auto-solib-add: Files. (line 322) +* show backtrace: Backtrace. (line 123) +* show basenames-may-differ: Files. (line 527) +* show board-address: M32R/D. (line 24) +* show breakpoint always-inserted: Set Breaks. (line 317) +* show breakpoint auto-hw: Set Breaks. (line 297) +* show breakpoint condition-evaluation: Set Breaks. (line 345) +* show breakpoint pending: Set Breaks. (line 266) +* show can-use-hw-watchpoints: Set Watchpoints. (line 119) +* show case-sensitive: Symbols. (line 40) +* show charset: Character Sets. (line 52) +* show check range: Range Checking. (line 34) +* show check type: Type Checking. (line 35) +* show circular-trace-buffer: Starting and Stopping Trace Experiments. + (line 100) +* show code-cache: Caching Target Data. (line 42) +* show coerce-float-to-double: ABI. (line 54) +* show com1base: DJGPP Native. (line 134) +* show com1irq: DJGPP Native. (line 134) +* show com2base: DJGPP Native. (line 134) +* show com2irq: DJGPP Native. (line 134) +* show com3base: DJGPP Native. (line 134) +* show com3irq: DJGPP Native. (line 134) +* show com4base: DJGPP Native. (line 134) +* show com4irq: DJGPP Native. (line 134) +* show commands: Command History. (line 80) +* show complaints: Messages/Warnings. (line 35) +* show configuration: Help. (line 147) +* show confirm: Messages/Warnings. (line 57) +* show convenience: Convenience Vars. (line 37) +* show copying: Help. (line 138) +* show cp-abi: ABI. (line 57) +* show cygwin-exceptions: Cygwin Native. (line 50) +* show data-directory: Data Files. (line 16) +* show dcache line-size: Caching Target Data. (line 68) +* show dcache size: Caching Target Data. (line 64) +* show debug: Debugging Output. (line 20) +* show debug auto-load: Auto-loading verbose mode. + (line 30) +* show debug darwin: Darwin. (line 13) +* show debug entry-values: Tail Call Frames. (line 55) +* show debug libthread-db: Threads. (line 209) +* show debug mach-o: Darwin. (line 23) +* show debug mips: MIPS. (line 104) +* show debug monitor: Target Commands. (line 105) +* show debug nios2: Nios II. (line 14) +* show debug-file-directory: Separate Debug Files. + (line 72) +* show default-collect: Tracepoint Actions. (line 142) +* show detach-on-fork: Forks. (line 69) +* show directories: Source Path. (line 122) +* show disassemble-next-line: Machine Code. (line 143) +* show disassembly-flavor: Machine Code. (line 140) +* show disconnected-dprintf: Dynamic Printf. (line 88) +* show disconnected-tracing: Starting and Stopping Trace Experiments. + (line 62) +* show displaced-stepping: Maintenance Commands. + (line 66) +* show download-path: M32R/D. (line 18) +* show editing: Editing. (line 22) +* show environment: Environment. (line 33) +* show exceptions, Hurd command: Hurd Native. (line 45) +* show exec-done-display: Debugging Output. (line 14) +* show extended-prompt: Prompt. (line 39) +* show follow-fork-mode: Forks. (line 48) +* show frame-filter priority: Frame Filter Management. + (line 91) +* show gnutarget: Target Commands. (line 40) +* show hash, for remote monitors: Target Commands. (line 98) +* show height: Screen Size. (line 20) +* show history: Command History. (line 72) +* show host-charset: Character Sets. (line 55) +* show inferior-tty: Input/Output. (line 52) +* show input-radix: Numbers. (line 35) +* show interactive-mode: Other Misc Settings. (line 20) +* show language: Show. (line 10) +* show libthread-db-search-path: Threads. (line 206) +* show listsize: List. (line 39) +* show logging: Logging Output. (line 22) +* show mach-exceptions: Darwin. (line 34) +* show max-user-call-depth: Define. (line 78) +* show mem inaccessible-by-default: Memory Region Attributes. + (line 129) +* show mips abi: MIPS. (line 46) +* show mips compression: MIPS. (line 72) +* show mips mask-address: MIPS. (line 86) +* show mipsfpu: MIPS Embedded. (line 58) +* show monitor-prompt, MIPS remote: MIPS Embedded. (line 115) +* show monitor-warnings, MIPS remote: MIPS Embedded. (line 125) +* show multiple-symbols: Ambiguous Expressions. + (line 70) +* show new-console: Cygwin Native. (line 59) +* show new-group: Cygwin Native. (line 68) +* show non-stop: Non-Stop Mode. (line 41) +* show opaque-type-resolution: Symbols. (line 336) +* show osabi: ABI. (line 11) +* show output-radix: Numbers. (line 38) +* show overload-resolution: Debugging C Plus Plus. + (line 72) +* show pagination: Screen Size. (line 45) +* show paths: Environment. (line 29) +* show print: Print Settings. (line 39) +* show print inferior-events: Inferiors and Programs. + (line 125) +* show print thread-events: Threads. (line 160) +* show print type methods: Symbols. (line 53) +* show print type typedefs: Symbols. (line 70) +* show processor: Targets. (line 31) +* show procfs-file: SVR4 Process Information. + (line 79) +* show procfs-trace: SVR4 Process Information. + (line 71) +* show prompt: Prompt. (line 19) +* show radix: Numbers. (line 43) +* show range-stepping: Continuing and Stepping. + (line 220) +* show ravenscar task-switching: Ravenscar Profile. (line 22) +* show rdiheartbeat: ARM. (line 112) +* show rdiromatzero: ARM. (line 104) +* show record: Process Record and Replay. + (line 239) +* show record full: Process Record and Replay. + (line 139) +* show remote: Remote Configuration. + (line 6) +* show remote system-call-allowed: system. (line 41) +* show remote-mips64-transfers-32bit-regs: MIPS. (line 96) +* show remotecache: Caching Target Data. (line 25) +* show remoteflow: Remote Configuration. + (line 45) +* show retransmit-timeout: MIPS Embedded. (line 81) +* show script-extension: Extending GDB. (line 27) +* show sdstimeout: PowerPC Embedded. (line 90) +* show server-address: M32R/D. (line 31) +* show sh calling-convention: Super-H. (line 22) +* show shell: Cygwin Native. (line 94) +* show signal-thread: Hurd Native. (line 27) +* show signals, Hurd command: Hurd Native. (line 17) +* show sigs, Hurd command: Hurd Native. (line 17) +* show sigthread: Hurd Native. (line 27) +* show solib-search-path: Files. (line 461) +* show spu: SPU. (line 43) +* show stack-cache: Caching Target Data. (line 33) +* show stop-on-solib-events: Files. (line 364) +* show stopped, Hurd command: Hurd Native. (line 36) +* show struct-convention: i386. (line 15) +* show substitute-path: Source Path. (line 162) +* show syn-garbage-limit, MIPS remote: MIPS Embedded. (line 101) +* show sysroot: Files. (line 447) +* show target-async: Background Execution. + (line 20) +* show target-charset: Character Sets. (line 58) +* show target-file-system-kind: Files. (line 464) +* show target-wide-charset: Character Sets. (line 67) +* show task, Hurd commands: Hurd Native. (line 56) +* show tcp: Remote Configuration. + (line 116) +* show thread, Hurd command: Hurd Native. (line 100) +* show timeout: MIPS Embedded. (line 81) +* show trace-buffer-size: Starting and Stopping Trace Experiments. + (line 114) +* show trace-notes: Starting and Stopping Trace Experiments. + (line 129) +* show trace-stop-notes: Starting and Stopping Trace Experiments. + (line 137) +* show trace-user: Starting and Stopping Trace Experiments. + (line 124) +* show unwind-on-terminating-exception: Calling. (line 54) +* show unwindonsignal: Calling. (line 42) +* show user: Define. (line 71) +* show values: Value History. (line 47) +* show verbose: Messages/Warnings. (line 21) +* show version: Help. (line 128) +* show warranty: Help. (line 142) +* show width: Screen Size. (line 20) +* show write: Patching. (line 26) +* show-all-if-ambiguous: Readline Init File Syntax. + (line 212) +* show-all-if-unmodified: Readline Init File Syntax. + (line 218) +* si ('stepi'): Continuing and Stepping. + (line 188) +* signal: Signaling. (line 6) +* signal annotation: Annotations for Running. + (line 42) +* signal-name annotation: Annotations for Running. + (line 22) +* signal-name-end annotation: Annotations for Running. + (line 22) +* signal-string annotation: Annotations for Running. + (line 22) +* signal-string-end annotation: Annotations for Running. + (line 22) +* SignalEvent.stop_signal: Events In Python. (line 91) +* signalled annotation: Annotations for Running. + (line 22) +* silent: Break Commands. (line 43) +* sim: Z8000. (line 15) +* sim, a command: Embedded Processors. (line 13) +* skip delete: Skipping Over Functions and Files. + (line 82) +* skip disable: Skipping Over Functions and Files. + (line 90) +* skip enable: Skipping Over Functions and Files. + (line 86) +* skip file: Skipping Over Functions and Files. + (line 46) +* skip function: Skipping Over Functions and Files. + (line 34) +* skip-completed-text: Readline Init File Syntax. + (line 227) +* skip-csi-sequence (): Miscellaneous Commands. + (line 51) +* source: Command Files. (line 17) +* source annotation: Source Annotations. (line 6) +* start: Starting. (line 78) +* start-kbd-macro (C-x (): Keyboard Macros. (line 6) +* starting annotation: Annotations for Running. + (line 6) +* STDERR: Basic Python. (line 140) +* STDERR <1>: Basic Python. (line 160) +* STDLOG: Basic Python. (line 143) +* STDLOG <1>: Basic Python. (line 163) +* STDOUT: Basic Python. (line 137) +* STDOUT <1>: Basic Python. (line 157) +* step: Continuing and Stepping. + (line 44) +* step&: Background Execution. + (line 39) +* stepi: Continuing and Stepping. + (line 188) +* stepi&: Background Execution. + (line 42) +* stop, a pseudo-command: Hooks. (line 21) +* stopping annotation: Annotations for Running. + (line 6) +* strace: Create and Delete Tracepoints. + (line 76) +* symbol-file: Files. (line 45) +* Symbol.addr_class: Symbols In Python. (line 74) +* Symbol.is_argument: Symbols In Python. (line 84) +* Symbol.is_constant: Symbols In Python. (line 87) +* Symbol.is_function: Symbols In Python. (line 90) +* Symbol.is_valid: Symbols In Python. (line 98) +* Symbol.is_variable: Symbols In Python. (line 93) +* Symbol.line: Symbols In Python. (line 57) +* Symbol.linkage_name: Symbols In Python. (line 65) +* Symbol.name: Symbols In Python. (line 61) +* Symbol.needs_frame: Symbols In Python. (line 79) +* Symbol.print_name: Symbols In Python. (line 69) +* Symbol.symtab: Symbols In Python. (line 52) +* Symbol.type: Symbols In Python. (line 47) +* Symbol.value: Symbols In Python. (line 105) +* SYMBOL_FUNCTIONS_DOMAIN: Symbols In Python. (line 128) +* SYMBOL_LABEL_DOMAIN: Symbols In Python. (line 123) +* SYMBOL_LOC_ARG: Symbols In Python. (line 145) +* SYMBOL_LOC_BLOCK: Symbols In Python. (line 161) +* SYMBOL_LOC_COMPUTED: Symbols In Python. (line 171) +* SYMBOL_LOC_CONST: Symbols In Python. (line 139) +* SYMBOL_LOC_CONST_BYTES: Symbols In Python. (line 163) +* SYMBOL_LOC_LOCAL: Symbols In Python. (line 156) +* SYMBOL_LOC_OPTIMIZED_OUT: Symbols In Python. (line 169) +* SYMBOL_LOC_REF_ARG: Symbols In Python. (line 148) +* SYMBOL_LOC_REGISTER: Symbols In Python. (line 143) +* SYMBOL_LOC_REGPARM_ADDR: Symbols In Python. (line 152) +* SYMBOL_LOC_STATIC: Symbols In Python. (line 141) +* SYMBOL_LOC_TYPEDEF: Symbols In Python. (line 158) +* SYMBOL_LOC_UNDEF: Symbols In Python. (line 137) +* SYMBOL_LOC_UNRESOLVED: Symbols In Python. (line 165) +* SYMBOL_STRUCT_DOMAIN: Symbols In Python. (line 121) +* SYMBOL_TYPES_DOMAIN: Symbols In Python. (line 130) +* SYMBOL_UNDEF_DOMAIN: Symbols In Python. (line 115) +* SYMBOL_VARIABLES_DOMAIN: Symbols In Python. (line 125) +* SYMBOL_VAR_DOMAIN: Symbols In Python. (line 118) +* Symtab.filename: Symbol Tables In Python. + (line 43) +* Symtab.fullname: Symbol Tables In Python. + (line 60) +* Symtab.global_block: Symbol Tables In Python. + (line 63) +* Symtab.is_valid: Symbol Tables In Python. + (line 53) +* Symtab.linetable: Symbol Tables In Python. + (line 71) +* Symtab.objfile: Symbol Tables In Python. + (line 47) +* Symtab.static_block: Symbol Tables In Python. + (line 67) +* Symtab_and_line.is_valid: Symbol Tables In Python. + (line 34) +* Symtab_and_line.last: Symbol Tables In Python. + (line 24) +* Symtab_and_line.line: Symbol Tables In Python. + (line 28) +* Symtab_and_line.pc: Symbol Tables In Python. + (line 20) +* Symtab_and_line.symtab: Symbol Tables In Python. + (line 16) +* sysinfo: DJGPP Native. (line 19) +* tab-insert (M-): Commands For Text. (line 24) +* tabset: TUI Commands. (line 84) +* target: Target Commands. (line 49) +* target array: MIPS Embedded. (line 48) +* target ctf: Trace Files. (line 28) +* target dbug: M68K. (line 9) +* target ddb PORT: MIPS Embedded. (line 40) +* target dink32: PowerPC Embedded. (line 72) +* target lsi PORT: MIPS Embedded. (line 43) +* target m32r: M32R/D. (line 6) +* target m32rsdi: M32R/D. (line 9) +* target mips PORT: MIPS Embedded. (line 14) +* target op50n: PA. (line 6) +* target pmon PORT: MIPS Embedded. (line 37) +* target ppcbug: PowerPC Embedded. (line 75) +* target ppcbug1: PowerPC Embedded. (line 76) +* target r3900: MIPS Embedded. (line 45) +* target rdi: ARM. (line 6) +* target rdp: ARM. (line 11) +* target record: Process Record and Replay. + (line 38) +* target record-btrace: Process Record and Replay. + (line 38) +* target record-full: Process Record and Replay. + (line 38) +* target sds: PowerPC Embedded. (line 79) +* target sim, with Z8000: Z8000. (line 15) +* target sparclite: Sparclite. (line 6) +* target tfile: Trace Files. (line 28) +* target vxworks: VxWorks. (line 6) +* target w89k: PA. (line 9) +* task (Ada): Ada Tasks. (line 103) +* tbreak: Set Breaks. (line 54) +* tcatch: Set Catchpoints. (line 251) +* tdump: tdump. (line 6) +* teval (tracepoints): Tracepoint Actions. (line 110) +* tfile: Trace Files. (line 28) +* tfind: tfind. (line 6) +* thbreak: Set Breaks. (line 79) +* this, inside C++ member functions: C Plus Plus Expressions. + (line 20) +* thread apply: Threads. (line 116) +* thread find: Threads. (line 136) +* thread name: Threads. (line 125) +* thread THREADNO: Threads. (line 94) +* thread-info: GDB/MI Support Commands. + (line 86) +* ThreadEvent.inferior_thread: Events In Python. (line 54) +* tilde-expand (M-~): Miscellaneous Commands. + (line 29) +* tload, M32R: M32R/D. (line 39) +* trace: Create and Delete Tracepoints. + (line 6) +* transpose-chars (C-t): Commands For Text. (line 30) +* transpose-words (M-t): Commands For Text. (line 36) +* tsave: Trace Files. (line 12) +* tstart [ NOTES ]: Starting and Stopping Trace Experiments. + (line 6) +* tstatus: Starting and Stopping Trace Experiments. + (line 27) +* tstop [ NOTES ]: Starting and Stopping Trace Experiments. + (line 16) +* tty: Input/Output. (line 23) +* tui reg: TUI Commands. (line 61) +* tvariable: Trace State Variables. + (line 26) +* Type.array: Types In Python. (line 103) +* Type.code: Types In Python. (line 33) +* Type.const: Types In Python. (line 124) +* Type.fields: Types In Python. (line 54) +* Type.name: Types In Python. (line 37) +* Type.pointer: Types In Python. (line 147) +* Type.range: Types In Python. (line 137) +* Type.reference: Types In Python. (line 143) +* Type.sizeof: Types In Python. (line 41) +* Type.strip_typedefs: Types In Python. (line 151) +* Type.tag: Types In Python. (line 46) +* Type.target: Types In Python. (line 155) +* Type.template_argument: Types In Python. (line 169) +* Type.unqualified: Types In Python. (line 132) +* Type.vector: Types In Python. (line 111) +* Type.volatile: Types In Python. (line 128) +* TYPE_CODE_ARRAY: Types In Python. (line 187) +* TYPE_CODE_BITSTRING: Types In Python. (line 225) +* TYPE_CODE_BOOL: Types In Python. (line 246) +* TYPE_CODE_CHAR: Types In Python. (line 243) +* TYPE_CODE_COMPLEX: Types In Python. (line 249) +* TYPE_CODE_DECFLOAT: Types In Python. (line 258) +* TYPE_CODE_ENUM: Types In Python. (line 196) +* TYPE_CODE_ERROR: Types In Python. (line 228) +* TYPE_CODE_FLAGS: Types In Python. (line 199) +* TYPE_CODE_FLT: Types In Python. (line 208) +* TYPE_CODE_FUNC: Types In Python. (line 202) +* TYPE_CODE_INT: Types In Python. (line 205) +* TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 261) +* TYPE_CODE_MEMBERPTR: Types In Python. (line 237) +* TYPE_CODE_METHOD: Types In Python. (line 231) +* TYPE_CODE_METHODPTR: Types In Python. (line 234) +* TYPE_CODE_NAMESPACE: Types In Python. (line 255) +* TYPE_CODE_PTR: Types In Python. (line 184) +* TYPE_CODE_RANGE: Types In Python. (line 217) +* TYPE_CODE_REF: Types In Python. (line 240) +* TYPE_CODE_SET: Types In Python. (line 214) +* TYPE_CODE_STRING: Types In Python. (line 220) +* TYPE_CODE_STRUCT: Types In Python. (line 190) +* TYPE_CODE_TYPEDEF: Types In Python. (line 252) +* TYPE_CODE_UNION: Types In Python. (line 193) +* TYPE_CODE_VOID: Types In Python. (line 211) +* u (SingleKey TUI key): TUI Single Key Mode. (line 31) +* u ('until'): Continuing and Stepping. + (line 116) +* undefined-command-error-code: GDB/MI Support Commands. + (line 101) +* undisplay: Auto Display. (line 45) +* undo (C-_ or C-x C-u): Miscellaneous Commands. + (line 22) +* universal-argument (): Numeric Arguments. (line 10) +* unix-filename-rubout (): Commands For Killing. + (line 32) +* unix-line-discard (C-u): Commands For Killing. + (line 12) +* unix-word-rubout (C-w): Commands For Killing. + (line 28) +* unset environment: Environment. (line 55) +* unset substitute-path: Source Path. (line 154) +* until: Continuing and Stepping. + (line 116) +* until&: Background Execution. + (line 57) +* up: Selection. (line 35) +* Up: TUI Keys. (line 53) +* up-silently: Selection. (line 64) +* upcase-word (M-u): Commands For Text. (line 41) +* update: TUI Commands. (line 76) +* upload, M32R: M32R/D. (line 34) +* use_dbt_break: M32R/D. (line 64) +* use_debug_dma: M32R/D. (line 53) +* use_ib_break: M32R/D. (line 61) +* use_mon_code: M32R/D. (line 57) +* v (SingleKey TUI key): TUI Single Key Mode. (line 34) +* Value.address: Values From Inferior. + (line 51) +* Value.cast: Values From Inferior. + (line 125) +* Value.dereference: Values From Inferior. + (line 131) +* Value.dynamic_cast: Values From Inferior. + (line 209) +* Value.dynamic_type: Values From Inferior. + (line 65) +* Value.fetch_lazy: Values From Inferior. + (line 271) +* Value.is_lazy: Values From Inferior. + (line 80) +* Value.is_optimized_out: Values From Inferior. + (line 56) +* Value.lazy_string: Values From Inferior. + (line 249) +* Value.referenced_value: Values From Inferior. + (line 184) +* Value.reinterpret_cast: Values From Inferior. + (line 213) +* Value.string: Values From Inferior. + (line 217) +* Value.type: Values From Inferior. + (line 61) +* Value.__init__: Values From Inferior. + (line 93) +* vi-editing-mode (M-C-j): Miscellaneous Commands. + (line 91) +* visible-stats: Readline Init File Syntax. + (line 240) +* vxworks-timeout: VxWorks. (line 22) +* w (SingleKey TUI key): TUI Single Key Mode. (line 37) +* watch: Set Watchpoints. (line 42) +* watchpoint annotation: Annotations for Running. + (line 50) +* whatis: Symbols. (line 103) +* where: Backtrace. (line 46) +* while: Command Files. (line 85) +* while-stepping (tracepoints): Tracepoint Actions. (line 118) +* winheight: TUI Commands. (line 80) +* WP_ACCESS: Breakpoints In Python. + (line 70) +* WP_READ: Breakpoints In Python. + (line 64) +* WP_WRITE: Breakpoints In Python. + (line 67) +* x (examine memory): Memory. (line 9) +* x(examine), and info line: Machine Code. (line 30) +* yank (C-y): Commands For Killing. + (line 59) +* yank-last-arg (M-. or M-_): Commands For History. + (line 64) +* yank-nth-arg (M-C-y): Commands For History. + (line 55) +* yank-pop (M-y): Commands For Killing. + (line 62) + diff --git a/util/X86MAC64/share/info/stabs.info b/util/X86MAC64/share/info/stabs.info new file mode 100644 index 0000000000..07c937355b --- /dev/null +++ b/util/X86MAC64/share/info/stabs.info @@ -0,0 +1,4577 @@ +This is stabs.info, produced by makeinfo version 5.1 from stabs.texinfo. + +Copyright (C) 1992-2014 Free Software Foundation, Inc. Contributed by +Cygnus Support. Written by Julia Menapace, Jim Kingdon, and David +MacKenzie. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Stabs: (stabs). The "stabs" debugging information format. +END-INFO-DIR-ENTRY + + This document describes the stabs debugging symbol tables. + + Copyright (C) 1992-2014 Free Software Foundation, Inc. Contributed +by Cygnus Support. Written by Julia Menapace, Jim Kingdon, and David +MacKenzie. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". + + +File: stabs.info, Node: Top, Next: Overview, Up: (dir) + +The "stabs" representation of debugging information +*************************************************** + +This document describes the stabs debugging format. + +* Menu: + +* Overview:: Overview of stabs +* Program Structure:: Encoding of the structure of the program +* Constants:: Constants +* Variables:: +* Types:: Type definitions +* Macro define and undefine:: Representation of #define and #undef +* Symbol Tables:: Symbol information in symbol tables +* Cplusplus:: Stabs specific to C++ +* Stab Types:: Symbol types in a.out files +* Symbol Descriptors:: Table of symbol descriptors +* Type Descriptors:: Table of type descriptors +* Expanded Reference:: Reference information by stab type +* Questions:: Questions and anomalies +* Stab Sections:: In some object file formats, stabs are + in sections. +* GNU Free Documentation License:: The license for this documentation +* Symbol Types Index:: Index of symbolic stab symbol type names. + + +File: stabs.info, Node: Overview, Next: Program Structure, Prev: Top, Up: Top + +1 Overview of Stabs +******************* + +"Stabs" refers to a format for information that describes a program to a +debugger. This format was apparently invented by Peter Kessler at the +University of California at Berkeley, for the 'pdx' Pascal debugger; the +format has spread widely since then. + + This document is one of the few published sources of documentation on +stabs. It is believed to be comprehensive for stabs used by C. The +lists of symbol descriptors (*note Symbol Descriptors::) and type +descriptors (*note Type Descriptors::) are believed to be completely +comprehensive. Stabs for COBOL-specific features and for variant +records (used by Pascal and Modula-2) are poorly documented here. + + Other sources of information on stabs are 'Dbx and Dbxtool +Interfaces', 2nd edition, by Sun, 1988, and 'AIX Version 3.2 Files +Reference', Fourth Edition, September 1992, "dbx Stabstring Grammar" in +the a.out section, page 2-31. This document is believed to incorporate +the information from those two sources except where it explicitly +directs you to them for more information. + +* Menu: + +* Flow:: Overview of debugging information flow +* Stabs Format:: Overview of stab format +* String Field:: The string field +* C Example:: A simple example in C source +* Assembly Code:: The simple example at the assembly level + + +File: stabs.info, Node: Flow, Next: Stabs Format, Up: Overview + +1.1 Overview of Debugging Information Flow +========================================== + +The GNU C compiler compiles C source in a '.c' file into assembly +language in a '.s' file, which the assembler translates into a '.o' +file, which the linker combines with other '.o' files and libraries to +produce an executable file. + + With the '-g' option, GCC puts in the '.s' file additional debugging +information, which is slightly transformed by the assembler and linker, +and carried through into the final executable. This debugging +information describes features of the source file like line numbers, the +types and scopes of variables, and function names, parameters, and +scopes. + + For some object file formats, the debugging information is +encapsulated in assembler directives known collectively as "stab" +(symbol table) directives, which are interspersed with the generated +code. Stabs are the native format for debugging information in the +a.out and XCOFF object file formats. The GNU tools can also emit stabs +in the COFF and ECOFF object file formats. + + The assembler adds the information from stabs to the symbol +information it places by default in the symbol table and the string +table of the '.o' file it is building. The linker consolidates the '.o' +files into one executable file, with one symbol table and one string +table. Debuggers use the symbol and string tables in the executable as +a source of debugging information about the program. + + +File: stabs.info, Node: Stabs Format, Next: String Field, Prev: Flow, Up: Overview + +1.2 Overview of Stab Format +=========================== + +There are three overall formats for stab assembler directives, +differentiated by the first word of the stab. The name of the directive +describes which combination of four possible data fields follows. It is +either '.stabs' (string), '.stabn' (number), or '.stabd' (dot). IBM's +XCOFF assembler uses '.stabx' (and some other directives such as '.file' +and '.bi') instead of '.stabs', '.stabn' or '.stabd'. + + The overall format of each class of stab is: + + .stabs "STRING",TYPE,OTHER,DESC,VALUE + .stabn TYPE,OTHER,DESC,VALUE + .stabd TYPE,OTHER,DESC + .stabx "STRING",VALUE,TYPE,SDB-TYPE + + For '.stabn' and '.stabd', there is no STRING (the 'n_strx' field is +zero; see *note Symbol Tables::). For '.stabd', the VALUE field is +implicit and has the value of the current file location. For '.stabx', +the SDB-TYPE field is unused for stabs and can always be set to zero. +The OTHER field is almost always unused and can be set to zero. + + The number in the TYPE field gives some basic information about which +type of stab this is (or whether it _is_ a stab, as opposed to an +ordinary symbol). Each valid type number defines a different stab type; +further, the stab type defines the exact interpretation of, and possible +values for, any remaining STRING, DESC, or VALUE fields present in the +stab. *Note Stab Types::, for a list in numeric order of the valid TYPE +field values for stab directives. + + +File: stabs.info, Node: String Field, Next: C Example, Prev: Stabs Format, Up: Overview + +1.3 The String Field +==================== + +For most stabs the string field holds the meat of the debugging +information. The flexible nature of this field is what makes stabs +extensible. For some stab types the string field contains only a name. +For other stab types the contents can be a great deal more complex. + + The overall format of the string field for most stab types is: + + "NAME:SYMBOL-DESCRIPTOR TYPE-INFORMATION" + + NAME is the name of the symbol represented by the stab; it can +contain a pair of colons (*note Nested Symbols::). NAME can be omitted, +which means the stab represents an unnamed object. For example, +':t10=*2' defines type 10 as a pointer to type 2, but does not give the +type a name. Omitting the NAME field is supported by AIX dbx and GDB +after about version 4.8, but not other debuggers. GCC sometimes uses a +single space as the name instead of omitting the name altogether; +apparently that is supported by most debuggers. + + The SYMBOL-DESCRIPTOR following the ':' is an alphabetic character +that tells more specifically what kind of symbol the stab represents. +If the SYMBOL-DESCRIPTOR is omitted, but type information follows, then +the stab represents a local variable. For a list of symbol descriptors, +see *note Symbol Descriptors::. The 'c' symbol descriptor is an +exception in that it is not followed by type information. *Note +Constants::. + + TYPE-INFORMATION is either a TYPE-NUMBER, or 'TYPE-NUMBER='. A +TYPE-NUMBER alone is a type reference, referring directly to a type that +has already been defined. + + The 'TYPE-NUMBER=' form is a type definition, where the number +represents a new type which is about to be defined. The type definition +may refer to other types by number, and those type numbers may be +followed by '=' and nested definitions. Also, the Lucid compiler will +repeat 'TYPE-NUMBER=' more than once if it wants to define several type +numbers at once. + + In a type definition, if the character that follows the equals sign +is non-numeric then it is a TYPE-DESCRIPTOR, and tells what kind of type +is about to be defined. Any other values following the TYPE-DESCRIPTOR +vary, depending on the TYPE-DESCRIPTOR. *Note Type Descriptors::, for a +list of TYPE-DESCRIPTOR values. If a number follows the '=' then the +number is a TYPE-REFERENCE. For a full description of types, *note +Types::. + + A TYPE-NUMBER is often a single number. The GNU and Sun tools +additionally permit a TYPE-NUMBER to be a pair +(FILE-NUMBER,FILETYPE-NUMBER) (the parentheses appear in the string, and +serve to distinguish the two cases). The FILE-NUMBER is 0 for the base +source file, 1 for the first included file, 2 for the next, and so on. +The FILETYPE-NUMBER is a number starting with 1 which is incremented for +each new type defined in the file. (Separating the file number and the +type number permits the 'N_BINCL' optimization to succeed more often; +see *note Include Files::). + + There is an AIX extension for type attributes. Following the '=' are +any number of type attributes. Each one starts with '@' and ends with +';'. Debuggers, including AIX's dbx and GDB 4.10, skip any type +attributes they do not recognize. GDB 4.9 and other versions of dbx may +not do this. Because of a conflict with C++ (*note Cplusplus::), new +attributes should not be defined which begin with a digit, '(', or '-'; +GDB may be unable to distinguish those from the C++ type descriptor '@'. +The attributes are: + +'aBOUNDARY' + BOUNDARY is an integer specifying the alignment. I assume it + applies to all variables of this type. + +'pINTEGER' + Pointer class (for checking). Not sure what this means, or how + INTEGER is interpreted. + +'P' + Indicate this is a packed type, meaning that structure fields or + array elements are placed more closely in memory, to save memory at + the expense of speed. + +'sSIZE' + Size in bits of a variable of this type. This is fully supported + by GDB 4.11 and later. + +'S' + Indicate that this type is a string instead of an array of + characters, or a bitstring instead of a set. It doesn't change the + layout of the data being represented, but does enable the debugger + to know which type it is. + +'V' + Indicate that this type is a vector instead of an array. The only + major difference between vectors and arrays is that vectors are + passed by value instead of by reference (vector coprocessor + extension). + + All of this can make the string field quite long. All versions of +GDB, and some versions of dbx, can handle arbitrarily long strings. But +many versions of dbx (or assemblers or linkers, I'm not sure which) +cretinously limit the strings to about 80 characters, so compilers which +must work with such systems need to split the '.stabs' directive into +several '.stabs' directives. Each stab duplicates every field except +the string field. The string field of every stab except the last is +marked as continued with a backslash at the end (in the assembly code +this may be written as a double backslash, depending on the assembler). +Removing the backslashes and concatenating the string fields of each +stab produces the original, long string. Just to be incompatible (or so +they don't have to worry about what the assembler does with +backslashes), AIX can use '?' instead of backslash. + + +File: stabs.info, Node: C Example, Next: Assembly Code, Prev: String Field, Up: Overview + +1.4 A Simple Example in C Source +================================ + +To get the flavor of how stabs describe source information for a C +program, let's look at the simple program: + + main() + { + printf("Hello world"); + } + + When compiled with '-g', the program above yields the following '.s' +file. Line numbers have been added to make it easier to refer to parts +of the '.s' file in the description of the stabs that follows. + + +File: stabs.info, Node: Assembly Code, Prev: C Example, Up: Overview + +1.5 The Simple Example at the Assembly Level +============================================ + +This simple "hello world" example demonstrates several of the stab types +used to describe C language source files. + + 1 gcc2_compiled.: + 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 + 3 .stabs "hello.c",100,0,0,Ltext0 + 4 .text + 5 Ltext0: + 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 + 7 .stabs "char:t2=r2;0;127;",128,0,0,0 + 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0 + 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 + 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0 + 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0 + 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0 + 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0 + 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0 + 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0 + 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0 + 17 .stabs "float:t12=r1;4;0;",128,0,0,0 + 18 .stabs "double:t13=r1;8;0;",128,0,0,0 + 19 .stabs "long double:t14=r1;8;0;",128,0,0,0 + 20 .stabs "void:t15=15",128,0,0,0 + 21 .align 4 + 22 LC0: + 23 .ascii "Hello, world!\12\0" + 24 .align 4 + 25 .global _main + 26 .proc 1 + 27 _main: + 28 .stabn 68,0,4,LM1 + 29 LM1: + 30 !#PROLOGUE# 0 + 31 save %sp,-136,%sp + 32 !#PROLOGUE# 1 + 33 call ___main,0 + 34 nop + 35 .stabn 68,0,5,LM2 + 36 LM2: + 37 LBB2: + 38 sethi %hi(LC0),%o1 + 39 or %o1,%lo(LC0),%o0 + 40 call _printf,0 + 41 nop + 42 .stabn 68,0,6,LM3 + 43 LM3: + 44 LBE2: + 45 .stabn 68,0,6,LM4 + 46 LM4: + 47 L1: + 48 ret + 49 restore + 50 .stabs "main:F1",36,0,0,_main + 51 .stabn 192,0,0,LBB2 + 52 .stabn 224,0,0,LBE2 + + +File: stabs.info, Node: Program Structure, Next: Constants, Prev: Overview, Up: Top + +2 Encoding the Structure of the Program +*************************************** + +The elements of the program structure that stabs encode include the name +of the main function, the names of the source and include files, the +line numbers, procedure names and types, and the beginnings and ends of +blocks of code. + +* Menu: + +* Main Program:: Indicate what the main program is +* Source Files:: The path and name of the source file +* Include Files:: Names of include files +* Line Numbers:: +* Procedures:: +* Nested Procedures:: +* Block Structure:: +* Alternate Entry Points:: Entering procedures except at the beginning. + + +File: stabs.info, Node: Main Program, Next: Source Files, Up: Program Structure + +2.1 Main Program +================ + +Most languages allow the main program to have any name. The 'N_MAIN' +stab type tells the debugger the name that is used in this program. +Only the string field is significant; it is the name of a function which +is the main program. Most C compilers do not use this stab (they expect +the debugger to assume that the name is 'main'), but some C compilers +emit an 'N_MAIN' stab for the 'main' function. I'm not sure how XCOFF +handles this. + + +File: stabs.info, Node: Source Files, Next: Include Files, Prev: Main Program, Up: Program Structure + +2.2 Paths and Names of the Source Files +======================================= + +Before any other stabs occur, there must be a stab specifying the source +file. This information is contained in a symbol of stab type 'N_SO'; +the string field contains the name of the file. The value of the symbol +is the start address of the portion of the text section corresponding to +that file. + + Some compilers use the desc field to indicate the language of the +source file. Sun's compilers started this usage, and the first +constants are derived from their documentation. Languages added by +gcc/gdb start at 0x32 to avoid conflict with languages Sun may add in +the future. A desc field with a value 0 indicates that no language has +been specified via this mechanism. + +'N_SO_AS' (0x1) + Assembly language +'N_SO_C' (0x2) + K&R traditional C +'N_SO_ANSI_C' (0x3) + ANSI C +'N_SO_CC' (0x4) + C++ +'N_SO_FORTRAN' (0x5) + Fortran +'N_SO_PASCAL' (0x6) + Pascal +'N_SO_FORTRAN90' (0x7) + Fortran90 +'N_SO_OBJC' (0x32) + Objective-C +'N_SO_OBJCPLUS' (0x33) + Objective-C++ + + Some compilers (for example, GCC2 and SunOS4 '/bin/cc') also include +the directory in which the source was compiled, in a second 'N_SO' +symbol preceding the one containing the file name. This symbol can be +distinguished by the fact that it ends in a slash. Code from the +'cfront' C++ compiler can have additional 'N_SO' symbols for nonexistent +source files after the 'N_SO' for the real source file; these are +believed to contain no useful information. + + For example: + + .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 # 100 is N_SO + .stabs "hello.c",100,0,0,Ltext0 + .text + Ltext0: + + Instead of 'N_SO' symbols, XCOFF uses a '.file' assembler directive +which assembles to a 'C_FILE' symbol; explaining this in detail is +outside the scope of this document. + + If it is useful to indicate the end of a source file, this is done +with an 'N_SO' symbol with an empty string for the name. The value is +the address of the end of the text section for the file. For some +systems, there is no indication of the end of a source file, and you +just need to figure it ended when you see an 'N_SO' for a different +source file, or a symbol ending in '.o' (which at least some linkers +insert to mark the start of a new '.o' file). + + +File: stabs.info, Node: Include Files, Next: Line Numbers, Prev: Source Files, Up: Program Structure + +2.3 Names of Include Files +========================== + +There are several schemes for dealing with include files: the +traditional 'N_SOL' approach, Sun's 'N_BINCL' approach, and the XCOFF +'C_BINCL' approach (which despite the similar name has little in common +with 'N_BINCL'). + + An 'N_SOL' symbol specifies which include file subsequent symbols +refer to. The string field is the name of the file and the value is the +text address corresponding to the end of the previous include file and +the start of this one. To specify the main source file again, use an +'N_SOL' symbol with the name of the main source file. + + The 'N_BINCL' approach works as follows. An 'N_BINCL' symbol +specifies the start of an include file. In an object file, only the +string is significant; the linker puts data into some of the other +fields. The end of the include file is marked by an 'N_EINCL' symbol +(which has no string field). In an object file, there is no significant +data in the 'N_EINCL' symbol. 'N_BINCL' and 'N_EINCL' can be nested. + + If the linker detects that two source files have identical stabs +between an 'N_BINCL' and 'N_EINCL' pair (as will generally be the case +for a header file), then it only puts out the stabs once. Each +additional occurrence is replaced by an 'N_EXCL' symbol. I believe the +GNU linker and the Sun (both SunOS4 and Solaris) linker are the only +ones which supports this feature. + + A linker which supports this feature will set the value of a +'N_BINCL' symbol to the total of all the characters in the stabs strings +included in the header file, omitting any file numbers. The value of an +'N_EXCL' symbol is the same as the value of the 'N_BINCL' symbol it +replaces. This information can be used to match up 'N_EXCL' and +'N_BINCL' symbols which have the same filename. The 'N_EINCL' value, +and the values of the other and description fields for all three, appear +to always be zero. + + For the start of an include file in XCOFF, use the '.bi' assembler +directive, which generates a 'C_BINCL' symbol. A '.ei' directive, which +generates a 'C_EINCL' symbol, denotes the end of the include file. Both +directives are followed by the name of the source file in quotes, which +becomes the string for the symbol. The value of each symbol, produced +automatically by the assembler and linker, is the offset into the +executable of the beginning (inclusive, as you'd expect) or end +(inclusive, as you would not expect) of the portion of the COFF line +table that corresponds to this include file. 'C_BINCL' and 'C_EINCL' do +not nest. + + +File: stabs.info, Node: Line Numbers, Next: Procedures, Prev: Include Files, Up: Program Structure + +2.4 Line Numbers +================ + +An 'N_SLINE' symbol represents the start of a source line. The desc +field contains the line number and the value contains the code address +for the start of that source line. On most machines the address is +absolute; for stabs in sections (*note Stab Sections::), it is relative +to the function in which the 'N_SLINE' symbol occurs. + + GNU documents 'N_DSLINE' and 'N_BSLINE' symbols for line numbers in +the data or bss segments, respectively. They are identical to 'N_SLINE' +but are relocated differently by the linker. They were intended to be +used to describe the source location of a variable declaration, but I +believe that GCC2 actually puts the line number in the desc field of the +stab for the variable itself. GDB has been ignoring these symbols +(unless they contain a string field) since at least GDB 3.5. + + For single source lines that generate discontiguous code, such as +flow of control statements, there may be more than one line number entry +for the same source line. In this case there is a line number entry at +the start of each code range, each with the same line number. + + XCOFF does not use stabs for line numbers. Instead, it uses COFF +line numbers (which are outside the scope of this document). Standard +COFF line numbers cannot deal with include files, but in XCOFF this is +fixed with the 'C_BINCL' method of marking include files (*note Include +Files::). + + +File: stabs.info, Node: Procedures, Next: Nested Procedures, Prev: Line Numbers, Up: Program Structure + +2.5 Procedures +============== + +All of the following stabs normally use the 'N_FUN' symbol type. +However, Sun's 'acc' compiler on SunOS4 uses 'N_GSYM' and 'N_STSYM', +which means that the value of the stab for the function is useless and +the debugger must get the address of the function from the non-stab +symbols instead. On systems where non-stab symbols have leading +underscores, the stabs will lack underscores and the debugger needs to +know about the leading underscore to match up the stab and the non-stab +symbol. BSD Fortran is said to use 'N_FNAME' with the same restriction; +the value of the symbol is not useful (I'm not sure it really does use +this, because GDB doesn't handle this and no one has complained). + + A function is represented by an 'F' symbol descriptor for a global +(extern) function, and 'f' for a static (local) function. For a.out, +the value of the symbol is the address of the start of the function; it +is already relocated. For stabs in ELF, the SunPRO compiler version +2.0.1 and GCC put out an address which gets relocated by the linker. In +a future release SunPRO is planning to put out zero, in which case the +address can be found from the ELF (non-stab) symbol. Because looking +things up in the ELF symbols would probably be slow, I'm not sure how to +find which symbol of that name is the right one, and this doesn't +provide any way to deal with nested functions, it would probably be +better to make the value of the stab an address relative to the start of +the file, or just absolute. See *note ELF Linker Relocation:: for more +information on linker relocation of stabs in ELF files. For XCOFF, the +stab uses the 'C_FUN' storage class and the value of the stab is +meaningless; the address of the function can be found from the csect +symbol (XTY_LD/XMC_PR). + + The type information of the stab represents the return type of the +function; thus 'foo:f5' means that foo is a function returning type 5. +There is no need to try to get the line number of the start of the +function from the stab for the function; it is in the next 'N_SLINE' +symbol. + + Some compilers (such as Sun's Solaris compiler) support an extension +for specifying the types of the arguments. I suspect this extension is +not used for old (non-prototyped) function definitions in C. If the +extension is in use, the type information of the stab for the function +is followed by type information for each argument, with each argument +preceded by ';'. An argument type of 0 means that additional arguments +are being passed, whose types and number may vary ('...' in ANSI C). GDB +has tolerated this extension (parsed the syntax, if not necessarily used +the information) since at least version 4.8; I don't know whether all +versions of dbx tolerate it. The argument types given here are not +redundant with the symbols for the formal parameters (*note +Parameters::); they are the types of the arguments as they are passed, +before any conversions might take place. For example, if a C function +which is declared without a prototype takes a 'float' argument, the +value is passed as a 'double' but then converted to a 'float'. +Debuggers need to use the types given in the arguments when printing +values, but when calling the function they need to use the types given +in the symbol defining the function. + + If the return type and types of arguments of a function which is +defined in another source file are specified (i.e., a function prototype +in ANSI C), traditionally compilers emit no stab; the only way for the +debugger to find the information is if the source file where the +function is defined was also compiled with debugging symbols. As an +extension the Solaris compiler uses symbol descriptor 'P' followed by +the return type of the function, followed by the arguments, each +preceded by ';', as in a stab with symbol descriptor 'f' or 'F'. This +use of symbol descriptor 'P' can be distinguished from its use for +register parameters (*note Register Parameters::) by the fact that it +has symbol type 'N_FUN'. + + The AIX documentation also defines symbol descriptor 'J' as an +internal function. I assume this means a function nested within another +function. It also says symbol descriptor 'm' is a module in Modula-2 or +extended Pascal. + + Procedures (functions which do not return values) are represented as +functions returning the 'void' type in C. I don't see why this couldn't +be used for all languages (inventing a 'void' type for this purpose if +necessary), but the AIX documentation defines 'I', 'P', and 'Q' for +internal, global, and static procedures, respectively. These symbol +descriptors are unusual in that they are not followed by type +information. + + The following example shows a stab for a function 'main' which +returns type number '1'. The '_main' specified for the value is a +reference to an assembler label which is used to fill in the start +address of the function. + + .stabs "main:F1",36,0,0,_main # 36 is N_FUN + + The stab representing a procedure is located immediately following +the code of the procedure. This stab is in turn directly followed by a +group of other stabs describing elements of the procedure. These other +stabs describe the procedure's parameters, its block local variables, +and its block structure. + + If functions can appear in different sections, then the debugger may +not be able to find the end of a function. Recent versions of GCC will +mark the end of a function with an 'N_FUN' symbol with an empty string +for the name. The value is the address of the end of the current +function. Without such a symbol, there is no indication of the address +of the end of a function, and you must assume that it ended at the +starting address of the next function or at the end of the text section +for the program. + + +File: stabs.info, Node: Nested Procedures, Next: Block Structure, Prev: Procedures, Up: Program Structure + +2.6 Nested Procedures +===================== + +For any of the symbol descriptors representing procedures, after the +symbol descriptor and the type information is optionally a scope +specifier. This consists of a comma, the name of the procedure, another +comma, and the name of the enclosing procedure. The first name is local +to the scope specified, and seems to be redundant with the name of the +symbol (before the ':'). This feature is used by GCC, and presumably +Pascal, Modula-2, etc., compilers, for nested functions. + + If procedures are nested more than one level deep, only the +immediately containing scope is specified. For example, this code: + + int + foo (int x) + { + int bar (int y) + { + int baz (int z) + { + return x + y + z; + } + return baz (x + 2 * y); + } + return x + bar (3 * x); + } + +produces the stabs: + + .stabs "baz:f1,baz,bar",36,0,0,_baz.15 # 36 is N_FUN + .stabs "bar:f1,bar,foo",36,0,0,_bar.12 + .stabs "foo:F1",36,0,0,_foo + + +File: stabs.info, Node: Block Structure, Next: Alternate Entry Points, Prev: Nested Procedures, Up: Program Structure + +2.7 Block Structure +=================== + +The program's block structure is represented by the 'N_LBRAC' (left +brace) and the 'N_RBRAC' (right brace) stab types. The variables +defined inside a block precede the 'N_LBRAC' symbol for most compilers, +including GCC. Other compilers, such as the Convex, Acorn RISC machine, +and Sun 'acc' compilers, put the variables after the 'N_LBRAC' symbol. +The values of the 'N_LBRAC' and 'N_RBRAC' symbols are the start and end +addresses of the code of the block, respectively. For most machines, +they are relative to the starting address of this source file. For the +Gould NP1, they are absolute. For stabs in sections (*note Stab +Sections::), they are relative to the function in which they occur. + + The 'N_LBRAC' and 'N_RBRAC' stabs that describe the block scope of a +procedure are located after the 'N_FUN' stab that represents the +procedure itself. + + Sun documents the desc field of 'N_LBRAC' and 'N_RBRAC' symbols as +containing the nesting level of the block. However, dbx seems to not +care, and GCC always sets desc to zero. + + For XCOFF, block scope is indicated with 'C_BLOCK' symbols. If the +name of the symbol is '.bb', then it is the beginning of the block; if +the name of the symbol is '.be'; it is the end of the block. + + +File: stabs.info, Node: Alternate Entry Points, Prev: Block Structure, Up: Program Structure + +2.8 Alternate Entry Points +========================== + +Some languages, like Fortran, have the ability to enter procedures at +some place other than the beginning. One can declare an alternate entry +point. The 'N_ENTRY' stab is for this; however, the Sun FORTRAN +compiler doesn't use it. According to AIX documentation, only the name +of a 'C_ENTRY' stab is significant; the address of the alternate entry +point comes from the corresponding external symbol. A previous revision +of this document said that the value of an 'N_ENTRY' stab was the +address of the alternate entry point, but I don't know the source for +that information. + + +File: stabs.info, Node: Constants, Next: Variables, Prev: Program Structure, Up: Top + +3 Constants +*********** + +The 'c' symbol descriptor indicates that this stab represents a +constant. This symbol descriptor is an exception to the general rule +that symbol descriptors are followed by type information. Instead, it +is followed by '=' and one of the following: + +'b VALUE' + Boolean constant. VALUE is a numeric value; I assume it is 0 for + false or 1 for true. + +'c VALUE' + Character constant. VALUE is the numeric value of the constant. + +'e TYPE-INFORMATION , VALUE' + Constant whose value can be represented as integral. + TYPE-INFORMATION is the type of the constant, as it would appear + after a symbol descriptor (*note String Field::). VALUE is the + numeric value of the constant. GDB 4.9 does not actually get the + right value if VALUE does not fit in a host 'int', but it does not + do anything violent, and future debuggers could be extended to + accept integers of any size (whether unsigned or not). This + constant type is usually documented as being only for enumeration + constants, but GDB has never imposed that restriction; I don't know + about other debuggers. + +'i VALUE' + Integer constant. VALUE is the numeric value. The type is some + sort of generic integer type (for GDB, a host 'int'); to specify + the type explicitly, use 'e' instead. + +'r VALUE' + Real constant. VALUE is the real value, which can be 'INF' + (optionally preceded by a sign) for infinity, 'QNAN' for a quiet + NaN (not-a-number), or 'SNAN' for a signalling NaN. If it is a + normal number the format is that accepted by the C library function + 'atof'. + +'s STRING' + String constant. STRING is a string enclosed in either ''' (in + which case ''' characters within the string are represented as '\'' + or '"' (in which case '"' characters within the string are + represented as '\"'). + +'S TYPE-INFORMATION , ELEMENTS , BITS , PATTERN' + Set constant. TYPE-INFORMATION is the type of the constant, as it + would appear after a symbol descriptor (*note String Field::). + ELEMENTS is the number of elements in the set (does this means how + many bits of PATTERN are actually used, which would be redundant + with the type, or perhaps the number of bits set in PATTERN? I + don't get it), BITS is the number of bits in the constant (meaning + it specifies the length of PATTERN, I think), and PATTERN is a + hexadecimal representation of the set. AIX documentation refers to + a limit of 32 bytes, but I see no reason why this limit should + exist. This form could probably be used for arbitrary constants, + not just sets; the only catch is that PATTERN should be understood + to be target, not host, byte order and format. + + The boolean, character, string, and set constants are not supported +by GDB 4.9, but it ignores them. GDB 4.8 and earlier gave an error +message and refused to read symbols from the file containing the +constants. + + The above information is followed by ';'. + + +File: stabs.info, Node: Variables, Next: Types, Prev: Constants, Up: Top + +4 Variables +*********** + +Different types of stabs describe the various ways that variables can be +allocated: on the stack, globally, in registers, in common blocks, +statically, or as arguments to a function. + +* Menu: + +* Stack Variables:: Variables allocated on the stack. +* Global Variables:: Variables used by more than one source file. +* Register Variables:: Variables in registers. +* Common Blocks:: Variables statically allocated together. +* Statics:: Variables local to one source file. +* Based Variables:: Fortran pointer based variables. +* Parameters:: Variables for arguments to functions. + + +File: stabs.info, Node: Stack Variables, Next: Global Variables, Up: Variables + +4.1 Automatic Variables Allocated on the Stack +============================================== + +If a variable's scope is local to a function and its lifetime is only as +long as that function executes (C calls such variables "automatic"), it +can be allocated in a register (*note Register Variables::) or on the +stack. + + Each variable allocated on the stack has a stab with the symbol +descriptor omitted. Since type information should begin with a digit, +'-', or '(', only those characters precluded from being used for symbol +descriptors. However, the Acorn RISC machine (ARM) is said to get this +wrong: it puts out a mere type definition here, without the preceding +'TYPE-NUMBER='. This is a bad idea; there is no guarantee that type +descriptors are distinct from symbol descriptors. Stabs for stack +variables use the 'N_LSYM' stab type, or 'C_LSYM' for XCOFF. + + The value of the stab is the offset of the variable within the local +variables. On most machines this is an offset from the frame pointer +and is negative. The location of the stab specifies which block it is +defined in; see *note Block Structure::. + + For example, the following C code: + + int + main () + { + int x; + } + + produces the following stabs: + + .stabs "main:F1",36,0,0,_main # 36 is N_FUN + .stabs "x:1",128,0,0,-12 # 128 is N_LSYM + .stabn 192,0,0,LBB2 # 192 is N_LBRAC + .stabn 224,0,0,LBE2 # 224 is N_RBRAC + + See *note Procedures:: for more information on the 'N_FUN' stab, and +*note Block Structure:: for more information on the 'N_LBRAC' and +'N_RBRAC' stabs. + + +File: stabs.info, Node: Global Variables, Next: Register Variables, Prev: Stack Variables, Up: Variables + +4.2 Global Variables +==================== + +A variable whose scope is not specific to just one source file is +represented by the 'G' symbol descriptor. These stabs use the 'N_GSYM' +stab type (C_GSYM for XCOFF). The type information for the stab (*note +String Field::) gives the type of the variable. + + For example, the following source code: + + char g_foo = 'c'; + +yields the following assembly code: + + .stabs "g_foo:G2",32,0,0,0 # 32 is N_GSYM + .global _g_foo + .data + _g_foo: + .byte 99 + + The address of the variable represented by the 'N_GSYM' is not +contained in the 'N_GSYM' stab. The debugger gets this information from +the external symbol for the global variable. In the example above, the +'.global _g_foo' and '_g_foo:' lines tell the assembler to produce an +external symbol. + + Some compilers, like GCC, output 'N_GSYM' stabs only once, where the +variable is defined. Other compilers, like SunOS4 /bin/cc, output a +'N_GSYM' stab for each compilation unit which references the variable. + + +File: stabs.info, Node: Register Variables, Next: Common Blocks, Prev: Global Variables, Up: Variables + +4.3 Register Variables +====================== + +Register variables have their own stab type, 'N_RSYM' ('C_RSYM' for +XCOFF), and their own symbol descriptor, 'r'. The stab's value is the +number of the register where the variable data will be stored. + + AIX defines a separate symbol descriptor 'd' for floating point +registers. This seems unnecessary; why not just just give floating +point registers different register numbers? I have not verified whether +the compiler actually uses 'd'. + + If the register is explicitly allocated to a global variable, but not +initialized, as in: + + register int g_bar asm ("%g5"); + +then the stab may be emitted at the end of the object file, with the +other bss symbols. + + +File: stabs.info, Node: Common Blocks, Next: Statics, Prev: Register Variables, Up: Variables + +4.4 Common Blocks +================= + +A common block is a statically allocated section of memory which can be +referred to by several source files. It may contain several variables. +I believe Fortran is the only language with this feature. + + A 'N_BCOMM' stab begins a common block and an 'N_ECOMM' stab ends it. +The only field that is significant in these two stabs is the string, +which names a normal (non-debugging) symbol that gives the address of +the common block. According to IBM documentation, only the 'N_BCOMM' +has the name of the common block (even though their compiler actually +puts it both places). + + The stabs for the members of the common block are between the +'N_BCOMM' and the 'N_ECOMM'; the value of each stab is the offset within +the common block of that variable. IBM uses the 'C_ECOML' stab type, +and there is a corresponding 'N_ECOML' stab type, but Sun's Fortran +compiler uses 'N_GSYM' instead. The variables within a common block use +the 'V' symbol descriptor (I believe this is true of all Fortran +variables). Other stabs (at least type declarations using 'C_DECL') can +also be between the 'N_BCOMM' and the 'N_ECOMM'. + + +File: stabs.info, Node: Statics, Next: Based Variables, Prev: Common Blocks, Up: Variables + +4.5 Static Variables +==================== + +Initialized static variables are represented by the 'S' and 'V' symbol +descriptors. 'S' means file scope static, and 'V' means procedure scope +static. One exception: in XCOFF, IBM's xlc compiler always uses 'V', +and whether it is file scope or not is distinguished by whether the stab +is located within a function. + + In a.out files, 'N_STSYM' means the data section, 'N_FUN' means the +text section, and 'N_LCSYM' means the bss section. For those systems +with a read-only data section separate from the text section (Solaris), +'N_ROSYM' means the read-only data section. + + For example, the source lines: + + static const int var_const = 5; + static int var_init = 2; + static int var_noinit; + +yield the following stabs: + + .stabs "var_const:S1",36,0,0,_var_const # 36 is N_FUN + ... + .stabs "var_init:S1",38,0,0,_var_init # 38 is N_STSYM + ... + .stabs "var_noinit:S1",40,0,0,_var_noinit # 40 is N_LCSYM + + In XCOFF files, the stab type need not indicate the section; +'C_STSYM' can be used for all statics. Also, each static variable is +enclosed in a static block. A 'C_BSTAT' (emitted with a '.bs' assembler +directive) symbol begins the static block; its value is the symbol +number of the csect symbol whose value is the address of the static +block, its section is the section of the variables in that static block, +and its name is '.bs'. A 'C_ESTAT' (emitted with a '.es' assembler +directive) symbol ends the static block; its name is '.es' and its value +and section are ignored. + + In ECOFF files, the storage class is used to specify the section, so +the stab type need not indicate the section. + + In ELF files, for the SunPRO compiler version 2.0.1, symbol +descriptor 'S' means that the address is absolute (the linker relocates +it) and symbol descriptor 'V' means that the address is relative to the +start of the relevant section for that compilation unit. SunPRO has +plans to have the linker stop relocating stabs; I suspect that their the +debugger gets the address from the corresponding ELF (not stab) symbol. +I'm not sure how to find which symbol of that name is the right one. +The clean way to do all this would be to have the value of a symbol +descriptor 'S' symbol be an offset relative to the start of the file, +just like everything else, but that introduces obvious compatibility +problems. For more information on linker stab relocation, *Note ELF +Linker Relocation::. + + +File: stabs.info, Node: Based Variables, Next: Parameters, Prev: Statics, Up: Variables + +4.6 Fortran Based Variables +=========================== + +Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature +which allows allocating arrays with 'malloc', but which avoids blurring +the line between arrays and pointers the way that C does. In stabs such +a variable uses the 'b' symbol descriptor. + + For example, the Fortran declarations + + real foo, foo10(10), foo10_5(10,5) + pointer (foop, foo) + pointer (foo10p, foo10) + pointer (foo105p, foo10_5) + + produce the stabs + + foo:b6 + foo10:bar3;1;10;6 + foo10_5:bar3;1;5;ar3;1;10;6 + + In this example, 'real' is type 6 and type 3 is an integral type +which is the type of the subscripts of the array (probably 'integer'). + + The 'b' symbol descriptor is like 'V' in that it denotes a statically +allocated symbol whose scope is local to a function; see *Note +Statics::. The value of the symbol, instead of being the address of the +variable itself, is the address of a pointer to that variable. So in +the above example, the value of the 'foo' stab is the address of a +pointer to a real, the value of the 'foo10' stab is the address of a +pointer to a 10-element array of reals, and the value of the 'foo10_5' +stab is the address of a pointer to a 5-element array of 10-element +arrays of reals. + + +File: stabs.info, Node: Parameters, Prev: Based Variables, Up: Variables + +4.7 Parameters +============== + +Formal parameters to a function are represented by a stab (or sometimes +two; see below) for each parameter. The stabs are in the order in which +the debugger should print the parameters (i.e., the order in which the +parameters are declared in the source file). The exact form of the stab +depends on how the parameter is being passed. + + Parameters passed on the stack use the symbol descriptor 'p' and the +'N_PSYM' symbol type (or 'C_PSYM' for XCOFF). The value of the symbol is +an offset used to locate the parameter on the stack; its exact meaning +is machine-dependent, but on most machines it is an offset from the +frame pointer. + + As a simple example, the code: + + main (argc, argv) + int argc; + char **argv; + + produces the stabs: + + .stabs "main:F1",36,0,0,_main # 36 is N_FUN + .stabs "argc:p1",160,0,0,68 # 160 is N_PSYM + .stabs "argv:p20=*21=*2",160,0,0,72 + + The type definition of 'argv' is interesting because it contains +several type definitions. Type 21 is pointer to type 2 (char) and +'argv' (type 20) is pointer to type 21. + + The following symbol descriptors are also said to go with 'N_PSYM'. +The value of the symbol is said to be an offset from the argument +pointer (I'm not sure whether this is true or not). + + pP (<>) + pF Fortran function parameter + X (function result variable) + +* Menu: + +* Register Parameters:: +* Local Variable Parameters:: +* Reference Parameters:: +* Conformant Arrays:: + + +File: stabs.info, Node: Register Parameters, Next: Local Variable Parameters, Up: Parameters + +4.7.1 Passing Parameters in Registers +------------------------------------- + +If the parameter is passed in a register, then traditionally there are +two symbols for each argument: + + .stabs "arg:p1" . . . ; N_PSYM + .stabs "arg:r1" . . . ; N_RSYM + + Debuggers use the second one to find the value, and the first one to +know that it is an argument. + + Because that approach is kind of ugly, some compilers use symbol +descriptor 'P' or 'R' to indicate an argument which is in a register. +Symbol type 'C_RPSYM' is used in XCOFF and 'N_RSYM' is used otherwise. +The symbol's value is the register number. 'P' and 'R' mean the same +thing; the difference is that 'P' is a GNU invention and 'R' is an IBM +(XCOFF) invention. As of version 4.9, GDB should handle either one. + + There is at least one case where GCC uses a 'p' and 'r' pair rather +than 'P'; this is where the argument is passed in the argument list and +then loaded into a register. + + According to the AIX documentation, symbol descriptor 'D' is for a +parameter passed in a floating point register. This seems +unnecessary--why not just use 'R' with a register number which indicates +that it's a floating point register? I haven't verified whether the +system actually does what the documentation indicates. + + On the sparc and hppa, for a 'P' symbol whose type is a structure or +union, the register contains the address of the structure. On the +sparc, this is also true of a 'p' and 'r' pair (using Sun 'cc') or a 'p' +symbol. However, if a (small) structure is really in a register, 'r' is +used. And, to top it all off, on the hppa it might be a structure which +was passed on the stack and loaded into a register and for which there +is a 'p' and 'r' pair! I believe that symbol descriptor 'i' is supposed +to deal with this case (it is said to mean "value parameter by +reference, indirect access"; I don't know the source for this +information), but I don't know details or what compilers or debuggers +use it, if any (not GDB or GCC). It is not clear to me whether this case +needs to be dealt with differently than parameters passed by reference +(*note Reference Parameters::). + + +File: stabs.info, Node: Local Variable Parameters, Next: Reference Parameters, Prev: Register Parameters, Up: Parameters + +4.7.2 Storing Parameters as Local Variables +------------------------------------------- + +There is a case similar to an argument in a register, which is an +argument that is actually stored as a local variable. Sometimes this +happens when the argument was passed in a register and then the compiler +stores it as a local variable. If possible, the compiler should claim +that it's in a register, but this isn't always done. + + If a parameter is passed as one type and converted to a smaller type +by the prologue (for example, the parameter is declared as a 'float', +but the calling conventions specify that it is passed as a 'double'), +then GCC2 (sometimes) uses a pair of symbols. The first symbol uses +symbol descriptor 'p' and the type which is passed. The second symbol +has the type and location which the parameter actually has after the +prologue. For example, suppose the following C code appears with no +prototypes involved: + + void + subr (f) + float f; + { + + if 'f' is passed as a double at stack offset 8, and the prologue +converts it to a float in register number 0, then the stabs look like: + + .stabs "f:p13",160,0,3,8 # 160 is 'N_PSYM', here 13 is 'double' + .stabs "f:r12",64,0,3,0 # 64 is 'N_RSYM', here 12 is 'float' + + In both stabs 3 is the line number where 'f' is declared (*note Line +Numbers::). + + GCC, at least on the 960, has another solution to the same problem. +It uses a single 'p' symbol descriptor for an argument which is stored +as a local variable but uses 'N_LSYM' instead of 'N_PSYM'. In this +case, the value of the symbol is an offset relative to the local +variables for that function, not relative to the arguments; on some +machines those are the same thing, but not on all. + + On the VAX or on other machines in which the calling convention +includes the number of words of arguments actually passed, the debugger +(GDB at least) uses the parameter symbols to keep track of whether it +needs to print nameless arguments in addition to the formal parameters +which it has printed because each one has a stab. For example, in + + extern int fprintf (FILE *stream, char *format, ...); + ... + fprintf (stdout, "%d\n", x); + + there are stabs for 'stream' and 'format'. On most machines, the +debugger can only print those two arguments (because it has no way of +knowing that additional arguments were passed), but on the VAX or other +machines with a calling convention which indicates the number of words +of arguments, the debugger can print all three arguments. To do so, the +parameter symbol (symbol descriptor 'p') (not necessarily 'r' or symbol +descriptor omitted symbols) needs to contain the actual type as passed +(for example, 'double' not 'float' if it is passed as a double and +converted to a float). + + +File: stabs.info, Node: Reference Parameters, Next: Conformant Arrays, Prev: Local Variable Parameters, Up: Parameters + +4.7.3 Passing Parameters by Reference +------------------------------------- + +If the parameter is passed by reference (e.g., Pascal 'VAR' parameters), +then the symbol descriptor is 'v' if it is in the argument list, or 'a' +if it in a register. Other than the fact that these contain the address +of the parameter rather than the parameter itself, they are identical to +'p' and 'R', respectively. I believe 'a' is an AIX invention; 'v' is +supported by all stabs-using systems as far as I know. + + +File: stabs.info, Node: Conformant Arrays, Prev: Reference Parameters, Up: Parameters + +4.7.4 Passing Conformant Array Parameters +----------------------------------------- + +Conformant arrays are a feature of Modula-2, and perhaps other +languages, in which the size of an array parameter is not known to the +called function until run-time. Such parameters have two stabs: a 'x' +for the array itself, and a 'C', which represents the size of the array. +The value of the 'x' stab is the offset in the argument list where the +address of the array is stored (it this right? it is a guess); the +value of the 'C' stab is the offset in the argument list where the size +of the array (in elements? in bytes?) is stored. + + +File: stabs.info, Node: Types, Next: Macro define and undefine, Prev: Variables, Up: Top + +5 Defining Types +**************** + +The examples so far have described types as references to previously +defined types, or defined in terms of subranges of or pointers to +previously defined types. This chapter describes the other type +descriptors that may follow the '=' in a type definition. + +* Menu: + +* Builtin Types:: Integers, floating point, void, etc. +* Miscellaneous Types:: Pointers, sets, files, etc. +* Cross-References:: Referring to a type not yet defined. +* Subranges:: A type with a specific range. +* Arrays:: An aggregate type of same-typed elements. +* Strings:: Like an array but also has a length. +* Enumerations:: Like an integer but the values have names. +* Structures:: An aggregate type of different-typed elements. +* Typedefs:: Giving a type a name. +* Unions:: Different types sharing storage. +* Function Types:: + + +File: stabs.info, Node: Builtin Types, Next: Miscellaneous Types, Up: Types + +5.1 Builtin Types +================= + +Certain types are built in ('int', 'short', 'void', 'float', etc.); the +debugger recognizes these types and knows how to handle them. Thus, +don't be surprised if some of the following ways of specifying builtin +types do not specify everything that a debugger would need to know about +the type--in some cases they merely specify enough information to +distinguish the type from other types. + + The traditional way to define builtin types is convoluted, so new +ways have been invented to describe them. Sun's 'acc' uses special +builtin type descriptors ('b' and 'R'), and IBM uses negative type +numbers. GDB accepts all three ways, as of version 4.8; dbx just +accepts the traditional builtin types and perhaps one of the other two +formats. The following sections describe each of these formats. + +* Menu: + +* Traditional Builtin Types:: Put on your seat belts and prepare for kludgery +* Builtin Type Descriptors:: Builtin types with special type descriptors +* Negative Type Numbers:: Builtin types using negative type numbers + + +File: stabs.info, Node: Traditional Builtin Types, Next: Builtin Type Descriptors, Up: Builtin Types + +5.1.1 Traditional Builtin Types +------------------------------- + +This is the traditional, convoluted method for defining builtin types. +There are several classes of such type definitions: integer, floating +point, and 'void'. + +* Menu: + +* Traditional Integer Types:: +* Traditional Other Types:: + + +File: stabs.info, Node: Traditional Integer Types, Next: Traditional Other Types, Up: Traditional Builtin Types + +5.1.1.1 Traditional Integer Types +................................. + +Often types are defined as subranges of themselves. If the bounding +values fit within an 'int', then they are given normally. For example: + + .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 # 128 is N_LSYM + .stabs "char:t2=r2;0;127;",128,0,0,0 + + Builtin types can also be described as subranges of 'int': + + .stabs "unsigned short:t6=r1;0;65535;",128,0,0,0 + + If the lower bound of a subrange is 0 and the upper bound is -1, the +type is an unsigned integral type whose bounds are too big to describe +in an 'int'. Traditionally this is only used for 'unsigned int' and +'unsigned long': + + .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 + + For larger types, GCC 2.4.5 puts out bounds in octal, with one or +more leading zeroes. In this case a negative bound consists of a number +which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in +the number (except the sign bit), and a positive bound is one which is a +1 bit for each bit in the number (except possibly the sign bit). All +known versions of dbx and GDB version 4 accept this (at least in the +sense of not refusing to process the file), but GDB 3.5 refuses to read +the whole file containing such symbols. So GCC 2.3.3 did not output the +proper size for these types. As an example of octal bounds, the string +fields of the stabs for 64 bit integer types look like: + + long int:t3=r1;001000000000000000000000;000777777777777777777777; + long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777; + + If the lower bound of a subrange is 0 and the upper bound is +negative, the type is an unsigned integral type whose size in bytes is +the absolute value of the upper bound. I believe this is a Convex +convention for 'unsigned long long'. + + If the lower bound of a subrange is negative and the upper bound is +0, the type is a signed integral type whose size in bytes is the +absolute value of the lower bound. I believe this is a Convex +convention for 'long long'. To distinguish this from a legitimate +subrange, the type should be a subrange of itself. I'm not sure whether +this is the case for Convex. + + +File: stabs.info, Node: Traditional Other Types, Prev: Traditional Integer Types, Up: Traditional Builtin Types + +5.1.1.2 Traditional Other Types +............................... + +If the upper bound of a subrange is 0 and the lower bound is positive, +the type is a floating point type, and the lower bound of the subrange +indicates the number of bytes in the type: + + .stabs "float:t12=r1;4;0;",128,0,0,0 + .stabs "double:t13=r1;8;0;",128,0,0,0 + + However, GCC writes 'long double' the same way it writes 'double', so +there is no way to distinguish. + + .stabs "long double:t14=r1;8;0;",128,0,0,0 + + Complex types are defined the same way as floating-point types; there +is no way to distinguish a single-precision complex from a +double-precision floating-point type. + + The C 'void' type is defined as itself: + + .stabs "void:t15=15",128,0,0,0 + + I'm not sure how a boolean type is represented. + + +File: stabs.info, Node: Builtin Type Descriptors, Next: Negative Type Numbers, Prev: Traditional Builtin Types, Up: Builtin Types + +5.1.2 Defining Builtin Types Using Builtin Type Descriptors +----------------------------------------------------------- + +This is the method used by Sun's 'acc' for defining builtin types. +These are the type descriptors to define builtin types: + +'b SIGNED CHAR-FLAG WIDTH ; OFFSET ; NBITS ;' + Define an integral type. SIGNED is 'u' for unsigned or 's' for + signed. CHAR-FLAG is 'c' which indicates this is a character type, + or is omitted. I assume this is to distinguish an integral type + from a character type of the same size, for example it might make + sense to set it for the C type 'wchar_t' so the debugger can print + such variables differently (Solaris does not do this). Sun sets it + on the C types 'signed char' and 'unsigned char' which arguably is + wrong. WIDTH and OFFSET appear to be for small objects stored in + larger ones, for example a 'short' in an 'int' register. WIDTH is + normally the number of bytes in the type. OFFSET seems to always + be zero. NBITS is the number of bits in the type. + + Note that type descriptor 'b' used for builtin types conflicts with + its use for Pascal space types (*note Miscellaneous Types::); they + can be distinguished because the character following the type + descriptor will be a digit, '(', or '-' for a Pascal space type, or + 'u' or 's' for a builtin type. + +'w' + Documented by AIX to define a wide character type, but their + compiler actually uses negative type numbers (*note Negative Type + Numbers::). + +'R FP-TYPE ; BYTES ;' + Define a floating point type. FP-TYPE has one of the following + values: + + '1 (NF_SINGLE)' + IEEE 32-bit (single precision) floating point format. + + '2 (NF_DOUBLE)' + IEEE 64-bit (double precision) floating point format. + + '3 (NF_COMPLEX)' + '4 (NF_COMPLEX16)' + '5 (NF_COMPLEX32)' + These are for complex numbers. A comment in the GDB source + describes them as Fortran 'complex', 'double complex', and + 'complex*16', respectively, but what does that mean? (i.e., + Single precision? Double precision?). + + '6 (NF_LDOUBLE)' + Long double. This should probably only be used for Sun format + 'long double', and new codes should be used for other floating + point formats ('NF_DOUBLE' can be used if a 'long double' is + really just an IEEE double, of course). + + BYTES is the number of bytes occupied by the type. This allows a + debugger to perform some operations with the type even if it + doesn't understand FP-TYPE. + +'g TYPE-INFORMATION ; NBITS' + Documented by AIX to define a floating type, but their compiler + actually uses negative type numbers (*note Negative Type + Numbers::). + +'c TYPE-INFORMATION ; NBITS' + Documented by AIX to define a complex type, but their compiler + actually uses negative type numbers (*note Negative Type + Numbers::). + + The C 'void' type is defined as a signed integral type 0 bits long: + .stabs "void:t19=bs0;0;0",128,0,0,0 + The Solaris compiler seems to omit the trailing semicolon in this +case. Getting sloppy in this way is not a swift move because if a type +is embedded in a more complex expression it is necessary to be able to +tell where it ends. + + I'm not sure how a boolean type is represented. + + +File: stabs.info, Node: Negative Type Numbers, Prev: Builtin Type Descriptors, Up: Builtin Types + +5.1.3 Negative Type Numbers +--------------------------- + +This is the method used in XCOFF for defining builtin types. Since the +debugger knows about the builtin types anyway, the idea of negative type +numbers is simply to give a special type number which indicates the +builtin type. There is no stab defining these types. + + There are several subtle issues with negative type numbers. + + One is the size of the type. A builtin type (for example the C types +'int' or 'long') might have different sizes depending on compiler +options, the target architecture, the ABI, etc. This issue doesn't come +up for IBM tools since (so far) they just target the RS/6000; the sizes +indicated below for each size are what the IBM RS/6000 tools use. To +deal with differing sizes, either define separate negative type numbers +for each size (which works but requires changing the debugger, and, +unless you get both AIX dbx and GDB to accept the change, introduces an +incompatibility), or use a type attribute (*note String Field::) to +define a new type with the appropriate size (which merely requires a +debugger which understands type attributes, like AIX dbx or GDB). For +example, + + .stabs "boolean:t10=@s8;-16",128,0,0,0 + + defines an 8-bit boolean type, and + + .stabs "boolean:t10=@s64;-16",128,0,0,0 + + defines a 64-bit boolean type. + + A similar issue is the format of the type. This comes up most often +for floating-point types, which could have various formats (particularly +extended doubles, which vary quite a bit even among IEEE systems). +Again, it is best to define a new negative type number for each +different format; changing the format based on the target system has +various problems. One such problem is that the Alpha has both VAX and +IEEE floating types. One can easily imagine one library using the VAX +types and another library in the same executable using the IEEE types. +Another example is that the interpretation of whether a boolean is true +or false can be based on the least significant bit, most significant +bit, whether it is zero, etc., and different compilers (or different +options to the same compiler) might provide different kinds of boolean. + + The last major issue is the names of the types. The name of a given +type depends _only_ on the negative type number given; these do not vary +depending on the language, the target system, or anything else. One can +always define separate type numbers--in the following list you will see +for example separate 'int' and 'integer*4' types which are identical +except for the name. But compatibility can be maintained by not +inventing new negative type numbers and instead just defining a new type +with a new name. For example: + + .stabs "CARDINAL:t10=-8",128,0,0,0 + + Here is the list of negative type numbers. The phrase "integral +type" is used to mean twos-complement (I strongly suspect that all +machines which use stabs use twos-complement; most machines use +twos-complement these days). + +'-1' + 'int', 32 bit signed integral type. + +'-2' + 'char', 8 bit type holding a character. Both GDB and dbx on AIX + treat this as signed. GCC uses this type whether 'char' is signed + or not, which seems like a bad idea. The AIX compiler ('xlc') + seems to avoid this type; it uses -5 instead for 'char'. + +'-3' + 'short', 16 bit signed integral type. + +'-4' + 'long', 32 bit signed integral type. + +'-5' + 'unsigned char', 8 bit unsigned integral type. + +'-6' + 'signed char', 8 bit signed integral type. + +'-7' + 'unsigned short', 16 bit unsigned integral type. + +'-8' + 'unsigned int', 32 bit unsigned integral type. + +'-9' + 'unsigned', 32 bit unsigned integral type. + +'-10' + 'unsigned long', 32 bit unsigned integral type. + +'-11' + 'void', type indicating the lack of a value. + +'-12' + 'float', IEEE single precision. + +'-13' + 'double', IEEE double precision. + +'-14' + 'long double', IEEE double precision. The compiler claims the size + will increase in a future release, and for binary compatibility you + have to avoid using 'long double'. I hope when they increase it + they use a new negative type number. + +'-15' + 'integer'. 32 bit signed integral type. + +'-16' + 'boolean'. 32 bit type. GDB and GCC assume that zero is false, + one is true, and other values have unspecified meaning. I hope + this agrees with how the IBM tools use the type. + +'-17' + 'short real'. IEEE single precision. + +'-18' + 'real'. IEEE double precision. + +'-19' + 'stringptr'. *Note Strings::. + +'-20' + 'character', 8 bit unsigned character type. + +'-21' + 'logical*1', 8 bit type. This Fortran type has a split personality + in that it is used for boolean variables, but can also be used for + unsigned integers. 0 is false, 1 is true, and other values are + non-boolean. + +'-22' + 'logical*2', 16 bit type. This Fortran type has a split + personality in that it is used for boolean variables, but can also + be used for unsigned integers. 0 is false, 1 is true, and other + values are non-boolean. + +'-23' + 'logical*4', 32 bit type. This Fortran type has a split + personality in that it is used for boolean variables, but can also + be used for unsigned integers. 0 is false, 1 is true, and other + values are non-boolean. + +'-24' + 'logical', 32 bit type. This Fortran type has a split personality + in that it is used for boolean variables, but can also be used for + unsigned integers. 0 is false, 1 is true, and other values are + non-boolean. + +'-25' + 'complex'. A complex type consisting of two IEEE single-precision + floating point values. + +'-26' + 'complex'. A complex type consisting of two IEEE double-precision + floating point values. + +'-27' + 'integer*1', 8 bit signed integral type. + +'-28' + 'integer*2', 16 bit signed integral type. + +'-29' + 'integer*4', 32 bit signed integral type. + +'-30' + 'wchar'. Wide character, 16 bits wide, unsigned (what format? + Unicode?). + +'-31' + 'long long', 64 bit signed integral type. + +'-32' + 'unsigned long long', 64 bit unsigned integral type. + +'-33' + 'logical*8', 64 bit unsigned integral type. + +'-34' + 'integer*8', 64 bit signed integral type. + + +File: stabs.info, Node: Miscellaneous Types, Next: Cross-References, Prev: Builtin Types, Up: Types + +5.2 Miscellaneous Types +======================= + +'b TYPE-INFORMATION ; BYTES' + Pascal space type. This is documented by IBM; what does it mean? + + This use of the 'b' type descriptor can be distinguished from its + use for builtin integral types (*note Builtin Type Descriptors::) + because the character following the type descriptor is always a + digit, '(', or '-'. + +'B TYPE-INFORMATION' + A volatile-qualified version of TYPE-INFORMATION. This is a Sun + extension. References and stores to a variable with a + volatile-qualified type must not be optimized or cached; they must + occur as the user specifies them. + +'d TYPE-INFORMATION' + File of type TYPE-INFORMATION. As far as I know this is only used + by Pascal. + +'k TYPE-INFORMATION' + A const-qualified version of TYPE-INFORMATION. This is a Sun + extension. A variable with a const-qualified type cannot be + modified. + +'M TYPE-INFORMATION ; LENGTH' + Multiple instance type. The type seems to composed of LENGTH + repetitions of TYPE-INFORMATION, for example 'character*3' is + represented by 'M-2;3', where '-2' is a reference to a character + type (*note Negative Type Numbers::). I'm not sure how this + differs from an array. This appears to be a Fortran feature. + LENGTH is a bound, like those in range types; see *note + Subranges::. + +'S TYPE-INFORMATION' + Pascal set type. TYPE-INFORMATION must be a small type such as an + enumeration or a subrange, and the type is a bitmask whose length + is specified by the number of elements in TYPE-INFORMATION. + + In CHILL, if it is a bitstring instead of a set, also use the 'S' + type attribute (*note String Field::). + +'* TYPE-INFORMATION' + Pointer to TYPE-INFORMATION. + + +File: stabs.info, Node: Cross-References, Next: Subranges, Prev: Miscellaneous Types, Up: Types + +5.3 Cross-References to Other Types +=================================== + +A type can be used before it is defined; one common way to deal with +that situation is just to use a type reference to a type which has not +yet been defined. + + Another way is with the 'x' type descriptor, which is followed by 's' +for a structure tag, 'u' for a union tag, or 'e' for a enumerator tag, +followed by the name of the tag, followed by ':'. If the name contains +'::' between a '<' and '>' pair (for C++ templates), such a '::' does +not end the name--only a single ':' ends the name; see *note Nested +Symbols::. + + For example, the following C declarations: + + struct foo; + struct foo *bar; + +produce: + + .stabs "bar:G16=*17=xsfoo:",32,0,0,0 + + Not all debuggers support the 'x' type descriptor, so on some +machines GCC does not use it. I believe that for the above example it +would just emit a reference to type 17 and never define it, but I +haven't verified that. + + Modula-2 imported types, at least on AIX, use the 'i' type +descriptor, which is followed by the name of the module from which the +type is imported, followed by ':', followed by the name of the type. +There is then optionally a comma followed by type information for the +type. This differs from merely naming the type (*note Typedefs::) in +that it identifies the module; I don't understand whether the name of +the type given here is always just the same as the name we are giving +it, or whether this type descriptor is used with a nameless stab (*note +String Field::), or what. The symbol ends with ';'. + + +File: stabs.info, Node: Subranges, Next: Arrays, Prev: Cross-References, Up: Types + +5.4 Subrange Types +================== + +The 'r' type descriptor defines a type as a subrange of another type. +It is followed by type information for the type of which it is a +subrange, a semicolon, an integral lower bound, a semicolon, an integral +upper bound, and a semicolon. The AIX documentation does not specify +the trailing semicolon, in an effort to specify array indexes more +cleanly, but a subrange which is not an array index has always included +a trailing semicolon (*note Arrays::). + + Instead of an integer, either bound can be one of the following: + +'A OFFSET' + The bound is passed by reference on the stack at offset OFFSET from + the argument list. *Note Parameters::, for more information on + such offsets. + +'T OFFSET' + The bound is passed by value on the stack at offset OFFSET from the + argument list. + +'a REGISTER-NUMBER' + The bound is passed by reference in register number + REGISTER-NUMBER. + +'t REGISTER-NUMBER' + The bound is passed by value in register number REGISTER-NUMBER. + +'J' + There is no bound. + + Subranges are also used for builtin types; see *note Traditional +Builtin Types::. + + +File: stabs.info, Node: Arrays, Next: Strings, Prev: Subranges, Up: Types + +5.5 Array Types +=============== + +Arrays use the 'a' type descriptor. Following the type descriptor is +the type of the index and the type of the array elements. If the index +type is a range type, it ends in a semicolon; otherwise (for example, if +it is a type reference), there does not appear to be any way to tell +where the types are separated. In an effort to clean up this mess, IBM +documents the two types as being separated by a semicolon, and a range +type as not ending in a semicolon (but this is not right for range types +which are not array indexes, *note Subranges::). I think probably the +best solution is to specify that a semicolon ends a range type, and that +the index type and element type of an array are separated by a +semicolon, but that if the index type is a range type, the extra +semicolon can be omitted. GDB (at least through version 4.9) doesn't +support any kind of index type other than a range anyway; I'm not sure +about dbx. + + It is well established, and widely used, that the type of the index, +unlike most types found in the stabs, is merely a type definition, not +type information (*note String Field::) (that is, it need not start with +'TYPE-NUMBER=' if it is defining a new type). According to a comment in +GDB, this is also true of the type of the array elements; it gives +'ar1;1;10;ar1;1;10;4' as a legitimate way to express a two dimensional +array. According to AIX documentation, the element type must be type +information. GDB accepts either. + + The type of the index is often a range type, expressed as the type +descriptor 'r' and some parameters. It defines the size of the array. +In the example below, the range 'r1;0;2;' defines an index type which is +a subrange of type 1 (integer), with a lower bound of 0 and an upper +bound of 2. This defines the valid range of subscripts of a +three-element C array. + + For example, the definition: + + char char_vec[3] = {'a','b','c'}; + +produces the output: + + .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0 + .global _char_vec + .align 4 + _char_vec: + .byte 97 + .byte 98 + .byte 99 + + If an array is "packed", the elements are spaced more closely than +normal, saving memory at the expense of speed. For example, an array of +3-byte objects might, if unpacked, have each element aligned on a 4-byte +boundary, but if packed, have no padding. One way to specify that +something is packed is with type attributes (*note String Field::). In +the case of arrays, another is to use the 'P' type descriptor instead of +'a'. Other than specifying a packed array, 'P' is identical to 'a'. + + An open array is represented by the 'A' type descriptor followed by +type information specifying the type of the array elements. + + An N-dimensional dynamic array is represented by + + D DIMENSIONS ; TYPE-INFORMATION + + DIMENSIONS is the number of dimensions; TYPE-INFORMATION specifies +the type of the array elements. + + A subarray of an N-dimensional array is represented by + + E DIMENSIONS ; TYPE-INFORMATION + + DIMENSIONS is the number of dimensions; TYPE-INFORMATION specifies +the type of the array elements. + + +File: stabs.info, Node: Strings, Next: Enumerations, Prev: Arrays, Up: Types + +5.6 Strings +=========== + +Some languages, like C or the original Pascal, do not have string types, +they just have related things like arrays of characters. But most +Pascals and various other languages have string types, which are +indicated as follows: + +'n TYPE-INFORMATION ; BYTES' + BYTES is the maximum length. I'm not sure what TYPE-INFORMATION + is; I suspect that it means that this is a string of + TYPE-INFORMATION (thus allowing a string of integers, a string of + wide characters, etc., as well as a string of characters). Not + sure what the format of this type is. This is an AIX feature. + +'z TYPE-INFORMATION ; BYTES' + Just like 'n' except that this is a gstring, not an ordinary + string. I don't know the difference. + +'N' + Pascal Stringptr. What is this? This is an AIX feature. + + Languages, such as CHILL which have a string type which is basically +just an array of characters use the 'S' type attribute (*note String +Field::). + + +File: stabs.info, Node: Enumerations, Next: Structures, Prev: Strings, Up: Types + +5.7 Enumerations +================ + +Enumerations are defined with the 'e' type descriptor. + + The source line below declares an enumeration type at file scope. +The type definition is located after the 'N_RBRAC' that marks the end of +the previous procedure's block scope, and before the 'N_FUN' that marks +the beginning of the next procedure's block scope. Therefore it does +not describe a block local symbol, but a file local one. + + The source line: + + enum e_places {first,second=3,last}; + +generates the following stab: + + .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0 + + The symbol descriptor ('T') says that the stab describes a structure, +enumeration, or union tag. The type descriptor 'e', following the '22=' +of the type definition narrows it down to an enumeration type. +Following the 'e' is a list of the elements of the enumeration. The +format is 'NAME:VALUE,'. The list of elements ends with ';'. The fact +that VALUE is specified as an integer can cause problems if the value is +large. GCC 2.5.2 tries to output it in octal in that case with a +leading zero, which is probably a good thing, although GDB 4.11 supports +octal only in cases where decimal is perfectly good. Negative decimal +values are supported by both GDB and dbx. + + There is no standard way to specify the size of an enumeration type; +it is determined by the architecture (normally all enumerations types +are 32 bits). Type attributes can be used to specify an enumeration +type of another size for debuggers which support them; see *note String +Field::. + + Enumeration types are unusual in that they define symbols for the +enumeration values ('first', 'second', and 'third' in the above +example), and even though these symbols are visible in the file as a +whole (rather than being in a more local namespace like structure member +names), they are defined in the type definition for the enumeration type +rather than each having their own symbol. In order to be fast, GDB will +only get symbols from such types (in its initial scan of the stabs) if +the type is the first thing defined after a 'T' or 't' symbol descriptor +(the above example fulfills this requirement). If the type does not +have a name, the compiler should emit it in a nameless stab (*note +String Field::); GCC does this. + + +File: stabs.info, Node: Structures, Next: Typedefs, Prev: Enumerations, Up: Types + +5.8 Structures +============== + +The encoding of structures in stabs can be shown with an example. + + The following source code declares a structure tag and defines an +instance of the structure in global scope. Then a 'typedef' equates the +structure tag with a new type. Separate stabs are generated for the +structure tag, the structure 'typedef', and the structure instance. The +stabs for the tag and the 'typedef' are emitted when the definitions are +encountered. Since the structure elements are not initialized, the stab +and code for the structure variable itself is located at the end of the +program in the bss section. + + struct s_tag { + int s_int; + float s_float; + char s_char_vec[8]; + struct s_tag* s_next; + } g_an_s; + + typedef struct s_tag s_typedef; + + The structure tag has an 'N_LSYM' stab type because, like the +enumeration, the symbol has file scope. Like the enumeration, the +symbol descriptor is 'T', for enumeration, structure, or tag type. The +type descriptor 's' following the '16=' of the type definition narrows +the symbol type to structure. + + Following the 's' type descriptor is the number of bytes the +structure occupies, followed by a description of each structure element. +The structure element descriptions are of the form 'NAME:TYPE, BIT +OFFSET FROM THE START OF THE STRUCT, NUMBER OF BITS IN THE ELEMENT'. + + # 128 is N_LSYM + .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32; + s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0 + + In this example, the first two structure elements are previously +defined types. For these, the type following the 'NAME:' part of the +element description is a simple type reference. The other two structure +elements are new types. In this case there is a type definition +embedded after the 'NAME:'. The type definition for the array element +looks just like a type definition for a stand-alone array. The 's_next' +field is a pointer to the same kind of structure that the field is an +element of. So the definition of structure type 16 contains a type +definition for an element which is a pointer to type 16. + + If a field is a static member (this is a C++ feature in which a +single variable appears to be a field of every structure of a given +type) it still starts out with the field name, a colon, and the type, +but then instead of a comma, bit position, comma, and bit size, there is +a colon followed by the name of the variable which each such field +refers to. + + If the structure has methods (a C++ feature), they follow the +non-method fields; see *note Cplusplus::. + + +File: stabs.info, Node: Typedefs, Next: Unions, Prev: Structures, Up: Types + +5.9 Giving a Type a Name +======================== + +To give a type a name, use the 't' symbol descriptor. The type is +specified by the type information (*note String Field::) for the stab. +For example, + + .stabs "s_typedef:t16",128,0,0,0 # 128 is N_LSYM + + specifies that 's_typedef' refers to type number 16. Such stabs have +symbol type 'N_LSYM' (or 'C_DECL' for XCOFF). (The Sun documentation +mentions using 'N_GSYM' in some cases). + + If you are specifying the tag name for a structure, union, or +enumeration, use the 'T' symbol descriptor instead. I believe C is the +only language with this feature. + + If the type is an opaque type (I believe this is a Modula-2 feature), +AIX provides a type descriptor to specify it. The type descriptor is +'o' and is followed by a name. I don't know what the name means--is it +always the same as the name of the type, or is this type descriptor used +with a nameless stab (*note String Field::)? There optionally follows a +comma followed by type information which defines the type of this type. +If omitted, a semicolon is used in place of the comma and the type +information, and the type is much like a generic pointer type--it has a +known size but little else about it is specified. + + +File: stabs.info, Node: Unions, Next: Function Types, Prev: Typedefs, Up: Types + +5.10 Unions +=========== + + union u_tag { + int u_int; + float u_float; + char* u_char; + } an_u; + + This code generates a stab for a union tag and a stab for a union +variable. Both use the 'N_LSYM' stab type. If a union variable is +scoped locally to the procedure in which it is defined, its stab is +located immediately preceding the 'N_LBRAC' for the procedure's block +start. + + The stab for the union tag, however, is located preceding the code +for the procedure in which it is defined. The stab type is 'N_LSYM'. +This would seem to imply that the union type is file scope, like the +struct type 's_tag'. This is not true. The contents and position of +the stab for 'u_type' do not convey any information about its procedure +local scope. + + # 128 is N_LSYM + .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;", + 128,0,0,0 + + The symbol descriptor 'T', following the 'name:' means that the stab +describes an enumeration, structure, or union tag. The type descriptor +'u', following the '23=' of the type definition, narrows it down to a +union type definition. Following the 'u' is the number of bytes in the +union. After that is a list of union element descriptions. Their +format is 'NAME:TYPE, BIT OFFSET INTO THE UNION, NUMBER OF BYTES FOR THE +ELEMENT;'. + + The stab for the union variable is: + + .stabs "an_u:23",128,0,0,-20 # 128 is N_LSYM + + '-20' specifies where the variable is stored (*note Stack +Variables::). + + +File: stabs.info, Node: Function Types, Prev: Unions, Up: Types + +5.11 Function Types +=================== + +Various types can be defined for function variables. These types are +not used in defining functions (*note Procedures::); they are used for +things like pointers to functions. + + The simple, traditional, type is type descriptor 'f' is followed by +type information for the return type of the function, followed by a +semicolon. + + This does not deal with functions for which the number and types of +the parameters are part of the type, as in Modula-2 or ANSI C. AIX +provides extensions to specify these, using the 'f', 'F', 'p', and 'R' +type descriptors. + + First comes the type descriptor. If it is 'f' or 'F', this type +involves a function rather than a procedure, and the type information +for the return type of the function follows, followed by a comma. Then +comes the number of parameters to the function and a semicolon. Then, +for each parameter, there is the name of the parameter followed by a +colon (this is only present for type descriptors 'R' and 'F' which +represent Pascal function or procedure parameters), type information for +the parameter, a comma, 0 if passed by reference or 1 if passed by +value, and a semicolon. The type definition ends with a semicolon. + + For example, this variable definition: + + int (*g_pf)(); + +generates the following code: + + .stabs "g_pf:G24=*25=f1",32,0,0,0 + .common _g_pf,4,"bss" + + The variable defines a new type, 24, which is a pointer to another +new type, 25, which is a function returning 'int'. + + +File: stabs.info, Node: Macro define and undefine, Next: Symbol Tables, Prev: Types, Up: Top + +6 Representation of #define and #undef +************************************** + +This section describes the stabs support for macro define and undefine +information, supported on some systems. (e.g., with '-g3' '-gstabs' +when using GCC). + + A '#define MACRO-NAME MACRO-BODY' is represented with an +'N_MAC_DEFINE' stab with a string field of 'MACRO-NAME MACRO-BODY'. + + An '#undef MACRO-NAME' is represented with an 'N_MAC_UNDEF' stabs +with a string field of simply 'MACRO-NAME'. + + For both 'N_MAC_DEFINE' and 'N_MAC_UNDEF', the desc field is the line +number within the file where the corresponding '#define' or '#undef' +occurred. + + For example, the following C code: + + #define NONE 42 + #define TWO(a, b) (a + (a) + 2 * b) + #define ONE(c) (c + 19) + + main(int argc, char *argv[]) + { + func(NONE, TWO(10, 11)); + func(NONE, ONE(23)); + + #undef ONE + #define ONE(c) (c + 23) + + func(NONE, ONE(-23)); + + return (0); + } + + int global; + + func(int arg1, int arg2) + { + global = arg1 + arg2; + } + +produces the following stabs (as well as many others): + + .stabs "NONE 42",54,0,1,0 + .stabs "TWO(a,b) (a + (a) + 2 * b)",54,0,2,0 + .stabs "ONE(c) (c + 19)",54,0,3,0 + .stabs "ONE",58,0,10,0 + .stabs "ONE(c) (c + 23)",54,0,11,0 + +NOTE: In the above example, '54' is 'N_MAC_DEFINE' and '58' is +'N_MAC_UNDEF'. + + +File: stabs.info, Node: Symbol Tables, Next: Cplusplus, Prev: Macro define and undefine, Up: Top + +7 Symbol Information in Symbol Tables +************************************* + +This chapter describes the format of symbol table entries and how stab +assembler directives map to them. It also describes the transformations +that the assembler and linker make on data from stabs. + +* Menu: + +* Symbol Table Format:: +* Transformations On Symbol Tables:: + + +File: stabs.info, Node: Symbol Table Format, Next: Transformations On Symbol Tables, Up: Symbol Tables + +7.1 Symbol Table Format +======================= + +Each time the assembler encounters a stab directive, it puts each field +of the stab into a corresponding field in a symbol table entry of its +output file. If the stab contains a string field, the symbol table +entry for that stab points to a string table entry containing the string +data from the stab. Assembler labels become relocatable addresses. +Symbol table entries in a.out have the format: + + struct internal_nlist { + unsigned long n_strx; /* index into string table of name */ + unsigned char n_type; /* type of symbol */ + unsigned char n_other; /* misc info (usually empty) */ + unsigned short n_desc; /* description field */ + bfd_vma n_value; /* value of symbol */ + }; + + If the stab has a string, the 'n_strx' field holds the offset in +bytes of the string within the string table. The string is terminated +by a NUL character. If the stab lacks a string (for example, it was +produced by a '.stabn' or '.stabd' directive), the 'n_strx' field is +zero. + + Symbol table entries with 'n_type' field values greater than 0x1f +originated as stabs generated by the compiler (with one random +exception). The other entries were placed in the symbol table of the +executable by the assembler or the linker. + + +File: stabs.info, Node: Transformations On Symbol Tables, Prev: Symbol Table Format, Up: Symbol Tables + +7.2 Transformations on Symbol Tables +==================================== + +The linker concatenates object files and does fixups of externally +defined symbols. + + You can see the transformations made on stab data by the assembler +and linker by examining the symbol table after each pass of the build. +To do this, use 'nm -ap', which dumps the symbol table, including +debugging information, unsorted. For stab entries the columns are: +VALUE, OTHER, DESC, TYPE, STRING. For assembler and linker symbols, the +columns are: VALUE, TYPE, STRING. + + The low 5 bits of the stab type tell the linker how to relocate the +value of the stab. Thus for stab types like 'N_RSYM' and 'N_LSYM', +where the value is an offset or a register number, the low 5 bits are +'N_ABS', which tells the linker not to relocate the value. + + Where the value of a stab contains an assembly language label, it is +transformed by each build step. The assembler turns it into a +relocatable address and the linker turns it into an absolute address. + +* Menu: + +* Transformations On Static Variables:: +* Transformations On Global Variables:: +* Stab Section Transformations:: For some object file formats, + things are a bit different. + + +File: stabs.info, Node: Transformations On Static Variables, Next: Transformations On Global Variables, Up: Transformations On Symbol Tables + +7.2.1 Transformations on Static Variables +----------------------------------------- + +This source line defines a static variable at file scope: + + static int s_g_repeat + +The following stab describes the symbol: + + .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat + +The assembler transforms the stab into this symbol table entry in the +'.o' file. The location is expressed as a data segment offset. + + 00000084 - 00 0000 STSYM s_g_repeat:S1 + +In the symbol table entry from the executable, the linker has made the +relocatable address absolute. + + 0000e00c - 00 0000 STSYM s_g_repeat:S1 + + +File: stabs.info, Node: Transformations On Global Variables, Next: Stab Section Transformations, Prev: Transformations On Static Variables, Up: Transformations On Symbol Tables + +7.2.2 Transformations on Global Variables +----------------------------------------- + +Stabs for global variables do not contain location information. In this +case, the debugger finds location information in the assembler or linker +symbol table entry describing the variable. The source line: + + char g_foo = 'c'; + +generates the stab: + + .stabs "g_foo:G2",32,0,0,0 + + The variable is represented by two symbol table entries in the object +file (see below). The first one originated as a stab. The second one +is an external symbol. The upper case 'D' signifies that the 'n_type' +field of the symbol table contains 7, 'N_DATA' with local linkage. The +stab's value is zero since the value is not used for 'N_GSYM' stabs. +The value of the linker symbol is the relocatable address corresponding +to the variable. + + 00000000 - 00 0000 GSYM g_foo:G2 + 00000080 D _g_foo + +These entries as transformed by the linker. The linker symbol table +entry now holds an absolute address: + + 00000000 - 00 0000 GSYM g_foo:G2 + ... + 0000e008 D _g_foo + + +File: stabs.info, Node: Stab Section Transformations, Prev: Transformations On Global Variables, Up: Transformations On Symbol Tables + +7.2.3 Transformations of Stabs in separate sections +--------------------------------------------------- + +For object file formats using stabs in separate sections (*note Stab +Sections::), use 'objdump --stabs' instead of 'nm' to show the stabs in +an object or executable file. 'objdump' is a GNU utility; Sun does not +provide any equivalent. + + The following example is for a stab whose value is an address is +relative to the compilation unit (*note ELF Linker Relocation::). For +example, if the source line + + static int ld = 5; + + appears within a function, then the assembly language output from the +compiler contains: + + .Ddata.data: + ... + .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data # 0x26 is N_STSYM + ... + .L18: + .align 4 + .word 0x5 + + Because the value is formed by subtracting one symbol from another, +the value is absolute, not relocatable, and so the object file contains + + Symnum n_type n_othr n_desc n_value n_strx String + 31 STSYM 0 4 00000004 680 ld:V(0,3) + + without any relocations, and the executable file also contains + + Symnum n_type n_othr n_desc n_value n_strx String + 31 STSYM 0 4 00000004 680 ld:V(0,3) + + +File: stabs.info, Node: Cplusplus, Next: Stab Types, Prev: Symbol Tables, Up: Top + +8 GNU C++ Stabs +*************** + +* Menu: + +* Class Names:: C++ class names are both tags and typedefs. +* Nested Symbols:: C++ symbol names can be within other types. +* Basic Cplusplus Types:: +* Simple Classes:: +* Class Instance:: +* Methods:: Method definition +* Method Type Descriptor:: The '#' type descriptor +* Member Type Descriptor:: The '@' type descriptor +* Protections:: +* Method Modifiers:: +* Virtual Methods:: +* Inheritance:: +* Virtual Base Classes:: +* Static Members:: + + +File: stabs.info, Node: Class Names, Next: Nested Symbols, Up: Cplusplus + +8.1 C++ Class Names +=================== + +In C++, a class name which is declared with 'class', 'struct', or +'union', is not only a tag, as in C, but also a type name. Thus there +should be stabs with both 't' and 'T' symbol descriptors (*note +Typedefs::). + + To save space, there is a special abbreviation for this case. If the +'T' symbol descriptor is followed by 't', then the stab defines both a +type name and a tag. + + For example, the C++ code + + struct foo {int x;}; + + can be represented as either + + .stabs "foo:T19=s4x:1,0,32;;",128,0,0,0 # 128 is N_LSYM + .stabs "foo:t19",128,0,0,0 + + or + + .stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0 + + +File: stabs.info, Node: Nested Symbols, Next: Basic Cplusplus Types, Prev: Class Names, Up: Cplusplus + +8.2 Defining a Symbol Within Another Type +========================================= + +In C++, a symbol (such as a type name) can be defined within another +type. + + In stabs, this is sometimes represented by making the name of a +symbol which contains '::'. Such a pair of colons does not end the name +of the symbol, the way a single colon would (*note String Field::). I'm +not sure how consistently used or well thought out this mechanism is. +So that a pair of colons in this position always has this meaning, ':' +cannot be used as a symbol descriptor. + + For example, if the string for a stab is 'foo::bar::baz:t5=*6', then +'foo::bar::baz' is the name of the symbol, 't' is the symbol descriptor, +and '5=*6' is the type information. + + +File: stabs.info, Node: Basic Cplusplus Types, Next: Simple Classes, Prev: Nested Symbols, Up: Cplusplus + +8.3 Basic Types For C++ +======================= + +<< the examples that follow are based on a01.C >> + + C++ adds two more builtin types to the set defined for C. These are +the unknown type and the vtable record type. The unknown type, type 16, +is defined in terms of itself like the void type. + + The vtable record type, type 17, is defined as a structure type and +then as a structure tag. The structure has four fields: delta, index, +pfn, and delta2. pfn is the function pointer. + + << In boilerplate $vtbl_ptr_type, what are the fields delta, index, +and delta2 used for? >> + + This basic type is present in all C++ programs even if there are no +virtual methods defined. + + .stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8) + elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16); + elem_name(index):type_ref(short int),bit_offset(16),field_bits(16); + elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void), + bit_offset(32),field_bits(32); + elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;" + N_LSYM, NIL, NIL + + .stabs "$vtbl_ptr_type:t17=s8 + delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;" + ,128,0,0,0 + + .stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL + + .stabs "$vtbl_ptr_type:T17",128,0,0,0 + + +File: stabs.info, Node: Simple Classes, Next: Class Instance, Prev: Basic Cplusplus Types, Up: Cplusplus + +8.4 Simple Class Definition +=========================== + +The stabs describing C++ language features are an extension of the stabs +describing C. Stabs representing C++ class types elaborate extensively +on the stab format used to describe structure types in C. Stabs +representing class type variables look just like stabs representing C +language variables. + + Consider the following very simple class definition. + + class baseA { + public: + int Adat; + int Ameth(int in, char other); + }; + + The class 'baseA' is represented by two stabs. The first stab +describes the class as a structure type. The second stab describes a +structure tag of the class type. Both stabs are of stab type 'N_LSYM'. +Since the stab is not located between an 'N_FUN' and an 'N_LBRAC' stab +this indicates that the class is defined at file scope. If it were, +then the 'N_LSYM' would signify a local variable. + + A stab describing a C++ class type is similar in format to a stab +describing a C struct, with each class member shown as a field in the +structure. The part of the struct format describing fields is expanded +to include extra information relevant to C++ class members. In +addition, if the class has multiple base classes or virtual functions +the struct format outside of the field parts is also augmented. + + In this simple example the field part of the C++ class stab +representing member data looks just like the field part of a C struct +stab. The section on protections describes how its format is sometimes +extended for member data. + + The field part of a C++ class stab representing a member function +differs substantially from the field part of a C struct stab. It still +begins with 'name:' but then goes on to define a new type number for the +member function, describe its return type, its argument types, its +protection level, any qualifiers applied to the method definition, and +whether the method is virtual or not. If the method is virtual then the +method description goes on to give the vtable index of the method, and +the type number of the first base class defining the method. + + When the field name is a method name it is followed by two colons +rather than one. This is followed by a new type definition for the +method. This is a number followed by an equal sign and the type of the +method. Normally this will be a type declared using the '#' type +descriptor; see *note Method Type Descriptor::; static member functions +are declared using the 'f' type descriptor instead; see *note Function +Types::. + + The format of an overloaded operator method name differs from that of +other methods. It is 'op$::OPERATOR-NAME.' where OPERATOR-NAME is the +operator name such as '+' or '+='. The name ends with a period, and any +characters except the period can occur in the OPERATOR-NAME string. + + The next part of the method description represents the arguments to +the method, preceded by a colon and ending with a semi-colon. The types +of the arguments are expressed in the same way argument types are +expressed in C++ name mangling. In this example an 'int' and a 'char' +map to 'ic'. + + This is followed by a number, a letter, and an asterisk or period, +followed by another semicolon. The number indicates the protections +that apply to the member function. Here the 2 means public. The letter +encodes any qualifier applied to the method definition. In this case, +'A' means that it is a normal function definition. The dot shows that +the method is not virtual. The sections that follow elaborate further +on these fields and describe the additional information present for +virtual methods. + + .stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4) + field_name(Adat):type(int),bit_offset(0),field_bits(32); + + method_name(Ameth)::type_def(21)=type_desc(method)return_type(int); + :arg_types(int char); + protection(public)qualifier(normal)virtual(no);;" + N_LSYM,NIL,NIL,NIL + + .stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0 + + .stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL + + .stabs "baseA:T20",128,0,0,0 + + +File: stabs.info, Node: Class Instance, Next: Methods, Prev: Simple Classes, Up: Cplusplus + +8.5 Class Instance +================== + +As shown above, describing even a simple C++ class definition is +accomplished by massively extending the stab format used in C to +describe structure types. However, once the class is defined, C stabs +with no modifications can be used to describe class instances. The +following source: + + main () { + baseA AbaseA; + } + +yields the following stab describing the class instance. It looks no +different from a standard C stab describing a local variable. + + .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset + + .stabs "AbaseA:20",128,0,0,-20 + + +File: stabs.info, Node: Methods, Next: Method Type Descriptor, Prev: Class Instance, Up: Cplusplus + +8.6 Method Definition +===================== + +The class definition shown above declares Ameth. The C++ source below +defines Ameth: + + int + baseA::Ameth(int in, char other) + { + return in; + }; + + This method definition yields three stabs following the code of the +method. One stab describes the method itself and following two describe +its parameters. Although there is only one formal argument all methods +have an implicit argument which is the 'this' pointer. The 'this' +pointer is a pointer to the object on which the method was called. Note +that the method name is mangled to encode the class name and argument +types. Name mangling is described in the ARM ('The Annotated C++ +Reference Manual', by Ellis and Stroustrup, ISBN 0-201-51459-1); +'gpcompare.texi' in Cygnus GCC distributions describes the differences +between GNU mangling and ARM mangling. + + .stabs "name:symbol_descriptor(global function)return_type(int)", + N_FUN, NIL, NIL, code_addr_of_method_start + + .stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic + + Here is the stab for the 'this' pointer implicit argument. The name +of the 'this' pointer is always 'this'. Type 19, the 'this' pointer is +defined as a pointer to type 20, 'baseA', but a stab defining 'baseA' +has not yet been emitted. Since the compiler knows it will be emitted +shortly, here it just outputs a cross reference to the undefined symbol, +by prefixing the symbol name with 'xs'. + + .stabs "name:sym_desc(register param)type_def(19)= + type_desc(ptr to)type_ref(baseA)= + type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number + + .stabs "this:P19=*20=xsbaseA:",64,0,0,8 + + The stab for the explicit integer argument looks just like a +parameter to a C function. The last field of the stab is the offset +from the argument pointer, which in most systems is the same as the +frame pointer. + + .stabs "name:sym_desc(value parameter)type_ref(int)", + N_PSYM,NIL,NIL,offset_from_arg_ptr + + .stabs "in:p1",160,0,0,72 + + << The examples that follow are based on A1.C >> + + +File: stabs.info, Node: Method Type Descriptor, Next: Member Type Descriptor, Prev: Methods, Up: Cplusplus + +8.7 The '#' Type Descriptor +=========================== + +This is used to describe a class method. This is a function which takes +an extra argument as its first argument, for the 'this' pointer. + + If the '#' is immediately followed by another '#', the second one +will be followed by the return type and a semicolon. The class and +argument types are not specified, and must be determined by demangling +the name of the method if it is available. + + Otherwise, the single '#' is followed by the class type, a comma, the +return type, a comma, and zero or more parameter types separated by +commas. The list of arguments is terminated by a semicolon. In the +debugging output generated by gcc, a final argument type of 'void' +indicates a method which does not take a variable number of arguments. +If the final argument type of 'void' does not appear, the method was +declared with an ellipsis. + + Note that although such a type will normally be used to describe +fields in structures, unions, or classes, for at least some versions of +the compiler it can also be used in other contexts. + + +File: stabs.info, Node: Member Type Descriptor, Next: Protections, Prev: Method Type Descriptor, Up: Cplusplus + +8.8 The '@' Type Descriptor +=========================== + +The '@' type descriptor is used for a pointer-to-non-static-member-data +type. It is followed by type information for the class (or union), a +comma, and type information for the member data. + + The following C++ source: + + typedef int A::*int_in_a; + + generates the following stab: + + .stabs "int_in_a:t20=21=@19,1",128,0,0,0 + + Note that there is a conflict between this and type attributes (*note +String Field::); both use type descriptor '@'. Fortunately, the '@' +type descriptor used in this C++ sense always will be followed by a +digit, '(', or '-', and type attributes never start with those things. + + +File: stabs.info, Node: Protections, Next: Method Modifiers, Prev: Member Type Descriptor, Up: Cplusplus + +8.9 Protections +=============== + +In the simple class definition shown above all member data and functions +were publicly accessible. The example that follows contrasts public, +protected and privately accessible fields and shows how these +protections are encoded in C++ stabs. + + If the character following the 'FIELD-NAME:' part of the string is +'/', then the next character is the visibility. '0' means private, '1' +means protected, and '2' means public. Debuggers should ignore +visibility characters they do not recognize, and assume a reasonable +default (such as public) (GDB 4.11 does not, but this should be fixed in +the next GDB release). If no visibility is specified the field is +public. The visibility '9' means that the field has been optimized out +and is public (there is no way to specify an optimized out field with a +private or protected visibility). Visibility '9' is not supported by +GDB 4.11; this should be fixed in the next GDB release. + + The following C++ source: + + class vis { + private: + int priv; + protected: + char prot; + public: + float pub; + }; + +generates the following stab: + + # 128 is N_LSYM + .stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0 + + 'vis:T19=s12' indicates that type number 19 is a 12 byte structure +named 'vis' The 'priv' field has public visibility ('/0'), type int +('1'), and offset and size ',0,32;'. The 'prot' field has protected +visibility ('/1'), type char ('2') and offset and size ',32,8;'. The +'pub' field has type float ('12'), and offset and size ',64,32;'. + + Protections for member functions are signified by one digit embedded +in the field part of the stab describing the method. The digit is 0 if +private, 1 if protected and 2 if public. Consider the C++ class +definition below: + + class all_methods { + private: + int priv_meth(int in){return in;}; + protected: + char protMeth(char in){return in;}; + public: + float pubMeth(float in){return in;}; + }; + + It generates the following stab. The digit in question is to the +left of an 'A' in each case. Notice also that in this case two symbol +descriptors apply to the class name struct tag and struct type. + + .stabs "class_name:sym_desc(struct tag&type)type_def(21)= + sym_desc(struct)struct_bytes(1) + meth_name::type_def(22)=sym_desc(method)returning(int); + :args(int);protection(private)modifier(normal)virtual(no); + meth_name::type_def(23)=sym_desc(method)returning(char); + :args(char);protection(protected)modifier(normal)virtual(no); + meth_name::type_def(24)=sym_desc(method)returning(float); + :args(float);protection(public)modifier(normal)virtual(no);;", + N_LSYM,NIL,NIL,NIL + + .stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.; + pubMeth::24=##12;:f;2A.;;",128,0,0,0 + + +File: stabs.info, Node: Method Modifiers, Next: Virtual Methods, Prev: Protections, Up: Cplusplus + +8.10 Method Modifiers ('const', 'volatile', 'const volatile') +============================================================= + +<< based on a6.C >> + + In the class example described above all the methods have the normal +modifier. This method modifier information is located just after the +protection information for the method. This field has four possible +character values. Normal methods use 'A', const methods use 'B', +volatile methods use 'C', and const volatile methods use 'D'. Consider +the class definition below: + + class A { + public: + int ConstMeth (int arg) const { return arg; }; + char VolatileMeth (char arg) volatile { return arg; }; + float ConstVolMeth (float arg) const volatile {return arg; }; + }; + + This class is described by the following stab: + + .stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1) + meth_name(ConstMeth)::type_def(21)sym_desc(method) + returning(int);:arg(int);protection(public)modifier(const)virtual(no); + meth_name(VolatileMeth)::type_def(22)=sym_desc(method) + returning(char);:arg(char);protection(public)modifier(volatile)virt(no) + meth_name(ConstVolMeth)::type_def(23)=sym_desc(method) + returning(float);:arg(float);protection(public)modifier(const volatile) + virtual(no);;", ... + + .stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.; + ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0 + + +File: stabs.info, Node: Virtual Methods, Next: Inheritance, Prev: Method Modifiers, Up: Cplusplus + +8.11 Virtual Methods +==================== + +<< The following examples are based on a4.C >> + + The presence of virtual methods in a class definition adds additional +data to the class description. The extra data is appended to the +description of the virtual method and to the end of the class +description. Consider the class definition below: + + class A { + public: + int Adat; + virtual int A_virt (int arg) { return arg; }; + }; + + This results in the stab below describing class A. It defines a new +type (20) which is an 8 byte structure. The first field of the class +struct is 'Adat', an integer, starting at structure offset 0 and +occupying 32 bits. + + The second field in the class struct is not explicitly defined by the +C++ class definition but is implied by the fact that the class contains +a virtual method. This field is the vtable pointer. The name of the +vtable pointer field starts with '$vf' and continues with a type +reference to the class it is part of. In this example the type +reference for class A is 20 so the name of its vtable pointer field is +'$vf20', followed by the usual colon. + + Next there is a type definition for the vtable pointer type (21). +This is in turn defined as a pointer to another new type (22). + + Type 22 is the vtable itself, which is defined as an array, indexed +by a range of integers between 0 and 1, and whose elements are of type +17. Type 17 was the vtable record type defined by the boilerplate C++ +type definitions, as shown earlier. + + The bit offset of the vtable pointer field is 32. The number of bits +in the field are not specified when the field is a vtable pointer. + + Next is the method definition for the virtual member function +'A_virt'. Its description starts out using the same format as the +non-virtual member functions described above, except instead of a dot +after the 'A' there is an asterisk, indicating that the function is +virtual. Since is is virtual some addition information is appended to +the end of the method description. + + The first number represents the vtable index of the method. This is +a 32 bit unsigned number with the high bit set, followed by a +semi-colon. + + The second number is a type reference to the first base class in the +inheritance hierarchy defining the virtual member function. In this +case the class stab describes a base class so the virtual function is +not overriding any other definition of the method. Therefore the +reference is to the type number of the class that the stab is describing +(20). + + This is followed by three semi-colons. One marks the end of the +current sub-section, one marks the end of the method field, and the +third marks the end of the struct definition. + + For classes containing virtual functions the very last section of the +string part of the stab holds a type reference to the first base class. +This is preceded by '~%' and followed by a final semi-colon. + + .stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8) + field_name(Adat):type_ref(int),bit_offset(0),field_bits(32); + field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)= + sym_desc(array)index_type_ref(range of int from 0 to 1); + elem_type_ref(vtbl elem type), + bit_offset(32); + meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int); + :arg_type(int),protection(public)normal(yes)virtual(yes) + vtable_index(1);class_first_defining(A);;;~%first_base(A);", + N_LSYM,NIL,NIL,NIL + + .stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; + A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 + + +File: stabs.info, Node: Inheritance, Next: Virtual Base Classes, Prev: Virtual Methods, Up: Cplusplus + +8.12 Inheritance +================ + +Stabs describing C++ derived classes include additional sections that +describe the inheritance hierarchy of the class. A derived class stab +also encodes the number of base classes. For each base class it tells +if the base class is virtual or not, and if the inheritance is private +or public. It also gives the offset into the object of the portion of +the object corresponding to each base class. + + This additional information is embedded in the class stab following +the number of bytes in the struct. First the number of base classes +appears bracketed by an exclamation point and a comma. + + Then for each base type there repeats a series: a virtual character, +a visibility character, a number, a comma, another number, and a +semi-colon. + + The virtual character is '1' if the base class is virtual and '0' if +not. The visibility character is '2' if the derivation is public, '1' +if it is protected, and '0' if it is private. Debuggers should ignore +virtual or visibility characters they do not recognize, and assume a +reasonable default (such as public and non-virtual) (GDB 4.11 does not, +but this should be fixed in the next GDB release). + + The number following the virtual and visibility characters is the +offset from the start of the object to the part of the object pertaining +to the base class. + + After the comma, the second number is a type_descriptor for the base +type. Finally a semi-colon ends the series, which repeats for each base +class. + + The source below defines three base classes 'A', 'B', and 'C' and the +derived class 'D'. + + class A { + public: + int Adat; + virtual int A_virt (int arg) { return arg; }; + }; + + class B { + public: + int B_dat; + virtual int B_virt (int arg) {return arg; }; + }; + + class C { + public: + int Cdat; + virtual int C_virt (int arg) {return arg; }; + }; + + class D : A, virtual B, public C { + public: + int Ddat; + virtual int A_virt (int arg ) { return arg+1; }; + virtual int B_virt (int arg) { return arg+2; }; + virtual int C_virt (int arg) { return arg+3; }; + virtual int D_virt (int arg) { return arg; }; + }; + + Class stabs similar to the ones described earlier are generated for +each base class. + + .stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; + A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 + + .stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1; + :i;2A*-2147483647;25;;;~%25;",128,0,0,0 + + .stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1; + :i;2A*-2147483647;28;;;~%28;",128,0,0,0 + + In the stab describing derived class 'D' below, the information about +the derivation of this class is encoded as follows. + + .stabs "derived_class_name:symbol_descriptors(struct tag&type)= + type_descriptor(struct)struct_bytes(32)!num_bases(3), + base_virtual(no)inheritance_public(no)base_offset(0), + base_class_type_ref(A); + base_virtual(yes)inheritance_public(no)base_offset(NIL), + base_class_type_ref(B); + base_virtual(no)inheritance_public(yes)base_offset(64), + base_class_type_ref(C); ... + + .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat: + 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt: + :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647; + 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 + + +File: stabs.info, Node: Virtual Base Classes, Next: Static Members, Prev: Inheritance, Up: Cplusplus + +8.13 Virtual Base Classes +========================= + +A derived class object consists of a concatenation in memory of the data +areas defined by each base class, starting with the leftmost and ending +with the rightmost in the list of base classes. The exception to this +rule is for virtual inheritance. In the example above, class 'D' +inherits virtually from base class 'B'. This means that an instance of +a 'D' object will not contain its own 'B' part but merely a pointer to a +'B' part, known as a virtual base pointer. + + In a derived class stab, the base offset part of the derivation +information, described above, shows how the base class parts are +ordered. The base offset for a virtual base class is always given as 0. +Notice that the base offset for 'B' is given as 0 even though 'B' is not +the first base class. The first base class 'A' starts at offset 0. + + The field information part of the stab for class 'D' describes the +field which is the pointer to the virtual base class 'B'. The vbase +pointer name is '$vb' followed by a type reference to the virtual base +class. Since the type id for 'B' in this example is 25, the vbase +pointer name is '$vb25'. + + .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1, + 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i; + 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt: + :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 + + Following the name and a semicolon is a type reference describing the +type of the virtual base class pointer, in this case 24. Type 24 was +defined earlier as the type of the 'B' class 'this' pointer. The 'this' +pointer for a class is a pointer to the class type. + + .stabs "this:P24=*25=xsB:",64,0,0,8 + + Finally the field offset part of the vbase pointer field description +shows that the vbase pointer is the first field in the 'D' object, +before any data fields defined by the class. The layout of a 'D' class +object is a follows, 'Adat' at 0, the vtable pointer for 'A' at 32, +'Cdat' at 64, the vtable pointer for C at 96, the virtual base pointer +for 'B' at 128, and 'Ddat' at 160. + + +File: stabs.info, Node: Static Members, Prev: Virtual Base Classes, Up: Cplusplus + +8.14 Static Members +=================== + +The data area for a class is a concatenation of the space used by the +data members of the class. If the class has virtual methods, a vtable +pointer follows the class data. The field offset part of each field +description in the class stab shows this ordering. + + << How is this reflected in stabs? See Cygnus bug #677 for some +info. >> + + +File: stabs.info, Node: Stab Types, Next: Symbol Descriptors, Prev: Cplusplus, Up: Top + +Appendix A Table of Stab Types +****************************** + +The following are all the possible values for the stab type field, for +a.out files, in numeric order. This does not apply to XCOFF, but it +does apply to stabs in sections (*note Stab Sections::). Stabs in ECOFF +use these values but add 0x8f300 to distinguish them from non-stab +symbols. + + The symbolic names are defined in the file 'include/aout/stabs.def'. + +* Menu: + +* Non-Stab Symbol Types:: Types from 0 to 0x1f +* Stab Symbol Types:: Types from 0x20 to 0xff + + +File: stabs.info, Node: Non-Stab Symbol Types, Next: Stab Symbol Types, Up: Stab Types + +A.1 Non-Stab Symbol Types +========================= + +The following types are used by the linker and assembler, not by stab +directives. Since this document does not attempt to describe aspects of +object file format other than the debugging format, no details are +given. + +'0x0 N_UNDF' + Undefined symbol + +'0x2 N_ABS' + File scope absolute symbol + +'0x3 N_ABS | N_EXT' + External absolute symbol + +'0x4 N_TEXT' + File scope text symbol + +'0x5 N_TEXT | N_EXT' + External text symbol + +'0x6 N_DATA' + File scope data symbol + +'0x7 N_DATA | N_EXT' + External data symbol + +'0x8 N_BSS' + File scope BSS symbol + +'0x9 N_BSS | N_EXT' + External BSS symbol + +'0x0c N_FN_SEQ' + Same as 'N_FN', for Sequent compilers + +'0x0a N_INDR' + Symbol is indirected to another symbol + +'0x12 N_COMM' + Common--visible after shared library dynamic link + +'0x14 N_SETA' +'0x15 N_SETA | N_EXT' + Absolute set element + +'0x16 N_SETT' +'0x17 N_SETT | N_EXT' + Text segment set element + +'0x18 N_SETD' +'0x19 N_SETD | N_EXT' + Data segment set element + +'0x1a N_SETB' +'0x1b N_SETB | N_EXT' + BSS segment set element + +'0x1c N_SETV' +'0x1d N_SETV | N_EXT' + Pointer to set vector + +'0x1e N_WARNING' + Print a warning message during linking + +'0x1f N_FN' + File name of a '.o' file + + +File: stabs.info, Node: Stab Symbol Types, Prev: Non-Stab Symbol Types, Up: Stab Types + +A.2 Stab Symbol Types +===================== + +The following symbol types indicate that this is a stab. This is the +full list of stab numbers, including stab types that are used in +languages other than C. + +'0x20 N_GSYM' + Global symbol; see *note Global Variables::. + +'0x22 N_FNAME' + Function name (for BSD Fortran); see *note Procedures::. + +'0x24 N_FUN' + Function name (*note Procedures::) or text segment variable (*note + Statics::). + +'0x26 N_STSYM' + Data segment file-scope variable; see *note Statics::. + +'0x28 N_LCSYM' + BSS segment file-scope variable; see *note Statics::. + +'0x2a N_MAIN' + Name of main routine; see *note Main Program::. + +'0x2c N_ROSYM' + Variable in '.rodata' section; see *note Statics::. + +'0x30 N_PC' + Global symbol (for Pascal); see *note N_PC::. + +'0x32 N_NSYMS' + Number of symbols (according to Ultrix V4.0); see *note N_NSYMS::. + +'0x34 N_NOMAP' + No DST map; see *note N_NOMAP::. + +'0x36 N_MAC_DEFINE' + Name and body of a '#define'd macro; see *note Macro define and + undefine::. + +'0x38 N_OBJ' + Object file (Solaris2). + +'0x3a N_MAC_UNDEF' + Name of an '#undef'ed macro; see *note Macro define and undefine::. + +'0x3c N_OPT' + Debugger options (Solaris2). + +'0x40 N_RSYM' + Register variable; see *note Register Variables::. + +'0x42 N_M2C' + Modula-2 compilation unit; see *note N_M2C::. + +'0x44 N_SLINE' + Line number in text segment; see *note Line Numbers::. + +'0x46 N_DSLINE' + Line number in data segment; see *note Line Numbers::. + +'0x48 N_BSLINE' + Line number in bss segment; see *note Line Numbers::. + +'0x48 N_BROWS' + Sun source code browser, path to '.cb' file; see *note N_BROWS::. + +'0x4a N_DEFD' + GNU Modula2 definition module dependency; see *note N_DEFD::. + +'0x4c N_FLINE' + Function start/body/end line numbers (Solaris2). + +'0x50 N_EHDECL' + GNU C++ exception variable; see *note N_EHDECL::. + +'0x50 N_MOD2' + Modula2 info "for imc" (according to Ultrix V4.0); see *note + N_MOD2::. + +'0x54 N_CATCH' + GNU C++ 'catch' clause; see *note N_CATCH::. + +'0x60 N_SSYM' + Structure of union element; see *note N_SSYM::. + +'0x62 N_ENDM' + Last stab for module (Solaris2). + +'0x64 N_SO' + Path and name of source file; see *note Source Files::. + +'0x80 N_LSYM' + Stack variable (*note Stack Variables::) or type (*note + Typedefs::). + +'0x82 N_BINCL' + Beginning of an include file (Sun only); see *note Include Files::. + +'0x84 N_SOL' + Name of include file; see *note Include Files::. + +'0xa0 N_PSYM' + Parameter variable; see *note Parameters::. + +'0xa2 N_EINCL' + End of an include file; see *note Include Files::. + +'0xa4 N_ENTRY' + Alternate entry point; see *note Alternate Entry Points::. + +'0xc0 N_LBRAC' + Beginning of a lexical block; see *note Block Structure::. + +'0xc2 N_EXCL' + Place holder for a deleted include file; see *note Include Files::. + +'0xc4 N_SCOPE' + Modula2 scope information (Sun linker); see *note N_SCOPE::. + +'0xe0 N_RBRAC' + End of a lexical block; see *note Block Structure::. + +'0xe2 N_BCOMM' + Begin named common block; see *note Common Blocks::. + +'0xe4 N_ECOMM' + End named common block; see *note Common Blocks::. + +'0xe8 N_ECOML' + Member of a common block; see *note Common Blocks::. + +'0xea N_WITH' + Pascal 'with' statement: type,,0,0,offset (Solaris2). + +'0xf0 N_NBTEXT' + Gould non-base registers; see *note Gould::. + +'0xf2 N_NBDATA' + Gould non-base registers; see *note Gould::. + +'0xf4 N_NBBSS' + Gould non-base registers; see *note Gould::. + +'0xf6 N_NBSTS' + Gould non-base registers; see *note Gould::. + +'0xf8 N_NBLCS' + Gould non-base registers; see *note Gould::. + + +File: stabs.info, Node: Symbol Descriptors, Next: Type Descriptors, Prev: Stab Types, Up: Top + +Appendix B Table of Symbol Descriptors +************************************** + +The symbol descriptor is the character which follows the colon in many +stabs, and which tells what kind of stab it is. *Note String Field::, +for more information about their use. + +'DIGIT' +'(' +'-' + Variable on the stack; see *note Stack Variables::. + +':' + C++ nested symbol; see *Note Nested Symbols::. + +'a' + Parameter passed by reference in register; see *note Reference + Parameters::. + +'b' + Based variable; see *note Based Variables::. + +'c' + Constant; see *note Constants::. + +'C' + Conformant array bound (Pascal, maybe other languages); *note + Conformant Arrays::. Name of a caught exception (GNU C++). These + can be distinguished because the latter uses 'N_CATCH' and the + former uses another symbol type. + +'d' + Floating point register variable; see *note Register Variables::. + +'D' + Parameter in floating point register; see *note Register + Parameters::. + +'f' + File scope function; see *note Procedures::. + +'F' + Global function; see *note Procedures::. + +'G' + Global variable; see *note Global Variables::. + +'i' + *Note Register Parameters::. + +'I' + Internal (nested) procedure; see *note Nested Procedures::. + +'J' + Internal (nested) function; see *note Nested Procedures::. + +'L' + Label name (documented by AIX, no further information known). + +'m' + Module; see *note Procedures::. + +'p' + Argument list parameter; see *note Parameters::. + +'pP' + *Note Parameters::. + +'pF' + Fortran Function parameter; see *note Parameters::. + +'P' + Unfortunately, three separate meanings have been independently + invented for this symbol descriptor. At least the GNU and Sun uses + can be distinguished by the symbol type. Global Procedure (AIX) + (symbol type used unknown); see *note Procedures::. Register + parameter (GNU) (symbol type 'N_PSYM'); see *note Parameters::. + Prototype of function referenced by this file (Sun 'acc') (symbol + type 'N_FUN'). + +'Q' + Static Procedure; see *note Procedures::. + +'R' + Register parameter; see *note Register Parameters::. + +'r' + Register variable; see *note Register Variables::. + +'S' + File scope variable; see *note Statics::. + +'s' + Local variable (OS9000). + +'t' + Type name; see *note Typedefs::. + +'T' + Enumeration, structure, or union tag; see *note Typedefs::. + +'v' + Parameter passed by reference; see *note Reference Parameters::. + +'V' + Procedure scope static variable; see *note Statics::. + +'x' + Conformant array; see *note Conformant Arrays::. + +'X' + Function return variable; see *note Parameters::. + + +File: stabs.info, Node: Type Descriptors, Next: Expanded Reference, Prev: Symbol Descriptors, Up: Top + +Appendix C Table of Type Descriptors +************************************ + +The type descriptor is the character which follows the type number and +an equals sign. It specifies what kind of type is being defined. *Note +String Field::, for more information about their use. + +'DIGIT' +'(' + Type reference; see *note String Field::. + +'-' + Reference to builtin type; see *note Negative Type Numbers::. + +'#' + Method (C++); see *note Method Type Descriptor::. + +'*' + Pointer; see *note Miscellaneous Types::. + +'&' + Reference (C++). + +'@' + Type Attributes (AIX); see *note String Field::. Member (class and + variable) type (GNU C++); see *note Member Type Descriptor::. + +'a' + Array; see *note Arrays::. + +'A' + Open array; see *note Arrays::. + +'b' + Pascal space type (AIX); see *note Miscellaneous Types::. Builtin + integer type (Sun); see *note Builtin Type Descriptors::. Const + and volatile qualified type (OS9000). + +'B' + Volatile-qualified type; see *note Miscellaneous Types::. + +'c' + Complex builtin type (AIX); see *note Builtin Type Descriptors::. + Const-qualified type (OS9000). + +'C' + COBOL Picture type. See AIX documentation for details. + +'d' + File type; see *note Miscellaneous Types::. + +'D' + N-dimensional dynamic array; see *note Arrays::. + +'e' + Enumeration type; see *note Enumerations::. + +'E' + N-dimensional subarray; see *note Arrays::. + +'f' + Function type; see *note Function Types::. + +'F' + Pascal function parameter; see *note Function Types:: + +'g' + Builtin floating point type; see *note Builtin Type Descriptors::. + +'G' + COBOL Group. See AIX documentation for details. + +'i' + Imported type (AIX); see *note Cross-References::. + Volatile-qualified type (OS9000). + +'k' + Const-qualified type; see *note Miscellaneous Types::. + +'K' + COBOL File Descriptor. See AIX documentation for details. + +'M' + Multiple instance type; see *note Miscellaneous Types::. + +'n' + String type; see *note Strings::. + +'N' + Stringptr; see *note Strings::. + +'o' + Opaque type; see *note Typedefs::. + +'p' + Procedure; see *note Function Types::. + +'P' + Packed array; see *note Arrays::. + +'r' + Range type; see *note Subranges::. + +'R' + Builtin floating type; see *note Builtin Type Descriptors:: (Sun). + Pascal subroutine parameter; see *note Function Types:: (AIX). + Detecting this conflict is possible with careful parsing (hint: a + Pascal subroutine parameter type will always contain a comma, and a + builtin type descriptor never will). + +'s' + Structure type; see *note Structures::. + +'S' + Set type; see *note Miscellaneous Types::. + +'u' + Union; see *note Unions::. + +'v' + Variant record. This is a Pascal and Modula-2 feature which is + like a union within a struct in C. See AIX documentation for + details. + +'w' + Wide character; see *note Builtin Type Descriptors::. + +'x' + Cross-reference; see *note Cross-References::. + +'Y' + Used by IBM's xlC C++ compiler (for structures, I think). + +'z' + gstring; see *note Strings::. + + +File: stabs.info, Node: Expanded Reference, Next: Questions, Prev: Type Descriptors, Up: Top + +Appendix D Expanded Reference by Stab Type +****************************************** + +For a full list of stab types, and cross-references to where they are +described, see *note Stab Types::. This appendix just covers certain +stabs which are not yet described in the main body of this document; +eventually the information will all be in one place. + + Format of an entry: + + The first line is the symbol type (see 'include/aout/stab.def'). + + The second line describes the language constructs the symbol type +represents. + + The third line is the stab format with the significant stab fields +named and the rest NIL. + + Subsequent lines expand upon the meaning and possible values for each +significant stab field. + + Finally, any further information. + +* Menu: + +* N_PC:: Pascal global symbol +* N_NSYMS:: Number of symbols +* N_NOMAP:: No DST map +* N_M2C:: Modula-2 compilation unit +* N_BROWS:: Path to .cb file for Sun source code browser +* N_DEFD:: GNU Modula2 definition module dependency +* N_EHDECL:: GNU C++ exception variable +* N_MOD2:: Modula2 information "for imc" +* N_CATCH:: GNU C++ "catch" clause +* N_SSYM:: Structure or union element +* N_SCOPE:: Modula2 scope information (Sun only) +* Gould:: non-base register symbols used on Gould systems +* N_LENG:: Length of preceding entry + + +File: stabs.info, Node: N_PC, Next: N_NSYMS, Up: Expanded Reference + +D.1 N_PC +======== + + -- '.stabs': N_PC + Global symbol (for Pascal). + + "name" -> "symbol_name" <> + value -> supposedly the line number (stab.def is skeptical) + + 'stabdump.c' says: + + global pascal symbol: name,,0,subtype,line + << subtype? >> + + +File: stabs.info, Node: N_NSYMS, Next: N_NOMAP, Prev: N_PC, Up: Expanded Reference + +D.2 N_NSYMS +=========== + + -- '.stabn': N_NSYMS + Number of symbols (according to Ultrix V4.0). + + 0, files,,funcs,lines (stab.def) + + +File: stabs.info, Node: N_NOMAP, Next: N_M2C, Prev: N_NSYMS, Up: Expanded Reference + +D.3 N_NOMAP +=========== + + -- '.stabs': N_NOMAP + No DST map for symbol (according to Ultrix V4.0). I think this + means a variable has been optimized out. + + name, ,0,type,ignored (stab.def) + + +File: stabs.info, Node: N_M2C, Next: N_BROWS, Prev: N_NOMAP, Up: Expanded Reference + +D.4 N_M2C +========= + + -- '.stabs': N_M2C + Modula-2 compilation unit. + + "string" -> "unit_name,unit_time_stamp[,code_time_stamp]" + desc -> unit_number + value -> 0 (main unit) + 1 (any other unit) + + See 'Dbx and Dbxtool Interfaces', 2nd edition, by Sun, 1988, for + more information. + + +File: stabs.info, Node: N_BROWS, Next: N_DEFD, Prev: N_M2C, Up: Expanded Reference + +D.5 N_BROWS +=========== + + -- '.stabs': N_BROWS + Sun source code browser, path to '.cb' file + + <> "path to associated '.cb' file" + + Note: N_BROWS has the same value as N_BSLINE. + + +File: stabs.info, Node: N_DEFD, Next: N_EHDECL, Prev: N_BROWS, Up: Expanded Reference + +D.6 N_DEFD +========== + + -- '.stabn': N_DEFD + GNU Modula2 definition module dependency. + + GNU Modula-2 definition module dependency. The value is the + modification time of the definition file. The other field is + non-zero if it is imported with the GNU M2 keyword '%INITIALIZE'. + Perhaps 'N_M2C' can be used if there are enough empty fields? + + +File: stabs.info, Node: N_EHDECL, Next: N_MOD2, Prev: N_DEFD, Up: Expanded Reference + +D.7 N_EHDECL +============ + + -- '.stabs': N_EHDECL + GNU C++ exception variable <>. + + "STRING is variable name" + + Note: conflicts with 'N_MOD2'. + + +File: stabs.info, Node: N_MOD2, Next: N_CATCH, Prev: N_EHDECL, Up: Expanded Reference + +D.8 N_MOD2 +========== + + -- '.stab?': N_MOD2 + Modula2 info "for imc" (according to Ultrix V4.0) + + Note: conflicts with 'N_EHDECL' <> + + +File: stabs.info, Node: N_CATCH, Next: N_SSYM, Prev: N_MOD2, Up: Expanded Reference + +D.9 N_CATCH +=========== + + -- '.stabn': N_CATCH + GNU C++ 'catch' clause + + GNU C++ 'catch' clause. The value is its address. The desc field + is nonzero if this entry is immediately followed by a 'CAUGHT' stab + saying what exception was caught. Multiple 'CAUGHT' stabs means + that multiple exceptions can be caught here. If desc is 0, it + means all exceptions are caught here. + + +File: stabs.info, Node: N_SSYM, Next: N_SCOPE, Prev: N_CATCH, Up: Expanded Reference + +D.10 N_SSYM +=========== + + -- '.stabn': N_SSYM + Structure or union element. + + The value is the offset in the structure. + + <> + + +File: stabs.info, Node: N_SCOPE, Next: Gould, Prev: N_SSYM, Up: Expanded Reference + +D.11 N_SCOPE +============ + + -- '.stab?': N_SCOPE + Modula2 scope information (Sun linker) <> + + +File: stabs.info, Node: Gould, Next: N_LENG, Prev: N_SCOPE, Up: Expanded Reference + +D.12 Non-base registers on Gould systems +======================================== + + -- '.stab?': N_NBTEXT + -- '.stab?': N_NBDATA + -- '.stab?': N_NBBSS + -- '.stab?': N_NBSTS + -- '.stab?': N_NBLCS + These are used on Gould systems for non-base registers syms. + + However, the following values are not the values used by Gould; + they are the values which GNU has been documenting for these values + for a long time, without actually checking what Gould uses. I + include these values only because perhaps some someone actually did + something with the GNU information (I hope not, why GNU knowingly + assigned wrong values to these in the header file is a complete + mystery to me). + + 240 0xf0 N_NBTEXT ?? + 242 0xf2 N_NBDATA ?? + 244 0xf4 N_NBBSS ?? + 246 0xf6 N_NBSTS ?? + 248 0xf8 N_NBLCS ?? + + +File: stabs.info, Node: N_LENG, Prev: Gould, Up: Expanded Reference + +D.13 N_LENG +=========== + + -- '.stabn': N_LENG + Second symbol entry containing a length-value for the preceding + entry. The value is the length. + + +File: stabs.info, Node: Questions, Next: Stab Sections, Prev: Expanded Reference, Up: Top + +Appendix E Questions and Anomalies +********************************** + + * For GNU C stabs defining local and global variables ('N_LSYM' and + 'N_GSYM'), the desc field is supposed to contain the source line + number on which the variable is defined. In reality the desc field + is always 0. (This behavior is defined in 'dbxout.c' and putting a + line number in desc is controlled by '#ifdef WINNING_GDB', which + defaults to false). GDB supposedly uses this information if you + say 'list VAR'. In reality, VAR can be a variable defined in the + program and GDB says 'function VAR not defined'. + + * In GNU C stabs, there seems to be no way to differentiate tag + types: structures, unions, and enums (symbol descriptor 'T') and + typedefs (symbol descriptor 't') defined at file scope from types + defined locally to a procedure or other more local scope. They all + use the 'N_LSYM' stab type. Types defined at procedure scope are + emitted after the 'N_RBRAC' of the preceding function and before + the code of the procedure in which they are defined. This is + exactly the same as types defined in the source file between the + two procedure bodies. GDB over-compensates by placing all types in + block #1, the block for symbols of file scope. This is true for + default, '-ansi' and '-traditional' compiler options. (Bugs + gcc/1063, gdb/1066.) + + * What ends the procedure scope? Is it the proc block's 'N_RBRAC' or + the next 'N_FUN'? (I believe its the first.) + + +File: stabs.info, Node: Stab Sections, Next: GNU Free Documentation License, Prev: Questions, Up: Top + +Appendix F Using Stabs in Their Own Sections +******************************************** + +Many object file formats allow tools to create object files with custom +sections containing any arbitrary data. For any such object file +format, stabs can be embedded in special sections. This is how stabs +are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs +are used with COFF. + +* Menu: + +* Stab Section Basics:: How to embed stabs in sections +* ELF Linker Relocation:: Sun ELF hacks + + +File: stabs.info, Node: Stab Section Basics, Next: ELF Linker Relocation, Up: Stab Sections + +F.1 How to Embed Stabs in Sections +================================== + +The assembler creates two custom sections, a section named '.stab' which +contains an array of fixed length structures, one struct per stab, and a +section named '.stabstr' containing all the variable length strings that +are referenced by stabs in the '.stab' section. The byte order of the +stabs binary data depends on the object file format. For ELF, it +matches the byte order of the ELF file itself, as determined from the +'EI_DATA' field in the 'e_ident' member of the ELF header. For SOM, it +is always big-endian (is this true??? FIXME). For COFF, it matches the +byte order of the COFF headers. The meaning of the fields is the same +as for a.out (*note Symbol Table Format::), except that the 'n_strx' +field is relative to the strings for the current compilation unit (which +can be found using the synthetic N_UNDF stab described below), rather +than the entire string table. + + The first stab in the '.stab' section for each compilation unit is +synthetic, generated entirely by the assembler, with no corresponding +'.stab' directive as input to the assembler. This stab contains the +following fields: + +'n_strx' + Offset in the '.stabstr' section to the source filename. + +'n_type' + 'N_UNDF'. + +'n_other' + Unused field, always zero. This may eventually be used to hold + overflows from the count in the 'n_desc' field. + +'n_desc' + Count of upcoming symbols, i.e., the number of remaining stabs for + this source file. + +'n_value' + Size of the string table fragment associated with this source file, + in bytes. + + The '.stabstr' section always starts with a null byte (so that string +offsets of zero reference a null string), followed by random length +strings, each of which is null byte terminated. + + The ELF section header for the '.stab' section has its 'sh_link' +member set to the section number of the '.stabstr' section, and the +'.stabstr' section has its ELF section header 'sh_type' member set to +'SHT_STRTAB' to mark it as a string table. SOM and COFF have no way of +linking the sections together or marking them as string tables. + + For COFF, the '.stab' and '.stabstr' sections may be simply +concatenated by the linker. GDB then uses the 'n_desc' fields to figure +out the extent of the original sections. Similarly, the 'n_value' +fields of the header symbols are added together in order to get the +actual position of the strings in a desired '.stabstr' section. +Although this design obviates any need for the linker to relocate or +otherwise manipulate '.stab' and '.stabstr' sections, it also requires +some care to ensure that the offsets are calculated correctly. For +instance, if the linker were to pad in between the '.stabstr' sections +before concatenating, then the offsets to strings in the middle of the +executable's '.stabstr' section would be wrong. + + The GNU linker is able to optimize stabs information by merging +duplicate strings and removing duplicate header file information (*note +Include Files::). When some versions of the GNU linker optimize stabs +in sections, they remove the leading 'N_UNDF' symbol and arranges for +all the 'n_strx' fields to be relative to the start of the '.stabstr' +section. + + +File: stabs.info, Node: ELF Linker Relocation, Prev: Stab Section Basics, Up: Stab Sections + +F.2 Having the Linker Relocate Stabs in ELF +=========================================== + +This section describes some Sun hacks for Stabs in ELF; it does not +apply to COFF or SOM. + + To keep linking fast, you don't want the linker to have to relocate +very many stabs. Making sure this is done for 'N_SLINE', 'N_RBRAC', and +'N_LBRAC' stabs is the most important thing (see the descriptions of +those stabs for more information). But Sun's stabs in ELF has taken +this further, to make all addresses in the 'n_value' field (functions +and static variables) relative to the source file. For the 'N_SO' +symbol itself, Sun simply omits the address. To find the address of +each section corresponding to a given source file, the compiler puts out +symbols giving the address of each section for a given source file. +Since these are ELF (not stab) symbols, the linker relocates them +correctly without having to touch the stabs section. They are named +'Bbss.bss' for the bss section, 'Ddata.data' for the data section, and +'Drodata.rodata' for the rodata section. For the text section, there is +no such symbol (but there should be, see below). For an example of how +these symbols work, *Note Stab Section Transformations::. GCC does not +provide these symbols; it instead relies on the stabs getting relocated. +Thus addresses which would normally be relative to 'Bbss.bss', etc., are +already relocated. The Sun linker provided with Solaris 2.2 and earlier +relocates stabs using normal ELF relocation information, as it would do +for any section. Sun has been threatening to kludge their linker to not +do this (to speed up linking), even though the correct way to avoid +having the linker do these relocations is to have the compiler no longer +output relocatable values. Last I heard they had been talked out of the +linker kludge. See Sun point patch 101052-01 and Sun bug 1142109. With +the Sun compiler this affects 'S' symbol descriptor stabs (*note +Statics::) and functions (*note Procedures::). In the latter case, to +adopt the clean solution (making the value of the stab relative to the +start of the compilation unit), it would be necessary to invent a +'Ttext.text' symbol, analogous to the 'Bbss.bss', etc., symbols. I +recommend this rather than using a zero value and getting the address +from the ELF symbols. + + Finding the correct 'Bbss.bss', etc., symbol is difficult, because +the linker simply concatenates the '.stab' sections from each '.o' file +without including any information about which part of a '.stab' section +comes from which '.o' file. The way GDB does this is to look for an ELF +'STT_FILE' symbol which has the same name as the last component of the +file name from the 'N_SO' symbol in the stabs (for example, if the file +name is '../../gdb/main.c', it looks for an ELF 'STT_FILE' symbol named +'main.c'). This loses if different files have the same name (they could +be in different directories, a library could have been copied from one +system to another, etc.). It would be much cleaner to have the +'Bbss.bss' symbols in the stabs themselves. Having the linker relocate +them there is no more work than having the linker relocate ELF symbols, +and it solves the problem of having to associate the ELF and stab +symbols. However, no one has yet designed or implemented such a scheme. + + +File: stabs.info, Node: GNU Free Documentation License, Next: Symbol Types Index, Prev: Stab Sections, Up: Top + +Appendix G GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: stabs.info, Node: Symbol Types Index, Prev: GNU Free Documentation License, Up: Top + +Symbol Types Index +****************** + +[index] +* Menu: + +* .bb: Block Structure. (line 25) +* .be: Block Structure. (line 25) +* C_BCOMM: Common Blocks. (line 10) +* C_BINCL: Include Files. (line 40) +* C_BLOCK: Block Structure. (line 25) +* C_BSTAT: Statics. (line 31) +* C_DECL, for types: Typedefs. (line 6) +* C_ECOML: Common Blocks. (line 17) +* C_ECOMM: Common Blocks. (line 10) +* C_EINCL: Include Files. (line 40) +* C_ENTRY: Alternate Entry Points. + (line 6) +* C_ESTAT: Statics. (line 31) +* C_FILE: Source Files. (line 53) +* C_FUN: Procedures. (line 17) +* C_GSYM: Global Variables. (line 6) +* C_LSYM: Stack Variables. (line 11) +* C_PSYM: Parameters. (line 12) +* C_RPSYM: Register Parameters. (line 15) +* C_RSYM: Register Variables. (line 6) +* C_STSYM: Statics. (line 31) +* N_BCOMM: Common Blocks. (line 10) +* N_BINCL: Include Files. (line 17) +* N_BROWS: N_BROWS. (line 6) +* N_BROWS <1>: N_BROWS. (line 7) +* N_BSLINE: Line Numbers. (line 12) +* N_CATCH: N_CATCH. (line 6) +* N_CATCH <1>: N_CATCH. (line 7) +* N_DEFD: N_DEFD. (line 6) +* N_DEFD <1>: N_DEFD. (line 7) +* N_DSLINE: Line Numbers. (line 12) +* N_ECOML: Common Blocks. (line 17) +* N_ECOMM: Common Blocks. (line 10) +* N_EHDECL: N_EHDECL. (line 6) +* N_EHDECL <1>: N_EHDECL. (line 7) +* N_EINCL: Include Files. (line 17) +* N_ENTRY: Alternate Entry Points. + (line 6) +* N_EXCL: Include Files. (line 17) +* N_FNAME: Procedures. (line 6) +* N_FUN, for functions: Procedures. (line 6) +* N_FUN, for variables: Statics. (line 12) +* N_GSYM: Global Variables. (line 6) +* N_GSYM, for functions (Sun acc): Procedures. (line 6) +* N_LBRAC: Block Structure. (line 6) +* N_LCSYM: Statics. (line 12) +* N_LENG: N_LENG. (line 6) +* N_LENG <1>: N_LENG. (line 7) +* N_LSYM, for parameter: Local Variable Parameters. + (line 35) +* N_LSYM, for stack variables: Stack Variables. (line 11) +* N_LSYM, for types: Typedefs. (line 6) +* N_M2C: N_M2C. (line 6) +* N_M2C <1>: N_M2C. (line 7) +* N_MAC_DEFINE: Macro define and undefine. + (line 11) +* N_MAC_UNDEF: Macro define and undefine. + (line 14) +* N_MAIN: Main Program. (line 6) +* N_MOD2: N_MOD2. (line 6) +* N_MOD2 <1>: N_MOD2. (line 7) +* N_NBBSS: Gould. (line 8) +* N_NBBSS <1>: Gould. (line 11) +* N_NBDATA: Gould. (line 7) +* N_NBDATA <1>: Gould. (line 11) +* N_NBLCS: Gould. (line 10) +* N_NBLCS <1>: Gould. (line 11) +* N_NBSTS: Gould. (line 9) +* N_NBSTS <1>: Gould. (line 11) +* N_NBTEXT: Gould. (line 6) +* N_NBTEXT <1>: Gould. (line 11) +* N_NOMAP: N_NOMAP. (line 6) +* N_NOMAP <1>: N_NOMAP. (line 7) +* N_NSYMS: N_NSYMS. (line 6) +* N_NSYMS <1>: N_NSYMS. (line 7) +* N_PC: N_PC. (line 6) +* N_PC <1>: N_PC. (line 7) +* N_PSYM: Parameters. (line 12) +* N_RBRAC: Block Structure. (line 6) +* N_ROSYM: Statics. (line 12) +* N_RSYM: Register Variables. (line 6) +* N_RSYM, for parameters: Register Parameters. (line 15) +* N_SCOPE: N_SCOPE. (line 6) +* N_SCOPE <1>: N_SCOPE. (line 7) +* N_SLINE: Line Numbers. (line 6) +* N_SO: Source Files. (line 6) +* N_SOL: Include Files. (line 11) +* N_SSYM: N_SSYM. (line 6) +* N_SSYM <1>: N_SSYM. (line 7) +* N_STSYM: Statics. (line 12) +* N_STSYM, for functions (Sun acc): Procedures. (line 6) + + + +Tag Table: +Node: Top1360 +Node: Overview2407 +Node: Flow3821 +Node: Stabs Format5347 +Node: String Field6909 +Node: C Example12338 +Node: Assembly Code12883 +Node: Program Structure14854 +Node: Main Program15580 +Node: Source Files16141 +Node: Include Files18583 +Node: Line Numbers21248 +Node: Procedures22782 +Node: Nested Procedures28673 +Node: Block Structure29849 +Node: Alternate Entry Points31253 +Node: Constants31986 +Node: Variables35097 +Node: Stack Variables35785 +Node: Global Variables37486 +Node: Register Variables38641 +Node: Common Blocks39463 +Node: Statics40716 +Node: Based Variables43295 +Node: Parameters44681 +Node: Register Parameters46292 +Node: Local Variable Parameters48552 +Node: Reference Parameters51467 +Node: Conformant Arrays52087 +Node: Types52805 +Node: Builtin Types53752 +Node: Traditional Builtin Types54898 +Node: Traditional Integer Types55299 +Node: Traditional Other Types57607 +Node: Builtin Type Descriptors58521 +Node: Negative Type Numbers62021 +Node: Miscellaneous Types68376 +Node: Cross-References70262 +Node: Subranges71937 +Node: Arrays73176 +Node: Strings76401 +Node: Enumerations77463 +Node: Structures79847 +Node: Typedefs82555 +Node: Unions83877 +Node: Function Types85458 +Node: Macro define and undefine87039 +Node: Symbol Tables88612 +Node: Symbol Table Format89064 +Node: Transformations On Symbol Tables90511 +Node: Transformations On Static Variables91865 +Node: Transformations On Global Variables92601 +Node: Stab Section Transformations93845 +Node: Cplusplus95228 +Node: Class Names95811 +Node: Nested Symbols96556 +Node: Basic Cplusplus Types97402 +Node: Simple Classes98962 +Node: Class Instance103255 +Node: Methods103972 +Node: Method Type Descriptor106191 +Node: Member Type Descriptor107391 +Node: Protections108183 +Node: Method Modifiers111273 +Node: Virtual Methods112901 +Node: Inheritance116701 +Node: Virtual Base Classes120397 +Node: Static Members122642 +Node: Stab Types123112 +Node: Non-Stab Symbol Types123736 +Node: Stab Symbol Types125119 +Node: Symbol Descriptors128902 +Node: Type Descriptors131681 +Node: Expanded Reference134893 +Node: N_PC136311 +Node: N_NSYMS136679 +Node: N_NOMAP136920 +Node: N_M2C137226 +Node: N_BROWS137659 +Node: N_DEFD137942 +Node: N_EHDECL138399 +Node: N_MOD2138650 +Node: N_CATCH138887 +Node: N_SSYM139381 +Node: N_SCOPE139666 +Node: Gould139856 +Node: N_LENG140849 +Node: Questions141077 +Node: Stab Sections142718 +Node: Stab Section Basics143328 +Node: ELF Linker Relocation146670 +Node: GNU Free Documentation License150079 +Node: Symbol Types Index175238 + +End Tag Table diff --git a/util/X86MAC64/share/info/standards.info b/util/X86MAC64/share/info/standards.info new file mode 100644 index 0000000000..4b436f02e7 --- /dev/null +++ b/util/X86MAC64/share/info/standards.info @@ -0,0 +1,5719 @@ +This is standards.info, produced by makeinfo version 5.1 from +standards.texi. + +The GNU coding standards, last updated April 12, 2010. + + Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, +2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". +INFO-DIR-SECTION GNU organization +START-INFO-DIR-ENTRY +* Standards: (standards). GNU coding standards. +END-INFO-DIR-ENTRY + + +File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir) + +Version +******* + +The GNU coding standards, last updated April 12, 2010. + + Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, +2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". + +* Menu: + +* Preface:: About the GNU Coding Standards. +* Legal Issues:: Keeping free software free. +* Design Advice:: General program design. +* Program Behavior:: Program behavior for all programs +* Writing C:: Making the best use of C. +* Documentation:: Documenting programs. +* Managing Releases:: The release process. +* References:: Mentioning non-free software or documentation. +* GNU Free Documentation License:: Copying and sharing this manual. +* Index:: + + +File: standards.info, Node: Preface, Next: Legal Issues, Up: Top + +1 About the GNU Coding Standards +******************************** + +The GNU Coding Standards were written by Richard Stallman and other GNU +Project volunteers. Their purpose is to make the GNU system clean, +consistent, and easy to install. This document can also be read as a +guide to writing portable, robust and reliable programs. It focuses on +programs written in C, but many of the rules and principles are useful +even if you write in another programming language. The rules often +state reasons for writing in a certain way. + + If you did not obtain this file directly from the GNU project and +recently, please check for a newer version. You can get the GNU Coding +Standards from the GNU web server in many different formats, including +the Texinfo source, PDF, HTML, DVI, plain text, and more, at: +. + + If you are maintaining an official GNU package, in addition to this +document, please read and follow the GNU maintainer information (*note +Contents: (maintain)Top.). + + If you want to receive diffs for every change to these GNU documents, +join the mailing list 'gnustandards-commit@gnu.org', via the web +interface at +. Archives +are also available there. + + Please send corrections or suggestions for this document to +. If you make a suggestion, please include a +suggested new wording for it, to help us consider the suggestion +efficiently. We prefer a context diff to the Texinfo source, but if +that's difficult for you, you can make a context diff for some other +version of this document, or propose it in any way that makes it clear. +The source repository for this document can be found at +. + + These standards cover the minimum of what is important when writing a +GNU package. Likely, the need for additional standards will come up. +Sometimes, you might suggest that such standards be added to this +document. If you think your standards would be generally useful, please +do suggest them. + + You should also set standards for your package on many questions not +addressed or not firmly specified here. The most important point is to +be self-consistent--try to stick to the conventions you pick, and try to +document them as much as possible. That way, your program will be more +maintainable by others. + + The GNU Hello program serves as an example of how to follow the GNU +coding standards for a trivial program. +. + + This release of the GNU Coding Standards was last updated April 12, +2010. + + +File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top + +2 Keeping Free Software Free +**************************** + +This chapter discusses how you can make sure that GNU software avoids +legal difficulties, and other related issues. + +* Menu: + +* Reading Non-Free Code:: Referring to proprietary programs. +* Contributions:: Accepting contributions. +* Trademarks:: How we deal with trademark issues. + + +File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues + +2.1 Referring to Proprietary Programs +===================================== + +Don't in any circumstances refer to Unix source code for or during your +work on GNU! (Or to any other proprietary programs.) + + If you have a vague recollection of the internals of a Unix program, +this does not absolutely mean you can't write an imitation of it, but do +try to organize the imitation internally along different lines, because +this is likely to make the details of the Unix version irrelevant and +dissimilar to your results. + + For example, Unix utilities were generally optimized to minimize +memory use; if you go for speed instead, your program will be very +different. You could keep the entire input file in memory and scan it +there instead of using stdio. Use a smarter algorithm discovered more +recently than the Unix program. Eliminate use of temporary files. Do +it in one pass instead of two (we did this in the assembler). + + Or, on the contrary, emphasize simplicity instead of speed. For some +applications, the speed of today's computers makes simpler algorithms +adequate. + + Or go for generality. For example, Unix programs often have static +tables or fixed-size strings, which make for arbitrary limits; use +dynamic allocation instead. Make sure your program handles NULs and +other funny characters in the input files. Add a programming language +for extensibility and write part of the program in that language. + + Or turn some parts of the program into independently usable +libraries. Or use a simple garbage collector instead of tracking +precisely when to free memory, or use a new GNU facility such as +obstacks. + + +File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues + +2.2 Accepting Contributions +=========================== + +If the program you are working on is copyrighted by the Free Software +Foundation, then when someone else sends you a piece of code to add to +the program, we need legal papers to use it--just as we asked you to +sign papers initially. _Each_ person who makes a nontrivial +contribution to a program must sign some sort of legal papers in order +for us to have clear title to the program; the main author alone is not +enough. + + So, before adding in any contributions from other people, please tell +us, so we can arrange to get the papers. Then wait until we tell you +that we have received the signed papers, before you actually use the +contribution. + + This applies both before you release the program and afterward. If +you receive diffs to fix a bug, and they make significant changes, we +need legal papers for that change. + + This also applies to comments and documentation files. For copyright +law, comments and code are just text. Copyright applies to all kinds of +text, so we need legal papers for all kinds. + + We know it is frustrating to ask for legal papers; it's frustrating +for us as well. But if you don't wait, you are going out on a limb--for +example, what if the contributor's employer won't sign a disclaimer? +You might have to take that code out again! + + You don't need papers for changes of a few lines here or there, since +they are not significant for copyright purposes. Also, you don't need +papers if all you get from the suggestion is some ideas, not actual code +which you use. For example, if someone sent you one implementation, but +you write a different implementation of the same idea, you don't need to +get papers. + + The very worst thing is if you forget to tell us about the other +contributor. We could be very embarrassed in court some day as a +result. + + We have more detailed advice for maintainers of programs; if you have +reached the stage of actually maintaining a program for GNU (whether +released or not), please ask us for a copy. It is also available online +for your perusal: . + + +File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues + +2.3 Trademarks +============== + +Please do not include any trademark acknowledgements in GNU software +packages or documentation. + + Trademark acknowledgements are the statements that such-and-such is a +trademark of so-and-so. The GNU Project has no objection to the basic +idea of trademarks, but these acknowledgements feel like kowtowing, and +there is no legal requirement for them, so we don't use them. + + What is legally required, as regards other people's trademarks, is to +avoid using them in ways which a reader might reasonably understand as +naming or labeling our own programs or activities. For example, since +"Objective C" is (or at least was) a trademark, we made sure to say that +we provide a "compiler for the Objective C language" rather than an +"Objective C compiler". The latter would have been meant as a shorter +way of saying the former, but it does not explicitly state the +relationship, so it could be misinterpreted as using "Objective C" as a +label for the compiler rather than for the language. + + Please don't use "win" as an abbreviation for Microsoft Windows in +GNU software or documentation. In hacker terminology, calling something +a "win" is a form of praise. If you wish to praise Microsoft Windows +when speaking on your own, by all means do so, but not in GNU software. +Usually we write the name "Windows" in full, but when brevity is very +important (as in file names and sometimes symbol names), we abbreviate +it to "w". For instance, the files and functions in Emacs that deal +with Windows start with 'w32'. + + +File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top + +3 General Program Design +************************ + +This chapter discusses some of the issues you should take into account +when designing your program. + +* Menu: + +* Source Language:: Which languages to use. +* Compatibility:: Compatibility with other implementations. +* Using Extensions:: Using non-standard features. +* Standard C:: Using standard C features. +* Conditional Compilation:: Compiling code only if a conditional is true. + + +File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice + +3.1 Which Languages to Use +========================== + +When you want to use a language that gets compiled and runs at high +speed, the best language to use is C. Using another language is like +using a non-standard feature: it will cause trouble for users. Even if +GCC supports the other language, users may find it inconvenient to have +to install the compiler for that other language in order to build your +program. For example, if you write your program in C++, people will +have to install the GNU C++ compiler in order to compile your program. + + C has one other advantage over C++ and other compiled languages: more +people know C, so more people will find it easy to read and modify the +program if it is written in C. + + So in general it is much better to use C, rather than the comparable +alternatives. + + But there are two exceptions to that conclusion: + + * It is no problem to use another language to write a tool + specifically intended for use with that language. That is because + the only people who want to build the tool will be those who have + installed the other language anyway. + + * If an application is of interest only to a narrow part of the + community, then the question of which language it is written in has + less effect on other people, so you may as well please yourself. + + Many programs are designed to be extensible: they include an +interpreter for a language that is higher level than C. Often much of +the program is written in that language, too. The Emacs editor +pioneered this technique. + + The standard extensibility interpreter for GNU software is Guile +(), which implements the language +Scheme (an especially clean and simple dialect of Lisp). Guile also +includes bindings for GTK+/GNOME, making it practical to write modern +GUI functionality within Guile. We don't reject programs written in +other "scripting languages" such as Perl and Python, but using Guile is +very important for the overall consistency of the GNU system. + + +File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice + +3.2 Compatibility with Other Implementations +============================================ + +With occasional exceptions, utility programs and libraries for GNU +should be upward compatible with those in Berkeley Unix, and upward +compatible with Standard C if Standard C specifies their behavior, and +upward compatible with POSIX if POSIX specifies their behavior. + + When these standards conflict, it is useful to offer compatibility +modes for each of them. + + Standard C and POSIX prohibit many kinds of extensions. Feel free to +make the extensions anyway, and include a '--ansi', '--posix', or +'--compatible' option to turn them off. However, if the extension has a +significant chance of breaking any real programs or scripts, then it is +not really upward compatible. So you should try to redesign its +interface to make it upward compatible. + + Many GNU programs suppress extensions that conflict with POSIX if the +environment variable 'POSIXLY_CORRECT' is defined (even if it is defined +with a null value). Please make your program recognize this variable if +appropriate. + + When a feature is used only by users (not by programs or command +files), and it is done poorly in Unix, feel free to replace it +completely with something totally different and better. (For example, +'vi' is replaced with Emacs.) But it is nice to offer a compatible +feature as well. (There is a free 'vi' clone, so we offer it.) + + Additional useful features are welcome regardless of whether there is +any precedent for them. + + +File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice + +3.3 Using Non-standard Features +=============================== + +Many GNU facilities that already exist support a number of convenient +extensions over the comparable Unix facilities. Whether to use these +extensions in implementing your program is a difficult question. + + On the one hand, using the extensions can make a cleaner program. On +the other hand, people will not be able to build the program unless the +other GNU tools are available. This might cause the program to work on +fewer kinds of machines. + + With some extensions, it might be easy to provide both alternatives. +For example, you can define functions with a "keyword" 'INLINE' and +define that as a macro to expand into either 'inline' or nothing, +depending on the compiler. + + In general, perhaps it is best not to use the extensions if you can +straightforwardly do without them, but to use the extensions if they are +a big improvement. + + An exception to this rule are the large, established programs (such +as Emacs) which run on a great variety of systems. Using GNU extensions +in such programs would make many users unhappy, so we don't do that. + + Another exception is for programs that are used as part of +compilation: anything that must be compiled with other compilers in +order to bootstrap the GNU compilation facilities. If these require the +GNU compiler, then no one can compile them without having them installed +already. That would be extremely troublesome in certain cases. + + +File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, Up: Design Advice + +3.4 Standard C and Pre-Standard C +================================= + +1989 Standard C is widespread enough now that it is ok to use its +features in new programs. There is one exception: do not ever use the +"trigraph" feature of Standard C. + + 1999 Standard C is not widespread yet, so please do not require its +features in programs. It is ok to use its features if they are present. + + However, it is easy to support pre-standard compilers in most +programs, so if you know how to do that, feel free. If a program you +are maintaining has such support, you should try to keep it working. + + To support pre-standard C, instead of writing function definitions in +standard prototype form, + + int + foo (int x, int y) + ... + +write the definition in pre-standard style like this, + + int + foo (x, y) + int x, y; + ... + +and use a separate declaration to specify the argument prototype: + + int foo (int, int); + + You need such a declaration anyway, in a header file, to get the +benefit of prototypes in all the files where the function is called. +And once you have the declaration, you normally lose nothing by writing +the function definition in the pre-standard style. + + This technique does not work for integer types narrower than 'int'. +If you think of an argument as being of a type narrower than 'int', +declare it as 'int' instead. + + There are a few special cases where this technique is hard to use. +For example, if a function argument needs to hold the system type +'dev_t', you run into trouble, because 'dev_t' is shorter than 'int' on +some machines; but you cannot use 'int' instead, because 'dev_t' is +wider than 'int' on some machines. There is no type you can safely use +on all machines in a non-standard definition. The only way to support +non-standard C and pass such an argument is to check the width of +'dev_t' using Autoconf and choose the argument type accordingly. This +may not be worth the trouble. + + In order to support pre-standard compilers that do not recognize +prototypes, you may want to use a preprocessor macro like this: + + /* Declare the prototype for a general external function. */ + #if defined (__STDC__) || defined (WINDOWSNT) + #define P_(proto) proto + #else + #define P_(proto) () + #endif + + +File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice + +3.5 Conditional Compilation +=========================== + +When supporting configuration options already known when building your +program we prefer using 'if (... )' over conditional compilation, as in +the former case the compiler is able to perform more extensive checking +of all possible code paths. + + For example, please write + + if (HAS_FOO) + ... + else + ... + +instead of: + + #ifdef HAS_FOO + ... + #else + ... + #endif + + A modern compiler such as GCC will generate exactly the same code in +both cases, and we have been using similar techniques with good success +in several projects. Of course, the former method assumes that +'HAS_FOO' is defined as either 0 or 1. + + While this is not a silver bullet solving all portability problems, +and is not always appropriate, following this policy would have saved +GCC developers many hours, or even days, per year. + + In the case of function-like macros like 'REVERSIBLE_CC_MODE' in GCC +which cannot be simply used in 'if (...)' statements, there is an easy +workaround. Simply introduce another macro 'HAS_REVERSIBLE_CC_MODE' as +in the following example: + + #ifdef REVERSIBLE_CC_MODE + #define HAS_REVERSIBLE_CC_MODE 1 + #else + #define HAS_REVERSIBLE_CC_MODE 0 + #endif + + +File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top + +4 Program Behavior for All Programs +*********************************** + +This chapter describes conventions for writing robust software. It also +describes general standards for error messages, the command line +interface, and how libraries should behave. + +* Menu: + +* Non-GNU Standards:: We consider standards such as POSIX; + we don't "obey" them. +* Semantics:: Writing robust programs. +* Libraries:: Library behavior. +* Errors:: Formatting error messages. +* User Interfaces:: Standards about interfaces generally. +* Graphical Interfaces:: Standards for graphical interfaces. +* Command-Line Interfaces:: Standards for command line interfaces. +* Option Table:: Table of long options. +* OID Allocations:: Table of OID slots for GNU. +* Memory Usage:: When and how to care about memory needs. +* File Usage:: Which files to use, and where. + + +File: standards.info, Node: Non-GNU Standards, Next: Semantics, Up: Program Behavior + +4.1 Non-GNU Standards +===================== + +The GNU Project regards standards published by other organizations as +suggestions, not orders. We consider those standards, but we do not +"obey" them. In developing a GNU program, you should implement an +outside standard's specifications when that makes the GNU system better +overall in an objective sense. When it doesn't, you shouldn't. + + In most cases, following published standards is convenient for +users--it means that their programs or scripts will work more portably. +For instance, GCC implements nearly all the features of Standard C as +specified by that standard. C program developers would be unhappy if it +did not. And GNU utilities mostly follow specifications of POSIX.2; +shell script writers and users would be unhappy if our programs were +incompatible. + + But we do not follow either of these specifications rigidly, and +there are specific points on which we decided not to follow them, so as +to make the GNU system better for users. + + For instance, Standard C says that nearly all extensions to C are +prohibited. How silly! GCC implements many extensions, some of which +were later adopted as part of the standard. If you want these +constructs to give an error message as "required" by the standard, you +must specify '--pedantic', which was implemented only so that we can say +"GCC is a 100% implementation of the standard," not because there is any +reason to actually use it. + + POSIX.2 specifies that 'df' and 'du' must output sizes by default in +units of 512 bytes. What users want is units of 1k, so that is what we +do by default. If you want the ridiculous behavior "required" by POSIX, +you must set the environment variable 'POSIXLY_CORRECT' (which was +originally going to be named 'POSIX_ME_HARDER'). + + GNU utilities also depart from the letter of the POSIX.2 +specification when they support long-named command-line options, and +intermixing options with ordinary arguments. This minor incompatibility +with POSIX is never a problem in practice, and it is very useful. + + In particular, don't reject a new feature, or remove an old one, +merely because a standard says it is "forbidden" or "deprecated." + + +File: standards.info, Node: Semantics, Next: Libraries, Prev: Non-GNU Standards, Up: Program Behavior + +4.2 Writing Robust Programs +=========================== + +Avoid arbitrary limits on the length or number of _any_ data structure, +including file names, lines, files, and symbols, by allocating all data +structures dynamically. In most Unix utilities, "long lines are +silently truncated". This is not acceptable in a GNU utility. + + Utilities reading files should not drop NUL characters, or any other +nonprinting characters _including those with codes above 0177_. The +only sensible exceptions would be utilities specifically intended for +interface to certain types of terminals or printers that can't handle +those characters. Whenever possible, try to make programs work properly +with sequences of bytes that represent multibyte characters, using +encodings such as UTF-8 and others. + + Check every system call for an error return, unless you know you wish +to ignore errors. Include the system error text (from 'perror' or +equivalent) in _every_ error message resulting from a failing system +call, as well as the name of the file if any and the name of the +utility. Just "cannot open foo.c" or "stat failed" is not sufficient. + + Check every call to 'malloc' or 'realloc' to see if it returned zero. +Check 'realloc' even if you are making the block smaller; in a system +that rounds block sizes to a power of 2, 'realloc' may get a different +block if you ask for less space. + + In Unix, 'realloc' can destroy the storage block if it returns zero. +GNU 'realloc' does not have this bug: if it fails, the original block is +unchanged. Feel free to assume the bug is fixed. If you wish to run +your program on Unix, and wish to avoid lossage in this case, you can +use the GNU 'malloc'. + + You must expect 'free' to alter the contents of the block that was +freed. Anything you want to fetch from the block, you must fetch before +calling 'free'. + + If 'malloc' fails in a noninteractive program, make that a fatal +error. In an interactive program (one that reads commands from the +user), it is better to abort the command and return to the command +reader loop. This allows the user to kill other processes to free up +virtual memory, and then try the command again. + + Use 'getopt_long' to decode arguments, unless the argument syntax +makes this unreasonable. + + When static storage is to be written in during program execution, use +explicit C code to initialize it. Reserve C initialized declarations +for data that will not be changed. + + Try to avoid low-level interfaces to obscure Unix data structures +(such as file directories, utmp, or the layout of kernel memory), since +these are less likely to work compatibly. If you need to find all the +files in a directory, use 'readdir' or some other high-level interface. +These are supported compatibly by GNU. + + The preferred signal handling facilities are the BSD variant of +'signal', and the POSIX 'sigaction' function; the alternative USG +'signal' interface is an inferior design. + + Nowadays, using the POSIX signal functions may be the easiest way to +make a program portable. If you use 'signal', then on GNU/Linux systems +running GNU libc version 1, you should include 'bsd/signal.h' instead of +'signal.h', so as to get BSD behavior. It is up to you whether to +support systems where 'signal' has only the USG behavior, or give up on +them. + + In error checks that detect "impossible" conditions, just abort. +There is usually no point in printing any message. These checks +indicate the existence of bugs. Whoever wants to fix the bugs will have +to read the source code and run a debugger. So explain the problem with +comments in the source. The relevant data will be in variables, which +are easy to examine with the debugger, so there is no point moving them +elsewhere. + + Do not use a count of errors as the exit status for a program. _That +does not work_, because exit status values are limited to 8 bits (0 +through 255). A single run of the program might have 256 errors; if you +try to return 256 as the exit status, the parent process will see 0 as +the status, and it will appear that the program succeeded. + + If you make temporary files, check the 'TMPDIR' environment variable; +if that variable is defined, use the specified directory instead of +'/tmp'. + + In addition, be aware that there is a possible security problem when +creating temporary files in world-writable directories. In C, you can +avoid this problem by creating temporary files in this manner: + + fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600); + +or by using the 'mkstemps' function from libiberty. + + In bash, use 'set -C' to avoid this problem. + + +File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior + +4.3 Library Behavior +==================== + +Try to make library functions reentrant. If they need to do dynamic +storage allocation, at least try to avoid any nonreentrancy aside from +that of 'malloc' itself. + + Here are certain name conventions for libraries, to avoid name +conflicts. + + Choose a name prefix for the library, more than two characters long. +All external function and variable names should start with this prefix. +In addition, there should only be one of these in any given library +member. This usually means putting each one in a separate source file. + + An exception can be made when two external symbols are always used +together, so that no reasonable program could use one without the other; +then they can both go in the same file. + + External symbols that are not documented entry points for the user +should have names beginning with '_'. The '_' should be followed by the +chosen name prefix for the library, to prevent collisions with other +libraries. These can go in the same files with user entry points if you +like. + + Static functions and variables can be used as you like and need not +fit any naming convention. + + +File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior + +4.4 Formatting Error Messages +============================= + +Error messages from compilers should look like this: + + SOURCE-FILE-NAME:LINENO: MESSAGE + +If you want to mention the column number, use one of these formats: + + SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE + SOURCE-FILE-NAME:LINENO.COLUMN: MESSAGE + +Line numbers should start from 1 at the beginning of the file, and +column numbers should start from 1 at the beginning of the line. (Both +of these conventions are chosen for compatibility.) Calculate column +numbers assuming that space and all ASCII printing characters have equal +width, and assuming tab stops every 8 columns. + + The error message can also give both the starting and ending +positions of the erroneous text. There are several formats so that you +can avoid redundant information such as a duplicate line number. Here +are the possible formats: + + SOURCE-FILE-NAME:LINENO-1.COLUMN-1-LINENO-2.COLUMN-2: MESSAGE + SOURCE-FILE-NAME:LINENO-1.COLUMN-1-COLUMN-2: MESSAGE + SOURCE-FILE-NAME:LINENO-1-LINENO-2: MESSAGE + +When an error is spread over several files, you can use this format: + + FILE-1:LINENO-1.COLUMN-1-FILE-2:LINENO-2.COLUMN-2: MESSAGE + + Error messages from other noninteractive programs should look like +this: + + PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE + +when there is an appropriate source file, or like this: + + PROGRAM: MESSAGE + +when there is no relevant source file. + + If you want to mention the column number, use this format: + + PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE + + In an interactive program (one that is reading commands from a +terminal), it is better not to include the program name in an error +message. The place to indicate which program is running is in the +prompt or with the screen layout. (When the same program runs with +input from a source other than a terminal, it is not interactive and +would do best to print error messages using the noninteractive style.) + + The string MESSAGE should not begin with a capital letter when it +follows a program name and/or file name, because that isn't the +beginning of a sentence. (The sentence conceptually starts at the +beginning of the line.) Also, it should not end with a period. + + Error messages from interactive programs, and other messages such as +usage messages, should start with a capital letter. But they should not +end with a period. + + +File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior + +4.5 Standards for Interfaces Generally +====================================== + +Please don't make the behavior of a utility depend on the name used to +invoke it. It is useful sometimes to make a link to a utility with a +different name, and that should not change what it does. + + Instead, use a run time option or a compilation switch or both to +select among the alternate behaviors. + + Likewise, please don't make the behavior of the program depend on the +type of output device it is used with. Device independence is an +important principle of the system's design; do not compromise it merely +to save someone from typing an option now and then. (Variation in error +message syntax when using a terminal is ok, because that is a side issue +that people do not depend on.) + + If you think one behavior is most useful when the output is to a +terminal, and another is most useful when the output is a file or a +pipe, then it is usually best to make the default behavior the one that +is useful with output to a terminal, and have an option for the other +behavior. + + Compatibility requires certain programs to depend on the type of +output device. It would be disastrous if 'ls' or 'sh' did not do so in +the way all users expect. In some of these cases, we supplement the +program with a preferred alternate version that does not depend on the +output device type. For example, we provide a 'dir' program much like +'ls' except that its default output format is always multi-column +format. + + +File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior + +4.6 Standards for Graphical Interfaces +====================================== + +When you write a program that provides a graphical user interface, +please make it work with the X Window System and the GTK+ toolkit unless +the functionality specifically requires some alternative (for example, +"displaying jpeg images while in console mode"). + + In addition, please provide a command-line interface to control the +functionality. (In many cases, the graphical user interface can be a +separate program which invokes the command-line program.) This is so +that the same jobs can be done from scripts. + + Please also consider providing a D-bus interface for use from other +running programs, such as within GNOME. (GNOME used to use CORBA for +this, but that is being phased out.) In addition, consider providing a +library interface (for use from C), and perhaps a keyboard-driven +console interface (for use by users from console mode). Once you are +doing the work to provide the functionality and the graphical interface, +these won't be much extra work. + + +File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior + +4.7 Standards for Command Line Interfaces +========================================= + +It is a good idea to follow the POSIX guidelines for the command-line +options of a program. The easiest way to do this is to use 'getopt' to +parse them. Note that the GNU version of 'getopt' will normally permit +options anywhere among the arguments unless the special argument '--' is +used. This is not what POSIX specifies; it is a GNU extension. + + Please define long-named options that are equivalent to the +single-letter Unix-style options. We hope to make GNU more user +friendly this way. This is easy to do with the GNU function +'getopt_long'. + + One of the advantages of long-named options is that they can be +consistent from program to program. For example, users should be able +to expect the "verbose" option of any GNU program which has one, to be +spelled precisely '--verbose'. To achieve this uniformity, look at the +table of common long-option names when you choose the option names for +your program (*note Option Table::). + + It is usually a good idea for file names given as ordinary arguments +to be input files only; any output files would be specified using +options (preferably '-o' or '--output'). Even if you allow an output +file name as an ordinary argument for compatibility, try to provide an +option as another way to specify it. This will lead to more consistency +among GNU utilities, and fewer idiosyncrasies for users to remember. + + All programs should support two standard options: '--version' and +'--help'. CGI programs should accept these as command-line options, and +also if given as the 'PATH_INFO'; for instance, visiting + in a browser should output the same +information as invoking 'p.cgi --help' from the command line. + +* Menu: + +* --version:: The standard output for -version. +* --help:: The standard output for -help. + + +File: standards.info, Node: --version, Next: --help, Up: Command-Line Interfaces + +4.7.1 '--version' +----------------- + +The standard '--version' option should direct the program to print +information about its name, version, origin and legal status, all on +standard output, and then exit successfully. Other options and +arguments should be ignored once this is seen, and the program should +not perform its normal function. + + The first line is meant to be easy for a program to parse; the +version number proper starts after the last space. In addition, it +contains the canonical name for this program, in this format: + + GNU Emacs 19.30 + +The program's name should be a constant string; _don't_ compute it from +'argv[0]'. The idea is to state the standard or canonical name for the +program, not its file name. There are other ways to find out the +precise file name where a command is found in 'PATH'. + + If the program is a subsidiary part of a larger package, mention the +package name in parentheses, like this: + + emacsserver (GNU Emacs) 19.30 + +If the package has a version number which is different from this +program's version number, you can mention the package version number +just before the close-parenthesis. + + If you _need_ to mention the version numbers of libraries which are +distributed separately from the package which contains this program, you +can do so by printing an additional line of version info for each +library you want to mention. Use the same format for these lines as for +the first line. + + Please do not mention all of the libraries that the program uses +"just for completeness"--that would produce a lot of unhelpful clutter. +Please mention library version numbers only if you find in practice that +they are very important to you in debugging. + + The following line, after the version number line or lines, should be +a copyright notice. If more than one copyright notice is called for, +put each on a separate line. + + Next should follow a line stating the license, preferably using one +of abbrevations below, and a brief statement that the program is free +software, and that users are free to copy and change it. Also mention +that there is no warranty, to the extent permitted by law. See +recommended wording below. + + It is ok to finish the output with a list of the major authors of the +program, as a way of giving credit. + + Here's an example of output that follows these rules: + + GNU hello 2.3 + Copyright (C) 2007 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + + You should adapt this to your program, of course, filling in the +proper year, copyright holder, name of program, and the references to +distribution terms, and changing the rest of the wording as necessary. + + This copyright notice only needs to mention the most recent year in +which changes were made--there's no need to list the years for previous +versions' changes. You don't have to mention the name of the program in +these notices, if that is inconvenient, since it appeared in the first +line. (The rules are different for copyright notices in source files; +*note (maintain)Copyright Notices::.) + + Translations of the above lines must preserve the validity of the +copyright notices (*note Internationalization::). If the translation's +character set supports it, the '(C)' should be replaced with the +copyright symbol, as follows: + + (the official copyright symbol, which is the letter C in a circle); + + Write the word "Copyright" exactly like that, in English. Do not +translate it into another language. International treaties recognize +the English word "Copyright"; translations into other languages do not +have legal significance. + + Finally, here is the table of our suggested license abbreviations. +Any abbreviation can be followed by 'vVERSION[+]', meaning that +particular version, or later versions with the '+', as shown above. + + In the case of exceptions for extra permissions with the GPL, we use +'/' for a separator; the version number can follow the license +abbreviation as usual, as in the examples below. + +GPL + GNU General Public License, . + +LGPL + GNU Lesser General Public License, + . + +GPL/Ada + GNU GPL with the exception for Ada. + +Apache + The Apache Software Foundation license, + . + +Artistic + The Artistic license used for Perl, + . + +Expat + The Expat license, . + +MPL + The Mozilla Public License, . + +OBSD + The original (4-clause) BSD license, incompatible with the GNU GPL + . + +PHP + The license used for PHP, . + +public domain + The non-license that is being in the public domain, + . + +Python + The license for Python, . + +RBSD + The revised (3-clause) BSD, compatible with the GNU GPL, + . + +X11 + The simple non-copyleft license used for most versions of the X + Window System, . + +Zlib + The license for Zlib, . + + More information about these licenses and many more are on the GNU +licensing web pages, . + + +File: standards.info, Node: --help, Prev: --version, Up: Command-Line Interfaces + +4.7.2 '--help' +-------------- + +The standard '--help' option should output brief documentation for how +to invoke the program, on standard output, then exit successfully. +Other options and arguments should be ignored once this is seen, and the +program should not perform its normal function. + + Near the end of the '--help' option's output, please place lines +giving the email address for bug reports, the package's home page +(normally 'http://www.gnu.org/software/PKG', and the general page for +help using GNU programs. The format should be like this: + + Report bugs to: MAILING-ADDRESS + PKG home page: + General help using GNU software: + + It is ok to mention other appropriate mailing lists and web pages. + + +File: standards.info, Node: Option Table, Next: OID Allocations, Prev: Command-Line Interfaces, Up: Program Behavior + +4.8 Table of Long Options +========================= + +Here is a table of long options used by GNU programs. It is surely +incomplete, but we aim to list all the options that a new program might +want to be compatible with. If you use names not already in the table, +please send a list of them, with their meanings, +so we can update the table. + +'after-date' + '-N' in 'tar'. + +'all' + '-a' in 'du', 'ls', 'nm', 'stty', 'uname', and 'unexpand'. + +'all-text' + '-a' in 'diff'. + +'almost-all' + '-A' in 'ls'. + +'append' + '-a' in 'etags', 'tee', 'time'; '-r' in 'tar'. + +'archive' + '-a' in 'cp'. + +'archive-name' + '-n' in 'shar'. + +'arglength' + '-l' in 'm4'. + +'ascii' + '-a' in 'diff'. + +'assign' + '-v' in 'gawk'. + +'assume-new' + '-W' in 'make'. + +'assume-old' + '-o' in 'make'. + +'auto-check' + '-a' in 'recode'. + +'auto-pager' + '-a' in 'wdiff'. + +'auto-reference' + '-A' in 'ptx'. + +'avoid-wraps' + '-n' in 'wdiff'. + +'background' + For server programs, run in the background. + +'backward-search' + '-B' in 'ctags'. + +'basename' + '-f' in 'shar'. + +'batch' + Used in GDB. + +'baud' + Used in GDB. + +'before' + '-b' in 'tac'. + +'binary' + '-b' in 'cpio' and 'diff'. + +'bits-per-code' + '-b' in 'shar'. + +'block-size' + Used in 'cpio' and 'tar'. + +'blocks' + '-b' in 'head' and 'tail'. + +'break-file' + '-b' in 'ptx'. + +'brief' + Used in various programs to make output shorter. + +'bytes' + '-c' in 'head', 'split', and 'tail'. + +'c++' + '-C' in 'etags'. + +'catenate' + '-A' in 'tar'. + +'cd' + Used in various programs to specify the directory to use. + +'changes' + '-c' in 'chgrp' and 'chown'. + +'classify' + '-F' in 'ls'. + +'colons' + '-c' in 'recode'. + +'command' + '-c' in 'su'; '-x' in GDB. + +'compare' + '-d' in 'tar'. + +'compat' + Used in 'gawk'. + +'compress' + '-Z' in 'tar' and 'shar'. + +'concatenate' + '-A' in 'tar'. + +'confirmation' + '-w' in 'tar'. + +'context' + Used in 'diff'. + +'copyleft' + '-W copyleft' in 'gawk'. + +'copyright' + '-C' in 'ptx', 'recode', and 'wdiff'; '-W copyright' in 'gawk'. + +'core' + Used in GDB. + +'count' + '-q' in 'who'. + +'count-links' + '-l' in 'du'. + +'create' + Used in 'tar' and 'cpio'. + +'cut-mark' + '-c' in 'shar'. + +'cxref' + '-x' in 'ctags'. + +'date' + '-d' in 'touch'. + +'debug' + '-d' in 'make' and 'm4'; '-t' in Bison. + +'define' + '-D' in 'm4'. + +'defines' + '-d' in Bison and 'ctags'. + +'delete' + '-D' in 'tar'. + +'dereference' + '-L' in 'chgrp', 'chown', 'cpio', 'du', 'ls', and 'tar'. + +'dereference-args' + '-D' in 'du'. + +'device' + Specify an I/O device (special file name). + +'diacritics' + '-d' in 'recode'. + +'dictionary-order' + '-d' in 'look'. + +'diff' + '-d' in 'tar'. + +'digits' + '-n' in 'csplit'. + +'directory' + Specify the directory to use, in various programs. In 'ls', it + means to show directories themselves rather than their contents. + In 'rm' and 'ln', it means to not treat links to directories + specially. + +'discard-all' + '-x' in 'strip'. + +'discard-locals' + '-X' in 'strip'. + +'dry-run' + '-n' in 'make'. + +'ed' + '-e' in 'diff'. + +'elide-empty-files' + '-z' in 'csplit'. + +'end-delete' + '-x' in 'wdiff'. + +'end-insert' + '-z' in 'wdiff'. + +'entire-new-file' + '-N' in 'diff'. + +'environment-overrides' + '-e' in 'make'. + +'eof' + '-e' in 'xargs'. + +'epoch' + Used in GDB. + +'error-limit' + Used in 'makeinfo'. + +'error-output' + '-o' in 'm4'. + +'escape' + '-b' in 'ls'. + +'exclude-from' + '-X' in 'tar'. + +'exec' + Used in GDB. + +'exit' + '-x' in 'xargs'. + +'exit-0' + '-e' in 'unshar'. + +'expand-tabs' + '-t' in 'diff'. + +'expression' + '-e' in 'sed'. + +'extern-only' + '-g' in 'nm'. + +'extract' + '-i' in 'cpio'; '-x' in 'tar'. + +'faces' + '-f' in 'finger'. + +'fast' + '-f' in 'su'. + +'fatal-warnings' + '-E' in 'm4'. + +'file' + '-f' in 'gawk', 'info', 'make', 'mt', 'sed', and 'tar'. + +'field-separator' + '-F' in 'gawk'. + +'file-prefix' + '-b' in Bison. + +'file-type' + '-F' in 'ls'. + +'files-from' + '-T' in 'tar'. + +'fill-column' + Used in 'makeinfo'. + +'flag-truncation' + '-F' in 'ptx'. + +'fixed-output-files' + '-y' in Bison. + +'follow' + '-f' in 'tail'. + +'footnote-style' + Used in 'makeinfo'. + +'force' + '-f' in 'cp', 'ln', 'mv', and 'rm'. + +'force-prefix' + '-F' in 'shar'. + +'foreground' + For server programs, run in the foreground; in other words, don't + do anything special to run the server in the background. + +'format' + Used in 'ls', 'time', and 'ptx'. + +'freeze-state' + '-F' in 'm4'. + +'fullname' + Used in GDB. + +'gap-size' + '-g' in 'ptx'. + +'get' + '-x' in 'tar'. + +'graphic' + '-i' in 'ul'. + +'graphics' + '-g' in 'recode'. + +'group' + '-g' in 'install'. + +'gzip' + '-z' in 'tar' and 'shar'. + +'hashsize' + '-H' in 'm4'. + +'header' + '-h' in 'objdump' and 'recode' + +'heading' + '-H' in 'who'. + +'help' + Used to ask for brief usage information. + +'here-delimiter' + '-d' in 'shar'. + +'hide-control-chars' + '-q' in 'ls'. + +'html' + In 'makeinfo', output HTML. + +'idle' + '-u' in 'who'. + +'ifdef' + '-D' in 'diff'. + +'ignore' + '-I' in 'ls'; '-x' in 'recode'. + +'ignore-all-space' + '-w' in 'diff'. + +'ignore-backups' + '-B' in 'ls'. + +'ignore-blank-lines' + '-B' in 'diff'. + +'ignore-case' + '-f' in 'look' and 'ptx'; '-i' in 'diff' and 'wdiff'. + +'ignore-errors' + '-i' in 'make'. + +'ignore-file' + '-i' in 'ptx'. + +'ignore-indentation' + '-I' in 'etags'. + +'ignore-init-file' + '-f' in Oleo. + +'ignore-interrupts' + '-i' in 'tee'. + +'ignore-matching-lines' + '-I' in 'diff'. + +'ignore-space-change' + '-b' in 'diff'. + +'ignore-zeros' + '-i' in 'tar'. + +'include' + '-i' in 'etags'; '-I' in 'm4'. + +'include-dir' + '-I' in 'make'. + +'incremental' + '-G' in 'tar'. + +'info' + '-i', '-l', and '-m' in Finger. + +'init-file' + In some programs, specify the name of the file to read as the + user's init file. + +'initial' + '-i' in 'expand'. + +'initial-tab' + '-T' in 'diff'. + +'inode' + '-i' in 'ls'. + +'interactive' + '-i' in 'cp', 'ln', 'mv', 'rm'; '-e' in 'm4'; '-p' in 'xargs'; '-w' + in 'tar'. + +'intermix-type' + '-p' in 'shar'. + +'iso-8601' + Used in 'date' + +'jobs' + '-j' in 'make'. + +'just-print' + '-n' in 'make'. + +'keep-going' + '-k' in 'make'. + +'keep-files' + '-k' in 'csplit'. + +'kilobytes' + '-k' in 'du' and 'ls'. + +'language' + '-l' in 'etags'. + +'less-mode' + '-l' in 'wdiff'. + +'level-for-gzip' + '-g' in 'shar'. + +'line-bytes' + '-C' in 'split'. + +'lines' + Used in 'split', 'head', and 'tail'. + +'link' + '-l' in 'cpio'. + +'lint' +'lint-old' + Used in 'gawk'. + +'list' + '-t' in 'cpio'; '-l' in 'recode'. + +'list' + '-t' in 'tar'. + +'literal' + '-N' in 'ls'. + +'load-average' + '-l' in 'make'. + +'login' + Used in 'su'. + +'machine' + Used in 'uname'. + +'macro-name' + '-M' in 'ptx'. + +'mail' + '-m' in 'hello' and 'uname'. + +'make-directories' + '-d' in 'cpio'. + +'makefile' + '-f' in 'make'. + +'mapped' + Used in GDB. + +'max-args' + '-n' in 'xargs'. + +'max-chars' + '-n' in 'xargs'. + +'max-lines' + '-l' in 'xargs'. + +'max-load' + '-l' in 'make'. + +'max-procs' + '-P' in 'xargs'. + +'mesg' + '-T' in 'who'. + +'message' + '-T' in 'who'. + +'minimal' + '-d' in 'diff'. + +'mixed-uuencode' + '-M' in 'shar'. + +'mode' + '-m' in 'install', 'mkdir', and 'mkfifo'. + +'modification-time' + '-m' in 'tar'. + +'multi-volume' + '-M' in 'tar'. + +'name-prefix' + '-a' in Bison. + +'nesting-limit' + '-L' in 'm4'. + +'net-headers' + '-a' in 'shar'. + +'new-file' + '-W' in 'make'. + +'no-builtin-rules' + '-r' in 'make'. + +'no-character-count' + '-w' in 'shar'. + +'no-check-existing' + '-x' in 'shar'. + +'no-common' + '-3' in 'wdiff'. + +'no-create' + '-c' in 'touch'. + +'no-defines' + '-D' in 'etags'. + +'no-deleted' + '-1' in 'wdiff'. + +'no-dereference' + '-d' in 'cp'. + +'no-inserted' + '-2' in 'wdiff'. + +'no-keep-going' + '-S' in 'make'. + +'no-lines' + '-l' in Bison. + +'no-piping' + '-P' in 'shar'. + +'no-prof' + '-e' in 'gprof'. + +'no-regex' + '-R' in 'etags'. + +'no-sort' + '-p' in 'nm'. + +'no-splash' + Don't print a startup splash screen. + +'no-split' + Used in 'makeinfo'. + +'no-static' + '-a' in 'gprof'. + +'no-time' + '-E' in 'gprof'. + +'no-timestamp' + '-m' in 'shar'. + +'no-validate' + Used in 'makeinfo'. + +'no-wait' + Used in 'emacsclient'. + +'no-warn' + Used in various programs to inhibit warnings. + +'node' + '-n' in 'info'. + +'nodename' + '-n' in 'uname'. + +'nonmatching' + '-f' in 'cpio'. + +'nstuff' + '-n' in 'objdump'. + +'null' + '-0' in 'xargs'. + +'number' + '-n' in 'cat'. + +'number-nonblank' + '-b' in 'cat'. + +'numeric-sort' + '-n' in 'nm'. + +'numeric-uid-gid' + '-n' in 'cpio' and 'ls'. + +'nx' + Used in GDB. + +'old-archive' + '-o' in 'tar'. + +'old-file' + '-o' in 'make'. + +'one-file-system' + '-l' in 'tar', 'cp', and 'du'. + +'only-file' + '-o' in 'ptx'. + +'only-prof' + '-f' in 'gprof'. + +'only-time' + '-F' in 'gprof'. + +'options' + '-o' in 'getopt', 'fdlist', 'fdmount', 'fdmountd', and 'fdumount'. + +'output' + In various programs, specify the output file name. + +'output-prefix' + '-o' in 'shar'. + +'override' + '-o' in 'rm'. + +'overwrite' + '-c' in 'unshar'. + +'owner' + '-o' in 'install'. + +'paginate' + '-l' in 'diff'. + +'paragraph-indent' + Used in 'makeinfo'. + +'parents' + '-p' in 'mkdir' and 'rmdir'. + +'pass-all' + '-p' in 'ul'. + +'pass-through' + '-p' in 'cpio'. + +'port' + '-P' in 'finger'. + +'portability' + '-c' in 'cpio' and 'tar'. + +'posix' + Used in 'gawk'. + +'prefix-builtins' + '-P' in 'm4'. + +'prefix' + '-f' in 'csplit'. + +'preserve' + Used in 'tar' and 'cp'. + +'preserve-environment' + '-p' in 'su'. + +'preserve-modification-time' + '-m' in 'cpio'. + +'preserve-order' + '-s' in 'tar'. + +'preserve-permissions' + '-p' in 'tar'. + +'print' + '-l' in 'diff'. + +'print-chars' + '-L' in 'cmp'. + +'print-data-base' + '-p' in 'make'. + +'print-directory' + '-w' in 'make'. + +'print-file-name' + '-o' in 'nm'. + +'print-symdefs' + '-s' in 'nm'. + +'printer' + '-p' in 'wdiff'. + +'prompt' + '-p' in 'ed'. + +'proxy' + Specify an HTTP proxy. + +'query-user' + '-X' in 'shar'. + +'question' + '-q' in 'make'. + +'quiet' + Used in many programs to inhibit the usual output. Every program + accepting '--quiet' should accept '--silent' as a synonym. + +'quiet-unshar' + '-Q' in 'shar' + +'quote-name' + '-Q' in 'ls'. + +'rcs' + '-n' in 'diff'. + +'re-interval' + Used in 'gawk'. + +'read-full-blocks' + '-B' in 'tar'. + +'readnow' + Used in GDB. + +'recon' + '-n' in 'make'. + +'record-number' + '-R' in 'tar'. + +'recursive' + Used in 'chgrp', 'chown', 'cp', 'ls', 'diff', and 'rm'. + +'reference' + '-r' in 'touch'. + +'references' + '-r' in 'ptx'. + +'regex' + '-r' in 'tac' and 'etags'. + +'release' + '-r' in 'uname'. + +'reload-state' + '-R' in 'm4'. + +'relocation' + '-r' in 'objdump'. + +'rename' + '-r' in 'cpio'. + +'replace' + '-i' in 'xargs'. + +'report-identical-files' + '-s' in 'diff'. + +'reset-access-time' + '-a' in 'cpio'. + +'reverse' + '-r' in 'ls' and 'nm'. + +'reversed-ed' + '-f' in 'diff'. + +'right-side-defs' + '-R' in 'ptx'. + +'same-order' + '-s' in 'tar'. + +'same-permissions' + '-p' in 'tar'. + +'save' + '-g' in 'stty'. + +'se' + Used in GDB. + +'sentence-regexp' + '-S' in 'ptx'. + +'separate-dirs' + '-S' in 'du'. + +'separator' + '-s' in 'tac'. + +'sequence' + Used by 'recode' to chose files or pipes for sequencing passes. + +'shell' + '-s' in 'su'. + +'show-all' + '-A' in 'cat'. + +'show-c-function' + '-p' in 'diff'. + +'show-ends' + '-E' in 'cat'. + +'show-function-line' + '-F' in 'diff'. + +'show-tabs' + '-T' in 'cat'. + +'silent' + Used in many programs to inhibit the usual output. Every program + accepting '--silent' should accept '--quiet' as a synonym. + +'size' + '-s' in 'ls'. + +'socket' + Specify a file descriptor for a network server to use for its + socket, instead of opening and binding a new socket. This provides + a way to run, in a non-privileged process, a server that normally + needs a reserved port number. + +'sort' + Used in 'ls'. + +'source' + '-W source' in 'gawk'. + +'sparse' + '-S' in 'tar'. + +'speed-large-files' + '-H' in 'diff'. + +'split-at' + '-E' in 'unshar'. + +'split-size-limit' + '-L' in 'shar'. + +'squeeze-blank' + '-s' in 'cat'. + +'start-delete' + '-w' in 'wdiff'. + +'start-insert' + '-y' in 'wdiff'. + +'starting-file' + Used in 'tar' and 'diff' to specify which file within a directory + to start processing with. + +'statistics' + '-s' in 'wdiff'. + +'stdin-file-list' + '-S' in 'shar'. + +'stop' + '-S' in 'make'. + +'strict' + '-s' in 'recode'. + +'strip' + '-s' in 'install'. + +'strip-all' + '-s' in 'strip'. + +'strip-debug' + '-S' in 'strip'. + +'submitter' + '-s' in 'shar'. + +'suffix' + '-S' in 'cp', 'ln', 'mv'. + +'suffix-format' + '-b' in 'csplit'. + +'sum' + '-s' in 'gprof'. + +'summarize' + '-s' in 'du'. + +'symbolic' + '-s' in 'ln'. + +'symbols' + Used in GDB and 'objdump'. + +'synclines' + '-s' in 'm4'. + +'sysname' + '-s' in 'uname'. + +'tabs' + '-t' in 'expand' and 'unexpand'. + +'tabsize' + '-T' in 'ls'. + +'terminal' + '-T' in 'tput' and 'ul'. '-t' in 'wdiff'. + +'text' + '-a' in 'diff'. + +'text-files' + '-T' in 'shar'. + +'time' + Used in 'ls' and 'touch'. + +'timeout' + Specify how long to wait before giving up on some operation. + +'to-stdout' + '-O' in 'tar'. + +'total' + '-c' in 'du'. + +'touch' + '-t' in 'make', 'ranlib', and 'recode'. + +'trace' + '-t' in 'm4'. + +'traditional' + '-t' in 'hello'; '-W traditional' in 'gawk'; '-G' in 'ed', 'm4', + and 'ptx'. + +'tty' + Used in GDB. + +'typedefs' + '-t' in 'ctags'. + +'typedefs-and-c++' + '-T' in 'ctags'. + +'typeset-mode' + '-t' in 'ptx'. + +'uncompress' + '-z' in 'tar'. + +'unconditional' + '-u' in 'cpio'. + +'undefine' + '-U' in 'm4'. + +'undefined-only' + '-u' in 'nm'. + +'update' + '-u' in 'cp', 'ctags', 'mv', 'tar'. + +'usage' + Used in 'gawk'; same as '--help'. + +'uuencode' + '-B' in 'shar'. + +'vanilla-operation' + '-V' in 'shar'. + +'verbose' + Print more information about progress. Many programs support this. + +'verify' + '-W' in 'tar'. + +'version' + Print the version number. + +'version-control' + '-V' in 'cp', 'ln', 'mv'. + +'vgrind' + '-v' in 'ctags'. + +'volume' + '-V' in 'tar'. + +'what-if' + '-W' in 'make'. + +'whole-size-limit' + '-l' in 'shar'. + +'width' + '-w' in 'ls' and 'ptx'. + +'word-regexp' + '-W' in 'ptx'. + +'writable' + '-T' in 'who'. + +'zeros' + '-z' in 'gprof'. + + +File: standards.info, Node: OID Allocations, Next: Memory Usage, Prev: Option Table, Up: Program Behavior + +4.9 OID Allocations +=================== + +The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the +GNU Project (thanks to Werner Koch). These are used for SNMP, LDAP, +X.509 certificates, and so on. The web site + has a (voluntary) listing of many +OID assignments. + + If you need a new slot for your GNU package, write +. Here is a list of arcs currently assigned: + + + 1.3.6.1.4.1.11591 GNU + + 1.3.6.1.4.1.11591.1 GNU Radius + + 1.3.6.1.4.1.11591.2 GnuPG + 1.3.6.1.4.1.11591.2.1 notation + 1.3.6.1.4.1.11591.2.1.1 pkaAddress + + 1.3.6.1.4.1.11591.3 GNU Radar + + 1.3.6.1.4.1.11591.4 GNU GSS + + 1.3.6.1.4.1.11591.5 GNU Mailutils + + 1.3.6.1.4.1.11591.6 GNU Shishi + + 1.3.6.1.4.1.11591.7 GNU Radio + + 1.3.6.1.4.1.11591.12 digestAlgorithm + 1.3.6.1.4.1.11591.12.2 TIGER/192 + 1.3.6.1.4.1.11591.13 encryptionAlgorithm + 1.3.6.1.4.1.11591.13.2 Serpent + 1.3.6.1.4.1.11591.13.2.1 Serpent-128-ECB + 1.3.6.1.4.1.11591.13.2.2 Serpent-128-CBC + 1.3.6.1.4.1.11591.13.2.3 Serpent-128-OFB + 1.3.6.1.4.1.11591.13.2.4 Serpent-128-CFB + 1.3.6.1.4.1.11591.13.2.21 Serpent-192-ECB + 1.3.6.1.4.1.11591.13.2.22 Serpent-192-CBC + 1.3.6.1.4.1.11591.13.2.23 Serpent-192-OFB + 1.3.6.1.4.1.11591.13.2.24 Serpent-192-CFB + 1.3.6.1.4.1.11591.13.2.41 Serpent-256-ECB + 1.3.6.1.4.1.11591.13.2.42 Serpent-256-CBC + 1.3.6.1.4.1.11591.13.2.43 Serpent-256-OFB + 1.3.6.1.4.1.11591.13.2.44 Serpent-256-CFB + 1.3.6.1.4.1.11591.14 CRC algorithms + 1.3.6.1.4.1.11591.14.1 CRC 32 + + +File: standards.info, Node: Memory Usage, Next: File Usage, Prev: OID Allocations, Up: Program Behavior + +4.10 Memory Usage +================= + +If a program typically uses just a few meg of memory, don't bother +making any effort to reduce memory usage. For example, if it is +impractical for other reasons to operate on files more than a few meg +long, it is reasonable to read entire input files into memory to operate +on them. + + However, for programs such as 'cat' or 'tail', that can usefully +operate on very large files, it is important to avoid using a technique +that would artificially limit the size of files it can handle. If a +program works by lines and could be applied to arbitrary user-supplied +input files, it should keep only a line in memory, because this is not +very hard and users will want to be able to operate on input files that +are bigger than will fit in memory all at once. + + If your program creates complicated data structures, just make them +in memory and give a fatal error if 'malloc' returns zero. + + +File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior + +4.11 File Usage +=============== + +Programs should be prepared to operate when '/usr' and '/etc' are +read-only file systems. Thus, if the program manages log files, lock +files, backup files, score files, or any other files which are modified +for internal purposes, these files should not be stored in '/usr' or +'/etc'. + + There are two exceptions. '/etc' is used to store system +configuration information; it is reasonable for a program to modify +files in '/etc' when its job is to update the system configuration. +Also, if the user explicitly asks to modify one file in a directory, it +is reasonable for the program to store other files in the same +directory. + + +File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top + +5 Making The Best Use of C +************************** + +This chapter provides advice on how best to use the C language when +writing GNU software. + +* Menu: + +* Formatting:: Formatting your source code. +* Comments:: Commenting your work. +* Syntactic Conventions:: Clean use of C constructs. +* Names:: Naming variables, functions, and files. +* System Portability:: Portability among different operating systems. +* CPU Portability:: Supporting the range of CPU types. +* System Functions:: Portability and "standard" library functions. +* Internationalization:: Techniques for internationalization. +* Character Set:: Use ASCII by default. +* Quote Characters:: Use '...' in the C locale. +* Mmap:: How you can safely use 'mmap'. + + +File: standards.info, Node: Formatting, Next: Comments, Up: Writing C + +5.1 Formatting Your Source Code +=============================== + +It is important to put the open-brace that starts the body of a C +function in column one, so that they will start a defun. Several tools +look for open-braces in column one to find the beginnings of C +functions. These tools will not work on code not formatted that way. + + Avoid putting open-brace, open-parenthesis or open-bracket in column +one when they are inside a function, so that they won't start a defun. +The open-brace that starts a 'struct' body can go in column one if you +find it useful to treat that definition as a defun. + + It is also important for function definitions to start the name of +the function in column one. This helps people to search for function +definitions, and may also help certain tools recognize them. Thus, +using Standard C syntax, the format is this: + + static char * + concat (char *s1, char *s2) + { + ... + } + +or, if you want to use traditional C syntax, format the definition like +this: + + static char * + concat (s1, s2) /* Name starts in column one here */ + char *s1, *s2; + { /* Open brace in column one here */ + ... + } + + In Standard C, if the arguments don't fit nicely on one line, split +it like this: + + int + lots_of_args (int an_integer, long a_long, short a_short, + double a_double, float a_float) + ... + + The rest of this section gives our recommendations for other aspects +of C formatting style, which is also the default style of the 'indent' +program in version 1.2 and newer. It corresponds to the options + + -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 + -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob + + We don't think of these recommendations as requirements, because it +causes no problems for users if two different programs have different +formatting styles. + + But whatever style you use, please use it consistently, since a +mixture of styles within one program tends to look ugly. If you are +contributing changes to an existing program, please follow the style of +that program. + + For the body of the function, our recommended style looks like this: + + if (x < foo (y, z)) + haha = bar[4] + 5; + else + { + while (z) + { + haha += foo (z, z); + z--; + } + return ++x + bar (); + } + + We find it easier to read a program when it has spaces before the +open-parentheses and after the commas. Especially after the commas. + + When you split an expression into multiple lines, split it before an +operator, not after one. Here is the right way: + + if (foo_this_is_long && bar > win (x, y, z) + && remaining_condition) + + Try to avoid having two operators of different precedence at the same +level of indentation. For example, don't write this: + + mode = (inmode[j] == VOIDmode + || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) + ? outmode[j] : inmode[j]); + + Instead, use extra parentheses so that the indentation shows the +nesting: + + mode = ((inmode[j] == VOIDmode + || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) + ? outmode[j] : inmode[j]); + + Insert extra parentheses so that Emacs will indent the code properly. +For example, the following indentation looks nice if you do it by hand, + + v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; + +but Emacs would alter it. Adding a set of parentheses produces +something that looks equally nice, and which Emacs will preserve: + + v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); + + Format do-while statements like this: + + do + { + a = foo (a); + } + while (a > 0); + + Please use formfeed characters (control-L) to divide the program into +pages at logical places (but not within a function). It does not matter +just how long the pages are, since they do not have to fit on a printed +page. The formfeeds should appear alone on lines by themselves. + + +File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C + +5.2 Commenting Your Work +======================== + +Every program should start with a comment saying briefly what it is for. +Example: 'fmt - filter for simple filling of text'. This comment should +be at the top of the source file containing the 'main' function of the +program. + + Also, please write a brief comment at the start of each source file, +with the file name and a line or two about the overall purpose of the +file. + + Please write the comments in a GNU program in English, because +English is the one language that nearly all programmers in all countries +can read. If you do not write English well, please write comments in +English as well as you can, then ask other people to help rewrite them. +If you can't write comments in English, please find someone to work with +you and translate your comments into English. + + Please put a comment on each function saying what the function does, +what sorts of arguments it gets, and what the possible values of +arguments mean and are used for. It is not necessary to duplicate in +words the meaning of the C argument declarations, if a C type is being +used in its customary fashion. If there is anything nonstandard about +its use (such as an argument of type 'char *' which is really the +address of the second character of a string, not the first), or any +possible values that would not work the way one would expect (such as, +that strings containing newlines are not guaranteed to work), be sure to +say so. + + Also explain the significance of the return value, if there is one. + + Please put two spaces after the end of a sentence in your comments, +so that the Emacs sentence commands will work. Also, please write +complete sentences and capitalize the first word. If a lower-case +identifier comes at the beginning of a sentence, don't capitalize it! +Changing the spelling makes it a different identifier. If you don't +like starting a sentence with a lower case letter, write the sentence +differently (e.g., "The identifier lower-case is ..."). + + The comment on a function is much clearer if you use the argument +names to speak about the argument values. The variable name itself +should be lower case, but write it in upper case when you are speaking +about the value rather than the variable itself. Thus, "the inode +number NODE_NUM" rather than "an inode". + + There is usually no purpose in restating the name of the function in +the comment before it, because the reader can see that for himself. +There might be an exception when the comment is so long that the +function itself would be off the bottom of the screen. + + There should be a comment on each static variable as well, like this: + + /* Nonzero means truncate lines in the display; + zero means continue them. */ + int truncate_lines; + + Every '#endif' should have a comment, except in the case of short +conditionals (just a few lines) that are not nested. The comment should +state the condition of the conditional that is ending, _including its +sense_. '#else' should have a comment describing the condition _and +sense_ of the code that follows. For example: + + #ifdef foo + ... + #else /* not foo */ + ... + #endif /* not foo */ + #ifdef foo + ... + #endif /* foo */ + +but, by contrast, write the comments this way for a '#ifndef': + + #ifndef foo + ... + #else /* foo */ + ... + #endif /* foo */ + #ifndef foo + ... + #endif /* not foo */ + + +File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C + +5.3 Clean Use of C Constructs +============================= + +Please explicitly declare the types of all objects. For example, you +should explicitly declare all arguments to functions, and you should +declare functions to return 'int' rather than omitting the 'int'. + + Some programmers like to use the GCC '-Wall' option, and change the +code whenever it issues a warning. If you want to do this, then do. +Other programmers prefer not to use '-Wall', because it gives warnings +for valid and legitimate code which they do not want to change. If you +want to do this, then do. The compiler should be your servant, not your +master. + + Declarations of external functions and functions to appear later in +the source file should all go in one place near the beginning of the +file (somewhere before the first function definition in the file), or +else should go in a header file. Don't put 'extern' declarations inside +functions. + + It used to be common practice to use the same local variables (with +names like 'tem') over and over for different values within one +function. Instead of doing this, it is better to declare a separate +local variable for each distinct purpose, and give it a name which is +meaningful. This not only makes programs easier to understand, it also +facilitates optimization by good compilers. You can also move the +declaration of each local variable into the smallest scope that includes +all its uses. This makes the program even cleaner. + + Don't use local variables or parameters that shadow global +identifiers. + + Don't declare multiple variables in one declaration that spans lines. +Start a new declaration on each line, instead. For example, instead of +this: + + int foo, + bar; + +write either this: + + int foo, bar; + +or this: + + int foo; + int bar; + +(If they are global variables, each should have a comment preceding it +anyway.) + + When you have an 'if'-'else' statement nested in another 'if' +statement, always put braces around the 'if'-'else'. Thus, never write +like this: + + if (foo) + if (bar) + win (); + else + lose (); + +always like this: + + if (foo) + { + if (bar) + win (); + else + lose (); + } + + If you have an 'if' statement nested inside of an 'else' statement, +either write 'else if' on one line, like this, + + if (foo) + ... + else if (bar) + ... + +with its 'then'-part indented like the preceding 'then'-part, or write +the nested 'if' within braces like this: + + if (foo) + ... + else + { + if (bar) + ... + } + + Don't declare both a structure tag and variables or typedefs in the +same declaration. Instead, declare the structure tag separately and +then use it to declare the variables or typedefs. + + Try to avoid assignments inside 'if'-conditions (assignments inside +'while'-conditions are ok). For example, don't write this: + + if ((foo = (char *) malloc (sizeof *foo)) == 0) + fatal ("virtual memory exhausted"); + +instead, write this: + + foo = (char *) malloc (sizeof *foo); + if (foo == 0) + fatal ("virtual memory exhausted"); + + Don't make the program ugly to placate 'lint'. Please don't insert +any casts to 'void'. Zero without a cast is perfectly fine as a null +pointer constant, except when calling a varargs function. + + +File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C + +5.4 Naming Variables, Functions, and Files +========================================== + +The names of global variables and functions in a program serve as +comments of a sort. So don't choose terse names--instead, look for +names that give useful information about the meaning of the variable or +function. In a GNU program, names should be English, like other +comments. + + Local variable names can be shorter, because they are used only +within one context, where (presumably) comments explain their purpose. + + Try to limit your use of abbreviations in symbol names. It is ok to +make a few abbreviations, explain what they mean, and then use them +frequently, but don't use lots of obscure abbreviations. + + Please use underscores to separate words in a name, so that the Emacs +word commands can be useful within them. Stick to lower case; reserve +upper case for macros and 'enum' constants, and for name-prefixes that +follow a uniform convention. + + For example, you should use names like 'ignore_space_change_flag'; +don't use names like 'iCantReadThis'. + + Variables that indicate whether command-line options have been +specified should be named after the meaning of the option, not after the +option-letter. A comment should state both the exact meaning of the +option and its letter. For example, + + /* Ignore changes in horizontal whitespace (-b). */ + int ignore_space_change_flag; + + When you want to define names with constant integer values, use +'enum' rather than '#define'. GDB knows about enumeration constants. + + You might want to make sure that none of the file names would +conflict if the files were loaded onto an MS-DOS file system which +shortens the names. You can use the program 'doschk' to test for this. + + Some GNU programs were designed to limit themselves to file names of +14 characters or less, to avoid file name conflicts if they are read +into older System V systems. Please preserve this feature in the +existing GNU programs that have it, but there is no need to do this in +new GNU programs. 'doschk' also reports file names longer than 14 +characters. + + +File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C + +5.5 Portability between System Types +==================================== + +In the Unix world, "portability" refers to porting to different Unix +versions. For a GNU program, this kind of portability is desirable, but +not paramount. + + The primary purpose of GNU software is to run on top of the GNU +kernel, compiled with the GNU C compiler, on various types of CPU. So +the kinds of portability that are absolutely necessary are quite +limited. But it is important to support Linux-based GNU systems, since +they are the form of GNU that is popular. + + Beyond that, it is good to support the other free operating systems +(*BSD), and it is nice to support other Unix-like systems if you want +to. Supporting a variety of Unix-like systems is desirable, although +not paramount. It is usually not too hard, so you may as well do it. +But you don't have to consider it an obligation, if it does turn out to +be hard. + + The easiest way to achieve portability to most Unix-like systems is +to use Autoconf. It's unlikely that your program needs to know more +information about the host platform than Autoconf can provide, simply +because most of the programs that need such knowledge have already been +written. + + Avoid using the format of semi-internal data bases (e.g., +directories) when there is a higher-level alternative ('readdir'). + + As for systems that are not like Unix, such as MSDOS, Windows, VMS, +MVS, and older Macintosh systems, supporting them is often a lot of +work. When that is the case, it is better to spend your time adding +features that will be useful on GNU and GNU/Linux, rather than on +supporting other incompatible systems. + + If you do support Windows, please do not abbreviate it as "win". In +hacker terminology, calling something a "win" is a form of praise. +You're free to praise Microsoft Windows on your own if you want, but +please don't do this in GNU packages. Instead of abbreviating "Windows" +to "win", you can write it in full or abbreviate it to "woe" or "w". In +GNU Emacs, for instance, we use 'w32' in file names of Windows-specific +files, but the macro for Windows conditionals is called 'WINDOWSNT'. + + It is a good idea to define the "feature test macro" '_GNU_SOURCE' +when compiling your C files. When you compile on GNU or GNU/Linux, this +will enable the declarations of GNU library extension functions, and +that will usually give you a compiler error message if you define the +same function names in some other way in your program. (You don't have +to actually _use_ these functions, if you prefer to make the program +more portable to other systems.) + + But whether or not you use these GNU extensions, you should avoid +using their names for any other meanings. Doing so would make it hard +to move your code into other GNU programs. + + +File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C + +5.6 Portability between CPUs +============================ + +Even GNU systems will differ because of differences among CPU types--for +example, difference in byte ordering and alignment requirements. It is +absolutely essential to handle these differences. However, don't make +any effort to cater to the possibility that an 'int' will be less than +32 bits. We don't support 16-bit machines in GNU. + + Similarly, don't make any effort to cater to the possibility that +'long' will be smaller than predefined types like 'size_t'. For +example, the following code is ok: + + printf ("size = %lu\n", (unsigned long) sizeof array); + printf ("diff = %ld\n", (long) (pointer2 - pointer1)); + + 1989 Standard C requires this to work, and we know of only one +counterexample: 64-bit programs on Microsoft Windows. We will leave it +to those who want to port GNU programs to that environment to figure out +how to do it. + + Predefined file-size types like 'off_t' are an exception: they are +longer than 'long' on many platforms, so code like the above won't work +with them. One way to print an 'off_t' value portably is to print its +digits yourself, one by one. + + Don't assume that the address of an 'int' object is also the address +of its least-significant byte. This is false on big-endian machines. +Thus, don't make the following mistake: + + int c; + ... + while ((c = getchar ()) != EOF) + write (file_descriptor, &c, 1); + +Instead, use 'unsigned char' as follows. (The 'unsigned' is for +portability to unusual systems where 'char' is signed and where there is +integer overflow checking.) + + int c; + while ((c = getchar ()) != EOF) + { + unsigned char u = c; + write (file_descriptor, &u, 1); + } + + It used to be ok to not worry about the difference between pointers +and integers when passing arguments to functions. However, on most +modern 64-bit machines pointers are wider than 'int'. Conversely, +integer types like 'long long int' and 'off_t' are wider than pointers +on most modern 32-bit machines. Hence it's often better nowadays to use +prototypes to define functions whose argument types are not trivial. + + In particular, if functions accept varying argument counts or types +they should be declared using prototypes containing '...' and defined +using 'stdarg.h'. For an example of this, please see the Gnulib +(http://www.gnu.org/software/gnulib/) error module, which declares and +defines the following function: + + /* Print a message with `fprintf (stderr, FORMAT, ...)'; + if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM). + If STATUS is nonzero, terminate the program with `exit (STATUS)'. */ + + void error (int status, int errnum, const char *format, ...); + + A simple way to use the Gnulib error module is to obtain the two +source files 'error.c' and 'error.h' from the Gnulib library source code +repository at . +Here's a sample use: + + #include "error.h" + #include + #include + + char *program_name = "myprogram"; + + FILE * + xfopen (char const *name) + { + FILE *fp = fopen (name, "r"); + if (! fp) + error (1, errno, "cannot read %s", name); + return fp; + } + + Avoid casting pointers to integers if you can. Such casts greatly +reduce portability, and in most programs they are easy to avoid. In the +cases where casting pointers to integers is essential--such as, a Lisp +interpreter which stores type information as well as an address in one +word--you'll have to make explicit provisions to handle different word +sizes. You will also need to make provision for systems in which the +normal range of addresses you can get from 'malloc' starts far away from +zero. + + +File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C + +5.7 Calling System Functions +============================ + +C implementations differ substantially. Standard C reduces but does not +eliminate the incompatibilities; meanwhile, many GNU packages still +support pre-standard compilers because this is not hard to do. This +chapter gives recommendations for how to use the more-or-less standard C +library functions to avoid unnecessary loss of portability. + + * Don't use the return value of 'sprintf'. It returns the number of + characters written on some systems, but not on all systems. + + * Be aware that 'vfprintf' is not always available. + + * 'main' should be declared to return type 'int'. It should + terminate either by calling 'exit' or by returning the integer + status code; make sure it cannot ever return an undefined value. + + * Don't declare system functions explicitly. + + Almost any declaration for a system function is wrong on some + system. To minimize conflicts, leave it to the system header files + to declare system functions. If the headers don't declare a + function, let it remain undeclared. + + While it may seem unclean to use a function without declaring it, + in practice this works fine for most system library functions on + the systems where this really happens; thus, the disadvantage is + only theoretical. By contrast, actual declarations have frequently + caused actual conflicts. + + * If you must declare a system function, don't specify the argument + types. Use an old-style declaration, not a Standard C prototype. + The more you specify about the function, the more likely a + conflict. + + * In particular, don't unconditionally declare 'malloc' or 'realloc'. + + Most GNU programs use those functions just once, in functions + conventionally named 'xmalloc' and 'xrealloc'. These functions + call 'malloc' and 'realloc', respectively, and check the results. + + Because 'xmalloc' and 'xrealloc' are defined in your program, you + can declare them in other files without any risk of type conflict. + + On most systems, 'int' is the same length as a pointer; thus, the + calls to 'malloc' and 'realloc' work fine. For the few exceptional + systems (mostly 64-bit machines), you can use *conditionalized* + declarations of 'malloc' and 'realloc'--or put these declarations + in configuration files specific to those systems. + + * The string functions require special treatment. Some Unix systems + have a header file 'string.h'; others have 'strings.h'. Neither + file name is portable. There are two things you can do: use + Autoconf to figure out which file to include, or don't include + either file. + + * If you don't include either strings file, you can't get + declarations for the string functions from the header file in the + usual way. + + That causes less of a problem than you might think. The newer + standard string functions should be avoided anyway because many + systems still don't support them. The string functions you can use + are these: + + strcpy strncpy strcat strncat + strlen strcmp strncmp + strchr strrchr + + The copy and concatenate functions work fine without a declaration + as long as you don't use their values. Using their values without + a declaration fails on systems where the width of a pointer differs + from the width of 'int', and perhaps in other cases. It is trivial + to avoid using their values, so do that. + + The compare functions and 'strlen' work fine without a declaration + on most systems, possibly all the ones that GNU software runs on. + You may find it necessary to declare them *conditionally* on a few + systems. + + The search functions must be declared to return 'char *'. Luckily, + there is no variation in the data type they return. But there is + variation in their names. Some systems give these functions the + names 'index' and 'rindex'; other systems use the names 'strchr' + and 'strrchr'. Some systems support both pairs of names, but + neither pair works on all systems. + + You should pick a single pair of names and use it throughout your + program. (Nowadays, it is better to choose 'strchr' and 'strrchr' + for new programs, since those are the standard names.) Declare + both of those names as functions returning 'char *'. On systems + which don't support those names, define them as macros in terms of + the other pair. For example, here is what to put at the beginning + of your file (or in a header) if you want to use the names 'strchr' + and 'strrchr' throughout: + + #ifndef HAVE_STRCHR + #define strchr index + #endif + #ifndef HAVE_STRRCHR + #define strrchr rindex + #endif + + char *strchr (); + char *strrchr (); + + Here we assume that 'HAVE_STRCHR' and 'HAVE_STRRCHR' are macros +defined in systems where the corresponding functions exist. One way to +get them properly defined is to use Autoconf. + + +File: standards.info, Node: Internationalization, Next: Character Set, Prev: System Functions, Up: Writing C + +5.8 Internationalization +======================== + +GNU has a library called GNU gettext that makes it easy to translate the +messages in a program into various languages. You should use this +library in every program. Use English for the messages as they appear +in the program, and let gettext provide the way to translate them into +other languages. + + Using GNU gettext involves putting a call to the 'gettext' macro +around each string that might need translation--like this: + + printf (gettext ("Processing file `%s'...")); + +This permits GNU gettext to replace the string '"Processing file +`%s'..."' with a translated version. + + Once a program uses gettext, please make a point of writing calls to +'gettext' when you add new strings that call for translation. + + Using GNU gettext in a package involves specifying a "text domain +name" for the package. The text domain name is used to separate the +translations for this package from the translations for other packages. +Normally, the text domain name should be the same as the name of the +package--for example, 'coreutils' for the GNU core utilities. + + To enable gettext to work well, avoid writing code that makes +assumptions about the structure of words or sentences. When you want +the precise text of a sentence to vary depending on the data, use two or +more alternative string constants each containing a complete sentences, +rather than inserting conditionalized words or phrases into a single +sentence framework. + + Here is an example of what not to do: + + printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk"); + + If you apply gettext to all strings, like this, + + printf (gettext ("%s is full"), + capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk")); + +the translator will hardly know that "disk" and "floppy disk" are meant +to be substituted in the other string. Worse, in some languages (like +French) the construction will not work: the translation of the word +"full" depends on the gender of the first part of the sentence; it +happens to be not the same for "disk" as for "floppy disk". + + Complete sentences can be translated without problems: + + printf (capacity > 5000000 ? gettext ("disk is full") + : gettext ("floppy disk is full")); + + A similar problem appears at the level of sentence structure with +this code: + + printf ("# Implicit rule search has%s been done.\n", + f->tried_implicit ? "" : " not"); + +Adding 'gettext' calls to this code cannot give correct results for all +languages, because negation in some languages requires adding words at +more than one place in the sentence. By contrast, adding 'gettext' +calls does the job straightforwardly if the code starts out like this: + + printf (f->tried_implicit + ? "# Implicit rule search has been done.\n", + : "# Implicit rule search has not been done.\n"); + + Another example is this one: + + printf ("%d file%s processed", nfiles, + nfiles != 1 ? "s" : ""); + +The problem with this example is that it assumes that plurals are made +by adding 's'. If you apply gettext to the format string, like this, + + printf (gettext ("%d file%s processed"), nfiles, + nfiles != 1 ? "s" : ""); + +the message can use different words, but it will still be forced to use +'s' for the plural. Here is a better way, with gettext being applied to +the two strings independently: + + printf ((nfiles != 1 ? gettext ("%d files processed") + : gettext ("%d file processed")), + nfiles); + +But this still doesn't work for languages like Polish, which has three +plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23, +24, ... and one for the rest. The GNU 'ngettext' function solves this +problem: + + printf (ngettext ("%d files processed", "%d file processed", nfiles), + nfiles); + + +File: standards.info, Node: Character Set, Next: Quote Characters, Prev: Internationalization, Up: Writing C + +5.9 Character Set +================= + +Sticking to the ASCII character set (plain text, 7-bit characters) is +preferred in GNU source code comments, text documents, and other +contexts, unless there is good reason to do something else because of +the application domain. For example, if source code deals with the +French Revolutionary calendar, it is OK if its literal strings contain +accented characters in month names like "Flore'al". Also, it is OK to +use non-ASCII characters to represent proper names of contributors in +change logs (*note Change Logs::). + + If you need to use non-ASCII characters, you should normally stick +with one encoding, as one cannot in general mix encodings reliably. + + +File: standards.info, Node: Quote Characters, Next: Mmap, Prev: Character Set, Up: Writing C + +5.10 Quote Characters +===================== + +In the C locale, GNU programs should stick to plain ASCII for quotation +characters in messages to users: preferably 0x60 ('`') for left quotes +and 0x27 (''') for right quotes. It is ok, but not required, to use +locale-specific quotes in other locales. + + The Gnulib (http://www.gnu.org/software/gnulib/) 'quote' and +'quotearg' modules provide a reasonably straightforward way to support +locale-specific quote characters, as well as taking care of other +issues, such as quoting a filename that itself contains a quote +character. See the Gnulib documentation for usage details. + + In any case, the documentation for your program should clearly +specify how it does quoting, if different than the preferred method of +'`' and '''. This is especially important if the output of your program +is ever likely to be parsed by another program. + + Quotation characters are a difficult area in the computing world at +this time: there are no true left or right quote characters in Latin1; +the '`' character we use was standardized there as a grave accent. +Moreover, Latin1 is still not universally usable. + + Unicode contains the unambiguous quote characters required, and its +common encoding UTF-8 is upward compatible with Latin1. However, +Unicode and UTF-8 are not universally well-supported, either. + + This may change over the next few years, and then we will revisit +this. + + +File: standards.info, Node: Mmap, Prev: Quote Characters, Up: Writing C + +5.11 Mmap +========= + +Don't assume that 'mmap' either works on all files or fails for all +files. It may work on some files and fail on others. + + The proper way to use 'mmap' is to try it on the specific file for +which you want to use it--and if 'mmap' doesn't work, fall back on doing +the job in another way using 'read' and 'write'. + + The reason this precaution is needed is that the GNU kernel (the +HURD) provides a user-extensible file system, in which there can be many +different kinds of "ordinary files." Many of them support 'mmap', but +some do not. It is important to make programs handle all these kinds of +files. + + +File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top + +6 Documenting Programs +********************** + +A GNU program should ideally come with full free documentation, adequate +for both reference and tutorial purposes. If the package can be +programmed or extended, the documentation should cover programming or +extending it, as well as just using it. + +* Menu: + +* GNU Manuals:: Writing proper manuals. +* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual. +* Manual Structure Details:: Specific structure conventions. +* License for Manuals:: Writing the distribution terms for a manual. +* Manual Credits:: Giving credit to documentation contributors. +* Printed Manuals:: Mentioning the printed manual. +* NEWS File:: NEWS files supplement manuals. +* Change Logs:: Recording changes. +* Man Pages:: Man pages are secondary. +* Reading other Manuals:: How far you can go in learning + from other manuals. + + +File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation + +6.1 GNU Manuals +=============== + +The preferred document format for the GNU system is the Texinfo +formatting language. Every GNU package should (ideally) have +documentation in Texinfo both for reference and for learners. Texinfo +makes it possible to produce a good quality formatted book, using TeX, +and to generate an Info file. It is also possible to generate HTML +output from Texinfo source. See the Texinfo manual, either the +hardcopy, or the on-line version available through 'info' or the Emacs +Info subsystem ('C-h i'). + + Nowadays some other formats such as Docbook and Sgmltexi can be +converted automatically into Texinfo. It is ok to produce the Texinfo +documentation by conversion this way, as long as it gives good results. + + Make sure your manual is clear to a reader who knows nothing about +the topic and reads it straight through. This means covering basic +topics at the beginning, and advanced topics only later. This also +means defining every specialized term when it is first used. + + Programmers tend to carry over the structure of the program as the +structure for its documentation. But this structure is not necessarily +good for explaining how to use the program; it may be irrelevant and +confusing for a user. + + Instead, the right way to structure documentation is according to the +concepts and questions that a user will have in mind when reading it. +This principle applies at every level, from the lowest (ordering +sentences in a paragraph) to the highest (ordering of chapter topics +within the manual). Sometimes this structure of ideas matches the +structure of the implementation of the software being documented--but +often they are different. An important part of learning to write good +documentation is to learn to notice when you have unthinkingly +structured the documentation like the implementation, stop yourself, and +look for better alternatives. + + For example, each program in the GNU system probably ought to be +documented in one manual; but this does not mean each program should +have its own manual. That would be following the structure of the +implementation, rather than the structure that helps the user +understand. + + Instead, each manual should cover a coherent _topic_. For example, +instead of a manual for 'diff' and a manual for 'diff3', we have one +manual for "comparison of files" which covers both of those programs, as +well as 'cmp'. By documenting these programs together, we can make the +whole subject clearer. + + The manual which discusses a program should certainly document all of +the program's command-line options and all of its commands. It should +give examples of their use. But don't organize the manual as a list of +features. Instead, organize it logically, by subtopics. Address the +questions that a user will ask when thinking about the job that the +program does. Don't just tell the reader what each feature can do--say +what jobs it is good for, and show how to use it for those jobs. +Explain what is recommended usage, and what kinds of usage users should +avoid. + + In general, a GNU manual should serve both as tutorial and reference. +It should be set up for convenient access to each topic through Info, +and for reading straight through (appendixes aside). A GNU manual +should give a good introduction to a beginner reading through from the +start, and should also provide all the details that hackers want. The +Bison manual is a good example of this--please take a look at it to see +what we mean. + + That is not as hard as it first sounds. Arrange each chapter as a +logical breakdown of its topic, but order the sections, and write their +text, so that reading the chapter straight through makes sense. Do +likewise when structuring the book into chapters, and when structuring a +section into paragraphs. The watchword is, _at each point, address the +most fundamental and important issue raised by the preceding text._ + + If necessary, add extra chapters at the beginning of the manual which +are purely tutorial and cover the basics of the subject. These provide +the framework for a beginner to understand the rest of the manual. The +Bison manual provides a good example of how to do this. + + To serve as a reference, a manual should have an Index that list all +the functions, variables, options, and important concepts that are part +of the program. One combined Index should do for a short manual, but +sometimes for a complex package it is better to use multiple indices. +The Texinfo manual includes advice on preparing good index entries, see +*note Making Index Entries: (texinfo)Index Entries, and see *note +Defining the Entries of an Index: (texinfo)Indexing Commands. + + Don't use Unix man pages as a model for how to write GNU +documentation; most of them are terse, badly structured, and give +inadequate explanation of the underlying concepts. (There are, of +course, some exceptions.) Also, Unix man pages use a particular format +which is different from what we use in GNU manuals. + + Please include an email address in the manual for where to report +bugs _in the text of the manual_. + + Please do not use the term "pathname" that is used in Unix +documentation; use "file name" (two words) instead. We use the term +"path" only for search paths, which are lists of directory names. + + Please do not use the term "illegal" to refer to erroneous input to a +computer program. Please use "invalid" for this, and reserve the term +"illegal" for activities prohibited by law. + + Please do not write '()' after a function name just to indicate it is +a function. 'foo ()' is not a function, it is a function call with no +arguments. + + +File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation + +6.2 Doc Strings and Manuals +=========================== + +Some programming systems, such as Emacs, provide a documentation string +for each function, command or variable. You may be tempted to write a +reference manual by compiling the documentation strings and writing a +little additional text to go around them--but you must not do it. That +approach is a fundamental mistake. The text of well-written +documentation strings will be entirely wrong for a manual. + + A documentation string needs to stand alone--when it appears on the +screen, there will be no other text to introduce or explain it. +Meanwhile, it can be rather informal in style. + + The text describing a function or variable in a manual must not stand +alone; it appears in the context of a section or subsection. Other text +at the beginning of the section should explain some of the concepts, and +should often make some general points that apply to several functions or +variables. The previous descriptions of functions and variables in the +section will also have given information about the topic. A description +written to stand alone would repeat some of that information; this +redundancy looks bad. Meanwhile, the informality that is acceptable in +a documentation string is totally unacceptable in a manual. + + The only good way to use documentation strings in writing a good +manual is to use them as a source of information for writing good text. + + +File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation + +6.3 Manual Structure Details +============================ + +The title page of the manual should state the version of the programs or +packages documented in the manual. The Top node of the manual should +also contain this information. If the manual is changing more +frequently than or independent of the program, also state a version +number for the manual in both of these places. + + Each program documented in the manual should have a node named +'PROGRAM Invocation' or 'Invoking PROGRAM'. This node (together with +its subnodes, if any) should describe the program's command line +arguments and how to run it (the sort of information people would look +for in a man page). Start with an '@example' containing a template for +all the options and arguments that the program uses. + + Alternatively, put a menu item in some menu whose item name fits one +of the above patterns. This identifies the node which that item points +to as the node for this purpose, regardless of the node's actual name. + + The '--usage' feature of the Info reader looks for such a node or +menu item in order to find the relevant text, so it is essential for +every Texinfo file to have one. + + If one manual describes several programs, it should have such a node +for each program described in the manual. + + +File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation + +6.4 License for Manuals +======================= + +Please use the GNU Free Documentation License for all GNU manuals that +are more than a few pages long. Likewise for a collection of short +documents--you only need one copy of the GNU FDL for the whole +collection. For a single short document, you can use a very permissive +non-copyleft license, to avoid taking up space with a long license. + + See for more explanation +of how to employ the GFDL. + + Note that it is not obligatory to include a copy of the GNU GPL or +GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It +can be a good idea to include the program's license in a large manual; +in a short manual, whose size would be increased considerably by +including the program's license, it is probably better not to include +it. + + +File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation + +6.5 Manual Credits +================== + +Please credit the principal human writers of the manual as the authors, +on the title page of the manual. If a company sponsored the work, thank +the company in a suitable place in the manual, but do not cite the +company as an author. + + +File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation + +6.6 Printed Manuals +=================== + +The FSF publishes some GNU manuals in printed form. To encourage sales +of these manuals, the on-line versions of the manual should mention at +the very start that the printed manual is available and should point at +information for getting it--for instance, with a link to the page +. This should not be included in +the printed manual, though, because there it is redundant. + + It is also useful to explain in the on-line forms of the manual how +the user can print out the manual from the sources. + + +File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation + +6.7 The NEWS File +================= + +In addition to its manual, the package should have a file named 'NEWS' +which contains a list of user-visible changes worth mentioning. In each +new release, add items to the front of the file and identify the version +they pertain to. Don't discard old items; leave them in the file after +the newer items. This way, a user upgrading from any previous version +can see what is new. + + If the 'NEWS' file gets very long, move some of the older items into +a file named 'ONEWS' and put a note at the end referring the user to +that file. + + +File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation + +6.8 Change Logs +=============== + +Keep a change log to describe all the changes made to program source +files. The purpose of this is so that people investigating bugs in the +future will know about the changes that might have introduced the bug. +Often a new bug can be found by looking at what was recently changed. +More importantly, change logs can help you eliminate conceptual +inconsistencies between different parts of a program, by giving you a +history of how the conflicting concepts arose and who they came from. + +* Menu: + +* Change Log Concepts:: +* Style of Change Logs:: +* Simple Changes:: +* Conditional Changes:: +* Indicating the Part Changed:: + + +File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs + +6.8.1 Change Log Concepts +------------------------- + +You can think of the change log as a conceptual "undo list" which +explains how earlier versions were different from the current version. +People can see the current version; they don't need the change log to +tell them what is in it. What they want from a change log is a clear +explanation of how the earlier version differed. + + The change log file is normally called 'ChangeLog' and covers an +entire directory. Each directory can have its own change log, or a +directory can use the change log of its parent directory--it's up to +you. + + Another alternative is to record change log information with a +version control system such as RCS or CVS. This can be converted +automatically to a 'ChangeLog' file using 'rcs2log'; in Emacs, the +command 'C-x v a' ('vc-update-change-log') does the job. + + There's no need to describe the full purpose of the changes or how +they work together. However, sometimes it is useful to write one line +to describe the overall purpose of a change or a batch of changes. If +you think that a change calls for explanation, you're probably right. +Please do explain it--but please put the full explanation in comments in +the code, where people will see it whenever they see the code. For +example, "New function" is enough for the change log when you add a +function, because there should be a comment before the function +definition to explain what it does. + + In the past, we recommended not mentioning changes in non-software +files (manuals, help files, etc.) in change logs. However, we've been +advised that it is a good idea to include them, for the sake of +copyright records. + + The easiest way to add an entry to 'ChangeLog' is with the Emacs +command 'M-x add-change-log-entry'. An entry should have an asterisk, +the name of the changed file, and then in parentheses the name of the +changed functions, variables or whatever, followed by a colon. Then +describe the changes you made to that function or variable. + + +File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs + +6.8.2 Style of Change Logs +-------------------------- + +Here are some simple examples of change log entries, starting with the +header line that says who made the change and when it was installed, +followed by descriptions of specific changes. (These examples are drawn +from Emacs and GCC.) + + 1998-08-17 Richard Stallman + + * register.el (insert-register): Return nil. + (jump-to-register): Likewise. + + * sort.el (sort-subr): Return nil. + + * tex-mode.el (tex-bibtex-file, tex-file, tex-region): + Restart the tex shell if process is gone or stopped. + (tex-shell-running): New function. + + * expr.c (store_one_arg): Round size up for move_block_to_reg. + (expand_call): Round up when emitting USE insns. + * stmt.c (assign_parms): Round size up for move_block_from_reg. + + It's important to name the changed function or variable in full. +Don't abbreviate function or variable names, and don't combine them. +Subsequent maintainers will often search for a function name to find all +the change log entries that pertain to it; if you abbreviate the name, +they won't find it when they search. + + For example, some people are tempted to abbreviate groups of function +names by writing '* register.el ({insert,jump-to}-register)'; this is +not a good idea, since searching for 'jump-to-register' or +'insert-register' would not find that entry. + + Separate unrelated change log entries with blank lines. When two +entries represent parts of the same change, so that they work together, +then don't put blank lines between them. Then you can omit the file +name and the asterisk when successive entries are in the same file. + + Break long lists of function names by closing continued lines with +')', rather than ',', and opening the continuation with '(' as in this +example: + + * keyboard.c (menu_bar_items, tool_bar_items) + (Fexecute_extended_command): Deal with `keymap' property. + + When you install someone else's changes, put the contributor's name +in the change log entry rather than in the text of the entry. In other +words, write this: + + 2002-07-14 John Doe + + * sewing.c: Make it sew. + +rather than this: + + 2002-07-14 Usual Maintainer + + * sewing.c: Make it sew. Patch by jdoe@gnu.org. + + As for the date, that should be the date you applied the change. + + +File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs + +6.8.3 Simple Changes +-------------------- + +Certain simple kinds of changes don't need much detail in the change +log. + + When you change the calling sequence of a function in a simple +fashion, and you change all the callers of the function to use the new +calling sequence, there is no need to make individual entries for all +the callers that you changed. Just write in the entry for the function +being called, "All callers changed"--like this: + + * keyboard.c (Fcommand_execute): New arg SPECIAL. + All callers changed. + + When you change just comments or doc strings, it is enough to write +an entry for the file, without mentioning the functions. Just "Doc +fixes" is enough for the change log. + + There's no technical need to make change log entries for +documentation files. This is because documentation is not susceptible +to bugs that are hard to fix. Documentation does not consist of parts +that must interact in a precisely engineered fashion. To correct an +error, you need not know the history of the erroneous passage; it is +enough to compare what the documentation says with the way the program +actually works. + + However, you should keep change logs for documentation files when the +project gets copyright assignments from its contributors, so as to make +the records of authorship more accurate. + + +File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs + +6.8.4 Conditional Changes +------------------------- + +C programs often contain compile-time '#if' conditionals. Many changes +are conditional; sometimes you add a new definition which is entirely +contained in a conditional. It is very useful to indicate in the change +log the conditions for which the change applies. + + Our convention for indicating conditional changes is to use square +brackets around the name of the condition. + + Here is a simple example, describing a change which is conditional +but does not have a function or entity name associated with it: + + * xterm.c [SOLARIS2]: Include string.h. + + Here is an entry describing a new definition which is entirely +conditional. This new definition for the macro 'FRAME_WINDOW_P' is used +only when 'HAVE_X_WINDOWS' is defined: + + * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined. + + Here is an entry for a change within the function 'init_display', +whose definition as a whole is unconditional, but the changes themselves +are contained in a '#ifdef HAVE_LIBNCURSES' conditional: + + * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent. + + Here is an entry for a change that takes affect only when a certain +macro is _not_ defined: + + (gethostname) [!HAVE_SOCKETS]: Replace with winsock version. + + +File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs + +6.8.5 Indicating the Part Changed +--------------------------------- + +Indicate the part of a function which changed by using angle brackets +enclosing an indication of what the changed part does. Here is an entry +for a change in the part of the function 'sh-while-getopts' that deals +with 'sh' commands: + + * progmodes/sh-script.el (sh-while-getopts) : Handle case that + user-specified option string is empty. + + +File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation + +6.9 Man Pages +============= + +In the GNU project, man pages are secondary. It is not necessary or +expected for every GNU program to have a man page, but some of them do. +It's your choice whether to include a man page in your program. + + When you make this decision, consider that supporting a man page +requires continual effort each time the program is changed. The time +you spend on the man page is time taken away from more useful work. + + For a simple program which changes little, updating the man page may +be a small job. Then there is little reason not to include a man page, +if you have one. + + For a large program that changes a great deal, updating a man page +may be a substantial burden. If a user offers to donate a man page, you +may find this gift costly to accept. It may be better to refuse the man +page unless the same person agrees to take full responsibility for +maintaining it--so that you can wash your hands of it entirely. If this +volunteer later ceases to do the job, then don't feel obliged to pick it +up yourself; it may be better to withdraw the man page from the +distribution until someone else agrees to update it. + + When a program changes only a little, you may feel that the +discrepancies are small enough that the man page remains useful without +updating. If so, put a prominent note near the beginning of the man +page explaining that you don't maintain it and that the Texinfo manual +is more authoritative. The note should say how to access the Texinfo +documentation. + + Be sure that man pages include a copyright statement and free +license. The simple all-permissive license is appropriate for simple +man pages (*note (maintain)License Notices for Other Files::). + + For long man pages, with enough explanation and documentation that +they can be considered true manuals, use the GFDL (*note License for +Manuals::). + + Finally, the GNU help2man program +() is one way to automate +generation of a man page, in this case from '--help' output. This is +sufficient in many cases. + + +File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation + +6.10 Reading other Manuals +========================== + +There may be non-free books or documentation files that describe the +program you are documenting. + + It is ok to use these documents for reference, just as the author of +a new algebra textbook can read other books on algebra. A large portion +of any non-fiction book consists of facts, in this case facts about how +a certain program works, and these facts are necessarily the same for +everyone who writes about the subject. But be careful not to copy your +outline structure, wording, tables or examples from preexisting non-free +documentation. Copying from free documentation may be ok; please check +with the FSF about the individual case. + + +File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top + +7 The Release Process +********************* + +Making a release is more than just bundling up your source files in a +tar file and putting it up for FTP. You should set up your software so +that it can be configured to run on a variety of systems. Your Makefile +should conform to the GNU standards described below, and your directory +layout should also conform to the standards discussed below. Doing so +makes it easy to include your package into the larger framework of all +GNU software. + +* Menu: + +* Configuration:: How configuration of GNU packages should work. +* Makefile Conventions:: Makefile conventions. +* Releases:: Making releases + + +File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases + +7.1 How Configuration Should Work +================================= + +Each GNU distribution should come with a shell script named 'configure'. +This script is given arguments which describe the kind of machine and +system you want to compile the program for. The 'configure' script must +record the configuration options so that they affect compilation. + + The description here is the specification of the interface for the +'configure' script in GNU packages. Many packages implement it using +GNU Autoconf (*note Introduction: (autoconf)Top.) and/or GNU Automake +(*note Introduction: (automake)Top.), but you do not have to use these +tools. You can implement it any way you like; for instance, by making +'configure' be a wrapper around a completely different configuration +system. + + Another way for the 'configure' script to operate is to make a link +from a standard name such as 'config.h' to the proper configuration file +for the chosen system. If you use this technique, the distribution +should _not_ contain a file named 'config.h'. This is so that people +won't be able to build the program without configuring it first. + + Another thing that 'configure' can do is to edit the Makefile. If +you do this, the distribution should _not_ contain a file named +'Makefile'. Instead, it should include a file 'Makefile.in' which +contains the input used for editing. Once again, this is so that people +won't be able to build the program without configuring it first. + + If 'configure' does write the 'Makefile', then 'Makefile' should have +a target named 'Makefile' which causes 'configure' to be rerun, setting +up the same configuration that was set up last time. The files that +'configure' reads should be listed as dependencies of 'Makefile'. + + All the files which are output from the 'configure' script should +have comments at the beginning explaining that they were generated +automatically using 'configure'. This is so that users won't think of +trying to edit them by hand. + + The 'configure' script should write a file named 'config.status' +which describes which configuration options were specified when the +program was last configured. This file should be a shell script which, +if run, will recreate the same configuration. + + The 'configure' script should accept an option of the form +'--srcdir=DIRNAME' to specify the directory where sources are found (if +it is not the current directory). This makes it possible to build the +program in a separate directory, so that the actual source directory is +not modified. + + If the user does not specify '--srcdir', then 'configure' should +check both '.' and '..' to see if it can find the sources. If it finds +the sources in one of these places, it should use them from there. +Otherwise, it should report that it cannot find the sources, and should +exit with nonzero status. + + Usually the easy way to support '--srcdir' is by editing a definition +of 'VPATH' into the Makefile. Some rules may need to refer explicitly +to the specified source directory. To make this possible, 'configure' +can add to the Makefile a variable named 'srcdir' whose value is +precisely the specified directory. + + In addition, the 'configure' script should take options corresponding +to most of the standard directory variables (*note Directory +Variables::). Here is the list: + + --prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir + --sharedstatedir --localstatedir --libdir --includedir --oldincludedir + --datarootdir --datadir --infodir --localedir --mandir --docdir + --htmldir --dvidir --pdfdir --psdir + + The 'configure' script should also take an argument which specifies +the type of system to build the program for. This argument should look +like this: + + CPU-COMPANY-SYSTEM + + For example, an Athlon-based GNU/Linux system might be +'i686-pc-linux-gnu'. + + The 'configure' script needs to be able to decode all plausible +alternatives for how to describe a machine. Thus, 'athlon-pc-gnu/linux' +would be a valid alias. There is a shell script called 'config.sub' +(http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD) +that you can use as a subroutine to validate system types and +canonicalize aliases. + + The 'configure' script should also take the option +'--build=BUILDTYPE', which should be equivalent to a plain BUILDTYPE +argument. For example, 'configure --build=i686-pc-linux-gnu' is +equivalent to 'configure i686-pc-linux-gnu'. When the build type is not +specified by an option or argument, the 'configure' script should +normally guess it using the shell script 'config.guess' +(http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD). + + Other options are permitted to specify in more detail the software or +hardware present on the machine, to include or exclude optional parts of +the package, or to adjust the name of some tools or arguments to them: + +'--enable-FEATURE[=PARAMETER]' + Configure the package to build and install an optional user-level + facility called FEATURE. This allows users to choose which + optional features to include. Giving an optional PARAMETER of 'no' + should omit FEATURE, if it is built by default. + + No '--enable' option should *ever* cause one feature to replace + another. No '--enable' option should ever substitute one useful + behavior for another useful behavior. The only proper use for + '--enable' is for questions of whether to build part of the program + or exclude it. + +'--with-PACKAGE' + The package PACKAGE will be installed, so configure this package to + work with PACKAGE. + + Possible values of PACKAGE include 'gnu-as' (or 'gas'), 'gnu-ld', + 'gnu-libc', 'gdb', 'x', and 'x-toolkit'. + + Do not use a '--with' option to specify the file name to use to + find certain files. That is outside the scope of what '--with' + options are for. + +'VARIABLE=VALUE' + Set the value of the variable VARIABLE to VALUE. This is used to + override the default values of commands or arguments in the build + process. For example, the user could issue 'configure CFLAGS=-g + CXXFLAGS=-g' to build with debugging information and without the + default optimization. + + Specifying variables as arguments to 'configure', like this: + ./configure CC=gcc + is preferable to setting them in environment variables: + CC=gcc ./configure + as it helps to recreate the same configuration later with + 'config.status'. However, both methods should be supported. + + All 'configure' scripts should accept all of the "detail" options and +the variable settings, whether or not they make any difference to the +particular package at hand. In particular, they should accept any +option that starts with '--with-' or '--enable-'. This is so users will +be able to configure an entire GNU source tree at once with a single set +of options. + + You will note that the categories '--with-' and '--enable-' are +narrow: they *do not* provide a place for any sort of option you might +think of. That is deliberate. We want to limit the possible +configuration options in GNU software. We do not want GNU programs to +have idiosyncratic configuration options. + + Packages that perform part of the compilation process may support +cross-compilation. In such a case, the host and target machines for the +program may be different. + + The 'configure' script should normally treat the specified type of +system as both the host and the target, thus producing a program which +works for the same type of machine that it runs on. + + To compile a program to run on a host type that differs from the +build type, use the configure option '--host=HOSTTYPE', where HOSTTYPE +uses the same syntax as BUILDTYPE. The host type normally defaults to +the build type. + + To configure a cross-compiler, cross-assembler, or what have you, you +should specify a target different from the host, using the configure +option '--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as +for the host type. So the command would look like this: + + ./configure --host=HOSTTYPE --target=TARGETTYPE + + The target type normally defaults to the host type. Programs for +which cross-operation is not meaningful need not accept the '--target' +option, because configuring an entire operating system for +cross-operation is not a meaningful operation. + + Some programs have ways of configuring themselves automatically. If +your program is set up to do this, your 'configure' script can simply +ignore most of its arguments. + + +File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases + +7.2 Makefile Conventions +======================== + +This node describes conventions for writing the Makefiles for GNU +programs. Using Automake will help you write a Makefile that follows +these conventions. + +* Menu: + +* Makefile Basics:: General conventions for Makefiles. +* Utilities in Makefiles:: Utilities to be used in Makefiles. +* Command Variables:: Variables for specifying commands. +* DESTDIR:: Supporting staged installs. +* Directory Variables:: Variables for installation directories. +* Standard Targets:: Standard targets for users. +* Install Command Categories:: Three categories of commands in the 'install' + rule: normal, pre-install and post-install. + + +File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions + +7.2.1 General Conventions for Makefiles +--------------------------------------- + +Every Makefile should contain this line: + + SHELL = /bin/sh + +to avoid trouble on systems where the 'SHELL' variable might be +inherited from the environment. (This is never a problem with GNU +'make'.) + + Different 'make' programs have incompatible suffix lists and implicit +rules, and this sometimes creates confusion or misbehavior. So it is a +good idea to set the suffix list explicitly using only the suffixes you +need in the particular Makefile, like this: + + .SUFFIXES: + .SUFFIXES: .c .o + +The first line clears out the suffix list, the second introduces all +suffixes which may be subject to implicit rules in this Makefile. + + Don't assume that '.' is in the path for command execution. When you +need to run programs that are a part of your package during the make, +please make sure that it uses './' if the program is built as part of +the make or '$(srcdir)/' if the file is an unchanging part of the source +code. Without one of these prefixes, the current search path is used. + + The distinction between './' (the "build directory") and '$(srcdir)/' +(the "source directory") is important because users can build in a +separate directory using the '--srcdir' option to 'configure'. A rule +of the form: + + foo.1 : foo.man sedscript + sed -e sedscript foo.man > foo.1 + +will fail when the build directory is not the source directory, because +'foo.man' and 'sedscript' are in the source directory. + + When using GNU 'make', relying on 'VPATH' to find the source file +will work in the case where there is a single dependency file, since the +'make' automatic variable '$<' will represent the source file wherever +it is. (Many versions of 'make' set '$<' only in implicit rules.) A +Makefile target like + + foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o + +should instead be written as + + foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@ + +in order to allow 'VPATH' to work correctly. When the target has +multiple dependencies, using an explicit '$(srcdir)' is the easiest way +to make the rule work well. For example, the target above for 'foo.1' +is best written as: + + foo.1 : foo.man sedscript + sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@ + + GNU distributions usually contain some files which are not source +files--for example, Info files, and the output from Autoconf, Automake, +Bison or Flex. Since these files normally appear in the source +directory, they should always appear in the source directory, not in the +build directory. So Makefile rules to update them should put the +updated files in the source directory. + + However, if a file does not appear in the distribution, then the +Makefile should not put it in the source directory, because building a +program in ordinary circumstances should not modify the source directory +in any way. + + Try to make the build and installation targets, at least (and all +their subtargets) work correctly with a parallel 'make'. + + +File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions + +7.2.2 Utilities in Makefiles +---------------------------- + +Write the Makefile commands (and any shell scripts, such as 'configure') +to run in 'sh', not in 'csh'. Don't use any special features of 'ksh' +or 'bash'. + + The 'configure' script and the Makefile rules for building and +installation should not use any utilities directly except these: + + cat cmp cp diff echo egrep expr false grep install-info + ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true + + The compression program 'gzip' can be used in the 'dist' rule. + + Stick to the generally supported options for these programs. For +example, don't use 'mkdir -p', convenient as it may be, because most +systems don't support it. + + It is a good idea to avoid creating symbolic links in makefiles, +since a few systems don't support them. + + The Makefile rules for building and installation can also use +compilers and related programs, but should do so via 'make' variables so +that the user can substitute alternatives. Here are some of the +programs we mean: + + ar bison cc flex install ld ldconfig lex + make makeinfo ranlib texi2dvi yacc + + Use the following 'make' variables to run those programs: + + $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) + $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) + + When you use 'ranlib' or 'ldconfig', you should make sure nothing bad +happens if the system does not have the program in question. Arrange to +ignore an error from that command, and print a message before the +command to tell the user that failure of this command does not mean a +problem. (The Autoconf 'AC_PROG_RANLIB' macro can help with this.) + + If you use symbolic links, you should implement a fallback for +systems that don't have symbolic links. + + Additional utilities that can be used via Make variables are: + + chgrp chmod chown mknod + + It is ok to use other utilities in Makefile portions (or scripts) +intended only for particular systems where you know those utilities +exist. + + +File: standards.info, Node: Command Variables, Next: DESTDIR, Prev: Utilities in Makefiles, Up: Makefile Conventions + +7.2.3 Variables for Specifying Commands +--------------------------------------- + +Makefiles should provide variables for overriding certain commands, +options, and so on. + + In particular, you should run most utility programs via variables. +Thus, if you use Bison, have a variable named 'BISON' whose default +value is set with 'BISON = bison', and refer to it with '$(BISON)' +whenever you need to use Bison. + + File management utilities such as 'ln', 'rm', 'mv', and so on, need +not be referred to through variables in this way, since users don't need +to replace them with other programs. + + Each program-name variable should come with an options variable that +is used to supply options to the program. Append 'FLAGS' to the +program-name variable name to get the options variable name--for +example, 'BISONFLAGS'. (The names 'CFLAGS' for the C compiler, 'YFLAGS' +for yacc, and 'LFLAGS' for lex, are exceptions to this rule, but we keep +them because they are standard.) Use 'CPPFLAGS' in any compilation +command that runs the preprocessor, and use 'LDFLAGS' in any compilation +command that does linking as well as in any direct use of 'ld'. + + If there are C compiler options that _must_ be used for proper +compilation of certain files, do not include them in 'CFLAGS'. Users +expect to be able to specify 'CFLAGS' freely themselves. Instead, +arrange to pass the necessary options to the C compiler independently of +'CFLAGS', by writing them explicitly in the compilation commands or by +defining an implicit rule, like this: + + CFLAGS = -g + ALL_CFLAGS = -I. $(CFLAGS) + .c.o: + $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< + + Do include the '-g' option in 'CFLAGS', because that is not +_required_ for proper compilation. You can consider it a default that +is only recommended. If the package is set up so that it is compiled +with GCC by default, then you might as well include '-O' in the default +value of 'CFLAGS' as well. + + Put 'CFLAGS' last in the compilation command, after other variables +containing compiler options, so the user can use 'CFLAGS' to override +the others. + + 'CFLAGS' should be used in every invocation of the C compiler, both +those which do compilation and those which do linking. + + Every Makefile should define the variable 'INSTALL', which is the +basic command for installing a file into the system. + + Every Makefile should also define the variables 'INSTALL_PROGRAM' and +'INSTALL_DATA'. (The default for 'INSTALL_PROGRAM' should be +'$(INSTALL)'; the default for 'INSTALL_DATA' should be '${INSTALL} -m +644'.) Then it should use those variables as the commands for actual +installation, for executables and non-executables respectively. Minimal +use of these variables is as follows: + + $(INSTALL_PROGRAM) foo $(bindir)/foo + $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a + + However, it is preferable to support a 'DESTDIR' prefix on the target +files, as explained in the next section. + +Always use a file name, not a directory name, as the second argument of +the installation commands. Use a separate command for each file to be +installed. + + +File: standards.info, Node: DESTDIR, Next: Directory Variables, Prev: Command Variables, Up: Makefile Conventions + +7.2.4 'DESTDIR': support for staged installs +-------------------------------------------- + +'DESTDIR' is a variable prepended to each installed target file, like +this: + + $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo + $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a + + The 'DESTDIR' variable is specified by the user on the 'make' command +line. For example: + + make DESTDIR=/tmp/stage install + +'DESTDIR' should be supported only in the 'install*' and 'uninstall*' +targets, as those are the only targets where it is useful. + + If your installation step would normally install '/usr/local/bin/foo' +and '/usr/local/lib/libfoo.a', then an installation invoked as in the +example above would install '/tmp/stage/usr/local/bin/foo' and +'/tmp/stage/usr/local/lib/libfoo.a' instead. + + Prepending the variable 'DESTDIR' to each target in this way provides +for "staged installs", where the installed files are not placed directly +into their expected location but are instead copied into a temporary +location ('DESTDIR'). However, installed files maintain their relative +directory structure and any embedded file names will not be modified. + + You should not set the value of 'DESTDIR' in your 'Makefile' at all; +then the files are installed into their expected locations by default. +Also, specifying 'DESTDIR' should not change the operation of the +software in any way, so its value should not be included in any file +contents. + + 'DESTDIR' support is commonly used in package creation. It is also +helpful to users who want to understand what a given package will +install where, and to allow users who don't normally have permissions to +install into protected areas to build and install before gaining those +permissions. Finally, it can be useful with tools such as 'stow', where +code is installed in one place but made to appear to be installed +somewhere else using symbolic links or special mount operations. So, we +strongly recommend GNU packages support 'DESTDIR', though it is not an +absolute requirement. + + +File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: DESTDIR, Up: Makefile Conventions + +7.2.5 Variables for Installation Directories +-------------------------------------------- + +Installation directories should always be named by variables, so it is +easy to install in a nonstandard place. The standard names for these +variables and the values they should have in GNU packages are described +below. They are based on a standard file system layout; variants of it +are used in GNU/Linux and other modern operating systems. + + Installers are expected to override these values when calling 'make' +(e.g., 'make prefix=/usr install' or 'configure' (e.g., 'configure +--prefix=/usr'). GNU packages should not try to guess which value +should be appropriate for these variables on the system they are being +installed onto: use the default settings specified here so that all GNU +packages behave identically, allowing the installer to achieve any +desired layout. + + These first two variables set the root for the installation. All the +other installation directories should be subdirectories of one of these +two, and nothing should be directly installed into these two +directories. + +'prefix' + A prefix used in constructing the default values of the variables + listed below. The default value of 'prefix' should be + '/usr/local'. When building the complete GNU system, the prefix + will be empty and '/usr' will be a symbolic link to '/'. (If you + are using Autoconf, write it as '@prefix@'.) + + Running 'make install' with a different value of 'prefix' from the + one used to build the program should _not_ recompile the program. + +'exec_prefix' + A prefix used in constructing the default values of some of the + variables listed below. The default value of 'exec_prefix' should + be '$(prefix)'. (If you are using Autoconf, write it as + '@exec_prefix@'.) + + Generally, '$(exec_prefix)' is used for directories that contain + machine-specific files (such as executables and subroutine + libraries), while '$(prefix)' is used directly for other + directories. + + Running 'make install' with a different value of 'exec_prefix' from + the one used to build the program should _not_ recompile the + program. + + Executable programs are installed in one of the following +directories. + +'bindir' + The directory for installing executable programs that users can + run. This should normally be '/usr/local/bin', but write it as + '$(exec_prefix)/bin'. (If you are using Autoconf, write it as + '@bindir@'.) + +'sbindir' + The directory for installing executable programs that can be run + from the shell, but are only generally useful to system + administrators. This should normally be '/usr/local/sbin', but + write it as '$(exec_prefix)/sbin'. (If you are using Autoconf, + write it as '@sbindir@'.) + +'libexecdir' + The directory for installing executable programs to be run by other + programs rather than by users. This directory should normally be + '/usr/local/libexec', but write it as '$(exec_prefix)/libexec'. + (If you are using Autoconf, write it as '@libexecdir@'.) + + The definition of 'libexecdir' is the same for all packages, so you + should install your data in a subdirectory thereof. Most packages + install their data under '$(libexecdir)/PACKAGE-NAME/', possibly + within additional subdirectories thereof, such as + '$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'. + + Data files used by the program during its execution are divided into +categories in two ways. + + * Some files are normally modified by programs; others are never + normally modified (though users may edit some of these). + + * Some files are architecture-independent and can be shared by all + machines at a site; some are architecture-dependent and can be + shared only by machines of the same kind and operating system; + others may never be shared between two machines. + + This makes for six different possibilities. However, we want to +discourage the use of architecture-dependent files, aside from object +files and libraries. It is much cleaner to make other data files +architecture-independent, and it is generally not hard. + + Here are the variables Makefiles should use to specify directories to +put these various kinds of files in: + +'datarootdir' + The root of the directory tree for read-only + architecture-independent data files. This should normally be + '/usr/local/share', but write it as '$(prefix)/share'. (If you are + using Autoconf, write it as '@datarootdir@'.) 'datadir''s default + value is based on this variable; so are 'infodir', 'mandir', and + others. + +'datadir' + The directory for installing idiosyncratic read-only + architecture-independent data files for this program. This is + usually the same place as 'datarootdir', but we use the two + separate variables so that you can move these program-specific + files without altering the location for Info files, man pages, etc. + + This should normally be '/usr/local/share', but write it as + '$(datarootdir)'. (If you are using Autoconf, write it as + '@datadir@'.) + + The definition of 'datadir' is the same for all packages, so you + should install your data in a subdirectory thereof. Most packages + install their data under '$(datadir)/PACKAGE-NAME/'. + +'sysconfdir' + The directory for installing read-only data files that pertain to a + single machine-that is to say, files for configuring a host. + Mailer and network configuration files, '/etc/passwd', and so forth + belong here. All the files in this directory should be ordinary + ASCII text files. This directory should normally be + '/usr/local/etc', but write it as '$(prefix)/etc'. (If you are + using Autoconf, write it as '@sysconfdir@'.) + + Do not install executables here in this directory (they probably + belong in '$(libexecdir)' or '$(sbindir)'). Also do not install + files that are modified in the normal course of their use (programs + whose purpose is to change the configuration of the system + excluded). Those probably belong in '$(localstatedir)'. + +'sharedstatedir' + The directory for installing architecture-independent data files + which the programs modify while they run. This should normally be + '/usr/local/com', but write it as '$(prefix)/com'. (If you are + using Autoconf, write it as '@sharedstatedir@'.) + +'localstatedir' + The directory for installing data files which the programs modify + while they run, and that pertain to one specific machine. Users + should never need to modify files in this directory to configure + the package's operation; put such configuration information in + separate files that go in '$(datadir)' or '$(sysconfdir)'. + '$(localstatedir)' should normally be '/usr/local/var', but write + it as '$(prefix)/var'. (If you are using Autoconf, write it as + '@localstatedir@'.) + + These variables specify the directory for installing certain specific +types of files, if your program has them. Every GNU package should have +Info files, so every program needs 'infodir', but not all need 'libdir' +or 'lispdir'. + +'includedir' + The directory for installing header files to be included by user + programs with the C '#include' preprocessor directive. This should + normally be '/usr/local/include', but write it as + '$(prefix)/include'. (If you are using Autoconf, write it as + '@includedir@'.) + + Most compilers other than GCC do not look for header files in + directory '/usr/local/include'. So installing the header files + this way is only useful with GCC. Sometimes this is not a problem + because some libraries are only really intended to work with GCC. + But some libraries are intended to work with other compilers. They + should install their header files in two places, one specified by + 'includedir' and one specified by 'oldincludedir'. + +'oldincludedir' + The directory for installing '#include' header files for use with + compilers other than GCC. This should normally be '/usr/include'. + (If you are using Autoconf, you can write it as '@oldincludedir@'.) + + The Makefile commands should check whether the value of + 'oldincludedir' is empty. If it is, they should not try to use it; + they should cancel the second installation of the header files. + + A package should not replace an existing header in this directory + unless the header came from the same package. Thus, if your Foo + package provides a header file 'foo.h', then it should install the + header file in the 'oldincludedir' directory if either (1) there is + no 'foo.h' there or (2) the 'foo.h' that exists came from the Foo + package. + + To tell whether 'foo.h' came from the Foo package, put a magic + string in the file--part of a comment--and 'grep' for that string. + +'docdir' + The directory for installing documentation files (other than Info) + for this package. By default, it should be + '/usr/local/share/doc/YOURPKG', but it should be written as + '$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write it + as '@docdir@'.) The YOURPKG subdirectory, which may include a + version number, prevents collisions among files with common names, + such as 'README'. + +'infodir' + The directory for installing the Info files for this package. By + default, it should be '/usr/local/share/info', but it should be + written as '$(datarootdir)/info'. (If you are using Autoconf, + write it as '@infodir@'.) 'infodir' is separate from 'docdir' for + compatibility with existing practice. + +'htmldir' +'dvidir' +'pdfdir' +'psdir' + Directories for installing documentation files in the particular + format. They should all be set to '$(docdir)' by default. (If you + are using Autoconf, write them as '@htmldir@', '@dvidir@', etc.) + Packages which supply several translations of their documentation + should install them in '$(htmldir)/'LL, '$(pdfdir)/'LL, etc. where + LL is a locale abbreviation such as 'en' or 'pt_BR'. + +'libdir' + The directory for object files and libraries of object code. Do + not install executables here, they probably ought to go in + '$(libexecdir)' instead. The value of 'libdir' should normally be + '/usr/local/lib', but write it as '$(exec_prefix)/lib'. (If you + are using Autoconf, write it as '@libdir@'.) + +'lispdir' + The directory for installing any Emacs Lisp files in this package. + By default, it should be '/usr/local/share/emacs/site-lisp', but it + should be written as '$(datarootdir)/emacs/site-lisp'. + + If you are using Autoconf, write the default as '@lispdir@'. In + order to make '@lispdir@' work, you need the following lines in + your 'configure.in' file: + + lispdir='${datarootdir}/emacs/site-lisp' + AC_SUBST(lispdir) + +'localedir' + The directory for installing locale-specific message catalogs for + this package. By default, it should be '/usr/local/share/locale', + but it should be written as '$(datarootdir)/locale'. (If you are + using Autoconf, write it as '@localedir@'.) This directory usually + has a subdirectory per locale. + + Unix-style man pages are installed in one of the following: + +'mandir' + The top-level directory for installing the man pages (if any) for + this package. It will normally be '/usr/local/share/man', but you + should write it as '$(datarootdir)/man'. (If you are using + Autoconf, write it as '@mandir@'.) + +'man1dir' + The directory for installing section 1 man pages. Write it as + '$(mandir)/man1'. +'man2dir' + The directory for installing section 2 man pages. Write it as + '$(mandir)/man2' +'...' + + *Don't make the primary documentation for any GNU software be a man + page. Write a manual in Texinfo instead. Man pages are just for + the sake of people running GNU software on Unix, which is a + secondary application only.* + +'manext' + The file name extension for the installed man page. This should + contain a period followed by the appropriate digit; it should + normally be '.1'. + +'man1ext' + The file name extension for installed section 1 man pages. +'man2ext' + The file name extension for installed section 2 man pages. +'...' + Use these names instead of 'manext' if the package needs to install + man pages in more than one section of the manual. + + And finally, you should set the following variable: + +'srcdir' + The directory for the sources being compiled. The value of this + variable is normally inserted by the 'configure' shell script. (If + you are using Autoconf, use 'srcdir = @srcdir@'.) + + For example: + + # Common prefix for installation directories. + # NOTE: This directory must exist when you start the install. + prefix = /usr/local + datarootdir = $(prefix)/share + datadir = $(datarootdir) + exec_prefix = $(prefix) + # Where to put the executable for the command `gcc'. + bindir = $(exec_prefix)/bin + # Where to put the directories used by the compiler. + libexecdir = $(exec_prefix)/libexec + # Where to put the Info files. + infodir = $(datarootdir)/info + + If your program installs a large number of files into one of the +standard user-specified directories, it might be useful to group them +into a subdirectory particular to that program. If you do this, you +should write the 'install' rule to create these subdirectories. + + Do not expect the user to include the subdirectory name in the value +of any of the variables listed above. The idea of having a uniform set +of variable names for installation directories is to enable the user to +specify the exact same values for several different GNU packages. In +order for this to be useful, all the packages must be designed so that +they will work sensibly when the user does so. + + At times, not all of these variables may be implemented in the +current release of Autoconf and/or Automake; but as of Autoconf 2.60, we +believe all of them are. When any are missing, the descriptions here +serve as specifications for what Autoconf will implement. As a +programmer, you can either use a development version of Autoconf or +avoid using these variables until a stable release is made which +supports them. + + +File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions + +7.2.6 Standard Targets for Users +-------------------------------- + +All GNU programs should have the following targets in their Makefiles: + +'all' + Compile the entire program. This should be the default target. + This target need not rebuild any documentation files; Info files + should normally be included in the distribution, and DVI (and other + documentation format) files should be made only when explicitly + asked for. + + By default, the Make rules should compile and link with '-g', so + that executable programs have debugging symbols. Users who don't + mind being helpless can strip the executables later if they wish. + +'install' + Compile the program and copy the executables, libraries, and so on + to the file names where they should reside for actual use. If + there is a simple test to verify that a program is properly + installed, this target should run that test. + + Do not strip executables when installing them. Devil-may-care + users can use the 'install-strip' target to do that. + + If possible, write the 'install' target rule so that it does not + modify anything in the directory where the program was built, + provided 'make all' has just been done. This is convenient for + building the program under one user name and installing it under + another. + + The commands should create all the directories in which files are + to be installed, if they don't already exist. This includes the + directories specified as the values of the variables 'prefix' and + 'exec_prefix', as well as all subdirectories that are needed. One + way to do this is by means of an 'installdirs' target as described + below. + + Use '-' before any command for installing a man page, so that + 'make' will ignore any errors. This is in case there are systems + that don't have the Unix man page documentation system installed. + + The way to install Info files is to copy them into '$(infodir)' + with '$(INSTALL_DATA)' (*note Command Variables::), and then run + the 'install-info' program if it is present. 'install-info' is a + program that edits the Info 'dir' file to add or update the menu + entry for the given Info file; it is part of the Texinfo package. + Here is a sample rule to install an Info file: + + $(DESTDIR)$(infodir)/foo.info: foo.info + $(POST_INSTALL) + # There may be a newer info file in . than in srcdir. + -if test -f foo.info; then d=.; \ + else d=$(srcdir); fi; \ + $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \ + # Run install-info only if it exists. + # Use `if' instead of just prepending `-' to the + # line so we notice real errors from install-info. + # We use `$(SHELL) -c' because some shells do not + # fail gracefully when there is an unknown command. + if $(SHELL) -c 'install-info --version' \ + >/dev/null 2>&1; then \ + install-info --dir-file=$(DESTDIR)$(infodir)/dir \ + $(DESTDIR)$(infodir)/foo.info; \ + else true; fi + + When writing the 'install' target, you must classify all the + commands into three categories: normal ones, "pre-installation" + commands and "post-installation" commands. *Note Install Command + Categories::. + +'install-html' +'install-dvi' +'install-pdf' +'install-ps' + These targets install documentation in formats other than Info; + they're intended to be called explicitly by the person installing + the package, if that format is desired. GNU prefers Info files, so + these must be installed by the 'install' target. + + When you have many documentation files to install, we recommend + that you avoid collisions and clutter by arranging for these + targets to install in subdirectories of the appropriate + installation directory, such as 'htmldir'. As one example, if your + package has multiple manuals, and you wish to install HTML + documentation with many files (such as the "split" mode output by + 'makeinfo --html'), you'll certainly want to use subdirectories, or + two nodes with the same name in different manuals will overwrite + each other. + + Please make these 'install-FORMAT' targets invoke the commands for + the FORMAT target, for example, by making FORMAT a dependency. + +'uninstall' + Delete all the installed files--the copies that the 'install' and + 'install-*' targets create. + + This rule should not modify the directories where compilation is + done, only the directories where files are installed. + + The uninstallation commands are divided into three categories, just + like the installation commands. *Note Install Command + Categories::. + +'install-strip' + Like 'install', but strip the executable files while installing + them. In simple cases, this target can use the 'install' target in + a simple way: + + install-strip: + $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ + install + + But if the package installs scripts as well as real executables, + the 'install-strip' target can't just refer to the 'install' + target; it has to strip the executables but not the scripts. + + 'install-strip' should not strip the executables in the build + directory which are being copied for installation. It should only + strip the copies that are installed. + + Normally we do not recommend stripping an executable unless you are + sure the program has no bugs. However, it can be reasonable to + install a stripped executable for actual execution while saving the + unstripped executable elsewhere in case there is a bug. + +'clean' + + Delete all files in the current directory that are normally created + by building the program. Also delete files in other directories if + they are created by this makefile. However, don't delete the files + that record the configuration. Also preserve files that could be + made by building, but normally aren't because the distribution + comes with them. There is no need to delete parent directories + that were created with 'mkdir -p', since they could have existed + anyway. + + Delete '.dvi' files here if they are not part of the distribution. + +'distclean' + Delete all files in the current directory (or created by this + makefile) that are created by configuring or building the program. + If you have unpacked the source and built the program without + creating any other files, 'make distclean' should leave only the + files that were in the distribution. However, there is no need to + delete parent directories that were created with 'mkdir -p', since + they could have existed anyway. + +'mostlyclean' + Like 'clean', but may refrain from deleting a few files that people + normally don't want to recompile. For example, the 'mostlyclean' + target for GCC does not delete 'libgcc.a', because recompiling it + is rarely necessary and takes a lot of time. + +'maintainer-clean' + Delete almost everything that can be reconstructed with this + Makefile. This typically includes everything deleted by + 'distclean', plus more: C source files produced by Bison, tags + tables, Info files, and so on. + + The reason we say "almost everything" is that running the command + 'make maintainer-clean' should not delete 'configure' even if + 'configure' can be remade using a rule in the Makefile. More + generally, 'make maintainer-clean' should not delete anything that + needs to exist in order to run 'configure' and then begin to build + the program. Also, there is no need to delete parent directories + that were created with 'mkdir -p', since they could have existed + anyway. These are the only exceptions; 'maintainer-clean' should + delete everything else that can be rebuilt. + + The 'maintainer-clean' target is intended to be used by a + maintainer of the package, not by ordinary users. You may need + special tools to reconstruct some of the files that 'make + maintainer-clean' deletes. Since these files are normally included + in the distribution, we don't take care to make them easy to + reconstruct. If you find you need to unpack the full distribution + again, don't blame us. + + To help make users aware of this, the commands for the special + 'maintainer-clean' target should start with these two: + + @echo 'This command is intended for maintainers to use; it' + @echo 'deletes files that may need special tools to rebuild.' + +'TAGS' + Update a tags table for this program. + +'info' + Generate any Info files needed. The best way to write the rules is + as follows: + + info: foo.info + + foo.info: foo.texi chap1.texi chap2.texi + $(MAKEINFO) $(srcdir)/foo.texi + + You must define the variable 'MAKEINFO' in the Makefile. It should + run the 'makeinfo' program, which is part of the Texinfo + distribution. + + Normally a GNU distribution comes with Info files, and that means + the Info files are present in the source directory. Therefore, the + Make rule for an info file should update it in the source + directory. When users build the package, ordinarily Make will not + update the Info files because they will already be up to date. + +'dvi' +'html' +'pdf' +'ps' + Generate documentation files in the given format. These targets + should always exist, but any or all can be a no-op if the given + output format cannot be generated. These targets should not be + dependencies of the 'all' target; the user must manually invoke + them. + + Here's an example rule for generating DVI files from Texinfo: + + dvi: foo.dvi + + foo.dvi: foo.texi chap1.texi chap2.texi + $(TEXI2DVI) $(srcdir)/foo.texi + + You must define the variable 'TEXI2DVI' in the Makefile. It should + run the program 'texi2dvi', which is part of the Texinfo + distribution.(1) Alternatively, write just the dependencies, and + allow GNU 'make' to provide the command. + + Here's another example, this one for generating HTML from Texinfo: + + html: foo.html + + foo.html: foo.texi chap1.texi chap2.texi + $(TEXI2HTML) $(srcdir)/foo.texi + + Again, you would define the variable 'TEXI2HTML' in the Makefile; + for example, it might run 'makeinfo --no-split --html' ('makeinfo' + is part of the Texinfo distribution). + +'dist' + Create a distribution tar file for this program. The tar file + should be set up so that the file names in the tar file start with + a subdirectory name which is the name of the package it is a + distribution for. This name can include the version number. + + For example, the distribution tar file of GCC version 1.40 unpacks + into a subdirectory named 'gcc-1.40'. + + The easiest way to do this is to create a subdirectory + appropriately named, use 'ln' or 'cp' to install the proper files + in it, and then 'tar' that subdirectory. + + Compress the tar file with 'gzip'. For example, the actual + distribution file for GCC version 1.40 is called 'gcc-1.40.tar.gz'. + + The 'dist' target should explicitly depend on all non-source files + that are in the distribution, to make sure they are up to date in + the distribution. *Note Making Releases: Releases. + +'check' + Perform self-tests (if any). The user must build the program + before running the tests, but need not install the program; you + should write the self-tests so that they work when the program is + built but not installed. + + The following targets are suggested as conventional names, for +programs in which they are useful. + +'installcheck' + Perform installation tests (if any). The user must build and + install the program before running the tests. You should not + assume that '$(bindir)' is in the search path. + +'installdirs' + It's useful to add a target named 'installdirs' to create the + directories where files are installed, and their parent + directories. There is a script called 'mkinstalldirs' which is + convenient for this; you can find it in the Texinfo package. You + can use a rule like this: + + # Make sure all installation directories (e.g. $(bindir)) + # actually exist by making them if necessary. + installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ + $(libdir) $(infodir) \ + $(mandir) + + or, if you wish to support 'DESTDIR', + + # Make sure all installation directories (e.g. $(bindir)) + # actually exist by making them if necessary. + installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs \ + $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ + $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ + $(DESTDIR)$(mandir) + + This rule should not modify the directories where compilation is + done. It should do nothing but create installation directories. + + ---------- Footnotes ---------- + + (1) 'texi2dvi' uses TeX to do the real work of formatting. TeX is +not distributed with Texinfo. + + +File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions + +7.2.7 Install Command Categories +-------------------------------- + +When writing the 'install' target, you must classify all the commands +into three categories: normal ones, "pre-installation" commands and +"post-installation" commands. + + Normal commands move files into their proper places, and set their +modes. They may not alter any files except the ones that come entirely +from the package they belong to. + + Pre-installation and post-installation commands may alter other +files; in particular, they can edit global configuration files or data +bases. + + Pre-installation commands are typically executed before the normal +commands, and post-installation commands are typically run after the +normal commands. + + The most common use for a post-installation command is to run +'install-info'. This cannot be done with a normal command, since it +alters a file (the Info directory) which does not come entirely and +solely from the package being installed. It is a post-installation +command because it needs to be done after the normal command which +installs the package's Info files. + + Most programs don't need any pre-installation commands, but we have +the feature just in case it is needed. + + To classify the commands in the 'install' rule into these three +categories, insert "category lines" among them. A category line +specifies the category for the commands that follow. + + A category line consists of a tab and a reference to a special Make +variable, plus an optional comment at the end. There are three +variables you can use, one for each category; the variable name +specifies the category. Category lines are no-ops in ordinary execution +because these three Make variables are normally undefined (and you +_should not_ define them in the makefile). + + Here are the three possible category lines, each with a comment that +explains what it means: + + $(PRE_INSTALL) # Pre-install commands follow. + $(POST_INSTALL) # Post-install commands follow. + $(NORMAL_INSTALL) # Normal commands follow. + + If you don't use a category line at the beginning of the 'install' +rule, all the commands are classified as normal until the first category +line. If you don't use any category lines, all the commands are +classified as normal. + + These are the category lines for 'uninstall': + + $(PRE_UNINSTALL) # Pre-uninstall commands follow. + $(POST_UNINSTALL) # Post-uninstall commands follow. + $(NORMAL_UNINSTALL) # Normal commands follow. + + Typically, a pre-uninstall command would be used for deleting entries +from the Info directory. + + If the 'install' or 'uninstall' target has any dependencies which act +as subroutines of installation, then you should start _each_ +dependency's commands with a category line, and start the main target's +commands with a category line also. This way, you can ensure that each +command is placed in the right category regardless of which of the +dependencies actually run. + + Pre-installation and post-installation commands should not run any +programs except for these: + + [ basename bash cat chgrp chmod chown cmp cp dd diff echo + egrep expand expr false fgrep find getopt grep gunzip gzip + hostname install install-info kill ldconfig ln ls md5sum + mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee + test touch true uname xargs yes + + The reason for distinguishing the commands in this way is for the +sake of making binary packages. Typically a binary package contains all +the executables and other files that need to be installed, and has its +own method of installing them--so it does not need to run the normal +installation commands. But installing the binary package does need to +execute the pre-installation and post-installation commands. + + Programs to build binary packages work by extracting the +pre-installation and post-installation commands. Here is one way of +extracting the pre-installation commands (the '-s' option to 'make' is +needed to silence messages about entering subdirectories): + + make -s -n install -o all \ + PRE_INSTALL=pre-install \ + POST_INSTALL=post-install \ + NORMAL_INSTALL=normal-install \ + | gawk -f pre-install.awk + +where the file 'pre-install.awk' could contain this: + + $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0} + on {print $0} + $0 ~ /^pre-install[ \t]*$/ {on = 1} + + +File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases + +7.3 Making Releases +=================== + +You should identify each release with a pair of version numbers, a major +version and a minor. We have no objection to using more than two +numbers, but it is very unlikely that you really need them. + + Package the distribution of 'Foo version 69.96' up in a gzipped tar +file with the name 'foo-69.96.tar.gz'. It should unpack into a +subdirectory named 'foo-69.96'. + + Building and installing the program should never modify any of the +files contained in the distribution. This means that all the files that +form part of the program in any way must be classified into "source +files" and "non-source files". Source files are written by humans and +never changed automatically; non-source files are produced from source +files by programs under the control of the Makefile. + + The distribution should contain a file named 'README' which gives the +name of the package, and a general description of what it does. It is +also good to explain the purpose of each of the first-level +subdirectories in the package, if there are any. The 'README' file +should either state the version number of the package, or refer to where +in the package it can be found. + + The 'README' file should refer to the file 'INSTALL', which should +contain an explanation of the installation procedure. + + The 'README' file should also refer to the file which contains the +copying conditions. The GNU GPL, if used, should be in a file called +'COPYING'. If the GNU LGPL is used, it should be in a file called +'COPYING.LESSER'. + + Naturally, all the source files must be in the distribution. It is +okay to include non-source files in the distribution, provided they are +up-to-date and machine-independent, so that building the distribution +normally will never modify them. We commonly include non-source files +produced by Bison, 'lex', TeX, and 'makeinfo'; this helps avoid +unnecessary dependencies between our distributions, so that users can +install whichever packages they want to install. + + Non-source files that might actually be modified by building and +installing the program should *never* be included in the distribution. +So if you do distribute non-source files, always make sure they are up +to date when you make a new distribution. + + Make sure that all the files in the distribution are world-readable, +and that directories are world-readable and world-searchable (octal mode +755). We used to recommend that all directories in the distribution +also be world-writable (octal mode 777), because ancient versions of +'tar' would otherwise not cope when extracting the archive as an +unprivileged user. That can easily lead to security issues when +creating the archive, however, so now we recommend against that. + + Don't include any symbolic links in the distribution itself. If the +tar file contains symbolic links, then people cannot even unpack it on +systems that don't support symbolic links. Also, don't use multiple +names for one file in different directories, because certain file +systems cannot handle this and that prevents unpacking the distribution. + + Try to make sure that all the file names will be unique on MS-DOS. A +name on MS-DOS consists of up to 8 characters, optionally followed by a +period and up to three characters. MS-DOS will truncate extra +characters both before and after the period. Thus, 'foobarhacker.c' and +'foobarhacker.o' are not ambiguous; they are truncated to 'foobarha.c' +and 'foobarha.o', which are distinct. + + Include in your distribution a copy of the 'texinfo.tex' you used to +test print any '*.texinfo' or '*.texi' files. + + Likewise, if your program uses small GNU software packages like +regex, getopt, obstack, or termcap, include them in the distribution +file. Leaving them out would make the distribution file a little +smaller at the expense of possible inconvenience to a user who doesn't +know what other files to get. + + +File: standards.info, Node: References, Next: GNU Free Documentation License, Prev: Managing Releases, Up: Top + +8 References to Non-Free Software and Documentation +*************************************************** + +A GNU program should not recommend, promote, or grant legitimacy to the +use of any non-free program. Proprietary software is a social and +ethical problem, and our aim is to put an end to that problem. We can't +stop some people from writing proprietary programs, or stop other people +from using them, but we can and should refuse to advertise them to new +potential customers, or to give the public the idea that their existence +is ethical. + + The GNU definition of free software is found on the GNU web site at +, and the definition of free +documentation is found at . +The terms "free" and "non-free", used in this document, refer to those +definitions. + + A list of important licenses and whether they qualify as free is in +. If it is not clear +whether a license qualifies as free, please ask the GNU Project by +writing to . We will answer, and if the license is +an important one, we will add it to the list. + + When a non-free program or system is well known, you can mention it +in passing--that is harmless, since users who might want to use it +probably already know about it. For instance, it is fine to explain how +to build your package on top of some widely used non-free operating +system, or how to use it together with some widely used non-free +program. + + However, you should give only the necessary information to help those +who already use the non-free program to use your program with it--don't +give, or refer to, any further information about the proprietary +program, and don't imply that the proprietary program enhances your +program, or that its existence is in any way a good thing. The goal +should be that people already using the proprietary program will get the +advice they need about how to use your free program with it, while +people who don't already use the proprietary program will not see +anything likely to lead them to take an interest in it. + + If a non-free program or system is obscure in your program's domain, +your program should not mention or support it at all, since doing so +would tend to popularize the non-free program more than it popularizes +your program. (You cannot hope to find many additional users for your +program among the users of Foobar, if the existence of Foobar is not +generally known among people who might want to use your program.) + + Sometimes a program is free software in itself but depends on a +non-free platform in order to run. For instance, many Java programs +depend on some non-free Java libraries. To recommend or promote such a +program is to promote the other programs it needs. This is why we are +careful about listing Java programs in the Free Software Directory: we +don't want to promote the non-free Java libraries. + + We hope this particular problem with Java will be gone by and by, as +we replace the remaining non-free standard Java libraries with free +software, but the general principle will remain the same: don't +recommend, promote or legitimize programs that depend on non-free +software to run. + + Some free programs strongly encourage the use of non-free software. +A typical example is 'mplayer'. It is free software in itself, and the +free code can handle some kinds of files. However, 'mplayer' recommends +use of non-free codecs for other kinds of files, and users that install +'mplayer' are very likely to install those codecs along with it. To +recommend 'mplayer' is, in effect, to promote use of the non-free +codecs. + + Thus, you should not recommend programs that strongly encourage the +use of non-free software. This is why we do not list 'mplayer' in the +Free Software Directory. + + A GNU package should not refer the user to any non-free documentation +for free software. Free documentation that can be included in free +operating systems is essential for completing the GNU system, or any +free operating system, so encouraging it is a priority; to recommend use +of documentation that we are not allowed to include undermines the +impetus for the community to produce documentation that we can include. +So GNU packages should never recommend non-free documentation. + + By contrast, it is ok to refer to journal articles and textbooks in +the comments of a program for explanation of how it functions, even +though they are non-free. This is because we don't include such things +in the GNU system even they are free--they are outside the scope of what +a software distribution needs to include. + + Referring to a web site that describes or recommends a non-free +program is promoting that program, so please do not make links (or +mention by name) web sites that contain such material. This policy is +relevant particularly for the web pages for a GNU package. + + Following links from nearly any web site can lead eventually to +non-free software; this is inherent in the nature of the web. So it +makes no sense to criticize a site for having such links. As long as +the site does not itself recommend a non-free program, there is no need +to consider the question of the sites that it links to for other +reasons. + + Thus, for example, you should not refer to AT&T's web site if that +recommends AT&T's non-free software packages; you should not refer to a +site that links to AT&T's site presenting it as a place to get some +non-free program, because that link recommends and legitimizes the +non-free program. However, that a site contains a link to AT&T's web +site for some other purpose (such as long-distance telephone service) is +not an objection against it. + + +File: standards.info, Node: GNU Free Documentation License, Next: Index, Prev: References, Up: Top + +Appendix A GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: standards.info, Node: Index, Prev: GNU Free Documentation License, Up: Top + +Index +***** + +[index] +* Menu: + +* '#endif', commenting: Comments. (line 60) +* '--help' output: --help. (line 6) +* '--version' output: --version. (line 6) +* '-Wall' compiler option: Syntactic Conventions. + (line 10) +* accepting contributions: Contributions. (line 6) +* address for bug reports: --help. (line 11) +* ANSI C standard: Standard C. (line 6) +* arbitrary limits on data: Semantics. (line 6) +* ASCII characters: Character Set. (line 6) +* autoconf: System Portability. (line 23) +* avoiding proprietary code: Reading Non-Free Code. + (line 6) +* behavior, dependent on program's name: User Interfaces. (line 6) +* binary packages: Install Command Categories. + (line 80) +* bindir: Directory Variables. (line 54) +* braces, in C source: Formatting. (line 6) +* bug reports: --help. (line 11) +* 'bug-standards@gnu.org' email address: Preface. (line 30) +* canonical name of a program: --version. (line 12) +* casting pointers to integers: CPU Portability. (line 88) +* CGI programs, standard options for: Command-Line Interfaces. + (line 31) +* change logs: Change Logs. (line 6) +* change logs, conditional changes: Conditional Changes. (line 6) +* change logs, style: Style of Change Logs. + (line 6) +* character set: Character Set. (line 6) +* command-line arguments, decoding: Semantics. (line 46) +* command-line interface: Command-Line Interfaces. + (line 6) +* commenting: Comments. (line 6) +* compatibility with C and POSIX standards: Compatibility. (line 6) +* compiler warnings: Syntactic Conventions. + (line 10) +* conditional changes, and change logs: Conditional Changes. (line 6) +* conditionals, comments for: Comments. (line 60) +* configure: Configuration. (line 6) +* control-L: Formatting. (line 118) +* conventions for makefiles: Makefile Conventions. + (line 6) +* CORBA: Graphical Interfaces. + (line 16) +* credits for manuals: Manual Credits. (line 6) +* D-bus: Graphical Interfaces. + (line 16) +* data types, and portability: CPU Portability. (line 6) +* declaration for system functions: System Functions. (line 21) +* DESTDIR: DESTDIR. (line 6) +* documentation: Documentation. (line 6) +* doschk: Names. (line 38) +* downloading this manual: Preface. (line 14) +* encodings: Character Set. (line 6) +* error messages: Semantics. (line 19) +* error messages, formatting: Errors. (line 6) +* exec_prefix: Directory Variables. (line 36) +* expressions, splitting: Formatting. (line 81) +* FDL, GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* file usage: File Usage. (line 6) +* file-name limitations: Names. (line 38) +* formatting error messages: Errors. (line 6) +* formatting source code: Formatting. (line 6) +* formfeed: Formatting. (line 118) +* function argument, declaring: Syntactic Conventions. + (line 6) +* function prototypes: Standard C. (line 17) +* getopt: Command-Line Interfaces. + (line 6) +* gettext: Internationalization. + (line 6) +* GNOME: Graphical Interfaces. + (line 16) +* GNOME and Guile: Source Language. (line 37) +* gnustandards project repository: Preface. (line 30) +* 'gnustandards-commit@gnu.org' mailing list: Preface. (line 24) +* graphical user interface: Graphical Interfaces. + (line 6) +* grave accent: Quote Characters. (line 6) +* GTK+: Graphical Interfaces. + (line 6) +* Guile: Source Language. (line 37) +* implicit 'int': Syntactic Conventions. + (line 6) +* impossible conditions: Semantics. (line 70) +* installations, staged: DESTDIR. (line 6) +* interface styles: Graphical Interfaces. + (line 6) +* internationalization: Internationalization. + (line 6) +* keyboard interface: Graphical Interfaces. + (line 16) +* LDAP: OID Allocations. (line 6) +* left quote: Quote Characters. (line 6) +* legal aspects: Legal Issues. (line 6) +* legal papers: Contributions. (line 6) +* libexecdir: Directory Variables. (line 67) +* libraries: Libraries. (line 6) +* library functions, and portability: System Functions. (line 6) +* library interface: Graphical Interfaces. + (line 16) +* license for manuals: License for Manuals. (line 6) +* lint: Syntactic Conventions. + (line 109) +* locale-specific quote characters: Quote Characters. (line 6) +* long option names: Option Table. (line 6) +* long-named options: Command-Line Interfaces. + (line 12) +* makefile, conventions for: Makefile Conventions. + (line 6) +* 'malloc' return value: Semantics. (line 25) +* man pages: Man Pages. (line 6) +* manual structure: Manual Structure Details. + (line 6) +* memory allocation failure: Semantics. (line 25) +* memory usage: Memory Usage. (line 6) +* message text, and internationalization: Internationalization. + (line 29) +* mmap: Mmap. (line 6) +* multiple variables in a line: Syntactic Conventions. + (line 35) +* names of variables, functions, and files: Names. (line 6) +* 'NEWS' file: NEWS File. (line 6) +* non-ASCII characters: Character Set. (line 6) +* non-POSIX systems, and portability: System Portability. (line 32) +* non-standard extensions: Using Extensions. (line 6) +* 'NUL' characters: Semantics. (line 11) +* OID allocations for GNU: OID Allocations. (line 6) +* open brace: Formatting. (line 6) +* optional features, configure-time: Configuration. (line 97) +* options for compatibility: Compatibility. (line 14) +* options, standard command-line: Command-Line Interfaces. + (line 31) +* output device and program's behavior: User Interfaces. (line 13) +* packaging: Releases. (line 6) +* PATH_INFO, specifying standard options as: Command-Line Interfaces. + (line 31) +* portability, and data types: CPU Portability. (line 6) +* portability, and library functions: System Functions. (line 6) +* portability, between system types: System Portability. (line 6) +* POSIX compatibility: Compatibility. (line 6) +* 'POSIXLY_CORRECT', environment variable: Compatibility. (line 21) +* post-installation commands: Install Command Categories. + (line 6) +* pre-installation commands: Install Command Categories. + (line 6) +* prefix: Directory Variables. (line 26) +* program configuration: Configuration. (line 6) +* program design: Design Advice. (line 6) +* program name and its behavior: User Interfaces. (line 6) +* program's canonical name: --version. (line 12) +* programming languages: Source Language. (line 6) +* proprietary programs: Reading Non-Free Code. + (line 6) +* quote characters: Quote Characters. (line 6) +* 'README' file: Releases. (line 21) +* references to non-free material: References. (line 6) +* releasing: Managing Releases. (line 6) +* Savannah repository for gnustandards: Preface. (line 30) +* sbindir: Directory Variables. (line 60) +* signal handling: Semantics. (line 59) +* SNMP: OID Allocations. (line 6) +* spaces before open-paren: Formatting. (line 75) +* staged installs: DESTDIR. (line 6) +* standard command-line options: Command-Line Interfaces. + (line 31) +* standards for makefiles: Makefile Conventions. + (line 6) +* string library functions: System Functions. (line 54) +* syntactic conventions: Syntactic Conventions. + (line 6) +* table of long options: Option Table. (line 6) +* temporary files: Semantics. (line 84) +* temporary variables: Syntactic Conventions. + (line 23) +* 'texinfo.tex', in a distribution: Releases. (line 70) +* 'TMPDIR' environment variable: Semantics. (line 84) +* trademarks: Trademarks. (line 6) +* user interface styles: Graphical Interfaces. + (line 6) +* where to obtain 'standards.texi': Preface. (line 14) +* X.509: OID Allocations. (line 6) + + + +Tag Table: +Node: Top808 +Node: Preface2083 +Node: Legal Issues4784 +Node: Reading Non-Free Code5254 +Node: Contributions6983 +Node: Trademarks9221 +Node: Design Advice10855 +Node: Source Language11447 +Node: Compatibility13566 +Node: Using Extensions15194 +Node: Standard C16771 +Node: Conditional Compilation19174 +Node: Program Behavior20572 +Node: Non-GNU Standards21688 +Node: Semantics23969 +Node: Libraries28689 +Node: Errors29934 +Node: User Interfaces32427 +Node: Graphical Interfaces34032 +Node: Command-Line Interfaces35215 +Node: --version37245 +Node: --help42964 +Node: Option Table43837 +Node: OID Allocations58792 +Node: Memory Usage60589 +Node: File Usage61625 +Node: Writing C62375 +Node: Formatting63345 +Node: Comments67634 +Node: Syntactic Conventions71185 +Node: Names74647 +Node: System Portability76859 +Node: CPU Portability79750 +Node: System Functions83652 +Node: Internationalization88844 +Node: Character Set92838 +Node: Quote Characters93651 +Node: Mmap95171 +Node: Documentation95879 +Node: GNU Manuals96985 +Node: Doc Strings and Manuals102723 +Node: Manual Structure Details104276 +Node: License for Manuals105694 +Node: Manual Credits106667 +Node: Printed Manuals107060 +Node: NEWS File107746 +Node: Change Logs108424 +Node: Change Log Concepts109178 +Node: Style of Change Logs111281 +Node: Simple Changes113781 +Node: Conditional Changes115223 +Node: Indicating the Part Changed116645 +Node: Man Pages117172 +Node: Reading other Manuals119346 +Node: Managing Releases120137 +Node: Configuration120917 +Node: Makefile Conventions129580 +Node: Makefile Basics130462 +Node: Utilities in Makefiles133636 +Node: Command Variables135782 +Node: DESTDIR139005 +Node: Directory Variables141154 +Node: Standard Targets155639 +Ref: Standard Targets-Footnote-1169155 +Node: Install Command Categories169256 +Node: Releases173789 +Node: References177793 +Node: GNU Free Documentation License183639 +Node: Index208786 + +End Tag Table diff --git a/util/X86MAC64/share/locale/da/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/da/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..deb4565597 Binary files /dev/null and b/util/X86MAC64/share/locale/da/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/da/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/da/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..2f18a0030b Binary files /dev/null and b/util/X86MAC64/share/locale/da/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/de/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/de/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..acd983f25e Binary files /dev/null and b/util/X86MAC64/share/locale/de/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/es/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/es/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..d31fab0062 Binary files /dev/null and b/util/X86MAC64/share/locale/es/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/es/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/es/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..4aba3dee46 Binary files /dev/null and b/util/X86MAC64/share/locale/es/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/fi/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/fi/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..25fe52e818 Binary files /dev/null and b/util/X86MAC64/share/locale/fi/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/fi/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/fi/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..5c10172cb1 Binary files /dev/null and b/util/X86MAC64/share/locale/fi/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/fr/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/fr/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..176e230191 Binary files /dev/null and b/util/X86MAC64/share/locale/fr/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/fr/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/fr/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..8d6122358a Binary files /dev/null and b/util/X86MAC64/share/locale/fr/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/ga/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/ga/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..fef67102ce Binary files /dev/null and b/util/X86MAC64/share/locale/ga/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/id/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/id/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..46b2f30394 Binary files /dev/null and b/util/X86MAC64/share/locale/id/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/id/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/id/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..4ad376403f Binary files /dev/null and b/util/X86MAC64/share/locale/id/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/it/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/it/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..7e18e7af6b Binary files /dev/null and b/util/X86MAC64/share/locale/it/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/ja/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/ja/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..321f8332da Binary files /dev/null and b/util/X86MAC64/share/locale/ja/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/nl/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/nl/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..8e26600c2d Binary files /dev/null and b/util/X86MAC64/share/locale/nl/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/pt_BR/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/pt_BR/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..083e8f4219 Binary files /dev/null and b/util/X86MAC64/share/locale/pt_BR/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/ro/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/ro/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..8621928313 Binary files /dev/null and b/util/X86MAC64/share/locale/ro/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/ro/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/ro/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..6125448e62 Binary files /dev/null and b/util/X86MAC64/share/locale/ro/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/ru/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/ru/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..9dd8b47e4f Binary files /dev/null and b/util/X86MAC64/share/locale/ru/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/rw/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/rw/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..49d9e2fd45 Binary files /dev/null and b/util/X86MAC64/share/locale/rw/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/sv/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/sv/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..e746ec02e7 Binary files /dev/null and b/util/X86MAC64/share/locale/sv/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/sv/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/sv/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..2347bdcdad Binary files /dev/null and b/util/X86MAC64/share/locale/sv/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/tr/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/tr/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..74c0ea8fc2 Binary files /dev/null and b/util/X86MAC64/share/locale/tr/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/tr/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/tr/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..98b9df1535 Binary files /dev/null and b/util/X86MAC64/share/locale/tr/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/uk/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/uk/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..9c85a90d66 Binary files /dev/null and b/util/X86MAC64/share/locale/uk/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/uk/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/uk/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..c9cbf5b7bd Binary files /dev/null and b/util/X86MAC64/share/locale/uk/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/vi/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/vi/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..0687a749e6 Binary files /dev/null and b/util/X86MAC64/share/locale/vi/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/vi/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/vi/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..38a5f5ae21 Binary files /dev/null and b/util/X86MAC64/share/locale/vi/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/locale/zh_CN/LC_MESSAGES/bfd.mo b/util/X86MAC64/share/locale/zh_CN/LC_MESSAGES/bfd.mo new file mode 100644 index 0000000000..65998865d3 Binary files /dev/null and b/util/X86MAC64/share/locale/zh_CN/LC_MESSAGES/bfd.mo differ diff --git a/util/X86MAC64/share/locale/zh_CN/LC_MESSAGES/opcodes.mo b/util/X86MAC64/share/locale/zh_CN/LC_MESSAGES/opcodes.mo new file mode 100644 index 0000000000..2bf6751c43 Binary files /dev/null and b/util/X86MAC64/share/locale/zh_CN/LC_MESSAGES/opcodes.mo differ diff --git a/util/X86MAC64/share/man/man1/gdb.1 b/util/X86MAC64/share/man/man1/gdb.1 new file mode 100644 index 0000000000..88a1546718 --- /dev/null +++ b/util/X86MAC64/share/man/man1/gdb.1 @@ -0,0 +1,396 @@ +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GDB 1" +.TH GDB 1 "2014-05-25" "gdb-7.7.1" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gdb \- The GNU Debugger +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +gdb [\fB\-help\fR] [\fB\-nh\fR] [\fB\-nx\fR] [\fB\-q\fR] +[\fB\-batch\fR] [\fB\-cd=\fR\fIdir\fR] [\fB\-f\fR] +[\fB\-b\fR\ \fIbps\fR] + [\fB\-tty=\fR\fIdev\fR] [\fB\-s\fR \fIsymfile\fR] +[\fB\-e\fR\ \fIprog\fR] [\fB\-se\fR\ \fIprog\fR] +[\fB\-c\fR\ \fIcore\fR] [\fB\-p\fR\ \fIprocID\fR] + [\fB\-x\fR\ \fIcmds\fR] [\fB\-d\fR\ \fIdir\fR] +[\fIprog\fR|\fIprog\fR \fIprocID\fR|\fIprog\fR \fIcore\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The purpose of a debugger such as \s-1GDB\s0 is to allow you to see what is +going on \*(L"inside\*(R" another program while it executes \*(-- or what another +program was doing at the moment it crashed. +.PP +\&\s-1GDB\s0 can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: +.IP "\(bu" 4 +Start your program, specifying anything that might affect its behavior. +.IP "\(bu" 4 +Make your program stop on specified conditions. +.IP "\(bu" 4 +Examine what has happened, when your program has stopped. +.IP "\(bu" 4 +Change things in your program, so you can experiment with correcting the +effects of one bug and go on to learn about another. +.PP +You can use \s-1GDB\s0 to debug programs written in C, C@t{++}, Fortran and +Modula\-2. +.PP +\&\s-1GDB\s0 is invoked with the shell command \f(CW\*(C`gdb\*(C'\fR. Once started, it reads +commands from the terminal until you tell it to exit with the \s-1GDB\s0 +command \f(CW\*(C`quit\*(C'\fR. You can get online help from \s-1GDB\s0 itself +by using the command \f(CW\*(C`help\*(C'\fR. +.PP +You can run \f(CW\*(C`gdb\*(C'\fR with no arguments or options; but the most +usual way to start \s-1GDB\s0 is with one argument or two, specifying an +executable program as the argument: +.PP +.Vb 1 +\& gdb program +.Ve +.PP +You can also start with both an executable program and a core file specified: +.PP +.Vb 1 +\& gdb program core +.Ve +.PP +You can, instead, specify a process \s-1ID\s0 as a second argument, if you want +to debug a running process: +.PP +.Vb 2 +\& gdb program 1234 +\& gdb \-p 1234 +.Ve +.PP +would attach \s-1GDB\s0 to process \f(CW1234\fR (unless you also have a file +named \fI1234\fR; \s-1GDB\s0 does check for a core file first). +With option \fB\-p\fR you can omit the \fIprogram\fR filename. +.PP +Here are some of the most frequently needed \s-1GDB\s0 commands: +.IP "\fBbreak [\fR\fIfile\fR\fB:]\fR\fIfunctiop\fR" 4 +.IX Item "break [file:]functiop" +Set a breakpoint at \fIfunction\fR (in \fIfile\fR). +.IP "\fBrun [\fR\fIarglist\fR\fB]\fR" 4 +.IX Item "run [arglist]" +Start your program (with \fIarglist\fR, if specified). +.IP "\fBbt\fR" 4 +.IX Item "bt" +Backtrace: display the program stack. +.IP "\fBprint\fR \fIexpr\fR" 4 +.IX Item "print expr" +Display the value of an expression. +.IP "\fBc\fR" 4 +.IX Item "c" +Continue running your program (after stopping, e.g. at a breakpoint). +.IP "\fBnext\fR" 4 +.IX Item "next" +Execute next program line (after stopping); step \fIover\fR any +function calls in the line. +.IP "\fBedit [\fR\fIfile\fR\fB:]\fR\fIfunction\fR" 4 +.IX Item "edit [file:]function" +look at the program line where it is presently stopped. +.IP "\fBlist [\fR\fIfile\fR\fB:]\fR\fIfunction\fR" 4 +.IX Item "list [file:]function" +type the text of the program in the vicinity of where it is presently stopped. +.IP "\fBstep\fR" 4 +.IX Item "step" +Execute next program line (after stopping); step \fIinto\fR any +function calls in the line. +.IP "\fBhelp [\fR\fIname\fR\fB]\fR" 4 +.IX Item "help [name]" +Show information about \s-1GDB\s0 command \fIname\fR, or general information +about using \s-1GDB\s0. +.IP "\fBquit\fR" 4 +.IX Item "quit" +Exit from \s-1GDB\s0. +.PP +For full details on \s-1GDB\s0, +see \fIUsing \s-1GDB:\s0 A Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +by Richard M. Stallman and Roland H. Pesch. The same text is available online +as the \f(CW\*(C`gdb\*(C'\fR entry in the \f(CW\*(C`info\*(C'\fR program. +.SH "OPTIONS" +.IX Header "OPTIONS" +Any arguments other than options specify an executable +file and core file (or process \s-1ID\s0); that is, the first argument +encountered with no +associated option flag is equivalent to a \fB\-se\fR option, and the second, +if any, is equivalent to a \fB\-c\fR option if it's the name of a file. +Many options have +both long and short forms; both are shown here. The long forms are also +recognized if you truncate them, so long as enough of the option is +present to be unambiguous. (If you prefer, you can flag option +arguments with \fB+\fR rather than \fB\-\fR, though we illustrate the +more usual convention.) +.PP +All the options and command line arguments you give are processed +in sequential order. The order makes a difference when the \fB\-x\fR +option is used. +.IP "\fB\-help\fR" 4 +.IX Item "-help" +.PD 0 +.IP "\fB\-h\fR" 4 +.IX Item "-h" +.PD +List all options, with brief explanations. +.IP "\fB\-symbols=\fR\fIfile\fR" 4 +.IX Item "-symbols=file" +.PD 0 +.IP "\fB\-s\fR \fIfile\fR" 4 +.IX Item "-s file" +.PD +Read symbol table from file \fIfile\fR. +.IP "\fB\-write\fR" 4 +.IX Item "-write" +Enable writing into executable and core files. +.IP "\fB\-exec=\fR\fIfile\fR" 4 +.IX Item "-exec=file" +.PD 0 +.IP "\fB\-e\fR \fIfile\fR" 4 +.IX Item "-e file" +.PD +Use file \fIfile\fR as the executable file to execute when +appropriate, and for examining pure data in conjunction with a core +dump. +.IP "\fB\-se=\fR\fIfile\fR" 4 +.IX Item "-se=file" +Read symbol table from file \fIfile\fR and use it as the executable +file. +.IP "\fB\-core=\fR\fIfile\fR" 4 +.IX Item "-core=file" +.PD 0 +.IP "\fB\-c\fR \fIfile\fR" 4 +.IX Item "-c file" +.PD +Use file \fIfile\fR as a core dump to examine. +.IP "\fB\-command=\fR\fIfile\fR" 4 +.IX Item "-command=file" +.PD 0 +.IP "\fB\-x\fR \fIfile\fR" 4 +.IX Item "-x file" +.PD +Execute \s-1GDB\s0 commands from file \fIfile\fR. +.IP "\fB\-ex\fR \fIcommand\fR" 4 +.IX Item "-ex command" +Execute given \s-1GDB\s0 \fIcommand\fR. +.IP "\fB\-directory=\fR\fIdirectory\fR" 4 +.IX Item "-directory=directory" +.PD 0 +.IP "\fB\-d\fR \fIdirectory\fR" 4 +.IX Item "-d directory" +.PD +Add \fIdirectory\fR to the path to search for source files. +.IP "\fB\-nh\fR" 4 +.IX Item "-nh" +Do not execute commands from \fI~/.gdbinit\fR. +.IP "\fB\-nx\fR" 4 +.IX Item "-nx" +.PD 0 +.IP "\fB\-n\fR" 4 +.IX Item "-n" +.PD +Do not execute commands from any \fI.gdbinit\fR initialization files. +.IP "\fB\-quiet\fR" 4 +.IX Item "-quiet" +.PD 0 +.IP "\fB\-q\fR" 4 +.IX Item "-q" +.PD +\&\*(L"Quiet\*(R". Do not print the introductory and copyright messages. These +messages are also suppressed in batch mode. +.IP "\fB\-batch\fR" 4 +.IX Item "-batch" +Run in batch mode. Exit with status \f(CW0\fR after processing all the command +files specified with \fB\-x\fR (and \fI.gdbinit\fR, if not inhibited). +Exit with nonzero status if an error occurs in executing the \s-1GDB\s0 +commands in the command files. +.Sp +Batch mode may be useful for running \s-1GDB\s0 as a filter, for example to +download and run a program on another computer; in order to make this +more useful, the message +.Sp +.Vb 1 +\& Program exited normally. +.Ve +.Sp +(which is ordinarily issued whenever a program running under \s-1GDB\s0 control +terminates) is not issued when running in batch mode. +.IP "\fB\-cd=\fR\fIdirectory\fR" 4 +.IX Item "-cd=directory" +Run \s-1GDB\s0 using \fIdirectory\fR as its working directory, +instead of the current directory. +.IP "\fB\-fullname\fR" 4 +.IX Item "-fullname" +.PD 0 +.IP "\fB\-f\fR" 4 +.IX Item "-f" +.PD +Emacs sets this option when it runs \s-1GDB\s0 as a subprocess. It tells +\&\s-1GDB\s0 to output the full file name and line number in a standard, +recognizable fashion each time a stack frame is displayed (which +includes each time the program stops). This recognizable format looks +like two \fB\e032\fR characters, followed by the file name, line number +and character position separated by colons, and a newline. The +Emacs-to-GDB interface program uses the two \fB\e032\fR +characters as a signal to display the source code for the frame. +.IP "\fB\-b\fR \fIbps\fR" 4 +.IX Item "-b bps" +Set the line speed (baud rate or bits per second) of any serial +interface used by \s-1GDB\s0 for remote debugging. +.IP "\fB\-tty=\fR\fIdevice\fR" 4 +.IX Item "-tty=device" +Run using \fIdevice\fR for your program's standard input and output. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual. +If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo +documentation are properly installed at your site, the command +.PP +.Vb 1 +\& info gdb +.Ve +.PP +should give you access to the complete manual. +.PP +\&\fIUsing \s-1GDB:\s0 A Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +Richard M. Stallman and Roland H. Pesch, July 1991. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2014 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs +Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R" +and with the Back-Cover Texts as in (a) below. +.PP +(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify +this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in +developing \s-1GNU\s0 and promoting software freedom.\*(R" diff --git a/util/X86MAC64/share/man/man1/gdbserver.1 b/util/X86MAC64/share/man/man1/gdbserver.1 new file mode 100644 index 0000000000..8c28ca4c9d --- /dev/null +++ b/util/X86MAC64/share/man/man1/gdbserver.1 @@ -0,0 +1,364 @@ +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GDBSERVER 1" +.TH GDBSERVER 1 "2014-05-25" "gdb-7.7.1" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gdbserver \- Remote Server for the GNU Debugger +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +gdbserver \fIcomm\fR \fIprog\fR [\fIargs\fR...] +.PP +gdbserver \-\-attach \fIcomm\fR \fIpid\fR +.PP +gdbserver \-\-multi \fIcomm\fR +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBgdbserver\fR is a program that allows you to run \s-1GDB\s0 on a different machine +than the one which is running the program being debugged. +.PP +Usage (server (target) side): +.PP +First, you need to have a copy of the program you want to debug put onto +the target system. The program can be stripped to save space if needed, as +\&\fBgdbserver\fR doesn't care about symbols. All symbol handling is taken care of by +the \s-1GDB\s0 running on the host system. +.PP +To use the server, you log on to the target system, and run the \fBgdbserver\fR +program. You must tell it (a) how to communicate with \s-1GDB\s0, (b) the name of +your program, and (c) its arguments. The general syntax is: +.PP +.Vb 1 +\& target> gdbserver [ ...] +.Ve +.PP +For example, using a serial port, you might say: +.PP +.Vb 1 +\& target> gdbserver /dev/com1 emacs foo.txt +.Ve +.PP +This tells \fBgdbserver\fR to debug emacs with an argument of foo.txt, and +to communicate with \s-1GDB\s0 via \fI/dev/com1\fR. \fBgdbserver\fR now +waits patiently for the host \s-1GDB\s0 to communicate with it. +.PP +To use a \s-1TCP\s0 connection, you could say: +.PP +.Vb 1 +\& target> gdbserver host:2345 emacs foo.txt +.Ve +.PP +This says pretty much the same thing as the last example, except that we are +going to communicate with the \f(CW\*(C`host\*(C'\fR \s-1GDB\s0 via \s-1TCP\s0. The \f(CW\*(C`host:2345\*(C'\fR argument means +that we are expecting to see a \s-1TCP\s0 connection from \f(CW\*(C`host\*(C'\fR to local \s-1TCP\s0 port +2345. (Currently, the \f(CW\*(C`host\*(C'\fR part is ignored.) You can choose any number you +want for the port number as long as it does not conflict with any existing \s-1TCP\s0 +ports on the target system. This same port number must be used in the host +GDBs \f(CW\*(C`target remote\*(C'\fR command, which will be described shortly. Note that if +you chose a port number that conflicts with another service, \fBgdbserver\fR will +print an error message and exit. +.PP +\&\fBgdbserver\fR can also attach to running programs. +This is accomplished via the \fB\-\-attach\fR argument. The syntax is: +.PP +.Vb 1 +\& target> gdbserver \-\-attach +.Ve +.PP +\&\fIpid\fR is the process \s-1ID\s0 of a currently running process. It isn't +necessary to point \fBgdbserver\fR at a binary for the running process. +.PP +To start \f(CW\*(C`gdbserver\*(C'\fR without supplying an initial command to run +or process \s-1ID\s0 to attach, use the \fB\-\-multi\fR command line option. +In such case you should connect using \f(CW\*(C`target extended\-remote\*(C'\fR to start +the program you want to debug. +.PP +.Vb 1 +\& target> gdbserver \-\-multi +.Ve +.PP +Usage (host side): +.PP +You need an unstripped copy of the target program on your host system, since +\&\s-1GDB\s0 needs to examine it's symbol tables and such. Start up \s-1GDB\s0 as you normally +would, with the target program as the first argument. (You may need to use the +\&\fB\-\-baud\fR option if the serial line is running at anything except 9600 baud.) +That is \f(CW\*(C`gdb TARGET\-PROG\*(C'\fR, or \f(CW\*(C`gdb \-\-baud BAUD TARGET\-PROG\*(C'\fR. After that, the only +new command you need to know about is \f(CW\*(C`target remote\*(C'\fR +(or \f(CW\*(C`target extended\-remote\*(C'\fR). Its argument is either +a device name (usually a serial device, like \fI/dev/ttyb\fR), or a \f(CW\*(C`HOST:PORT\*(C'\fR +descriptor. For example: +.PP +.Vb 1 +\& (gdb) target remote /dev/ttyb +.Ve +.PP +communicates with the server via serial line \fI/dev/ttyb\fR, and: +.PP +.Vb 1 +\& (gdb) target remote the\-target:2345 +.Ve +.PP +communicates via a \s-1TCP\s0 connection to port 2345 on host `the\-target', where +you previously started up \fBgdbserver\fR with the same port number. Note that for +\&\s-1TCP\s0 connections, you must start up \fBgdbserver\fR prior to using the `target remote' +command, otherwise you may get an error that looks something like +`Connection refused'. +.PP +\&\fBgdbserver\fR can also debug multiple inferiors at once, +described in +the \s-1GDB\s0 manual in node \f(CW\*(C`Inferiors and Programs\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n \*(AqInferiors and Programs\*(Aq\*(C'\fR. +In such case use the \f(CW\*(C`extended\-remote\*(C'\fR \s-1GDB\s0 command variant: +.PP +.Vb 1 +\& (gdb) target extended\-remote the\-target:2345 +.Ve +.PP +The \fBgdbserver\fR option \fB\-\-multi\fR may or may not be used in such +case. +.SH "OPTIONS" +.IX Header "OPTIONS" +There are three different modes for invoking \fBgdbserver\fR: +.IP "\(bu" 4 +Debug a specific program specified by its program name: +.Sp +.Vb 1 +\& gdbserver [...] +.Ve +.Sp +The \fIcomm\fR parameter specifies how should the server communicate +with \s-1GDB\s0; it is either a device name (to use a serial line), +a \s-1TCP\s0 port number (\f(CW\*(C`:1234\*(C'\fR), or \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`stdio\*(C'\fR to use +stdin/stdout of \f(CW\*(C`gdbserver\*(C'\fR. Specify the name of the program to +debug in \fIprog\fR. Any remaining arguments will be passed to the +program verbatim. When the program exits, \s-1GDB\s0 will close the +connection, and \f(CW\*(C`gdbserver\*(C'\fR will exit. +.IP "\(bu" 4 +Debug a specific program by specifying the process \s-1ID\s0 of a running +program: +.Sp +.Vb 1 +\& gdbserver \-\-attach +.Ve +.Sp +The \fIcomm\fR parameter is as described above. Supply the process \s-1ID\s0 +of a running program in \fIpid\fR; \s-1GDB\s0 will do everything +else. Like with the previous mode, when the process \fIpid\fR exits, +\&\s-1GDB\s0 will close the connection, and \f(CW\*(C`gdbserver\*(C'\fR will exit. +.IP "\(bu" 4 +Multi-process mode \*(-- debug more than one program/process: +.Sp +.Vb 1 +\& gdbserver \-\-multi +.Ve +.Sp +In this mode, \s-1GDB\s0 can instruct \fBgdbserver\fR which +command(s) to run. Unlike the other 2 modes, \s-1GDB\s0 will not +close the connection when a process being debugged exits, so you can +debug several processes in the same session. +.PP +In each of the modes you may specify these options: +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +List all options, with brief explanations. +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +This option causes \fBgdbserver\fR to print its version number and exit. +.IP "\fB\-\-attach\fR" 4 +.IX Item "--attach" +\&\fBgdbserver\fR will attach to a running program. The syntax is: +.Sp +.Vb 1 +\& target> gdbserver \-\-attach +.Ve +.Sp +\&\fIpid\fR is the process \s-1ID\s0 of a currently running process. It isn't +necessary to point \fBgdbserver\fR at a binary for the running process. +.IP "\fB\-\-multi\fR" 4 +.IX Item "--multi" +To start \f(CW\*(C`gdbserver\*(C'\fR without supplying an initial command to run +or process \s-1ID\s0 to attach, use this command line option. +Then you can connect using \f(CW\*(C`target extended\-remote\*(C'\fR and start +the program you want to debug. The syntax is: +.Sp +.Vb 1 +\& target> gdbserver \-\-multi +.Ve +.IP "\fB\-\-debug\fR" 4 +.IX Item "--debug" +Instruct \f(CW\*(C`gdbserver\*(C'\fR to display extra status information about the debugging +process. +This option is intended for \f(CW\*(C`gdbserver\*(C'\fR development and for bug reports to +the developers. +.IP "\fB\-\-remote\-debug\fR" 4 +.IX Item "--remote-debug" +Instruct \f(CW\*(C`gdbserver\*(C'\fR to display remote protocol debug output. +This option is intended for \f(CW\*(C`gdbserver\*(C'\fR development and for bug reports to +the developers. +.IP "\fB\-\-wrapper\fR" 4 +.IX Item "--wrapper" +Specify a wrapper to launch programs +for debugging. The option should be followed by the name of the +wrapper, then any command-line arguments to pass to the wrapper, then +\&\f(CW\*(C`\-\-\*(C'\fR indicating the end of the wrapper arguments. +.IP "\fB\-\-once\fR" 4 +.IX Item "--once" +By default, \fBgdbserver\fR keeps the listening \s-1TCP\s0 port open, so that +additional connections are possible. However, if you start \f(CW\*(C`gdbserver\*(C'\fR +with the \fB\-\-once\fR option, it will stop listening for any further +connection attempts after connecting to the first \s-1GDB\s0 session. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual. +If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo +documentation are properly installed at your site, the command +.PP +.Vb 1 +\& info gdb +.Ve +.PP +should give you access to the complete manual. +.PP +\&\fIUsing \s-1GDB:\s0 A Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +Richard M. Stallman and Roland H. Pesch, July 1991. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2014 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs +Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R" +and with the Back-Cover Texts as in (a) below. +.PP +(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify +this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in +developing \s-1GNU\s0 and promoting software freedom.\*(R" diff --git a/util/X86MAC64/share/man/man5/gdbinit.5 b/util/X86MAC64/share/man/man5/gdbinit.5 new file mode 100644 index 0000000000..4d66527d5f --- /dev/null +++ b/util/X86MAC64/share/man/man5/gdbinit.5 @@ -0,0 +1,200 @@ +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GDBINIT 5" +.TH GDBINIT 5 "2014-05-25" "gdb-7.7.1" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gdbinit \- GDB initialization scripts +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +~/.gdbinit +.PP +\&./.gdbinit +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These files contain \s-1GDB\s0 commands to automatically execute during +\&\s-1GDB\s0 startup. The lines of contents are canned sequences of commands, +described in +the \s-1GDB\s0 manual in node \f(CW\*(C`Sequences\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n Sequences\*(C'\fR. +.PP +Please read more in +the \s-1GDB\s0 manual in node \f(CW\*(C`Startup\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n Startup\*(C'\fR. +.ie n .IP "\fB(not enabled with \fB""\-\-with\-system\-gdbinit""\fB during compilation)\fR" 4 +.el .IP "\fB(not enabled with \f(CB\-\-with\-system\-gdbinit\fB during compilation)\fR" 4 +.IX Item "(not enabled with --with-system-gdbinit during compilation)" +System-wide initialization file. It is executed unless user specified +\&\s-1GDB\s0 option \f(CW\*(C`\-nx\*(C'\fR or \f(CW\*(C`\-n\*(C'\fR. +See more in +the \s-1GDB\s0 manual in node \f(CW\*(C`System\-wide configuration\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n \*(AqSystem\-wide configuration\*(Aq\*(C'\fR. +.IP "\fB~/.gdbinit\fR" 4 +.IX Item "~/.gdbinit" +User initialization file. It is executed unless user specified +\&\s-1GDB\s0 options \f(CW\*(C`\-nx\*(C'\fR, \f(CW\*(C`\-n\*(C'\fR or \f(CW\*(C`\-nh\*(C'\fR. +.IP "\fB./.gdbinit\fR" 4 +.IX Item "./.gdbinit" +Initialization file for current directory. It may need to be enabled with +\&\s-1GDB\s0 security command \f(CW\*(C`set auto\-load local\-gdbinit\*(C'\fR. +See more in +the \s-1GDB\s0 manual in node \f(CW\*(C`Init File in the Current Directory\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n \*(AqInit File in the Current Directory\*(Aq\*(C'\fR. +.SH "OPTIONS" +.IX Header "OPTIONS" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgdb\fR\|(1), \f(CW\*(C`info \-f gdb \-n Startup\*(C'\fR +.PP +The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual. +If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo +documentation are properly installed at your site, the command +.PP +.Vb 1 +\& info gdb +.Ve +.PP +should give you access to the complete manual. +.PP +\&\fIUsing \s-1GDB:\s0 A Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +Richard M. Stallman and Roland H. Pesch, July 1991. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2014 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs +Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R" +and with the Back-Cover Texts as in (a) below. +.PP +(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify +this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in +developing \s-1GNU\s0 and promoting software freedom.\*(R"