Provided by: gnuspool_1.7ubuntu1_amd64 
NAME
gspl-pr - print spooler
gspl-rpr - print spooler to remote queue
SYNOPSIS
gspl-pr [ -options ] [ file ... ]
gspl-rpr [ -options ] [ file ... ]
DESCRIPTION
gspl-pr queues up one or more print jobs for the GNUspool spooler.
gspl-rpr queues up one or more print jobs to a remote queue running the GNUspool spooler.
GNUspool does not need to be running on the submitting machine; only the message file and
hosts file are required.
If one or more files are specified, each file is treated as a separate spool job, with a
title constructed from the file name. If no files are specified gspl-pr and gspl-rpr read
from the standard input instead. In this case the job is placed on the queue with a blank
title unless otherwise specified.
The standard default options are to print one copy, preceded by a banner page, with the
priority, printer and form types specified for the user. The standard banner page will
contain: the user name and job title (in large characters), the name of the user who
submitted the job (if different), the job number, its size and priority.
Other default options may be set up using environment variables "GSPL_PR" for gspl-pr and
"GSPL_RPR" for gspl-rpr and/or .gnuspool files. Any defaults may be overridden by re-
specifying that option on the command line.
OPTIONS
Note that the order of treatment, letters and keywords described below may be modified by
editing the file rest.help - see spsyntax(5). The environment variable on which options
are supplied is "GSPL_PR" for gspl-pr and "GSPL_RPR" for gspl-rpr and the environment
variable to specify the help file is "SPRESTCONF" in both cases.
-? or +explain
causes a summary of the other options to be displayed without taking further action.
-a or +mail-attention
requests that a message be sent in the mail to the user if a job is awaiting
attention, either because it reaches the top of the queue and the required form type
is currently unavailable or because the form requires alignment.
-A or +write-attention
requests that a message be sent to every terminal at which the user is logged in, or
by mail otherwise if the user is not logged in, if a job is awaiting attention, either
because it reaches the top of the queue and the required form type is currently
unavailable or because the form requires alignment.
-b or +noatt-message
turns off any job attention messages previously requested.
-c n or +copies n
sets the number of copies to be printed to n, which may possibly be zero.
The maximum number of copies at a time may be restricted to a number for each user
such as 10. See the output from gspl-user(1) for information on the maximum number of
copies.
-C nnnn or +classcode nnnn
where nnnn is some collection of the letters "A" through to "P" inclusive (upper or
lower case) with "-" to indicate ranges, requests that the job be given the specified
class code.
The class code of a job may restrict which printers the job may be printed on, or
which other users can display details of the job.
In normal circumstances (except where the user has override class privilege), the
specified class code is reduced to the intersection of (i.e. is "anded" with) the
specified class code and the user's own class code.
-d or +delimiter-number
is used in conjunction with the -Dstring option to specify that a page is to be
considered complete after reading n delimiter strings. The default value is 1.
-D string or +delimiter string
specifies an alternative delimiter to the default of formfeed as being the end of a
page. If a number is given using the -dn option, then the page is considered ended
after that number of occurrences of the delimiter.
The string given may contain standard constructs such as
\n
\r
\t
etc to denote linefeed, carriage return etc. Remember that when the job is printed,
the printer's setup file may re-specify the delimiter, which will replace the
delimiter specified by these options.
-E n or +external-system n
(gspl-pr only) Used internally to signify originating system type. n may be a number,
or the name of a system type given in gnuspool.ext. This option may only be used by
"root" or "spooler" regardless of other privileges set, as it is intended for use by
xtlpd to set parameters on incoming jobs. Any errors in this parameter, including
permissions, are silently ignored.
-f string or +formtype string
specifies that the supplied form type (with optional suffix introduced by ""."" or
""-"") is used. Note that not all users may be allowed to select form types other some
pattern, causing the job to be rejected.
-F string or +post-proc-flags string
causes the specified string to be passed as the value of the environment variable
"SPOOLFLAGS" to any program invoked at the time the job is printed. This might be as a
post-processing filter command, or alternatively some shell command invoked as (for
example) a "docstart" string.
-h string or +header string
supplies string as the title for each job, otherwise it is derived from the file name
specified. The title appears on the banner page, if this is printed.
-i or +interpolate
causes any file name suffixes .c, .o etc of the files from which jobs are created, to
be appended to the form type, unless it already has a suffix, for example:
gspl-pr -i -f a4 x.c y.ps
would submit jobs using the files x.c and y.ps with form types "a4.c" and "a4.ps"
respectively.
-I or +no-interpolate
cancels any previously-specified -i option.
-j n or +job-wait-time n
is relevant only if input to gspl-pr or gspl-rpr is from a pipeline as in
program|gspl-pr ....
This causes a job to be submitted if no data is received over the pipe for n seconds.
gspl-pr or gspl-rpr will still wait, and may submit any number of subsequent jobs
until the pipe is closed by the program generating the output.
Note that nothing can be done by gspl-pr to guess at what output might appear
(possibly halfway through a line) if the program writing to the pipe does not flush
its output buffer after each occasion that it writes something.
Specify a parameter of zero to cancel any previous -j option, if required.
-l or +local-only
in a networked environment requests that the job be printed only on the printers local
to the machine at which the job is submitted.
-L or +network-wide
cancels the request that the job or jobs be printed only on printers local to the
machine at which the job is submitted.
-m or +mail-message
requests a message to be sent in the mail to the user on completion or termination of
the job.
-n nn or +delay-for nn
specifies that the job should be held on the queue for at least nn minutes from the
current time before being printed. The time may alternatively be specified as hh:mm or
as hh:mm:ss, specifying a delay in hours and minutes, or hours, minutes and seconds.
-N time or +delay-until time
is an alternative to the -nnn option to specify the earliest time at which the job is
to be printed. The argument may be hh:mm or hh:mm:ss to give the time of day in
24-hour clock notation. If the time has passed, then tomorrow is assumed.
Alternatively a date and a comma may be prefixed to the time in the form mm/dd or
dd/mm depending upon the local convention for date format used. Thus the resulting
argument might be
10/11,12:30
-o host or +originating-host host
(gspl-pr only) Used internally to signify originating host name, in place of the local
host. The host name given should appear in the host file gnuspool.hosts, possibly with
the "external" keyword. This option may only be specified by spooler or root users,
but is silently ignored in other cases as are all other errors. It is intended for use
by xtlpd(8) to set parameters on incoming jobs.
-O flag or +odd-even-flags flag
where flag is one of O, E, A, B or - (the letters may be upper or lower case), cause
odd or even-numbered pages to be skipped. or - to reset this flag.
O causes odd-numbered pages not to be printed.
E causes even-numbered pages not to be printed.
A and B are useful if more than one copy is to be printed.
A causes even-numbered pages not to be printed on odd-numbered copies, and odd-
numbered pages not to be printed on even-numbered copies.
B is the other way around.
If you do not understand this, all you have to do is remember that
gspl-pr -c2 -OA ....
prints all the odd-numbered pages followed by all the even-numbered ones.
For this to work properly, page delimiters must be set appropriately.
-p n or +priority n
specifies the priority of the job, between 1 (lowest) and 255 (highest) or some
narrower range to which the user is limited.
Increasing the priority of a job increases its chances of being printed earlier than
it otherwise would be whilst increasing the charge applied to the user in a non-linear
fashion.
-P name or +printer name
specifies that the job is to be sent to a printer with the name given, as opposed to
printing it on the first available printer with the given form type. name may be a
pattern to select any printer matching the pattern.
A user may be limited to a range of printers which must be a superset of name.
To "turn off" a printer name previously specified by a preceding -Pname option, put a
single - sign as the printer name.
-q or +retain
requests that the job or jobs be retained on the queue with copies set to zero after
printing, for explicit deletion, or automatically at the expiry of the timeout (as set
by the -tn option).
-Q hostname or +host hostname
send the job or jobs to the given hostname. Note that hostname must be in
gnuspool.hosts on the submitting machine and the submitting machine's hostname must be
in gnuspool.hosts on the receiving machine.
If supplied to gspl-pr it will re-invoke gspl-rpr with the same command-line options.
It is, however, required for gspl-rpr, which will not try to invoke gspl-pr if it is
not supplied (as that could loop endlessly, this could happen if the -Q option was in
a .gnuspool file for gspl-pr but not in one for gspl-rpr).
-r or +banner
restores banner pages previously suppressed using -s.
Note that some form types may be set up never to use banners regardless of this
option.
-R m-nor +page-range m-n
Specifies that pages m through to n inclusive are to be printed. This does of course
assume that the job has recognisable pages. If m or n are omitted, then "the
beginning" or "the end" respectively is assumed, so "-R 3-5" would print pages 3 to 5,
"-7" would print pages 1 to 7 inclusive, and "-R 4-" would print page 4 to the end
inclusive. "-R 1-" would turn this option off by selecting 1 to the end.
-s or +no-banner
suppresses any banner page (large letter user name etc) which is printed before the
job itself.
Note that some form types may be set up always to print banners regardless of this
option.
-t n or +printed-timeout n
specifies that if retained on the queue (either because of the -q option, or because
the setup file has the "retain" keyword as described in the system reference manual on
printer setup files), the job will be deleted automatically after n hours. The default
value is 24 hours, and the maximum value is 32767 hours (nearly 4 years).
-T n or +not-printed-timeout n
specifies that if held on the queue without being printed, the job will be deleted
automatically after n hours. The default value is 168 hours (1 week), and the maximum
value is 32767 hours (nearly 4 years).
-u name or +post-user name
requests that the specified user name be substituted for the submitting user on the
banner page optionally printed at the start of the job. The job still remains the
responsibility of the submitting user.
To "turn off" a user name specified in a previous -uname option, put a single - sign
as the user name.
The user name must exist on the machine to which the job is queued, but this will be
ignored if not.
-U user or +originating-user user
(gspl-pr only) Used internally to signify originating user name. This may only be
specified by users "spooler" and "root" to have any effect, otherwise the option is
silently ignored, as are all errors. It is intended for use by xtlpd(8) to set
parameters on incoming jobs.
-v or -V or +toggle-verbose
alternately with successive uses turns on or off the verbose switch. This causes job
number information to be output on standard error when job are submitted.
+verbose
turns on the verbose switch. There is no default letter option (however it is possible
to create one by editing the message file).
+no-verbose
turns off the verbose switch. There is no default letter option (however it is
possible to create one by editing the message file).
-w or +write-message
requests a message to be sent to every terminal at which the user is logged in, or by
mail otherwise if the user is not logged in, when the job is completed or terminated.
-x or +no-message
turns off any job completion messages previously requested with -m or -w
-z or +no-retain
cancels a request that the job or jobs be retained on the queue after printing.
-Z limit or +job-size-limit limit
limit the size of jobs to limit. limit may be a number, giving a size in bytes, or it
may be suffixed with P to indicate a number of pages.
If a job exceeds the limit it is truncated with a warning message, but a job is still
created. If the limit is prefixed with an E, then the warning becomes an error, and no
job is created.
Supply an argument of a single - to turn off this option.
+freeze-current
Save all the current options in a .gnuspool file in the current directory. This will
supply defaults for further gspl-pr or gspl-rpr commands invoked subsequently when
started from the directory.
Note that no job will be expected from standard input if no files are specified after
including this option.
+freeze-home
Save all the current options in a .gnuspool file in the user's home directory. This
will supply defaults for further gspl-pr or gspl-rpr commands invoked subsequently.
Note that no job will be expected from standard input if no files are specified after
including this option.
FILES
~/.gnuspool configuration file (home directory)
.gnuspool configuration file (current directory)
rest.help message file
ENVIRONMENT
GSPL_PR
space-separated options to override defaults for gspl-pr.
GSPL_RPR
space-separated options to override defaults for gspl-rpr.
SPRESTCONF
location of alternative help file.
NOTES
N.B. Please note that from release 23 the scheduler spshed(8) is no longer automatically
started if it is not running -- use gspl-start(1).
Messages via terminal and e-mail
You can have a message sent to your terminal or receive mail in two circumstances.
1. When your job has:
a. Completed normally
b. Been manually deleted (using gspl-pq(1) etc).
c. Been automatically deleted after remaining on the queue for a specified time as
specified using the -t or -T options.
d. Been aborted during printing.
2 When your job reaches the top of the queue and:
a. It has been selected for printing, but operator attention is required for:
i. Approval of an alignment page
ii. Confirmation to proceed in single job operation
b. It has not been selected for printing because no printer is available with the
selected form type loaded.
The option -w causes a message to be sent to your terminal, and the option -m causes you
to be sent mail in one of the first set of circumstances. If neither is specified, you
should still receive mail if a filter process produces output on standard error or
terminates abnormally, or if a job is automatically deleted. (Do not forget you can
override the "MAILER" program to change this behaviour if required as described in the
Reference Manual).
The option -A causes a message to be sent to your terminal, and the option -a causes you
to be sent mail in the second set of circumstances.
If any of these are set in the environment and you don't want them, you may suppress them
on the gspl-pr command line using -x to turn off both the -w and -m options, and -b to
turn off the -A and -a options.
If your terminal cannot be written to, or you have logged out when a message to your
terminal is invoked, it will be diverted to the mail program instead.
Queue Timeouts.
When the gspl-pr or gspl-rpr command receives its data on standard input from a pipe, or
terminal device, the job is not normally submitted until an end-of-file indication is
encountered. This is typically caused by the termination of the process writing to the
pipe, or by typing the end-of-file character (often ctrl-D) when input is being taken from
a terminal.
In some circumstances the process writing to the pipe may never finish, or the terminal
being read from may not be being accessed by a human, but the user may wish to proceed
anyway with printing.
The -j option provides a wait timeout in seconds. If some characters have been received,
the timeout is set before reading more characters. If the timeout expires before any more
characters are read, then a job is created using the characters received so far and gspl-
pr or gspl-rpr restarts, possibly making further jobs if more characters arrive.
This cannot be ideal in the case of pipes without some co-operation from the sending
process; this is because if stdio (i.e. the C library functions "printf" etc, which is
also used by many other languages and applications) then the output is usually "buffered"
in 1024-byte chunks, and thus up to 1023 bytes of the last part of the output will not be
written out to the pipe until the sending process decides to send some more or terminates,
and therefore all but the last of the jobs created by use of this option may be "short" by
up to 1023 bytes.
If the sending process is a 'C' program or other program which the user has access to,
then the user should ensure that the routine "fflush" is used after every block of
output, thus:
printf("Totals for......\n";, ....);
fflush(stdout);
Alternatively, the routine "setbuf" should be invoked to reduce the buffering on standard
output.
If the user does not have any access to the sending process this option may have
undesirable effects at "the seams" of the various jobs due to this buffering. The only
successful approach would be to insert a filter process in between gspl-pr and the sending
process to ensure that complete pages only were passed through to gspl-pr. It is
considered unacceptable to monopolise a printer on speculation that further data may
arrive.
A parameter of zero turns off the -j option if it has been set in an environment variable
or .gnuspool file.
Delay times.
The -n and -N options provide for the job to be held unprinted on the queue for, or until,
a specific time.
The -n option provides a time interval to be held for, in minutes, in hours and minutes,
or in hours, minutes and seconds. The following examples all specify the same time
interval of 1 hour and 30 minutes. If no colon appears, a time period of minutes is
assumed:
-n 90
-n 1:30
-n 1:30:00
The -N option provides an explicit time and possibly a date to be held until. The time may
be specified as a 24-hour clock time with optional seconds thus
-N 16:35
-N 04:28:32
In these cases the given time in the next 24 hours is taken to be the required time. If a
different date is required this can be put in front of the time in the format yy/mm/dd
with a comma thus:
-N 91/2/12,12:30
The year may be omitted, and the date will be taken as a future date. The date will be
taken as dd/mm for timezones less than 4 West, otherwise mm/dd.
This allows the printing of long jobs to be printed at a quiet time, overnight for
example. Alternatively specifying a delay time can provide an opportunity for thought and
possible amendment before continuing.
Environment selection of gspl-pr and gspl-rpr options.
In common with all GNUspool programs, a configuration file mechanism applies to gspl-pr
and gspl-rpr.
The environment variable "GSPL_PR" may be used to contain options for gspl-pr and the
environment variable "GSPL_RPR" may be used to contain options for gspl-rpr, and the
.gnuspool files may contain the keyword "GSPL_PR" or "GSPL_RPR" to select options without
having to specify them on the command line.
This enables you to specify, for example, that you always want the -v (job confirmation)
option, or that when in certain directories, you always want to use the form type
"letterhead", or "invoices", or perhaps 2 copies.
Saving current gspl-pr or gspl-rpr options
The special options "+freeze-current" and "+freeze-home" cause the currently selected set
of options to be saved in .gnuspool files in the current directory or home directory
respectively. Either or both may be specified.
If no file arguments are given to gspl-pr or gspl-rpr when one or both of these keywords
are specified, then the program will not expect to find data on the standard input. If
file arguments are given, then the ".gnuspool" file or files are saved before the file
arguments are processed. If the ".gnuspool" file cannot be saved, perhaps because the
access permission to the current directory is inappropriate, the jobs files specified will
still be queued, the program will not fatally abort.
Interaction of gspl-pr and gspl-rpr
If the -Q option is given to gspl-pr, either on the command line or in the environment or
.gnuspool files, then gspl-rpr will be invoked with the same command line options (but
gspl-rpr will accept its own "GSPL_RPR" environment variable or .gnuspool file options).
Gspl-Rpr, however, will not invoke gspl-pr if the -Q option is not given; this is an
error. Remember that the -Q option could be set from a "GSPL_PR" definition in a .gnuspool
file, but without a -Q option on an "GSPL_RPR" definition, this would mean that gspl-rpr
did not get invoked with a -Q option, so this could give an infinite loop.
SEE ALSO
spsyntax(5), gnuspool.conf(5), gnuspool.hosts(5).
DIAGNOSTICS
Various diagnostics are read and printed as required from the message file, by default
rest.help.
COPYRIGHT
Copyright (c) 2009 Free Software Foundation, Inc. This is free software. You may
redistribute copies of it under the terms of the GNU General Public License
<http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by
law.
AUTHOR
John M Collins, Xi Software Ltd.