Subversion Repositories planix.SVN

.TH POSTIO 1 "DWB 3.2"

.SH NAME

.B postio

\- serial interface for PostScript printers

.SH SYNOPSIS

\*(mBpostio\f1

.OP \-l line

.OP "" options []

.OP "" files []

.SH DESCRIPTION

.B postio

sends

.I files

to the PostScript printer attached to

.IR line .

If no

.I files

are specified the standard input is sent.

The first group of

.I options

should be sufficient for most applications:

.TP 0.75i

.OP \-b speed

Transmit data over

.I line

at baud rate

.I speed.

Recognized baud rates are 1200, 2400, 4800, 9600, and 19200.

The default

.I speed

is 9600 baud.

.TP

.OP \-c

Do not send

.MR ^C s

(interrupts) to the printer,

which means

.B postio

does not force a busy printer into the idle state.

.TP

.OP \-l line

Connect to printer attached to

.IR line .

In most cases there is no default and

.B postio

must be able to read and write

.IR line .

If

.I line

does not begin with

.MW /

it is treated as a Datakit destination.

.TP

.OP \-q

Prevents status queries while

.I files

are being sent to the printer.

When status queries are disabled a dummy message is appended

to the log file before each block is transmitted.

.TP

.OP \-B num

Set internal buffer size for reading and writing

.I files

to

.I num

bytes

(default is 2048 bytes).

.TP

.OP \-D

Enable debug mode.

Guarantees that everything read on

.I line

will be added to the log file (standard error by default).

.TP

.OP \-L file

Data received on

.I line

gets put in

.IR file .

The default log

.I file

is standard error.

Printer or status messages that do not indicate a change in state

are not normally written to

.I file

but can be forced out using the

.OP \-D

option.

.TP

.OP \-P string

Send

.I string

to the printer before any of the input files.

The default

.I string

is simple PostScript code that disables timeouts.

.TP

.OP \-R num

Run

.B postio

as a single process if

.I num

is 1 or as separate read and write processes if

.I num

is 2.

By default

.B postio

runs as a single process.

.PP

The next two

.I options

are provided for users who expect to run

.B postio

on their own.

Neither is suitable for use in spooler interface

programs:

.TP 0.35i

.OP \-i

Run the program in interactive mode.

Any

.I files

are sent first and followed by the standard input.

Forces separate read and write processes

and overrides many other options.

To exit interactive mode use your interrupt or quit character.

To get a friendly interactive connection with the printer type

.MW executive

on a line by itself.

.TP

.OP \-t

Data received on

.I line

and not recognized as printer or status information is written to

the standard output.

Forces separate read and write processes.

Convenient if you have a PostScript program that

will be returning useful data to the host.

.PP

The last option is not generally recommended and should only

be used if all else fails to provide a reliable connection:

.TP 0.35i

.OP \-S

Slow the transmission of data to the printer.

Severely limits throughput, runs as a single process,

disables the

.OP \-q

option, limits the internal buffer size to 1024 bytes,

can use an excessive amount of

.SM CPU

time, and does nothing in interactive mode.

.PP

Best performance is usually obtained by using

a large internal buffer

.OP -B "" ) (

and by running the program as separate read and write processes

.OP \-R2 "" ). (

Inability to fork the additional process causes

.B postio

to continue as a single read/write process.

When one process is used, only data sent to the printer is flow-controlled.

.PP

The options are not all mutually exclusive.

The

.OP \-i

option always wins, selecting its own settings for whatever is

needed to run interactive mode, independent of anything else

found on the command line.

Interactive mode runs as separate read and write processes

and few of the other

.I options

accomplish anything in the presence of the

.OP \-i

option.

The

.OP \-t

option needs a reliable two way connection to the printer and

therefore tries to force separate read and write processes.

The

.OP \-S

option relies on the status query mechanism, so

.OP \-q

is disabled and the program runs as a single process.

.PP

In most cases

.B postio

starts by making a connection to

.I line

and then attempts to force the printer into the

.SM IDLE

state by sending an appropriate sequence of

.MW ^T

(status query), 

.MW ^C

(interrupt), and

.MW ^D

(end of job) characters.

When the printer goes

.SM IDLE

.I files

are transmitted along with an occasional

.MW ^T

(unless the

.OP \-q

option was used).

After all the

.I files

are sent the program waits until it is reasonably sure the

job is complete.

Printer generated error messages received at any time

except while establishing the initial connection

(or when running interactive mode) cause

.B postio

to exit with a non-zero status.

In addition to being added to the log file, printer error messages

are also echoed to standard error.

.SH EXAMPLES

Run as a single process at 9600 baud and send

.I file1

and

.I file2

to the printer attached to

.MR /dev/tty01 :

.EX

postio -l /dev/tty01  \f2file1  file2

.EE

Same as above except two processes are used,

the internal buffer is set to 4096 bytes,

and data returned by the printer gets put in file

.MR log :

.EX

postio -R2 -B4096 -l/dev/tty01 -Llog  \f2file1  file2

.EE

Establish an interactive connection with the printer at Datakit

destination

.MR my/printer :

.EX

postio -i -l my/printer

.EE

Send file

.MW program

to the printer connected to

.MR /dev/tty22 ,

recover any data in file

.MR results ,

and put log messages in file

.MR log :

.EX

postio -t -l /dev/tty22 -L log program >results

.EE

.SH DIAGNOSTICS

A 0 exit status is returned if the files ran successfully.

System errors (e.g., ``can't open the line'') set the low order

bit in the exit status, while PostScript errors set bit 1.

An exit status of 2 usually means the printer

detected a PostScript error in the input

.IR files .

.SH WARNINGS

.PP

The input

.I files

are handled as a single PostScript job.

Sending several different jobs, each with their own internal

end of job mark

.RM ( ^D )

is not guaranteed to work properly.

.B postio

may quit before all the jobs have completed and could be restarted

before the last one finishes.

.PP

All the capabilities described above may not be available on every

machine or even across the different versions of

.SM UNIX

that are currently supported by the program.

For example, the code needed to connect to a Datakit destination may only

work on System\ V and may require that the

.SM DKHOST

software package be available at compile time.

.PP

There may be no default

.I line

so using

.OP \-l

option is strongly recommended.

If omitted

.B postio

may attempt to connect to the printer using the standard output.

If Datakit is involved the

.OP \-b

may be ineffective and attempts by

.B postio

to flow control data in both directions may not work.

The

.OP \-q

option can help if the printer is connected to \s-1RADIAN\s+1.

The

.OP \-S

option is not generally recommended and should only be used if

all else fails to establish a reliable connection.

.SH SEE ALSO

.BR buildtables (1),

.BR dpost (1),

.BR postdaisy (1),

.BR postdmd (1),

.BR postmd (1),

.BR postprint (1),

.BR postreverse (1),

.BR posttek (1),

.BR printfont (1)