16.2. Filter Exit Codes

When a filter exits, the exit code value is used by the parent process to determine what actions to take. Since filters are used in several places in the printing process, not just to do format conversion, there is a large number of recognized exit values.

    Key      Value   Meaning
    JSUCC    0       Successful
    JFAIL    1, 32   Failed - retry later
    JABORT   2, 33   Abort - terminate queue processing
    JREMOVE  3, 34   Failed - remove job
    (Unused) 4, 35   (Unused)
    (Unused) 5, 36   (Unused)
    JHOLD    6, 37   Hold this job - reprint later
    JNOSPOOL 7, 38   No spooling to this queue
    JNOPRINT 8, 39   No printing from this queue
    JSIGNAL  9,  40   Killed by unrecognized signal
    JFAILNORETRY 10, 41 Failed, no retry
    Other            Abort - terminate queue processing


16.2.1. JSUCC

A zero or JSUCC exit value always indicates success; a non-zero exit value indicates failure or a problem condition and requires special handling by the parent process.

16.2.2. JFAIL

When printing or performing some action that can be repeated, such as connecting to a remote printer, a 1 or JFAIL status indicates a transient failure condition. Depending on various configuration options, the printing or other operation can be retried.

16.2.3. JABORT

The 2 or JABORT is a more serious error, and indicates that there is no expectation that the operation would succeed if retried. It may also indicate that no other similar operation should be performed. Jobs whose print filters exit with JABORT are usually unprintable, and by default are removed from the print queue.

16.2.4. JREMOVE

The JREMOVE status indicates that the job should be removed from the print queue. This is a refinement of the JFAIL and JABORT status. The job is usually unconditionally removed from the print queue, even if it is normally kept in the queue for reprinting. This status is usually returned by filters which are responsible for permission checking and is returned when the user has no permission to print.

16.2.5. JHOLD

The JREMOVE status indicates that the job should be held and reprinted at a later time. This status is returned by various filters during the processing of a job, and usually indicates that the resources needed for a job are not available. Held jobs need to be explicitly released by the administrator.

16.2.6. JNOSPOOL and JNOPRINT

The JNOSPOOL and JNOPRINT are used as part of the management of load balancing queues and the check idle filter. LPRng has the ability to run a program to check to see if a spool queue is available for printing on a dynamic basis. If the filter that does this checking exits with JNOSPOOL or JNOPRINT then jobs should not be sent to the spool queue.

16.2.7. JSIGNAL

This status is usually returned when the exiting process is terminated by a signal or abort, and does not exit using the exit facility. It is usually handled like a JABORT exit status, and is the indication of a severe and possibly non-restartable system failure.

16.2.8. JFAILNORETRY

This code is used under an extremely odd set of circumstances and was used to support a sophisticated print retry system.

Normally when a print filter or other filter returns this code, it is treated as JFAIL. The job is marked as having an error condition and is not immediately retried. Other jobs can then be tried for printing in the queue. It is not removed from the print queue, but marked as unprintable.

When a round-robin retry print scheduling algorithm is used, if there are no other jobs available for printing then the jobs that failed with JFAILNORETRY are retried. Thus, jobs that are submitted go to the head of the queue for printing, and jobs that are pending for repeat are printed after them. This algorithm is deprecated, and that the details of this algorithm are undocumented.

16.2.9. Other Values

If a filter exits with other than the indicated value, or a value inappropriate for its purpose, then the result is treated like JABORT.