NAME

       gspool_ptrlist - get a list of printers

SYNOPSIS

       #include <gspool.h>

       int gspool_ptrlist(const int fd, const unsigned flags, int *numptrs, slotno_t **slots)

DESCRIPTION

       The gspool_ptrlist() function is used to obtain a list of printers.

       fd is a file descriptor previously returned by gspool_open

       flags is either zero, or "GSPOOL_FLAG_LOCALONLY" to request that only printers local to the server be
       listed.

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

       slots is a pointer to to an array of slot numbers. These slot numbers can be used to access individual
       printers. 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_ptrlist() 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_joblist,  may  reuse  the  space,  so  the
       contents should be copied if required before other API calls are made.

EXAMPLE

       An example to list all printers

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

        fd = gspool_open("myhost", (char *) 0, 0);
        if (fd < 0) { /* error handling */
            ...
        }

        ret = gspool_ptrlist(fd, 0, &np, &slots);
        if (ret < 0) { /* error handling */
            ...
        }

        for (i = 0; i < np; i++) {
            slotno_t this_slot = slots[i];
            /* process this_slot */
            ...
        }
        gspool_close(fd);

SEE ALSO

       gspool_ptrread(3),    gspool_ptradd(3),   gspool_ptrdel(3),   gspool_ptrfind(3),   gspool_ptrfindslot(3),
       gspool_ptrupd(3), gspool_ptrmon(3), gspool_ptrop(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_ptrlist(3)