Что такое примечание?

Чтобы создавать примечания, запустите GDB с ключем --annotate=2.

Примечания начинаются с символа новой строки, двух символов `control-z' и имени примечания. Если нет дополнительной информации, связанной с примечанием, непосредственно за его именем следует символ новой строки. Если дополнительная информация есть, за именем примечания следует пропуск, дополнительная информация и символ новой строки. Дополнительная информация не может содержать символа новой строки.

Любой вывод, не начинающийся с символа новой строки и двух `control-z', означает буквальный вывод GDB. В настоящее время GDB не нужно выводить два `control-z' вслед за символом новой строки, но если это понадобится, примечания могут быть расширены `экранирующим' примечанием, которое означает вывод этих трех символов.

Вот простой пример запуска GDB с примечаниями:

$ 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
$ 

Здесь `quit' является для GDB вводом; остальное---вывод GDB. Три строки, начинающиеся с `^Z^Z' (где `^Z' означает знак `control-z'), суть примечания; остальное является выводом GDB.

Префикс server

Чтобы подать команду GDB, не оказывая влияния на определенные аспекты состояния, видимые для пользователей, начните ее с `server '. Это означает, что данная команда не воздействует на историю команд, а также не влияет на понятие GDB о том, какую команду повторять, если в пустой строке нажата клавиша RET.

Префикс server не влияет на запись значений в историю значений; чтобы напечатать значение, не занося его в историю, используйте команду output вместо print.

Значения

Когда значение выводится в различных контекстах, GDB использует примечания, чтобы отделить его от окружающего текста.

Если значение выводится с помощью print и добавляется в историю значений, примечание выглядит так:

^Z^Zvalue-history-begin <VAR>номер-в-истории</VAR> <VAR>флаги-значения</VAR>
<VAR>строка-истории</VAR>
^Z^Zvalue-history-value
<VAR>значение</VAR>
^Z^Zvalue-history-end

где номер-в-истории---номер, который значение получает в истории, строка-истории---строка, такая как `$5 = ', которая представляет значение пользователю, значение является выводом, соответствующим самому значению, а флаги-значения---`*' для значения, которое может быть разыменовано, и `-', если нет.

Если значение не добавляется в историю значений (это может быть или неверное число с плавающей точкой, или оно выводится командой output), примечание выглядит похожим образом:

^Z^Zvalue-begin <VAR>флаги-значения</VAR>
<VAR>значение</VAR>
^Z^Zvalue-end

Когда GDB выводит аргумент функции (например, в выводе команды backtrace), он делает такие примечания:

^Z^Zarg-begin
<VAR>имя-аргумента</VAR>
^Z^Zarg-name-end
<VAR>строка-разделитель</VAR>
^Z^Zarg-value <VAR>флаги-значения</VAR>
<VAR>значение</VAR>
^Z^Zarg-end

где имя-аргумента есть имя аргумента, строка-разделитель---текст (такой как `='), который отделяет имя от значения для удобства пользователя, а флаги-значения и значение имеют такой же смысл, что и в примечании value-history-begin.

При выводе структуры, GDB делает следующие примечания:

^Z^Zfield-begin <VAR>флаги-значения</VAR>
<VAR>имя-поля</VAR>
^Z^Zfield-name-end
<VAR>строка-разделитель</VAR>
^Z^Zfield-value
<VAR>значение</VAR>
^Z^Zfield-end

где имя-поля есть имя поля, строка-разделитель---текст (такой как `='), который отделяет имя от значения для удобства пользователя, а флаги-значения и значение имеют тот же смысл, что и в примечании value-history-begin.

При выводе массива, GDB делает следующие примечания:

^Z^Zarray-section-begin <VAR>индекс-в-массиве</VAR> <VAR>флаги-значения</VAR>

где индекс-в-массиве---индекс первого аннотируемого элемента, а флаги-значения имеют такой же смысл, что и в примечании value-history-begin. За этим следует произвольное число элементов. Элемент может быть либо одиночным

<SAMP>`,'</SAMP> <VAR>пропуск</VAR>           ; опускается для первого элемента
<VAR>значение</VAR>
^Z^Zelt

либо повторяющимся

<SAMP>`,'</SAMP> <VAR>пропуск</VAR>           ; опускается для первого элемента
<VAR>значение</VAR>
^Z^Zelt-rep <VAR>число-повторений</VAR>
<VAR>строка-повторений</VAR>
^Z^Zelt-rep-end

В обоих случаях, значение является выводом значения элемента, а пропуск может содержать пробелы, символы табуляции и новой строки. В случае повторяющихся элементов, число-повторений представляет число последовательных элементов массива, которые содержат данное значение, а строка-повторений является строкой, которая предназначена для уведомления пользователя о том, что выводятся повторяющиеся элементы.

После того, как выведены все элементы массива, примечание к массиву заканчивается так:

^Z^Zarray-section-end

Кадры

Когда GDB печатает кадр, он делает к нему примечания. Например, это применяется к кадрам, выводимым при остановке GDB, в результате вывода командами, такими как backtrace или up, и так далее.

Примечания к кадру начинаются с

^Z^Zframe-begin <VAR>уровень</VAR> <VAR>адрес</VAR>
<VAR>строка-уровня</VAR>

где уровень---это номер кадра (0 для самого внутреннего кадра, другие кадры имеют положительные номера), адрес---это адрес кода, выполняющегося в данном кадре, а строка-уровня---строка, предназначенная для передачи уровня пользователю. Адрес имеет форму `0x', за которым следует одна или более шестнадцатеричных цифр в нижнем регистре (заметьте, что это не зависит от языка). Кадр заканчивается так:

^Z^Zframe-end

Между этими комментариями находится основное тело кадра, которое может состоять из

• ^Z^Zfunction-call
  <VAR>строка-вызова-функции</VAR>

  где строка-вызова-функции является текстом, предназначенным для уведомления пользователя, что этот кадр связан с вызовом функции, который GDB сделал в отлаживаемой программе.

• ^Z^Zsignal-handler-caller
  <VAR>строка-вызова-обработчика-сигнала</VAR>

  где строка-вызова-обработчика-сигнала---текст, предназначенный для уведомления пользователя, что этот кадр связан с тем механизмом, который использовался операционной системой при вызове обработчика сигнала (это тот кадр, из которого произошел вызов обработчика, а не кадр для самого обработчика).
• Обычный кадр. Это может, возможно (в зависимости от того, считается ли это информацией, интересной для пользователя), начинаться с

  ^Z^Zframe-address
  <VAR>адрес</VAR>
  ^Z^Zframe-address-end
  <VAR>строка-разделитель</VAR>

  здесь адрес---это адрес, где происходит выполнение в кадре (тот же адрес, что и в примечании frame-begin, но выведенный в форме, предназначенной для пользователя---в частности, синтаксис различается в зависимости от языка), а строка-разделитель является строкой, предназначенной для отделения этого адреса от того, что за ним следует для удобства пользователя. Затем идет

  ^Z^Zframe-function-name
  <VAR>имя-функции</VAR>
  ^Z^Zframe-args
  <VAR>аргументы</VAR>

  где имя-функции есть имя функции, выполняющейся в кадре, или `??', если оно не известно, а аргументы---это аргументы к кадру, со скобками вокруг них (каждый аргумент аннотируется также индивидуально, see section Значения). Если доступна информация об исходных текстах, печатается ссылка на них:

  ^Z^Zframe-source-begin
  <VAR>вводная-исходная-строка</VAR>
  ^Z^Zframe-source-file
  <VAR>имя-файла</VAR>
  ^Z^Zframe-source-file-end
  :
  ^Z^Zframe-source-line
  <VAR>номер-строки</VAR>
  ^Z^Zframe-source-end

  где вводная-исходная-строка отделяет ссылку от предшествуещего ей текста, для удобства пользователя, имя-файла---это имя исходного файла, номер-строки---номер строки в этом файле (первая строка имеет номер 1). Если GDB печатает некоторую информацию о том, откуда появился этот кадр (какая библиотека, какой сегмент загрузки, и так далее; в настоящее время реализовано только на RS/6000), он делает такие примечания:

  ^Z^Zframe-where
  <VAR>информация</VAR>

  Затем, если исходный текст действительно должен быть отображен для этого кадра (например, это не верно для вывода от команды backtrace), тогда выводится примечание source (see section Вывод исходного текста). В отличие от большинства примечаний, этот вывод производится вместо обычного текста, который был бы напечатан, а не в дополнение к нему.

Отображения

Когда GDB велят отобразить что-то с помощью команды display, к результату отображения делаются примечания:

^Z^Zdisplay-begin
<VAR>номер</VAR>
^Z^Zdisplay-number-end
<VAR>разделитель-номеров</VAR>
^Z^Zdisplay-format
<VAR>формат</VAR>
^Z^Zdisplay-expression
<VAR>выражение</VAR>
^Z^Zdisplay-expression-end
<VAR>разделитель-выражений</VAR>
^Z^Zdisplay-value
<VAR>значение</VAR>
^Z^Zdisplay-end

здесь номер---это номер отображения, разделитель-номеров предназначен для отделения номеров от того, что следует затем для пользователя, формат включает информацию о том, как отображается значение, такую как размер, формат и так далее, выражение---это отображаемое выражение, разделитель-выражений предназначен для отделения выражения от следующего за ним текста для пользователя, и значение---это действительное значение, которое отображается.

Примечания ко вводу GDB

Когда GDB выводит приглашение для ввода, он делает к этому примечания, так что становится возможным узнать, когда посылать данные, когда закончен вывод от данной команды, и так далее.

Каждый из различных видов ввода имеет различный тип ввода. Каждый тип ввода имеет три примечания: примечание pre-, обозначающее начало каждого выводимого приглашения, простое примечание, обозначающее конец приглашения, и затем примечание post-, обозначающее конец любого эхо, которое может быть ассоциировано (а может и не быть) со вводом. Например, характерной чертой типа ввода prompt являются следующие примечания:

^Z^Zpre-prompt
^Z^Zprompt
^Z^Zpost-prompt

Существуют следующие типы ввода:

prompt

Когда GDB запрашивает команду (главное приглашение GDB).

commands

Когда GDB запрашивает набор команд, как в команде commands. Примечания повторяются для каждой введенной команды.

overload-choice

Когда GDB хочет, чтобы пользователь выбрал одну из нескольких перегруженных функций.

query

Когда GDB хочет, чтобы пользователь подтвердил потенциально опасное действие.

prompt-for-continue

Когда GDB запрашивает у пользователя нажатие ввода для продолжения. Замечание: не ожидайте, что это будет работать хорошо; используйте вместо этого set height 0 для отключения приглашений. Это происходит потому, что при наличии примечаний подсчет строк происходит неверно.

Ошибки

^Z^Zquit

Это примечание появляется непосредственно перед тем, как GDB отвечает на прерывание.

^Z^Zerror

Это примечание появляется сразу перед тем, как GDB отвечает на ошибку.

Примечания выхода и ошибки обозначают, что любое примечание, в середине которого находился GDB, могут внезапно оборваться. Например, если за примечанием value-history-begin следует error, то не нужно ожидать соответствующий value-history-end. Однако, не следует также ожидать, что его точно не будет; примечание об ошибке не обязательно означает, что GDB немедленно возвращается в начало на самый верхний уровень.

Примечанию к ошибке или выходу может предшествовать

^Z^Zerror-begin

Весь вывод между этим и примечанием к ошибке или выходу является сообщением об ошибке.

Пока примечаний к предупреждающим сообщениям не делается.

Информация о точке останова

К выводу, производимому командой info breakpoints, делаются следующие примечания:

^Z^Zbreakpoints-headers
<VAR>элемент-заголовка</VAR>
^Z^Zbreakpoints-table

где элемент-заголовка имеет тот же синтаксис, что и элемент (смотрите ниже), но вместо данных, он содержит строки, которые предназначены для разъяснения пользователю значений каждого поля. Затем следует произвольное число элементов. Если поле не подходит к этому элементу, оно опускается. Поля могут содержать завершающие пропуски. Каждое поле состоит из:

^Z^Zrecord
^Z^Zfield 0
<VAR>номер</VAR>
^Z^Zfield 1
<VAR>тип</VAR>
^Z^Zfield 2
<VAR>положение</VAR>
^Z^Zfield 3
<VAR>включена</VAR>
^Z^Zfield 4
<VAR>адрес</VAR>
^Z^Zfield 5
<VAR>что</VAR>
^Z^Zfield 6
<VAR>кадр</VAR>
^Z^Zfield 7
<VAR>условие</VAR>
^Z^Zfield 8
<VAR>счетчик-игнорирований</VAR>
^Z^Zfield 9
<VAR>команды</VAR>

Заметьте, что адрес предназначен для использования пользователем---синтаксис различается в зависимости от языка.

Вывод заканчивается так:

^Z^Zbreakpoints-table-end

Сообщения о недостоверности

Следующие примечания говорят о том, что определенные куски информации, описывающие состояние, могли измениться.

^Z^Zframes-invalid

Кадры (например, вывод команды backtrace) могли измениться.

^Z^Zbreakpoints-invalid

Точки останова могли измениться. Например, пользователь только что добавил или удалил точку останова.

Выполнение программы

Когда программа начинает выполняться вследствие команды GDB, такой как step или continue, выводится

^Z^Zstarting

Когда программа останавливается, выводится

^Z^Zstopped

Перед примечанием stopped, множество примечаний описывают, как программа остановилась.

^Z^Zexited код-выхода

Программа завершилась, и код-выхода является кодом выхода (ноль при успешном завершении, в противном случае не ноль).

^Z^Zsignalled

Программа завершилась по сигналу. После ^Z^Zsignalled, примечания продолжаются:

<VAR>вступительный-текст</VAR>
^Z^Zsignal-name
<VAR>имя</VAR>
^Z^Zsignal-name-end
<VAR>текст-в-середине</VAR>
^Z^Zsignal-string
<VAR>строка</VAR>
^Z^Zsignal-string-end
<VAR>заключительный-текст</VAR>

где имя является именем сигнала, таким как SIGILL или SIGSEGV, а строка представляет объяснение сигнала, такое как Illegal Instruction или Segmentation fault. Вступительный-текст, текст-в-середине и заключительный текст используются для удобства пользователя и не имеют определенного формата.

^Z^Zsignal

Синтаксис этого примечания такой же, как для signalled, но GDB сообщает, что программа лишь получила сигнал, а не то, что она остановилась из-за него.

^Z^Zbreakpoint номер

Программа достигла точки останова с номером номер.

^Z^Zwatchpoint номер

Программа достигла точки наблюдения с номером номер.

Вывод исходного текста

Следующие примечания используются вместо вывода исходного текста:

^Z^Zsource <VAR>имя-файла</VAR>:<VAR>строка</VAR>:<VAR>символ</VAR>:<VAR>middle</VAR>:<VAR>адрес</VAR>

где имя-файла указывает абсолютное имя файла, строка---это номер строки в этом файле (первая строка имеет номер 1), символ---позиция символа в файле (первый символ в исходном файле имеет номер 0) (для большинства отладочных форматов это будет обязательно указывать на начало строки), middle есть `middle', если адрес находится в середине строки, или `beg', если адрес находится в начале строки, а адрес является адресом в целевой программе, ассоциированным с выводимым исходным текстом. Адрес записан в форме `0x', за которым следует одна или несколько шестнадцатеричных цифр в нижнем регистре (заметьте, что это не зависит от языка).

Примечания, которые могут понадобиться с будущем

    - target-invalid
      цель могла измениться (регистры, содержимое памяти или статус
      выполнения).  Для эффективности выполнения, мы можем захотеть
      определять `register-invalid' и `all-register-invalid' с большей
      точностью
 
    - систематические примечания к параметрам set/show (включая
      сообщения о недостоверности).
 
    - аналогично, `info' возвращает список кандидатов на сообщение о
      недостоверности.