=head1 NAME

gspool_joblist - get a list of jobs

=head1 SYNOPSIS

=for man
\&\fB#include <gspool.h>\fR
.PP

=for html
<STRONG>#include &lt;gspool.h&gt;</STRONG>
<br>

B<int gspool_joblist(const int> I<fd>B<, const unsigned>
I<flags>B<, int *>I<numjobs>B<, slotno_t **>I<slots>B<)>

=head1 DESCRIPTION

The B<gspool_joblist()> function is used to obtain a list of jobs.

I<fd> is a file descriptor previously returned by B<gspool_open>

I<flags> is zero, or a logical OR of one or more of the following values

=over 4

=item GSPOOL_FLAG_LOCALONLY

Ignore remote printers/hosts, i.e. not local to the server, not the client.

=item GSPOOL_FLAG_USERONLY

Ignore other users jobs

=back

I<numjobs> is a pointer to an integer value which, on successful
completion, will contain the number of job slots returned.

I<slots> is a pointer to to an array of slot numbers. These slot
numbers can be used to access individual jobs.  The memory used by
this vector is owned by the API, therefore no attempt should be made
by the user to free it.

=head1 RETURN VALUES

=for html
<P>The function returns 0 if successful otherwise one of the error codes
<A HREF="TxtAPI-3.html#Error_codes">listed in Chapter 3</A>.</P>

=for man
The function \fBgspool_joblist()\fR returns 0 if successful, otherwise one
of the following codes:
.Ip "GSPOOL_INVALID_FD" 8
Invalid File descriptor
.Ip "GSPOOL_BADWRITE" 8
failure writing to the network
.Ip "GSPOOL_BADREAD" 8
failure reading from the network

=head1 NOTES

The value assigned to C<*slots> is owned by the API, so the user
should not attempt to free it. This contrasts, for example, with X
library routines.

Also note that certain other calls to the API, notably B<gspool_ptrlist>,
may reuse the space, so the contents should be copied if required
before other API calls are made.

=head1 EXAMPLE

An example to list all jobs:

 int fd, ret, nj, i;
 slotno_t *slots;

 fd = gspool_open("myhost", (char *) 0, 0);

 if (fd < 0) { /* error handling */
     ...
 }

 ret = gspool_joblist(fd, 0, &nj, &slots);

 if (ret < 0) { /* error handling */
     ...
 }

 for (i = 0; i < nj; i++) {
     slotno_t this_slot = slots[i];

     /* process this_slot */

     ...
 }

 gspool_close(fd);


=head1 SEE ALSO

gspool_jobread(3),
gspool_jobdata(3),
gspool_jobadd(3),
gspool_jobdel(3),
gspool_jobfind(3),
gspool_jobfindslot(3),
gspool_jobupd(3),
gspool_jobmon(3),
gspool_jobpbrk(3).

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

## Local Variables:
## mode: nroff
## End:
