=head1 NAME

gspool_jobpbrk - retrieve the page offsets and delimiter string

=head1 SYNOPSIS

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

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

B<FILE *gspool_jobpbrk(const int>
I<fd>B<, const unsigned>
I<flags>B<, const slotno_t>
I<slotno>B<)>

B<int gspool_jobpbrk(const int>
I<fd>B<, const int>
I<outfile>B<, int (*>I<func>B<)(int,void*,unsigned), const unsigned>
I<flags>B<, const slotno_t>
I<slotno>B<)>

=head1 DESCRIPTION

=head2 Unix and GNU/Linux

The function B<gspool_jobpbrk()> is used to retrieve the page break offset
file of a job.

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

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

The result is a C<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, B<gspool_jobpbrk> returns C<NULL> and an error
code is placed in the external variable C<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
C<GSPOOL_BAD_PF> will be returned. You can tell whether there is a page
file from the C<struct apispq> job structure returned by B<xb_jobread>
or B<xb_jobfind>. The field C<apispq_dflags> has the bit designated by
C<APISPQ_PAGEFILE> set if there is a page file.

The data is returned in three parts.

=over 8

=item struct apipages

This is an instance of the following structure, defined in
F<gspool.h>, and described below.

=item delimiter string

This is the delimiter string itself.

=item vector of longs

This is a vector of C<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 B<gspool_jobdata>).

=back

=head2 Windows

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

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

The third argument I<func> is a function with the same specifications
as C<write>, indeed it may very well be C<write>. The main reason for
doing it this way is that some versions of Windows do strange things
if C<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 C<FILE*> or C<NULL>. For consistency with the
Unix version, the external variable C<gspool_dataerror> is also
assigned any error code returned.

The C<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 */
 };

=head1 ERROR CODES

In the event of an error, the external variable C<gspool_dataerror> is
set to the error code. The Unix version of B<gspool_jobpbrk> returns
C<NULL>. The Windows version returns the error code.

=for html
<P>Error codes are <A HREF="TxtAPI-3.html#Error_codes">listed in Chapter
3</A>.</P>

=for man
Error codes which might be returned are:
.Ip "GSPOOL_INVALID_FD" 8
Invalid file descriptor
.Ip "GSPOOL_BADWRITE" 8
failure writing to network
.Ip "GSPOOL_BADREAD" 8
failure reading from network
.Ip "GSPOOL_UNKNOWN_JOB" 8
job not found
.Ip "GSPOOL_NOPERM" 8
job does not belong to user
.Ip "GSPOOL_SEQUENCE" 8
sequence error, job may be out of data
.Ip "GSPOOL_INVALIDSLOT" 8
Invalid slot number
.Ip "GSPOOL_BAD_PF" 8
The job had no page file
.Ip "GSPOOL_NOMEM_PF" 8
There is no memory for the page file

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

=head1 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.

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

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