Polish ppscheck.

2 files changed, 24 insertions, 7 deletions

diff --git a/contrib/README b/contrib/README
index 133c3875..849bae44 100644
--- a/contrib/README
+++ b/contrib/README
@@ -50,5 +50,5 @@ ppscheck watches a specified serial device for changes in handshake lines
 CD, RI, and CTS by running ioctl(...., TIOCMIWAIT, ...) in a loop.  When it
 sees a state change it emits a timestamped line of output dumping the state
 of the handshake signals. It's useful for checking whether a device is
-emitting 1PPS.
+emitting 1PPS.  There is troubleshooting advice in the header comment.
   
diff --git a/contrib/ppscheck.c b/contrib/ppscheck.c
index 6b2d2255..93625d53 100644
--- a/contrib/ppscheck.c
+++ b/contrib/ppscheck.c
@@ -1,5 +1,23 @@
 /*
  * Watch a specified serial port for transitions that might be 1PPS.
+ *
+ * Each output line is the second and nanosecond parts of a timestamp
+ * followed by the names of handshake signals then asserted.  Off 
+ * transitions may generate lines with no signals aserted.
+ *
+ * If you don't see output within a second, use gpsmon or some other
+ * equivalent tool to check that your device has satellite lock and is
+ * getting fixes before giving up on the possibility of 1PPS.
+ *
+ * Also, check your cable. Cheap DB9 to DB9 cables such as those
+ * issued with UPSes often carry TXD/RXD/SG only, omitting handshake
+ * lines such as DCD.  Suspect this especially if the cable jacket
+ * looks too skinny to hold more than three leads!
+ *
+ * This code requires only ANSI/POSIX. If it doesn't compile and run
+ * on your Unix there is something very wrong with your Unix.
+ *
+ * This code by ESR, Copyright (C) 2013, under BSD terms.
  */
 #include <stdio.h>
 #include <string.h>
@@ -31,7 +49,7 @@ struct assoc {
  *  4    20    DTR  --> Data Terminal Ready
  *  1     8    DCD  <-- Data Carrier Detect
  *  9    22    RI   <-- Ring Indicator
- *  5     7    SG       Signal ground
+ *  5     7    GND      Signal ground
  */
 const static struct assoc hlines[] = {
     {TIOCM_CD, "TIOCM_CD"},
@@ -40,7 +58,6 @@ const static struct assoc hlines[] = {
     {TIOCM_CTS, "TIOCM_CTS"},
 };
 
-
 int main(int argc, char *argv[])
 {
     struct timespec ts;
@@ -53,8 +70,6 @@ int main(int argc, char *argv[])
 	return 1;
     }
 
-    (void)printf("Beginning wait...\n");
-
     for (;;) {
 	if (ioctl(fd, TIOCMIWAIT, TIOCM_CD|TIOCM_DSR|TIOCM_CAR|TIOCM_RI|TIOCM_CTS) != 0) {
 	    (void)fprintf(stderr,
@@ -65,8 +80,8 @@ int main(int argc, char *argv[])
 	    const struct assoc *sp;
 	    int handshakes;
 
-	    clock_gettime(CLOCK_REALTIME, &ts);
-	    ioctl(fd, TIOCMGET, &handshakes);
+	    (void)clock_gettime(CLOCK_REALTIME, &ts);
+	    (void)ioctl(fd, TIOCMGET, &handshakes);
 	    (void)fprintf(stdout, "%10ld %10ld", ts.tv_sec, ts.tv_nsec);
 	    for (sp = hlines;
 		 sp < hlines + sizeof(hlines)/sizeof(hlines[0]);
@@ -79,3 +94,5 @@ int main(int argc, char *argv[])
 	}
     } 
 }
+
+/* end */