Техническая статья

Структура PDF-файла: заголовок, объекты, xref, трейлер

PDF, оборванный на середине загрузки, может отказаться открываться, хотя дошли почти все страницы, — а руководство на 2000 страниц мгновенно прыгает на страницу 1500. И то и другое следует из структуры PDF-файла, как её пишет HotPDF Delphi Component: заголовок, тело из пронумерованных объектов, таблица перекрёстных ссылок (xref) из байтовых смещений и трейлер, причём последние два лежат в конце файла

ISO 32000-2 §7.5.1 описывает ту же четырёхчастную анатомию для любого PDF — от одностраничной квитанции до сканированного архива. Части всегда лежат по файлу в одном порядке и связаны фиксированной цепочкой: трейлер называет каталог и сообщает, где начинается таблица xref, таблица xref сообщает, где начинается каждый объект, а объекты указывают друг на друга по номеру. Выдержки ниже взяты из Hello World-файла в 610 байтов, чьи смещения проверены побайтово; полный файл с разметкой каждого ключевого слова — в статье о том, как PDF выглядит изнутри, а что просмотрщик делает с этими частями на пути к пикселям — в статье о том, как PDF работает, когда его открывает читатель

Диаграмма формата PDF: дисковая структура PDF-файла — заголовок, тело объектов, таблица перекрёстных ссылок и трейлер
заголовок, тело объектов, таблица перекрёстных ссылок и трейлер лежат на диске в одном фиксированном порядке, и трейлер в конце связывает остальные три части

Заголовок PDF состоит из двух строк, и вторая имеет значение

Первая строка, например %PDF-1.7, с точки зрения синтаксиса — комментарий, но читатели обращаются с ней как с сигнатурой файла и берут из неё версию; на практике версия обрабатывается вольно, так что считайте число подсказкой о том, каких возможностей ждать. Вторая строка — та, которую случайно удаляют, а потом полдня тратят на отладку. Её полезная нагрузка — не меньше четырёх байтов выше ASCII 127 (ISO 32000-1 §7.5.2): они существуют, чтобы всё, что переносит файл в текстовом режиме, распознавало его как двоичный и переставало переписывать концы строк. В сжатых потоках есть байты, совпадающие с возвратом каретки или переводом строки чисто случайно; перепишите их — и длина потока, записанная в словаре, перестанет совпадать с байтами на диске. Каждый серьёзный писатель по-прежнему записывает этот комментарий, потому что предотвращаемый им сбой тих и тотален

Тело: пронумерованные объекты и восемь типов объектов PDF

Тело — плоская последовательность косвенных объектов, каждый обёрнут как N G obj ... endobj с номером объекта и номером поколения. Плоский список превращает во внутреннюю структуру PDF ссылочный токен N G R: 2 0 R означает «объект 2, поколение 0, где бы он ни лежал в файле». Любое значение можно записать и на месте как прямой объект. В выдержке словарь /Resources страницы — прямой, а шрифт, который он называет, — косвенный, поэтому сто страниц могут делить объект 4 вместо того, чтобы нести сто копий:

1 0 obj
<< /Type /Catalog /Pages 2 0 R >>          % каталог указывает на дерево страниц
endobj
...
3 0 obj
<< /Type /Page
   /Parent 2 0 R
   /MediaBox [0 0 612 792]
   /Resources << /Font << /F1 4 0 R >> >>   % прямой словарь, косвенный шрифт
   /Contents 5 0 R
>>
endobj
Анатомия косвенной ссылки PDF: объект шрифта 12 определён один раз и достигается из словаря ресурсов страницы через нотацию 12 0 R
объект получает идентичность через номера объекта и поколения, а потребители достигают его там, где нужно, записывая соответствующую ссылку R вместо копии

ISO 32000-1 §7.3 держит словарь коротким: каждое значение в PDF — один из восьми базовых типов. Булевы значения и числа — скаляры, и в PDF нет экспоненциальной записи, поэтому 1e6 в корректном файле не встречается. Строки хранят байты и пишутся как (Hello, World!) или в hex как <48656C6C6F>. Имена вроде /Type или /Helvetica сравниваются побайтово, поэтому (Helvetica) там, где /BaseFont ждёт имя, — ошибка типа, хотя символы совпадают. Массивы держат что угодно по порядку, как MediaBox. Словари отображают имена в значения и несут большую часть структуры. Поток — это словарь плюс сырые байты, дом для содержимого страниц, шрифтов и изображений. Восьмой тип — null: ссылка на несуществующий объект разрешается в него вместо ошибки, что позволяет повреждённому файлу деградировать, а не отказывать целиком

Сетка карточек восьми типов объектов PDF с примерами синтаксиса boolean, number, string, name, array, dictionary, stream и null
восемь примитивных типов образуют весь словарь значений PDF; словарь несёт основную структурную нагрузку, а потоки — объёмистый сжатый груз

Номер поколения существует для повторного использования. Когда правка удаляет объект, его номер попадает в список свободных, и если поздняя правка задействует номер заново, поколение вырастает на единицу, поэтому устаревшая 12 0 R не может молча разрешиться в новый 12 1 obj. Почти каждый встреченный вами объект — поколение 0. Разрешение начинается с каталога — объекта 1 в выдержке, чья запись /Pages ведёт в дерево страниц; внутренние узлы собирают страницы в /Kids, хранят /Count и могут передавать атрибуты вроде /MediaBox вниз потомкам. Почему порядок страниц решает именно это дерево, а не физический порядок объектов, разобрано в статье о деревьях страниц PDF и порядке страниц

Как таблица xref находит объект?

Таблица xref превращает номер объекта в байтовое смещение арифметикой — именно поэтому руководство на 2000 страниц открывается сразу на странице 1500, не разбирая страницы перед ним. ISO 32000-1 §7.5.4 фиксирует каждую запись ровно в двадцать байтов: десятизначное смещение от начала файла, пробел, пятизначное поколение, пробел, буква типа и двухбайтовый конец строки, который при LF — это пробел плюс перевод строки. Строки одинаковые, поэтому читатель арифметикой выходит прямо на запись объекта n. Строка 0 6 — заголовок подраздела, а запись 0 всегда свободна с поколением 65535 и возглавляет связанный список свободных номеров объектов. Каждое прочее смещение обязано попадать на первую цифру заголовка N G obj, как в файле на 610 байтов:

xref
0 6                  % 6 записей, начиная с объекта 0
0000000000 65535 f   % запись 0: начало списка свободных
0000000019 00000 n   % объект 1 (каталог) начинается с байта 19
0000000068 00000 n   % объект 2 (дерево страниц) начинается с байта 68
0000000125 00000 n   % объект 3 (страница) начинается с байта 125
0000000263 00000 n   % объект 4 (шрифт) начинается с байта 263
0000000333 00000 n   % объект 5 (поток содержимого) начинается с байта 333
Анатомия двадцатибайтовой записи xref PDF: десятизначное байтовое смещение позволяет читателю выйти на любой объект без сканирования
однообразные двадцатибайтовые строки превращают номер объекта в байтовое смещение арифметикой, а объект 0 возглавляет список свободных

Почему усечённый PDF отказывается открываться?

Усечённый PDF отказывает потому, что две части, связывающие всё воедино, — таблица xref и трейлер — записаны последними байтами. Словарь трейлера несёт /Root — каталог — и /Size — число записей xref, на единицу больше наибольшего номера объекта, потому что нулевой слот держит свободную запись. Под ним startxref даёт байтовое смещение ключевого слова xref, а %%EOF закрывает файл:

trailer
<< /Size 6 /Root 1 0 R >>   % число записей, каталог документа
startxref
427                          % байтовое смещение ключевого слова xref
%%EOF

Потеряйте последние несколько сотен байтов — и у файла есть объекты, но нет карты к ним. Строгие читатели на этом останавливаются; снисходительные сканируют весь файл в поисках заголовков N G obj и перестраивают таблицу — тот медленный путь, ради избегания которого xref и существует, — а перестроенная карта всё ещё может пропустить объекты или взять не ту копию правленного. Передача в текстовом режиме портит тише, потому что переписывание концов строк сдвигает каждый объект. Мы сконвертировали файл на 610 байтов в концы строк CRLF и запустили qpdf --check (qpdf 12.3.2): он сообщил «file is damaged» и «xref not found» на смещении 427 и перестроил таблицу сканированием, прежде чем что-либо проверять

Классическая таблица xref или поток перекрёстных ссылок?

Начиная с PDF 1.5, xref может быть и потоком перекрёстных ссылок (ISO 32000-1 §7.5.8): это косвенный объект с /Type /XRef, чьи двоичные строки заменяют текстовую таблицу, а словарь потока вбирает записи трейлера, поэтому ключевое слово trailer исчезает и startxref указывает на этот объект. Типы строк становятся числами (0 — свободно, 1 — на байтовом смещении, 2 — внутри объектного потока), /W даёт ширину каждого столбца в байтах, а HotPDF сжимает строки Flate и предиктором PNG Up. HotPDF пишет потоковую форму, когда Version равен pdf15 или выше, поэтому пример выставляет его явно, а UseObjectStreams строится на том же переключателе. Мы оставляем UseXRefStream выключенным для файлов, которым открываться в инструментах эпохи PDF 1.4 — они вообще не умеют разбирать поток xref, — и включаем его для больших документов, где компактный индекс окупается. Меняется только хвост файла:

uses
  System.SysUtils, HPDFDoc;

procedure SaveWithXRef(const FileName: string; AsStream: Boolean);
var
  PDF: THotPDF;
begin
  PDF := THotPDF.Create(nil);
  try
    PDF.AutoLaunch := False;
    PDF.FileName := FileName;
    PDF.Version := pdf17;            // потокам xref нужен PDF 1.5 или выше
    PDF.UseXRefStream := AsStream;   // по умолчанию False: текстовая таблица плюс трейлер
    PDF.BeginDoc;
    PDF.CurrentPage.TextOut(72, 72, 0, 'Same page, different index');
    PDF.EndDoc;
  finally
    PDF.Free;
  end;
end;

// SaveWithXRef('table.pdf', False);
//   Ожидаемый хвост: xref, 0 N, строки по двадцать байтов,
//   trailer << /Size /Root /Info /ID >>, startxref, %%EOF
// SaveWithXRef('stream.pdf', True);
//   Ожидаемый хвост: N 0 obj << /Type /XRef /Size /Root /Info /ID /W ...
//   /Filter /FlateDecode >> stream ... endstream endobj, startxref, %%EOF

Инкрементные обновления дописывают второй xref вместо перезаписи

PDF можно править, не трогая ни одного байта, уже лежащего на диске. Изменённые и новые объекты дописываются, за ними следует раздел xref, перечисляющий только их, и трейлер, чья запись /Prev хранит смещение предыдущей таблицы. Читатель идёт по startxref к новейшему разделу, проходит цепочку /Prev назад и даёт побеждать новейшей записи для каждого номера объекта. Правка ниже добавляет заметку-аннотацию к файлу на 610 байтов: объект страницы 3 переписан с массивом /Annots под тем же номером, а объект 6 — новый. Без комментариев и с концами строк LF смещения точны, и qpdf --check проходит по результату без ошибок:

% ... исходные 610 байтов, нетронуты ...
3 0 obj                          % заменяет страницу 3, тот же номер объекта
<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R /Annots [6 0 R] >>
endobj
6 0 obj                          % новая аннотация
<< /Type /Annot /Subtype /Text /Rect [72 650 92 670] /Contents (Checked) >>
endobj
xref                             % два подраздела по одной записи
3 1
0000000610 00000 n
6 1
0000000752 00000 n
trailer
<< /Size 7 /Root 1 0 R /Prev 427 >>
startxref
843
%%EOF
PDF: инкрементное обновление дописывает второй раздел xref и трейлер, сцепленные через /Prev, пока исходные байты и подписанные диапазоны нетронуты
правка дописывает новые объекты плюс свежие xref и трейлер, сцепленные через /Prev; исходный диапазон байтов никогда не сдвигается — именно это держит подписи валидными

Дописывание — то, что держит подписанные PDF проверяемыми: подпись покрывает диапазон байтов, а инкрементное обновление никогда эти байты не сдвигает. Это же причина, по которой PDF несёт восстанавливаемую историю: старая страница 3 по-прежнему сидит на байте 125, недостижимая, но присутствующая. Файлы, правленные много раз, отращивают длинную цепочку /Prev; qpdf revised.pdf flat.pdf ресериализует достижимые объекты под единственным xref и выбрасывает старые ревизии — на файле выше это оставило одну таблицу xref и ни одного /Prev ценой любых подписей над исходными байтами. В HotPDF инкрементная ревизия выглядит так:

procedure ReviseInPlace(const Original, Revised: string);
var
  PDF: THotPDF;
begin
  PDF := THotPDF.Create(nil);
  try
    PDF.AutoLaunch := False;
    PDF.BeginIncrementalUpdate(Original);   // хранит исходные байты дословно
    PDF.SetLoadedTitle('Quarterly report, revised');
    PDF.SetLoadedAuthor('Finance');
    PDF.SaveIncrementalUpdate(Revised);      // изменённые объекты, новый xref, трейлер с /Prev
  finally
    PDF.Free;
  end;
end;

Четырёхчастная компоновка заодно даёт быстрый порядок первичной диагностики для плохо ведущего себя PDF: проверьте, что файл кончается %%EOF с правдоподобным startxref, удостоверьтесь, что одно-два смещения xref попадают на заголовок N G obj, затем идите по /Root в каталог и дерево страниц. HotPDF Delphi Component для Delphi и C++Builder по запросу пишет классические таблицы xref или потоки перекрёстных ссылок и дописывает инкрементные ревизии, оставляя более ранние байты и подписи над ними нетронутыми