SLGetQueue(3) Impressario SLGetQueue(3)NAMESLGetQueue - reports the printer queue contents
SYNOPSIS
#include <spool.h>
int SLGetQueue(const SLPrinterStruct *printer_info,
int queue_type,
SLQueueStruct *queuep[],
int *num_queuep);
DESCRIPTIONSLGetQueue returns a list of the jobs on the queue for the specified
printer. The function uses the current default spooling system.
The printer_info parameter specifies the printer whose queue is to be
reported. Note that this parameter is a pointer to an SLPrinterStruct
structure and not a printer name. This is because SLGetQueue requires
information available in the structure to properly locate and read the
printer queue. A NULL printer_info parameter is illegal and will return
an error. Values for this parameter can be obtained directly from the
printer list returned by the SLGetPrinterList(3) function.
queue_type specifies the type of queue to obtain. The value of this
parameter is used only for networked printers under the System V spooler.
Under the System V Release 3 spooling system there are two queues for a
networked printer, the queue on the local machine and the queue on the
remote machine. queue_type specifies which of these two queues should be
read and provides the capability to merge the two queues into one list.
The possible values for queue_type are:
SL_QUEUE_LOCAL Obtain the network printer queue on the local
machine.
SL_QUEUE_REMOTE Obtain the network printer queue on the remote host
machine.
SL_QUEUE_MERGED Merge the local and remote printer queues into one
list. If a print job appears in both the local and
remote printer queues, only the local job will be
listed.
queuep is set by the function to point to a list of SLQueueStruct
structures. These structures contain detailed information about each job
in the printer queue. num_queuep is set to the number of jobs in the
queue list.
The SLQueueStruct is defined as:
typedef struct _slQueueStruct {
char *job_id; /* Job ID */
char *username; /* Job owner's user name */
Page 1
SLGetQueue(3) Impressario SLGetQueue(3)
char *title; /* Print job title, or name */
/* of first file in request */
unsigned int size; /* Size of the job in bytes */
unsigned int is_local: 1; /* 1 == job is in the local */
/* queue (Sys V only) */
unsigned int _padding: 31; /* Unused - for alignment */
time_t time_stamp; /* Submittal time */
} SLQueueStruct;
RETURN VALUE
0 is returned if execution was successful. -1 is returned and SLerrno is
set if an execution error has occurred.
EXECUTION ERROR CODESSLGetQueue will fail under the following 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_SPOOLER_ERROR A printer spooling system error has occurred.
SL_ERR_BAD_PRINTER_STRUCT
An invalid printer structure has been specified.
SL_ERR_REMOTE An error has occurred while attempting a remote
shell execution (rsh). This error could be
caused by transitory network problems. The
function call should be retried.
WARNING
A pointer to queuep obtained by a previous call to SLGetQueue will be
invalid after subsequent calls to the function. The contents of the queue
list queuep must be copied to be preserved. Note that the character
string fields of the structure must be duplicated in any copy operation
since these pointers also become invalid.
NOTES
All mention of "fields" refers to the fields of the SLQueueStruct
structure.
1. Under the BSD spooling system the time_stamp field will be set to
the 0.
2. The queue_type parameter is only used by the System V spooling
system when a networked printer is specified. In all other cases the
value of this parameter is ignored.
Page 2
SLGetQueue(3) Impressario SLGetQueue(3)
3. 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.
4. Under System V spooling SLGetQueue must perform network command
execution to obtain queue information for a remote printer. If a
connection to the remote machine cannot be established SLGetQueue
will return an error indication and set SLerrno to SL_ERR_REMOTE.
Upon receiving this error, an application should retry the call a
number of times to ensure that the failure is not due to a
transitory network problem.
5. Under System V spooling SLGetQueue must perform network command
execution to obtain queue information for a remote printer. Remote
command execution is attempted as the user 'lp'. Normally, the lp
account will not have a passwd and access is freely granted. If an
installation protects the lp account with a password and uses the
rhosts mechanism, SLGetQueue will fail to get permission to access
the remote queue. An example of how an application might handle
this situation is to run as a setuid lp program and bracket its
calls to SLGetQeueue with the setreuid(2) and setregid(2) functions.
For example, assume that the following code is executed by a program
that has uid=joe and euid=lp.
/* Swap uid with euid and gid with egid.
Thus uid=lp and euid=joe
*/
setreuid(geteuid(), getuid());
setregid(getegid(), getgid());
/* Get the remote queue as lp */
SLGetQueue(prptr, queue_type, &queue, &numjobs);
/* Swap everything back. Thus uid=joe and euid=lp */
setreuid(geteuid(), getuid());
setregid(getegid(), getgid());
6. The title field will be NULL if libspool was unable to determine the
title of a print job.
SEE ALSOSLGetPrinterList(3), SLSubmitJob(3), SLPerror(3), libspool(3)time(2),
ctime(3), setreuid(2), setregid(2)
Page 3
