SLSubmitJob(3)
SLSubmitJob, SLSubmitJobFd, SLSubmitJobBuf, SLSubmitJobSimple - submit a job for printing
As shipped in IRIX 6.5.30. Unchanged since IRIX 6.5.
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. 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 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. 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 ALSO SLCancelJob(3), SLGetQueue(3), SLPerror(3), libspool(3), lp(1), lpr(1) time(2), ctime(3)