SLGetQueue(3)
SLGetQueue - reports the printer queue contents
As shipped in IRIX 6.5. First release of IRIX 6.5.
NAME SLGetQueue - reports the printer queue contents SYNOPSIS #include <spool.h> int SLGetQueue(const SLPrinterStruct *printer_info, int queue_type, SLQueueStruct *queuep[], int *num_queuep); DESCRIPTION SLGetQueue 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 */ 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 CODES SLGetQueue 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. 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 ALSO SLGetPrinterList(3), SLSubmitJob(3), SLPerror(3), libspool(3) time(2), ctime(3), setreuid(2), setregid(2)