SLSubmitJob(3) Impressario SLSubmitJob(3)NAME
SLSubmitJob, SLSubmitJobFd, SLSubmitJobBuf, SLSubmitJobSimple - submit a
job for printing
SYNOPSIS
#include <spool.h>
SLPrintJob* SLSubmitJob(const char *filename,
const char *printer,
int num_copies, int copy,
int mail, const char *title,
const char *options);
SLPrintJob* SLSubmitJobFd(int file_desc, const char *printer,
int num_copies, int copy,
int mail, const char *title,
const char *options);
SLPrintJob* SLSubmitJobBuf(const void *buffer, size_t amount,
const char *printer, int num_copies,
int copy, int mail, const char *title,
const char *options);
SLPrintJob* SLSubmitJobSimple(const char *filename);
DESCRIPTION
SLSubmitJob submits a file to be printed using the current default
spooling system.
SLSubmitJobSimple also submits a file for printing but uses default
values for all printing options.
SLSubmitJobFd submits the contents of the file specified by a file
descriptor for printing.
SLSubmitJobBuf submits the contents of the specified buffer for printing.
filename Specifies the pathname of the file to be printed. This
string can specify multiple files by separating the
filenames with one or more whitespace characters. Wildcard
characters may be used but shell job control meta
characters such as ";" and "&" must not be used. Note
that it is the responsibility of the caller to verify that
filename does not contain characters that would be
interpreted as job control meta characters. libspool does
not perform this verification.
file_desc Specifies a file descriptor open for reading.
buffer Specifies a buffer to be printed.
Page 1
SLSubmitJob(3) Impressario SLSubmitJob(3)
amount Specifies the number of bytes in buffer.
printer Specifies the name of the printer on which the job is to
be printed. If printer is NULL, the default printer for
the current spooling system is used.
num_copies Specifies the number of copies of the job that are to be
printed. The value specified must be greater than 0.
copy If set to 1, this parameter specifies that the file to be
printed should be copied to the spooling directory for the
destination printer. If set to 0, a link will be created
in the spooling directory pointing to the real file. If a
link is created, the user should not change or delete the
file until it has been printed.
mail If set to 1, this parameter indicates that mail should be
sent to the user upon completion of printing. If set to 0,
no mail will be sent.
title Specifies a title to be printed on the banner page of the
print job. If set to NULL, the system dependent default
title, if any, will be printed.
options The file(s) specified to this function are submitted to
the spooling system print command corresponding to the
current default spooling system. For System V, SLSubmitJob
executes lp(1) and for BSD, the function executes lpr(1).
Each of these spooling system commands allows option flags
and parameters not covered by the SLSubmitJob formal
parameter list. The options string provides the means to
pass parameters that are spooling system specific. The
string specified is passed unchanged to the appropriate
spooling system print command. If there are no options to
be passed to the spooling system, this parameter can be
set to NULL.
The SLSubmitJobSimple function uses the following default printing
options:
Printing Option Default Value
___________________________________________
Printer Default printer
Number of copies 1
Copy or link file Link
Send mail on completion No mail
Title None
Spooler dependent options None
Page 2
SLSubmitJob(3) Impressario SLSubmitJob(3)RETURN VALUE
If an error has occurred during execution of the function, NULL is
returned. If execution was successful, a pointer to a SLPrintJob
structure is returned. This structure contains detailed information about
the print job. The SLPrintJob structure is defined as:
typedef struct _slPrintJob {
unsigned int spooler; /* Spooling system for job */
/* e.g. SL_SPOOLER_BSD */
char *printer; /* Local name of printer */
char *filename; /* File(s) to be printed */
char *username; /* Job owner user name */
char *job_id; /* Job ID, where available */
time_t time_stamp; /* Time when submitted */
} SLPrintJob;
EXECUTION ERROR CODES
All job submittal functions will fail under the following general
circumstances.
SL_ERR_FIND_SPOOLER An error occurred while attempting to determine
the available printer spooling systems.
SL_ERR_NO_SPOOLERS There are no printer spooling systems available.
SL_ERR_NO_DEF_PRINTER There is no default printer registered with the
printer spooling system.
SL_ERR_SPOOLER_ERROR A printer spooling system error has occurred.
SL_ERR_BAD_PRINTER_NAME The printer name specified is either an empty
string (""), or a string consisting entirely of
whitespace.
In addition to the general circumstances, SLSubmitJobSimple and
SLSubmitJob will fail under the following circumstances.
SL_ERR_NO_FILENAME The filename specified is either a NULL pointer,
an empty string ("") or a string consisting
entirely of whitespace.
SLSubmitJob, SLSubmitJobFd and SLSubmitJobBuf will fail if the following
problems are detected in the job submittal options.
SL_ERR_NUM_COPIES An invalid number of copies to print has been
specified.
SL_ERR_JOB_COPY An invalid job copy/link parameter has been
specified.
Page 3
SLSubmitJob(3) Impressario SLSubmitJob(3)
SL_ERR_MAIL An invalid mail parameter has been specified.
SLSubmitJobFd will fail if:
SL_ERR_BAD_FD An invalid file descriptor has been specified.
and SLSubmitJobBuf will fail if:
SL_ERR_BAD_BUF An invalid buffer pointer or buffer size has
been specified.
WARNING
The print job pointer returned by the functions points to static storage
within libspool. Subsequent calls to the functions will change the
contents of the job structure. To preserve a job structure, copy the
structure and contents to a user buffer.
NOTES
All mention of "fields" refers to the fields of the SLPrintJob structure.
1. Under the BSD spooling system, the job_id field will be set to
NULL. To determine the job ID under BSD spooling, the printer queue
must be examined manually.
2. Under System V spooling, the job_id field will be set to NULL if the
-s flag is passed using the options parameter.
3. The username field contains the name of the user submitting the job
based on the real user id, not the effective user ID. This is
because the spooling system determines job ownership based on real
user ID.
4. The time_stamp field contains the value returned by the time(2)
function. Refer to the time(2) and ctime(3) man pages for
information about the time value and how it may be converted to a
time string.
SEE ALSOSLCancelJob(3), SLGetQueue(3), SLPerror(3), libspool(3), lp(1), lpr(1)time(2), ctime(3)
Page 4
