update docs

docs/manual.md

@@ -723,6 +723,24 @@ ipcache представляет собой структуру в памяти
 * **SIGUSR1** выводит содержимое пула conntrack
 * **SIGUSR2** выводит счетчики autohostlist и содержимое пула ipcache
 
+## Отладка
+
+Параметр `--debug` включает вывод отладочных сообщений.
+
+* `--debug=0` выключает вывод
+* `--debug`, `--debug=1` вывод на консоль
+* `--debug=@<filename>` вывод в файл. размер файла ничем не ограничивается, но файл может быть удален в любой момент, и запись продолжится с чистого листа
+* `--debug=syslog` вывод в syslog. чтение зависит от syslog daemon. rsyslog пишет файлы в /var/log. busybox logd читается через logread.
+* `--debug=android` вывод в android log. чтение через logcat. доступно только в версиях, собранных в Android NDK
+
+Умение обращаться с `--debug` логом совершенно необходимо для отладки настроек и тем более для написания собственного LUA кода.
+
+Все сообщения об ошибках (DLOG_ERR) и особо важные сообщения (DLOG_CONDUP) дублируются на консоли вне зависимости от log target.
+Сообщения об ошибках выводятся в stderr.
+
+Параметр `--dry-run` позволяет протестировать корректность опций командной строки и доступность используемых файлов под сброшенными привилегиями.
+`--dry-run` не инициализирует движок LUA, и поэтому не может обнаружить синтаксические ошибки LUA.
+
 ## Песочница
 
 В целях безопасности nfqws2 после инициализации сбрасывает свои привилегии.
@@ -734,7 +752,7 @@ BSD :
 Linux :
 * Меняется UID/GID на указанные в параметрах `--user`, `--uid`. По умолчанию на 0x7FFFFFFF.
 * Сбрасываются capabilities до cap_net_raw, cap_net_admin (требуется для NFQUEUE). Сбрасывается bounding set до нуля.
-* Выставляется признак NO_NEW_PRIVS, чтобы не работали suid биты и caps на файлах. Если ядро старее 3.5, NO_NEW_PRIVS не поддерживается. В этом случае выводится предупреждение, но выполнение не прекращается.
+* Выставляется признак NO_NEW_PRIVS, чтобы не работали suid биты и caps на файлах. Если ядро старее 3.5, NO_NEW_PRIVS не поддерживается. В этом случае выводится предупреждение, выполнение не прекращается.
 * Включается seccomp фильтр, запрещающий exec и ряд файловых операций - чтение содержимого каталогов, создание/удаление каталогов, создание специальных файлов (линки, девайсы), chmod, chown, посылание сигналов (kill), ptrace.
 В случае нарушения процесс аварийно завершается. Если ядро не поддерживает seccomp, выводится предупреждение, но выполнение не прекращается.
 
@@ -1304,3 +1322,138 @@ mss дублируется в поле `desync.tcp_mss` независимо о
 | IPTOS_DSCP_MASK | number | битовая маска поля ip_tos, соответствующая DSCP | 0xFC |
 | IP6F_MORE_FRAG | number | бит "More fragment" поля ip6f_offlg из ipv6 fragment header | 0x0001 |
 | IPPROTO_IP<br>IPPROTO_IPV6<br>IPPROTO_ICMP<br>IPPROTO_TCP<br>IPPROTO_UDP<br>IPPROTO_ICMPV6<br>IPPROTO_HOPOPTS<br>IPPROTO_ROUTING<br>IPPROTO_FRAGMENT<br>IPPROTO_AH<br>IPPROTO_ESP<br>IPPROTO_DSTOPTS<br>IPPROTO_MH<br>IPPROTO_HIP<br>IPPROTO_SHIM6<br>IPPROTO_NONE | number | [номера IP протоколов](https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml) | используются в ipv4 и ipv6 |
+
+## C функции
+
+### Логгинг
+
+```
+function DLOG(string)
+function DLOG_ERR(string)
+function DLOG_CONDUP(string)
+```
+
+Функции выводят строку с добавлением EOL в --debug лог.
+* DLOG - обычный вывод
+* DLOG_CONDUP - обычный вывод + вывод на консоль, если включено логирование в файл или syslog
+* DLOG_ERR - вывод в stderr + на консоль
+
+### Конвертация IP
+
+```
+function ntop(raw_ip)
+function pton(string_ip)
+```
+
+* ntop конвертирует строку с байтами ipv4 или ipv6 адреса в строковое представление. версия IP определяется по размеру raw_ip - 4 или 16 байт. При несоответствии размера возвращается nil.
+* pton конвертирует строковое представление ipv4 или ipv6 адреса в raw_ip. Если строковое представление не является корректным ipv4 или ipv6 адресом, возвращается nil.
+
+### Битовые операции
+
+LUA 5.1, на котором основан luajit, не имеет встроенных битовых операций. Luajit имеет встроенный модуль bitop.
+LUA 5.3 имеет встроенные битовые операции, но не имеет встроенного модуля bitop. Он может быть подгружен,
+но только если не использована статическая компиляция и если модуль установлен. nfqws2 на github собирается статически.
+
+При работе с полями сетевых пакетов без битовых операций никуда.
+Битовые операции и сдвиги обычно реализуются одной машинной командой. Для процессора это родные операции.
+Заменять их конструкциями, основанных на математике с плавающей точкой неразумно (возведение в степень, деление, округление и тд),
+особенно в условиях частого отсутствия FPU на роутерах и других embedded устройствах.
+
+Чтобы не зависеть от всей этой неразберихи, в nfqws2 выставляется свой собственный набор битовых функций и функций сдвига,
+который не зависит от типа движка LUA и его версии. Все типы битовых операций работают с беззнаковыми числами от 8 до 32 бит.
+При передаче отрицательных чисел они интерпретируются в дополнительном коде. Например, в 32 битах -2 становится 0xFFFFFFFE, в 8 битах - 0xFE.
+Большая разрядность не поддерживается, поскольку возникают несовместимости между LUA 5.3+ и более старыми версиями.
+Только в LUA 5.3 реализова тип integer 64 bit. В более старых исползьзуется формат плавающей точки - double с мантиссой 53 бит.
+
+Стандартные операции сдвига и побитовые логические операции :
+```
+function bitlshift(u32, bits)
+function bitrshift(u32, bits)
+function bitand(u32_1, u32_2, ...., u32_N)
+function bitor(u32_1, u32_2, ...., u32_N)
+function bitxor(u32_1, u32_2, ...., u32_N)
+function bitnot(u32)
+```
+
+bitand, bitor и bitxor работает с произвольным количеством чисел.
+
+Операции получения и установки отдельных битов :
+```
+function bitget(u32, bit_from, bit_to)
+function bitset(u32, bit_from, bit_to, set)
+```
+
+* bitget получает число из диапазона битов u32 с номерами от bit_from до bit_to. нумерация битов с 0.
+* bitset записывает число set в диапазон битов u32 с номерами от bit_from до bit_to. нумерация битов с 0. старшие биты set, выходящие за пределы (bit_to-bit_from), игнорируются.
+
+### Операции с беззнаковыми числами
+
+При операциях с числями без знака всегда важна разрядность. От нее зависит результат.
+Поэтому все функции имеют в своем названии разрядность. При передаче аргументов, выходящих за пределы разрядности, вызывается error.
+
+```
+function u8(raw_string, offset)
+function u16(raw_string, offset)
+function u24(raw_string, offset)
+function u32(raw_string, offset)
+```
+
+Эти функции используются для извлечения числовых полей в формате big endian из raw строки.
+offset - номер байта от начала raw строки, начиная с 1.
+Аналогичные встроенные средства (string.unpack) есть только в LUA 5.3.
+
+```
+function bu8(u8)
+function bu16(u16)
+function bu24(u24)
+function bu32(u32)
+```
+
+Преобразуют число в raw строку в формате big endian.
+Чтобы собрать структуру из числовых полей, можно использовать обычную операцию конкатенации строк `..`.
+
+```
+function swap16(u16)
+function swap32(u32)
+```
+
+Инвертируют порядок следования байт в u16 или u32. Если в вашей структуре порядок байт little endian,
+можно использовать uX/buX + swap.
+
+```
+function u8add(u8_1, u8_2, ...., u8_N)
+function u16add(u16_1, u16_2, ...., u16_N)
+function u24add(u24_1, u24_2, ...., u24_N)
+function u32add(u32_1, u32_2, ...., u32_N)
+```
+
+Функции для сложения произвольного количества беззнаковых чисел указанной разрядности.
+Операнды должны вписываться в указанную разрядность, иначе вызывается error.
+Перенос старшего разряда игнорируется.
+
+### Целочисленное деление
+
+Встроенное целочисленное деление есть только в LUA 5.3+, где есть тип данных integer.
+Чтобы не возиться с округлением, целочисленное деление реализовано C функцией :
+
+```
+function divint(dividend, divisor)
+```
+
+В этой функции нет ограничения на разрядность. Внутри используется тип int64_t.
+В LUA 5.3+ потерь разрядности нет, в более старых - разрядность будет обрезана до размера мантиссы типа double.
+
+### Генерация случайных данных
+
+Функции генерируют raw строку указанного размера , состоящую из случайных байт.
+```
+function brandom(size)
+function brandom_az(size)
+function brandom_az09(size)
+```
+
+* brandom возвращает байты с 0 до 255
+* brandom_az - символы от 'a' до 'z'
+* brandom_az09 - символы от 'a' до 'z' и числа от '0' до '9'
+
+