=head1 NAME

spshed - spool scheduler

=head1 SYNOPSIS

B<spshed>
[ I<options> ]

=head1 DESCRIPTION

B<spshed> is the spool scheduler process for the B<GNUspool> spooler
and document management system.

To start B<GNUspool>, B<spshed> should be started. This should normally
be done using gspl-start(1), which restarts it and passes the appropriate
options. This may be put within the Operating System startup scripts.

Likewise to halt it, gspl-stop(1) should be invoked. This should be put,
using the B<-y> option, in any system shutdown
routines.

If you do need to kill B<spshed> for any reason, first try kill(1)
I<without> any B<-9> option. This will give B<spshed> the opportunity
to attempt to tidy up any IPC facilities before shutting down.

Information, either in respect of other machines to connect
to, or pre-existing jobs and printers on the current machine, are read
from the files F<gnuspool.hosts> and the spool directory respectively.

If a networked version of B<GNUspool> is being run, then a "slave"
B<spshed> process is spawned to monitor and process incoming network
messages. Incoming remotely-submitted jobs and API interfaces are
handled via a separate process xtnetserv(8), which is also invoked as
appropriate by gspl-start(1).

Appropriate log messages are written by B<spshed> and other system
processes to a log file, F<spshed_reps>. Be sure to
check this file for any error messages relevant to any problems you
encounter.

=head1 FILES

F<gnuspool.hosts>
host names and descriptions

F<gnuspool.conf>
master configuration file

F<int-config>
message file

F<spshed_jfile>
job file

F<spshed_pfile>
printer file

F<spshed_reps>
error log file

F<spufile0>
user data

F<charges0>
user charges data

F<spmm_jobi>
job memory-mapped hash file

F<spmm_jobd>
job memory-mapped data file

F<spmm_ptrs>
printers memory-mapped file

F<spmm_xfer>
communication buffer memory-mapped file

=head1 ENVIRONMENT

=over 4

=item SPOOLDIR

alternative location for spool directory.

=item SPHELPDIR

alternative location for help file directory.

=item SPROGDIR

alternative location for internal programs directory.

=back

=head1 IPC FACILITIES

An IPC message queue, with key C<0x58691000> and owned by C<spooler>,
is created by B<spshed> and used to receive messages from user
processes, pass instructions to spd(8), and to pass internal messages
from the slave B<spshed> process to the master.

Two shared memory segments are created to hold details of jobs and
printers. As the shared memory facility provides no facilities for
growth, then additional shared memory segments may be created if the
job and printer lists expand sufficiently and the original ones
deallocated.

The keys given to the shared memory segments start at C<0x58691002>
and ascend upwards to C<0x58691064> before wrapping around.

A further shared memory segment, with key C<0x58692002> is created to
hold details of pending jobs before transfer to the main shared memory
segment.

Versions of B<spshed> may use memory-mapped files rather than shared
memory. The files are held in the spool directory, by default
F</var/spool/gnuspool>, and have the names F<spmm_jobi>, F<spmm_jobd>,
F<spmm_ptrs> and F<spmm_xfer>.

A set of 5 semaphores, with the key C<0x58691001> is created to
interlock access to the shared memory segments.

The presence or absence of these IPC facilities is used by B<spshed>
and other programs to determine whether a previous copy of itself is
running. If B<spshed> is abnormally terminated, it will probably be
necessary to delete these IPC facilities before B<spshed> can be
restarted.

When printers are set running, B<spshed> invokes an instance of spd(8)
to control each printer. Mail and attention messages are passed to
spmdisp(8) for processing.

=head1 INTERNET PORTS

B<spshed> accepts and sends interconnections from other machines on
TCP port, passes the contents of spool files on a further TCP port, and
undertakes "probes" on a UDP port.

The port numbers are set up in the F</etc/services> file when
B<GNUspool> is first installed.

=head1 SEE ALSO

gspl-pr(1),
gspl-pq(1),
gspl-puser(1),
gspl-qdel(1),
gspl-qchange(1),
gspl-qlist(1),
gspl-plist(1),
gspl-charge(1),
gspl-start(1),
gspl-stop(1),
gnuspool.conf(5),
gnuspool.hosts(5),
gspl-cjlist(8),
gspl-cplist(8),
dosspwrite(8),
ripc(8),
spd(8),
spdinit(8),
spmdisp(8),
spwrite(8),
gspl-spuconv(8),
xtnetserv(8).

=head1 DIAGNOSTICS

B<spshed> is invoked from system startup procedures or other programs
such as gspl-start(1). Thereafter it runs as a "daemon process" and
diagnostics are not written to any terminal but to the file
F<spshed_reps>.

In the event of any problems this file should be examined.

=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:
## LocalWords:  spshed spstart sstop IPC xtnetserv SPOOLDIR SPHELPDIR SPROGDIR
## LocalWords:  spd spmdisp
