--- /dev/null
+../lmrcImageAddValueCuda.cu
\ No newline at end of file
--- /dev/null
+../lmrcImageClusterAnalysis.cu
\ No newline at end of file
--- /dev/null
+../pdbTransCuda.cu
\ No newline at end of file
--- /dev/null
+X86MAC64/eosFunc.o:eosFunc.o
--- /dev/null
+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 \
+
+
--- /dev/null
+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
+
--- /dev/null
+../../../../../hostdepend/X86MAC64/src/Objects/General/eosFunc/src/X86MAC64
\ No newline at end of file
+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
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 \
--- /dev/null
+../eosPointRotate.c
\ No newline at end of file
--- /dev/null
+../eosPointUtil.c
\ No newline at end of file
--- /dev/null
+../eosPointWrite.c
\ No newline at end of file
--- /dev/null
+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
--- /dev/null
+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
--- /dev/null
+../../../../../hostdepend/X86MAC64/src/Tools/eosPoint/eosPointRotation/src/X86MAC64
\ No newline at end of file
--- /dev/null
+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
--- /dev/null
+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
--- /dev/null
+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
--- /dev/null
+../../../../../hostdepend/X86MAC64/src/Tools/rec3d/marker2Dto3DEstimator/src/X86MAC64
\ No newline at end of file
--- /dev/null
+/* 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 <varargs.h> and C89 <stdarg.h> 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 */
--- /dev/null
+/* 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 <sys/stat.h>
+
+#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;
+\f
+/* 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;
+\f
+/* 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. */
+};
+\f
+/* 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;
+\f
+/* 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)
+\f
+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);
+\f
+/* 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 *);
+\f
+/* 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 <<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 } \
+ }
+
+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 <<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;
+
+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 <<WDISP30>>.) 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; <<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;
+
+#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 <<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 *);
+
+
+ /* 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
--- /dev/null
+/* 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
+ };
+\f
+/* 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;
+};
+\f
+/* 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);
+};
+\f
+/* 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
--- /dev/null
+/* 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 <stdio.h>
+#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;
+
+\f
+/* 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 *);
+
+\f
+/* 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) */
--- /dev/null
+/* 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 <http://www.gnu.org/licenses/>. */
+
+#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
--- /dev/null
+/* 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 */
--- /dev/null
+# 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'
--- /dev/null
+# 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'
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+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 "<function called from gdb>"
+ elif frame.type() == gdb.SIGTRAMP_FRAME:
+ return "<signal handler called>"
+
+ 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
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+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()
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+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()
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+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 ())
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+"""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 = ("<Enter %d to explore this field of type "
+ "'%s'>" % (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 = ("<Enter %d to explore this %s of type "
+ "'%s'>" %
+ (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 = ("<Enter %d to explore this %s of type '%s'>" %
+ (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()
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+"""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()
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+"""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()
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+"""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()
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+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()
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+"""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
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+"""$_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()
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+"""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('<unknown: 0x%x>' % 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
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+""" 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 '<no %s>' % what
+ if hasattr(obj, attr):
+ result = getattr(obj, attr)
+ if callable(result):
+ result = result()
+ return result
+ else:
+ return '<no attribute %s on current %s>' % (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
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+"""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)
--- /dev/null
+<?xml version="1.0"?>
+<!-- Copyright (C) 2009-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. -->
+
+<!DOCTYPE feature SYSTEM "gdb-syscalls.dtd">
+
+<!-- This file was generated using the following file:
+
+ /usr/src/linux/arch/x86/include/asm/unistd_64.h
+
+ The file mentioned above belongs to the Linux Kernel. -->
+
+<syscalls_info>
+ <syscall name="read" number="0"/>
+ <syscall name="write" number="1"/>
+ <syscall name="open" number="2"/>
+ <syscall name="close" number="3"/>
+ <syscall name="stat" number="4"/>
+ <syscall name="fstat" number="5"/>
+ <syscall name="lstat" number="6"/>
+ <syscall name="poll" number="7"/>
+ <syscall name="lseek" number="8"/>
+ <syscall name="mmap" number="9"/>
+ <syscall name="mprotect" number="10"/>
+ <syscall name="munmap" number="11"/>
+ <syscall name="brk" number="12"/>
+ <syscall name="rt_sigaction" number="13"/>
+ <syscall name="rt_sigprocmask" number="14"/>
+ <syscall name="rt_sigreturn" number="15"/>
+ <syscall name="ioctl" number="16"/>
+ <syscall name="pread64" number="17"/>
+ <syscall name="pwrite64" number="18"/>
+ <syscall name="readv" number="19"/>
+ <syscall name="writev" number="20"/>
+ <syscall name="access" number="21"/>
+ <syscall name="pipe" number="22"/>
+ <syscall name="select" number="23"/>
+ <syscall name="sched_yield" number="24"/>
+ <syscall name="mremap" number="25"/>
+ <syscall name="msync" number="26"/>
+ <syscall name="mincore" number="27"/>
+ <syscall name="madvise" number="28"/>
+ <syscall name="shmget" number="29"/>
+ <syscall name="shmat" number="30"/>
+ <syscall name="shmctl" number="31"/>
+ <syscall name="dup" number="32"/>
+ <syscall name="dup2" number="33"/>
+ <syscall name="pause" number="34"/>
+ <syscall name="nanosleep" number="35"/>
+ <syscall name="getitimer" number="36"/>
+ <syscall name="alarm" number="37"/>
+ <syscall name="setitimer" number="38"/>
+ <syscall name="getpid" number="39"/>
+ <syscall name="sendfile" number="40"/>
+ <syscall name="socket" number="41"/>
+ <syscall name="connect" number="42"/>
+ <syscall name="accept" number="43"/>
+ <syscall name="sendto" number="44"/>
+ <syscall name="recvfrom" number="45"/>
+ <syscall name="sendmsg" number="46"/>
+ <syscall name="recvmsg" number="47"/>
+ <syscall name="shutdown" number="48"/>
+ <syscall name="bind" number="49"/>
+ <syscall name="listen" number="50"/>
+ <syscall name="getsockname" number="51"/>
+ <syscall name="getpeername" number="52"/>
+ <syscall name="socketpair" number="53"/>
+ <syscall name="setsockopt" number="54"/>
+ <syscall name="getsockopt" number="55"/>
+ <syscall name="clone" number="56"/>
+ <syscall name="fork" number="57"/>
+ <syscall name="vfork" number="58"/>
+ <syscall name="execve" number="59"/>
+ <syscall name="exit" number="60"/>
+ <syscall name="wait4" number="61"/>
+ <syscall name="kill" number="62"/>
+ <syscall name="uname" number="63"/>
+ <syscall name="semget" number="64"/>
+ <syscall name="semop" number="65"/>
+ <syscall name="semctl" number="66"/>
+ <syscall name="shmdt" number="67"/>
+ <syscall name="msgget" number="68"/>
+ <syscall name="msgsnd" number="69"/>
+ <syscall name="msgrcv" number="70"/>
+ <syscall name="msgctl" number="71"/>
+ <syscall name="fcntl" number="72"/>
+ <syscall name="flock" number="73"/>
+ <syscall name="fsync" number="74"/>
+ <syscall name="fdatasync" number="75"/>
+ <syscall name="truncate" number="76"/>
+ <syscall name="ftruncate" number="77"/>
+ <syscall name="getdents" number="78"/>
+ <syscall name="getcwd" number="79"/>
+ <syscall name="chdir" number="80"/>
+ <syscall name="fchdir" number="81"/>
+ <syscall name="rename" number="82"/>
+ <syscall name="mkdir" number="83"/>
+ <syscall name="rmdir" number="84"/>
+ <syscall name="creat" number="85"/>
+ <syscall name="link" number="86"/>
+ <syscall name="unlink" number="87"/>
+ <syscall name="symlink" number="88"/>
+ <syscall name="readlink" number="89"/>
+ <syscall name="chmod" number="90"/>
+ <syscall name="fchmod" number="91"/>
+ <syscall name="chown" number="92"/>
+ <syscall name="fchown" number="93"/>
+ <syscall name="lchown" number="94"/>
+ <syscall name="umask" number="95"/>
+ <syscall name="gettimeofday" number="96"/>
+ <syscall name="getrlimit" number="97"/>
+ <syscall name="getrusage" number="98"/>
+ <syscall name="sysinfo" number="99"/>
+ <syscall name="times" number="100"/>
+ <syscall name="ptrace" number="101"/>
+ <syscall name="getuid" number="102"/>
+ <syscall name="syslog" number="103"/>
+ <syscall name="getgid" number="104"/>
+ <syscall name="setuid" number="105"/>
+ <syscall name="setgid" number="106"/>
+ <syscall name="geteuid" number="107"/>
+ <syscall name="getegid" number="108"/>
+ <syscall name="setpgid" number="109"/>
+ <syscall name="getppid" number="110"/>
+ <syscall name="getpgrp" number="111"/>
+ <syscall name="setsid" number="112"/>
+ <syscall name="setreuid" number="113"/>
+ <syscall name="setregid" number="114"/>
+ <syscall name="getgroups" number="115"/>
+ <syscall name="setgroups" number="116"/>
+ <syscall name="setresuid" number="117"/>
+ <syscall name="getresuid" number="118"/>
+ <syscall name="setresgid" number="119"/>
+ <syscall name="getresgid" number="120"/>
+ <syscall name="getpgid" number="121"/>
+ <syscall name="setfsuid" number="122"/>
+ <syscall name="setfsgid" number="123"/>
+ <syscall name="getsid" number="124"/>
+ <syscall name="capget" number="125"/>
+ <syscall name="capset" number="126"/>
+ <syscall name="rt_sigpending" number="127"/>
+ <syscall name="rt_sigtimedwait" number="128"/>
+ <syscall name="rt_sigqueueinfo" number="129"/>
+ <syscall name="rt_sigsuspend" number="130"/>
+ <syscall name="sigaltstack" number="131"/>
+ <syscall name="utime" number="132"/>
+ <syscall name="mknod" number="133"/>
+ <syscall name="uselib" number="134"/>
+ <syscall name="personality" number="135"/>
+ <syscall name="ustat" number="136"/>
+ <syscall name="statfs" number="137"/>
+ <syscall name="fstatfs" number="138"/>
+ <syscall name="sysfs" number="139"/>
+ <syscall name="getpriority" number="140"/>
+ <syscall name="setpriority" number="141"/>
+ <syscall name="sched_setparam" number="142"/>
+ <syscall name="sched_getparam" number="143"/>
+ <syscall name="sched_setscheduler" number="144"/>
+ <syscall name="sched_getscheduler" number="145"/>
+ <syscall name="sched_get_priority_max" number="146"/>
+ <syscall name="sched_get_priority_min" number="147"/>
+ <syscall name="sched_rr_get_interval" number="148"/>
+ <syscall name="mlock" number="149"/>
+ <syscall name="munlock" number="150"/>
+ <syscall name="mlockall" number="151"/>
+ <syscall name="munlockall" number="152"/>
+ <syscall name="vhangup" number="153"/>
+ <syscall name="modify_ldt" number="154"/>
+ <syscall name="pivot_root" number="155"/>
+ <syscall name="_sysctl" number="156"/>
+ <syscall name="prctl" number="157"/>
+ <syscall name="arch_prctl" number="158"/>
+ <syscall name="adjtimex" number="159"/>
+ <syscall name="setrlimit" number="160"/>
+ <syscall name="chroot" number="161"/>
+ <syscall name="sync" number="162"/>
+ <syscall name="acct" number="163"/>
+ <syscall name="settimeofday" number="164"/>
+ <syscall name="mount" number="165"/>
+ <syscall name="umount2" number="166"/>
+ <syscall name="swapon" number="167"/>
+ <syscall name="swapoff" number="168"/>
+ <syscall name="reboot" number="169"/>
+ <syscall name="sethostname" number="170"/>
+ <syscall name="setdomainname" number="171"/>
+ <syscall name="iopl" number="172"/>
+ <syscall name="ioperm" number="173"/>
+ <syscall name="create_module" number="174"/>
+ <syscall name="init_module" number="175"/>
+ <syscall name="delete_module" number="176"/>
+ <syscall name="get_kernel_syms" number="177"/>
+ <syscall name="query_module" number="178"/>
+ <syscall name="quotactl" number="179"/>
+ <syscall name="nfsservctl" number="180"/>
+ <syscall name="getpmsg" number="181"/>
+ <syscall name="putpmsg" number="182"/>
+ <syscall name="afs_syscall" number="183"/>
+ <syscall name="tuxcall" number="184"/>
+ <syscall name="security" number="185"/>
+ <syscall name="gettid" number="186"/>
+ <syscall name="readahead" number="187"/>
+ <syscall name="setxattr" number="188"/>
+ <syscall name="lsetxattr" number="189"/>
+ <syscall name="fsetxattr" number="190"/>
+ <syscall name="getxattr" number="191"/>
+ <syscall name="lgetxattr" number="192"/>
+ <syscall name="fgetxattr" number="193"/>
+ <syscall name="listxattr" number="194"/>
+ <syscall name="llistxattr" number="195"/>
+ <syscall name="flistxattr" number="196"/>
+ <syscall name="removexattr" number="197"/>
+ <syscall name="lremovexattr" number="198"/>
+ <syscall name="fremovexattr" number="199"/>
+ <syscall name="tkill" number="200"/>
+ <syscall name="time" number="201"/>
+ <syscall name="futex" number="202"/>
+ <syscall name="sched_setaffinity" number="203"/>
+ <syscall name="sched_getaffinity" number="204"/>
+ <syscall name="set_thread_area" number="205"/>
+ <syscall name="io_setup" number="206"/>
+ <syscall name="io_destroy" number="207"/>
+ <syscall name="io_getevents" number="208"/>
+ <syscall name="io_submit" number="209"/>
+ <syscall name="io_cancel" number="210"/>
+ <syscall name="get_thread_area" number="211"/>
+ <syscall name="lookup_dcookie" number="212"/>
+ <syscall name="epoll_create" number="213"/>
+ <syscall name="epoll_ctl_old" number="214"/>
+ <syscall name="epoll_wait_old" number="215"/>
+ <syscall name="remap_file_pages" number="216"/>
+ <syscall name="getdents64" number="217"/>
+ <syscall name="set_tid_address" number="218"/>
+ <syscall name="restart_syscall" number="219"/>
+ <syscall name="semtimedop" number="220"/>
+ <syscall name="fadvise64" number="221"/>
+ <syscall name="timer_create" number="222"/>
+ <syscall name="timer_settime" number="223"/>
+ <syscall name="timer_gettime" number="224"/>
+ <syscall name="timer_getoverrun" number="225"/>
+ <syscall name="timer_delete" number="226"/>
+ <syscall name="clock_settime" number="227"/>
+ <syscall name="clock_gettime" number="228"/>
+ <syscall name="clock_getres" number="229"/>
+ <syscall name="clock_nanosleep" number="230"/>
+ <syscall name="exit_group" number="231"/>
+ <syscall name="epoll_wait" number="232"/>
+ <syscall name="epoll_ctl" number="233"/>
+ <syscall name="tgkill" number="234"/>
+ <syscall name="utimes" number="235"/>
+ <syscall name="vserver" number="236"/>
+ <syscall name="mbind" number="237"/>
+ <syscall name="set_mempolicy" number="238"/>
+ <syscall name="get_mempolicy" number="239"/>
+ <syscall name="mq_open" number="240"/>
+ <syscall name="mq_unlink" number="241"/>
+ <syscall name="mq_timedsend" number="242"/>
+ <syscall name="mq_timedreceive" number="243"/>
+ <syscall name="mq_notify" number="244"/>
+ <syscall name="mq_getsetattr" number="245"/>
+ <syscall name="kexec_load" number="246"/>
+ <syscall name="waitid" number="247"/>
+ <syscall name="add_key" number="248"/>
+ <syscall name="request_key" number="249"/>
+ <syscall name="keyctl" number="250"/>
+ <syscall name="ioprio_set" number="251"/>
+ <syscall name="ioprio_get" number="252"/>
+ <syscall name="inotify_init" number="253"/>
+ <syscall name="inotify_add_watch" number="254"/>
+ <syscall name="inotify_rm_watch" number="255"/>
+ <syscall name="migrate_pages" number="256"/>
+ <syscall name="openat" number="257"/>
+ <syscall name="mkdirat" number="258"/>
+ <syscall name="mknodat" number="259"/>
+ <syscall name="fchownat" number="260"/>
+ <syscall name="futimesat" number="261"/>
+ <syscall name="newfstatat" number="262"/>
+ <syscall name="unlinkat" number="263"/>
+ <syscall name="renameat" number="264"/>
+ <syscall name="linkat" number="265"/>
+ <syscall name="symlinkat" number="266"/>
+ <syscall name="readlinkat" number="267"/>
+ <syscall name="fchmodat" number="268"/>
+ <syscall name="faccessat" number="269"/>
+ <syscall name="pselect6" number="270"/>
+ <syscall name="ppoll" number="271"/>
+ <syscall name="unshare" number="272"/>
+ <syscall name="set_robust_list" number="273"/>
+ <syscall name="get_robust_list" number="274"/>
+ <syscall name="splice" number="275"/>
+ <syscall name="tee" number="276"/>
+ <syscall name="sync_file_range" number="277"/>
+ <syscall name="vmsplice" number="278"/>
+ <syscall name="move_pages" number="279"/>
+ <syscall name="utimensat" number="280"/>
+ <syscall name="epoll_pwait" number="281"/>
+ <syscall name="signalfd" number="282"/>
+ <syscall name="timerfd_create" number="283"/>
+ <syscall name="eventfd" number="284"/>
+ <syscall name="fallocate" number="285"/>
+ <syscall name="timerfd_settime" number="286"/>
+ <syscall name="timerfd_gettime" number="287"/>
+ <syscall name="accept4" number="288"/>
+ <syscall name="signalfd4" number="289"/>
+ <syscall name="eventfd2" number="290"/>
+ <syscall name="epoll_create1" number="291"/>
+ <syscall name="dup3" number="292"/>
+ <syscall name="pipe2" number="293"/>
+ <syscall name="inotify_init1" number="294"/>
+ <syscall name="preadv" number="295"/>
+ <syscall name="pwritev" number="296"/>
+</syscalls_info>
--- /dev/null
+<?xml version="1.0"?>
+<!-- Copyright (C) 2009-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. This file is offered as-is,
+ without any warranty. -->
+
+<!DOCTYPE feature SYSTEM "gdb-syscalls.dtd">
+
+<!-- This file was generated using the following file:
+
+ linux/arch/arm/include/uapi/asm/unistd.h
+
+ The file mentioned above belongs to the Linux Kernel.
+ Some small hand-edits were made. -->
+
+<syscalls_info>
+ <syscall name="restart_syscall" number="0"/>
+ <syscall name="exit" number="1"/>
+ <syscall name="fork" number="2"/>
+ <syscall name="read" number="3"/>
+ <syscall name="write" number="4"/>
+ <syscall name="open" number="5"/>
+ <syscall name="close" number="6"/>
+ <syscall name="waitpid" number="7"/> <!-- removed -->
+ <syscall name="creat" number="8"/>
+ <syscall name="link" number="9"/>
+ <syscall name="unlink" number="10"/>
+ <syscall name="execve" number="11"/>
+ <syscall name="chdir" number="12"/>
+ <syscall name="time" number="13"/>
+ <syscall name="mknod" number="14"/>
+ <syscall name="chmod" number="15"/>
+ <syscall name="lchown" number="16"/>
+ <syscall name="break" number="17"/> <!-- removed -->
+ <syscall name="oldstat" number="18"/> <!-- removed -->
+ <syscall name="lseek" number="19"/>
+ <syscall name="getpid" number="20"/>
+ <syscall name="mount" number="21"/>
+ <syscall name="umount" number="22"/>
+ <syscall name="setuid" number="23"/>
+ <syscall name="getuid" number="24"/>
+ <syscall name="stime" number="25"/>
+ <syscall name="ptrace" number="26"/>
+ <syscall name="alarm" number="27"/>
+ <syscall name="oldfstat" number="28"/> <!-- removed -->
+ <syscall name="pause" number="29"/>
+ <syscall name="utime" number="30"/>
+ <syscall name="stty" number="31"/> <!-- removed -->
+ <syscall name="gtty" number="32"/> <!-- removed -->
+ <syscall name="access" number="33"/>
+ <syscall name="nice" number="34"/>
+ <syscall name="ftime" number="35"/> <!-- removed -->
+ <syscall name="sync" number="36"/>
+ <syscall name="kill" number="37"/>
+ <syscall name="rename" number="38"/>
+ <syscall name="mkdir" number="39"/>
+ <syscall name="rmdir" number="40"/>
+ <syscall name="dup" number="41"/>
+ <syscall name="pipe" number="42"/>
+ <syscall name="times" number="43"/>
+ <syscall name="prof" number="44"/> <!-- removed -->
+ <syscall name="brk" number="45"/>
+ <syscall name="setgid" number="46"/>
+ <syscall name="getgid" number="47"/>
+ <syscall name="signal" number="48"/> <!-- removed -->
+ <syscall name="geteuid" number="49"/>
+ <syscall name="getegid" number="50"/>
+ <syscall name="acct" number="51"/>
+ <syscall name="umount2" number="52"/>
+ <syscall name="lock" number="53"/> <!-- removed -->
+ <syscall name="ioctl" number="54"/>
+ <syscall name="fcntl" number="55"/>
+ <syscall name="mpx" number="56"/> <!-- removed -->
+ <syscall name="setpgid" number="57"/>
+ <syscall name="ulimit" number="58"/> <!-- removed -->
+ <syscall name="oldolduname" number="59"/> <!-- removed -->
+ <syscall name="umask" number="60"/>
+ <syscall name="chroot" number="61"/>
+ <syscall name="ustat" number="62"/>
+ <syscall name="dup2" number="63"/>
+ <syscall name="getppid" number="64"/>
+ <syscall name="getpgrp" number="65"/>
+ <syscall name="setsid" number="66"/>
+ <syscall name="sigaction" number="67"/>
+ <syscall name="sgetmask" number="68"/> <!-- removed -->
+ <syscall name="ssetmask" number="69"/> <!-- removed -->
+ <syscall name="setreuid" number="70"/>
+ <syscall name="setregid" number="71"/>
+ <syscall name="sigsuspend" number="72"/>
+ <syscall name="sigpending" number="73"/>
+ <syscall name="sethostname" number="74"/>
+ <syscall name="setrlimit" number="75"/>
+ <syscall name="getrlimit" number="76"/>
+ <syscall name="getrusage" number="77"/>
+ <syscall name="gettimeofday" number="78"/>
+ <syscall name="settimeofday" number="79"/>
+ <syscall name="getgroups" number="80"/>
+ <syscall name="setgroups" number="81"/>
+ <syscall name="select" number="82"/>
+ <syscall name="symlink" number="83"/>
+ <syscall name="oldlstat" number="84"/> <!-- removed -->
+ <syscall name="readlink" number="85"/>
+ <syscall name="uselib" number="86"/>
+ <syscall name="swapon" number="87"/>
+ <syscall name="reboot" number="88"/>
+ <syscall name="readdir" number="89"/>
+ <syscall name="mmap" number="90"/>
+ <syscall name="munmap" number="91"/>
+ <syscall name="truncate" number="92"/>
+ <syscall name="ftruncate" number="93"/>
+ <syscall name="fchmod" number="94"/>
+ <syscall name="fchown" number="95"/>
+ <syscall name="getpriority" number="96"/>
+ <syscall name="setpriority" number="97"/>
+ <syscall name="profil" number="98"/> <!-- removed -->
+ <syscall name="statfs" number="99"/>
+ <syscall name="fstatfs" number="100"/>
+ <syscall name="ioperm" number="101"/> <!-- removed -->
+ <syscall name="socketcall" number="102"/>
+ <syscall name="syslog" number="103"/>
+ <syscall name="setitimer" number="104"/>
+ <syscall name="getitimer" number="105"/>
+ <syscall name="stat" number="106"/>
+ <syscall name="lstat" number="107"/>
+ <syscall name="fstat" number="108"/>
+ <syscall name="olduname" number="109"/> <!-- removed -->
+ <syscall name="iopl" number="110"/> <!-- removed -->
+ <syscall name="vhangup" number="111"/>
+ <syscall name="idle" number="112"/> <!-- removed -->
+ <syscall name="syscall" number="113"/>
+ <syscall name="wait4" number="114"/>
+ <syscall name="swapoff" number="115"/>
+ <syscall name="sysinfo" number="116"/>
+ <syscall name="ipc" number="117"/>
+ <syscall name="fsync" number="118"/>
+ <syscall name="sigreturn" number="119"/>
+ <syscall name="clone" number="120"/>
+ <syscall name="setdomainname" number="121"/>
+ <syscall name="uname" number="122"/>
+ <syscall name="modify_ldt" number="123"/> <!-- removed -->
+ <syscall name="adjtimex" number="124"/>
+ <syscall name="mprotect" number="125"/>
+ <syscall name="sigprocmask" number="126"/>
+ <syscall name="create_module" number="127"/> <!-- removed -->
+ <syscall name="init_module" number="128"/>
+ <syscall name="delete_module" number="129"/>
+ <syscall name="get_kernel_syms" number="130"/> <!-- removed -->
+ <syscall name="quotactl" number="131"/>
+ <syscall name="getpgid" number="132"/>
+ <syscall name="fchdir" number="133"/>
+ <syscall name="bdflush" number="134"/>
+ <syscall name="sysfs" number="135"/>
+ <syscall name="personality" number="136"/>
+ <syscall name="afs_syscall" number="137"/> <!-- removed -->
+ <syscall name="setfsuid" number="138"/>
+ <syscall name="setfsgid" number="139"/>
+ <syscall name="_llseek" number="140"/>
+ <syscall name="getdents" number="141"/>
+ <syscall name="_newselect" number="142"/>
+ <syscall name="flock" number="143"/>
+ <syscall name="msync" number="144"/>
+ <syscall name="readv" number="145"/>
+ <syscall name="writev" number="146"/>
+ <syscall name="getsid" number="147"/>
+ <syscall name="fdatasync" number="148"/>
+ <syscall name="_sysctl" number="149"/>
+ <syscall name="mlock" number="150"/>
+ <syscall name="munlock" number="151"/>
+ <syscall name="mlockall" number="152"/>
+ <syscall name="munlockall" number="153"/>
+ <syscall name="sched_setparam" number="154"/>
+ <syscall name="sched_getparam" number="155"/>
+ <syscall name="sched_setscheduler" number="156"/>
+ <syscall name="sched_getscheduler" number="157"/>
+ <syscall name="sched_yield" number="158"/>
+ <syscall name="sched_get_priority_max" number="159"/>
+ <syscall name="sched_get_priority_min" number="160"/>
+ <syscall name="sched_rr_get_interval" number="161"/>
+ <syscall name="nanosleep" number="162"/>
+ <syscall name="mremap" number="163"/>
+ <syscall name="setresuid" number="164"/>
+ <syscall name="getresuid" number="165"/>
+ <syscall name="vm86" number="166"/> <!-- removed -->
+ <syscall name="query_module" number="167"/> <!-- removed -->
+ <syscall name="poll" number="168"/>
+ <syscall name="nfsservctl" number="169"/>
+ <syscall name="setresgid" number="170"/>
+ <syscall name="getresgid" number="171"/>
+ <syscall name="prctl" number="172"/>
+ <syscall name="rt_sigreturn" number="173"/>
+ <syscall name="rt_sigaction" number="174"/>
+ <syscall name="rt_sigprocmask" number="175"/>
+ <syscall name="rt_sigpending" number="176"/>
+ <syscall name="rt_sigtimedwait" number="177"/>
+ <syscall name="rt_sigqueueinfo" number="178"/>
+ <syscall name="rt_sigsuspend" number="179"/>
+ <syscall name="pread64" number="180"/>
+ <syscall name="pwrite64" number="181"/>
+ <syscall name="chown" number="182"/>
+ <syscall name="getcwd" number="183"/>
+ <syscall name="capget" number="184"/>
+ <syscall name="capset" number="185"/>
+ <syscall name="sigaltstack" number="186"/>
+ <syscall name="sendfile" number="187"/>
+ <syscall name="vfork" number="190"/>
+ <syscall name="ugetrlimit" number="191"/>
+ <syscall name="mmap2" number="192"/>
+ <syscall name="truncate64" number="193"/>
+ <syscall name="ftruncate64" number="194"/>
+ <syscall name="stat64" number="195"/>
+ <syscall name="lstat64" number="196"/>
+ <syscall name="fstat64" number="197"/>
+ <syscall name="lchown32" number="198"/>
+ <syscall name="getuid32" number="199"/>
+ <syscall name="getgid32" number="200"/>
+ <syscall name="geteuid32" number="201"/>
+ <syscall name="getegid32" number="202"/>
+ <syscall name="setreuid32" number="203"/>
+ <syscall name="setregid32" number="204"/>
+ <syscall name="getgroups32" number="205"/>
+ <syscall name="setgroups32" number="206"/>
+ <syscall name="fchown32" number="207"/>
+ <syscall name="setresuid32" number="208"/>
+ <syscall name="getresuid32" number="209"/>
+ <syscall name="setresgid32" number="210"/>
+ <syscall name="getresgid32" number="211"/>
+ <syscall name="chown32" number="212"/>
+ <syscall name="setuid32" number="213"/>
+ <syscall name="setgid32" number="214"/>
+ <syscall name="setfsuid32" number="215"/>
+ <syscall name="setfsgid32" number="216"/>
+ <syscall name="getdents64" number="217"/>
+ <syscall name="pivot_root" number="218"/>
+ <syscall name="mincore" number="219"/>
+ <syscall name="madvise" number="220"/>
+ <syscall name="fcntl64" number="221"/>
+ <syscall name="gettid" number="224"/>
+ <syscall name="readahead" number="225"/>
+ <syscall name="setxattr" number="226"/>
+ <syscall name="lsetxattr" number="227"/>
+ <syscall name="fsetxattr" number="228"/>
+ <syscall name="getxattr" number="229"/>
+ <syscall name="lgetxattr" number="230"/>
+ <syscall name="fgetxattr" number="231"/>
+ <syscall name="listxattr" number="232"/>
+ <syscall name="llistxattr" number="233"/>
+ <syscall name="flistxattr" number="234"/>
+ <syscall name="removexattr" number="235"/>
+ <syscall name="lremovexattr" number="236"/>
+ <syscall name="fremovexattr" number="237"/>
+ <syscall name="tkill" number="238"/>
+ <syscall name="sendfile64" number="239"/>
+ <syscall name="futex" number="240"/>
+ <syscall name="sched_setaffinity" number="241"/>
+ <syscall name="sched_getaffinity" number="242"/>
+ <syscall name="io_setup" number="243"/>
+ <syscall name="io_destroy" number="244"/>
+ <syscall name="io_getevents" number="245"/>
+ <syscall name="io_submit" number="246"/>
+ <syscall name="io_cancel" number="247"/>
+ <syscall name="exit_group" number="248"/>
+ <syscall name="lookup_dcookie" number="249"/>
+ <syscall name="epoll_create" number="250"/>
+ <syscall name="epoll_ctl" number="251"/>
+ <syscall name="epoll_wait" number="252"/>
+ <syscall name="remap_file_pages" number="253"/>
+ <syscall name="set_tid_address" number="256"/>
+ <syscall name="timer_create" number="257"/>
+ <syscall name="timer_settime" number="258"/>
+ <syscall name="timer_gettime" number="259"/>
+ <syscall name="timer_getoverrun" number="260"/>
+ <syscall name="timer_delete" number="261"/>
+ <syscall name="clock_settime" number="262"/>
+ <syscall name="clock_gettime" number="263"/>
+ <syscall name="clock_getres" number="264"/>
+ <syscall name="clock_nanosleep" number="265"/>
+ <syscall name="statfs64" number="266"/>
+ <syscall name="fstatfs64" number="267"/>
+ <syscall name="tgkill" number="268"/>
+ <syscall name="utimes" number="269"/>
+ <syscall name="arm_fadvise64_64" number="270"/>
+ <syscall name="pciconfig_iobase" number="271"/>
+ <syscall name="pciconfig_read" number="272"/>
+ <syscall name="pciconfig_write" number="273"/>
+ <syscall name="mq_open" number="274"/>
+ <syscall name="mq_unlink" number="275"/>
+ <syscall name="mq_timedsend" number="276"/>
+ <syscall name="mq_timedreceive" number="277"/>
+ <syscall name="mq_notify" number="278"/>
+ <syscall name="mq_getsetattr" number="279"/>
+ <syscall name="waitid" number="280"/>
+ <syscall name="socket" number="281"/>
+ <syscall name="bind" number="282"/>
+ <syscall name="connect" number="283"/>
+ <syscall name="listen" number="284"/>
+ <syscall name="accept" number="285"/>
+ <syscall name="getsockname" number="286"/>
+ <syscall name="getpeername" number="287"/>
+ <syscall name="socketpair" number="288"/>
+ <syscall name="send" number="289"/>
+ <syscall name="sendto" number="290"/>
+ <syscall name="recv" number="291"/>
+ <syscall name="recvfrom" number="292"/>
+ <syscall name="shutdown" number="293"/>
+ <syscall name="setsockopt" number="294"/>
+ <syscall name="getsockopt" number="295"/>
+ <syscall name="sendmsg" number="296"/>
+ <syscall name="recvmsg" number="297"/>
+ <syscall name="semop" number="298"/>
+ <syscall name="semget" number="299"/>
+ <syscall name="semctl" number="300"/>
+ <syscall name="msgsnd" number="301"/>
+ <syscall name="msgrcv" number="302"/>
+ <syscall name="msgget" number="303"/>
+ <syscall name="msgctl" number="304"/>
+ <syscall name="shmat" number="305"/>
+ <syscall name="shmdt" number="306"/>
+ <syscall name="shmget" number="307"/>
+ <syscall name="shmctl" number="308"/>
+ <syscall name="add_key" number="309"/>
+ <syscall name="request_key" number="310"/>
+ <syscall name="keyctl" number="311"/>
+ <syscall name="semtimedop" number="312"/>
+ <syscall name="vserver" number="313"/>
+ <syscall name="ioprio_set" number="314"/>
+ <syscall name="ioprio_get" number="315"/>
+ <syscall name="inotify_init" number="316"/>
+ <syscall name="inotify_add_watch" number="317"/>
+ <syscall name="inotify_rm_watch" number="318"/>
+ <syscall name="mbind" number="319"/>
+ <syscall name="get_mempolicy" number="320"/>
+ <syscall name="set_mempolicy" number="321"/>
+ <syscall name="openat" number="322"/>
+ <syscall name="mkdirat" number="323"/>
+ <syscall name="mknodat" number="324"/>
+ <syscall name="fchownat" number="325"/>
+ <syscall name="futimesat" number="326"/>
+ <syscall name="fstatat64" number="327"/>
+ <syscall name="unlinkat" number="328"/>
+ <syscall name="renameat" number="329"/>
+ <syscall name="linkat" number="330"/>
+ <syscall name="symlinkat" number="331"/>
+ <syscall name="readlinkat" number="332"/>
+ <syscall name="fchmodat" number="333"/>
+ <syscall name="faccessat" number="334"/>
+ <syscall name="pselect6" number="335"/>
+ <syscall name="ppoll" number="336"/>
+ <syscall name="unshare" number="337"/>
+ <syscall name="set_robust_list" number="338"/>
+ <syscall name="get_robust_list" number="339"/>
+ <syscall name="splice" number="340"/>
+ <syscall name="arm_sync_file_range" number="341"/>
+ <syscall name="tee" number="342"/>
+ <syscall name="vmsplice" number="343"/>
+ <syscall name="move_pages" number="344"/>
+ <syscall name="getcpu" number="345"/>
+ <syscall name="epoll_pwait" number="346"/>
+ <syscall name="kexec_load" number="347"/>
+ <syscall name="utimensat" number="348"/>
+ <syscall name="signalfd" number="349"/>
+ <syscall name="timerfd_create" number="350"/>
+ <syscall name="eventfd" number="351"/>
+ <syscall name="fallocate" number="352"/>
+ <syscall name="timerfd_settime" number="353"/>
+ <syscall name="timerfd_gettime" number="354"/>
+ <syscall name="signalfd4" number="355"/>
+ <syscall name="eventfd2" number="356"/>
+ <syscall name="epoll_create1" number="357"/>
+ <syscall name="dup3" number="358"/>
+ <syscall name="pipe2" number="359"/>
+ <syscall name="inotify_init1" number="360"/>
+ <syscall name="preadv" number="361"/>
+ <syscall name="pwritev" number="362"/>
+ <syscall name="rt_tgsigqueueinfo" number="363"/>
+ <syscall name="perf_event_open" number="364"/>
+ <syscall name="recvmmsg" number="365"/>
+ <syscall name="accept4" number="366"/>
+ <syscall name="fanotify_init" number="367"/>
+ <syscall name="fanotify_mark" number="368"/>
+ <syscall name="prlimit64" number="369"/>
+ <syscall name="name_to_handle_at" number="370"/>
+ <syscall name="open_by_handle_at" number="371"/>
+ <syscall name="clock_adjtime" number="372"/>
+ <syscall name="syncfs" number="373"/>
+ <syscall name="sendmmsg" number="374"/>
+ <syscall name="setns" number="375"/>
+ <syscall name="process_vm_readv" number="376"/>
+ <syscall name="process_vm_writev" number="377"/>
+ <syscall name="kcmp" number="378"/>
+ <syscall name="finit_module" number="379"/>
+ <syscall name="ARM_breakpoint" number="983041"/>
+ <syscall name="ARM_cacheflush" number="983042"/>
+ <syscall name="ARM_usr26" number="983043"/>
+ <syscall name="ARM_usr32" number="983044"/>
+ <syscall name="ARM_set_tls" number="983045"/>
+</syscalls_info>
--- /dev/null
+<!-- Copyright (C) 2009-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. -->
+
+<!-- The root element of a syscall info is <syscalls-info>. -->
+
+<!ELEMENT syscalls-info (syscall*)>
+
+<!ELEMENT syscall EMPTY>
+<!ATTLIST syscall
+ name CDATA #REQUIRED
+ number CDATA #REQUIRED>
--- /dev/null
+<?xml version="1.0"?>
+<!-- Copyright (C) 2009-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. -->
+
+<!DOCTYPE feature SYSTEM "gdb-syscalls.dtd">
+
+<!-- This file was generated using the following file:
+
+ /usr/src/linux/arch/x86/include/asm/unistd_32.h
+
+ The file mentioned above belongs to the Linux Kernel. -->
+
+<syscalls_info>
+ <syscall name="restart_syscall" number="0"/>
+ <syscall name="exit" number="1"/>
+ <syscall name="fork" number="2"/>
+ <syscall name="read" number="3"/>
+ <syscall name="write" number="4"/>
+ <syscall name="open" number="5"/>
+ <syscall name="close" number="6"/>
+ <syscall name="waitpid" number="7"/>
+ <syscall name="creat" number="8"/>
+ <syscall name="link" number="9"/>
+ <syscall name="unlink" number="10"/>
+ <syscall name="execve" number="11"/>
+ <syscall name="chdir" number="12"/>
+ <syscall name="time" number="13"/>
+ <syscall name="mknod" number="14"/>
+ <syscall name="chmod" number="15"/>
+ <syscall name="lchown" number="16"/>
+ <syscall name="break" number="17"/>
+ <syscall name="oldstat" number="18"/>
+ <syscall name="lseek" number="19"/>
+ <syscall name="getpid" number="20"/>
+ <syscall name="mount" number="21"/>
+ <syscall name="umount" number="22"/>
+ <syscall name="setuid" number="23"/>
+ <syscall name="getuid" number="24"/>
+ <syscall name="stime" number="25"/>
+ <syscall name="ptrace" number="26"/>
+ <syscall name="alarm" number="27"/>
+ <syscall name="oldfstat" number="28"/>
+ <syscall name="pause" number="29"/>
+ <syscall name="utime" number="30"/>
+ <syscall name="stty" number="31"/>
+ <syscall name="gtty" number="32"/>
+ <syscall name="access" number="33"/>
+ <syscall name="nice" number="34"/>
+ <syscall name="ftime" number="35"/>
+ <syscall name="sync" number="36"/>
+ <syscall name="kill" number="37"/>
+ <syscall name="rename" number="38"/>
+ <syscall name="mkdir" number="39"/>
+ <syscall name="rmdir" number="40"/>
+ <syscall name="dup" number="41"/>
+ <syscall name="pipe" number="42"/>
+ <syscall name="times" number="43"/>
+ <syscall name="prof" number="44"/>
+ <syscall name="brk" number="45"/>
+ <syscall name="setgid" number="46"/>
+ <syscall name="getgid" number="47"/>
+ <syscall name="signal" number="48"/>
+ <syscall name="geteuid" number="49"/>
+ <syscall name="getegid" number="50"/>
+ <syscall name="acct" number="51"/>
+ <syscall name="umount2" number="52"/>
+ <syscall name="lock" number="53"/>
+ <syscall name="ioctl" number="54"/>
+ <syscall name="fcntl" number="55"/>
+ <syscall name="mpx" number="56"/>
+ <syscall name="setpgid" number="57"/>
+ <syscall name="ulimit" number="58"/>
+ <syscall name="oldolduname" number="59"/>
+ <syscall name="umask" number="60"/>
+ <syscall name="chroot" number="61"/>
+ <syscall name="ustat" number="62"/>
+ <syscall name="dup2" number="63"/>
+ <syscall name="getppid" number="64"/>
+ <syscall name="getpgrp" number="65"/>
+ <syscall name="setsid" number="66"/>
+ <syscall name="sigaction" number="67"/>
+ <syscall name="sgetmask" number="68"/>
+ <syscall name="ssetmask" number="69"/>
+ <syscall name="setreuid" number="70"/>
+ <syscall name="setregid" number="71"/>
+ <syscall name="sigsuspend" number="72"/>
+ <syscall name="sigpending" number="73"/>
+ <syscall name="sethostname" number="74"/>
+ <syscall name="setrlimit" number="75"/>
+ <syscall name="getrlimit" number="76"/>
+ <syscall name="getrusage" number="77"/>
+ <syscall name="gettimeofday" number="78"/>
+ <syscall name="settimeofday" number="79"/>
+ <syscall name="getgroups" number="80"/>
+ <syscall name="setgroups" number="81"/>
+ <syscall name="select" number="82"/>
+ <syscall name="symlink" number="83"/>
+ <syscall name="oldlstat" number="84"/>
+ <syscall name="readlink" number="85"/>
+ <syscall name="uselib" number="86"/>
+ <syscall name="swapon" number="87"/>
+ <syscall name="reboot" number="88"/>
+ <syscall name="readdir" number="89"/>
+ <syscall name="mmap" number="90"/>
+ <syscall name="munmap" number="91"/>
+ <syscall name="truncate" number="92"/>
+ <syscall name="ftruncate" number="93"/>
+ <syscall name="fchmod" number="94"/>
+ <syscall name="fchown" number="95"/>
+ <syscall name="getpriority" number="96"/>
+ <syscall name="setpriority" number="97"/>
+ <syscall name="profil" number="98"/>
+ <syscall name="statfs" number="99"/>
+ <syscall name="fstatfs" number="100"/>
+ <syscall name="ioperm" number="101"/>
+ <syscall name="socketcall" number="102"/>
+ <syscall name="syslog" number="103"/>
+ <syscall name="setitimer" number="104"/>
+ <syscall name="getitimer" number="105"/>
+ <syscall name="stat" number="106"/>
+ <syscall name="lstat" number="107"/>
+ <syscall name="fstat" number="108"/>
+ <syscall name="olduname" number="109"/>
+ <syscall name="iopl" number="110"/>
+ <syscall name="vhangup" number="111"/>
+ <syscall name="idle" number="112"/>
+ <syscall name="vm86old" number="113"/>
+ <syscall name="wait4" number="114"/>
+ <syscall name="swapoff" number="115"/>
+ <syscall name="sysinfo" number="116"/>
+ <syscall name="ipc" number="117"/>
+ <syscall name="fsync" number="118"/>
+ <syscall name="sigreturn" number="119"/>
+ <syscall name="clone" number="120"/>
+ <syscall name="setdomainname" number="121"/>
+ <syscall name="uname" number="122"/>
+ <syscall name="modify_ldt" number="123"/>
+ <syscall name="adjtimex" number="124"/>
+ <syscall name="mprotect" number="125"/>
+ <syscall name="sigprocmask" number="126"/>
+ <syscall name="create_module" number="127"/>
+ <syscall name="init_module" number="128"/>
+ <syscall name="delete_module" number="129"/>
+ <syscall name="get_kernel_syms" number="130"/>
+ <syscall name="quotactl" number="131"/>
+ <syscall name="getpgid" number="132"/>
+ <syscall name="fchdir" number="133"/>
+ <syscall name="bdflush" number="134"/>
+ <syscall name="sysfs" number="135"/>
+ <syscall name="personality" number="136"/>
+ <syscall name="afs_syscall" number="137"/>
+ <syscall name="setfsuid" number="138"/>
+ <syscall name="setfsgid" number="139"/>
+ <syscall name="_llseek" number="140"/>
+ <syscall name="getdents" number="141"/>
+ <syscall name="_newselect" number="142"/>
+ <syscall name="flock" number="143"/>
+ <syscall name="msync" number="144"/>
+ <syscall name="readv" number="145"/>
+ <syscall name="writev" number="146"/>
+ <syscall name="getsid" number="147"/>
+ <syscall name="fdatasync" number="148"/>
+ <syscall name="_sysctl" number="149"/>
+ <syscall name="mlock" number="150"/>
+ <syscall name="munlock" number="151"/>
+ <syscall name="mlockall" number="152"/>
+ <syscall name="munlockall" number="153"/>
+ <syscall name="sched_setparam" number="154"/>
+ <syscall name="sched_getparam" number="155"/>
+ <syscall name="sched_setscheduler" number="156"/>
+ <syscall name="sched_getscheduler" number="157"/>
+ <syscall name="sched_yield" number="158"/>
+ <syscall name="sched_get_priority_max" number="159"/>
+ <syscall name="sched_get_priority_min" number="160"/>
+ <syscall name="sched_rr_get_interval" number="161"/>
+ <syscall name="nanosleep" number="162"/>
+ <syscall name="mremap" number="163"/>
+ <syscall name="setresuid" number="164"/>
+ <syscall name="getresuid" number="165"/>
+ <syscall name="vm86" number="166"/>
+ <syscall name="query_module" number="167"/>
+ <syscall name="poll" number="168"/>
+ <syscall name="nfsservctl" number="169"/>
+ <syscall name="setresgid" number="170"/>
+ <syscall name="getresgid" number="171"/>
+ <syscall name="prctl" number="172"/>
+ <syscall name="rt_sigreturn" number="173"/>
+ <syscall name="rt_sigaction" number="174"/>
+ <syscall name="rt_sigprocmask" number="175"/>
+ <syscall name="rt_sigpending" number="176"/>
+ <syscall name="rt_sigtimedwait" number="177"/>
+ <syscall name="rt_sigqueueinfo" number="178"/>
+ <syscall name="rt_sigsuspend" number="179"/>
+ <syscall name="pread64" number="180"/>
+ <syscall name="pwrite64" number="181"/>
+ <syscall name="chown" number="182"/>
+ <syscall name="getcwd" number="183"/>
+ <syscall name="capget" number="184"/>
+ <syscall name="capset" number="185"/>
+ <syscall name="sigaltstack" number="186"/>
+ <syscall name="sendfile" number="187"/>
+ <syscall name="getpmsg" number="188"/>
+ <syscall name="putpmsg" number="189"/>
+ <syscall name="vfork" number="190"/>
+ <syscall name="ugetrlimit" number="191"/>
+ <syscall name="mmap2" number="192"/>
+ <syscall name="truncate64" number="193"/>
+ <syscall name="ftruncate64" number="194"/>
+ <syscall name="stat64" number="195"/>
+ <syscall name="lstat64" number="196"/>
+ <syscall name="fstat64" number="197"/>
+ <syscall name="lchown32" number="198"/>
+ <syscall name="getuid32" number="199"/>
+ <syscall name="getgid32" number="200"/>
+ <syscall name="geteuid32" number="201"/>
+ <syscall name="getegid32" number="202"/>
+ <syscall name="setreuid32" number="203"/>
+ <syscall name="setregid32" number="204"/>
+ <syscall name="getgroups32" number="205"/>
+ <syscall name="setgroups32" number="206"/>
+ <syscall name="fchown32" number="207"/>
+ <syscall name="setresuid32" number="208"/>
+ <syscall name="getresuid32" number="209"/>
+ <syscall name="setresgid32" number="210"/>
+ <syscall name="getresgid32" number="211"/>
+ <syscall name="chown32" number="212"/>
+ <syscall name="setuid32" number="213"/>
+ <syscall name="setgid32" number="214"/>
+ <syscall name="setfsuid32" number="215"/>
+ <syscall name="setfsgid32" number="216"/>
+ <syscall name="pivot_root" number="217"/>
+ <syscall name="mincore" number="218"/>
+ <syscall name="madvise" number="219"/>
+ <syscall name="madvise1" number="220"/>
+ <syscall name="getdents64" number="221"/>
+ <syscall name="fcntl64" number="222"/>
+ <syscall name="gettid" number="224"/>
+ <syscall name="readahead" number="225"/>
+ <syscall name="setxattr" number="226"/>
+ <syscall name="lsetxattr" number="227"/>
+ <syscall name="fsetxattr" number="228"/>
+ <syscall name="getxattr" number="229"/>
+ <syscall name="lgetxattr" number="230"/>
+ <syscall name="fgetxattr" number="231"/>
+ <syscall name="listxattr" number="232"/>
+ <syscall name="llistxattr" number="233"/>
+ <syscall name="flistxattr" number="234"/>
+ <syscall name="removexattr" number="235"/>
+ <syscall name="lremovexattr" number="236"/>
+ <syscall name="fremovexattr" number="237"/>
+ <syscall name="tkill" number="238"/>
+ <syscall name="sendfile64" number="239"/>
+ <syscall name="futex" number="240"/>
+ <syscall name="sched_setaffinity" number="241"/>
+ <syscall name="sched_getaffinity" number="242"/>
+ <syscall name="set_thread_area" number="243"/>
+ <syscall name="get_thread_area" number="244"/>
+ <syscall name="io_setup" number="245"/>
+ <syscall name="io_destroy" number="246"/>
+ <syscall name="io_getevents" number="247"/>
+ <syscall name="io_submit" number="248"/>
+ <syscall name="io_cancel" number="249"/>
+ <syscall name="fadvise64" number="250"/>
+ <syscall name="exit_group" number="252"/>
+ <syscall name="lookup_dcookie" number="253"/>
+ <syscall name="epoll_create" number="254"/>
+ <syscall name="epoll_ctl" number="255"/>
+ <syscall name="epoll_wait" number="256"/>
+ <syscall name="remap_file_pages" number="257"/>
+ <syscall name="set_tid_address" number="258"/>
+ <syscall name="timer_create" number="259"/>
+ <syscall name="timer_settime" number="260"/>
+ <syscall name="timer_gettime" number="261"/>
+ <syscall name="timer_getoverrun" number="262"/>
+ <syscall name="timer_delete" number="263"/>
+ <syscall name="clock_settime" number="264"/>
+ <syscall name="clock_gettime" number="265"/>
+ <syscall name="clock_getres" number="266"/>
+ <syscall name="clock_nanosleep" number="267"/>
+ <syscall name="statfs64" number="268"/>
+ <syscall name="fstatfs64" number="269"/>
+ <syscall name="tgkill" number="270"/>
+ <syscall name="utimes" number="271"/>
+ <syscall name="fadvise64_64" number="272"/>
+ <syscall name="vserver" number="273"/>
+ <syscall name="mbind" number="274"/>
+ <syscall name="get_mempolicy" number="275"/>
+ <syscall name="set_mempolicy" number="276"/>
+ <syscall name="mq_open" number="277"/>
+ <syscall name="mq_unlink" number="278"/>
+ <syscall name="mq_timedsend" number="279"/>
+ <syscall name="mq_timedreceive" number="280"/>
+ <syscall name="mq_notify" number="281"/>
+ <syscall name="mq_getsetattr" number="282"/>
+ <syscall name="kexec_load" number="283"/>
+ <syscall name="waitid" number="284"/>
+ <syscall name="add_key" number="286"/>
+ <syscall name="request_key" number="287"/>
+ <syscall name="keyctl" number="288"/>
+ <syscall name="ioprio_set" number="289"/>
+ <syscall name="ioprio_get" number="290"/>
+ <syscall name="inotify_init" number="291"/>
+ <syscall name="inotify_add_watch" number="292"/>
+ <syscall name="inotify_rm_watch" number="293"/>
+ <syscall name="migrate_pages" number="294"/>
+ <syscall name="openat" number="295"/>
+ <syscall name="mkdirat" number="296"/>
+ <syscall name="mknodat" number="297"/>
+ <syscall name="fchownat" number="298"/>
+ <syscall name="futimesat" number="299"/>
+ <syscall name="fstatat64" number="300"/>
+ <syscall name="unlinkat" number="301"/>
+ <syscall name="renameat" number="302"/>
+ <syscall name="linkat" number="303"/>
+ <syscall name="symlinkat" number="304"/>
+ <syscall name="readlinkat" number="305"/>
+ <syscall name="fchmodat" number="306"/>
+ <syscall name="faccessat" number="307"/>
+ <syscall name="pselect6" number="308"/>
+ <syscall name="ppoll" number="309"/>
+ <syscall name="unshare" number="310"/>
+ <syscall name="set_robust_list" number="311"/>
+ <syscall name="get_robust_list" number="312"/>
+ <syscall name="splice" number="313"/>
+ <syscall name="sync_file_range" number="314"/>
+ <syscall name="tee" number="315"/>
+ <syscall name="vmsplice" number="316"/>
+ <syscall name="move_pages" number="317"/>
+ <syscall name="getcpu" number="318"/>
+ <syscall name="epoll_pwait" number="319"/>
+ <syscall name="utimensat" number="320"/>
+ <syscall name="signalfd" number="321"/>
+ <syscall name="timerfd_create" number="322"/>
+ <syscall name="eventfd" number="323"/>
+ <syscall name="fallocate" number="324"/>
+ <syscall name="timerfd_settime" number="325"/>
+</syscalls_info>
--- /dev/null
+<?xml version="1.0"?>
+<!-- Copyright (C) 2011-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. -->
+
+<!DOCTYPE feature SYSTEM "gdb-syscalls.dtd">
+
+<!-- This file was generated using the following file:
+
+ /usr/src/linux/arch/mips/include/asm/unistd.h
+
+ The file mentioned above belongs to the Linux Kernel. -->
+
+<syscalls_info>
+ <syscall name="read" number="6000"/>
+ <syscall name="write" number="6001"/>
+ <syscall name="open" number="6002"/>
+ <syscall name="close" number="6003"/>
+ <syscall name="stat" number="6004"/>
+ <syscall name="fstat" number="6005"/>
+ <syscall name="lstat" number="6006"/>
+ <syscall name="poll" number="6007"/>
+ <syscall name="lseek" number="6008"/>
+ <syscall name="mmap" number="6009"/>
+ <syscall name="mprotect" number="6010"/>
+ <syscall name="munmap" number="6011"/>
+ <syscall name="brk" number="6012"/>
+ <syscall name="rt_sigaction" number="6013"/>
+ <syscall name="rt_sigprocmask" number="6014"/>
+ <syscall name="ioctl" number="6015"/>
+ <syscall name="pread64" number="6016"/>
+ <syscall name="pwrite64" number="6017"/>
+ <syscall name="readv" number="6018"/>
+ <syscall name="writev" number="6019"/>
+ <syscall name="access" number="6020"/>
+ <syscall name="pipe" number="6021"/>
+ <syscall name="_newselect" number="6022"/>
+ <syscall name="sched_yield" number="6023"/>
+ <syscall name="mremap" number="6024"/>
+ <syscall name="msync" number="6025"/>
+ <syscall name="mincore" number="6026"/>
+ <syscall name="madvise" number="6027"/>
+ <syscall name="shmget" number="6028"/>
+ <syscall name="shmat" number="6029"/>
+ <syscall name="shmctl" number="6030"/>
+ <syscall name="dup" number="6031"/>
+ <syscall name="dup2" number="6032"/>
+ <syscall name="pause" number="6033"/>
+ <syscall name="nanosleep" number="6034"/>
+ <syscall name="getitimer" number="6035"/>
+ <syscall name="setitimer" number="6036"/>
+ <syscall name="alarm" number="6037"/>
+ <syscall name="getpid" number="6038"/>
+ <syscall name="sendfile" number="6039"/>
+ <syscall name="socket" number="6040"/>
+ <syscall name="connect" number="6041"/>
+ <syscall name="accept" number="6042"/>
+ <syscall name="sendto" number="6043"/>
+ <syscall name="recvfrom" number="6044"/>
+ <syscall name="sendmsg" number="6045"/>
+ <syscall name="recvmsg" number="6046"/>
+ <syscall name="shutdown" number="6047"/>
+ <syscall name="bind" number="6048"/>
+ <syscall name="listen" number="6049"/>
+ <syscall name="getsockname" number="6050"/>
+ <syscall name="getpeername" number="6051"/>
+ <syscall name="socketpair" number="6052"/>
+ <syscall name="setsockopt" number="6053"/>
+ <syscall name="getsockopt" number="6054"/>
+ <syscall name="clone" number="6055"/>
+ <syscall name="fork" number="6056"/>
+ <syscall name="execve" number="6057"/>
+ <syscall name="exit" number="6058"/>
+ <syscall name="wait4" number="6059"/>
+ <syscall name="kill" number="6060"/>
+ <syscall name="uname" number="6061"/>
+ <syscall name="semget" number="6062"/>
+ <syscall name="semop" number="6063"/>
+ <syscall name="semctl" number="6064"/>
+ <syscall name="shmdt" number="6065"/>
+ <syscall name="msgget" number="6066"/>
+ <syscall name="msgsnd" number="6067"/>
+ <syscall name="msgrcv" number="6068"/>
+ <syscall name="msgctl" number="6069"/>
+ <syscall name="fcntl" number="6070"/>
+ <syscall name="flock" number="6071"/>
+ <syscall name="fsync" number="6072"/>
+ <syscall name="fdatasync" number="6073"/>
+ <syscall name="truncate" number="6074"/>
+ <syscall name="ftruncate" number="6075"/>
+ <syscall name="getdents" number="6076"/>
+ <syscall name="getcwd" number="6077"/>
+ <syscall name="chdir" number="6078"/>
+ <syscall name="fchdir" number="6079"/>
+ <syscall name="rename" number="6080"/>
+ <syscall name="mkdir" number="6081"/>
+ <syscall name="rmdir" number="6082"/>
+ <syscall name="creat" number="6083"/>
+ <syscall name="link" number="6084"/>
+ <syscall name="unlink" number="6085"/>
+ <syscall name="symlink" number="6086"/>
+ <syscall name="readlink" number="6087"/>
+ <syscall name="chmod" number="6088"/>
+ <syscall name="fchmod" number="6089"/>
+ <syscall name="chown" number="6090"/>
+ <syscall name="fchown" number="6091"/>
+ <syscall name="lchown" number="6092"/>
+ <syscall name="umask" number="6093"/>
+ <syscall name="gettimeofday" number="6094"/>
+ <syscall name="getrlimit" number="6095"/>
+ <syscall name="getrusage" number="6096"/>
+ <syscall name="sysinfo" number="6097"/>
+ <syscall name="times" number="6098"/>
+ <syscall name="ptrace" number="6099"/>
+ <syscall name="getuid" number="6100"/>
+ <syscall name="syslog" number="6101"/>
+ <syscall name="getgid" number="6102"/>
+ <syscall name="setuid" number="6103"/>
+ <syscall name="setgid" number="6104"/>
+ <syscall name="geteuid" number="6105"/>
+ <syscall name="getegid" number="6106"/>
+ <syscall name="setpgid" number="6107"/>
+ <syscall name="getppid" number="6108"/>
+ <syscall name="getpgrp" number="6109"/>
+ <syscall name="setsid" number="6110"/>
+ <syscall name="setreuid" number="6111"/>
+ <syscall name="setregid" number="6112"/>
+ <syscall name="getgroups" number="6113"/>
+ <syscall name="setgroups" number="6114"/>
+ <syscall name="setresuid" number="6115"/>
+ <syscall name="getresuid" number="6116"/>
+ <syscall name="setresgid" number="6117"/>
+ <syscall name="getresgid" number="6118"/>
+ <syscall name="getpgid" number="6119"/>
+ <syscall name="setfsuid" number="6120"/>
+ <syscall name="setfsgid" number="6121"/>
+ <syscall name="getsid" number="6122"/>
+ <syscall name="capget" number="6123"/>
+ <syscall name="capset" number="6124"/>
+ <syscall name="rt_sigpending" number="6125"/>
+ <syscall name="rt_sigtimedwait" number="6126"/>
+ <syscall name="rt_sigqueueinfo" number="6127"/>
+ <syscall name="rt_sigsuspend" number="6128"/>
+ <syscall name="sigaltstack" number="6129"/>
+ <syscall name="utime" number="6130"/>
+ <syscall name="mknod" number="6131"/>
+ <syscall name="personality" number="6132"/>
+ <syscall name="ustat" number="6133"/>
+ <syscall name="statfs" number="6134"/>
+ <syscall name="fstatfs" number="6135"/>
+ <syscall name="sysfs" number="6136"/>
+ <syscall name="getpriority" number="6137"/>
+ <syscall name="setpriority" number="6138"/>
+ <syscall name="sched_setparam" number="6139"/>
+ <syscall name="sched_getparam" number="6140"/>
+ <syscall name="sched_setscheduler" number="6141"/>
+ <syscall name="sched_getscheduler" number="6142"/>
+ <syscall name="sched_get_priority_max" number="6143"/>
+ <syscall name="sched_get_priority_min" number="6144"/>
+ <syscall name="sched_rr_get_interval" number="6145"/>
+ <syscall name="mlock" number="6146"/>
+ <syscall name="munlock" number="6147"/>
+ <syscall name="mlockall" number="6148"/>
+ <syscall name="munlockall" number="6149"/>
+ <syscall name="vhangup" number="6150"/>
+ <syscall name="pivot_root" number="6151"/>
+ <syscall name="_sysctl" number="6152"/>
+ <syscall name="prctl" number="6153"/>
+ <syscall name="adjtimex" number="6154"/>
+ <syscall name="setrlimit" number="6155"/>
+ <syscall name="chroot" number="6156"/>
+ <syscall name="sync" number="6157"/>
+ <syscall name="acct" number="6158"/>
+ <syscall name="settimeofday" number="6159"/>
+ <syscall name="mount" number="6160"/>
+ <syscall name="umount2" number="6161"/>
+ <syscall name="swapon" number="6162"/>
+ <syscall name="swapoff" number="6163"/>
+ <syscall name="reboot" number="6164"/>
+ <syscall name="sethostname" number="6165"/>
+ <syscall name="setdomainname" number="6166"/>
+ <syscall name="create_module" number="6167"/>
+ <syscall name="init_module" number="6168"/>
+ <syscall name="delete_module" number="6169"/>
+ <syscall name="get_kernel_syms" number="6170"/>
+ <syscall name="query_module" number="6171"/>
+ <syscall name="quotactl" number="6172"/>
+ <syscall name="nfsservctl" number="6173"/>
+ <syscall name="getpmsg" number="6174"/>
+ <syscall name="putpmsg" number="6175"/>
+ <syscall name="afs_syscall" number="6176"/>
+ <syscall name="reserved177" number="6177"/>
+ <syscall name="gettid" number="6178"/>
+ <syscall name="readahead" number="6179"/>
+ <syscall name="setxattr" number="6180"/>
+ <syscall name="lsetxattr" number="6181"/>
+ <syscall name="fsetxattr" number="6182"/>
+ <syscall name="getxattr" number="6183"/>
+ <syscall name="lgetxattr" number="6184"/>
+ <syscall name="fgetxattr" number="6185"/>
+ <syscall name="listxattr" number="6186"/>
+ <syscall name="llistxattr" number="6187"/>
+ <syscall name="flistxattr" number="6188"/>
+ <syscall name="removexattr" number="6189"/>
+ <syscall name="lremovexattr" number="6190"/>
+ <syscall name="fremovexattr" number="6191"/>
+ <syscall name="tkill" number="6192"/>
+ <syscall name="reserved193" number="6193"/>
+ <syscall name="futex" number="6194"/>
+ <syscall name="sched_setaffinity" number="6195"/>
+ <syscall name="sched_getaffinity" number="6196"/>
+ <syscall name="cacheflush" number="6197"/>
+ <syscall name="cachectl" number="6198"/>
+ <syscall name="sysmips" number="6199"/>
+ <syscall name="io_setup" number="6200"/>
+ <syscall name="io_destroy" number="6201"/>
+ <syscall name="io_getevents" number="6202"/>
+ <syscall name="io_submit" number="6203"/>
+ <syscall name="io_cancel" number="6204"/>
+ <syscall name="exit_group" number="6205"/>
+ <syscall name="lookup_dcookie" number="6206"/>
+ <syscall name="epoll_create" number="6207"/>
+ <syscall name="epoll_ctl" number="6208"/>
+ <syscall name="epoll_wait" number="6209"/>
+ <syscall name="remap_file_pages" number="6210"/>
+ <syscall name="rt_sigreturn" number="6211"/>
+ <syscall name="fcntl64" number="6212"/>
+ <syscall name="set_tid_address" number="6213"/>
+ <syscall name="restart_syscall" number="6214"/>
+ <syscall name="semtimedop" number="6215"/>
+ <syscall name="fadvise64" number="6216"/>
+ <syscall name="statfs64" number="6217"/>
+ <syscall name="fstatfs64" number="6218"/>
+ <syscall name="sendfile64" number="6219"/>
+ <syscall name="timer_create" number="6220"/>
+ <syscall name="timer_settime" number="6221"/>
+ <syscall name="timer_gettime" number="6222"/>
+ <syscall name="timer_getoverrun" number="6223"/>
+ <syscall name="timer_delete" number="6224"/>
+ <syscall name="clock_settime" number="6225"/>
+ <syscall name="clock_gettime" number="6226"/>
+ <syscall name="clock_getres" number="6227"/>
+ <syscall name="clock_nanosleep" number="6228"/>
+ <syscall name="tgkill" number="6229"/>
+ <syscall name="utimes" number="6230"/>
+ <syscall name="mbind" number="6231"/>
+ <syscall name="get_mempolicy" number="6232"/>
+ <syscall name="set_mempolicy" number="6233"/>
+ <syscall name="mq_open" number="6234"/>
+ <syscall name="mq_unlink" number="6235"/>
+ <syscall name="mq_timedsend" number="6236"/>
+ <syscall name="mq_timedreceive" number="6237"/>
+ <syscall name="mq_notify" number="6238"/>
+ <syscall name="mq_getsetattr" number="6239"/>
+ <syscall name="vserver" number="6240"/>
+ <syscall name="waitid" number="6241"/>
+ <syscall name="add_key" number="6243"/>
+ <syscall name="request_key" number="6244"/>
+ <syscall name="keyctl" number="6245"/>
+ <syscall name="set_thread_area" number="6246"/>
+ <syscall name="inotify_init" number="6247"/>
+ <syscall name="inotify_add_watch" number="6248"/>
+ <syscall name="inotify_rm_watch" number="6249"/>
+ <syscall name="migrate_pages" number="6250"/>
+ <syscall name="openat" number="6251"/>
+ <syscall name="mkdirat" number="6252"/>
+ <syscall name="mknodat" number="6253"/>
+ <syscall name="fchownat" number="6254"/>
+ <syscall name="futimesat" number="6255"/>
+ <syscall name="newfstatat" number="6256"/>
+ <syscall name="unlinkat" number="6257"/>
+ <syscall name="renameat" number="6258"/>
+ <syscall name="linkat" number="6259"/>
+ <syscall name="symlinkat" number="6260"/>
+ <syscall name="readlinkat" number="6261"/>
+ <syscall name="fchmodat" number="6262"/>
+ <syscall name="faccessat" number="6263"/>
+ <syscall name="pselect6" number="6264"/>
+ <syscall name="ppoll" number="6265"/>
+ <syscall name="unshare" number="6266"/>
+ <syscall name="splice" number="6267"/>
+ <syscall name="sync_file_range" number="6268"/>
+ <syscall name="tee" number="6269"/>
+ <syscall name="vmsplice" number="6270"/>
+ <syscall name="move_pages" number="6271"/>
+ <syscall name="set_robust_list" number="6272"/>
+ <syscall name="get_robust_list" number="6273"/>
+ <syscall name="kexec_load" number="6274"/>
+ <syscall name="getcpu" number="6275"/>
+ <syscall name="epoll_pwait" number="6276"/>
+ <syscall name="ioprio_set" number="6277"/>
+ <syscall name="ioprio_get" number="6278"/>
+ <syscall name="utimensat" number="6279"/>
+ <syscall name="signalfd" number="6280"/>
+ <syscall name="timerfd" number="6281"/>
+ <syscall name="eventfd" number="6282"/>
+ <syscall name="fallocate" number="6283"/>
+ <syscall name="timerfd_create" number="6284"/>
+ <syscall name="timerfd_gettime" number="6285"/>
+ <syscall name="timerfd_settime" number="6286"/>
+ <syscall name="signalfd4" number="6287"/>
+ <syscall name="eventfd2" number="6288"/>
+ <syscall name="epoll_create1" number="6289"/>
+ <syscall name="dup3" number="6290"/>
+ <syscall name="pipe2" number="6291"/>
+ <syscall name="inotify_init1" number="6292"/>
+ <syscall name="preadv" number="6293"/>
+ <syscall name="pwritev" number="6294"/>
+ <syscall name="rt_tgsigqueueinfo" number="6295"/>
+ <syscall name="perf_event_open" number="6296"/>
+ <syscall name="accept4" number="6297"/>
+ <syscall name="recvmmsg" number="6298"/>
+ <syscall name="getdents64" number="6299"/>
+ <syscall name="fanotify_init" number="6300"/>
+ <syscall name="fanotify_mark" number="6301"/>
+ <syscall name="prlimit64" number="6302"/>
+</syscalls_info>
--- /dev/null
+<?xml version="1.0"?>
+<!-- Copyright (C) 2011-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. -->
+
+<!DOCTYPE feature SYSTEM "gdb-syscalls.dtd">
+
+<!-- This file was generated using the following file:
+
+ /usr/src/linux/arch/mips/include/asm/unistd.h
+
+ The file mentioned above belongs to the Linux Kernel. -->
+
+<syscalls_info>
+ <syscall name="read" number="5000"/>
+ <syscall name="write" number="5001"/>
+ <syscall name="open" number="5002"/>
+ <syscall name="close" number="5003"/>
+ <syscall name="stat" number="5004"/>
+ <syscall name="fstat" number="5005"/>
+ <syscall name="lstat" number="5006"/>
+ <syscall name="poll" number="5007"/>
+ <syscall name="lseek" number="5008"/>
+ <syscall name="mmap" number="5009"/>
+ <syscall name="mprotect" number="5010"/>
+ <syscall name="munmap" number="5011"/>
+ <syscall name="brk" number="5012"/>
+ <syscall name="rt_sigaction" number="5013"/>
+ <syscall name="rt_sigprocmask" number="5014"/>
+ <syscall name="ioctl" number="5015"/>
+ <syscall name="pread64" number="5016"/>
+ <syscall name="pwrite64" number="5017"/>
+ <syscall name="readv" number="5018"/>
+ <syscall name="writev" number="5019"/>
+ <syscall name="access" number="5020"/>
+ <syscall name="pipe" number="5021"/>
+ <syscall name="_newselect" number="5022"/>
+ <syscall name="sched_yield" number="5023"/>
+ <syscall name="mremap" number="5024"/>
+ <syscall name="msync" number="5025"/>
+ <syscall name="mincore" number="5026"/>
+ <syscall name="madvise" number="5027"/>
+ <syscall name="shmget" number="5028"/>
+ <syscall name="shmat" number="5029"/>
+ <syscall name="shmctl" number="5030"/>
+ <syscall name="dup" number="5031"/>
+ <syscall name="dup2" number="5032"/>
+ <syscall name="pause" number="5033"/>
+ <syscall name="nanosleep" number="5034"/>
+ <syscall name="getitimer" number="5035"/>
+ <syscall name="setitimer" number="5036"/>
+ <syscall name="alarm" number="5037"/>
+ <syscall name="getpid" number="5038"/>
+ <syscall name="sendfile" number="5039"/>
+ <syscall name="socket" number="5040"/>
+ <syscall name="connect" number="5041"/>
+ <syscall name="accept" number="5042"/>
+ <syscall name="sendto" number="5043"/>
+ <syscall name="recvfrom" number="5044"/>
+ <syscall name="sendmsg" number="5045"/>
+ <syscall name="recvmsg" number="5046"/>
+ <syscall name="shutdown" number="5047"/>
+ <syscall name="bind" number="5048"/>
+ <syscall name="listen" number="5049"/>
+ <syscall name="getsockname" number="5050"/>
+ <syscall name="getpeername" number="5051"/>
+ <syscall name="socketpair" number="5052"/>
+ <syscall name="setsockopt" number="5053"/>
+ <syscall name="getsockopt" number="5054"/>
+ <syscall name="clone" number="5055"/>
+ <syscall name="fork" number="5056"/>
+ <syscall name="execve" number="5057"/>
+ <syscall name="exit" number="5058"/>
+ <syscall name="wait4" number="5059"/>
+ <syscall name="kill" number="5060"/>
+ <syscall name="uname" number="5061"/>
+ <syscall name="semget" number="5062"/>
+ <syscall name="semop" number="5063"/>
+ <syscall name="semctl" number="5064"/>
+ <syscall name="shmdt" number="5065"/>
+ <syscall name="msgget" number="5066"/>
+ <syscall name="msgsnd" number="5067"/>
+ <syscall name="msgrcv" number="5068"/>
+ <syscall name="msgctl" number="5069"/>
+ <syscall name="fcntl" number="5070"/>
+ <syscall name="flock" number="5071"/>
+ <syscall name="fsync" number="5072"/>
+ <syscall name="fdatasync" number="5073"/>
+ <syscall name="truncate" number="5074"/>
+ <syscall name="ftruncate" number="5075"/>
+ <syscall name="getdents" number="5076"/>
+ <syscall name="getcwd" number="5077"/>
+ <syscall name="chdir" number="5078"/>
+ <syscall name="fchdir" number="5079"/>
+ <syscall name="rename" number="5080"/>
+ <syscall name="mkdir" number="5081"/>
+ <syscall name="rmdir" number="5082"/>
+ <syscall name="creat" number="5083"/>
+ <syscall name="link" number="5084"/>
+ <syscall name="unlink" number="5085"/>
+ <syscall name="symlink" number="5086"/>
+ <syscall name="readlink" number="5087"/>
+ <syscall name="chmod" number="5088"/>
+ <syscall name="fchmod" number="5089"/>
+ <syscall name="chown" number="5090"/>
+ <syscall name="fchown" number="5091"/>
+ <syscall name="lchown" number="5092"/>
+ <syscall name="umask" number="5093"/>
+ <syscall name="gettimeofday" number="5094"/>
+ <syscall name="getrlimit" number="5095"/>
+ <syscall name="getrusage" number="5096"/>
+ <syscall name="sysinfo" number="5097"/>
+ <syscall name="times" number="5098"/>
+ <syscall name="ptrace" number="5099"/>
+ <syscall name="getuid" number="5100"/>
+ <syscall name="syslog" number="5101"/>
+ <syscall name="getgid" number="5102"/>
+ <syscall name="setuid" number="5103"/>
+ <syscall name="setgid" number="5104"/>
+ <syscall name="geteuid" number="5105"/>
+ <syscall name="getegid" number="5106"/>
+ <syscall name="setpgid" number="5107"/>
+ <syscall name="getppid" number="5108"/>
+ <syscall name="getpgrp" number="5109"/>
+ <syscall name="setsid" number="5110"/>
+ <syscall name="setreuid" number="5111"/>
+ <syscall name="setregid" number="5112"/>
+ <syscall name="getgroups" number="5113"/>
+ <syscall name="setgroups" number="5114"/>
+ <syscall name="setresuid" number="5115"/>
+ <syscall name="getresuid" number="5116"/>
+ <syscall name="setresgid" number="5117"/>
+ <syscall name="getresgid" number="5118"/>
+ <syscall name="getpgid" number="5119"/>
+ <syscall name="setfsuid" number="5120"/>
+ <syscall name="setfsgid" number="5121"/>
+ <syscall name="getsid" number="5122"/>
+ <syscall name="capget" number="5123"/>
+ <syscall name="capset" number="5124"/>
+ <syscall name="rt_sigpending" number="5125"/>
+ <syscall name="rt_sigtimedwait" number="5126"/>
+ <syscall name="rt_sigqueueinfo" number="5127"/>
+ <syscall name="rt_sigsuspend" number="5128"/>
+ <syscall name="sigaltstack" number="5129"/>
+ <syscall name="utime" number="5130"/>
+ <syscall name="mknod" number="5131"/>
+ <syscall name="personality" number="5132"/>
+ <syscall name="ustat" number="5133"/>
+ <syscall name="statfs" number="5134"/>
+ <syscall name="fstatfs" number="5135"/>
+ <syscall name="sysfs" number="5136"/>
+ <syscall name="getpriority" number="5137"/>
+ <syscall name="setpriority" number="5138"/>
+ <syscall name="sched_setparam" number="5139"/>
+ <syscall name="sched_getparam" number="5140"/>
+ <syscall name="sched_setscheduler" number="5141"/>
+ <syscall name="sched_getscheduler" number="5142"/>
+ <syscall name="sched_get_priority_max" number="5143"/>
+ <syscall name="sched_get_priority_min" number="5144"/>
+ <syscall name="sched_rr_get_interval" number="5145"/>
+ <syscall name="mlock" number="5146"/>
+ <syscall name="munlock" number="5147"/>
+ <syscall name="mlockall" number="5148"/>
+ <syscall name="munlockall" number="5149"/>
+ <syscall name="vhangup" number="5150"/>
+ <syscall name="pivot_root" number="5151"/>
+ <syscall name="_sysctl" number="5152"/>
+ <syscall name="prctl" number="5153"/>
+ <syscall name="adjtimex" number="5154"/>
+ <syscall name="setrlimit" number="5155"/>
+ <syscall name="chroot" number="5156"/>
+ <syscall name="sync" number="5157"/>
+ <syscall name="acct" number="5158"/>
+ <syscall name="settimeofday" number="5159"/>
+ <syscall name="mount" number="5160"/>
+ <syscall name="umount2" number="5161"/>
+ <syscall name="swapon" number="5162"/>
+ <syscall name="swapoff" number="5163"/>
+ <syscall name="reboot" number="5164"/>
+ <syscall name="sethostname" number="5165"/>
+ <syscall name="setdomainname" number="5166"/>
+ <syscall name="create_module" number="5167"/>
+ <syscall name="init_module" number="5168"/>
+ <syscall name="delete_module" number="5169"/>
+ <syscall name="get_kernel_syms" number="5170"/>
+ <syscall name="query_module" number="5171"/>
+ <syscall name="quotactl" number="5172"/>
+ <syscall name="nfsservctl" number="5173"/>
+ <syscall name="getpmsg" number="5174"/>
+ <syscall name="putpmsg" number="5175"/>
+ <syscall name="afs_syscall" number="5176"/>
+ <syscall name="gettid" number="5178"/>
+ <syscall name="readahead" number="5179"/>
+ <syscall name="setxattr" number="5180"/>
+ <syscall name="lsetxattr" number="5181"/>
+ <syscall name="fsetxattr" number="5182"/>
+ <syscall name="getxattr" number="5183"/>
+ <syscall name="lgetxattr" number="5184"/>
+ <syscall name="fgetxattr" number="5185"/>
+ <syscall name="listxattr" number="5186"/>
+ <syscall name="llistxattr" number="5187"/>
+ <syscall name="flistxattr" number="5188"/>
+ <syscall name="removexattr" number="5189"/>
+ <syscall name="lremovexattr" number="5190"/>
+ <syscall name="fremovexattr" number="5191"/>
+ <syscall name="tkill" number="5192"/>
+ <syscall name="futex" number="5194"/>
+ <syscall name="sched_setaffinity" number="5195"/>
+ <syscall name="sched_getaffinity" number="5196"/>
+ <syscall name="cacheflush" number="5197"/>
+ <syscall name="cachectl" number="5198"/>
+ <syscall name="sysmips" number="5199"/>
+ <syscall name="io_setup" number="5200"/>
+ <syscall name="io_destroy" number="5201"/>
+ <syscall name="io_getevents" number="5202"/>
+ <syscall name="io_submit" number="5203"/>
+ <syscall name="io_cancel" number="5204"/>
+ <syscall name="exit_group" number="5205"/>
+ <syscall name="lookup_dcookie" number="5206"/>
+ <syscall name="epoll_create" number="5207"/>
+ <syscall name="epoll_ctl" number="5208"/>
+ <syscall name="epoll_wait" number="5209"/>
+ <syscall name="remap_file_pages" number="5210"/>
+ <syscall name="rt_sigreturn" number="5211"/>
+ <syscall name="set_tid_address" number="5212"/>
+ <syscall name="restart_syscall" number="5213"/>
+ <syscall name="semtimedop" number="5214"/>
+ <syscall name="fadvise64" number="5215"/>
+ <syscall name="timer_create" number="5216"/>
+ <syscall name="timer_settime" number="5217"/>
+ <syscall name="timer_gettime" number="5218"/>
+ <syscall name="timer_getoverrun" number="5219"/>
+ <syscall name="timer_delete" number="5220"/>
+ <syscall name="clock_settime" number="5221"/>
+ <syscall name="clock_gettime" number="5222"/>
+ <syscall name="clock_getres" number="5223"/>
+ <syscall name="clock_nanosleep" number="5224"/>
+ <syscall name="tgkill" number="5225"/>
+ <syscall name="utimes" number="5226"/>
+ <syscall name="mbind" number="5227"/>
+ <syscall name="get_mempolicy" number="5228"/>
+ <syscall name="set_mempolicy" number="5229"/>
+ <syscall name="mq_open" number="5230"/>
+ <syscall name="mq_unlink" number="5231"/>
+ <syscall name="mq_timedsend" number="5232"/>
+ <syscall name="mq_timedreceive" number="5233"/>
+ <syscall name="mq_notify" number="5234"/>
+ <syscall name="mq_getsetattr" number="5235"/>
+ <syscall name="vserver" number="5236"/>
+ <syscall name="waitid" number="5237"/>
+ <syscall name="add_key" number="5239"/>
+ <syscall name="request_key" number="5240"/>
+ <syscall name="keyctl" number="5241"/>
+ <syscall name="set_thread_area" number="5242"/>
+ <syscall name="inotify_init" number="5243"/>
+ <syscall name="inotify_add_watch" number="5244"/>
+ <syscall name="inotify_rm_watch" number="5245"/>
+ <syscall name="migrate_pages" number="5246"/>
+ <syscall name="openat" number="5247"/>
+ <syscall name="mkdirat" number="5248"/>
+ <syscall name="mknodat" number="5249"/>
+ <syscall name="fchownat" number="5250"/>
+ <syscall name="futimesat" number="5251"/>
+ <syscall name="newfstatat" number="5252"/>
+ <syscall name="unlinkat" number="5253"/>
+ <syscall name="renameat" number="5254"/>
+ <syscall name="linkat" number="5255"/>
+ <syscall name="symlinkat" number="5256"/>
+ <syscall name="readlinkat" number="5257"/>
+ <syscall name="fchmodat" number="5258"/>
+ <syscall name="faccessat" number="5259"/>
+ <syscall name="pselect6" number="5260"/>
+ <syscall name="ppoll" number="5261"/>
+ <syscall name="unshare" number="5262"/>
+ <syscall name="splice" number="5263"/>
+ <syscall name="sync_file_range" number="5264"/>
+ <syscall name="tee" number="5265"/>
+ <syscall name="vmsplice" number="5266"/>
+ <syscall name="move_pages" number="5267"/>
+ <syscall name="set_robust_list" number="5268"/>
+ <syscall name="get_robust_list" number="5269"/>
+ <syscall name="kexec_load" number="5270"/>
+ <syscall name="getcpu" number="5271"/>
+ <syscall name="epoll_pwait" number="5272"/>
+ <syscall name="ioprio_set" number="5273"/>
+ <syscall name="ioprio_get" number="5274"/>
+ <syscall name="utimensat" number="5275"/>
+ <syscall name="signalfd" number="5276"/>
+ <syscall name="timerfd" number="5277"/>
+ <syscall name="eventfd" number="5278"/>
+ <syscall name="fallocate" number="5279"/>
+ <syscall name="timerfd_create" number="5280"/>
+ <syscall name="timerfd_gettime" number="5281"/>
+ <syscall name="timerfd_settime" number="5282"/>
+ <syscall name="signalfd4" number="5283"/>
+ <syscall name="eventfd2" number="5284"/>
+ <syscall name="epoll_create1" number="5285"/>
+ <syscall name="dup3" number="5286"/>
+ <syscall name="pipe2" number="5287"/>
+ <syscall name="inotify_init1" number="5288"/>
+ <syscall name="preadv" number="5289"/>
+ <syscall name="pwritev" number="5290"/>
+ <syscall name="rt_tgsigqueueinfo" number="5291"/>
+ <syscall name="perf_event_open" number="5292"/>
+ <syscall name="accept4" number="5293"/>
+ <syscall name="recvmmsg" number="5294"/>
+ <syscall name="fanotify_init" number="5295"/>
+ <syscall name="fanotify_mark" number="5296"/>
+ <syscall name="prlimit64" number="5297"/>
+</syscalls_info>
--- /dev/null
+<?xml version="1.0"?>
+<!-- Copyright (C) 2011-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. -->
+
+<!DOCTYPE feature SYSTEM "gdb-syscalls.dtd">
+
+<!-- This file was generated using the following file:
+
+ /usr/src/linux/arch/mips/include/asm/unistd.h
+
+ The file mentioned above belongs to the Linux Kernel. -->
+
+<syscalls_info>
+ <syscall name="syscall" number="4000"/>
+ <syscall name="exit" number="4001"/>
+ <syscall name="fork" number="4002"/>
+ <syscall name="read" number="4003"/>
+ <syscall name="write" number="4004"/>
+ <syscall name="open" number="4005"/>
+ <syscall name="close" number="4006"/>
+ <syscall name="waitpid" number="4007"/>
+ <syscall name="creat" number="4008"/>
+ <syscall name="link" number="4009"/>
+ <syscall name="unlink" number="4010"/>
+ <syscall name="execve" number="4011"/>
+ <syscall name="chdir" number="4012"/>
+ <syscall name="time" number="4013"/>
+ <syscall name="mknod" number="4014"/>
+ <syscall name="chmod" number="4015"/>
+ <syscall name="lchown" number="4016"/>
+ <syscall name="break" number="4017"/>
+ <syscall name="lseek" number="4019"/>
+ <syscall name="getpid" number="4020"/>
+ <syscall name="mount" number="4021"/>
+ <syscall name="umount" number="4022"/>
+ <syscall name="setuid" number="4023"/>
+ <syscall name="getuid" number="4024"/>
+ <syscall name="stime" number="4025"/>
+ <syscall name="ptrace" number="4026"/>
+ <syscall name="alarm" number="4027"/>
+ <syscall name="pause" number="4029"/>
+ <syscall name="utime" number="4030"/>
+ <syscall name="stty" number="4031"/>
+ <syscall name="gtty" number="4032"/>
+ <syscall name="access" number="4033"/>
+ <syscall name="nice" number="4034"/>
+ <syscall name="ftime" number="4035"/>
+ <syscall name="sync" number="4036"/>
+ <syscall name="kill" number="4037"/>
+ <syscall name="rename" number="4038"/>
+ <syscall name="mkdir" number="4039"/>
+ <syscall name="rmdir" number="4040"/>
+ <syscall name="dup" number="4041"/>
+ <syscall name="pipe" number="4042"/>
+ <syscall name="times" number="4043"/>
+ <syscall name="prof" number="4044"/>
+ <syscall name="brk" number="4045"/>
+ <syscall name="setgid" number="4046"/>
+ <syscall name="getgid" number="4047"/>
+ <syscall name="signal" number="4048"/>
+ <syscall name="geteuid" number="4049"/>
+ <syscall name="getegid" number="4050"/>
+ <syscall name="acct" number="4051"/>
+ <syscall name="umount2" number="4052"/>
+ <syscall name="lock" number="4053"/>
+ <syscall name="ioctl" number="4054"/>
+ <syscall name="fcntl" number="4055"/>
+ <syscall name="mpx" number="4056"/>
+ <syscall name="setpgid" number="4057"/>
+ <syscall name="ulimit" number="4058"/>
+ <syscall name="umask" number="4060"/>
+ <syscall name="chroot" number="4061"/>
+ <syscall name="ustat" number="4062"/>
+ <syscall name="dup2" number="4063"/>
+ <syscall name="getppid" number="4064"/>
+ <syscall name="getpgrp" number="4065"/>
+ <syscall name="setsid" number="4066"/>
+ <syscall name="sigaction" number="4067"/>
+ <syscall name="sgetmask" number="4068"/>
+ <syscall name="ssetmask" number="4069"/>
+ <syscall name="setreuid" number="4070"/>
+ <syscall name="setregid" number="4071"/>
+ <syscall name="sigsuspend" number="4072"/>
+ <syscall name="sigpending" number="4073"/>
+ <syscall name="sethostname" number="4074"/>
+ <syscall name="setrlimit" number="4075"/>
+ <syscall name="getrlimit" number="4076"/>
+ <syscall name="getrusage" number="4077"/>
+ <syscall name="gettimeofday" number="4078"/>
+ <syscall name="settimeofday" number="4079"/>
+ <syscall name="getgroups" number="4080"/>
+ <syscall name="setgroups" number="4081"/>
+ <syscall name="symlink" number="4083"/>
+ <syscall name="readlink" number="4085"/>
+ <syscall name="uselib" number="4086"/>
+ <syscall name="swapon" number="4087"/>
+ <syscall name="reboot" number="4088"/>
+ <syscall name="readdir" number="4089"/>
+ <syscall name="mmap" number="4090"/>
+ <syscall name="munmap" number="4091"/>
+ <syscall name="truncate" number="4092"/>
+ <syscall name="ftruncate" number="4093"/>
+ <syscall name="fchmod" number="4094"/>
+ <syscall name="fchown" number="4095"/>
+ <syscall name="getpriority" number="4096"/>
+ <syscall name="setpriority" number="4097"/>
+ <syscall name="profil" number="4098"/>
+ <syscall name="statfs" number="4099"/>
+ <syscall name="fstatfs" number="4100"/>
+ <syscall name="ioperm" number="4101"/>
+ <syscall name="socketcall" number="4102"/>
+ <syscall name="syslog" number="4103"/>
+ <syscall name="setitimer" number="4104"/>
+ <syscall name="getitimer" number="4105"/>
+ <syscall name="stat" number="4106"/>
+ <syscall name="lstat" number="4107"/>
+ <syscall name="fstat" number="4108"/>
+ <syscall name="iopl" number="4110"/>
+ <syscall name="vhangup" number="4111"/>
+ <syscall name="idle" number="4112"/>
+ <syscall name="vm86" number="4113"/>
+ <syscall name="wait4" number="4114"/>
+ <syscall name="swapoff" number="4115"/>
+ <syscall name="sysinfo" number="4116"/>
+ <syscall name="ipc" number="4117"/>
+ <syscall name="fsync" number="4118"/>
+ <syscall name="sigreturn" number="4119"/>
+ <syscall name="clone" number="4120"/>
+ <syscall name="setdomainname" number="4121"/>
+ <syscall name="uname" number="4122"/>
+ <syscall name="modify_ldt" number="4123"/>
+ <syscall name="adjtimex" number="4124"/>
+ <syscall name="mprotect" number="4125"/>
+ <syscall name="sigprocmask" number="4126"/>
+ <syscall name="create_module" number="4127"/>
+ <syscall name="init_module" number="4128"/>
+ <syscall name="delete_module" number="4129"/>
+ <syscall name="get_kernel_syms" number="4130"/>
+ <syscall name="quotactl" number="4131"/>
+ <syscall name="getpgid" number="4132"/>
+ <syscall name="fchdir" number="4133"/>
+ <syscall name="bdflush" number="4134"/>
+ <syscall name="sysfs" number="4135"/>
+ <syscall name="personality" number="4136"/>
+ <syscall name="afs_syscall" number="4137"/>
+ <syscall name="setfsuid" number="4138"/>
+ <syscall name="setfsgid" number="4139"/>
+ <syscall name="_llseek" number="4140"/>
+ <syscall name="getdents" number="4141"/>
+ <syscall name="_newselect" number="4142"/>
+ <syscall name="flock" number="4143"/>
+ <syscall name="msync" number="4144"/>
+ <syscall name="readv" number="4145"/>
+ <syscall name="writev" number="4146"/>
+ <syscall name="cacheflush" number="4147"/>
+ <syscall name="cachectl" number="4148"/>
+ <syscall name="sysmips" number="4149"/>
+ <syscall name="getsid" number="4151"/>
+ <syscall name="fdatasync" number="4152"/>
+ <syscall name="_sysctl" number="4153"/>
+ <syscall name="mlock" number="4154"/>
+ <syscall name="munlock" number="4155"/>
+ <syscall name="mlockall" number="4156"/>
+ <syscall name="munlockall" number="4157"/>
+ <syscall name="sched_setparam" number="4158"/>
+ <syscall name="sched_getparam" number="4159"/>
+ <syscall name="sched_setscheduler" number="4160"/>
+ <syscall name="sched_getscheduler" number="4161"/>
+ <syscall name="sched_yield" number="4162"/>
+ <syscall name="sched_get_priority_max" number="4163"/>
+ <syscall name="sched_get_priority_min" number="4164"/>
+ <syscall name="sched_rr_get_interval" number="4165"/>
+ <syscall name="nanosleep" number="4166"/>
+ <syscall name="mremap" number="4167"/>
+ <syscall name="accept" number="4168"/>
+ <syscall name="bind" number="4169"/>
+ <syscall name="connect" number="4170"/>
+ <syscall name="getpeername" number="4171"/>
+ <syscall name="getsockname" number="4172"/>
+ <syscall name="getsockopt" number="4173"/>
+ <syscall name="listen" number="4174"/>
+ <syscall name="recv" number="4175"/>
+ <syscall name="recvfrom" number="4176"/>
+ <syscall name="recvmsg" number="4177"/>
+ <syscall name="send" number="4178"/>
+ <syscall name="sendmsg" number="4179"/>
+ <syscall name="sendto" number="4180"/>
+ <syscall name="setsockopt" number="4181"/>
+ <syscall name="shutdown" number="4182"/>
+ <syscall name="socket" number="4183"/>
+ <syscall name="socketpair" number="4184"/>
+ <syscall name="setresuid" number="4185"/>
+ <syscall name="getresuid" number="4186"/>
+ <syscall name="query_module" number="4187"/>
+ <syscall name="poll" number="4188"/>
+ <syscall name="nfsservctl" number="4189"/>
+ <syscall name="setresgid" number="4190"/>
+ <syscall name="getresgid" number="4191"/>
+ <syscall name="prctl" number="4192"/>
+ <syscall name="rt_sigreturn" number="4193"/>
+ <syscall name="rt_sigaction" number="4194"/>
+ <syscall name="rt_sigprocmask" number="4195"/>
+ <syscall name="rt_sigpending" number="4196"/>
+ <syscall name="rt_sigtimedwait" number="4197"/>
+ <syscall name="rt_sigqueueinfo" number="4198"/>
+ <syscall name="rt_sigsuspend" number="4199"/>
+ <syscall name="pread64" number="4200"/>
+ <syscall name="pwrite64" number="4201"/>
+ <syscall name="chown" number="4202"/>
+ <syscall name="getcwd" number="4203"/>
+ <syscall name="capget" number="4204"/>
+ <syscall name="capset" number="4205"/>
+ <syscall name="sigaltstack" number="4206"/>
+ <syscall name="sendfile" number="4207"/>
+ <syscall name="getpmsg" number="4208"/>
+ <syscall name="putpmsg" number="4209"/>
+ <syscall name="mmap2" number="4210"/>
+ <syscall name="truncate64" number="4211"/>
+ <syscall name="ftruncate64" number="4212"/>
+ <syscall name="stat64" number="4213"/>
+ <syscall name="lstat64" number="4214"/>
+ <syscall name="fstat64" number="4215"/>
+ <syscall name="pivot_root" number="4216"/>
+ <syscall name="mincore" number="4217"/>
+ <syscall name="madvise" number="4218"/>
+ <syscall name="getdents64" number="4219"/>
+ <syscall name="fcntl64" number="4220"/>
+ <syscall name="gettid" number="4222"/>
+ <syscall name="readahead" number="4223"/>
+ <syscall name="setxattr" number="4224"/>
+ <syscall name="lsetxattr" number="4225"/>
+ <syscall name="fsetxattr" number="4226"/>
+ <syscall name="getxattr" number="4227"/>
+ <syscall name="lgetxattr" number="4228"/>
+ <syscall name="fgetxattr" number="4229"/>
+ <syscall name="listxattr" number="4230"/>
+ <syscall name="llistxattr" number="4231"/>
+ <syscall name="flistxattr" number="4232"/>
+ <syscall name="removexattr" number="4233"/>
+ <syscall name="lremovexattr" number="4234"/>
+ <syscall name="fremovexattr" number="4235"/>
+ <syscall name="tkill" number="4236"/>
+ <syscall name="sendfile64" number="4237"/>
+ <syscall name="futex" number="4238"/>
+ <syscall name="sched_setaffinity" number="4239"/>
+ <syscall name="sched_getaffinity" number="4240"/>
+ <syscall name="io_setup" number="4241"/>
+ <syscall name="io_destroy" number="4242"/>
+ <syscall name="io_getevents" number="4243"/>
+ <syscall name="io_submit" number="4244"/>
+ <syscall name="io_cancel" number="4245"/>
+ <syscall name="exit_group" number="4246"/>
+ <syscall name="lookup_dcookie" number="4247"/>
+ <syscall name="epoll_create" number="4248"/>
+ <syscall name="epoll_ctl" number="4249"/>
+ <syscall name="epoll_wait" number="4250"/>
+ <syscall name="remap_file_pages" number="4251"/>
+ <syscall name="set_tid_address" number="4252"/>
+ <syscall name="restart_syscall" number="4253"/>
+ <syscall name="fadvise64" number="4254"/>
+ <syscall name="statfs64" number="4255"/>
+ <syscall name="fstatfs64" number="4256"/>
+ <syscall name="timer_create" number="4257"/>
+ <syscall name="timer_settime" number="4258"/>
+ <syscall name="timer_gettime" number="4259"/>
+ <syscall name="timer_getoverrun" number="4260"/>
+ <syscall name="timer_delete" number="4261"/>
+ <syscall name="clock_settime" number="4262"/>
+ <syscall name="clock_gettime" number="4263"/>
+ <syscall name="clock_getres" number="4264"/>
+ <syscall name="clock_nanosleep" number="4265"/>
+ <syscall name="tgkill" number="4266"/>
+ <syscall name="utimes" number="4267"/>
+ <syscall name="mbind" number="4268"/>
+ <syscall name="get_mempolicy" number="4269"/>
+ <syscall name="set_mempolicy" number="4270"/>
+ <syscall name="mq_open" number="4271"/>
+ <syscall name="mq_unlink" number="4272"/>
+ <syscall name="mq_timedsend" number="4273"/>
+ <syscall name="mq_timedreceive" number="4274"/>
+ <syscall name="mq_notify" number="4275"/>
+ <syscall name="mq_getsetattr" number="4276"/>
+ <syscall name="vserver" number="4277"/>
+ <syscall name="waitid" number="4278"/>
+ <syscall name="add_key" number="4280"/>
+ <syscall name="request_key" number="4281"/>
+ <syscall name="keyctl" number="4282"/>
+ <syscall name="set_thread_area" number="4283"/>
+ <syscall name="inotify_init" number="4284"/>
+ <syscall name="inotify_add_watch" number="4285"/>
+ <syscall name="inotify_rm_watch" number="4286"/>
+ <syscall name="migrate_pages" number="4287"/>
+ <syscall name="openat" number="4288"/>
+ <syscall name="mkdirat" number="4289"/>
+ <syscall name="mknodat" number="4290"/>
+ <syscall name="fchownat" number="4291"/>
+ <syscall name="futimesat" number="4292"/>
+ <syscall name="fstatat64" number="4293"/>
+ <syscall name="unlinkat" number="4294"/>
+ <syscall name="renameat" number="4295"/>
+ <syscall name="linkat" number="4296"/>
+ <syscall name="symlinkat" number="4297"/>
+ <syscall name="readlinkat" number="4298"/>
+ <syscall name="fchmodat" number="4299"/>
+ <syscall name="faccessat" number="4300"/>
+ <syscall name="pselect6" number="4301"/>
+ <syscall name="ppoll" number="4302"/>
+ <syscall name="unshare" number="4303"/>
+ <syscall name="splice" number="4304"/>
+ <syscall name="sync_file_range" number="4305"/>
+ <syscall name="tee" number="4306"/>
+ <syscall name="vmsplice" number="4307"/>
+ <syscall name="move_pages" number="4308"/>
+ <syscall name="set_robust_list" number="4309"/>
+ <syscall name="get_robust_list" number="4310"/>
+ <syscall name="kexec_load" number="4311"/>
+ <syscall name="getcpu" number="4312"/>
+ <syscall name="epoll_pwait" number="4313"/>
+ <syscall name="ioprio_set" number="4314"/>
+ <syscall name="ioprio_get" number="4315"/>
+ <syscall name="utimensat" number="4316"/>
+ <syscall name="signalfd" number="4317"/>
+ <syscall name="timerfd" number="4318"/>
+ <syscall name="eventfd" number="4319"/>
+ <syscall name="fallocate" number="4320"/>
+ <syscall name="timerfd_create" number="4321"/>
+ <syscall name="timerfd_gettime" number="4322"/>
+ <syscall name="timerfd_settime" number="4323"/>
+ <syscall name="signalfd4" number="4324"/>
+ <syscall name="eventfd2" number="4325"/>
+ <syscall name="epoll_create1" number="4326"/>
+ <syscall name="dup3" number="4327"/>
+ <syscall name="pipe2" number="4328"/>
+ <syscall name="inotify_init1" number="4329"/>
+ <syscall name="preadv" number="4330"/>
+ <syscall name="pwritev" number="4331"/>
+ <syscall name="rt_tgsigqueueinfo" number="4332"/>
+ <syscall name="perf_event_open" number="4333"/>
+ <syscall name="accept4" number="4334"/>
+ <syscall name="recvmmsg" number="4335"/>
+ <syscall name="fanotify_init" number="4336"/>
+ <syscall name="fanotify_mark" number="4337"/>
+ <syscall name="prlimit64" number="4338"/>
+</syscalls_info>
--- /dev/null
+<?xml version="1.0"?>
+<!-- Copyright (C) 2009-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. -->
+
+<!DOCTYPE feature SYSTEM "gdb-syscalls.dtd">
+
+<!-- This file was generated using the following file:
+
+ /usr/src/linux/arch/powerpc/include/asm/unistd.h
+
+ The file mentioned above belongs to the Linux Kernel. -->
+
+<syscalls_info>
+ <syscall name="restart_syscall" number="0"/>
+ <syscall name="exit" number="1"/>
+ <syscall name="fork" number="2"/>
+ <syscall name="read" number="3"/>
+ <syscall name="write" number="4"/>
+ <syscall name="open" number="5"/>
+ <syscall name="close" number="6"/>
+ <syscall name="waitpid" number="7"/>
+ <syscall name="creat" number="8"/>
+ <syscall name="link" number="9"/>
+ <syscall name="unlink" number="10"/>
+ <syscall name="execve" number="11"/>
+ <syscall name="chdir" number="12"/>
+ <syscall name="time" number="13"/>
+ <syscall name="mknod" number="14"/>
+ <syscall name="chmod" number="15"/>
+ <syscall name="lchown" number="16"/>
+ <syscall name="break" number="17"/>
+ <syscall name="oldstat" number="18"/>
+ <syscall name="lseek" number="19"/>
+ <syscall name="getpid" number="20"/>
+ <syscall name="mount" number="21"/>
+ <syscall name="umount" number="22"/>
+ <syscall name="setuid" number="23"/>
+ <syscall name="getuid" number="24"/>
+ <syscall name="stime" number="25"/>
+ <syscall name="ptrace" number="26"/>
+ <syscall name="alarm" number="27"/>
+ <syscall name="oldfstat" number="28"/>
+ <syscall name="pause" number="29"/>
+ <syscall name="utime" number="30"/>
+ <syscall name="stty" number="31"/>
+ <syscall name="gtty" number="32"/>
+ <syscall name="access" number="33"/>
+ <syscall name="nice" number="34"/>
+ <syscall name="ftime" number="35"/>
+ <syscall name="sync" number="36"/>
+ <syscall name="kill" number="37"/>
+ <syscall name="rename" number="38"/>
+ <syscall name="mkdir" number="39"/>
+ <syscall name="rmdir" number="40"/>
+ <syscall name="dup" number="41"/>
+ <syscall name="pipe" number="42"/>
+ <syscall name="times" number="43"/>
+ <syscall name="prof" number="44"/>
+ <syscall name="brk" number="45"/>
+ <syscall name="setgid" number="46"/>
+ <syscall name="getgid" number="47"/>
+ <syscall name="signal" number="48"/>
+ <syscall name="geteuid" number="49"/>
+ <syscall name="getegid" number="50"/>
+ <syscall name="acct" number="51"/>
+ <syscall name="umount2" number="52"/>
+ <syscall name="lock" number="53"/>
+ <syscall name="ioctl" number="54"/>
+ <syscall name="fcntl" number="55"/>
+ <syscall name="mpx" number="56"/>
+ <syscall name="setpgid" number="57"/>
+ <syscall name="ulimit" number="58"/>
+ <syscall name="oldolduname" number="59"/>
+ <syscall name="umask" number="60"/>
+ <syscall name="chroot" number="61"/>
+ <syscall name="ustat" number="62"/>
+ <syscall name="dup2" number="63"/>
+ <syscall name="getppid" number="64"/>
+ <syscall name="getpgrp" number="65"/>
+ <syscall name="setsid" number="66"/>
+ <syscall name="sigaction" number="67"/>
+ <syscall name="sgetmask" number="68"/>
+ <syscall name="ssetmask" number="69"/>
+ <syscall name="setreuid" number="70"/>
+ <syscall name="setregid" number="71"/>
+ <syscall name="sigsuspend" number="72"/>
+ <syscall name="sigpending" number="73"/>
+ <syscall name="sethostname" number="74"/>
+ <syscall name="setrlimit" number="75"/>
+ <syscall name="getrlimit" number="76"/>
+ <syscall name="getrusage" number="77"/>
+ <syscall name="gettimeofday" number="78"/>
+ <syscall name="settimeofday" number="79"/>
+ <syscall name="getgroups" number="80"/>
+ <syscall name="setgroups" number="81"/>
+ <syscall name="select" number="82"/>
+ <syscall name="symlink" number="83"/>
+ <syscall name="oldlstat" number="84"/>
+ <syscall name="readlink" number="85"/>
+ <syscall name="uselib" number="86"/>
+ <syscall name="swapon" number="87"/>
+ <syscall name="reboot" number="88"/>
+ <syscall name="readdir" number="89"/>
+ <syscall name="mmap" number="90"/>
+ <syscall name="munmap" number="91"/>
+ <syscall name="truncate" number="92"/>
+ <syscall name="ftruncate" number="93"/>
+ <syscall name="fchmod" number="94"/>
+ <syscall name="fchown" number="95"/>
+ <syscall name="getpriority" number="96"/>
+ <syscall name="setpriority" number="97"/>
+ <syscall name="profil" number="98"/>
+ <syscall name="statfs" number="99"/>
+ <syscall name="fstatfs" number="100"/>
+ <syscall name="ioperm" number="101"/>
+ <syscall name="socketcall" number="102"/>
+ <syscall name="syslog" number="103"/>
+ <syscall name="setitimer" number="104"/>
+ <syscall name="getitimer" number="105"/>
+ <syscall name="stat" number="106"/>
+ <syscall name="lstat" number="107"/>
+ <syscall name="fstat" number="108"/>
+ <syscall name="olduname" number="109"/>
+ <syscall name="iopl" number="110"/>
+ <syscall name="vhangup" number="111"/>
+ <syscall name="idle" number="112"/>
+ <syscall name="vm86" number="113"/>
+ <syscall name="wait4" number="114"/>
+ <syscall name="swapoff" number="115"/>
+ <syscall name="sysinfo" number="116"/>
+ <syscall name="ipc" number="117"/>
+ <syscall name="fsync" number="118"/>
+ <syscall name="sigreturn" number="119"/>
+ <syscall name="clone" number="120"/>
+ <syscall name="setdomainname" number="121"/>
+ <syscall name="uname" number="122"/>
+ <syscall name="modify_ldt" number="123"/>
+ <syscall name="adjtimex" number="124"/>
+ <syscall name="mprotect" number="125"/>
+ <syscall name="sigprocmask" number="126"/>
+ <syscall name="create_module" number="127"/>
+ <syscall name="init_module" number="128"/>
+ <syscall name="delete_module" number="129"/>
+ <syscall name="get_kernel_syms" number="130"/>
+ <syscall name="quotactl" number="131"/>
+ <syscall name="getpgid" number="132"/>
+ <syscall name="fchdir" number="133"/>
+ <syscall name="bdflush" number="134"/>
+ <syscall name="sysfs" number="135"/>
+ <syscall name="personality" number="136"/>
+ <syscall name="afs_syscall" number="137"/>
+ <syscall name="setfsuid" number="138"/>
+ <syscall name="setfsgid" number="139"/>
+ <syscall name="_llseek" number="140"/>
+ <syscall name="getdents" number="141"/>
+ <syscall name="_newselect" number="142"/>
+ <syscall name="flock" number="143"/>
+ <syscall name="msync" number="144"/>
+ <syscall name="readv" number="145"/>
+ <syscall name="writev" number="146"/>
+ <syscall name="getsid" number="147"/>
+ <syscall name="fdatasync" number="148"/>
+ <syscall name="_sysctl" number="149"/>
+ <syscall name="mlock" number="150"/>
+ <syscall name="munlock" number="151"/>
+ <syscall name="mlockall" number="152"/>
+ <syscall name="munlockall" number="153"/>
+ <syscall name="sched_setparam" number="154"/>
+ <syscall name="sched_getparam" number="155"/>
+ <syscall name="sched_setscheduler" number="156"/>
+ <syscall name="sched_getscheduler" number="157"/>
+ <syscall name="sched_yield" number="158"/>
+ <syscall name="sched_get_priority_max" number="159"/>
+ <syscall name="sched_get_priority_min" number="160"/>
+ <syscall name="sched_rr_get_interval" number="161"/>
+ <syscall name="nanosleep" number="162"/>
+ <syscall name="mremap" number="163"/>
+ <syscall name="setresuid" number="164"/>
+ <syscall name="getresuid" number="165"/>
+ <syscall name="query_module" number="166"/>
+ <syscall name="poll" number="167"/>
+ <syscall name="nfsservctl" number="168"/>
+ <syscall name="setresgid" number="169"/>
+ <syscall name="getresgid" number="170"/>
+ <syscall name="prctl" number="171"/>
+ <syscall name="rt_sigreturn" number="172"/>
+ <syscall name="rt_sigaction" number="173"/>
+ <syscall name="rt_sigprocmask" number="174"/>
+ <syscall name="rt_sigpending" number="175"/>
+ <syscall name="rt_sigtimedwait" number="176"/>
+ <syscall name="rt_sigqueueinfo" number="177"/>
+ <syscall name="rt_sigsuspend" number="178"/>
+ <syscall name="pread64" number="179"/>
+ <syscall name="pwrite64" number="180"/>
+ <syscall name="chown" number="181"/>
+ <syscall name="getcwd" number="182"/>
+ <syscall name="capget" number="183"/>
+ <syscall name="capset" number="184"/>
+ <syscall name="sigaltstack" number="185"/>
+ <syscall name="sendfile" number="186"/>
+ <syscall name="getpmsg" number="187"/>
+ <syscall name="putpmsg" number="188"/>
+ <syscall name="vfork" number="189"/>
+ <syscall name="ugetrlimit" number="190"/>
+ <syscall name="readahead" number="191"/>
+ <syscall name="mmap2" number="192"/>
+ <syscall name="truncate64" number="193"/>
+ <syscall name="ftruncate64" number="194"/>
+ <syscall name="stat64" number="195"/>
+ <syscall name="lstat64" number="196"/>
+ <syscall name="fstat64" number="197"/>
+ <syscall name="pciconfig_read" number="198"/>
+ <syscall name="pciconfig_write" number="199"/>
+ <syscall name="pciconfig_iobase" number="200"/>
+ <syscall name="multiplexer" number="201"/>
+ <syscall name="getdents64" number="202"/>
+ <syscall name="pivot_root" number="203"/>
+ <syscall name="fcntl64" number="204"/>
+ <syscall name="madvise" number="205"/>
+ <syscall name="mincore" number="206"/>
+ <syscall name="gettid" number="207"/>
+ <syscall name="tkill" number="208"/>
+ <syscall name="setxattr" number="209"/>
+ <syscall name="lsetxattr" number="210"/>
+ <syscall name="fsetxattr" number="211"/>
+ <syscall name="getxattr" number="212"/>
+ <syscall name="lgetxattr" number="213"/>
+ <syscall name="fgetxattr" number="214"/>
+ <syscall name="listxattr" number="215"/>
+ <syscall name="llistxattr" number="216"/>
+ <syscall name="flistxattr" number="217"/>
+ <syscall name="removexattr" number="218"/>
+ <syscall name="lremovexattr" number="219"/>
+ <syscall name="fremovexattr" number="220"/>
+ <syscall name="futex" number="221"/>
+ <syscall name="sched_setaffinity" number="222"/>
+ <syscall name="sched_getaffinity" number="223"/>
+ <syscall name="tuxcall" number="225"/>
+ <syscall name="sendfile64" number="226"/>
+ <syscall name="io_setup" number="227"/>
+ <syscall name="io_destroy" number="228"/>
+ <syscall name="io_getevents" number="229"/>
+ <syscall name="io_submit" number="230"/>
+ <syscall name="io_cancel" number="231"/>
+ <syscall name="set_tid_address" number="232"/>
+ <syscall name="fadvise64" number="233"/>
+ <syscall name="exit_group" number="234"/>
+ <syscall name="lookup_dcookie" number="235"/>
+ <syscall name="epoll_create" number="236"/>
+ <syscall name="epoll_ctl" number="237"/>
+ <syscall name="epoll_wait" number="238"/>
+ <syscall name="remap_file_pages" number="239"/>
+ <syscall name="timer_create" number="240"/>
+ <syscall name="timer_settime" number="241"/>
+ <syscall name="timer_gettime" number="242"/>
+ <syscall name="timer_getoverrun" number="243"/>
+ <syscall name="timer_delete" number="244"/>
+ <syscall name="clock_settime" number="245"/>
+ <syscall name="clock_gettime" number="246"/>
+ <syscall name="clock_getres" number="247"/>
+ <syscall name="clock_nanosleep" number="248"/>
+ <syscall name="swapcontext" number="249"/>
+ <syscall name="tgkill" number="250"/>
+ <syscall name="utimes" number="251"/>
+ <syscall name="statfs64" number="252"/>
+ <syscall name="fstatfs64" number="253"/>
+ <syscall name="fadvise64_64" number="254"/>
+ <syscall name="rtas" number="255"/>
+ <syscall name="sys_debug_setcontext" number="256"/>
+ <syscall name="mbind" number="259"/>
+ <syscall name="get_mempolicy" number="260"/>
+ <syscall name="set_mempolicy" number="261"/>
+ <syscall name="mq_open" number="262"/>
+ <syscall name="mq_unlink" number="263"/>
+ <syscall name="mq_timedsend" number="264"/>
+ <syscall name="mq_timedreceive" number="265"/>
+ <syscall name="mq_notify" number="266"/>
+ <syscall name="mq_getsetattr" number="267"/>
+ <syscall name="kexec_load" number="268"/>
+ <syscall name="add_key" number="269"/>
+ <syscall name="request_key" number="270"/>
+ <syscall name="keyctl" number="271"/>
+ <syscall name="waitid" number="272"/>
+ <syscall name="ioprio_set" number="273"/>
+ <syscall name="ioprio_get" number="274"/>
+ <syscall name="inotify_init" number="275"/>
+ <syscall name="inotify_add_watch" number="276"/>
+ <syscall name="inotify_rm_watch" number="277"/>
+ <syscall name="spu_run" number="278"/>
+ <syscall name="spu_create" number="279"/>
+ <syscall name="pselect6" number="280"/>
+ <syscall name="ppoll" number="281"/>
+ <syscall name="unshare" number="282"/>
+ <syscall name="openat" number="286"/>
+ <syscall name="mkdirat" number="287"/>
+ <syscall name="mknodat" number="288"/>
+ <syscall name="fchownat" number="289"/>
+ <syscall name="futimesat" number="290"/>
+ <syscall name="fstatat64" number="291"/>
+ <syscall name="unlinkat" number="292"/>
+ <syscall name="renameat" number="293"/>
+ <syscall name="linkat" number="294"/>
+ <syscall name="symlinkat" number="295"/>
+ <syscall name="readlinkat" number="296"/>
+ <syscall name="fchmodat" number="297"/>
+ <syscall name="faccessat" number="298"/>
+</syscalls_info>
--- /dev/null
+<?xml version="1.0"?>
+<!-- Copyright (C) 2009-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. -->
+
+<!DOCTYPE feature SYSTEM "gdb-syscalls.dtd">
+
+<!-- This file was generated using the following file:
+
+ /usr/src/linux/arch/powerpc/include/asm/unistd.h
+
+ The file mentioned above belongs to the Linux Kernel. -->
+
+<syscalls_info>
+ <syscall name="restart_syscall" number="0"/>
+ <syscall name="exit" number="1"/>
+ <syscall name="fork" number="2"/>
+ <syscall name="read" number="3"/>
+ <syscall name="write" number="4"/>
+ <syscall name="open" number="5"/>
+ <syscall name="close" number="6"/>
+ <syscall name="waitpid" number="7"/>
+ <syscall name="creat" number="8"/>
+ <syscall name="link" number="9"/>
+ <syscall name="unlink" number="10"/>
+ <syscall name="execve" number="11"/>
+ <syscall name="chdir" number="12"/>
+ <syscall name="time" number="13"/>
+ <syscall name="mknod" number="14"/>
+ <syscall name="chmod" number="15"/>
+ <syscall name="lchown" number="16"/>
+ <syscall name="break" number="17"/>
+ <syscall name="oldstat" number="18"/>
+ <syscall name="lseek" number="19"/>
+ <syscall name="getpid" number="20"/>
+ <syscall name="mount" number="21"/>
+ <syscall name="umount" number="22"/>
+ <syscall name="setuid" number="23"/>
+ <syscall name="getuid" number="24"/>
+ <syscall name="stime" number="25"/>
+ <syscall name="ptrace" number="26"/>
+ <syscall name="alarm" number="27"/>
+ <syscall name="oldfstat" number="28"/>
+ <syscall name="pause" number="29"/>
+ <syscall name="utime" number="30"/>
+ <syscall name="stty" number="31"/>
+ <syscall name="gtty" number="32"/>
+ <syscall name="access" number="33"/>
+ <syscall name="nice" number="34"/>
+ <syscall name="ftime" number="35"/>
+ <syscall name="sync" number="36"/>
+ <syscall name="kill" number="37"/>
+ <syscall name="rename" number="38"/>
+ <syscall name="mkdir" number="39"/>
+ <syscall name="rmdir" number="40"/>
+ <syscall name="dup" number="41"/>
+ <syscall name="pipe" number="42"/>
+ <syscall name="times" number="43"/>
+ <syscall name="prof" number="44"/>
+ <syscall name="brk" number="45"/>
+ <syscall name="setgid" number="46"/>
+ <syscall name="getgid" number="47"/>
+ <syscall name="signal" number="48"/>
+ <syscall name="geteuid" number="49"/>
+ <syscall name="getegid" number="50"/>
+ <syscall name="acct" number="51"/>
+ <syscall name="umount2" number="52"/>
+ <syscall name="lock" number="53"/>
+ <syscall name="ioctl" number="54"/>
+ <syscall name="fcntl" number="55"/>
+ <syscall name="mpx" number="56"/>
+ <syscall name="setpgid" number="57"/>
+ <syscall name="ulimit" number="58"/>
+ <syscall name="oldolduname" number="59"/>
+ <syscall name="umask" number="60"/>
+ <syscall name="chroot" number="61"/>
+ <syscall name="ustat" number="62"/>
+ <syscall name="dup2" number="63"/>
+ <syscall name="getppid" number="64"/>
+ <syscall name="getpgrp" number="65"/>
+ <syscall name="setsid" number="66"/>
+ <syscall name="sigaction" number="67"/>
+ <syscall name="sgetmask" number="68"/>
+ <syscall name="ssetmask" number="69"/>
+ <syscall name="setreuid" number="70"/>
+ <syscall name="setregid" number="71"/>
+ <syscall name="sigsuspend" number="72"/>
+ <syscall name="sigpending" number="73"/>
+ <syscall name="sethostname" number="74"/>
+ <syscall name="setrlimit" number="75"/>
+ <syscall name="getrlimit" number="76"/>
+ <syscall name="getrusage" number="77"/>
+ <syscall name="gettimeofday" number="78"/>
+ <syscall name="settimeofday" number="79"/>
+ <syscall name="getgroups" number="80"/>
+ <syscall name="setgroups" number="81"/>
+ <syscall name="select" number="82"/>
+ <syscall name="symlink" number="83"/>
+ <syscall name="oldlstat" number="84"/>
+ <syscall name="readlink" number="85"/>
+ <syscall name="uselib" number="86"/>
+ <syscall name="swapon" number="87"/>
+ <syscall name="reboot" number="88"/>
+ <syscall name="readdir" number="89"/>
+ <syscall name="mmap" number="90"/>
+ <syscall name="munmap" number="91"/>
+ <syscall name="truncate" number="92"/>
+ <syscall name="ftruncate" number="93"/>
+ <syscall name="fchmod" number="94"/>
+ <syscall name="fchown" number="95"/>
+ <syscall name="getpriority" number="96"/>
+ <syscall name="setpriority" number="97"/>
+ <syscall name="profil" number="98"/>
+ <syscall name="statfs" number="99"/>
+ <syscall name="fstatfs" number="100"/>
+ <syscall name="ioperm" number="101"/>
+ <syscall name="socketcall" number="102"/>
+ <syscall name="syslog" number="103"/>
+ <syscall name="setitimer" number="104"/>
+ <syscall name="getitimer" number="105"/>
+ <syscall name="stat" number="106"/>
+ <syscall name="lstat" number="107"/>
+ <syscall name="fstat" number="108"/>
+ <syscall name="olduname" number="109"/>
+ <syscall name="iopl" number="110"/>
+ <syscall name="vhangup" number="111"/>
+ <syscall name="idle" number="112"/>
+ <syscall name="vm86" number="113"/>
+ <syscall name="wait4" number="114"/>
+ <syscall name="swapoff" number="115"/>
+ <syscall name="sysinfo" number="116"/>
+ <syscall name="ipc" number="117"/>
+ <syscall name="fsync" number="118"/>
+ <syscall name="sigreturn" number="119"/>
+ <syscall name="clone" number="120"/>
+ <syscall name="setdomainname" number="121"/>
+ <syscall name="uname" number="122"/>
+ <syscall name="modify_ldt" number="123"/>
+ <syscall name="adjtimex" number="124"/>
+ <syscall name="mprotect" number="125"/>
+ <syscall name="sigprocmask" number="126"/>
+ <syscall name="create_module" number="127"/>
+ <syscall name="init_module" number="128"/>
+ <syscall name="delete_module" number="129"/>
+ <syscall name="get_kernel_syms" number="130"/>
+ <syscall name="quotactl" number="131"/>
+ <syscall name="getpgid" number="132"/>
+ <syscall name="fchdir" number="133"/>
+ <syscall name="bdflush" number="134"/>
+ <syscall name="sysfs" number="135"/>
+ <syscall name="personality" number="136"/>
+ <syscall name="afs_syscall" number="137"/>
+ <syscall name="setfsuid" number="138"/>
+ <syscall name="setfsgid" number="139"/>
+ <syscall name="_llseek" number="140"/>
+ <syscall name="getdents" number="141"/>
+ <syscall name="_newselect" number="142"/>
+ <syscall name="flock" number="143"/>
+ <syscall name="msync" number="144"/>
+ <syscall name="readv" number="145"/>
+ <syscall name="writev" number="146"/>
+ <syscall name="getsid" number="147"/>
+ <syscall name="fdatasync" number="148"/>
+ <syscall name="_sysctl" number="149"/>
+ <syscall name="mlock" number="150"/>
+ <syscall name="munlock" number="151"/>
+ <syscall name="mlockall" number="152"/>
+ <syscall name="munlockall" number="153"/>
+ <syscall name="sched_setparam" number="154"/>
+ <syscall name="sched_getparam" number="155"/>
+ <syscall name="sched_setscheduler" number="156"/>
+ <syscall name="sched_getscheduler" number="157"/>
+ <syscall name="sched_yield" number="158"/>
+ <syscall name="sched_get_priority_max" number="159"/>
+ <syscall name="sched_get_priority_min" number="160"/>
+ <syscall name="sched_rr_get_interval" number="161"/>
+ <syscall name="nanosleep" number="162"/>
+ <syscall name="mremap" number="163"/>
+ <syscall name="setresuid" number="164"/>
+ <syscall name="getresuid" number="165"/>
+ <syscall name="query_module" number="166"/>
+ <syscall name="poll" number="167"/>
+ <syscall name="nfsservctl" number="168"/>
+ <syscall name="setresgid" number="169"/>
+ <syscall name="getresgid" number="170"/>
+ <syscall name="prctl" number="171"/>
+ <syscall name="rt_sigreturn" number="172"/>
+ <syscall name="rt_sigaction" number="173"/>
+ <syscall name="rt_sigprocmask" number="174"/>
+ <syscall name="rt_sigpending" number="175"/>
+ <syscall name="rt_sigtimedwait" number="176"/>
+ <syscall name="rt_sigqueueinfo" number="177"/>
+ <syscall name="rt_sigsuspend" number="178"/>
+ <syscall name="pread64" number="179"/>
+ <syscall name="pwrite64" number="180"/>
+ <syscall name="chown" number="181"/>
+ <syscall name="getcwd" number="182"/>
+ <syscall name="capget" number="183"/>
+ <syscall name="capset" number="184"/>
+ <syscall name="sigaltstack" number="185"/>
+ <syscall name="sendfile" number="186"/>
+ <syscall name="getpmsg" number="187"/>
+ <syscall name="putpmsg" number="188"/>
+ <syscall name="vfork" number="189"/>
+ <syscall name="ugetrlimit" number="190"/>
+ <syscall name="readahead" number="191"/>
+ <syscall name="pciconfig_read" number="198"/>
+ <syscall name="pciconfig_write" number="199"/>
+ <syscall name="pciconfig_iobase" number="200"/>
+ <syscall name="multiplexer" number="201"/>
+ <syscall name="getdents64" number="202"/>
+ <syscall name="pivot_root" number="203"/>
+ <syscall name="madvise" number="205"/>
+ <syscall name="mincore" number="206"/>
+ <syscall name="gettid" number="207"/>
+ <syscall name="tkill" number="208"/>
+ <syscall name="setxattr" number="209"/>
+ <syscall name="lsetxattr" number="210"/>
+ <syscall name="fsetxattr" number="211"/>
+ <syscall name="getxattr" number="212"/>
+ <syscall name="lgetxattr" number="213"/>
+ <syscall name="fgetxattr" number="214"/>
+ <syscall name="listxattr" number="215"/>
+ <syscall name="llistxattr" number="216"/>
+ <syscall name="flistxattr" number="217"/>
+ <syscall name="removexattr" number="218"/>
+ <syscall name="lremovexattr" number="219"/>
+ <syscall name="fremovexattr" number="220"/>
+ <syscall name="futex" number="221"/>
+ <syscall name="sched_setaffinity" number="222"/>
+ <syscall name="sched_getaffinity" number="223"/>
+ <syscall name="tuxcall" number="225"/>
+ <syscall name="io_setup" number="227"/>
+ <syscall name="io_destroy" number="228"/>
+ <syscall name="io_getevents" number="229"/>
+ <syscall name="io_submit" number="230"/>
+ <syscall name="io_cancel" number="231"/>
+ <syscall name="set_tid_address" number="232"/>
+ <syscall name="fadvise64" number="233"/>
+ <syscall name="exit_group" number="234"/>
+ <syscall name="lookup_dcookie" number="235"/>
+ <syscall name="epoll_create" number="236"/>
+ <syscall name="epoll_ctl" number="237"/>
+ <syscall name="epoll_wait" number="238"/>
+ <syscall name="remap_file_pages" number="239"/>
+ <syscall name="timer_create" number="240"/>
+ <syscall name="timer_settime" number="241"/>
+ <syscall name="timer_gettime" number="242"/>
+ <syscall name="timer_getoverrun" number="243"/>
+ <syscall name="timer_delete" number="244"/>
+ <syscall name="clock_settime" number="245"/>
+ <syscall name="clock_gettime" number="246"/>
+ <syscall name="clock_getres" number="247"/>
+ <syscall name="clock_nanosleep" number="248"/>
+ <syscall name="swapcontext" number="249"/>
+ <syscall name="tgkill" number="250"/>
+ <syscall name="utimes" number="251"/>
+ <syscall name="statfs64" number="252"/>
+ <syscall name="fstatfs64" number="253"/>
+ <syscall name="rtas" number="255"/>
+ <syscall name="sys_debug_setcontext" number="256"/>
+ <syscall name="mbind" number="259"/>
+ <syscall name="get_mempolicy" number="260"/>
+ <syscall name="set_mempolicy" number="261"/>
+ <syscall name="mq_open" number="262"/>
+ <syscall name="mq_unlink" number="263"/>
+ <syscall name="mq_timedsend" number="264"/>
+ <syscall name="mq_timedreceive" number="265"/>
+ <syscall name="mq_notify" number="266"/>
+ <syscall name="mq_getsetattr" number="267"/>
+ <syscall name="kexec_load" number="268"/>
+ <syscall name="add_key" number="269"/>
+ <syscall name="request_key" number="270"/>
+ <syscall name="keyctl" number="271"/>
+ <syscall name="waitid" number="272"/>
+ <syscall name="ioprio_set" number="273"/>
+ <syscall name="ioprio_get" number="274"/>
+ <syscall name="inotify_init" number="275"/>
+ <syscall name="inotify_add_watch" number="276"/>
+ <syscall name="inotify_rm_watch" number="277"/>
+ <syscall name="spu_run" number="278"/>
+ <syscall name="spu_create" number="279"/>
+ <syscall name="pselect6" number="280"/>
+ <syscall name="ppoll" number="281"/>
+ <syscall name="unshare" number="282"/>
+ <syscall name="unlinkat" number="286"/>
+ <syscall name="renameat" number="287"/>
+ <syscall name="linkat" number="288"/>
+ <syscall name="symlinkat" number="289"/>
+ <syscall name="readlinkat" number="290"/>
+ <syscall name="fchmodat" number="291"/>
+ <syscall name="faccessat" number="292"/>
+</syscalls_info>
--- /dev/null
+<?xml version="1.0"?>
+<!-- Copyright (C) 2010-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. -->
+
+<!DOCTYPE feature SYSTEM "gdb-syscalls.dtd">
+
+<!-- This file was generated using the following file:
+
+ /usr/src/linux/arch/sparc/include/asm/unistd.h
+
+ The file mentioned above belongs to the Linux Kernel. -->
+
+<syscalls_info>
+ <syscall name="restart_syscall" number="0"/>
+ <syscall name="exit" number="1"/>
+ <syscall name="fork" number="2"/>
+ <syscall name="read" number="3"/>
+ <syscall name="write" number="4"/>
+ <syscall name="open" number="5"/>
+ <syscall name="close" number="6"/>
+ <syscall name="wait4" number="7"/>
+ <syscall name="creat" number="8"/>
+ <syscall name="link" number="9"/>
+ <syscall name="unlink" number="10"/>
+ <syscall name="execv" number="11"/>
+ <syscall name="chdir" number="12"/>
+ <syscall name="chown" number="13"/>
+ <syscall name="mknod" number="14"/>
+ <syscall name="chmod" number="15"/>
+ <syscall name="lchown" number="16"/>
+ <syscall name="brk" number="17"/>
+ <syscall name="perfctr" number="18"/>
+ <syscall name="lseek" number="19"/>
+ <syscall name="getpid" number="20"/>
+ <syscall name="capget" number="21"/>
+ <syscall name="capset" number="22"/>
+ <syscall name="setuid" number="23"/>
+ <syscall name="getuid" number="24"/>
+ <syscall name="vmsplice" number="25"/>
+ <syscall name="ptrace" number="26"/>
+ <syscall name="alarm" number="27"/>
+ <syscall name="sigaltstack" number="28"/>
+ <syscall name="pause" number="29"/>
+ <syscall name="utime" number="30"/>
+ <syscall name="lchown32" number="31"/>
+ <syscall name="fchown32" number="32"/>
+ <syscall name="access" number="33"/>
+ <syscall name="nice" number="34"/>
+ <syscall name="chown32" number="35"/>
+ <syscall name="sync" number="36"/>
+ <syscall name="kill" number="37"/>
+ <syscall name="stat" number="38"/>
+ <syscall name="sendfile" number="39"/>
+ <syscall name="lstat" number="40"/>
+ <syscall name="dup" number="41"/>
+ <syscall name="pipe" number="42"/>
+ <syscall name="times" number="43"/>
+ <syscall name="getuid32" number="44"/>
+ <syscall name="umount2" number="45"/>
+ <syscall name="setgid" number="46"/>
+ <syscall name="getgid" number="47"/>
+ <syscall name="signal" number="48"/>
+ <syscall name="geteuid" number="49"/>
+ <syscall name="getegid" number="50"/>
+ <syscall name="acct" number="51"/>
+ <syscall name="getgid32" number="53"/>
+ <syscall name="ioctl" number="54"/>
+ <syscall name="reboot" number="55"/>
+ <syscall name="mmap2" number="56"/>
+ <syscall name="symlink" number="57"/>
+ <syscall name="readlink" number="58"/>
+ <syscall name="execve" number="59"/>
+ <syscall name="umask" number="60"/>
+ <syscall name="chroot" number="61"/>
+ <syscall name="fstat" number="62"/>
+ <syscall name="fstat64" number="63"/>
+ <syscall name="getpagesize" number="64"/>
+ <syscall name="msync" number="65"/>
+ <syscall name="vfork" number="66"/>
+ <syscall name="pread64" number="67"/>
+ <syscall name="pwrite64" number="68"/>
+ <syscall name="geteuid32" number="69"/>
+ <syscall name="getegid32" number="70"/>
+ <syscall name="mmap" number="71"/>
+ <syscall name="setreuid32" number="72"/>
+ <syscall name="munmap" number="73"/>
+ <syscall name="mprotect" number="74"/>
+ <syscall name="madvise" number="75"/>
+ <syscall name="vhangup" number="76"/>
+ <syscall name="truncate64" number="77"/>
+ <syscall name="mincore" number="78"/>
+ <syscall name="getgroups" number="79"/>
+ <syscall name="setgroups" number="80"/>
+ <syscall name="getpgrp" number="81"/>
+ <syscall name="setgroups32" number="82"/>
+ <syscall name="setitimer" number="83"/>
+ <syscall name="ftruncate64" number="84"/>
+ <syscall name="swapon" number="85"/>
+ <syscall name="getitimer" number="86"/>
+ <syscall name="setuid32" number="87"/>
+ <syscall name="sethostname" number="88"/>
+ <syscall name="setgid32" number="89"/>
+ <syscall name="dup2" number="90"/>
+ <syscall name="setfsuid32" number="91"/>
+ <syscall name="fcntl" number="92"/>
+ <syscall name="select" number="93"/>
+ <syscall name="setfsgid32" number="94"/>
+ <syscall name="fsync" number="95"/>
+ <syscall name="setpriority" number="96"/>
+ <syscall name="socket" number="97"/>
+ <syscall name="connect" number="98"/>
+ <syscall name="accept" number="99"/>
+ <syscall name="getpriority" number="100"/>
+ <syscall name="rt_sigreturn" number="101"/>
+ <syscall name="rt_sigaction" number="102"/>
+ <syscall name="rt_sigprocmask" number="103"/>
+ <syscall name="rt_sigpending" number="104"/>
+ <syscall name="rt_sigtimedwait" number="105"/>
+ <syscall name="rt_sigqueueinfo" number="106"/>
+ <syscall name="rt_sigsuspend" number="107"/>
+ <syscall name="setresuid32" number="108"/>
+ <syscall name="getresuid32" number="109"/>
+ <syscall name="setresgid32" number="110"/>
+ <syscall name="getresgid32" number="111"/>
+ <syscall name="setregid32" number="112"/>
+ <syscall name="recvmsg" number="113"/>
+ <syscall name="sendmsg" number="114"/>
+ <syscall name="getgroups32" number="115"/>
+ <syscall name="gettimeofday" number="116"/>
+ <syscall name="getrusage" number="117"/>
+ <syscall name="getsockopt" number="118"/>
+ <syscall name="getcwd" number="119"/>
+ <syscall name="readv" number="120"/>
+ <syscall name="writev" number="121"/>
+ <syscall name="settimeofday" number="122"/>
+ <syscall name="fchown" number="123"/>
+ <syscall name="fchmod" number="124"/>
+ <syscall name="recvfrom" number="125"/>
+ <syscall name="setreuid" number="126"/>
+ <syscall name="setregid" number="127"/>
+ <syscall name="rename" number="128"/>
+ <syscall name="truncate" number="129"/>
+ <syscall name="ftruncate" number="130"/>
+ <syscall name="flock" number="131"/>
+ <syscall name="lstat64" number="132"/>
+ <syscall name="sendto" number="133"/>
+ <syscall name="shutdown" number="134"/>
+ <syscall name="socketpair" number="135"/>
+ <syscall name="mkdir" number="136"/>
+ <syscall name="rmdir" number="137"/>
+ <syscall name="utimes" number="138"/>
+ <syscall name="stat64" number="139"/>
+ <syscall name="sendfile64" number="140"/>
+ <syscall name="getpeername" number="141"/>
+ <syscall name="futex" number="142"/>
+ <syscall name="gettid" number="143"/>
+ <syscall name="getrlimit" number="144"/>
+ <syscall name="setrlimit" number="145"/>
+ <syscall name="pivot_root" number="146"/>
+ <syscall name="prctl" number="147"/>
+ <syscall name="pciconfig_read" number="148"/>
+ <syscall name="pciconfig_write" number="149"/>
+ <syscall name="getsockname" number="150"/>
+ <syscall name="inotify_init" number="151"/>
+ <syscall name="inotify_add_watch" number="152"/>
+ <syscall name="poll" number="153"/>
+ <syscall name="getdents64" number="154"/>
+ <syscall name="fcntl64" number="155"/>
+ <syscall name="inotify_rm_watch" number="156"/>
+ <syscall name="statfs" number="157"/>
+ <syscall name="fstatfs" number="158"/>
+ <syscall name="umount" number="159"/>
+ <syscall name="sched_set_affinity" number="160"/>
+ <syscall name="sched_get_affinity" number="161"/>
+ <syscall name="getdomainname" number="162"/>
+ <syscall name="setdomainname" number="163"/>
+ <syscall name="quotactl" number="165"/>
+ <syscall name="set_tid_address" number="166"/>
+ <syscall name="mount" number="167"/>
+ <syscall name="ustat" number="168"/>
+ <syscall name="setxattr" number="169"/>
+ <syscall name="lsetxattr" number="170"/>
+ <syscall name="fsetxattr" number="171"/>
+ <syscall name="getxattr" number="172"/>
+ <syscall name="lgetxattr" number="173"/>
+ <syscall name="getdents" number="174"/>
+ <syscall name="setsid" number="175"/>
+ <syscall name="fchdir" number="176"/>
+ <syscall name="fgetxattr" number="177"/>
+ <syscall name="listxattr" number="178"/>
+ <syscall name="llistxattr" number="179"/>
+ <syscall name="flistxattr" number="180"/>
+ <syscall name="removexattr" number="181"/>
+ <syscall name="lremovexattr" number="182"/>
+ <syscall name="sigpending" number="183"/>
+ <syscall name="query_module" number="184"/>
+ <syscall name="setpgid" number="185"/>
+ <syscall name="fremovexattr" number="186"/>
+ <syscall name="tkill" number="187"/>
+ <syscall name="exit_group" number="188"/>
+ <syscall name="uname" number="189"/>
+ <syscall name="init_module" number="190"/>
+ <syscall name="personality" number="191"/>
+ <syscall name="remap_file_pages" number="192"/>
+ <syscall name="epoll_create" number="193"/>
+ <syscall name="epoll_ctl" number="194"/>
+ <syscall name="epoll_wait" number="195"/>
+ <syscall name="ioprio_set" number="196"/>
+ <syscall name="getppid" number="197"/>
+ <syscall name="sigaction" number="198"/>
+ <syscall name="sgetmask" number="199"/>
+ <syscall name="ssetmask" number="200"/>
+ <syscall name="sigsuspend" number="201"/>
+ <syscall name="oldlstat" number="202"/>
+ <syscall name="uselib" number="203"/>
+ <syscall name="readdir" number="204"/>
+ <syscall name="readahead" number="205"/>
+ <syscall name="socketcall" number="206"/>
+ <syscall name="syslog" number="207"/>
+ <syscall name="lookup_dcookie" number="208"/>
+ <syscall name="fadvise64" number="209"/>
+ <syscall name="fadvise64_64" number="210"/>
+ <syscall name="tgkill" number="211"/>
+ <syscall name="waitpid" number="212"/>
+ <syscall name="swapoff" number="213"/>
+ <syscall name="sysinfo" number="214"/>
+ <syscall name="ipc" number="215"/>
+ <syscall name="sigreturn" number="216"/>
+ <syscall name="clone" number="217"/>
+ <syscall name="ioprio_get" number="218"/>
+ <syscall name="adjtimex" number="219"/>
+ <syscall name="sigprocmask" number="220"/>
+ <syscall name="create_module" number="221"/>
+ <syscall name="delete_module" number="222"/>
+ <syscall name="get_kernel_syms" number="223"/>
+ <syscall name="getpgid" number="224"/>
+ <syscall name="bdflush" number="225"/>
+ <syscall name="sysfs" number="226"/>
+ <syscall name="afs_syscall" number="227"/>
+ <syscall name="setfsuid" number="228"/>
+ <syscall name="setfsgid" number="229"/>
+ <syscall name="_newselect" number="230"/>
+ <syscall name="time" number="231"/>
+ <syscall name="splice" number="232"/>
+ <syscall name="stime" number="233"/>
+ <syscall name="statfs64" number="234"/>
+ <syscall name="fstatfs64" number="235"/>
+ <syscall name="_llseek" number="236"/>
+ <syscall name="mlock" number="237"/>
+ <syscall name="munlock" number="238"/>
+ <syscall name="mlockall" number="239"/>
+ <syscall name="munlockall" number="240"/>
+ <syscall name="sched_setparam" number="241"/>
+ <syscall name="sched_getparam" number="242"/>
+ <syscall name="sched_setscheduler" number="243"/>
+ <syscall name="sched_getscheduler" number="244"/>
+ <syscall name="sched_yield" number="245"/>
+ <syscall name="sched_get_priority_max" number="246"/>
+ <syscall name="sched_get_priority_min" number="247"/>
+ <syscall name="sched_rr_get_interval" number="248"/>
+ <syscall name="nanosleep" number="249"/>
+ <syscall name="mremap" number="250"/>
+ <syscall name="_sysctl" number="251"/>
+ <syscall name="getsid" number="252"/>
+ <syscall name="fdatasync" number="253"/>
+ <syscall name="nfsservctl" number="254"/>
+ <syscall name="sync_file_range" number="255"/>
+ <syscall name="clock_settime" number="256"/>
+ <syscall name="clock_gettime" number="257"/>
+ <syscall name="clock_getres" number="258"/>
+ <syscall name="clock_nanosleep" number="259"/>
+ <syscall name="sched_getaffinity" number="260"/>
+ <syscall name="sched_setaffinity" number="261"/>
+ <syscall name="timer_settime" number="262"/>
+ <syscall name="timer_gettime" number="263"/>
+ <syscall name="timer_getoverrun" number="264"/>
+ <syscall name="timer_delete" number="265"/>
+ <syscall name="timer_create" number="266"/>
+ <syscall name="vserver" number="267"/>
+ <syscall name="io_setup" number="268"/>
+ <syscall name="io_destroy" number="269"/>
+ <syscall name="io_submit" number="270"/>
+ <syscall name="io_cancel" number="271"/>
+ <syscall name="io_getevents" number="272"/>
+ <syscall name="mq_open" number="273"/>
+ <syscall name="mq_unlink" number="274"/>
+ <syscall name="mq_timedsend" number="275"/>
+ <syscall name="mq_timedreceive" number="276"/>
+ <syscall name="mq_notify" number="277"/>
+ <syscall name="mq_getsetattr" number="278"/>
+ <syscall name="waitid" number="279"/>
+ <syscall name="tee" number="280"/>
+ <syscall name="add_key" number="281"/>
+ <syscall name="request_key" number="282"/>
+ <syscall name="keyctl" number="283"/>
+ <syscall name="openat" number="284"/>
+ <syscall name="mkdirat" number="285"/>
+ <syscall name="mknodat" number="286"/>
+ <syscall name="fchownat" number="287"/>
+ <syscall name="futimesat" number="288"/>
+ <syscall name="fstatat64" number="289"/>
+ <syscall name="unlinkat" number="290"/>
+ <syscall name="renameat" number="291"/>
+ <syscall name="linkat" number="292"/>
+ <syscall name="symlinkat" number="293"/>
+ <syscall name="readlinkat" number="294"/>
+ <syscall name="fchmodat" number="295"/>
+ <syscall name="faccessat" number="296"/>
+ <syscall name="pselect6" number="297"/>
+ <syscall name="ppoll" number="298"/>
+ <syscall name="unshare" number="299"/>
+ <syscall name="set_robust_list" number="300"/>
+ <syscall name="get_robust_list" number="301"/>
+ <syscall name="migrate_pages" number="302"/>
+ <syscall name="mbind" number="303"/>
+ <syscall name="get_mempolicy" number="304"/>
+ <syscall name="set_mempolicy" number="305"/>
+ <syscall name="kexec_load" number="306"/>
+ <syscall name="move_pages" number="307"/>
+ <syscall name="getcpu" number="308"/>
+ <syscall name="epoll_pwait" number="309"/>
+ <syscall name="utimensat" number="310"/>
+ <syscall name="signalfd" number="311"/>
+ <syscall name="timerfd_create" number="312"/>
+ <syscall name="eventfd" number="313"/>
+ <syscall name="fallocate" number="314"/>
+ <syscall name="timerfd_settime" number="315"/>
+ <syscall name="timerfd_gettime" number="316"/>
+ <syscall name="signalfd4" number="317"/>
+ <syscall name="eventfd2" number="318"/>
+ <syscall name="epoll_create1" number="319"/>
+ <syscall name="dup3" number="320"/>
+ <syscall name="pipe2" number="321"/>
+ <syscall name="inotify_init1" number="322"/>
+ <syscall name="accept4" number="323"/>
+ <syscall name="preadv" number="324"/>
+ <syscall name="pwritev" number="325"/>
+ <syscall name="rt_tgsigqueueinfo" number="326"/>
+ <syscall name="perf_event_open" number="327"/>
+ <syscall name="recvmmsg" number="328"/>
+</syscalls_info>
--- /dev/null
+<?xml version="1.0"?>
+<!-- Copyright (C) 2010-2014 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved. -->
+
+<!DOCTYPE feature SYSTEM "gdb-syscalls.dtd">
+
+<!-- This file was generated using the following file:
+
+ /usr/src/linux/arch/sparc/include/asm/unistd.h
+
+ The file mentioned above belongs to the Linux Kernel. -->
+
+<syscalls_info>
+ <syscall name="restart_syscall" number="0"/>
+ <syscall name="exit" number="1"/>
+ <syscall name="fork" number="2"/>
+ <syscall name="read" number="3"/>
+ <syscall name="write" number="4"/>
+ <syscall name="open" number="5"/>
+ <syscall name="close" number="6"/>
+ <syscall name="wait4" number="7"/>
+ <syscall name="creat" number="8"/>
+ <syscall name="link" number="9"/>
+ <syscall name="unlink" number="10"/>
+ <syscall name="execv" number="11"/>
+ <syscall name="chdir" number="12"/>
+ <syscall name="chown" number="13"/>
+ <syscall name="mknod" number="14"/>
+ <syscall name="chmod" number="15"/>
+ <syscall name="lchown" number="16"/>
+ <syscall name="brk" number="17"/>
+ <syscall name="perfctr" number="18"/>
+ <syscall name="lseek" number="19"/>
+ <syscall name="getpid" number="20"/>
+ <syscall name="capget" number="21"/>
+ <syscall name="capset" number="22"/>
+ <syscall name="setuid" number="23"/>
+ <syscall name="getuid" number="24"/>
+ <syscall name="vmsplice" number="25"/>
+ <syscall name="ptrace" number="26"/>
+ <syscall name="alarm" number="27"/>
+ <syscall name="sigaltstack" number="28"/>
+ <syscall name="pause" number="29"/>
+ <syscall name="utime" number="30"/>
+ <syscall name="access" number="33"/>
+ <syscall name="nice" number="34"/>
+ <syscall name="sync" number="36"/>
+ <syscall name="kill" number="37"/>
+ <syscall name="stat" number="38"/>
+ <syscall name="sendfile" number="39"/>
+ <syscall name="lstat" number="40"/>
+ <syscall name="dup" number="41"/>
+ <syscall name="pipe" number="42"/>
+ <syscall name="times" number="43"/>
+ <syscall name="umount2" number="45"/>
+ <syscall name="setgid" number="46"/>
+ <syscall name="getgid" number="47"/>
+ <syscall name="signal" number="48"/>
+ <syscall name="geteuid" number="49"/>
+ <syscall name="getegid" number="50"/>
+ <syscall name="acct" number="51"/>
+ <syscall name="memory_ordering" number="52"/>
+ <syscall name="ioctl" number="54"/>
+ <syscall name="reboot" number="55"/>
+ <syscall name="symlink" number="57"/>
+ <syscall name="readlink" number="58"/>
+ <syscall name="execve" number="59"/>
+ <syscall name="umask" number="60"/>
+ <syscall name="chroot" number="61"/>
+ <syscall name="fstat" number="62"/>
+ <syscall name="fstat64" number="63"/>
+ <syscall name="getpagesize" number="64"/>
+ <syscall name="msync" number="65"/>
+ <syscall name="vfork" number="66"/>
+ <syscall name="pread64" number="67"/>
+ <syscall name="pwrite64" number="68"/>
+ <syscall name="mmap" number="71"/>
+ <syscall name="munmap" number="73"/>
+ <syscall name="mprotect" number="74"/>
+ <syscall name="madvise" number="75"/>
+ <syscall name="vhangup" number="76"/>
+ <syscall name="mincore" number="78"/>
+ <syscall name="getgroups" number="79"/>
+ <syscall name="setgroups" number="80"/>
+ <syscall name="getpgrp" number="81"/>
+ <syscall name="setitimer" number="83"/>
+ <syscall name="swapon" number="85"/>
+ <syscall name="getitimer" number="86"/>
+ <syscall name="sethostname" number="88"/>
+ <syscall name="dup2" number="90"/>
+ <syscall name="fcntl" number="92"/>
+ <syscall name="select" number="93"/>
+ <syscall name="fsync" number="95"/>
+ <syscall name="setpriority" number="96"/>
+ <syscall name="socket" number="97"/>
+ <syscall name="connect" number="98"/>
+ <syscall name="accept" number="99"/>
+ <syscall name="getpriority" number="100"/>
+ <syscall name="rt_sigreturn" number="101"/>
+ <syscall name="rt_sigaction" number="102"/>
+ <syscall name="rt_sigprocmask" number="103"/>
+ <syscall name="rt_sigpending" number="104"/>
+ <syscall name="rt_sigtimedwait" number="105"/>
+ <syscall name="rt_sigqueueinfo" number="106"/>
+ <syscall name="rt_sigsuspend" number="107"/>
+ <syscall name="setresuid" number="108"/>
+ <syscall name="getresuid" number="109"/>
+ <syscall name="setresgid" number="110"/>
+ <syscall name="getresgid" number="111"/>
+ <syscall name="recvmsg" number="113"/>
+ <syscall name="sendmsg" number="114"/>
+ <syscall name="gettimeofday" number="116"/>
+ <syscall name="getrusage" number="117"/>
+ <syscall name="getsockopt" number="118"/>
+ <syscall name="getcwd" number="119"/>
+ <syscall name="readv" number="120"/>
+ <syscall name="writev" number="121"/>
+ <syscall name="settimeofday" number="122"/>
+ <syscall name="fchown" number="123"/>
+ <syscall name="fchmod" number="124"/>
+ <syscall name="recvfrom" number="125"/>
+ <syscall name="setreuid" number="126"/>
+ <syscall name="setregid" number="127"/>
+ <syscall name="rename" number="128"/>
+ <syscall name="truncate" number="129"/>
+ <syscall name="ftruncate" number="130"/>
+ <syscall name="flock" number="131"/>
+ <syscall name="lstat64" number="132"/>
+ <syscall name="sendto" number="133"/>
+ <syscall name="shutdown" number="134"/>
+ <syscall name="socketpair" number="135"/>
+ <syscall name="mkdir" number="136"/>
+ <syscall name="rmdir" number="137"/>
+ <syscall name="utimes" number="138"/>
+ <syscall name="stat64" number="139"/>
+ <syscall name="sendfile64" number="140"/>
+ <syscall name="getpeername" number="141"/>
+ <syscall name="futex" number="142"/>
+ <syscall name="gettid" number="143"/>
+ <syscall name="getrlimit" number="144"/>
+ <syscall name="setrlimit" number="145"/>
+ <syscall name="pivot_root" number="146"/>
+ <syscall name="prctl" number="147"/>
+ <syscall name="pciconfig_read" number="148"/>
+ <syscall name="pciconfig_write" number="149"/>
+ <syscall name="getsockname" number="150"/>
+ <syscall name="inotify_init" number="151"/>
+ <syscall name="inotify_add_watch" number="152"/>
+ <syscall name="poll" number="153"/>
+ <syscall name="getdents64" number="154"/>
+ <syscall name="inotify_rm_watch" number="156"/>
+ <syscall name="statfs" number="157"/>
+ <syscall name="fstatfs" number="158"/>
+ <syscall name="umount" number="159"/>
+ <syscall name="sched_set_affinity" number="160"/>
+ <syscall name="sched_get_affinity" number="161"/>
+ <syscall name="getdomainname" number="162"/>
+ <syscall name="setdomainname" number="163"/>
+ <syscall name="utrap_install" number="164"/>
+ <syscall name="quotactl" number="165"/>
+ <syscall name="set_tid_address" number="166"/>
+ <syscall name="mount" number="167"/>
+ <syscall name="ustat" number="168"/>
+ <syscall name="setxattr" number="169"/>
+ <syscall name="lsetxattr" number="170"/>
+ <syscall name="fsetxattr" number="171"/>
+ <syscall name="getxattr" number="172"/>
+ <syscall name="lgetxattr" number="173"/>
+ <syscall name="getdents" number="174"/>
+ <syscall name="setsid" number="175"/>
+ <syscall name="fchdir" number="176"/>
+ <syscall name="fgetxattr" number="177"/>
+ <syscall name="listxattr" number="178"/>
+ <syscall name="llistxattr" number="179"/>
+ <syscall name="flistxattr" number="180"/>
+ <syscall name="removexattr" number="181"/>
+ <syscall name="lremovexattr" number="182"/>
+ <syscall name="sigpending" number="183"/>
+ <syscall name="query_module" number="184"/>
+ <syscall name="setpgid" number="185"/>
+ <syscall name="fremovexattr" number="186"/>
+ <syscall name="tkill" number="187"/>
+ <syscall name="exit_group" number="188"/>
+ <syscall name="uname" number="189"/>
+ <syscall name="init_module" number="190"/>
+ <syscall name="personality" number="191"/>
+ <syscall name="remap_file_pages" number="192"/>
+ <syscall name="epoll_create" number="193"/>
+ <syscall name="epoll_ctl" number="194"/>
+ <syscall name="epoll_wait" number="195"/>
+ <syscall name="ioprio_set" number="196"/>
+ <syscall name="getppid" number="197"/>
+ <syscall name="sigaction" number="198"/>
+ <syscall name="sgetmask" number="199"/>
+ <syscall name="ssetmask" number="200"/>
+ <syscall name="sigsuspend" number="201"/>
+ <syscall name="oldlstat" number="202"/>
+ <syscall name="uselib" number="203"/>
+ <syscall name="readdir" number="204"/>
+ <syscall name="readahead" number="205"/>
+ <syscall name="socketcall" number="206"/>
+ <syscall name="syslog" number="207"/>
+ <syscall name="lookup_dcookie" number="208"/>
+ <syscall name="fadvise64" number="209"/>
+ <syscall name="fadvise64_64" number="210"/>
+ <syscall name="tgkill" number="211"/>
+ <syscall name="waitpid" number="212"/>
+ <syscall name="swapoff" number="213"/>
+ <syscall name="sysinfo" number="214"/>
+ <syscall name="ipc" number="215"/>
+ <syscall name="sigreturn" number="216"/>
+ <syscall name="clone" number="217"/>
+ <syscall name="ioprio_get" number="218"/>
+ <syscall name="adjtimex" number="219"/>
+ <syscall name="sigprocmask" number="220"/>
+ <syscall name="create_module" number="221"/>
+ <syscall name="delete_module" number="222"/>
+ <syscall name="get_kernel_syms" number="223"/>
+ <syscall name="getpgid" number="224"/>
+ <syscall name="bdflush" number="225"/>
+ <syscall name="sysfs" number="226"/>
+ <syscall name="afs_syscall" number="227"/>
+ <syscall name="setfsuid" number="228"/>
+ <syscall name="setfsgid" number="229"/>
+ <syscall name="_newselect" number="230"/>
+ <syscall name="splice" number="232"/>
+ <syscall name="stime" number="233"/>
+ <syscall name="statfs64" number="234"/>
+ <syscall name="fstatfs64" number="235"/>
+ <syscall name="_llseek" number="236"/>
+ <syscall name="mlock" number="237"/>
+ <syscall name="munlock" number="238"/>
+ <syscall name="mlockall" number="239"/>
+ <syscall name="munlockall" number="240"/>
+ <syscall name="sched_setparam" number="241"/>
+ <syscall name="sched_getparam" number="242"/>
+ <syscall name="sched_setscheduler" number="243"/>
+ <syscall name="sched_getscheduler" number="244"/>
+ <syscall name="sched_yield" number="245"/>
+ <syscall name="sched_get_priority_max" number="246"/>
+ <syscall name="sched_get_priority_min" number="247"/>
+ <syscall name="sched_rr_get_interval" number="248"/>
+ <syscall name="nanosleep" number="249"/>
+ <syscall name="mremap" number="250"/>
+ <syscall name="_sysctl" number="251"/>
+ <syscall name="getsid" number="252"/>
+ <syscall name="fdatasync" number="253"/>
+ <syscall name="nfsservctl" number="254"/>
+ <syscall name="sync_file_range" number="255"/>
+ <syscall name="clock_settime" number="256"/>
+ <syscall name="clock_gettime" number="257"/>
+ <syscall name="clock_getres" number="258"/>
+ <syscall name="clock_nanosleep" number="259"/>
+ <syscall name="sched_getaffinity" number="260"/>
+ <syscall name="sched_setaffinity" number="261"/>
+ <syscall name="timer_settime" number="262"/>
+ <syscall name="timer_gettime" number="263"/>
+ <syscall name="timer_getoverrun" number="264"/>
+ <syscall name="timer_delete" number="265"/>
+ <syscall name="timer_create" number="266"/>
+ <syscall name="vserver" number="267"/>
+ <syscall name="io_setup" number="268"/>
+ <syscall name="io_destroy" number="269"/>
+ <syscall name="io_submit" number="270"/>
+ <syscall name="io_cancel" number="271"/>
+ <syscall name="io_getevents" number="272"/>
+ <syscall name="mq_open" number="273"/>
+ <syscall name="mq_unlink" number="274"/>
+ <syscall name="mq_timedsend" number="275"/>
+ <syscall name="mq_timedreceive" number="276"/>
+ <syscall name="mq_notify" number="277"/>
+ <syscall name="mq_getsetattr" number="278"/>
+ <syscall name="waitid" number="279"/>
+ <syscall name="tee" number="280"/>
+ <syscall name="add_key" number="281"/>
+ <syscall name="request_key" number="282"/>
+ <syscall name="keyctl" number="283"/>
+ <syscall name="openat" number="284"/>
+ <syscall name="mkdirat" number="285"/>
+ <syscall name="mknodat" number="286"/>
+ <syscall name="fchownat" number="287"/>
+ <syscall name="futimesat" number="288"/>
+ <syscall name="fstatat64" number="289"/>
+ <syscall name="unlinkat" number="290"/>
+ <syscall name="renameat" number="291"/>
+ <syscall name="linkat" number="292"/>
+ <syscall name="symlinkat" number="293"/>
+ <syscall name="readlinkat" number="294"/>
+ <syscall name="fchmodat" number="295"/>
+ <syscall name="faccessat" number="296"/>
+ <syscall name="pselect6" number="297"/>
+ <syscall name="ppoll" number="298"/>
+ <syscall name="unshare" number="299"/>
+ <syscall name="set_robust_list" number="300"/>
+ <syscall name="get_robust_list" number="301"/>
+ <syscall name="migrate_pages" number="302"/>
+ <syscall name="mbind" number="303"/>
+ <syscall name="get_mempolicy" number="304"/>
+ <syscall name="set_mempolicy" number="305"/>
+ <syscall name="kexec_load" number="306"/>
+ <syscall name="move_pages" number="307"/>
+ <syscall name="getcpu" number="308"/>
+ <syscall name="epoll_pwait" number="309"/>
+ <syscall name="utimensat" number="310"/>
+ <syscall name="signalfd" number="311"/>
+ <syscall name="timerfd_create" number="312"/>
+ <syscall name="eventfd" number="313"/>
+ <syscall name="fallocate" number="314"/>
+ <syscall name="timerfd_settime" number="315"/>
+ <syscall name="timerfd_gettime" number="316"/>
+ <syscall name="signalfd4" number="317"/>
+ <syscall name="eventfd2" number="318"/>
+ <syscall name="epoll_create1" number="319"/>
+ <syscall name="dup3" number="320"/>
+ <syscall name="pipe2" number="321"/>
+ <syscall name="inotify_init1" number="322"/>
+ <syscall name="accept4" number="323"/>
+ <syscall name="preadv" number="324"/>
+ <syscall name="pwritev" number="325"/>
+ <syscall name="rt_tgsigqueueinfo" number="326"/>
+ <syscall name="perf_event_open" number="327"/>
+ <syscall name="recvmmsg" number="328"/>
+</syscalls_info>
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+"""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()
--- /dev/null
+# 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 <http://www.gnu.org/licenses/>.
+
+"""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"
--- /dev/null
+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".
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <RET> 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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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.
+ <http://fsf.org/>
+
+ 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
+ <http://www.gnu.org/copyleft/>.
+
+ 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.
+
+
+\1f
+Tag Table:
+Node: Top\7f1166
+Node: Annotations Overview\7f2336
+Node: Limitations\7f4135
+Node: Migrating to GDB/MI\7f6720
+Node: Server Prefix\7f7103
+Node: Value Annotations\7f7749
+Node: Frame Annotations\7f10919
+Node: Displays\7f14818
+Node: Prompting\7f15849
+Node: Errors\7f17352
+Node: Breakpoint Info\7f18242
+Node: Invalidation\7f19467
+Node: Annotations for Running\7f19948
+Node: Source Annotations\7f21461
+Node: Multi-threaded Apps\7f22407
+Node: GNU Free Documentation License\7f23017
+\1f
+End Tag Table
--- /dev/null
+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
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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').
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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::
+
+\1f
+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;
+ }
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 } \
+ }
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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;
+
+\1f
+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))
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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 <<WDISP30>>.) 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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+<http://www-cs-faculty.stanford.edu/~knuth/programs/mmix.tar.gz>
+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
+<http://www-cs-faculty.stanford.edu/~knuth/mmix.html> 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::
+
+\1f
+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
+<http://www-cs-faculty.stanford.edu/~knuth/mmixal-intro.ps.gz>, 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.
+ <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.
+
+\1f
+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
+<http://www-cs-faculty.stanford.edu/~knuth/programs/mmix.tar.gz>):
+"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.
+
+\1f
+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.
+
+\1f
+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.
+ <http://fsf.org/>
+
+ 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
+ <http://www.gnu.org/copyleft/>.
+
+ 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.
+
+\1f
+File: bfd.info, Node: BFD Index, Prev: GNU Free Documentation License, Up: Top
+
+BFD Index
+*********
+
+\0\b[index\0\b]
+* 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)
+
+
+\1f
+Tag Table:
+Node: Top\7f1056
+Node: Overview\7f1392
+Node: History\7f2450
+Node: How It Works\7f3395
+Node: What BFD Version 2 Can Do\7f4932
+Node: BFD information loss\7f6249
+Node: Canonical format\7f8790
+Node: BFD front end\7f13167
+Node: typedef bfd\7f13591
+Node: Error reporting\7f24512
+Node: Miscellaneous\7f29371
+Node: Memory Usage\7f46501
+Node: Initialization\7f47732
+Node: Sections\7f48191
+Node: Section Input\7f48674
+Node: Section Output\7f50043
+Node: typedef asection\7f52530
+Node: section prototypes\7f78656
+Node: Symbols\7f88924
+Node: Reading Symbols\7f90527
+Node: Writing Symbols\7f91635
+Node: Mini Symbols\7f93379
+Node: typedef asymbol\7f94353
+Node: symbol handling functions\7f100394
+Node: Archives\7f105725
+Node: Formats\7f109753
+Node: Relocations\7f112704
+Node: typedef arelent\7f113431
+Node: howto manager\7f129082
+Node: Core Files\7f240822
+Node: Targets\7f242860
+Node: bfd_target\7f244835
+Node: Architectures\7f268049
+Node: Opening and Closing\7f295156
+Node: Internal\7f309471
+Node: File Caching\7f315818
+Node: Linker Functions\7f317736
+Node: Creating a Linker Hash Table\7f319410
+Node: Adding Symbols to the Hash Table\7f321149
+Node: Differing file formats\7f322049
+Node: Adding symbols from an object file\7f323774
+Node: Adding symbols from an archive\7f325924
+Node: Performing the Final Link\7f328853
+Node: Information provided by the linker\7f330094
+Node: Relocating the section contents\7f331248
+Node: Writing the symbol table\7f333000
+Node: Hash Tables\7f337383
+Node: Creating and Freeing a Hash Table\7f338581
+Node: Looking Up or Entering a String\7f339831
+Node: Traversing a Hash Table\7f341084
+Node: Deriving a New Hash Table Type\7f341873
+Node: Define the Derived Structures\7f342939
+Node: Write the Derived Creation Routine\7f344020
+Node: Write Other Derived Routines\7f346644
+Node: BFD back ends\7f347959
+Node: What to Put Where\7f348229
+Node: aout\7f348409
+Node: coff\7f354732
+Node: elf\7f383206
+Node: mmo\7f383607
+Node: File layout\7f384532
+Node: Symbol-table\7f390170
+Node: mmo section mapping\7f393937
+Node: GNU Free Documentation License\7f397591
+Node: BFD Index\7f422654
+\1f
+End Tag Table
--- /dev/null
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <stdio.h>
+ #include <stdlib.h>
+ #include <sys/types.h>
+ #include <utime.h>
+
+ 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.
+
+\1f
+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 <stdio.h>
+
+ #ifdef STDC_HEADERS
+ #include <stdlib.h>
+ #endif
+
+ #include <sys/types.h>
+
+ #ifdef HAVE_UTIME_H
+ #include <utime.h>
+ #endif
+
+ #ifndef HAVE_UTIME_NULL
+
+ #include <time.h>
+
+ #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.
+
+\1f
+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
+
+\1f
+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'
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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*'.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+File: configure.info, Node: Index, Prev: FAQ, Up: Top
+
+Index
+*****
+
+\0\b[index\0\b]
+* 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)
+
+
+\1f
+Tag Table:
+Node: Top\7f966
+Node: Introduction\7f1494
+Node: Goals\7f2576
+Node: Tools\7f3300
+Node: History\7f4289
+Node: Building\7f7285
+Node: Getting Started\7f10548
+Node: Write configure.in\7f11061
+Node: Write Makefile.am\7f18275
+Node: Write acconfig.h\7f21431
+Node: Generate files\7f22968
+Node: Getting Started Example\7f24934
+Node: Getting Started Example 1\7f25689
+Node: Getting Started Example 2\7f27610
+Node: Getting Started Example 3\7f30605
+Node: Generate Files in Example\7f32966
+Node: Files\7f34052
+Node: Developer Files\7f34663
+Node: Developer Files Picture\7f35043
+Node: Written Developer Files\7f36343
+Node: Generated Developer Files\7f38895
+Node: Build Files\7f42039
+Node: Build Files Picture\7f42700
+Node: Build Files Description\7f43463
+Node: Support Files\7f45463
+Node: Configuration Names\7f48332
+Node: Configuration Name Definition\7f48831
+Node: Using Configuration Names\7f51151
+Node: Cross Compilation Tools\7f53121
+Node: Cross Compilation Concepts\7f53812
+Node: Host and Target\7f54780
+Node: Using the Host Type\7f56281
+Node: Specifying the Target\7f57628
+Node: Using the Target Type\7f58417
+Node: Cross Tools in the Cygnus Tree\7f61847
+Node: Host and Target Libraries\7f62904
+Node: Target Library Configure Scripts\7f66649
+Node: Make Targets in Cygnus Tree\7f69741
+Node: Target libiberty\7f71089
+Node: Canadian Cross\7f72475
+Node: Canadian Cross Example\7f73316
+Node: Canadian Cross Concepts\7f74435
+Node: Build Cross Host Tools\7f75947
+Node: Build and Host Options\7f76899
+Node: CCross not in Cygnus Tree\7f78685
+Node: CCross in Cygnus Tree\7f79663
+Node: Standard Cygnus CCross\7f80084
+Node: Cross Cygnus CCross\7f81448
+Node: Supporting Canadian Cross\7f84248
+Node: CCross in Configure\7f84863
+Node: CCross in Make\7f88028
+Node: Cygnus Configure\7f89631
+Node: Cygnus Configure Basics\7f90466
+Node: Cygnus Configure in C++ Libraries\7f95144
+Node: Multilibs\7f96151
+Node: Multilibs in gcc\7f97196
+Node: Multilibs in Target Libraries\7f98274
+Node: FAQ\7f102458
+Node: Index\7f106559
+\1f
+End Tag Table
--- /dev/null
+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."
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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 <licensing@gnu.org>.
+
+ 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
+<http://www.fsf.org/doc/other-free-books.html>.
+
+\1f
+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.
+
+\1f
+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 '<QUOTE>' and the close quote
+string to '<UNQUOTE>', 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(<QUOTE>,<UNQUOTE>)
+
+ define(baz,defn(<QUOTE>foo<UNQUOTE>))
+ 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(<QUOTE>,<UNQUOTE>)
+
+ 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 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
+ 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 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
+ 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 "<QUOTE>"
+ (gdb) p rquote
+ $2 = 0x35d50 "<UNQUOTE>"
+
+'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(<QUOTE>foo<UNQUOTE>))
+
+ 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
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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::).
+
+\1f
+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.
+
+\1f
+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.).
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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 <RET>. You can also use the <TAB> 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
+
+\1f
+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 <RET>) 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 <RET>,
+construct new arguments rather than repeating exactly as typed. This
+permits easy scanning of source or memory.
+
+ GDB can also use <RET> 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 <RET> 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 <RET>, and then
+fetches the next line relative to the current line from the history for
+editing.
+
+\1f
+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 <TAB> 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 <RET> to enter it). For
+example, if you type
+
+ (gdb) info bre <TAB>
+
+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 <RET> 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 <RET>
+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 <TAB>, GDB sounds a bell. You can either supply more characters
+and try again, or just press <TAB> 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_<TAB>' GDB just sounds the bell. Typing <TAB> again
+displays all the function names in your program that begin with those
+characters, for example:
+
+ (gdb) b make_ <TAB>
+GDB sounds bell; press <TAB> 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 <TAB> twice. 'M-?' means
+'<META> ?'. You can type this either by holding down a key designated
+as the <META> shift on your keyboard (if there is one) while typing '?',
+or as <ESC> 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 <TAB> 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 <TAB>
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <RET> 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 <RET> 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.).
+
+\1f
+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).
+
+\1f
+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 <null> 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 '<null>'.
+
+'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 '<null>'.
+
+ 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.
+
+\1f
+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.
+
+\1f
+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 <null> prog1
+ (gdb) run
+ process 12020 is executing new program: prog2
+ Program exited normally.
+ (gdb) info inferiors
+ Id Description Executable
+ * 2 <null> prog2
+ 1 <null> 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 <null> prog1
+ (gdb) run
+ process 12020 is executing new program: prog2
+ Program exited normally.
+ (gdb) info inferiors
+ Id Description Executable
+ * 1 <null> 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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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..."
+
+\1f
+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 '<PENDING>'. 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 '<MULTIPLE>' 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 '<MULTIPLE>' 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 <MULTIPLE>
+ stop only if i==1
+ breakpoint already hit 1 time
+ 1.1 y 0x080486a2 in void foo<int>() at t.cc:8
+ 1.2 y 0x080486ca in void foo<double>() 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::).
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+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 <RET> 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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+<http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation> for
+a good reference on how the SDT probes are implemented.
+
+ Currently, 'SystemTap' (<http://sourceware.org/systemtap/>) SDT
+probes are supported on ELF-compatible systems. See
+<http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps> 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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 '<PENDING>'. 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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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'.
+
+\1f
+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=<optimized out>) at macro.c:242
+ #2 0x6840 in expand_token (obs=0x0, t=<optimized out>, 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 '<optimized out>'.
+
+ 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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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 <RET> 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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 <main+204>: addil 0,dp
+ 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
+ 0x32cc <main+212>: ldil 0x3000,r31
+ 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
+ 0x32d4 <main+220>: ldo 0(r31),rp
+ 0x32d8 <main+224>: addil -0x800,dp
+ 0x32dc <main+228>: ldo 0x588(r1),r26
+ 0x32e0 <main+232>: 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 <puts@plt>
+
+ 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.
+
+\1f
+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 = <Enter 0 to explore this field of type `struct SimpleStruct *'>
+ arr = <Enter 1 to explore this field of type `int [10]'>
+
+ 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
+
+\1f
+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.
+
+\1f
+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 <RET>' 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 <RET>' 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.
+
+\1f
+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 '<incomplete type>'. *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'}
+
+\1f
+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 <RET>. 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
+ <RET>
+ <RET>
+ ...
+
+\1f
+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.
+
+\1f
+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 <RET> 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 <main+11>: mov %esp,%ebp
+ 0x8048381 <main+13>: push %ecx
+ 0x8048382 <main+14>: sub $0x4,%esp
+ => 0x8048385 <main+17>: movl $0x8048460,(%esp)
+ 0x804838c <main+24>: call 0x80482d4 <puts@plt>
+
+ 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.
+
+\1f
+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 <RET> 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 <RET> 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.
+
+\1f
+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 <t in hi2.c>
+
+ _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=<optimized out>)
+ #0 born (val=10)
+ #0 invalid (val=<optimized out>)
+
+ '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=<optimized out>)
+ #0 invalid (val@entry=<optimized out>)
+
+ '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=<optimized out>)
+
+ '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=<optimized out>)
+
+ '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=<optimized out>, val@entry=5)
+ #0 born (val=10, val@entry=<optimized out>)
+ #0 invalid (val=<optimized out>, val@entry=<optimized out>)
+
+ '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 '<optimized out>'. 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=<optimized out>)
+
+ '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=<optimized out>, val@entry=5)
+ #0 born (val=10)
+ #0 invalid (val=<optimized out>)
+
+ 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 '"<repeats N
+ times>"', 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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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 = {
+ <std::allocator<char>> = {
+ <__gnu_cxx::new_allocator<char>> = {
+ <No data fields>}, <No data fields>
+ },
+ members of std::basic_string<char, std::char_traits<char>,
+ std::allocator<char> >::_Alloc_hider:
+ _M_p = 0x804a014 "abcd"
+ }
+ }
+
+ With a pretty-printer for 'std::string' only the contents are
+printed:
+
+ (gdb) print s
+ $2 = "abcd"
+
+\1f
+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.
+
+\1f
+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 <RET>.
+
+ 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 <RET> to repeat 'show values N' has exactly the same effect
+as 'show values +'.
+
+\1f
+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 <RET>.
+
+ 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 <signal.h>
+
+ 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.
+
+\1f
+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.
+
+\1f
+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 '<not saved>' 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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 <TAB><TAB>'.
+
+'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 <TAB><TAB>', 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 <TAB><TAB>', 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 <TAB><TAB>'.
+
+'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 <stdio.h>
+
+ 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 <TAB><TAB>, 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.
+
+\1f
+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.
+
+\1f
+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 <hello.1620+6>
+ 1 pattern found
+ (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
+ 0x8049567 <hello.1620>
+ 0x804956d <hello.1620+6>
+ 2 patterns found
+ (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
+ 0x8049567 <hello.1620>
+ 1 pattern found
+ (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
+ 0x8049560 <mixed.1625>
+ 1 pattern found
+ (gdb) print $numfound
+ $1 = 1
+ (gdb) print $_
+ $2 = (void *) 0x8049560
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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 <b(int, double)+11>: jmp 0x400640 <c(int, double)>
+ (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=<optimized out>) 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
+'<optimized out>' instead.
+
+\1f
+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 <stdio.h>
+ #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.
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <MULTIPLE>
+ 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 <PENDING> 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'.
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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 <RET> repeatedly you
+can examine all the trace snapshots in order. Or, by saying 'tfind -'
+and then hitting <RET> 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
+
+\1f
+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.
+
+\1f
+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'
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <main>
+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 <foo>
+
+ 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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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:]
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <JMPBUF_SAVE>[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.
+
+\1f
+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'.
+
+\1f
+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::.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 '<incomplete type>'. 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>
+
+ "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:
+ {<no data fields>}
+
+'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)
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <RET> 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.
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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 <RET> 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 <RET> 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 <RET> 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:'.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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" <program>
+
+ Instead you must do, for example,
+
+ $ gdb -iex "set use-deprecated-index-sections on" <program>
+
+ 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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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
+
+\1f
+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.).
+
+\1f
+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 <RET> 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 <RET> again after using it.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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, <http://lttng.org/ust>) 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.
+
+\1f
+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'
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.).
+
+\1f
+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::
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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-<BREAK>'
+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
+
+\1f
+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 <cygwin1!__argv>: 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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'
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: gdb.info, Node: Alpha, Next: MIPS, Prev: i386, Up: Architectures
+
+21.4.3 Alpha
+------------
+
+See the following section.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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').
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+<RET> 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.
+
+\1f
+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 <RET> 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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 <RET> (*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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 "<string>", line 1, in <module>
+ 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
+
+\1f
+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.
+
+\1f
+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::).
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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<char,.*>$")
+ 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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <TAB> and <M-?> 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.
+
+\1f
+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.
+
+\1f
+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!"
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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"
+
+\1f
+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::).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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:
+
+<PgUp>
+ Scroll the active window one page up.
+
+<PgDn>
+ Scroll the active window one page down.
+
+<Up>
+ Scroll the active window one line up.
+
+<Down>
+ Scroll the active window one line down.
+
+<Left>
+ Scroll the active window one column left.
+
+<Right>
+ 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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <SPC>' ('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 <RET> 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::).
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::).
+
+\1f
+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 <gdb@sourceware.org> and <gdb-patches@sourceware.org>.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 '<PENDING>', for a pending
+ breakpoint; or the string '<MULTIPLE>', 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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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)
+
+\1f
+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).
+
+\1f
+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)
+
+\1f
+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::
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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
+
+\1f
+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)
+
+\1f
+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'.
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <RET> 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::).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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 <bug-gdb@gnu.org> 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.
+
+\1f
+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.
+
+\1f
+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 <k> 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 <k>
+key is pressed. The Meta key is labeled <ALT> on many keyboards. On
+keyboards with two keys labeled <ALT> (usually to either side of the
+space bar), the <ALT> on the left side is generally set to work as a
+Meta key. The <ALT> 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 <ALT> key, or another key working as a
+Meta key, the identical keystroke can be generated by typing <ESC>
+_first_, and then typing <k>. Either process is known as "metafying"
+the <k> 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, <DEL>,
+<ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen
+in this text, or in an init file (*note Readline Init File::). If your
+keyboard lacks a <LFD> key, typing <C-j> will produce the desired
+character. The <RET> key may be labeled <Return> or <Enter> on some
+keyboards.
+
+\1f
+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 <RET>. You do not have to be at the end of
+the line to press <RET>; 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.
+
+\1f
+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.
+<DEL> or <Backspace>
+ 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 <Backspace> key be set to delete
+the character to the left of the cursor and the <DEL> key set to delete
+the character underneath the cursor, like 'C-d', rather than the
+character to the left of the cursor.)
+
+\1f
+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 <DEL>.
+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.
+
+\1f
+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-<DEL>'
+ 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-<DEL>' 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'.
+
+\1f
+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.
+
+\1f
+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 <ESC> 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 <RET> 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.
+
+\1f
+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.
+
+\1f
+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 <ESC> 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 <ESC> 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 '<ESC> <[> <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\\": "\\"
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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".
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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-<TAB>)'
+ 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.
+
+\1f
+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-<DEL>)'
+ 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'.
+
+\1f
+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.
+
+\1f
+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 (<TAB>)'
+ 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 <TAB>, 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.
+
+\1f
+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.
+
+\1f
+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 (<ESC>)'
+ Metafy the next character typed. This is for keyboards without a
+ meta key. Typing '<ESC> 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.
+
+\1f
+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 <ESC> 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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 <http://expat.sourceforge.net>.
+ 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
+ <http://zlib.net>.
+
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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...
+ -> +
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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 <RET>. 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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
+
+Lseek Flags
+...........
+
+ SEEK_SET 0
+ SEEK_CUR 1
+ SEEK_END 2
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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:
+
+ <library-list>
+ <library name="/lib/libc.so.6">
+ <segment address="0x10000000"/>
+ </library>
+ </library-list>
+
+ Another simple memory map, with one loaded library with three
+allocated sections (.text, .data, .bss), looks like this:
+
+ <library-list>
+ <library name="sharedlib.o">
+ <section address="0x10000000"/>
+ <section address="0x20000000"/>
+ <section address="0x30000000"/>
+ </library>
+ </library-list>
+
+ The format of a library list is described by this DTD:
+
+ <!-- library-list: Root element with versioning -->
+ <!ELEMENT library-list (library)*>
+ <!ATTLIST library-list version CDATA #FIXED "1.0">
+ <!ELEMENT library (segment*, section*)>
+ <!ATTLIST library name CDATA #REQUIRED>
+ <!ELEMENT segment EMPTY>
+ <!ATTLIST segment address CDATA #REQUIRED>
+ <!ELEMENT section EMPTY>
+ <!ATTLIST section address CDATA #REQUIRED>
+
+ 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.
+
+\1f
+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:
+
+ <library-list-svr4 version="1.0" main-lm="0xe4f8f8">
+ <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
+ l_ld="0xe4eefc"/>
+ <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
+ l_ld="0x152350"/>
+ </library-list-svr>
+
+ The format of an SVR4 library list is described by this DTD:
+
+ <!-- library-list-svr4: Root element with versioning -->
+ <!ELEMENT library-list-svr4 (library)*>
+ <!ATTLIST library-list-svr4 version CDATA #FIXED "1.0">
+ <!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED>
+ <!ELEMENT library EMPTY>
+ <!ATTLIST library name CDATA #REQUIRED>
+ <!ATTLIST library lm CDATA #REQUIRED>
+ <!ATTLIST library l_addr CDATA #REQUIRED>
+ <!ATTLIST library l_ld CDATA #REQUIRED>
+
+\1f
+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:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE memory-map
+ PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+ "http://sourceware.org/gdb/gdb-memory-map.dtd">
+ <memory-map>
+ region...
+ </memory-map>
+
+ Each region can be either:
+
+ * A region of RAM starting at ADDR and extending for LENGTH bytes
+ from there:
+
+ <memory type="ram" start="ADDR" length="LENGTH"/>
+
+ * A region of read-only memory:
+
+ <memory type="rom" start="ADDR" length="LENGTH"/>
+
+ * A region of flash memory, with erasure blocks BLOCKSIZE bytes in
+ length:
+
+ <memory type="flash" start="ADDR" length="LENGTH">
+ <property name="blocksize">BLOCKSIZE</property>
+ </memory>
+
+ 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:
+
+ <!-- ................................................... -->
+ <!-- Memory Map XML DTD ................................ -->
+ <!-- File: memory-map.dtd .............................. -->
+ <!-- .................................... .............. -->
+ <!-- memory-map.dtd -->
+ <!-- memory-map: Root element with versioning -->
+ <!ELEMENT memory-map (memory | property)>
+ <!ATTLIST memory-map version CDATA #FIXED "1.0.0">
+ <!ELEMENT memory (property)>
+ <!-- memory: Specifies a memory region,
+ and its type, or device. -->
+ <!ATTLIST memory type CDATA #REQUIRED
+ start CDATA #REQUIRED
+ length CDATA #REQUIRED
+ device CDATA #IMPLIED>
+ <!-- property: Generic attribute tag -->
+ <!ELEMENT property (#PCDATA | property)*>
+ <!ATTLIST property name CDATA #REQUIRED>
+
+\1f
+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:
+
+ <?xml version="1.0"?>
+ <threads>
+ <thread id="id" core="0">
+ ... description ...
+ </thread>
+ </threads>
+
+ 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.
+
+\1f
+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:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE traceframe-info
+ PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+ "http://sourceware.org/gdb/gdb-traceframe-info.dtd">
+ <traceframe-info>
+ block...
+ </traceframe-info>
+
+ Each traceframe block can be either:
+
+ * A region of collected memory starting at ADDR and extending for
+ LENGTH bytes from there:
+
+ <memory start="ADDR" length="LENGTH"/>
+
+ * A block indicating trace state variable numbered NUMBER has been
+ collected:
+
+ <tvar id="NUMBER"/>
+
+ The formal DTD for the traceframe info format is given below:
+
+ <!ELEMENT traceframe-info (memory | tvar)* >
+ <!ATTLIST traceframe-info version CDATA #FIXED "1.0">
+
+ <!ELEMENT memory EMPTY>
+ <!ATTLIST memory start CDATA #REQUIRED
+ length CDATA #REQUIRED>
+ <!ELEMENT tvar>
+ <!ATTLIST tvar id CDATA #REQUIRED>
+
+\1f
+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:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE btrace
+ PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"
+ "http://sourceware.org/gdb/gdb-btrace.dtd">
+ <btrace>
+ block...
+ </btrace>
+
+ * A block of sequentially executed instructions starting at BEGIN and
+ ending at END:
+
+ <block begin="BEGIN" end="END"/>
+
+ The formal DTD for the branch trace format is given below:
+
+ <!ELEMENT btrace (block)* >
+ <!ATTLIST btrace version CDATA #FIXED "1.0">
+
+ <!ELEMENT block EMPTY>
+ <!ATTLIST block begin CDATA #REQUIRED
+ end CDATA #REQUIRED>
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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<<B
+ Pop two integers from the stack; let A be the next-to-top value,
+ and B be the top value. Shift A left by B bits, and push the
+ result.
+
+'rsh_signed' (0x0a): A B => '(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<B
+ Pop two signed integers from the stack; if the next-to-top value is
+ less than the top value, push the value one; otherwise, push the
+ value zero.
+
+'less_unsigned' (0x15): A B => A<B
+ Pop two unsigned integers from the stack; if the next-to-top value
+ is less than the top value, push the value one; otherwise, push the
+ value zero.
+
+'ext' (0x16) N: 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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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:
+
+ <target version="1.0">
+ <architecture>i386:x86-64</architecture>
+ </target>
+
+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.
+
+ <?xml version="1.0"?>
+ <!DOCTYPE target SYSTEM "gdb-target.dtd">
+ <target version="1.0">
+ [ARCHITECTURE]
+ [OSABI]
+ [COMPATIBLE]
+ [FEATURE...]
+ </target>
+
+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 '<target>' 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:
+
+ <xi:include href="DOCUMENT"/>
+
+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 '<architecture>' element has this form:
+
+ <architecture>ARCH</architecture>
+
+ 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 '<osabi>' element has this form:
+
+ <osabi>ABI-NAME</osabi>
+
+ 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 '<compatible>' element has this form:
+
+ <compatible>ARCH</compatible>
+
+ ARCH is one of the architectures from the set accepted by 'set
+architecture' (*note Specifying a Debugging Target: Targets.).
+
+ A '<compatible>' element is used to specify that the target is able
+to run binaries in some other than the main target architecture given by
+the '<architecture>' 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 '<compatible>' is as
+follows:
+
+ <architecture>powerpc:common</architecture>
+ <compatible>spu</compatible>
+
+G.2.5 Features
+--------------
+
+Each '<feature>' describes some logical portion of the target system.
+Features are currently used to describe available CPU registers and the
+types of their contents. A '<feature>' element has this form:
+
+ <feature name="NAME">
+ [TYPE...]
+ REG...
+ </feature>
+
+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 '<feature>') 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 '<vector>' elements,
+specifying the array element type, TYPE, and the number of elements,
+COUNT:
+
+ <vector id="ID" type="TYPE" count="COUNT"/>
+
+ If a register's value is usefully viewed in multiple ways, define it
+with a union type containing the useful representations. The '<union>'
+element contains one or more '<field>' elements, each of which has a
+NAME and a TYPE:
+
+ <union id="ID">
+ <field name="NAME" type="TYPE"/>
+ ...
+ </union>
+
+ If a register's value is composed from several separate values,
+define it with a structure type. There are two forms of the '<struct>'
+element; a '<struct>' 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.
+
+ <struct id="ID" size="SIZE">
+ <field name="NAME" start="START" end="END"/>
+ ...
+ </struct>
+
+ If the structure contains no bitfields, then each field has an
+explicit type, and no implicit padding is added.
+
+ <struct id="ID">
+ <field name="NAME" type="TYPE"/>
+ ...
+ </struct>
+
+ If a register's value is a series of single-bit flags, define it with
+a flags type. The '<flags>' element has an explicit SIZE and contains
+one or more '<field>' elements. Each field has a NAME, a START, and an
+END. Only single-bit flags are supported.
+
+ <flags id="ID" size="SIZE">
+ <field name="NAME" start="START" end="END"/>
+ ...
+ </flags>
+
+G.2.7 Registers
+---------------
+
+Each register is represented as an element with this form:
+
+ <reg name="NAME"
+ bitsize="SIZE"
+ [regnum="NUM"]
+ [save-restore="SAVE-RESTORE"]
+ [type="TYPE"]
+ [group="GROUP"]/>
+
+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'.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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').
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE target SYSTEM "osdata.dtd">
+ <osdata type="processes">
+ <item>
+ <column name="pid">1</column>
+ <column name="user">root</column>
+ <column name="command">/sbin/init</column>
+ <column name="cores">1,2,3</column>
+ </item>
+ </osdata>
+
+ 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.
+
+\1f
+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.
+
+\1f
+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);
+ }
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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. <http://fsf.org/>
+
+ 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 <http://www.gnu.org/licenses/>.
+
+ 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 <http://www.gnu.org/licenses/>.
+
+ 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 <http://www.gnu.org/philosophy/why-not-lgpl.html>.
+
+\1f
+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.
+ <http://fsf.org/>
+
+ 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
+ <http://www.gnu.org/copyleft/>.
+
+ 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.
+
+\1f
+File: gdb.info, Node: Concept Index, Next: Command and Variable Index, Prev: GNU Free Documentation License, Up: Top
+
+Concept Index
+*************
+
+\0\b[index\0\b]
+* 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)
+* <architecture>: Target Description Format.
+ (line 72)
+* '<compatible>': Target Description Format.
+ (line 95)
+* <feature>: Target Description Format.
+ (line 119)
+* <flags>: Target Description Format.
+ (line 185)
+* <not saved> values: Registers. (line 101)
+* '<osabi>': Target Description Format.
+ (line 82)
+* <reg>: Target Description Format.
+ (line 198)
+* <struct>: Target Description Format.
+ (line 163)
+* <union>: Target Description Format.
+ (line 153)
+* <vector>: 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)
+
+\1f
+File: gdb.info, Node: Command and Variable Index, Prev: Concept Index, Up: Top
+
+Command, Variable, and Function Index
+*************************************
+
+\0\b[index\0\b]
+* 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-<DEL>): 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 (<TAB>): 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 (<ESC>): 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-<TAB>): 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)
+
+
+\1f
+Tag Table:
+Node: Top\7f1702
+Node: Summary\7f5160
+Node: Free Software\7f7021
+Node: Free Documentation\7f7761
+Node: Contributors\7f12695
+Node: Sample Session\7f20793
+Node: Invocation\7f27631
+Node: Invoking GDB\7f28174
+Node: File Options\7f30486
+Node: Mode Options\7f33543
+Ref: -nx\7f33770
+Ref: -nh\7f34854
+Node: Startup\7f41157
+Ref: Home Directory Init File\7f41708
+Ref: Option -init-eval-command\7f41818
+Ref: Init File in the Current Directory during Startup\7f42158
+Ref: Startup-Footnote-1\7f44354
+Node: Quitting GDB\7f44463
+Node: Shell Commands\7f45360
+Node: Logging Output\7f46287
+Node: Commands\7f47124
+Node: Command Syntax\7f47762
+Node: Completion\7f49928
+Ref: Completion-Footnote-1\7f55292
+Node: Help\7f55452
+Node: Running\7f61203
+Node: Compilation\7f62432
+Node: Starting\7f64516
+Node: Arguments\7f74638
+Node: Environment\7f75907
+Node: Working Directory\7f79283
+Node: Input/Output\7f80435
+Node: Attach\7f82406
+Node: Kill Process\7f84872
+Node: Inferiors and Programs\7f85853
+Node: Threads\7f93095
+Ref: set libthread-db-search-path\7f100499
+Node: Forks\7f102553
+Node: Checkpoint/Restart\7f108867
+Ref: Checkpoint/Restart-Footnote-1\7f113395
+Node: Stopping\7f113430
+Node: Breakpoints\7f114693
+Node: Set Breaks\7f118232
+Node: Set Watchpoints\7f136950
+Node: Set Catchpoints\7f146354
+Node: Delete Breaks\7f157224
+Node: Disabling\7f159164
+Node: Conditions\7f162549
+Node: Break Commands\7f168196
+Node: Dynamic Printf\7f171417
+Node: Save Breakpoints\7f175676
+Node: Static Probe Points\7f176851
+Node: Error in Breakpoints\7f179538
+Node: Breakpoint-related Warnings\7f180274
+Node: Continuing and Stepping\7f182601
+Ref: range stepping\7f191976
+Node: Skipping Over Functions and Files\7f193056
+Node: Signals\7f196628
+Ref: extra signal information\7f201058
+Node: Thread Stops\7f202562
+Node: All-Stop Mode\7f203661
+Node: Non-Stop Mode\7f207561
+Node: Background Execution\7f211034
+Node: Thread-Specific Breakpoints\7f213598
+Node: Interrupted System Calls\7f215602
+Node: Observer Mode\7f217116
+Node: Reverse Execution\7f220552
+Ref: Reverse Execution-Footnote-1\7f225177
+Ref: Reverse Execution-Footnote-2\7f225804
+Node: Process Record and Replay\7f225854
+Node: Stack\7f238819
+Node: Frames\7f240367
+Node: Backtrace\7f243119
+Ref: backtrace-command\7f243470
+Ref: Backtrace-Footnote-1\7f249240
+Node: Frame Filter Management\7f249428
+Ref: disable frame-filter all\7f249972
+Node: Selection\7f254272
+Node: Frame Info\7f257150
+Node: Source\7f259137
+Node: List\7f260203
+Node: Specify Location\7f262905
+Node: Edit\7f267509
+Ref: Edit-Footnote-1\7f268985
+Node: Search\7f269220
+Node: Source Path\7f270028
+Ref: set substitute-path\7f276394
+Node: Machine Code\7f278614
+Node: Data\7f285515
+Node: Expressions\7f293179
+Node: Ambiguous Expressions\7f295270
+Node: Variables\7f298500
+Node: Arrays\7f304566
+Node: Output Formats\7f307097
+Ref: Output Formats-Footnote-1\7f310470
+Node: Memory\7f310627
+Node: Auto Display\7f316779
+Node: Print Settings\7f321321
+Ref: set print entry-values\7f329483
+Node: Pretty Printing\7f340797
+Node: Pretty-Printer Introduction\7f341311
+Node: Pretty-Printer Example\7f343066
+Node: Pretty-Printer Commands\7f343844
+Node: Value History\7f346268
+Node: Convenience Vars\7f348690
+Node: Convenience Funs\7f355172
+Node: Registers\7f358043
+Ref: Registers-Footnote-1\7f363972
+Node: Floating Point Hardware\7f364367
+Node: Vector Unit\7f364899
+Node: OS Information\7f365286
+Ref: linux info os infotypes\7f367310
+Node: Memory Region Attributes\7f371517
+Node: Dump/Restore Files\7f376181
+Node: Core File Generation\7f378486
+Node: Character Sets\7f379710
+Node: Caching Target Data\7f386075
+Ref: Caching Target Data-Footnote-1\7f388803
+Node: Searching Memory\7f389041
+Node: Optimized Code\7f391919
+Node: Inline Functions\7f393596
+Node: Tail Call Frames\7f396223
+Ref: set debug entry-values\7f398363
+Node: Macros\7f402437
+Ref: Macros-Footnote-1\7f410013
+Node: Tracepoints\7f410166
+Node: Set Tracepoints\7f412228
+Node: Create and Delete Tracepoints\7f415166
+Node: Enable and Disable Tracepoints\7f421567
+Node: Tracepoint Passcounts\7f422807
+Node: Tracepoint Conditions\7f424218
+Node: Trace State Variables\7f425912
+Node: Tracepoint Actions\7f428103
+Node: Listing Tracepoints\7f434406
+Node: Listing Static Tracepoint Markers\7f436108
+Node: Starting and Stopping Trace Experiments\7f437956
+Ref: disconnected tracing\7f439701
+Node: Tracepoint Restrictions\7f444121
+Node: Analyze Collected Data\7f447890
+Node: tfind\7f449196
+Node: tdump\7f453618
+Node: save tracepoints\7f456133
+Node: Tracepoint Variables\7f456629
+Node: Trace Files\7f457757
+Node: Overlays\7f460127
+Node: How Overlays Work\7f460847
+Ref: A code overlay\7f463402
+Node: Overlay Commands\7f466815
+Node: Automatic Overlay Debugging\7f470997
+Node: Overlay Sample Program\7f473136
+Node: Languages\7f474873
+Node: Setting\7f476036
+Node: Filenames\7f477737
+Node: Manually\7f478548
+Node: Automatically\7f479757
+Node: Show\7f480818
+Ref: show language\7f481106
+Node: Checks\7f482140
+Node: Type Checking\7f483145
+Node: Range Checking\7f484974
+Node: Supported Languages\7f487375
+Node: C\7f488675
+Node: C Operators\7f489639
+Node: C Constants\7f493952
+Node: C Plus Plus Expressions\7f496831
+Node: C Defaults\7f500174
+Node: C Checks\7f500842
+Node: Debugging C\7f501402
+Node: Debugging C Plus Plus\7f501886
+Node: Decimal Floating Point\7f505360
+Node: D\7f506630
+Node: Go\7f506888
+Node: Objective-C\7f507982
+Node: Method Names in Commands\7f508445
+Node: The Print Command with Objective-C\7f510136
+Node: OpenCL C\7f510787
+Node: OpenCL C Datatypes\7f511062
+Node: OpenCL C Expressions\7f511437
+Node: OpenCL C Operators\7f511794
+Node: Fortran\7f512026
+Node: Fortran Operators\7f512747
+Node: Fortran Defaults\7f513603
+Node: Special Fortran Commands\7f513988
+Node: Pascal\7f514494
+Node: Modula-2\7f515009
+Node: M2 Operators\7f515984
+Node: Built-In Func/Proc\7f518982
+Node: M2 Constants\7f521842
+Node: M2 Types\7f523443
+Node: M2 Defaults\7f526661
+Node: Deviations\7f527262
+Node: M2 Checks\7f528363
+Node: M2 Scope\7f529180
+Node: GDB/M2\7f530204
+Node: Ada\7f531117
+Node: Ada Mode Intro\7f532227
+Node: Omissions from Ada\7f534138
+Node: Additions to Ada\7f538491
+Node: Stopping Before Main Program\7f542418
+Node: Ada Exceptions\7f542952
+Node: Ada Tasks\7f544149
+Node: Ada Tasks and Core Files\7f550553
+Node: Ravenscar Profile\7f551471
+Node: Ada Glitches\7f552540
+Node: Unsupported Languages\7f555328
+Node: Symbols\7f556018
+Node: Altering\7f573359
+Node: Assignment\7f574328
+Node: Jumping\7f577434
+Node: Signaling\7f579596
+Node: Returning\7f580729
+Node: Calling\7f584080
+Node: Patching\7f587107
+Node: GDB Files\7f588184
+Node: Files\7f588904
+Ref: Shared Libraries\7f602494
+Ref: Files-Footnote-1\7f614124
+Node: Separate Debug Files\7f614299
+Ref: debug-file-directory\7f617403
+Node: MiniDebugInfo\7f626048
+Node: Index Files\7f628499
+Node: Symbol Errors\7f630561
+Node: Data Files\7f634177
+Node: Targets\7f635133
+Node: Active Targets\7f636613
+Node: Target Commands\7f637687
+Ref: load\7f641813
+Node: Byte Order\7f642794
+Node: Remote Debugging\7f643768
+Node: Connecting\7f645030
+Node: File Transfer\7f649965
+Node: Server\7f650904
+Ref: Monitor Commands for gdbserver\7f661125
+Ref: Server-Footnote-1\7f665782
+Node: Remote Configuration\7f665902
+Ref: set remotebreak\7f666928
+Ref: set remote hardware-watchpoint-limit\7f668391
+Ref: set remote hardware-breakpoint-limit\7f668391
+Ref: set remote hardware-watchpoint-length-limit\7f668617
+Ref: set remote exec-file\7f669032
+Node: Remote Stub\7f678521
+Node: Stub Contents\7f681416
+Node: Bootstrapping\7f683523
+Node: Debug Session\7f687333
+Node: Configurations\7f689374
+Node: Native\7f690143
+Node: HP-UX\7f690712
+Node: BSD libkvm Interface\7f691001
+Node: SVR4 Process Information\7f692072
+Node: DJGPP Native\7f695876
+Node: Cygwin Native\7f702435
+Node: Non-debug DLL Symbols\7f706382
+Node: Hurd Native\7f710938
+Node: Darwin\7f716194
+Node: Embedded OS\7f717455
+Node: VxWorks\7f717931
+Node: VxWorks Connection\7f720145
+Node: VxWorks Download\7f721079
+Node: VxWorks Attach\7f722814
+Node: Embedded Processors\7f723211
+Node: ARM\7f724344
+Node: M32R/D\7f728467
+Node: M68K\7f730169
+Node: MicroBlaze\7f730461
+Node: MIPS Embedded\7f731910
+Node: PowerPC Embedded\7f736847
+Node: PA\7f740613
+Node: Sparclet\7f740896
+Node: Sparclet File\7f742365
+Node: Sparclet Connection\7f743245
+Node: Sparclet Download\7f743723
+Node: Sparclet Execution\7f744771
+Node: Sparclite\7f745362
+Node: Z8000\7f745734
+Node: AVR\7f747116
+Node: CRIS\7f747479
+Node: Super-H\7f748457
+Node: Architectures\7f749516
+Node: AArch64\7f749953
+Node: i386\7f750359
+Ref: i386-Footnote-1\7f752591
+Node: Alpha\7f752677
+Node: MIPS\7f752810
+Node: HPPA\7f756704
+Node: SPU\7f757222
+Node: PowerPC\7f759408
+Node: Nios II\7f760143
+Node: Controlling GDB\7f760532
+Node: Prompt\7f761428
+Node: Editing\7f763146
+Node: Command History\7f764089
+Node: Screen Size\7f767620
+Node: Numbers\7f769554
+Node: ABI\7f771525
+Node: Auto-loading\7f774698
+Ref: set auto-load off\7f776073
+Ref: show auto-load\7f776709
+Ref: info auto-load\7f777488
+Node: Init File in the Current Directory\7f780157
+Ref: set auto-load local-gdbinit\7f780732
+Ref: show auto-load local-gdbinit\7f780914
+Ref: info auto-load local-gdbinit\7f781078
+Node: libthread_db.so.1 file\7f781226
+Ref: set auto-load libthread-db\7f782165
+Ref: show auto-load libthread-db\7f782296
+Ref: info auto-load libthread-db\7f782433
+Node: Auto-loading safe path\7f782617
+Ref: set auto-load safe-path\7f783923
+Ref: show auto-load safe-path\7f784662
+Ref: add-auto-load-safe-path\7f784785
+Node: Auto-loading verbose mode\7f787679
+Ref: set debug auto-load\7f788842
+Ref: show debug auto-load\7f788943
+Node: Messages/Warnings\7f789065
+Ref: confirmation requests\7f790499
+Node: Debugging Output\7f791703
+Node: Other Misc Settings\7f800180
+Node: Extending GDB\7f801204
+Node: Sequences\7f802927
+Node: Define\7f803588
+Node: Hooks\7f807386
+Node: Command Files\7f809751
+Node: Output\7f814824
+Node: Auto-loading sequences\7f819788
+Ref: set auto-load gdb-scripts\7f820283
+Ref: show auto-load gdb-scripts\7f820407
+Ref: info auto-load gdb-scripts\7f820537
+Node: Python\7f820768
+Node: Python Commands\7f821959
+Node: Python API\7f824287
+Node: Basic Python\7f826594
+Ref: prompt_hook\7f835194
+Node: Exception Handling\7f835792
+Node: Values From Inferior\7f838288
+Node: Types In Python\7f850286
+Node: Pretty Printing API\7f859508
+Node: Selecting Pretty-Printers\7f863404
+Node: Writing a Pretty-Printer\7f865737
+Node: Type Printing API\7f871059
+Node: Frame Filter API\7f873657
+Node: Frame Decorator API\7f880938
+Ref: frame_args\7f884522
+Node: Writing a Frame Filter\7f887852
+Node: Inferiors In Python\7f899319
+Node: Events In Python\7f902203
+Node: Threads In Python\7f907382
+Node: Commands In Python\7f909822
+Node: Parameters In Python\7f919228
+Node: Functions In Python\7f924688
+Node: Progspaces In Python\7f926905
+Node: Objfiles In Python\7f928589
+Node: Frames In Python\7f930848
+Node: Blocks In Python\7f937015
+Node: Symbols In Python\7f941377
+Node: Symbol Tables In Python\7f948585
+Node: Line Tables In Python\7f951510
+Node: Breakpoints In Python\7f954347
+Node: Finish Breakpoints in Python\7f962261
+Node: Lazy Strings In Python\7f964367
+Node: Architectures In Python\7f966601
+Node: Python Auto-loading\7f968790
+Ref: set auto-load python-scripts\7f969419
+Ref: show auto-load python-scripts\7f969519
+Ref: info auto-load python-scripts\7f969625
+Node: Python modules\7f970650
+Node: gdb.printing\7f971036
+Node: gdb.types\7f972450
+Node: gdb.prompt\7f975475
+Node: Auto-loading extensions\7f977124
+Node: objfile-gdbdotext file\7f978302
+Ref: set auto-load scripts-directory\7f979709
+Ref: with-auto-load-dir\7f980085
+Ref: show auto-load scripts-directory\7f980903
+Node: dotdebug_gdb_scripts section\7f981233
+Node: Which flavor to choose?\7f983025
+Node: Aliases\7f984846
+Node: Interpreters\7f987706
+Node: TUI\7f989804
+Node: TUI Overview\7f990748
+Node: TUI Keys\7f993181
+Node: TUI Single Key Mode\7f995485
+Node: TUI Commands\7f996360
+Node: TUI Configuration\7f998744
+Node: Emacs\7f1000050
+Node: GDB/MI\7f1005487
+Node: GDB/MI General Design\7f1007461
+Node: Context management\7f1009981
+Node: Asynchronous and non-stop modes\7f1013809
+Node: Thread groups\7f1015800
+Node: GDB/MI Command Syntax\7f1018078
+Node: GDB/MI Input Syntax\7f1018321
+Node: GDB/MI Output Syntax\7f1019871
+Node: GDB/MI Compatibility with CLI\7f1023441
+Node: GDB/MI Development and Front Ends\7f1024178
+Node: GDB/MI Output Records\7f1025832
+Node: GDB/MI Result Records\7f1026238
+Node: GDB/MI Stream Records\7f1027588
+Node: GDB/MI Async Records\7f1028853
+Node: GDB/MI Breakpoint Information\7f1038468
+Node: GDB/MI Frame Information\7f1042419
+Node: GDB/MI Thread Information\7f1043505
+Node: GDB/MI Ada Exception Information\7f1044485
+Node: GDB/MI Simple Examples\7f1044908
+Node: GDB/MI Command Description Format\7f1047116
+Node: GDB/MI Breakpoint Commands\7f1047996
+Node: GDB/MI Catchpoint Commands\7f1067842
+Node: Shared Library GDB/MI Catchpoint Commands\7f1068210
+Node: Ada Exception GDB/MI Catchpoint Commands\7f1069868
+Node: GDB/MI Program Context\7f1072272
+Node: GDB/MI Thread Commands\7f1076540
+Node: GDB/MI Ada Tasking Commands\7f1080496
+Node: GDB/MI Program Execution\7f1082749
+Node: GDB/MI Stack Manipulation\7f1094783
+Ref: -stack-list-arguments\7f1096682
+Ref: -stack-list-frames\7f1100387
+Ref: -stack-list-locals\7f1104250
+Ref: -stack-list-variables\7f1105740
+Node: GDB/MI Variable Objects\7f1107274
+Ref: -var-set-format\7f1117232
+Ref: -var-list-children\7f1118350
+Ref: -var-update\7f1127142
+Ref: -var-set-frozen\7f1130140
+Ref: -var-set-update-range\7f1130937
+Ref: -var-set-visualizer\7f1131466
+Node: GDB/MI Data Manipulation\7f1132956
+Node: GDB/MI Tracepoint Commands\7f1152494
+Node: GDB/MI Symbol Query\7f1164079
+Node: GDB/MI File Commands\7f1164768
+Node: GDB/MI Target Manipulation\7f1168063
+Node: GDB/MI File Transfer Commands\7f1174278
+Node: GDB/MI Ada Exceptions Commands\7f1175601
+Node: GDB/MI Support Commands\7f1176954
+Node: GDB/MI Miscellaneous Commands\7f1181527
+Ref: -interpreter-exec\7f1191551
+Node: Annotations\7f1193891
+Node: Annotations Overview\7f1194810
+Node: Server Prefix\7f1197273
+Node: Prompting\7f1198007
+Node: Errors\7f1199524
+Node: Invalidation\7f1200420
+Node: Annotations for Running\7f1200899
+Node: Source Annotations\7f1202419
+Node: JIT Interface\7f1203344
+Node: Declarations\7f1205143
+Node: Registering Code\7f1206530
+Node: Unregistering Code\7f1207502
+Node: Custom Debug Info\7f1208129
+Node: Using JIT Debug Info Readers\7f1209425
+Node: Writing JIT Debug Info Readers\7f1210439
+Node: In-Process Agent\7f1212634
+Ref: Control Agent\7f1214577
+Node: In-Process Agent Protocol\7f1215444
+Node: IPA Protocol Objects\7f1216235
+Ref: agent expression object\7f1217233
+Ref: tracepoint action object\7f1217438
+Ref: tracepoint object\7f1217518
+Node: IPA Protocol Commands\7f1220094
+Node: GDB Bugs\7f1221546
+Node: Bug Criteria\7f1222278
+Node: Bug Reporting\7f1223155
+Node: Command Line Editing\7f1230984
+Node: Introduction and Notation\7f1231636
+Node: Readline Interaction\7f1233257
+Node: Readline Bare Essentials\7f1234446
+Node: Readline Movement Commands\7f1236227
+Node: Readline Killing Commands\7f1237185
+Node: Readline Arguments\7f1239101
+Node: Searching\7f1240143
+Node: Readline Init File\7f1242293
+Node: Readline Init File Syntax\7f1243444
+Node: Conditional Init Constructs\7f1258543
+Node: Sample Init File\7f1261066
+Node: Bindable Readline Commands\7f1264180
+Node: Commands For Moving\7f1265232
+Node: Commands For History\7f1266090
+Node: Commands For Text\7f1269485
+Node: Commands For Killing\7f1272208
+Node: Numeric Arguments\7f1274348
+Node: Commands For Completion\7f1275484
+Node: Keyboard Macros\7f1277450
+Node: Miscellaneous Commands\7f1278018
+Node: Readline vi Mode\7f1281866
+Node: Using History Interactively\7f1282776
+Node: History Interaction\7f1283291
+Node: Event Designators\7f1284713
+Node: Word Designators\7f1285850
+Node: Modifiers\7f1287485
+Node: In Memoriam\7f1288706
+Node: Formatting Documentation\7f1289589
+Ref: Formatting Documentation-Footnote-1\7f1292909
+Node: Installing GDB\7f1292977
+Node: Requirements\7f1293549
+Ref: Expat\7f1294118
+Node: Running Configure\7f1296685
+Node: Separate Objdir\7f1300254
+Node: Config Names\7f1303149
+Node: Configure Options\7f1304598
+Node: System-wide configuration\7f1306969
+Node: System-wide Configuration Scripts\7f1308929
+Node: Maintenance Commands\7f1310113
+Ref: maint info breakpoints\7f1311768
+Node: Remote Protocol\7f1327695
+Node: Overview\7f1328349
+Ref: Binary Data\7f1330894
+Node: Packets\7f1333419
+Ref: thread-id syntax\7f1334319
+Ref: extended mode\7f1335764
+Ref: bc\7f1337488
+Ref: bs\7f1337698
+Ref: read registers packet\7f1339303
+Ref: cycle step packet\7f1341236
+Ref: write register packet\7f1343113
+Ref: step with signal packet\7f1344110
+Ref: vCont packet\7f1345566
+Ref: X packet\7f1351378
+Ref: insert breakpoint or watchpoint packet\7f1351665
+Node: Stop Reply Packets\7f1355707
+Node: General Query Packets\7f1360451
+Ref: QNonStop\7f1370675
+Ref: QPassSignals\7f1371302
+Ref: QProgramSignals\7f1372474
+Ref: qSearch memory\7f1374954
+Ref: QStartNoAckMode\7f1375453
+Ref: qSupported\7f1375984
+Ref: multiprocess extensions\7f1388682
+Ref: install tracepoint in tracing\7f1390712
+Ref: qXfer read\7f1394072
+Ref: qXfer auxiliary vector read\7f1394567
+Ref: qXfer btrace read\7f1394915
+Ref: qXfer target description read\7f1395538
+Ref: qXfer library list read\7f1395972
+Ref: qXfer svr4 library list read\7f1396628
+Ref: qXfer memory map read\7f1398481
+Ref: qXfer sdata read\7f1398868
+Ref: qXfer siginfo read\7f1399334
+Ref: qXfer spu read\7f1399731
+Ref: qXfer threads read\7f1400255
+Ref: qXfer traceframe info read\7f1400658
+Ref: qXfer unwind info block\7f1401076
+Ref: qXfer fdpic loadmap read\7f1401310
+Ref: qXfer osdata read\7f1401726
+Ref: qXfer write\7f1402933
+Ref: qXfer siginfo write\7f1403486
+Ref: qXfer spu write\7f1403883
+Ref: General Query Packets-Footnote-1\7f1406416
+Node: Architecture-Specific Protocol Details\7f1406743
+Node: ARM-Specific Protocol Details\7f1407252
+Node: ARM Breakpoint Kinds\7f1407500
+Node: MIPS-Specific Protocol Details\7f1407831
+Node: MIPS Register packet Format\7f1408114
+Node: MIPS Breakpoint Kinds\7f1409041
+Node: Tracepoint Packets\7f1409459
+Ref: QTEnable\7f1418454
+Ref: QTDisable\7f1418650
+Ref: qTfSTM\7f1424189
+Ref: qTsSTM\7f1424189
+Ref: qTSTMat\7f1425228
+Ref: QTBuffer-size\7f1426375
+Node: Host I/O Packets\7f1428344
+Node: Interrupts\7f1432954
+Node: Notification Packets\7f1434857
+Node: Remote Non-Stop\7f1440266
+Node: Packet Acknowledgment\7f1442556
+Node: Examples\7f1444671
+Node: File-I/O Remote Protocol Extension\7f1445265
+Node: File-I/O Overview\7f1445727
+Node: Protocol Basics\7f1447926
+Node: The F Request Packet\7f1450155
+Node: The F Reply Packet\7f1451056
+Node: The Ctrl-C Message\7f1451974
+Node: Console I/O\7f1453600
+Node: List of Supported Calls\7f1454816
+Node: open\7f1455178
+Node: close\7f1457686
+Node: read\7f1458069
+Node: write\7f1458678
+Node: lseek\7f1459449
+Node: rename\7f1460333
+Node: unlink\7f1461740
+Node: stat/fstat\7f1462687
+Node: gettimeofday\7f1463580
+Node: isatty\7f1464016
+Node: system\7f1464612
+Node: Protocol-specific Representation of Datatypes\7f1466154
+Node: Integral Datatypes\7f1466531
+Node: Pointer Values\7f1467338
+Node: Memory Transfer\7f1468042
+Node: struct stat\7f1468662
+Node: struct timeval\7f1470864
+Node: Constants\7f1471381
+Node: Open Flags\7f1471830
+Node: mode_t Values\7f1472171
+Node: Errno Values\7f1472663
+Node: Lseek Flags\7f1473473
+Node: Limits\7f1473658
+Node: File-I/O Examples\7f1474018
+Node: Library List Format\7f1475106
+Node: Library List Format for SVR4 Targets\7f1477888
+Node: Memory Map Format\7f1480355
+Node: Thread List Format\7f1482930
+Node: Traceframe Info Format\7f1483748
+Node: Branch Trace Format\7f1485434
+Node: Agent Expressions\7f1486779
+Node: General Bytecode Design\7f1489600
+Node: Bytecode Descriptions\7f1494394
+Node: Using Agent Expressions\7f1507825
+Node: Varying Target Capabilities\7f1509802
+Node: Rationale\7f1510963
+Node: Target Descriptions\7f1518352
+Node: Retrieving Descriptions\7f1520226
+Node: Target Description Format\7f1521311
+Node: Predefined Target Types\7f1530359
+Node: Standard Target Features\7f1531743
+Node: AArch64 Features\7f1533607
+Node: ARM Features\7f1534030
+Node: i386 Features\7f1535548
+Node: MIPS Features\7f1536905
+Node: M68K Features\7f1538090
+Node: Nios II Features\7f1538753
+Node: PowerPC Features\7f1539151
+Node: S/390 and System z Features\7f1540474
+Node: TIC6x Features\7f1541939
+Node: Operating System Information\7f1542499
+Node: Process list\7f1543334
+Node: Trace File Format\7f1544397
+Node: Index Section Format\7f1546390
+Node: Man Pages\7f1554360
+Node: gdb man\7f1554766
+Node: gdbserver man\7f1560802
+Node: gcore man\7f1567807
+Node: gdbinit man\7f1568464
+Node: Copying\7f1569347
+Node: GNU Free Documentation License\7f1606907
+Node: Concept Index\7f1632053
+Node: Command and Variable Index\7f1755064
+\1f
+End Tag Table
--- /dev/null
+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."
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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 <licensing@gnu.org>.
+
+ 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
+<http://www.fsf.org/doc/other-free-books.html>.
+
+\1f
+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.
+
+\1f
+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 '<QUOTE>' and the close quote
+string to '<UNQUOTE>', 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(<QUOTE>,<UNQUOTE>)
+
+ define(baz,defn(<QUOTE>foo<UNQUOTE>))
+ 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(<QUOTE>,<UNQUOTE>)
+
+ 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 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
+ 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 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
+ 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 "<QUOTE>"
+ (gdb) p rquote
+ $2 = 0x35d50 "<UNQUOTE>"
+
+'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(<QUOTE>foo<UNQUOTE>))
+
+ 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
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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::).
+
+\1f
+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.
+
+\1f
+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.).
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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 <RET>. You can also use the <TAB> 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
+
+\1f
+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 <RET>) 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 <RET>,
+construct new arguments rather than repeating exactly as typed. This
+permits easy scanning of source or memory.
+
+ GDB can also use <RET> 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 <RET> 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 <RET>, and then
+fetches the next line relative to the current line from the history for
+editing.
+
+\1f
+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 <TAB> 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 <RET> to enter it). For
+example, if you type
+
+ (gdb) info bre <TAB>
+
+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 <RET> 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 <RET>
+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 <TAB>, GDB sounds a bell. You can either supply more characters
+and try again, or just press <TAB> 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_<TAB>' GDB just sounds the bell. Typing <TAB> again
+displays all the function names in your program that begin with those
+characters, for example:
+
+ (gdb) b make_ <TAB>
+GDB sounds bell; press <TAB> 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 <TAB> twice. 'M-?' means
+'<META> ?'. You can type this either by holding down a key designated
+as the <META> shift on your keyboard (if there is one) while typing '?',
+or as <ESC> 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 <TAB> 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 <TAB>
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <RET> 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 <RET> 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.).
+
+\1f
+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).
+
+\1f
+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 <null> 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 '<null>'.
+
+'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 '<null>'.
+
+ 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.
+
+\1f
+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.
+
+\1f
+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 <null> prog1
+ (gdb) run
+ process 12020 is executing new program: prog2
+ Program exited normally.
+ (gdb) info inferiors
+ Id Description Executable
+ * 2 <null> prog2
+ 1 <null> 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 <null> prog1
+ (gdb) run
+ process 12020 is executing new program: prog2
+ Program exited normally.
+ (gdb) info inferiors
+ Id Description Executable
+ * 1 <null> 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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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..."
+
+\1f
+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 '<PENDING>'. 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 '<MULTIPLE>' 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 '<MULTIPLE>' 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 <MULTIPLE>
+ stop only if i==1
+ breakpoint already hit 1 time
+ 1.1 y 0x080486a2 in void foo<int>() at t.cc:8
+ 1.2 y 0x080486ca in void foo<double>() 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::).
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+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 <RET> 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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+<http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation> for
+a good reference on how the SDT probes are implemented.
+
+ Currently, 'SystemTap' (<http://sourceware.org/systemtap/>) SDT
+probes are supported on ELF-compatible systems. See
+<http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps> 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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 '<PENDING>'. 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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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'.
+
+\1f
+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=<optimized out>) at macro.c:242
+ #2 0x6840 in expand_token (obs=0x0, t=<optimized out>, 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 '<optimized out>'.
+
+ 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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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 <RET> 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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 <main+204>: addil 0,dp
+ 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
+ 0x32cc <main+212>: ldil 0x3000,r31
+ 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
+ 0x32d4 <main+220>: ldo 0(r31),rp
+ 0x32d8 <main+224>: addil -0x800,dp
+ 0x32dc <main+228>: ldo 0x588(r1),r26
+ 0x32e0 <main+232>: 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 <puts@plt>
+
+ 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.
+
+\1f
+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 = <Enter 0 to explore this field of type `struct SimpleStruct *'>
+ arr = <Enter 1 to explore this field of type `int [10]'>
+
+ 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
+
+\1f
+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.
+
+\1f
+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 <RET>' 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 <RET>' 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.
+
+\1f
+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 '<incomplete type>'. *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'}
+
--- /dev/null
+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
+
+\1f
+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 <RET>. 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
+ <RET>
+ <RET>
+ ...
+
+\1f
+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.
+
+\1f
+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 <RET> 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 <main+11>: mov %esp,%ebp
+ 0x8048381 <main+13>: push %ecx
+ 0x8048382 <main+14>: sub $0x4,%esp
+ => 0x8048385 <main+17>: movl $0x8048460,(%esp)
+ 0x804838c <main+24>: call 0x80482d4 <puts@plt>
+
+ 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.
+
+\1f
+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 <RET> 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 <RET> 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.
+
+\1f
+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 <t in hi2.c>
+
+ _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=<optimized out>)
+ #0 born (val=10)
+ #0 invalid (val=<optimized out>)
+
+ '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=<optimized out>)
+ #0 invalid (val@entry=<optimized out>)
+
+ '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=<optimized out>)
+
+ '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=<optimized out>)
+
+ '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=<optimized out>, val@entry=5)
+ #0 born (val=10, val@entry=<optimized out>)
+ #0 invalid (val=<optimized out>, val@entry=<optimized out>)
+
+ '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 '<optimized out>'. 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=<optimized out>)
+
+ '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=<optimized out>, val@entry=5)
+ #0 born (val=10)
+ #0 invalid (val=<optimized out>)
+
+ 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 '"<repeats N
+ times>"', 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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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 = {
+ <std::allocator<char>> = {
+ <__gnu_cxx::new_allocator<char>> = {
+ <No data fields>}, <No data fields>
+ },
+ members of std::basic_string<char, std::char_traits<char>,
+ std::allocator<char> >::_Alloc_hider:
+ _M_p = 0x804a014 "abcd"
+ }
+ }
+
+ With a pretty-printer for 'std::string' only the contents are
+printed:
+
+ (gdb) print s
+ $2 = "abcd"
+
+\1f
+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.
+
+\1f
+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 <RET>.
+
+ 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 <RET> to repeat 'show values N' has exactly the same effect
+as 'show values +'.
+
+\1f
+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 <RET>.
+
+ 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 <signal.h>
+
+ 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.
+
+\1f
+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.
+
+\1f
+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 '<not saved>' 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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 <TAB><TAB>'.
+
+'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 <TAB><TAB>', 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 <TAB><TAB>', 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 <TAB><TAB>'.
+
+'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 <stdio.h>
+
+ 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 <TAB><TAB>, 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.
+
+\1f
+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.
+
+\1f
+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 <hello.1620+6>
+ 1 pattern found
+ (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
+ 0x8049567 <hello.1620>
+ 0x804956d <hello.1620+6>
+ 2 patterns found
+ (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
+ 0x8049567 <hello.1620>
+ 1 pattern found
+ (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
+ 0x8049560 <mixed.1625>
+ 1 pattern found
+ (gdb) print $numfound
+ $1 = 1
+ (gdb) print $_
+ $2 = (void *) 0x8049560
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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 <b(int, double)+11>: jmp 0x400640 <c(int, double)>
+ (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=<optimized out>) 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
+'<optimized out>' instead.
+
+\1f
+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 <stdio.h>
+ #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.
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <MULTIPLE>
+ 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 <PENDING> 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'.
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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 <RET> repeatedly you
+can examine all the trace snapshots in order. Or, by saying 'tfind -'
+and then hitting <RET> 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
+
+\1f
+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.
+
+\1f
+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'
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <main>
+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 <foo>
+
+ 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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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:]
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <JMPBUF_SAVE>[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.
+
+\1f
+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'.
+
+\1f
+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::.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 '<incomplete type>'. 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>
+
+ "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:
+ {<no data fields>}
+
+'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)
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <RET> 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.
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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 <RET> 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 <RET> 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 <RET> 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:'.
+
--- /dev/null
+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
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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" <program>
+
+ Instead you must do, for example,
+
+ $ gdb -iex "set use-deprecated-index-sections on" <program>
+
+ 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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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
+
+\1f
+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.).
+
+\1f
+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 <RET> 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 <RET> again after using it.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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, <http://lttng.org/ust>) 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.
+
+\1f
+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'
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.).
+
+\1f
+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::
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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-<BREAK>'
+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
+
+\1f
+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 <cygwin1!__argv>: 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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'
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: gdb.info, Node: Alpha, Next: MIPS, Prev: i386, Up: Architectures
+
+21.4.3 Alpha
+------------
+
+See the following section.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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').
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+<RET> 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.
+
+\1f
+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 <RET> 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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 <RET> (*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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 "<string>", line 1, in <module>
+ 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
+
+\1f
+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.
+
+\1f
+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::).
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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<char,.*>$")
+ 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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
--- /dev/null
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <TAB> and <M-?> 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.
+
+\1f
+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.
+
+\1f
+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!"
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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"
+
+\1f
+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::).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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:
+
+<PgUp>
+ Scroll the active window one page up.
+
+<PgDn>
+ Scroll the active window one page down.
+
+<Up>
+ Scroll the active window one line up.
+
+<Down>
+ Scroll the active window one line down.
+
+<Left>
+ Scroll the active window one column left.
+
+<Right>
+ 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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <SPC>' ('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 <RET> 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::).
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::).
+
+\1f
+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 <gdb@sourceware.org> and <gdb-patches@sourceware.org>.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 '<PENDING>', for a pending
+ breakpoint; or the string '<MULTIPLE>', 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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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)
+
+\1f
+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).
+
+\1f
+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)
+
+\1f
+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::
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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
+
+\1f
+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)
+
+\1f
+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'.
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <RET> 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::).
+
--- /dev/null
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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 <bug-gdb@gnu.org> 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.
+
+\1f
+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.
+
+\1f
+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 <k> 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 <k>
+key is pressed. The Meta key is labeled <ALT> on many keyboards. On
+keyboards with two keys labeled <ALT> (usually to either side of the
+space bar), the <ALT> on the left side is generally set to work as a
+Meta key. The <ALT> 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 <ALT> key, or another key working as a
+Meta key, the identical keystroke can be generated by typing <ESC>
+_first_, and then typing <k>. Either process is known as "metafying"
+the <k> 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, <DEL>,
+<ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen
+in this text, or in an init file (*note Readline Init File::). If your
+keyboard lacks a <LFD> key, typing <C-j> will produce the desired
+character. The <RET> key may be labeled <Return> or <Enter> on some
+keyboards.
+
+\1f
+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 <RET>. You do not have to be at the end of
+the line to press <RET>; 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.
+
+\1f
+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.
+<DEL> or <Backspace>
+ 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 <Backspace> key be set to delete
+the character to the left of the cursor and the <DEL> key set to delete
+the character underneath the cursor, like 'C-d', rather than the
+character to the left of the cursor.)
+
+\1f
+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 <DEL>.
+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.
+
+\1f
+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-<DEL>'
+ 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-<DEL>' 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'.
+
+\1f
+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.
+
+\1f
+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 <ESC> 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 <RET> 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.
+
+\1f
+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.
+
+\1f
+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 <ESC> 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 <ESC> 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 '<ESC> <[> <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\\": "\\"
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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".
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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-<TAB>)'
+ 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.
+
+\1f
+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-<DEL>)'
+ 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'.
+
+\1f
+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.
+
+\1f
+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 (<TAB>)'
+ 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 <TAB>, 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.
+
+\1f
+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.
+
+\1f
+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 (<ESC>)'
+ Metafy the next character typed. This is for keyboards without a
+ meta key. Typing '<ESC> 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.
+
+\1f
+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 <ESC> 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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 <http://expat.sourceforge.net>.
+ 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
+ <http://zlib.net>.
+
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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...
+ -> +
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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 <RET>. 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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
+
+Lseek Flags
+...........
+
+ SEEK_SET 0
+ SEEK_CUR 1
+ SEEK_END 2
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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:
+
+ <library-list>
+ <library name="/lib/libc.so.6">
+ <segment address="0x10000000"/>
+ </library>
+ </library-list>
+
+ Another simple memory map, with one loaded library with three
+allocated sections (.text, .data, .bss), looks like this:
+
+ <library-list>
+ <library name="sharedlib.o">
+ <section address="0x10000000"/>
+ <section address="0x20000000"/>
+ <section address="0x30000000"/>
+ </library>
+ </library-list>
+
+ The format of a library list is described by this DTD:
+
+ <!-- library-list: Root element with versioning -->
+ <!ELEMENT library-list (library)*>
+ <!ATTLIST library-list version CDATA #FIXED "1.0">
+ <!ELEMENT library (segment*, section*)>
+ <!ATTLIST library name CDATA #REQUIRED>
+ <!ELEMENT segment EMPTY>
+ <!ATTLIST segment address CDATA #REQUIRED>
+ <!ELEMENT section EMPTY>
+ <!ATTLIST section address CDATA #REQUIRED>
+
+ 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.
+
+\1f
+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:
+
+ <library-list-svr4 version="1.0" main-lm="0xe4f8f8">
+ <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
+ l_ld="0xe4eefc"/>
+ <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
+ l_ld="0x152350"/>
+ </library-list-svr>
+
+ The format of an SVR4 library list is described by this DTD:
+
+ <!-- library-list-svr4: Root element with versioning -->
+ <!ELEMENT library-list-svr4 (library)*>
+ <!ATTLIST library-list-svr4 version CDATA #FIXED "1.0">
+ <!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED>
+ <!ELEMENT library EMPTY>
+ <!ATTLIST library name CDATA #REQUIRED>
+ <!ATTLIST library lm CDATA #REQUIRED>
+ <!ATTLIST library l_addr CDATA #REQUIRED>
+ <!ATTLIST library l_ld CDATA #REQUIRED>
+
+\1f
+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:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE memory-map
+ PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+ "http://sourceware.org/gdb/gdb-memory-map.dtd">
+ <memory-map>
+ region...
+ </memory-map>
+
+ Each region can be either:
+
+ * A region of RAM starting at ADDR and extending for LENGTH bytes
+ from there:
+
+ <memory type="ram" start="ADDR" length="LENGTH"/>
+
+ * A region of read-only memory:
+
+ <memory type="rom" start="ADDR" length="LENGTH"/>
+
+ * A region of flash memory, with erasure blocks BLOCKSIZE bytes in
+ length:
+
+ <memory type="flash" start="ADDR" length="LENGTH">
+ <property name="blocksize">BLOCKSIZE</property>
+ </memory>
+
+ 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:
+
+ <!-- ................................................... -->
+ <!-- Memory Map XML DTD ................................ -->
+ <!-- File: memory-map.dtd .............................. -->
+ <!-- .................................... .............. -->
+ <!-- memory-map.dtd -->
+ <!-- memory-map: Root element with versioning -->
+ <!ELEMENT memory-map (memory | property)>
+ <!ATTLIST memory-map version CDATA #FIXED "1.0.0">
+ <!ELEMENT memory (property)>
+ <!-- memory: Specifies a memory region,
+ and its type, or device. -->
+ <!ATTLIST memory type CDATA #REQUIRED
+ start CDATA #REQUIRED
+ length CDATA #REQUIRED
+ device CDATA #IMPLIED>
+ <!-- property: Generic attribute tag -->
+ <!ELEMENT property (#PCDATA | property)*>
+ <!ATTLIST property name CDATA #REQUIRED>
+
+\1f
+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:
+
+ <?xml version="1.0"?>
+ <threads>
+ <thread id="id" core="0">
+ ... description ...
+ </thread>
+ </threads>
+
+ 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.
+
+\1f
+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:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE traceframe-info
+ PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+ "http://sourceware.org/gdb/gdb-traceframe-info.dtd">
+ <traceframe-info>
+ block...
+ </traceframe-info>
+
+ Each traceframe block can be either:
+
+ * A region of collected memory starting at ADDR and extending for
+ LENGTH bytes from there:
+
+ <memory start="ADDR" length="LENGTH"/>
+
+ * A block indicating trace state variable numbered NUMBER has been
+ collected:
+
+ <tvar id="NUMBER"/>
+
+ The formal DTD for the traceframe info format is given below:
+
+ <!ELEMENT traceframe-info (memory | tvar)* >
+ <!ATTLIST traceframe-info version CDATA #FIXED "1.0">
+
+ <!ELEMENT memory EMPTY>
+ <!ATTLIST memory start CDATA #REQUIRED
+ length CDATA #REQUIRED>
+ <!ELEMENT tvar>
+ <!ATTLIST tvar id CDATA #REQUIRED>
+
+\1f
+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:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE btrace
+ PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"
+ "http://sourceware.org/gdb/gdb-btrace.dtd">
+ <btrace>
+ block...
+ </btrace>
+
+ * A block of sequentially executed instructions starting at BEGIN and
+ ending at END:
+
+ <block begin="BEGIN" end="END"/>
+
+ The formal DTD for the branch trace format is given below:
+
+ <!ELEMENT btrace (block)* >
+ <!ATTLIST btrace version CDATA #FIXED "1.0">
+
+ <!ELEMENT block EMPTY>
+ <!ATTLIST block begin CDATA #REQUIRED
+ end CDATA #REQUIRED>
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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<<B
+ Pop two integers from the stack; let A be the next-to-top value,
+ and B be the top value. Shift A left by B bits, and push the
+ result.
+
+'rsh_signed' (0x0a): A B => '(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<B
+ Pop two signed integers from the stack; if the next-to-top value is
+ less than the top value, push the value one; otherwise, push the
+ value zero.
+
+'less_unsigned' (0x15): A B => A<B
+ Pop two unsigned integers from the stack; if the next-to-top value
+ is less than the top value, push the value one; otherwise, push the
+ value zero.
+
+'ext' (0x16) N: 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.
+
--- /dev/null
+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
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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:
+
+ <target version="1.0">
+ <architecture>i386:x86-64</architecture>
+ </target>
+
+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.
+
+ <?xml version="1.0"?>
+ <!DOCTYPE target SYSTEM "gdb-target.dtd">
+ <target version="1.0">
+ [ARCHITECTURE]
+ [OSABI]
+ [COMPATIBLE]
+ [FEATURE...]
+ </target>
+
+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 '<target>' 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:
+
+ <xi:include href="DOCUMENT"/>
+
+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 '<architecture>' element has this form:
+
+ <architecture>ARCH</architecture>
+
+ 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 '<osabi>' element has this form:
+
+ <osabi>ABI-NAME</osabi>
+
+ 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 '<compatible>' element has this form:
+
+ <compatible>ARCH</compatible>
+
+ ARCH is one of the architectures from the set accepted by 'set
+architecture' (*note Specifying a Debugging Target: Targets.).
+
+ A '<compatible>' element is used to specify that the target is able
+to run binaries in some other than the main target architecture given by
+the '<architecture>' 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 '<compatible>' is as
+follows:
+
+ <architecture>powerpc:common</architecture>
+ <compatible>spu</compatible>
+
+G.2.5 Features
+--------------
+
+Each '<feature>' describes some logical portion of the target system.
+Features are currently used to describe available CPU registers and the
+types of their contents. A '<feature>' element has this form:
+
+ <feature name="NAME">
+ [TYPE...]
+ REG...
+ </feature>
+
+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 '<feature>') 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 '<vector>' elements,
+specifying the array element type, TYPE, and the number of elements,
+COUNT:
+
+ <vector id="ID" type="TYPE" count="COUNT"/>
+
+ If a register's value is usefully viewed in multiple ways, define it
+with a union type containing the useful representations. The '<union>'
+element contains one or more '<field>' elements, each of which has a
+NAME and a TYPE:
+
+ <union id="ID">
+ <field name="NAME" type="TYPE"/>
+ ...
+ </union>
+
+ If a register's value is composed from several separate values,
+define it with a structure type. There are two forms of the '<struct>'
+element; a '<struct>' 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.
+
+ <struct id="ID" size="SIZE">
+ <field name="NAME" start="START" end="END"/>
+ ...
+ </struct>
+
+ If the structure contains no bitfields, then each field has an
+explicit type, and no implicit padding is added.
+
+ <struct id="ID">
+ <field name="NAME" type="TYPE"/>
+ ...
+ </struct>
+
+ If a register's value is a series of single-bit flags, define it with
+a flags type. The '<flags>' element has an explicit SIZE and contains
+one or more '<field>' elements. Each field has a NAME, a START, and an
+END. Only single-bit flags are supported.
+
+ <flags id="ID" size="SIZE">
+ <field name="NAME" start="START" end="END"/>
+ ...
+ </flags>
+
+G.2.7 Registers
+---------------
+
+Each register is represented as an element with this form:
+
+ <reg name="NAME"
+ bitsize="SIZE"
+ [regnum="NUM"]
+ [save-restore="SAVE-RESTORE"]
+ [type="TYPE"]
+ [group="GROUP"]/>
+
+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'.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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').
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE target SYSTEM "osdata.dtd">
+ <osdata type="processes">
+ <item>
+ <column name="pid">1</column>
+ <column name="user">root</column>
+ <column name="command">/sbin/init</column>
+ <column name="cores">1,2,3</column>
+ </item>
+ </osdata>
+
+ 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.
+
+\1f
+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.
+
+\1f
+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);
+ }
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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. <http://fsf.org/>
+
+ 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 <http://www.gnu.org/licenses/>.
+
+ 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 <http://www.gnu.org/licenses/>.
+
+ 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 <http://www.gnu.org/philosophy/why-not-lgpl.html>.
+
+\1f
+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.
+ <http://fsf.org/>
+
+ 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
+ <http://www.gnu.org/copyleft/>.
+
+ 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.
+
+\1f
+File: gdb.info, Node: Concept Index, Next: Command and Variable Index, Prev: GNU Free Documentation License, Up: Top
+
+Concept Index
+*************
+
+\0\b[index\0\b]
+* 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)
+* <architecture>: Target Description Format.
+ (line 72)
+* '<compatible>': Target Description Format.
+ (line 95)
+* <feature>: Target Description Format.
+ (line 119)
+* <flags>: Target Description Format.
+ (line 185)
+* <not saved> values: Registers. (line 101)
+* '<osabi>': Target Description Format.
+ (line 82)
+* <reg>: Target Description Format.
+ (line 198)
+* <struct>: Target Description Format.
+ (line 163)
+* <union>: Target Description Format.
+ (line 153)
+* <vector>: 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)
+
+\1f
+File: gdb.info, Node: Command and Variable Index, Prev: Concept Index, Up: Top
+
+Command, Variable, and Function Index
+*************************************
+
+\0\b[index\0\b]
+* 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-<DEL>): 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 (<TAB>): 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 (<ESC>): 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-<TAB>): 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)
+
--- /dev/null
+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".
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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::).
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 ';'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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::).
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 ';'.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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::).
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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::).
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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)
+
+\1f
+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::
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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 >>
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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. >>
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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::.
+
+\1f
+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::.
+
+\1f
+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::.
+
+\1f
+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
+
+\1f
+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? >>
+
+\1f
+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)
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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?
+
+\1f
+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'.
+
+\1f
+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' <<?>>
+
+\1f
+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.
+
+\1f
+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.
+
+ <<?looking at structs and unions in C I didn't see these>>
+
+\1f
+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) <<?>>
+
+\1f
+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 ??
+
+\1f
+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.
+
+\1f
+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.)
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+ <http://fsf.org/>
+
+ 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
+ <http://www.gnu.org/copyleft/>.
+
+ 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.
+
+\1f
+File: stabs.info, Node: Symbol Types Index, Prev: GNU Free Documentation License, Up: Top
+
+Symbol Types Index
+******************
+
+\0\b[index\0\b]
+* 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)
+
+
+\1f
+Tag Table:
+Node: Top\7f1360
+Node: Overview\7f2407
+Node: Flow\7f3821
+Node: Stabs Format\7f5347
+Node: String Field\7f6909
+Node: C Example\7f12338
+Node: Assembly Code\7f12883
+Node: Program Structure\7f14854
+Node: Main Program\7f15580
+Node: Source Files\7f16141
+Node: Include Files\7f18583
+Node: Line Numbers\7f21248
+Node: Procedures\7f22782
+Node: Nested Procedures\7f28673
+Node: Block Structure\7f29849
+Node: Alternate Entry Points\7f31253
+Node: Constants\7f31986
+Node: Variables\7f35097
+Node: Stack Variables\7f35785
+Node: Global Variables\7f37486
+Node: Register Variables\7f38641
+Node: Common Blocks\7f39463
+Node: Statics\7f40716
+Node: Based Variables\7f43295
+Node: Parameters\7f44681
+Node: Register Parameters\7f46292
+Node: Local Variable Parameters\7f48552
+Node: Reference Parameters\7f51467
+Node: Conformant Arrays\7f52087
+Node: Types\7f52805
+Node: Builtin Types\7f53752
+Node: Traditional Builtin Types\7f54898
+Node: Traditional Integer Types\7f55299
+Node: Traditional Other Types\7f57607
+Node: Builtin Type Descriptors\7f58521
+Node: Negative Type Numbers\7f62021
+Node: Miscellaneous Types\7f68376
+Node: Cross-References\7f70262
+Node: Subranges\7f71937
+Node: Arrays\7f73176
+Node: Strings\7f76401
+Node: Enumerations\7f77463
+Node: Structures\7f79847
+Node: Typedefs\7f82555
+Node: Unions\7f83877
+Node: Function Types\7f85458
+Node: Macro define and undefine\7f87039
+Node: Symbol Tables\7f88612
+Node: Symbol Table Format\7f89064
+Node: Transformations On Symbol Tables\7f90511
+Node: Transformations On Static Variables\7f91865
+Node: Transformations On Global Variables\7f92601
+Node: Stab Section Transformations\7f93845
+Node: Cplusplus\7f95228
+Node: Class Names\7f95811
+Node: Nested Symbols\7f96556
+Node: Basic Cplusplus Types\7f97402
+Node: Simple Classes\7f98962
+Node: Class Instance\7f103255
+Node: Methods\7f103972
+Node: Method Type Descriptor\7f106191
+Node: Member Type Descriptor\7f107391
+Node: Protections\7f108183
+Node: Method Modifiers\7f111273
+Node: Virtual Methods\7f112901
+Node: Inheritance\7f116701
+Node: Virtual Base Classes\7f120397
+Node: Static Members\7f122642
+Node: Stab Types\7f123112
+Node: Non-Stab Symbol Types\7f123736
+Node: Stab Symbol Types\7f125119
+Node: Symbol Descriptors\7f128902
+Node: Type Descriptors\7f131681
+Node: Expanded Reference\7f134893
+Node: N_PC\7f136311
+Node: N_NSYMS\7f136679
+Node: N_NOMAP\7f136920
+Node: N_M2C\7f137226
+Node: N_BROWS\7f137659
+Node: N_DEFD\7f137942
+Node: N_EHDECL\7f138399
+Node: N_MOD2\7f138650
+Node: N_CATCH\7f138887
+Node: N_SSYM\7f139381
+Node: N_SCOPE\7f139666
+Node: Gould\7f139856
+Node: N_LENG\7f140849
+Node: Questions\7f141077
+Node: Stab Sections\7f142718
+Node: Stab Section Basics\7f143328
+Node: ELF Linker Relocation\7f146670
+Node: GNU Free Documentation License\7f150079
+Node: Symbol Types Index\7f175238
+\1f
+End Tag Table
--- /dev/null
+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
+
+\1f
+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::
+
+\1f
+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:
+<http://www.gnu.org/prep/standards/>.
+
+ 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
+<http://lists.gnu.org/mailman/listinfo/gnustandards-commit>. Archives
+are also available there.
+
+ Please send corrections or suggestions for this document to
+<bug-standards@gnu.org>. 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
+<http://savannah.gnu.org/projects/gnustandards>.
+
+ 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.
+<http://www.gnu.org/software/hello/hello.html>.
+
+ This release of the GNU Coding Standards was last updated April 12,
+2010.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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: <http://www.gnu.org/prep/maintain/>.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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
+(<http://www.gnu.org/software/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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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."
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+<http://example.org/p.cgi/--help> 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.
+
+\1f
+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 <http://gnu.org/licenses/gpl.html>
+ 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, <http://www.gnu.org/licenses/gpl.html>.
+
+LGPL
+ GNU Lesser General Public License,
+ <http://www.gnu.org/licenses/lgpl.html>.
+
+GPL/Ada
+ GNU GPL with the exception for Ada.
+
+Apache
+ The Apache Software Foundation license,
+ <http://www.apache.org/licenses>.
+
+Artistic
+ The Artistic license used for Perl,
+ <http://www.perlfoundation.org/legal>.
+
+Expat
+ The Expat license, <http://www.jclark.com/xml/copying.txt>.
+
+MPL
+ The Mozilla Public License, <http://www.mozilla.org/MPL/>.
+
+OBSD
+ The original (4-clause) BSD license, incompatible with the GNU GPL
+ <http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6>.
+
+PHP
+ The license used for PHP, <http://www.php.net/license/>.
+
+public domain
+ The non-license that is being in the public domain,
+ <http://www.gnu.org/licenses/license-list.html#PublicDomain>.
+
+Python
+ The license for Python, <http://www.python.org/2.0.1/license.html>.
+
+RBSD
+ The revised (3-clause) BSD, compatible with the GNU GPL,
+ <http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5>.
+
+X11
+ The simple non-copyleft license used for most versions of the X
+ Window System, <http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3>.
+
+Zlib
+ The license for Zlib, <http://www.gzip.org/zlib/zlib_license.html>.
+
+ More information about these licenses and many more are on the GNU
+licensing web pages, <http://www.gnu.org/licenses/license-list.html>.
+
+\1f
+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: <http://www.gnu.org/software/PKG/>
+ General help using GNU software: <http://www.gnu.org/gethelp/>
+
+ It is ok to mention other appropriate mailing lists and web pages.
+
+\1f
+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 <bug-standards@gnu.org> 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'.
+
+\1f
+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
+<http://www.alvestrand.no/objectid> has a (voluntary) listing of many
+OID assignments.
+
+ If you need a new slot for your GNU package, write
+<maintainers@gnu.org>. 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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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 */
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <http://git.savannah.gnu.org/gitweb/?p=gnulib.git>.
+Here's a sample use:
+
+ #include "error.h"
+ #include <errno.h>
+ #include <stdio.h>
+
+ 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.
+
+\1f
+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.
+
+\1f
+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);
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <http://www.gnu.org/copyleft/fdl-howto.html> 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.
+
+\1f
+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.
+
+\1f
+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
+<http://www.gnu.org/order/order.html>. 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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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 <rms@gnu.org>
+
+ * 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 <jdoe@gnu.org>
+
+ * sewing.c: Make it sew.
+
+rather than this:
+
+ 2002-07-14 Usual Maintainer <usual@gnu.org>
+
+ * sewing.c: Make it sew. Patch by jdoe@gnu.org.
+
+ As for the date, that should be the date you applied the change.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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) <sh>: Handle case that
+ user-specified option string is empty.
+
+\1f
+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
+(<http://www.gnu.org/software/help2man/>) is one way to automate
+generation of a man page, in this case from '--help' output. This is
+sufficient in many cases.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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}
+
+\1f
+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.
+
+\1f
+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
+<http://www.gnu.org/philosophy/free-sw.html>, and the definition of free
+documentation is found at <http://www.gnu.org/philosophy/free-doc.html>.
+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
+<http://www.gnu.org/licenses/license-list.html>. If it is not clear
+whether a license qualifies as free, please ask the GNU Project by
+writing to <licensing@gnu.org>. 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.
+
+\1f
+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.
+ <http://fsf.org/>
+
+ 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
+ <http://www.gnu.org/copyleft/>.
+
+ 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.
+
+\1f
+File: standards.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
+
+Index
+*****
+
+\0\b[index\0\b]
+* 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)
+
+
+\1f
+Tag Table:
+Node: Top\7f808
+Node: Preface\7f2083
+Node: Legal Issues\7f4784
+Node: Reading Non-Free Code\7f5254
+Node: Contributions\7f6983
+Node: Trademarks\7f9221
+Node: Design Advice\7f10855
+Node: Source Language\7f11447
+Node: Compatibility\7f13566
+Node: Using Extensions\7f15194
+Node: Standard C\7f16771
+Node: Conditional Compilation\7f19174
+Node: Program Behavior\7f20572
+Node: Non-GNU Standards\7f21688
+Node: Semantics\7f23969
+Node: Libraries\7f28689
+Node: Errors\7f29934
+Node: User Interfaces\7f32427
+Node: Graphical Interfaces\7f34032
+Node: Command-Line Interfaces\7f35215
+Node: --version\7f37245
+Node: --help\7f42964
+Node: Option Table\7f43837
+Node: OID Allocations\7f58792
+Node: Memory Usage\7f60589
+Node: File Usage\7f61625
+Node: Writing C\7f62375
+Node: Formatting\7f63345
+Node: Comments\7f67634
+Node: Syntactic Conventions\7f71185
+Node: Names\7f74647
+Node: System Portability\7f76859
+Node: CPU Portability\7f79750
+Node: System Functions\7f83652
+Node: Internationalization\7f88844
+Node: Character Set\7f92838
+Node: Quote Characters\7f93651
+Node: Mmap\7f95171
+Node: Documentation\7f95879
+Node: GNU Manuals\7f96985
+Node: Doc Strings and Manuals\7f102723
+Node: Manual Structure Details\7f104276
+Node: License for Manuals\7f105694
+Node: Manual Credits\7f106667
+Node: Printed Manuals\7f107060
+Node: NEWS File\7f107746
+Node: Change Logs\7f108424
+Node: Change Log Concepts\7f109178
+Node: Style of Change Logs\7f111281
+Node: Simple Changes\7f113781
+Node: Conditional Changes\7f115223
+Node: Indicating the Part Changed\7f116645
+Node: Man Pages\7f117172
+Node: Reading other Manuals\7f119346
+Node: Managing Releases\7f120137
+Node: Configuration\7f120917
+Node: Makefile Conventions\7f129580
+Node: Makefile Basics\7f130462
+Node: Utilities in Makefiles\7f133636
+Node: Command Variables\7f135782
+Node: DESTDIR\7f139005
+Node: Directory Variables\7f141154
+Node: Standard Targets\7f155639
+Ref: Standard Targets-Footnote-1\7f169155
+Node: Install Command Categories\7f169256
+Node: Releases\7f173789
+Node: References\7f177793
+Node: GNU Free Documentation License\7f183639
+Node: Index\7f208786
+\1f
+End Tag Table
--- /dev/null
+.\" 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"
--- /dev/null
+.\" 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 <comm> <program> [<args> ...]
+.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 <comm> <pid>
+.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 <comm>
+.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 <comm> <prog> [<args>...]
+.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 <comm> <pid>
+.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 <comm>
+.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 <comm> <pid>
+.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 <comm>
+.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"
--- /dev/null
+.\" 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"