Provided by: gnuspool_1.7_amd64 bug

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.