NAME

       gspool_jobpbrk - retrieve the page offsets and delimiter string

SYNOPSIS

       #include <gspool.h>
       #include <stdio.h>

       FILE *gspool_jobpbrk(const int fd, const unsigned flags, const slotno_t slotno)

       int gspool_jobpbrk(const int fd, const int outfile, int (*func)(int,void*,unsigned), const unsigned
       flags, const slotno_t slotno)

DESCRIPTION

   Unix and GNU/Linux
       The function gspool_jobpbrk() is used to retrieve the page break offset file of a job.

       fd is a file descriptor previously returned by gspool_open. flags is zero, or "GSPOOL_FLAG_IGNORESEQ" to
       changes since the job list was last read.

       slotno is the slot number corresponding to the job previously returned by functions such as
       gspool_joblist or gspool_jobfindslot.

       The result is a "FILE" pointer which can be used with all standard I/O input functions such as fread(3),
       fgets(3), getc(3) etc. At the end of the data fclose(3) must be called. For reasons of sychronisation the
       file should be read to the end before other operations are attempted.

       If an error is detected, gspool_jobpbrk returns "NULL" and an error code is placed in the external
       variable "gspool_dataerror".

       If there is no page offset file, probably because the delimiter is set to formfeed, then this isn't
       really an error, but an error report of "GSPOOL_BAD_PF" will be returned. You can tell whether there is a
       page file from the "struct apispq" job structure returned by xb_jobread or xb_jobfind. The field
       "apispq_dflags" has the bit designated by "APISPQ_PAGEFILE" set if there is a page file.

       The data is returned in three parts.

       struct apipages
               This is an instance of the following structure, defined in gspool.h, and described below.

       delimiter string
               This is the delimiter string itself.

       vector of longs
               This  is  a  vector  of "long"s giving the offsets of the start of each page, including the first
               page, which is always zero, within the job data (as read by gspool_jobdata).

   Windows
       The second format of the gspool_jobpbrk function  is  for  use  by  Windows  programs,  as  there  is  no
       acceptable equivalent of the pipe(2) construct.

       The  second argument outfile is (possibly) a file handle to the file from to which the job data is passed
       as the first argument to func.

       The third argument func is a function with the same specifications as "write", indeed it may very well be
       "write". The main reason for doing it this way is that some versions of  Windows  do  strange  things  if
       "write" is invoked from within a DLL.

       Other aspects of the interface are similar to the Unix routine, apart from the routine returning zero for
       success  and  an  error  code  for failure rather than a "FILE*" or "NULL". For consistency with the Unix
       version, the external variable "gspool_dataerror" is also assigned any error code returned.

       The "struct apipages" structure is as follows:

        struct apipages {
          long delimnum;  /* Number of delimiters */
          long deliml;    /* Length of delimiter string */
          long lastpage;  /* Number of delimiters remaining on last page */
        };

ERROR CODES

       In the event of an error, the external variable "gspool_dataerror" is set to the  error  code.  The  Unix
       version  of gspool_jobpbrk returns "NULL". The Windows version returns the error code.  Error codes which
       might be returned are:

       GSPOOL_INVALID_FD
               Invalid file descriptor

       GSPOOL_BADWRITE
               failure writing to network

       GSPOOL_BADREAD
               failure reading from network

       GSPOOL_UNKNOWN_JOB
               job not found

       GSPOOL_NOPERM
               job does not belong to user

       GSPOOL_SEQUENCE
               sequence error, job may be out of data

       GSPOOL_INVALIDSLOT
               Invalid slot number

       GSPOOL_BAD_PF
               The job had no page file

       GSPOOL_NOMEM_PF
               There is no memory for the page file

SEE ALSO

       gspool_joblist(3),    gspool_jobread(3),    gspool_jobdata(3),    gspool_jobadd(3),     gspool_jobdel(3),
       gspool_jobfind(3), gspool_jobfindslot(3), gspool_jobupd(3), gspool_jobmon(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_jobpbrk(3)