Updated to match programs at ckuethe's previous commit.

18 files changed, 53 insertions, 42 deletions

diff --git a/doc/explan_bits.h.xml b/doc/explan_bits.h.xml
index 1cdd50cb..722f0383 100644
--- a/doc/explan_bits.h.xml
+++ b/doc/explan_bits.h.xml
@@ -7,7 +7,7 @@
 
 <tbody>
 <row>
-  <entry><para>This file only contains macros that convert data variables from the native format of the device output (MSB-first or LSB-first) into a standard form for <application>gpsd</application> use. This makes data parsing consistent regardless of the underlying format. If the device driver file makes no deliberate selection, the default is to assume the device emits data in big-endian (network byte) order.</para></entry>
+  <entry><para>This file only contains macros that convert data variables from the native format of the device output (MSB-first or LSB-first) into a standard form for <function>gpsd</function> use. This makes data parsing consistent regardless of the underlying format. If the device driver file makes no deliberate selection, the default is to assume the device emits data in big-endian (network byte) order.</para></entry>
 </row>
 </tbody>
 
diff --git a/doc/explan_dgnss.c.xml b/doc/explan_dgnss.c.xml
index a0543485..12d50f90 100644
--- a/doc/explan_dgnss.c.xml
+++ b/doc/explan_dgnss.c.xml
@@ -18,7 +18,7 @@
 </row>
 <row>
   <entry><function>int dgnss_open(struct gps_context_t *context, char *dgnss_service)</function></entry>
-  <entry><para>Try to open a connection to the nominated service. If the service cannot be opened, the return is -1. The supported services are <emphasis>dgpsip</emphasis> (differential corrections via IP) and <emphasis>ntrip</emphasis> (differential corrections in http form).</para></entry>
+  <entry><para>Try to open a connection to the nominated service. If the service cannot be opened, the return is -1. The supported services are <function>dgpsip</function> (differential corrections via IP) and <function>ntrip</function> (differential corrections in http form).</para></entry>
 </row>
 <row>
   <entry><function>int dgnss_poll(struct gps_context_t *context)</function></entry>
diff --git a/doc/explan_driver_proto.c.xml b/doc/explan_driver_proto.c.xml
index d0f72618..626d9866 100644
--- a/doc/explan_driver_proto.c.xml
+++ b/doc/explan_driver_proto.c.xml
@@ -13,7 +13,7 @@
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: driver_proto.c 4229 2007-01-10 23:24:52Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: driver_proto.c 4373 2007-06-01 22:30:43Z esr $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_drivers.c.xml b/doc/explan_drivers.c.xml
index b92efcb7..12340391 100644
--- a/doc/explan_drivers.c.xml
+++ b/doc/explan_drivers.c.xml
@@ -44,7 +44,7 @@
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: drivers.c 4297 2007-03-09 07:11:46Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: drivers.c 4373 2007-06-01 22:30:43Z esr $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_gps.h.xml b/doc/explan_gps.h.xml
index ac08310a..43651c0e 100644
--- a/doc/explan_gps.h.xml
+++ b/doc/explan_gps.h.xml
@@ -28,7 +28,7 @@
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: gps.h 4284 2007-01-27 07:27:42Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: gps.h 4369 2007-06-01 19:23:17Z esr $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_gpsd.c.xml b/doc/explan_gpsd.c.xml
index c214560e..51b816bc 100644
--- a/doc/explan_gpsd.c.xml
+++ b/doc/explan_gpsd.c.xml
@@ -14,7 +14,7 @@
 <tbody>
 <row>
   <entry><function>static void onsig(int sig)</function></entry>
-  <entry><para>Reset a previously modified signal to default handling.</para></entry>
+  <entry><para>This ia a simple catchall routine to trap wanted signal. Simply store the signal number in a variable to advise the main loop which signal to handle.</para></entry>
 </row>
 <row>
   <entry><function>static int daemonize(void)</function></entry>
@@ -54,7 +54,7 @@
 </row>
 <row>
   <entry><function>static ssize_t throttled_write(struct subscriber_t *sub, char *buf, ssize_t len)</function></entry>
-  <entry><para>Check if we have a high enough debug level active to warrant printing out the information we are about to send to the client.</para><para>Make the actual <function>write()</function> call and if that was successful, return the counter value from that operation.</para><para>If we have suffered some kind of failure, try to analyse it.</para><para>Trap <function>EBADF</function> and generate a suitable report.</para><para>Trap <function>EWOULDBLOCK</function> and if the client has not read data for more than a reasonable amount of time, generate a suitable report.</para><para>For all other errors, generate a general error and call <function>detach_cient()</function>.</para><para>Finally, return the status (-1 in this case).</para></entry>
+  <entry><para>Check if we have a high enough debug level active to warrant printing out the information we are about to send to the client.</para><para>Make the actual <function>write()</function> call and if that was successful, return the counter value from that operation.</para><para>If we have suffered some kind of failure, try to analyse it.</para><para>On a short write, detach the client and return a 0.</para><para>Trap <function>EAGAIN</function> or <function>EINTR</function> and return a 0.</para><para>Trap <function>EBADF</function> or a <function>EWOULDBLOCK</function> where the client has not read data for more than a reasonable amount of time and generate a suitable report.</para><para>For all other errors, generate a general error. In these last several cases, call <function>detach_cient()</function>.</para><para>Finally, return the status (-1 in this case).</para></entry>
 </row>
 <row>
   <entry><function>static void notify_watchers(struct gps_device_t *device, char *sentence, ...)</function></entry>
@@ -70,7 +70,7 @@
 </row>
 <row>
   <entry><function>static struct gps_device_t *open_device(char *device_name)</function></entry>
-  <entry><para>Check if the incoming device name is a DGPS URL via a call to <function>dgnss_url()</function>.</para><para>If it is, try to open it via a call to <function>dgnss_open()</function>.</para><para>If this worked, add the fd to our list of active fds and housekeep the highest fd number via a call to <function>adjust_max_fd()</function>. Exit by returning the address of the channels array (see the comment in the code!!).</para><para>For a non-DGPS (normal) device, scan all channels looking for an unallocated one. Exit early on a successful search. If none is found, return a NULL.</para><para>If one is found, make a call to <function>gpsd_init()</function> and store address of the local <function>raw_hook()</function> code in the selected channel's <function>gpsdata.raw_hook</function>.</para><para>Try to activate the device via a call to <function>gpsd_activate()</function>.</para><para>If this fails return -1.</para><para>If it succeeds, add the fd to our list of active fds, housekeep the highest fd number and return the channel number allocated.</para></entry>
+  <entry><para>Check if the incoming device name is a DGPS URL via a call to <function>dgnss_url()</function>.</para><para>If it is, try to open it via a call to <function>dgnss_open()</function>.</para><para>If this worked, add the fd to our list of active fds and housekeep the highest fd number via a call to <function>adjust_max_fd()</function>. Exit by returning the address of the channels array (see the comment in the code!!).</para><para>For a non-DGPS (normal) device, scan all channels looking for an unallocated one. Exit early on a successful search. If none is found, return a NULL.</para><para>If one is found, make a call to <function>gpsd_init()</function> and store address of the local <function>raw_hook()</function> code in the selected channel's <function>gpsdata.raw_hook</function>.</para><para>Try to activate the device via a call to <function>gpsd_activate()</function>.</para><para>If this fails return a NULL.</para><para>If it succeeds, add the fd to our list of active fds, housekeep the highest fd number and return the channel number allocated.</para></entry>
 </row>
 <row>
   <entry><function>static bool allocation_policy(struct gps_device_t *channel, struct subscriber_t *user, double most_recent)</function></entry>
@@ -102,13 +102,13 @@
 </row>
 <row>
   <entry><function>int main(int argc, char *argv[])</function></entry>
-  <entry><para>If the 1PPS function is compiled in, initialise the local mutex structure for use by the program.</para><para>A <function>while()</function> loop reads in any command line arguments which are options and handles the options. Most set an internal variable to contol action when running, either to a fixed value or to the associated option's parameter.</para><para>Carry out a series of calls to routines to set things up ready for the main task (e.g. opening a control socket if one is needed). We also take care of tasks such as daemonizing when appropriate. The last piece of preparation is to set the permissions of the default devices correctly if we are daemonizing and are presently running as root.</para><para>Switch to the compiled in user name (typically <quote>nobody</quote>) and the group used by the tty devices.</para><para>Now we clear important data for all the records in the subscriber list.</para><para>Use <function>setjmp()</function> to prepare things for when the daemon terminates.</para><para>Set some important signals so they are trapped by a local handler. This handler just resets the calling signal to its default behaviour and calls <function>longjmp()</function>. This will bring things back to the <function>setjmp()</function> just mentioned and initiate a clean up and exit.</para><para>Add the command and RTCM sockets (if active) to the list of active fds, housekeeping the highest fd number and pre-clear the list of control fds.</para><para>Process the remaining parameter on the command line which should be the device name and try to open the specified device.</para><para>Enter the main execution loop, an endless <function>for()</function> loop. What follows will repeat over and over until an external termination happens or the <function>select()</function> function fails due to some unexpected reason.</para><para>First we make a working copy of the active fds and then we make a time-limited (1 second time limit) call to <function>select()</function> using the working copy of the fds. This means that when the <function>select()</function> returns, we will either have returned on timeout or because some fd became ready to read.</para><para>First we check if any new clients have come active and (if we have resources) allocate a subscriber slot to it, doing housekeeping such as adding it to the main list of active fds and removing it from the local copy of the list. If RTCM support is compiled in, the last operation is repeated for any new RTCM client. The operation is then repeated for any new control socket clients.</para><para>If we are expecting DGPS reports, make a call to <function>dgnss_poll()</function> and if there are no ready reports, clear the fd from the main and local active fd lists.</para><para>Check if any of the active control sockets has sent one or more commands.</para><para>For every one which has sent commands, make calls to <function>handle_control()</function> to process them and remove the associated fd from the main and control lists of active fds.</para><para>Poll every active gps device and send RTCM data to it (if needed), followed by reading its output (if any). If the device returns an error, disable the device. If it has gone off-line, disable the device.</para><para>If we get here, we have something to handle, so we take care of a device which we know about, but do not have a subtype for.</para><para>We send the available data to all subscribers who are connected to this device. If the data is RTCM information, pass it to all gps devices that can accept the data.</para><para>Handle any subscribers who are in watcher mode building up an approriate set of requests, depending on the available data and passing the requests to <function>handle_gpsd_request()</function>.</para><para>If we care about DBUS, send the fix to the DBUS.</para><para><emphasis>Note that this small section of code is presently disabled pending development of the DGNSS function.</emphasis> If DGNSS is avalable and we have a fix, we poll a DGNSS report via <function>dgnss_autoconnect()</function>.</para><para>Loop round all clients and process active ones. We check for input from them and if the read fails, the client is released with <function>detach_cleint()</function>. If it succeeds, any data is handled via <function>handle_rtc_request()</function> or <function>handle_gpsd_request()</function>.</para><para>If the transaction fails, the client is released with <function>detach_client()</function>.</para><para>If the client has timed out with no device assigned, it is released with <function>detach_client()</function>.</para><para>If the client has a device, but has timed out on no response (when not in raw or watcher modes) it is released with <function>detach_client()</function>.</para><para>If we are not running in <quote>nowait</quote> mode, we are supposed to go idle when there are no clients. However, this is subject to a restriction that a device is not allowed to go idle like this until we have actually discovered what it is. This means we stay active until the packet sniffer has returned the packet type.</para><para>If a device (with a known type) has no active clients, then we can actually make it idle via <function>gpsd_deactivate()</function>.</para><para>If we reach here, we are out of the endless loop, so finally we check for the existance of a control socket or a pid file and delete them.</para></entry>
+  <entry><para>If the 1PPS function is compiled in, initialise the local mutex structure for use by the program.</para><para>A <function>while()</function> loop reads in any command line arguments which are options and handles the options. Most set an internal variable to contol action when running, either to a fixed value or to the associated option's parameter.</para><para>Carry out a series of calls to routines to set things up ready for the main task (e.g. opening a control socket if one is needed). We also take care of tasks such as daemonizing when appropriate. The last piece of preparation is to set the permissions of the default devices correctly if we are daemonizing and are presently running as root.</para><para>Switch to the compiled in user name (typically <quote>nobody</quote>) and the group used by the tty devices.</para><para>Now we clear important data for all the records in the subscriber list.</para><para>Use <function>setjmp()</function> to prepare things for when the daemon terminates.</para><para>Clear the semaphore variable which will contain the signal number if one arrives and set some important signals so they are trapped by the stub handler in <function>onsig()</function>.</para><para>Add the command and RTCM sockets (if active) to the list of active fds, housekeeping the highest fd number and pre-clear the list of control fds.</para><para>Process the remaining parameter on the command line which should be the device name and try to open the specified device.</para><para>Enter the main execution loop, a <function>while()</function> loop which terminates if a signal sets the semaphore variable. What follows will repeat over and over until an external termination happens.</para><para>First we make a working copy of the active fds and then we make a time-limited (1 second time limit) call to <function>select()</function> using the working copy of the fds. This means that when the <function>select()</function> returns, we will either have returned on timeout or because some fd became ready to read.</para><para>First we check if any new clients have come active and (if we have resources) allocate a subscriber slot to it, doing housekeeping such as adding it to the main list of active fds and removing it from the local copy of the list. If RTCM support is compiled in, the last operation is repeated for any new RTCM client. The operation is then repeated for any new control socket clients.</para><para>If we are expecting DGPS reports, make a call to <function>dgnss_poll()</function> and if there are no ready reports, clear the fd from the main and local active fd lists.</para><para>Check if any of the active control sockets has sent one or more commands.</para><para>For every one which has sent commands, make calls to <function>handle_control()</function> to process them and remove the associated fd from the main and control lists of active fds.</para><para>Poll every active gps device and send RTCM data to it (if needed), followed by reading its output (if any). If the device returns an error, disable the device. If it has gone off-line, disable the device.</para><para>If we get here, we have something to handle, so we take care of a device which we know about, but do not have a subtype for.</para><para>We send the available data to all subscribers who are connected to this device. If the data is RTCM information, pass it to all gps devices that can accept the data.</para><para>Handle any subscribers who are in watcher mode building up an approriate set of requests, depending on the available data and passing the requests to <function>handle_gpsd_request()</function>.</para><para>If we care about DBUS, send the fix to the DBUS.</para><para><emphasis>Note that this small section of code is presently disabled pending development of the DGNSS function.</emphasis> If DGNSS is avalable and we have a fix, we poll a DGNSS report via <function>dgnss_autoconnect()</function>.</para><para>Loop round all clients and process active ones. We check for input from them and if the read fails, the client is released with <function>detach_cleint()</function>. If it succeeds, any data is handled via <function>handle_rtc_request()</function> or <function>handle_gpsd_request()</function>.</para><para>If the transaction fails, the client is released with <function>detach_client()</function>.</para><para>If the client has timed out with no device assigned, it is released with <function>detach_client()</function>.</para><para>If the client has a device, but has timed out on no response (when not in raw or watcher modes) it is released with <function>detach_client()</function>.</para><para>If we are not running in <quote>nowait</quote> mode, we are supposed to go idle when there are no clients. However, this is subject to a restriction that a device is not allowed to go idle like this until we have actually discovered what it is. This means we stay active until the packet sniffer has returned the packet type.</para><para>If a device (with a known type) has no active clients, then we can actually make it idle via <function>gpsd_deactivate()</function>.</para><para>If we reach here, we are out of the endless while loop. We check if the signal was <function>SIGHUP</function> and restart the program if it was. If it is any other signal, we deallocate all channels and wrap up any devices. Finally we check for the existance of a control socket or a pid file and delete them.</para></entry>
 </row>
 </tbody>
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: gpsd.c 4302 2007-03-14 02:27:45Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: gpsd.c 4418 2007-09-12 02:47:38Z ckuethe $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_gpsd.h.xml b/doc/explan_gpsd.h.xml
index 736d83fb..20ff8fab 100644
--- a/doc/explan_gpsd.h.xml
+++ b/doc/explan_gpsd.h.xml
@@ -13,6 +13,9 @@
 
 <tbody>
 <row>
+  <entry spanname='s1' align='left'><para>This file is created at <function>configure</function> time by combining <function>gpsd.h-head</function>, certain configuration options from the auto-generated file <function>gpsd_configure.h</function> and <function>gpsd.h-tail</function>. This file (<function>gpsd.h</function>) should not be edited directly, neither should <function>gpsd.h-head</function>. You should only edit <function>gpsd.h-tail</function> as needed.</para></entry>
+</row>
+<row>
   <entry><function>struct gps_packet_t {}</function></entry>
   <entry><para>Provides the data structure used by <function>packet_getter()</function>. 1 per <application>gpsd</application> session.</para></entry>
 </row>
@@ -32,7 +35,7 @@
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: gpsd.h 4304 2007-03-14 06:07:46Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: gpsd.h-tail 4383 2007-06-03 21:11:37Z ckuethe $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_libgps.c.xml b/doc/explan_libgps.c.xml
index 669ee7af..ffb2944a 100644
--- a/doc/explan_libgps.c.xml
+++ b/doc/explan_libgps.c.xml
@@ -13,6 +13,10 @@
 
 <tbody>
 <row>
+  <entry><function>char *deg_to_str( enum deg_str_type type,  double f)</function></entry>
+  <entry><para>Convert double degrees to a static string and return a pointer to it.</para><para>Makes a simple check on invalid degree values (less than 0 or more than 360) and returns "nan" if found.</para><para>For valid values, it generates the appropriate string according to the string type enumeration, defaulting to DD MM SS.sss</para></entry>
+</row>
+<row>
   <entry><function>enum unit gpsd_units(void)</function></entry>
   <entry><para>Simple check of the environment to determine what units are required. If all else fails, use compiled in units.</para></entry>
 </row>
@@ -66,13 +70,13 @@
 </row>
 <row>
   <entry><function>int main(int argc, char *argv[])</function></entry>
-  <entry><para>A simple command line parser and endless loop to exercise the daemon when deugging.</para></entry>
+  <entry><para>A simple command line parser and endless loop to exercise the daemon when debugging.</para></entry>
 </row>
 </tbody>
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: libgps.c 4226 2007-01-06 20:26:47Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: libgps.c 4377 2007-06-02 14:52:38Z esr $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_libgpsd_core.c.xml b/doc/explan_libgpsd_core.c.xml
index 9cdf4e99..8da9c69f 100644
--- a/doc/explan_libgpsd_core.c.xml
+++ b/doc/explan_libgpsd_core.c.xml
@@ -22,7 +22,7 @@
 </row>
 <row>
   <entry><function>void gpsd_deactivate(struct gps_device_t *session)</function></entry>
-  <entry><para>Release the NTPD resources, including the 1PPS resourecs if they are active.</para><para>If the device has a revert function, trigger it.</para><para>If it has an NMEA mode switcher, invoke it.</para><para>If it has a wrapup routine, invoke it.</para><para>Finally, close the device.</para></entry>
+  <entry><para>All actions below, except the last one are conditional on the <function>ntpd</function> interface being compiled in.</para><para>Release the <function>ntpd</function> resources, including the 1PPS resourecs if they are active.</para><para>If the device has a revert function, trigger it.</para><para>If it has an NMEA mode switcher, invoke it.</para><para>If it has a wrapup routine, invoke it.</para><para>Finally, close the device.</para></entry>
 </row>
 <row>
   <entry><function>static void *gpsd_ppsmonitor(void *arg)</function></entry>
diff --git a/doc/explan_netlib.c.xml b/doc/explan_netlib.c.xml
index 08724c4c..f5a2d7b9 100644
--- a/doc/explan_netlib.c.xml
+++ b/doc/explan_netlib.c.xml
@@ -16,11 +16,15 @@
   <entry><function>int netlib_connectsock(const char *host, const char *service, const char *protocol)</function></entry>
   <entry><para>This attempts to connect the to nominated service on the nominated host using the nominated protocol. On success, the return value is the socket number. On error, an appropriate system defined error code is returned.</para></entry>
 </row>
+<row>
+  <entry><function>char *sock2ip(int fd)</function></entry>
+  <entry><para>This makes a call to <function>getpeername</function> using the spplied fd. On success, the returned string is the ip address in dotted notation. On error, "&lt;unknown&gt;" is returned.</para></entry>
+</row>
 </tbody>
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: netlib.c 4264 2007-01-22 15:53:33Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: netlib.c 4376 2007-06-02 06:29:26Z esr $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_nmea_parse.c.xml b/doc/explan_nmea_parse.c.xml
index 630ea54d..1d6aa6b7 100644
--- a/doc/explan_nmea_parse.c.xml
+++ b/doc/explan_nmea_parse.c.xml
@@ -26,11 +26,11 @@
 </row>
 <row>
   <entry><function>static gps_mask_t processGPRMC(int count, char *field[], struct gps_device_t *session)</function></entry>
-  <entry><para>Handle a $GPRMC sentence stored in an array of strings, one member per field.</para><para>Check if the message is stamped valid or not.</para><para>If it is invalid, set the status and fix mode to NO_FIX and save the corresponding flags locally; also save the online flag so we know we have handled a known sentence.</para><para>If the fix is autonomous and valid, start to decode the fields.</para><para>First, test if there are enough fields available; then handle the date and time via <function>merge_ddmmyy()</function> and <function>merge_hhmmss()</function>, storing the TIME_SET flag and storing the fix time as a UNIX-epoch relative value.</para><para>If the sentence time and this fix time are different, we have started a new cycle of observation, so update the sentence time and the store the CYCLE_START_SET flag.</para><para>Whatever the number of fields, store the fix co-ordinates via <function>do_lat_lon()</function>, store the speed and the track and save the corresponding flags.</para><para>Return the local aggregated flags to allow the main copy in the session data to be updated.</para></entry>
+  <entry><para>Handle a $GPRMC sentence stored in an array of strings, one member per field.</para><para>Check if the message is stamped valid or not.</para><para>If it is invalid, set the status and fix mode to NO_FIX and save the corresponding flags locally; also save the online flag to indicate we have handled a known sentence.</para><para>If the fix is autonomous and valid, start to decode the fields.</para><para>First, test if there are enough fields available; then handle the date and time via <function>merge_ddmmyy()</function> and <function>merge_hhmmss()</function>, storing the TIME_SET flag and storing the fix time as a UNIX-epoch relative value.</para><para>If the sentence time and this fix time are different, we have started a new cycle of observation, so update the sentence time and the store the CYCLE_START_SET flag.</para><para>Whatever the number of fields, store the fix co-ordinates via <function>do_lat_lon()</function>, store the speed and the track and save the corresponding flags.</para><para>Return the local aggregated flags to allow the main copy in the session data to be updated.</para></entry>
 </row>
 <row>
   <entry><function>static gps_mask_t processGPGLL(int count, char *field[], struct gps_device_t *session)</function></entry>
-  <entry><para>Preload the local flag with the ERROR_SET flag.</para><para>Check that the sentence is usable, exiting with the preset error flag if it is not.</para><para>If it is usable, clear the local flags and start processing the fields, updating any local flag fields on the way.</para><para>If the year is already known, update the time and check for the start of cycle (see <function>processGPRMC()</function> above).</para><para>Handle the fix location and, if the number of received fixes is more than 8 and the status is differential, stash the new status as STATUS_DGPS_FIX; otherwise stash STATUS_FIX.</para><para>If the present mode is less than 2D_FIX, update it to 2D_FIX.</para><para>Update the status to the stashed value of newstatus and return all the locally aggregated flags.</para></entry>
+  <entry><para>Preload the local flag with the ERROR_SET flag.</para><para>Check that the sentence is usable, exiting with the preset error flag if it is not.</para><para>If it is usable, clear the local flags and start processing the fields, updating any local flag fields on the way.</para><para>If the year is already known, update the time and check for the start of cycle (see <function>processGPRMC()</function> above).</para><para>Handle the fix location and, if the number of received fixes is more than 8 and the status is differential, stash the new status as STATUS_DGPS_FIX; otherwise stash STATUS_FIX.</para><para>If the present mode is less than 2D_FIX, update it to 2D_FIX.</para><para>Write the stashed value of newstatus into the session status and return all the locally aggregated flags.</para></entry>
 </row>
 <row>
   <entry><function>static gps_mask_t processGPGGA(int c UNUSED, char *field[], struct gps_device_t *session)</function></entry>
@@ -50,11 +50,11 @@
 </row>
 <row>
   <entry><function>static gps_mask_t processGPZDA(int c UNUSED, char *field[], struct gps_device_t *session)</function></entry>
-  <entry><para>Set the local flag variable to indicate that the time is available.</para><para>Store the actual time by a call to <function>merge_hhmmss()</function> and fill in the other fields from the sentence data.</para><para>If the sentence is not timestamped the same as the fixtime, update the fixtime and set the CYCLE_START_SET flag.</para><para>Finally, return all the locally aggregated flags.</para></entry>
+  <entry><para>Set the local flag variable to indicate that the time is available.</para><para>Store the actual time by a call to <function>merge_hhmmss()</function> and fill in the other fields from the sentence data.</para><para>If the sentence is not timestamped the same as the fixtime, set the CYCLE_START_SET flag.</para><para>Update the fixtime to the sentence timestamp.</para><para>Finally, return all the locally aggregated flags.</para></entry>
 </row>
 <row>
   <entry><function>static gps_mask_t processTNTHTM(int c UNUSED, char *field[], struct gps_device_t *session)</function></entry>
-  <entry><para>Set the local variable to indicate the the unit is on-line.</para><para>Fill all appropriate fields from the sentence and set the associated flags in the local flag variable.</para><para>Set the fix status and freturn all the locally aggregated flags.</para></entry>
+  <entry><para>Set the local variable to indicate the the unit is on-line.</para><para>Fill all appropriate fields from the sentence and set the associated flags in the local flag variable.</para><para>Set the fix status and return all the locally aggregated flags.</para></entry>
 </row>
 <row>
   <entry><function>static short nmea_checksum(char *sentence, unsigned char *correct_sum)</function></entry>
@@ -62,21 +62,21 @@
 </row>
 <row>
   <entry><function>gps_mask_t nmea_parse(char *sentence, struct gps_device_t *session)</function></entry>
-  <entry><para>Take an NMEA sentence and check the checksum with <function>nmea_checksum()</function> (note:- this is switched off at the moment).</para><para>Test the length is acceptable, retuning an on-line indication if it is too long to handle.</para><para>If it is within limits, make a local copy and split it on the commas into an array, one field per element.</para><para>Use the first element to match the command to the table of decodable commands.</para><para>If it is supported and the number of fields is reasonable, invoke the correct decoder and return the value from that call.</para><para>If it fails the testing, return an on-line status.</para></entry>
+  <entry><para>Take an NMEA sentence and check the checksum with <function>nmea_checksum()</function>, returning an empty flag mask if so (note:- this is switched off at the moment).</para><para>Test the length is acceptable, simply returning an on-line indication if it is too long to handle.</para><para>If it is within limits, make a local copy and split it on the commas into an array, one field per element.</para><para>Use the first element to match the command to the table of decodable commands.</para><para>Check if it is supported and the number of fields is reasonable, invoke the correct decoder and return the value from that call.</para><para>If it fails the check, simply return an on-line status.</para></entry>
 </row>
 <row>
   <entry><function>void nmea_add_checksum(char *sentence)</function></entry>
-  <entry><para>Calcluate the checksum then insert a '*', the checksum and CR+LF into the end of an NMEA Sentence, skipping any existing '*'.</para></entry>
+  <entry><para>Calcluate the checksum then append '*' + the checksum + CR/LF to the end of an NMEA sentence, skipping any existing '*'.</para></entry>
 </row>
 <row>
   <entry><function>int nmea_send(int fd, const char *fmt, ... )</function></entry>
-  <entry><para>Read the incoming data into a buffer, reserving the last 5 bytes (at least) for the terminating data.</para><para>If the buffer starts with a '$', asssume it is an NMEA sentence and call nmea_add_checksum; otherwise, just add a CR+LF.</para><para>Write the buffer to the device, stashing the byte count returned. Wait until all output is sent.</para><para>Check the returned value against the number of bytes in the buffer. If they are equal, return the stashed count. If not, return -1.</para></entry>
+  <entry><para>Read the incoming data into a buffer, reserving the last 5 bytes (at least) for the terminating data.</para><para>If the buffer starts with a '$', asssume it is an NMEA sentence and call <function>nmea_add_checksum</function>. Otherwise, just add a CR+LF.</para><para>Write the buffer to the device, stashing the byte count returned. Wait until all output is sent.</para><para>Check the returned value against the number of bytes in the buffer. If they are equal, return the stashed count. If not, return -1.</para></entry>
 </row>
 </tbody>
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: nmea_parse.c 4306 2007-03-15 06:33:17Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: nmea_parse.c 4373 2007-06-01 22:30:43Z esr $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_ntpshm.c.xml b/doc/explan_ntpshm.c.xml
index 88ff86de..cf74c769 100644
--- a/doc/explan_ntpshm.c.xml
+++ b/doc/explan_ntpshm.c.xml
@@ -18,15 +18,15 @@
 </row>
 <row>
   <entry><function>void ntpshm_init(struct gps_context_t *context, bool enablepps)</function></entry>
-  <entry><para>Attaches all ntp shared memeory segments.</para></entry>
+  <entry><para>Attaches all ntp shared memeory segments, flagging the avaliablilty of the NMEA and 1pps capabilities as appropriate.</para></entry>
 </row>
 <row>
   <entry><function>int ntpshm_alloc(struct gps_context_t *context)</function></entry>
-  <entry><para>This allocates a free ntp shared memory segment.</para><para>If one is available, initialise it for use and flag it as in use.</para><para>Returns the segment number on success or -1 on failure.</para></entry>
+  <entry><para>This tries to allocate a free ntp shared memory segment.</para><para>If one is available, initialise it for use and flag it as in use.</para><para>Returns the segment number on success or -1 on failure.</para></entry>
 </row>
 <row>
   <entry><function>bool ntpshm_free(struct gps_context_t *context, int segment)</function></entry>
-  <entry><para>This releases a previously allocated ntp shared memory segment. Indicates the outcome by returning true (success) or false.</para></entry>
+  <entry><para>This tries to release a previously allocated ntp shared memory segment. Indicates the outcome by returning true (success) or false.</para></entry>
 </row>
 <row>
   <entry><function>int ntpshm_put(struct gps_device_t *session, double fixtime)</function></entry>
@@ -34,13 +34,13 @@
 </row>
 <row>
   <entry><function>int ntpshm_pps(struct gps_device_t *session, struct timeval *tv)</function></entry>
-  <entry><para>Only available if the 1PPS function is compiled in.</para><para>Checks if the shared memory structures are valid. If so, it validates that the time received is within the locking range.</para><para>If good, the time is stored in the shared memory.</para><para>A return value of 1 indicates successful update; 0 indicates there is a problem with the shared memory structures and -1 indicates that the time could not be locked to.</para></entry>
+  <entry><para>This code is only available if the 1PPS function is compiled in.</para><para>The shared memory structures are checked for validity and if not valid, a 0 is returned.</para><para>The time received is then checked to be within 100 milliseconds of the PC's internal time and if not, a -1 is returned.</para><para></para><para>The time received is then checked to be within 500 milliseconds of the second boundary and if not, the shared memory structure is advised that lock is lost and a -1 is returned.</para><para>If good, the time is stored in the shared memory and 1 is returned.</para></entry>
 </row>
 </tbody>
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: ntpshm.c 3771 2006-11-02 05:15:20Z esr $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: ntpshm.c 4412 2007-08-21 15:48:02Z ckuethe $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_packet.c.xml b/doc/explan_packet.c.xml
index d459d714..29b23afc 100644
--- a/doc/explan_packet.c.xml
+++ b/doc/explan_packet.c.xml
@@ -30,11 +30,11 @@
 </row>
 <row>
   <entry><function>ssize_t packet_parse(struct gps_packet_t *lexer, size_t fix)</function></entry>
-  <entry><para>Call the <function>nextstate()</function> function to process the available data and set the recognition state correctly. Return the number of characters handled.</para></entry>
+  <entry><para>Call the <function>nextstate()</function> function to process the available data and set the recognition state correctly.<para>When a packet is matched to a driver, call <function>packet_accept()</function> and <function>packet_discard()</function> to handle the packet. If it is not matched, call <function>packet_discard()</function> and set the state to <quote>GROUND_STATE</quote></para> Return the number of characters handled.</para></entry>
 </row>
 <row>
   <entry><function>ssize_t packet_get(int fd, struct gps_packet_t *lexer)</function></entry>
-  <entry><para>Reads raw data from the input port. Returns the number of characters read (0 or more) or BAD_PACKET if there was an error in reading. Errors <errortype>EAGAIN</errortype> and <errortype>EINTR</errortype> are not classed as failures and cause a return of 0.</para></entry>
+  <entry><para>Reads raw data from the input port.</para><para>Returns the number of characters read (0 or more) or BAD_PACKET if there was an error in reading.</para><para>Errors <errortype>EAGAIN</errortype> and <errortype>EINTR</errortype> are not classed as failures and cause a return of 0.</para><para>In case of a good read of more than 0 characters, the return value is the output from a call to <function>packet_parse()</function>.</para></entry>
 </row>
 <row>
   <entry><function>void packet_reset(struct gps_packet_t *lexer)</function></entry>
@@ -48,7 +48,7 @@
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: packet.c 4299 2007-03-11 19:51:22Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: packet.c 4377 2007-06-02 14:52:38Z esr $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_packet_names.h.xml b/doc/explan_packet_names.h.xml
index 407468c9..0e8da905 100644
--- a/doc/explan_packet_names.h.xml
+++ b/doc/explan_packet_names.h.xml
@@ -13,7 +13,7 @@
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: packet_names.h 4231 2007-01-11 02:06:56Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: packet_names.h 4299 2007-03-11 19:51:22Z ckuethe $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_rtcm.c.xml b/doc/explan_rtcm.c.xml
index 690dc323..24146bf4 100644
--- a/doc/explan_rtcm.c.xml
+++ b/doc/explan_rtcm.c.xml
@@ -48,7 +48,7 @@
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: rtcm.c 4065 2006-12-04 05:31:59Z esr $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: rtcm.c 4364 2007-05-31 08:43:23Z esr $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_serial.c.xml b/doc/explan_serial.c.xml
index 8901b318..aa4fc5ae 100644
--- a/doc/explan_serial.c.xml
+++ b/doc/explan_serial.c.xml
@@ -14,7 +14,7 @@
 <tbody>
 <row>
   <entry><function>void gpsd_tty_init(struct gps_device_t *session)</function></entry>
-  <entry><para>To be called on allocating a device. Mark GPS fd closed and its baud rate unknown.</para></entry>
+  <entry><para>To be called on allocating a device. Mark GPS fd closed and its baud rate unknown.</para><para>If we are supporting <function>ntpd</function> shared memory segments, ensure they are initally unused.</para></entry>
 </row>
 <row>
   <entry><function>void cfmakeraw(struct termios *termios_p)</function></entry>
@@ -30,7 +30,7 @@
 </row>
 <row>
   <entry><function>void gpsd_set_speed(struct gps_device_t *session, speed_t speed, unsigned char parity, unsigned int stopbits)</function></entry>
-  <entry><para>Sets the speed, parity and stopbits.</para><para>Lots of black magic fiddling goes on to ensure the port is flushed on the baud rate change and wakeup strings are fired off just in case the device needs prodding into life.</para><para>READ THE CODE AND COMMENTS!!!</para></entry>
+  <entry><para>Sets the speed, parity and stopbits.</para><para>Lots of black magic fiddling goes on to ensure the port is flushed on the baud rate change and wakeup strings are fired off just in case the device needs prodding into life.</para><para>READ THE CODE AND COMMENTS!!!</para><para>Prior to exit, a call is made to <function>packet_reset()</function> to ensure the packet state machine is initialised.</para></entry>
 </row>
 <row>
   <entry><function>int gpsd_open(struct gps_device_t *session)</function></entry>
@@ -38,7 +38,7 @@
 </row>
 <row>
   <entry><function>bool gpsd_write(struct gps_device_t *session, void const *buf, size_t len)</function></entry>
-  <entry><para>Try to write <function>len</function> characters to the device. waiting until all data has been sent.</para><para>If the write was successful (number of bytes written = <function>len</function>), return <quote>true</quote>, othewise return <quote>false</quote>.</para></entry>
+  <entry><para>If the device is read-only, simply return 0.</para><para>If not, try to write <function>len</function> characters to the device. waiting until all data has been sent.</para><para>Return the number of bytes written.</para></entry>
 </row>
 <row>
   <entry><function>bool gpsd_next_hunt_setting(struct gps_device_t *session)</function></entry>
@@ -57,7 +57,7 @@ Set the HUPCL flag in the original data, write the old data to the port, close t
 
 <tfoot>
 <row>
-  <entry spanname='s1' align='left'>Notes based on <function>$Id: serial.c 4302 2007-03-14 02:27:45Z ckuethe $</function></entry>
+  <entry spanname='s1' align='left'>Notes based on <function>$Id: serial.c 4405 2007-07-27 16:16:09Z ckuethe $</function></entry>
 </row>
 </tfoot>
 
diff --git a/doc/explan_wrapup.xml b/doc/explan_wrapup.xml
index 9e833538..74958499 100644
--- a/doc/explan_wrapup.xml
+++ b/doc/explan_wrapup.xml
@@ -2,5 +2,5 @@
 <para>Mick Durkin
 &lt;mick.durkin@saunalahti.fi&gt;</para>
 <para>Helsinki</para>
-<para>March 2007</para>
+<para>November 2007</para>
 </sect1>
diff --git a/doc/explanation.xml b/doc/explanation.xml
index d51cc9a9..ac415648 100644
--- a/doc/explanation.xml
+++ b/doc/explanation.xml
@@ -42,10 +42,10 @@
 </author>
 <revhistory>
    <revision>
-      <revnumber>1.0</revnumber>
-      <date>20 March 2007</date>
+      <revnumber>2.0</revnumber>
+      <date>14 November 2007</date>
       <authorinitials>md</authorinitials>
-      <revremark>Initial draft</revremark>
+      <revremark>Updated to version 4420</revremark>
    </revision>
 </revhistory>
 
@@ -84,4 +84,4 @@
 &subframe.c;
 &timebase.h;
 &wrapup;
-</article>
\ No newline at end of file
+</article>