gspool_jobpbrk - retrieve the page offsets and delimiter string
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)
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.
This is an instance of the following structure, defined in gspool.h, and described below.
This is the delimiter string itself.
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).
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 */ };
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 are listed in Chapter 3.
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 (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.
John M Collins, Xi Software Ltd.