Xi-Text Printer Setup Files: What They Contain and When They Are Read

The files in a printer's directory, the order in which Xi-Text reads them, and how to tell whether one parsed

Xi-TextXi-Textconfigurationprinterssetup-filestroubleshooting

Each Xi-Text printer has a directory of text setup files that say how the printer is driven, from the serial line settings to the strings sent around each page. This article says what those files contain, which of them is read and when, and what a syntax error does. The procedures for starting and halting printers are in Managing Xi-Text Printer States and Operations.

Where the files live

Setup files are in printer-specific subdirectories under the printers directory (default: /var/spool/xi/printers). The default can be moved by setting SPOOLPT in /etc/xi/textconfig.

For a printer named ptr1, setup files are in:

/var/spool/xi/printers/ptr1/

The three kinds of file in a printer directory

Setup files, one per paper type

Files without leading . or - characters are setup files representing paper types:

/var/spool/xi/printers/ptr1/a4
/var/spool/xi/printers/ptr1/letter
/var/spool/xi/printers/ptr1/default

A file is offered as a paper type only when it is a plain file owned by the system user spooler. A file owned by anyone else is still read if a job asks for it by name, and it stays out of the list of paper types that Xi-Text offers an operator loading the printer.

The .device file

The .device file holds the settings that describe the connection to the printer, and that therefore stay the same whatever paper is loaded:

/var/spool/xi/printers/ptr1/.device

This file is where the printer installation script Ptrinstall puts:

Serial line settings - baud, ixon, ixany, parenb, parodd, cs7, cs8, twostop, clocal
The network command for a printer reached over the network (network=)
Timeouts - open, offline, close, postclose
Output buffering and device handling - outbuffer, reopen, canhang

The .device file is read before the paper-type setup file, every time the setup files are read. The two files are parsed as one continuous stream, so a symbolic name defined in .device can be used in the paper-type file that follows it.

A printer with a .device file still needs a paper-type file or a default file; if neither can be opened the printer fails to start. The .device file is also the only place the network command belongs: a printer whose device is a network address must have a network= command, and a printer on a local device must not have one. Either mismatch stops the printer with "does not have network command specified or non-network printer does".

The physical device or network address itself is a property of the printer, set with spadd or spchange. There is no port or device keyword in a setup file.

Helper files

Files beginning with . or - are never treated as paper types, so a printer directory is also the natural place for the files a setup file refers to:

/var/spool/xi/printers/ptr1/-Help       # Online help text
/var/spool/xi/printers/ptr1/.setpage    # Named by an align= line
/var/spool/xi/printers/ptr1/.acct       # Named by a record or logfile line

Only -Help is a fixed name: Xi-Text opens it by that name to give an operator help when they are choosing a form type to load onto the printer. The others are ordinary names chosen by whoever wrote the setup file. A file name in an align, record or logfile line that does not begin with / is taken relative to the printer's own directory, which is why the short names above work.

How Xi-Text chooses which file to read

When a printer needs its setup, Xi-Text:

Splits the form type into a paper type (everything before the first . or -) and a suffix (the rest)
Changes to the printer's directory under the printers directory - if that directory is missing, the printer goes to Error
Reads .device first, if it exists
Reads the file whose name is exactly the paper type
Falls back to default if there is no file of that name
Fails, and puts the printer into Error, if neither can be opened

Steps 4 and 5 happen whether or not there is a .device file. The file name is matched by the operating system, so it is case sensitive - a job submitted as A4.ps is accepted by a printer loaded with a4, but the setup file looked for is A4, and where there is no such file the printer uses default instead, with nothing logged.

The suffix never selects a file. It selects material within the files that are read, through the conditional construct described below.

An example

For printer ptr1 with these files:

.device
a4
letter
default

Form type selections:

a4.ps → reads .device, then a4 (suffix: ps)
letter.p10 → reads .device, then letter (suffix: p10)
legal → reads .device, then default (no suffix)
A4.ps → reads .device, then default, because there is no file called A4

When the files are read

Setup files are processed:

At printer startup - .device and the setup file are read before the device is opened and the setup string sent
When the form type changes - if the next job's form type differs from the printer's current one in any character, including the suffix alone, the printer sends its sufend string, adopts the new form type, re-reads both files and sends the new sufstart string

They are not read once per job. A job whose form type matches what the printer is already showing reuses the settings already in memory.

An edit is therefore picked up at the next printer start, and also at the next form type change, so a file edited into a broken state can drop a running printer into Error part-way through a queue rather than at the moment you saved it. Restart the printer after an edit, and send a job with a different suffix to exercise the conditional blocks.

What the files control

Hardware parameters (typically in .device)

Serial line settings - baud, cs7 / cs8, twostop, parenb, parodd, clocal
Flow control - ixon, ixany
Output translation - onlcr, ocrnl, olcuc, onocr, onlret, extabs, addcr
Timeouts - open, offline, close, postclose
Device handling - outbuffer, reopen, canhang, closekill
A command to run against the port before use - portsetup
An stty command line to run against the port - stty

Print job handling

Banner page control - banner, nohdr, forcehdr, stdhdr, hdrpercopy, and bannprog to name a program that produces the banner
Single-sheet mode - single, which puts the printer into the a/w oper state before each job so paper can be fed by hand
Page delimiter - delimiter, which defines what counts as a page boundary
Page range handling - noranges, where the printer itself understands page ranges
Copies and retention - onecopy, retain, inclpage1, windback
Accounting and logging - charge, record, logfile, logerror, fberror
Banner page width - width

Strings sent to the printer

setup - sent once when the printer starts
halt - sent when the printer stops
docstart - before each document
docend - after each document
pagestart - before each page
pageend - after each page
sufstart - after a new form type has been adopted
sufend - before the old form type is given up
abort - on job cancellation
restart - when a job is restarted

Each of these takes its value as a quoted string, or as one or more symbolic names defined earlier in the file. Writing the keyword with an = sign and nothing else clears the string.

Processing options

filter - command that all output is piped through
network - command that carries the data to a network interface
align - file holding an alignment page
execalign - command that generates an alignment page
bannprog - program that produces banner pages
portsetup - command run against the port before the device is opened
exec - written before a string keyword's value to run it as a command rather than send it

Conditional handling

Suffix-specific settings using a { (pattern) ... (pattern) ... } block, where the patterns are matched against the suffix and the first one that matches is used
@ matches the empty suffix, and *, ? and [...] are the wildcards
Suffix patterns are matched case sensitively, and carry no leading dot

Examples

Serial printer

# .device file - values are written after the keyword, with no = sign
# Porttype: Serial

baud 9600
ixon
open 30
offline 300
outbuffer 1024

# default setup file
# Symbolic names first - defining one sends nothing by itself

RESET=\eE

setup   RESET
halt    RESET

PCL printer with multiple paper types

# a4 setup file

RESET=\eE
A4SIZE=\e&l26A

setup   RESET A4SIZE

# letter setup file

RESET=\eE
LETTERSIZE=\e&l2A

setup   RESET LETTERSIZE

Suffix handling within one setup file

LANDSCAPE=\e&l1O
PORTRAIT=\e&l0O
P12=\e(s12H

{
        (l*)
                docstart LANDSCAPE
        (*)
                docstart PORTRAIT
}

{
        (*12)
                sufstart P12
}

Network terminal server

# .device file

open 30
offline 300
close 10000
postclose 1
reopen

network=/usr/libexec/xi/xtelnet -p 9100 -h $SPOOLDEV

What a syntax error does

Setup file syntax errors prevent printer startup. When a printer enters Error state:

Check the system log file:

bash tail -20 /var/spool/xi/spd/spshed_reps
Each entry names the printers directory, the printer and the file that was being read, then gives the reason. The messages come from the setup file reader and read like:
- "Error near line 12 - probable undefined name `csize'." - a name Xi-Text does not recognise, used without an = sign
- "Error near line 4 - Number expected" - a keyword such as baud or open followed by something other than a number, most often an = sign
- "Error near line 9 - Expected a `}'" - an unclosed conditional block
- "Error near line 7 - Invalid baud rate 12000"
- "There does not appear to be a setup file (even a possible default one of `default') in the printer directory for printer name ptr1"
- "There does not appear to be a directory for the printer name ptr1 in the printers directory /var/spool/xi/printers"
The same file can be read from within spq with the X command.

Nothing is written to the log when a setup file is read successfully, so an empty log after a printer start means the files parsed.

Common mistakes, and what each one does:

A keyword name Xi-Text does not have. Any unrecognised word is taken as a symbolic name, so it needs an = sign and a value. Without one you get "probable undefined name". With one - ptr_type=ps, for example - it is accepted in silence and does nothing at all.
Writing setup=, docstart= and so on with a value. The = sign on these keywords clears the string. The value must follow as a quoted string or as a symbolic name.
A backslash or other punctuation where a keyword is expected. Writing setup=\e&l26A stops the parse dead at the backslash: the rest of the file is discarded, nothing is logged, the printer starts, and it starts with an empty setup string. Escape sequences belong on the right-hand side of a symbolic name definition, as in the examples above.
An unclosed quote. The string ends at the end of the line, and no error is raised.

Ownership and permissions

Owner: spooler - required for a file to be offered as a paper type
Permissions: 644 (read for all, write for owner)
Directory: 755 (readable and executable for all)

Xi-Text does not test the group, and the group the packages give these files differs between distributions, so leave it alone.

Check permissions:

ls -la /var/spool/xi/printers/ptr1/

Fix if needed:

chown -R spooler: /var/spool/xi/printers/ptr1/
chmod 755 /var/spool/xi/printers/ptr1/
find /var/spool/xi/printers/ptr1/ -type f -exec chmod 644 {} \;

Use find here. A shell wildcard does not match a leading dot, so it misses .device - the first file Xi-Text tries to open.

Sharing one directory between identical printers

For identical printers, create a master template directory and link to it:

# Master template
/var/spool/xi/printers/hp-laserjet-template/

# Symbolic links
/var/spool/xi/printers/office1 -> hp-laserjet-template
/var/spool/xi/printers/office2 -> hp-laserjet-template

Individual files can also be linked:

cd /var/spool/xi/printers/office1
ln -s ../template-printer/a4 a4

Xi-Text follows the link when it checks a file, so it is the file at the far end of the link that must be a plain file owned by spooler.

Where the procedures are

Configuring Xi-Text Form Types, Paper Types and Suffixes - Understanding form type structure
Managing Xi-Text Printer States and Operations - Starting and stopping printers
Diagnosing and Clearing the Xi-Text Printer error State - Troubleshooting setup file problems
Reading the Xi-Text System Log (spshed_reps) - Reading the messages described above
Setting Up and Working With Xi-Text Alignment Pages - The align and execalign keywords

The complete setup file syntax and every keyword are in the Xi-Text System Reference Manual, Chapter: Printer Definitions.

Last updated: 20 August 2026