NAME

       gspool_joblist - get a list of jobs

SYNOPSIS

       #include <gspool.h>

       int gspool_joblist(const int fd, const unsigned flags, int *numjobs, slotno_t **slots)

DESCRIPTION

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

       fd is a file descriptor previously returned by gspool_open

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

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

       GSPOOL_FLAG_USERONLY
           Ignore other users jobs

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

       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.

RETURN VALUES

       The function gspool_joblist() returns 0 if successful, otherwise one of the following codes:

       GSPOOL_INVALID_FD
               Invalid File descriptor

       GSPOOL_BADWRITE
               failure writing to the network

       GSPOOL_BADREAD
               failure reading from the network

NOTES

       The value assigned to *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 gspool_ptrlist, may reuse the space, so the
       contents should be copied if required before other API calls are made.

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);

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).

COPYRIGHT

       Copyright  (c) 2009 Free Software Foundation, Inc.  This is free software. You may redistribute copies of
       it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.  There is NO
       WARRANTY, to the extent permitted by law.

AUTHOR

       John M Collins, Xi Software Ltd.

GNUspool Release 1                                 2009-05-30                                  gspool_joblist(3)