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 из исходного текста.

Info

Вт 23 Янв 2024 00:00:00 Библиотека Bee2