defs.h - Man Page
Базовые определения
Synopsis
#include <limits.h>
#include <stddef.h>
Макросы
#define LITTLE_ENDIAN 1234
Порядок 'от младших к старшим'.
#define BIG_ENDIAN 4321
Порядок 'от старших к младшим'.
#define OCTET_ORDER LITTLE_ENDIAN
Порядок октетов в машинном слове
#define B_PER_W 32
Число битов в машинном слове
#define O_PER_W (B_PER_W / 8)
Число октетов в машинном слове
#define O_PER_S (B_PER_S / 8)
Число октетов в size_t.
#define B_PER_S 32
Число битов в size_t.
#define O_OF_B(nb) (((nb) + 7) / 8)
Число октетов для размещения nb битов
#define W_OF_B(nb) (((nb) + B_PER_W - 1) / B_PER_W)
Число машинных слов для размещения nb битов
#define B_OF_O(no) ((no) * 8)
Число битов для размещения no октетов
#define W_OF_O(no) (((no) + O_PER_W - 1) / O_PER_W)
Число машинных слов для размещения no октетов
#define O_OF_W(nw) ((nw) * O_PER_W)
Число октетов для размещения nw машинных слов
#define B_OF_W(nw) ((nw) * B_PER_W)
Число битов для размещения nw машинных слов
#define ERR_OK ((err_t)0)
Код успешного завершения
#define ERR_MAX (ERR_OK - (err_t)1)
Максимальный код ошибки
#define B_PER_IMPOSSIBLE 64
Невозможное событие
Определения типов
typedef unsigned char u8
8-разрядное беззнаковое целое
typedef signed char i8
8-разрядное знаковое целое
typedef u8 octet
Октет
typedef unsigned short u16
16-разрядное беззнаковое целое
typedef signed short i16
16-разрядное знаковое целое
typedef unsigned int u32
32-разрядное беззнаковое целое
typedef signed int i32
32-разрядное знаковое целое
typedef u32 word
Машинное слово
typedef u64 dword
Двойное машинное слово
typedef int bool_t
Булев тип
typedef u32 err_t
Коды ошибок
typedef void(* gen_i) (void *buf, size_t count, void *state)
Интерфейс генерации
typedef err_t(* read_i) (size_t *read, void *buf, size_t count, void *file)
Интерфейс чтения
typedef err_t(* write_i) (size_t *written, const void *buf, size_t count, void *file)
Интерфейс записи
Подробное описание
Типы данных
Предусловие
Длина машинного слова в битах (B_PER_W) равняется 16, 32 или 64.
Длина слова типа size_t в битах не менее 16.
Обязательно поддерживаются типы u16, u32.
Могут поддерживаться типы u64, u128.
Прим.
Поддержка B_PER_W == 16 полезна для организации тестирования арифметики больших чисел и арифметики многочленов: как правило, ошибки в функциях арифметики возникают с вероятностями, близкими к 1 / 2^B_PER_W.
При разборе платформ для определения порядка октетов использован код Брайана Гладмана (Brian Gladman, http://www.gladman.me.uk/) и ресурс https://sourceforge.net/p/predef/wiki/Endianness/.
Платформа EMSCRIPTEN (https://emscripten.org) является виртуальной, на ней выполняется компиляция в asm.js.
Массивы
Массив элементов типа T, как правило, передается в функцию в виде пары (указатель in на элементы массива, длина массива in_len). Здесь in имеет тип const T*, а in_len -- тип size_t. При документировании массива используется запись [in_len]in. При T == void запись имеет такой же смысл, как при T == octet.
Если длина in_len заранее известна, то она может не передаваться в функцию.
Массив элементов типа T заранее известного размера возвращается из функций через буфер, на который ссылается указатель out типа T*.
Если длина массива заранее неизвестна, то для его возврата используется пара (указатель out, размер out_len), где out_len имеет тип size_t*. Если обратиться к функции с нулевым out, то по адресу out_len будет размещена длина возвращаемого массива. При обращении с ненулевым out по адресу out_len должно быть указано число элементов типа T, зарезервированных в буфере out. В результате выполнения функции число по адресу out_len корректируется -- устанавливается равным актуальному числу элементов, записанных в массив out. Размера буфера может контролироваться предусловиями. О недостаточности размера функция может сообщать через коды возврата.
При документировании описанной логики возврата массива используется запись [?out_len]out. При T == void запись имеет такой же смысл, как при T == octet.
Имеется схожий синтаксис [out_len?]out. Отличие в том, что при обращении к функции с ненулевым указателем out значение по адресу out_len не определено, более того, адрес out_len при дополнительных оговорках может быть нулевым.
Выражение out_len? может входить в арифметическое выражение, которое уточняет требуемый объем памяти. Например, запись [out_len? + 1]str означает, что для буфера (строки) str требуется один дополнительный к out_len октет (в него будет записан завершающий нулевой символ).
Последовательности вызовов
Ограничения на последовательность вызовов определенных функций документируются с помощью знаков '<', '*' и '<<'.
Запись 'f1() < f2()' означает, что функция f2() должна вызываться после f1().
Запись 'f1() < [f2()] < f3()' означает, что функция f2() должна вызываться после f1(), f3() после f2(), и вызов f2() может быть пропущен.
Запись 'f()*' означает, что функция f() может вызываться последовательно произвольное число раз.
Запись 'f1()* < f2()' означает, что несколько вызовов f1() завершаются вызовом f2().
Запись '(f1()* < f2())*' означает, что каскад 'несколько раз f1(), затем f2()' может повторяться произвольное число раз. Например, возможность инкрементального хэширования, при котором можно рассчитывать хэш-значение все более длинного фрагмента, обозначается следующим образом:
(hash_step()* < hash_get())*.
Знак '<<' используется при документировании протоколов. Запись 'f1() << f2()' означает, что перед вызовом функции f2() стороной A сторона B должна вызвать функцию f1() и переслать результаты ее работы стороне B.
Макросы
#define B_PER_IMPOSSIBLE 64
Событие, вероятность наступления которого <= 2^{-B_PER_IMPOSSIBLE}, считается невозможным.
Прим.
Э. Борель: 'событие, вероятность которого ниже 10^{-50} ≈ 2^{-166}, не произойдет никогда, сколько бы возможностей ни представилось' [Probability and Life, 1962].
Типы
typedef u32 err_t
Прим.
Высокоуровневые функции возвращают значения типа err_t. Возврат ERR_OK означает, что функция завершена успешно. Код ERR_MAX зарезервирован для описания специальных особых ситуаций. Возврат других значений означает ошибку при выполнении функции.
typedef void(* gen_i) (void *buf, size_t count, void *state)
Функция интерфейса gen_i генерирует count октетов и записывает их в буфер buf. При генерации может использоваться и изменяться вспомогательная память (состояние) state.
Функция интерфейса gen_i интерпретируется как генератор с состоянием state. Используются генераторы двух типов:
- rng (random number generator): генераторы случайных или псевдослучайных чисел;
- ang (arbitrary number generator): генераторы произвольных чисел, которые реализуют принцип 'выбрать произвольным образом'. Генерируемые числа (октеты) могут строиться по меткам времени, значениям монотонного счетчика, случайным или псевдослучайным числам. Числа могут использоваться в криптографических протоколах для построения синхропосылок, нонсов, затравочных значений (seed), 'соли' (salt).
Предусловие
Буфер buf корректен.
Состояние state корректно.
Ожидается
Состояние state поддерживается постоянным между последовательными обращениями к функции.
Ожидается
Октеты, формируемые генераторами rng, обладают минимальным статистическим качеством: каждое значение встречается с примерно равной частотой.
Ожидается
Октеты, формируемые генераторами ang, почти не повторяются (повторяются только с пренебрежимо малыми вероятностями или только на недостижимо больших интервалах наблюдения).
Прим.
Функция интерфейса gen_i всегда генерирует все запрашиваемые октеты. Ошибки при генерации не предусмотрены.
- Аргументы
buf случайные числа
count число октетов
state cостояние
typedef err_t(* read_i) (size_t *read, void *buf, size_t count, void *file)
Функция интерфейса read_i читает данные из файла file в буфер [count]buf. По адресу read возвращается число прочитанных октетов.
Предусловие
Буфер buf корректен.
Указатель read корректен.
Файл file корректен.
- Возвращает
ERR_OK, если прочитано определенное число октетов (возможно меньшее count и возможно нулевое) и конец файла не достигнут, ERR_MAX, если прочитано меньше чем count октетов и достигнут конец файла, или другой код ошибки.
Прим.
Файл -- это произвольный массив или поток данных на произвольном устройстве. В качестве файла может выступать обычный дисковый файл, сетевое соединение, источник случайности и т.д.
Для файлов некоторых устройств ошибкой не считается ситуация, когда прочитано меньше чем count октетов. Данная ситуация может быть связана с ожиданием данных в канале связи.
Передавая count == 0, можно проверить наличие файла.
- Аргументы
read число прочитанных октетов
buf прочитанные данные
count длина buf в октетах
file описание файла
typedef err_t(* write_i) (size_t *written, const void *buf, size_t count, void *file)
Функция интерфейса write_i записывает буфер [count]buf в файл file. По адресу written возвращается число записанных в файл октетов.
Предусловие
Указатель written корректен.
Буфер buf корректен.
Файл file корректен.
- Возвращает
ERR_OK, если записаны все октеты buf, и код ошибки в противном случае.
- Аргументы
written число записанных октетов
buf записываемые данные
count длина buf в октетах
file описание файла
Автор
Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.