1defs.h(3) Library Functions Manual defs.h(3)
2
6 defs.h - Базовые определения
7
10 #include <limits.h>
11 #include <stddef.h>
12 Макросы
15 #define LITTLE_ENDIAN 1234
16 Порядок 'от младших к старшим'.
17 #define BIG_ENDIAN 4321
18 Порядок 'от старших к младшим'.
19 #define OCTET_ORDER LITTLE_ENDIAN
20 Порядок октетов в машинном слове
21 #define B_PER_W 32
22 Число битов в машинном слове
23 #define O_PER_W (B_PER_W / 8)
24 Число октетов в машинном слове
25 #define O_PER_S (B_PER_S / 8)
26 Число октетов в size_t.
27 #define B_PER_S 32
28 Число битов в size_t.
29 #define O_OF_B(nb) (((nb) + 7) / 8)
30 Число октетов для размещения nb битов
31 #define W_OF_B(nb) (((nb) + B_PER_W - 1) / B_PER_W)
32 Число машинных слов для размещения nb битов
33 #define B_OF_O(no) ((no) * 8)
34 Число битов для размещения no октетов
35 #define W_OF_O(no) (((no) + O_PER_W - 1) / O_PER_W)
36 Число машинных слов для размещения no октетов
37 #define O_OF_W(nw) ((nw) * O_PER_W)
38 Число октетов для размещения nw машинных слов
39 #define B_OF_W(nw) ((nw) * B_PER_W)
40 Число битов для размещения nw машинных слов
41 #define ERR_OK ((err_t)0)
42 Код успешного завершения
43 #define ERR_MAX (ERR_OK - (err_t)1)
44 Максимальный код ошибки
45 #define B_PER_IMPOSSIBLE 64
46 Невозможное событие
47 Определения типов
49 typedef unsigned char u8
50 8-разрядное беззнаковое целое
51 typedef signed char i8
52 8-разрядное знаковое целое
53 typedef u8 octet
54 Октет
55 typedef unsigned short u16
56 16-разрядное беззнаковое целое
57 typedef signed short i16
58 16-разрядное знаковое целое
59 typedef unsigned int u32
60 32-разрядное беззнаковое целое
61 typedef signed int i32
62 32-разрядное знаковое целое
63 typedef u32 word
64 Машинное слово
65 typedef u64 dword
66 Двойное машинное слово
67 typedef int bool_t
68 Булев тип
69 typedef u32 err_t
70 Коды ошибок
71 typedef void(* gen_i) (void *buf, size_t count, void *state)
72 Интерфейс генерации
73 typedef err_t(* read_i) (size_t *read, void *buf, size_t count, void
74 *file)
75 Интерфейс чтения
76 typedef err_t(* write_i) (size_t *written, const void *buf, size_t
77 count, void *file)
78 Интерфейс записи
79
82 Предусловие
83 Длина машинного слова в битах (B_PER_W) равняется 16, 32 или 64.
84 Длина слова типа size_t в битах не менее 16.
86 Обязательно поддерживаются типы u16, u32.
88 Могут поддерживаться типы u64, u128.
90 Прим.
92 Поддержка B_PER_W == 16 полезна для организации тестирования
93 арифметики больших чисел и арифметики многочленов: как правило,
94 ошибки в функциях арифметики возникают с вероятностями, близкими к
95 1 / 2^B_PER_W.
96 При разборе платформ для определения порядка октетов использован
98 код Брайана Гладмана (Brian Gladman, http://www.gladman.me.uk/) и
99 ресурс https://sourceforge.net/p/predef/wiki/Endianness/.
100 Платформа EMSCRIPTEN (https://emscripten.org) является виртуальной,
102 на ней выполняется компиляция в asm.js.
103
105 Массив элементов типа T, как правило, передается в функцию в виде пары
106 (указатель in на элементы массива, длина массива in_len). Здесь in
107 имеет тип const T*, а in_len -- тип size_t. При документировании
108 массива используется запись [in_len]in. При T == void запись имеет
109 такой же смысл, как при T == octet.
110 Если длина in_len заранее известна, то она может не передаваться в
112 функцию.
113 Массив элементов типа T заранее известного размера возвращается из
115 функций через буфер, на который ссылается указатель out типа T*.
116 Если длина массива заранее неизвестна, то для его возврата используется
118 пара (указатель out, размер out_len), где out_len имеет тип size_t*.
119 Если обратиться к функции с нулевым out, то по адресу out_len будет
120 размещена длина возвращаемого массива. При обращении с ненулевым out по
121 адресу out_len должно быть указано число элементов типа T,
122 зарезервированных в буфере out. В результате выполнения функции число
123 по адресу out_len корректируется -- устанавливается равным актуальному
124 числу элементов, записанных в массив out. Размера буфера может
125 контролироваться предусловиями. О недостаточности размера функция может
126 сообщать через коды возврата.
127 При документировании описанной логики возврата массива используется
129 запись [?out_len]out. При T == void запись имеет такой же смысл, как
130 при T == octet.
131 Имеется схожий синтаксис [out_len?]out. Отличие в том, что при
133 обращении к функции с ненулевым указателем out значение по адресу
134 out_len не определено, более того, адрес out_len при дополнительных
135 оговорках может быть нулевым.
136 Выражение out_len? может входить в арифметическое выражение, которое
138 уточняет требуемый объем памяти. Например, запись [out_len? + 1]str
139 означает, что для буфера (строки) str требуется один дополнительный к
140 out_len октет (в него будет записан завершающий нулевой символ).
141
143 Ограничения на последовательность вызовов определенных функций
144 документируются с помощью знаков '<', '*' и '<<'.
145 Запись 'f1() < f2()' означает, что функция f2() должна вызываться после
147 f1().
148 Запись 'f1() < [f2()] < f3()' означает, что функция f2() должна
150 вызываться после f1(), f3() после f2(), и вызов f2() может быть
151 пропущен.
152 Запись 'f()*' означает, что функция f() может вызываться
154 последовательно произвольное число раз.
155 Запись 'f1()* < f2()' означает, что несколько вызовов f1() завершаются
157 вызовом f2().
158 Запись '(f1()* < f2())*' означает, что каскад 'несколько раз f1(),
160 затем f2()' может повторяться произвольное число раз. Например,
161 возможность инкрементального хэширования, при котором можно
162 рассчитывать хэш-значение все более длинного фрагмента, обозначается
163 следующим образом:
164 (hash_step()* < hash_get())*.
166 Знак '<<' используется при документировании протоколов. Запись 'f1() <<
169 f2()' означает, что перед вызовом функции f2() стороной A сторона B
170 должна вызвать функцию f1() и переслать результаты ее работы стороне B.
171
173 #define B_PER_IMPOSSIBLE 64
174 Событие, вероятность наступления которого <= 2^{-B_PER_IMPOSSIBLE},
175 считается невозможным.
176 Прим.
178 Э. Борель: 'событие, вероятность которого ниже 10^{-50} ≈ 2^{-166},
179 не произойдет никогда, сколько бы возможностей ни представилось'
180 [Probability and Life, 1962].
181 #define B_PER_S 32
183 #define B_PER_W 32
184 #define BIG_ENDIAN 4321
185 #define LITTLE_ENDIAN 1234
186 #define O_PER_S (B_PER_S / 8)
187 #define O_PER_W (B_PER_W / 8)
188 #define OCTET_ORDER LITTLE_ENDIAN
190 dword
191 typedef u32 err_t
192 Прим.
193 Высокоуровневые функции возвращают значения типа err_t. Возврат
194 ERR_OK означает, что функция завершена успешно. Код ERR_MAX
195 зарезервирован для описания специальных особых ситуаций. Возврат
196 других значений означает ошибку при выполнении функции.
197 typedef void(* gen_i) (void *buf, size_t count, void *state)
199 Функция интерфейса gen_i генерирует count октетов и записывает их в
200 буфер buf. При генерации может использоваться и изменяться
201 вспомогательная память (состояние) state.
202 Функция интерфейса gen_i интерпретируется как генератор с состоянием
204 state. Используются генераторы двух типов:
205 • rng (random number generator): генераторы случайных или
207 псевдослучайных чисел;
208 • ang (arbitrary number generator): генераторы произвольных чисел,
210 которые реализуют принцип 'выбрать произвольным образом'.
211 Генерируемые числа (октеты) могут строиться по меткам времени,
212 значениям монотонного счетчика, случайным или псевдослучайным числам.
213 Числа могут использоваться в криптографических протоколах для
214 построения синхропосылок, нонсов, затравочных значений (seed), 'соли'
215 (salt).
216 Предусловие
218 Буфер buf корректен.
219 Состояние state корректно.
221 Ожидается
223 Состояние state поддерживается постоянным между последовательными
224 обращениями к функции.
225 Ожидается
227 Октеты, формируемые генераторами rng, обладают минимальным
228 статистическим качеством: каждое значение встречается с примерно
229 равной частотой.
230 Ожидается
232 Октеты, формируемые генераторами ang, почти не повторяются
233 (повторяются только с пренебрежимо малыми вероятностями или только
234 на недостижимо больших интервалах наблюдения).
235 Прим.
237 Функция интерфейса gen_i всегда генерирует все запрашиваемые
238 октеты. Ошибки при генерации не предусмотрены.
239 Аргументы
241 buf случайные числа
242 count число октетов
243 state cостояние
244 i16
246 i32
247 i8
248 octet
249 typedef err_t(* read_i) (size_t *read, void *buf, size_t count, void *file)
250 Функция интерфейса read_i читает данные из файла file в буфер
251 [count]buf. По адресу read возвращается число прочитанных октетов.
252 Предусловие
254 Буфер buf корректен.
255 Указатель read корректен.
257 Файл file корректен.
259 Возвращает
261 ERR_OK, если прочитано определенное число октетов (возможно меньшее
262 count и возможно нулевое) и конец файла не достигнут, ERR_MAX, если
263 прочитано меньше чем count октетов и достигнут конец файла, или
264 другой код ошибки.
265 Прим.
267 Файл -- это произвольный массив или поток данных на произвольном
268 устройстве. В качестве файла может выступать обычный дисковый файл,
269 сетевое соединение, источник случайности и т.д.
270 Для файлов некоторых устройств ошибкой не считается ситуация, когда
272 прочитано меньше чем count октетов. Данная ситуация может быть
273 связана с ожиданием данных в канале связи.
274 Передавая count == 0, можно проверить наличие файла.
276 Аргументы
278 read число прочитанных октетов
279 buf прочитанные данные
280 count длина buf в октетах
281 file описание файла
282 u16
284 u32
285 u8
286 word
287 typedef err_t(* write_i) (size_t *written, const void *buf, size_t count,
288 void *file)
289 Функция интерфейса write_i записывает буфер [count]buf в файл file. По
290 адресу written возвращается число записанных в файл октетов.
291 Предусловие
293 Указатель written корректен.
294 Буфер buf корректен.
296 Файл file корректен.
298 Возвращает
300 ERR_OK, если записаны все октеты buf, и код ошибки в противном
301 случае.
302 Аргументы
304 written число записанных октетов
305 buf записываемые данные
306 count длина buf в октетах
307 file описание файла
308
310 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
311Библиотека Bee2 Пт 23 Июн 2023 defs.h(3)