From d0fcb3b062d0f1a66c9a89f799f4e8ac6f194d37 Mon Sep 17 00:00:00 2001 From: user Date: Wed, 23 Sep 2026 23:34:03 +0400 Subject: [PATCH] docs: add Russian README and update English docs Add a Russian README and revise the English documentation to keep both versions aligned. --- README.md | 78 ++++++++++---------- README.ru.md | 205 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 244 insertions(+), 39 deletions(-) create mode 100644 README.ru.md diff --git a/README.md b/README.md index 86136da..198a9fb 100644 --- a/README.md +++ b/README.md @@ -4,65 +4,65 @@ SPDX-FileCopyrightText: 2026 Contributors to cups-kyocera-rastertokpsl-fix SPDX-License-Identifier: CC0-1.0 --> -# CUPS wrapper для Kyocera `rastertokpsl` +# CUPS wrapper for Kyocera `rastertokpsl` -Обёртка для CUPS-фильтра `rastertokpsl`, предназначенная для устранения падений оригинального Kyocera-фильтра при печати заданий с длинными или не-ASCII названиями. +A wrapper for the CUPS `rastertokpsl` filter designed to prevent crashes of the original Kyocera filter when processing print jobs with long or non-ASCII titles. -## Проблема +## Problem -Некоторые версии Kyocera `rastertokpsl` используют фиксированный буфер для обработки названия задания. При передаче длинной строки или строки с кириллицей это может приводить к переполнению буфера и аварийному завершению фильтра: +Some versions of the Kyocera `rastertokpsl` filter use a fixed-size buffer to process the job title. Passing a long string or a string containing Cyrillic characters can cause a buffer overflow and result in the filter terminating unexpectedly: ```text *** buffer overflow detected ***: terminated ``` -В журналах CUPS это может выглядеть примерно так: +In the CUPS logs, this may look like: ```text PID 30752 (/usr/lib/cups/filter/rastertokpsl) crashed on signal 6 ``` -В результате задание не печатается, а очередь принтера может перейти в состояние `stopped`. +As a result, the job is not printed and the printer queue may enter the `stopped` state. -## Решение +## Solution -Wrapper перехватывает аргументы CUPS перед запуском оригинального `rastertokpsl`. +The wrapper intercepts the CUPS arguments before launching the original `rastertokpsl`. -Перед передачей названия задания оригинальному фильтру wrapper: +Before passing the job title to the original filter, the wrapper: -- преобразует UTF-8 в ASCII; -- удаляет неподдерживаемые символы; -- ограничивает длину строки; -- использует `print-job`, если после обработки строка оказалась пустой. +- converts UTF-8 to ASCII; +- removes unsupported characters; +- limits the string length; +- uses `print-job` if the resulting string is empty. -Оригинальный бинарник сохраняется под именем: +The original binary is stored as: ```text /usr/lib/cups/filter/rastertokpsl.real ``` -Wrapper устанавливается вместо него: +The wrapper is installed in its place: ```text /usr/lib/cups/filter/rastertokpsl ``` -## Установка +## Installation -Сначала сохраните оригинальный фильтр: +First, save the original filter: ```bash sudo cp /usr/lib/cups/filter/rastertokpsl \ /usr/lib/cups/filter/rastertokpsl.real ``` -Создайте файл wrapper: +Create the wrapper file: ```bash sudo nano /usr/lib/cups/filter/rastertokpsl ``` -Содержимое: +Contents: ```bash #!/bin/bash @@ -107,7 +107,7 @@ exec "$REAL" \ "$options" ``` -Назначьте права: +Set the appropriate permissions: ```bash sudo chown root:root /usr/lib/cups/filter/rastertokpsl @@ -115,59 +115,59 @@ sudo chmod 755 /usr/lib/cups/filter/rastertokpsl sudo chmod 755 /usr/lib/cups/filter/rastertokpsl.real ``` -Перезапустите CUPS: +Restart CUPS: ```bash sudo systemctl restart cups ``` -## Проверка +## Verification -Убедитесь, что оригинальный файл является исполняемым бинарником: +Make sure the original file is an executable binary: ```bash file /usr/lib/cups/filter/rastertokpsl.real ``` -Ожидается вывод с `ELF ... executable`. +The expected output should contain `ELF ... executable`. -Проверьте печать обычного задания: +Test printing a normal job: ```bash lp -d PRINTER /tmp/test.pdf ``` -Затем проверьте длинное название задания: +Then test a job with a long title: ```bash lp -d PRINTER \ - -t "Очень длинное кириллическое название задания для проверки" \ + -t "Very long Cyrillic job title for testing" \ /tmp/test.pdf ``` -Посмотреть состояние очереди: +Check the queue status: ```bash lpstat -p lpstat -o ``` -При необходимости включить подробное логирование CUPS: +To enable verbose CUPS logging when needed: ```bash sudo cupsctl --debug-logging sudo tail -F /var/log/cups/error_log ``` -После завершения диагностики: +After troubleshooting is complete: ```bash sudo cupsctl --no-debug-logging ``` -## Восстановление оригинального фильтра +## Restoring the Original Filter -Чтобы удалить wrapper и вернуть оригинальный `rastertokpsl`: +To remove the wrapper and restore the original `rastertokpsl`: ```bash sudo mv /usr/lib/cups/filter/rastertokpsl.real \ @@ -176,21 +176,21 @@ sudo mv /usr/lib/cups/filter/rastertokpsl.real \ sudo systemctl restart cups ``` -## Ограничения +## Limitations -Wrapper рассчитан на конкретный вариант интерфейса Kyocera `rastertokpsl`, использующий пять аргументов: +The wrapper is designed for a specific Kyocera `rastertokpsl` interface that uses five arguments: ```text printer job-id title copies options ``` -Размер `20` символов выбран как консервативное ограничение для проблемных версий фильтра. Точный размер внутреннего буфера конкретной версии `rastertokpsl` зависит от драйвера и не определяется самим CUPS. +The `20` character limit was chosen as a conservative restriction for problematic filter versions. The exact size of the internal buffer depends on the specific `rastertokpsl` driver version and is not determined by CUPS itself. -Перед установкой рекомендуется сохранить исходный бинарник и проверить версию драйвера. +Before installation, it is recommended to back up the original binary and check the driver version. -## Структура +## Repository Structure -Пример структуры репозитория: +Example repository structure: ```text cups-kyocera-rastertokpsl-fix/ @@ -198,7 +198,7 @@ cups-kyocera-rastertokpsl-fix/ └── rastertokpsl ``` -Файл `rastertokpsl` из репозитория устанавливается в: +The `rastertokpsl` file from the repository is installed to: ```text /usr/lib/cups/filter/rastertokpsl diff --git a/README.ru.md b/README.ru.md new file mode 100644 index 0000000..86136da --- /dev/null +++ b/README.ru.md @@ -0,0 +1,205 @@ + + +# CUPS wrapper для Kyocera `rastertokpsl` + +Обёртка для CUPS-фильтра `rastertokpsl`, предназначенная для устранения падений оригинального Kyocera-фильтра при печати заданий с длинными или не-ASCII названиями. + +## Проблема + +Некоторые версии Kyocera `rastertokpsl` используют фиксированный буфер для обработки названия задания. При передаче длинной строки или строки с кириллицей это может приводить к переполнению буфера и аварийному завершению фильтра: + +```text +*** buffer overflow detected ***: terminated +``` + +В журналах CUPS это может выглядеть примерно так: + +```text +PID 30752 (/usr/lib/cups/filter/rastertokpsl) crashed on signal 6 +``` + +В результате задание не печатается, а очередь принтера может перейти в состояние `stopped`. + +## Решение + +Wrapper перехватывает аргументы CUPS перед запуском оригинального `rastertokpsl`. + +Перед передачей названия задания оригинальному фильтру wrapper: + +- преобразует UTF-8 в ASCII; +- удаляет неподдерживаемые символы; +- ограничивает длину строки; +- использует `print-job`, если после обработки строка оказалась пустой. + +Оригинальный бинарник сохраняется под именем: + +```text +/usr/lib/cups/filter/rastertokpsl.real +``` + +Wrapper устанавливается вместо него: + +```text +/usr/lib/cups/filter/rastertokpsl +``` + +## Установка + +Сначала сохраните оригинальный фильтр: + +```bash +sudo cp /usr/lib/cups/filter/rastertokpsl \ + /usr/lib/cups/filter/rastertokpsl.real +``` + +Создайте файл wrapper: + +```bash +sudo nano /usr/lib/cups/filter/rastertokpsl +``` + +Содержимое: + +```bash +#!/bin/bash + +REAL="/usr/lib/cups/filter/rastertokpsl.real" + +# Kyocera rastertokpsl uses the following arguments: +# $1 printer +# $2 job-id +# $3 title +# $4 copies +# $5 options + +if [ "$#" -ne 5 ]; then + echo "ERROR: rastertokpsl wrapper: expected 5 arguments, got $#" >&2 + exit 1 +fi + +printer="$1" +job_id="$2" +title="$3" +copies="$4" +options="$5" + +# Convert the title to ASCII, remove unsupported characters, +# and limit its length to 20 characters. +safe_title="$( + printf '%s' "$title" | + iconv -f UTF-8 -t ASCII//TRANSLIT 2>/dev/null | + LC_ALL=C tr -cd 'A-Za-z0-9' | + tail -c 20 +)" + +[ -n "$safe_title" ] || safe_title="print-job" + +# Pass the raster data through stdin. +exec "$REAL" \ + "$printer" \ + "$job_id" \ + "$safe_title" \ + "$copies" \ + "$options" +``` + +Назначьте права: + +```bash +sudo chown root:root /usr/lib/cups/filter/rastertokpsl +sudo chmod 755 /usr/lib/cups/filter/rastertokpsl +sudo chmod 755 /usr/lib/cups/filter/rastertokpsl.real +``` + +Перезапустите CUPS: + +```bash +sudo systemctl restart cups +``` + +## Проверка + +Убедитесь, что оригинальный файл является исполняемым бинарником: + +```bash +file /usr/lib/cups/filter/rastertokpsl.real +``` + +Ожидается вывод с `ELF ... executable`. + +Проверьте печать обычного задания: + +```bash +lp -d PRINTER /tmp/test.pdf +``` + +Затем проверьте длинное название задания: + +```bash +lp -d PRINTER \ + -t "Очень длинное кириллическое название задания для проверки" \ + /tmp/test.pdf +``` + +Посмотреть состояние очереди: + +```bash +lpstat -p +lpstat -o +``` + +При необходимости включить подробное логирование CUPS: + +```bash +sudo cupsctl --debug-logging +sudo tail -F /var/log/cups/error_log +``` + +После завершения диагностики: + +```bash +sudo cupsctl --no-debug-logging +``` + +## Восстановление оригинального фильтра + +Чтобы удалить wrapper и вернуть оригинальный `rastertokpsl`: + +```bash +sudo mv /usr/lib/cups/filter/rastertokpsl.real \ + /usr/lib/cups/filter/rastertokpsl + +sudo systemctl restart cups +``` + +## Ограничения + +Wrapper рассчитан на конкретный вариант интерфейса Kyocera `rastertokpsl`, использующий пять аргументов: + +```text +printer job-id title copies options +``` + +Размер `20` символов выбран как консервативное ограничение для проблемных версий фильтра. Точный размер внутреннего буфера конкретной версии `rastertokpsl` зависит от драйвера и не определяется самим CUPS. + +Перед установкой рекомендуется сохранить исходный бинарник и проверить версию драйвера. + +## Структура + +Пример структуры репозитория: + +```text +cups-kyocera-rastertokpsl-fix/ +├── README.md +└── rastertokpsl +``` + +Файл `rastertokpsl` из репозитория устанавливается в: + +```text +/usr/lib/cups/filter/rastertokpsl +```