ppop.1
ppop - PPR operators utility
ppop
[switches] [subcommand ... ] [arguments]
If the ppop command is invoked without sub-command arguments it will enter
interactive mode. In interactive mode it reads commands from stdin and
executes them.
The --version switch prints the PPR version number.
The --help switch prints abbreviated instructions for use. It will suggest that
the user type ``ppop help'' for further instructions.
There are other switches which may be used when invoking
ppop
, either
with a subcommand on the command line or without one (for interactive mode).
The -X switch can be used to submit a principal identification string. A
principal identification string is used when dealing with jobs which a Unix
user has submited on the behalf of other users. This may be apply in the
case of a network print server process which accepts jobs from remote
clients. The remote users may be either real Unix users or anything other
sort of entity which may be identified by a short unique string.
If an -X switch was used when submitting the job and a subsequent
ppop command includes an -X switch, the principal string must be
the same or permission to perform the operation will be denied. A network
print server such as Samba can use this to prevent a remote user from
deleting any but the jobs he submitted.
The
ppop
command has some limited support for wildcards in principal
strings. For principal strings containing an ``@'', the user name, the host
name, or both may be replaced with ``*'' which will match any user name or any
host name. For example, ``
ppop -X 'smith@*' cancel myprn
'' will cancel all
jobs for queued for ``myprn'' which were submitted on behalf of the user
``smith'' from any host. The command ``
ppop -X '*@*' cancel myprn
'' will cancel
jobs submitted on the behalf of any user from any host but it will not
delete any non-proxy jobs, nor will it delete proxy jobs with principal
strings that do not contain an ``@''. These wildcards are exploited by
lprsrv. Careful reading of the above rules will reveal that lprm can
generally only be used to remove jobs submitted with lpr.
The -M switch should be used when another program will be parsing ppop's
output. The -M switch simplifies the output format. Banner lines which
give column names are suppressed. In interactive
mode the banner is changed to a terse one, the prompt is suppressed, and after
each command is executed a line in the form ``*DONE\t%d\n
'' is printed where
%d
is the return code of the command. Columns which would ordinarily be
separated by a varying number of spaces may be separated by tabs.
The -u switch can be used by an operator to cause
ppop
to behave as
though he were another user. For example,
ppop -u smith cancel chipmunk
will cancel all jobs belonging to user ``smith'' which are queued for ``chipmunk''.
The -A can cause arrested jobs to be ommited from queue listings on the
theory that they are unimportant. It takes an integer as its argument.
This integer is an interval in seconds. Jobs which were arrested more than
integer seconds ago are ommited from queue listings.
Most operations performed by the ppop command require PPR operator privileges.
Only those operations which do not alter the spooler state (such as listing
the queue) or only affect a user's own jobs may be performed by
non-privileged users. This command defines a privileged user as the
user ``ppr'', a user with a UID of 0 (root), or a user who is a member
of the group ``ppop''.
-
ppop destination
{destination, all}
-
-
ppop dest
{destination, all}
-
displays information about the indicated Idestination>
(printer or group). This information includes whether it is a printer or a
group, whether it is currently accepting jobs, and whether it is
``protected''. If you specify ``all'' instead of a destination name, you will
be shown the aforementioned information for all destinations.
-
ppop ldest
{destination, all}
-
This command is identical to the
ppop dest
command, except that this
command also displays the comment which is attached to each printer or
group.
-
ppop accept
destination
-
Instruct the indicated destination to begin accepting new print jobs.
-
ppop reject
destination
-
Instructs the indicated destination to reject new print jobs. Any jobs a
user attempts to submit will be discarded and the user will be notified.
Notice that setting a printer destination to ``reject'' does not prevent it
from printing jobs for any group of which it happens to be a member, nor
does setting a group to reject prevent its members from printing jobs
explicitly sent to them or for other groups of which they happen to be
members, nor
does setting a printer or group to reject stop it from printing those
jobs which have already been accepted.
.
-
ppop list
{destination-name, all}
-
Display a somewhat detailed list of those jobs queued for the indicated
destination or for all destinations. If a single job name is specified,
information is displayed for only that job.
-
ppop short
{destination-name, all}
-
Display a terser queue listing than that displayed by
ppop list
.
-
ppop details
{destination-name, job-id, all}
-
Display an extremely verbose queue listing. This command is used for
debugging PPR and for the World Wide Web interface.
The output format of this command is likely to change in the future.
-
ppop lpq
destination-name [job# ...] [
username
...]
-
Display a queue listing in a format similar to Berkeley's lpq. If there
are no jobs in the queue, ``no entries'' is displayed. If there are jobs in
the queue, the status of the printer indicated by destination-name or
each member of destination-name if it is a group is displayed. Then,
a line is emmited describing each job queued for the destination.
Additional parameters are interpreted as BSD style job numbers and as user
names. If such additional parameters appear, only jobs which match one or
more of them will be displayed. A job number will match any job for which
it equals the numberic portion of the PPR job-id. The way
username
matching is done depends on whether the job is a proxy job. If ppr's
-X switch was used when submitting it, the
username
must match the
portion of the jobs principal id before the first ``@''. If it is not a proxy
job, the
username
must match the user identity as established by ppr's
-f switch and the PostScript ``%%For:'' comment.
The
ppop lpq
command is designed primarily for use with Samba and
lprsrv.
-
ppop progress
job-id
-
This command is new and experimental. It reports the amount of an indicated
job which has been printed. The output is terse because it is intended for
use by GUI front ends.
-
ppop qquery
{destination-name, job_id, all} field1 ... fieldN
-
This command is new and experimental. It is designed for use by programs
such as GUI front ends which might wish to invoke ppop in order to get
information about print queues.
The first parameter is name name of the queue to be listed, the name of a
job to be listed or ``all''.
The output is a table. The columns of the table are separated by tabs. The
second and subsequent parameters are the names of columns desired in the
output. These are the valid column names:
-
jobname
-
The PPR job id. If the subid is zero it is ommited. If the destination
node is this node it is ommited. If the home node is this node it is
ommited. (In the current version of PPR, the last two conditions will
always be true.) A typical jobname will be ``chipmunk-2001''.
-
fulljobname
-
The PPR job id in long form. A typical fulljobname will be
``mouse:chipmunk-2001.0(mouse)''.
-
lpqfilename
-
For jobs received through lprsrv, the name of the origional input file, if known.
If it is unknown, this field will contain the same string as the
title
field. This is the information that the
ppop lpq
command displays in the
``Files'' column.
-
for
-
The DSC ``%%For:'' line data. This is the submitter identification as it
appears in normal queue listings.
-
title
-
The DSC ``%%Title:'' line data.
-
status
-
A string describing the job status. Typical values are ``printing'', "waiting
for printer``, and ''arrested".
-
explain
-
A string which gives furthur information about the job status. If the job
status is ``waiting for media'' then this field will contain a space delimited
list of the required media. If this job status is ``arrested'', this field
may contain the reason. If the job status is ``printing'', the explain field
will contain ``on printer''. There may be other possible values. This
field should be displayed near the ``status'' field.
-
copies
-
The number of copies desired. If the number of copies was not specified
then this field will contain ``1?''. The reflects the fact that the number of
copies is probably 1 but there may be PostScript code which selects a
different number of copies.
-
copiescollate
-
Either ``true'' or ``false'' to indicate whether multiple copies should be collated.
-
pagefactor
-
The number of page descriptions per sheet. For duplex mode this will be 2.
For 4-Up this will be 4. For 4-Up and duplex it will be 8.
-
routing
-
The DSC routing string. If there is not ``%%Routing:'' line in the PostScript
file, this field will be blank.
-
creator
-
The DSC creator string. If there is not ``%%Creator:'' line in the PostScript
file, this field will be blank.
-
nupn
-
The number if page descriptions which will be printed on each side of the sheet.
-
nupborders
-
Either ``true'' or ``false'' to indicate whether borders will be printed
around virtual pages when printing in N-Up mode.
-
sigsheets
-
The number of sheets per signiture when printing in signiture mode, 0 if not
printing in signiture mode.
-
sigpart
-
The part of each signiture which should be printed. The values are
``Fronts'', ``Backs'', and ``Both''. This is specified at the time a job is
submitted by using ppr's -s switch.
-
pageorder
-
The DSC ``%%PageOrder:'' value. The possible values are ``Ascend'', ``Descend'',
and ``Special''.
-
proofmode
-
The DSC ``%%ProofMode:'' argument. The values are ``NotifyMe'', ``Substitute'', and
``TrustMe''. If no ``%%ProofMode:'' line appears in the PostScript file and
ppr's -P switch is not used then the value will be ``Substitute''.
-
priority
-
The current priority of the job. This is a number between 0 and 39
inclusive with lower numbers indicating higher priority. A queued job's
priority number will drop periodically.
-
opriority
-
The job's priority at the time it was submitted. This is a number between 0
and 39 inclusive with lower number indicating higher priority. The default
priority is 20, but other values may be specified with ppr's -q
switch.
-
banner
-
The submitter's stated preference as to banner pages. The possible values
are ``Yes'', ``No'', and ``Unspecified''.
-
trailer
-
The submitter's stated preference as to trailer pages. The possible values
are ``Yes'', ``No'', and ``Unspecified''.
-
inputbytes
-
The number of bytes in the input file if it was not PostScript. If the
input file was PostScript, this value will be 0.
-
postscriptbytes
-
The number of bytes in the input file if it was PostScript, or the number of
bytes in the PostScript filter output if it was not.
-
prolog
-
Either ``true'' or ``false'' to indicate whether a DSC prolog section exists.
-
docsetup
-
Either ``true'' or ``false'' to indicate whether a DSC document setup section
exists.
-
script
-
Either ``true'' or ``false'' to indicate whether DSC comments delineate at least
one page description.
-
orientation
-
The orientation of the document, if known. The values are ``Portrait'',
``LandScape'', and ``Unknown''.
-
draft
-
The `draft' notice. This is a message such as ``Draft'' or ``Confidential''
which is overlaid diagonally on the page.
-
username
-
The name of the unix user who invoked ppr.
-
userid
-
The numberic unix id of the user who invoked ppr.
-
proxy
-
The proxy for string. When a user has submitted a job on behalf of another
user, generally on a remote machine, this field will often contain a string
identifying the user for whom the job was submitted. (This is the value
passed to the ppr -X switch.
-
longsubtime
-
The time the job was submitted.
-
subtime
-
The time the job was submitted in the abreviated format used by B
-
pages
-
The number of page descriptions in the document. (This should not be
confused with the number of printed sides or the number of sheets of paper
that will be used. The value in this field does not take into account the
number of copies to be printed, duplex, or N-Up.)
-
totalpages
-
The number of page descriptions in the document multiplied by the number of
pages. (This field and the two that follow are provided for convenience.
It is possible to derive their values from other fields.)
-
totalsides
-
The number of printed sides in all copies of this document. (That is, totalpages
divided by the N-Up factor and rounded up to the next whole number.)
-
totalsheets
-
The number of sheets of paper which will be used to print this job. (That
is, totalpages divided by the N-Up factor and furthur divided by two for
duplex mode, the whole being rounded up to the next whole number.)
.
-
ppop move
{job-id, destination-name} new_destination-name
-
Move the indicated job or all jobs queued for the destination named in the
first parameter to the destination indicated by the second parameter. An
ordinary user may move any job that belongs to him but may not move all jobs
queued for a destionation.
-
ppop hold
job-id ...
-
Place the indicated job in the ``held'' state. If you hold a job which is
currently being printed then printing will be stopt. Prior to version 1.30
it was not possible to hold a job that was being printed.
-
ppop release
job-id ...
-
Change the state of the indicated job from ``held'' or ``arrested'' to a state
which allows it to print.
-
ppop cancel
{job-id, destination-name, all} ...
-
Cancel the indicated jobs or all jobs owned by the user who runs
ppop
which are queued for the indicated destination or destinations. An operator
may use the -u switch to cancel all jobs queued by another user on the
indicated destination or destinations. It is permissible to cancel a job
which is currently printing. Note that canceling all jobs queued for a
group will not cancel jobs queued specifically for the individual printers
which are members of that group. (Prior to version 1.30,
ppop cancel
destination-name performed the action that is now performed by Bdestination-name.)
-
ppop scancel
{job-id, destination-name, all} ...
-
Just like
ppop cancel
except it does not notify the owners of
the canceled jobs
-
ppop purge
{destination-name, all} ...
-
This command may be used by an operator to delete all jobs from the
indicated queues or from all queues if the special destination name ``all'' is
used. Note that canceling all jobs queued for a group will not cancel jobs
queued specifically for the individual printers which are members of that
group. (Prior to version 1.30, this function was performed by Bdestination-name.)
-
ppop spurge
{destination-name, all} ...
-
Just like
ppop purge
except it does not notify the owners of the
canceled jobs.
-
ppop cancel-active
{destination-name, all} ...
-
Cancel any jobs queued for the indicated destination or destinations that are
printing.
-
ppop cancel-my-active
{destination-name, all} ...
-
Cancel any jobs queued for the indicated destination or destinations that
are printing and are owned by the invoking user. If a proxy-for string is
specified with the -X switch, it must match the job too.
-
ppop clean
{destination-name, all} ...
-
This cammand may be used by an operator to delete all arrested jobs in the
indicated queue or queues. The special queue name ``all'' may be used to
delete all arrested jobs from all queues.
-
ppop rush
job_name ...
-
Move the indicated job or jobs to the head of the queue. This command will
not interrupt any currently printing job, is simply moves the indicated jobs
to the head of their queues so that they will be started as soon as
the printer or one of the group's member printers becomes idle.
-
ppop log
job_name
-
Display the log of the indicated job. This log will include DSC comment
warnings if the ``-w log'' switch was used when ppr was invoked and it will
include any messages received from the printer while the jobs was being
printed. If a banner or trailer page is printed, the contents of the log
are printed on it and the log is deleted. The log is deleted when a job is
removed from the queue. Also, if a job is arrested because the printer is
incapable of printing it, the log will contain messages indicating the
precise reason.
.
-
ppop status
{destination-name, all}
-
Display the status of the indicated printer, or, if destination-name is a
group, all printers in the indicated group, or, if ``all'' is used, all
printers known to PPR.
-
ppop message
printer
-
This command is new and experimental. It is designed for use by
programs which might wish to read the last error message received from
a printer. This command will eventually be documented in an appendix of
PPR, a PostScript Print Spooler.
-
ppop start
printer ...
-
Start a printer or printers which were previously stopt, are in an error
state, or in the otherwise engaged state.
-
ppop stop
printer ...
-
Stop the indicated printer or printers as soon as the current job (if any)
is done printing.
-
ppop wstop
printer
-
Stop the indicated printer as soon as the current job (if any) is done
printing. Does not return until the printer is stopped. Good for use in
shell scripts when the next operation (such as changing the mounted media)
can not be done until the printer has stopt.
-
ppop halt
printer ...
-
Stop the indicated printer or printers immediately, aborting printing of any
jobs currently being printed. A job whose printing is aborted is returned
to the queue and will start again from the begining as soon as a printer
becomes available. This means that if the job was submitted to a group and another
member of the group is idle, one of the idle printers will immediately begin
printing it.
-
ppop alerts
printer
-
Display the most recent alert messages concerning the indicated printer.
By ``recent'' we mean that this log is cleared and started over when an
alert is posted and the previous alert was posted more than one hour before.
In such a case, the previous alert presumably was the result of another
problem.
.
-
ppop media
{destination-name, all}
-
Display the name of the media mounted on each input bin of the indicated
printer, or, if destination-name is a group, each member of the
indicated group, or, if ``all'' is used, all printers on the system.
-
ppop mount
printer bin media
-
Mount the indicated media on the indicated bin
of the indicated printer. All of the parameters are case sensitive.
In general, a job which requires a specific type of media will not be
printed until that media is mounted on one or more bins.
The first exception to this rule occurs when a printer has no bins in its
bin list. In this case, it will print any job immediately without regard
to the job's media requirments.
The second exception is the bin name ``AutoSelect'' which has a special
status. Regardless of what media is mounted on it, all jobs will be printed
immediately even if the proper media is not explicitly mounted. Pages which
require a media which is not among those explicitly mounted will be directed
to the AutoSelect bin.
.
This command writes to the spooler communications FIFO
/var/spool/ppr/PIPE. It also uses temporary files in /var/tmp.
Exit codes for ppop(1) are defined in the source file
include/util_exits.h.
ppr(1), pprd(8), ppad(8)
``PPR, a PostScript Print Spooler'', ``Installing and Using PPR''.
PPR was written at Trinity College during 1993, 1994, 1995, and 1996. It
was first released to the public on 26 April 1995.
David Chappell, Trinity College Computing Center, Hartford, Connecticut.