OpenPrinting CUPS Filters

For modern native PDF printers controlled via IPP, pdftopdf can emit Job Control Language (JCL) when the provided PPD file contains the *JCLToPDFInterpreter: keyword. This enables hardware-level features like device collation or hardware copy generation.

PPD Configuration Example:

*JCLBegin:           "<1B>%-12345X@PJL JOB<0A>"
    *JCLToPDFInterpreter: "@PJL ENTER LANGUAGE = PDF <0A>"
    *JCLEnd:             "<1B>%-12345X@PJL EOJ <0A><1B>%-12345X"

Key Features:

• Custom JCL Strings: For any marked option in the PPD, you can use the prefix pdftopdfJCL<option name> to send raw JCL strings. This includes *pdftopdfJCLBegin and *pdftopdfJCLCopies.
• Copies Support: If the PPD contains the Copies keyword, pdftopdf automatically adds @PJL SET COPIES=... or @PJL SET QTY=....
• UI Injection: Other JCL code can be injected using *JCLOpenUI: ... and *JCLCloseUI: ....

To compile and use cups-filters, ensure the following dependencies are met:

Core Dependencies:

• CUPS (version 2.2.2 or newer)
• libcupsfilters 2.x
• libppd

Recommended PDF Renderers (at least one required, especially for non-PDF printers):

• Ghostscript (preferred)
• Poppler
• MuPDF (version 1.15 or newer is required to avoid printing bugs)

Build Tools:

• gcc (C compiler)
• automake
• autoconf
• autopoint
• libtool
• On Debian/Ubuntu-based systems, installing the build-essential package will satisfy most build tool requirements.

Ghostscript Specific Requirements: If using Ghostscript (via gsto... or universal filters), you must use Ghostscript 10.00.0 (10.01.0+ highly recommended). It must be built with libcups (2.2.2+) and include the following output devices:

• pdfwrite
• ps2write
• cups
• pwgraster
• appleraster
• pclm
• pclm8
• pdfimage24
• pdfimage8
• pxlcolor
• pxlmono

The beh (Backend Error Handler) is a wrapper for CUPS backends that prevents print queues from being disabled when a backend error occurs (e.g., printer offline). It allows you to configure retry logic, intervals, and whether to disable the queue upon final failure.

Activation

Activate beh for a print queue using lpadmin with a specific URI format:

lpadmin -p <queue name> -E -v beh:/<dd>/<att>/<delay>/<originaluri>

URI Parameters

All parameters must be specified, even if they are effectively ignored by other settings:

• <dd> (Don't Disable): 1 means the queue is never disabled (even if the job is lost); 0 means the error status is passed to CUPS, which may disable the queue.
• <att> (Attempts): Number of retries. 0 means infinite retries.
• <delay> (Delay): Integer number of seconds between attempts. (Meaningless if <att> is 1).
• <originaluri>: The original backend URI (find this via lpstat -v).

Note: beh works with all backends except the HPLIP hp backend.

Usage Examples

• Retry 3 times with 5s delay, then discard job (don't disable queue): beh:/1/3/5/socket://printer:9100
• Retry 10 times with 60s delay, then disable queue on failure: beh:/0/10/60/socket://printer:9100
• Retry infinitely with 60s delay (ideal for home/desktop printers): beh:/1/0/60/usb://Brother/HL-5040%20series

The texttotext filter is designed for text-only printers (line printers, daisy-wheels, POS printers). It takes UTF-8 plain text as input and avoids the overhead of PDF conversion.

Installation: To set up a printer using this filter, use lpadmin with the following driver:

# Use the textonly.ppd driver
# Note: This is a conceptual command based on the documentation
# lpadmin -p <printer_name> -m drv:///cupsfilters.drv/textonly.ppd

Configuration via Installable Options:

• Page Sizes: Define the number of lines and columns for each supported page size. (Default: 6 lines per inch, 10 columns per inch).
• Form Feed: Configure whether to send a Form Feed character after each page. It is highly recommended for sheet alignment. If the printer doesn't support it, disable it and ensure line counts are adjusted so the printer advances via blank lines.

Key Features:

• Continuous Printing: Supports a non-paginated mode for roll paper (POS printing) that ignores page height.
• Pagination Control: Supports standard CUPS options like page-ranges, page-set, output-order, collate, and multiple copies when pagination is enabled.

If a PostScript printer misbehaves or crashes due to Ghostscript's compressed output, you can use the psdebug option to generate uncompressed PostScript for analysis.

Enable for a single job:

lpr -P <printer> -o psdebug <file>
# OR
lp -d <printer> -o psdebug <file>

Set as a personal default:

lpoptions -p <printer> -o psdebug

How to extract the output for analysis:

1. Enable file device printing: cupsctl FileDevice=yes
2. Create a test queue that prints to a file:

   lpadmin -p test -E -v file:/tmp/printout -P /etc/cups/ppd/<original_ppd_name>.ppd

3. Print to the test queue using the psdebug option.
4. The uncompressed PostScript will be available in /tmp/printout.

lpr -P <printer> -o psdebug <file>

# To extract output for analysis:
cupsctl FileDevice=yes
lpadmin -p test -E -v file:/tmp/printout -P /etc/cups/ppd/<name of original queue>.ppd

Follow these formatting rules for C/C++ code:

Indentation

• Brackets: The opening brace { must begin on a new line. The code following it starts on a new line and is indented 2 spaces. The closing brace } is placed on a new line at the original indentation level.
• Control Flow: Single-line statements following do, else, for, if, and while are indented 2 spaces.
• Switch Blocks: Code inside case or default blocks is indented 4 spaces.

Spacing

• A space must follow reserved words like if or while.
• Do not insert a space between a function name and the arguments in parenthesis.

Return Values

• Parenthesis must surround returned values: return (VALUE);

{
  int i;

  for (i = 0; i < 1000; i ++)
  {
    do_this(i);
    do_that(i);
  }
}

switch (array[i])
{
  case STATE_IDLE :
      do_this(i);
      break;

  default :
      do_nothing(i);
      break;
}