18. Примечания GDB

на относительно высоком уровне.

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

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

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

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

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

 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.

18.2 Префикс server

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

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

18.3 Значения

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

^Z^Zarray-section-end

18.4 Кадры

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

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

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

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

^Z^Zframe-end

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

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

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

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

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

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

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

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

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

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

  где вводная-исходная-строка отделяет ссылку от предшествующего ей текста, для удобства пользователя, имя-файла -- это имя исходного файла, номер-строки -- номер строки в этом файле (первая строка имеет номер 1).

  ^Z^Zframe-where
  информация
  

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

18.5 Отображения

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

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

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

18.6 Примечания ко вводу 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 для отключения приглашений. Это происходит потому, что при наличии примечаний подсчет строк происходит неверно.

18.7 Ошибки

^Z^Zquit

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

^Z^Zerror

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

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

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

^Z^Zerror-begin

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

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

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

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

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

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

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

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

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

^Z^Zbreakpoints-table-end

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

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

^Z^Zframes-invalid

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

^Z^Zbreakpoints-invalid

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

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

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

^Z^Zstarting

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

^Z^Zstopped

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

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

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

^Z^Zsignalled

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

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

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

^Z^Zsignal

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

^Z^Zbreakpoint номер

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

^Z^Zwatchpoint номер

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

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

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

^Z^Zsource имя-файла:строка:знак:середина:адрес

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

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

 с большей
      точностью

    - систематические примечания к параметрам set/show (включая
      сообщения о недостоверности).

    - аналогично, `info' возвращает список кандидатов на сообщение о
      недостоверности.