Add gps_errstr() to the client API so client code doesn't have to

reinvent it all the time.  Use it in gpsmon.

12 files changed, 51 insertions, 96 deletions

diff --git a/cgps.c b/cgps.c
index 96481707..92116949 100644
--- a/cgps.c
+++ b/cgps.c
@@ -754,18 +754,9 @@ int main(int argc, char *argv[])
   /* Open the stream to gpsd. */
   /*@i@*/gpsdata = gps_open(source.server, source.port);
   if (!gpsdata) {
-    switch ( errno ) {
-    case NL_NOSERVICE:  err_str = "can't get service entry"; break;
-    case NL_NOHOST:     err_str = "can't get host entry"; break;
-    case NL_NOPROTO:    err_str = "can't get protocol entry"; break;
-    case NL_NOSOCK:     err_str = "can't create socket"; break;
-    case NL_NOSOCKOPT:  err_str = "error SETSOCKOPT SO_REUSEADDR"; break;
-    case NL_NOCONNECT:  err_str = "can't connect to host"; break;
-    default:		    err_str = "Unknown"; break;
-    }
     (void)fprintf( stderr,
 		   "cgps: no gpsd running or network error: %d, %s\n",
-		   errno, err_str);
+		   errno, netlib_errstr(errno));
     exit(2);
   }
 
diff --git a/gps.h b/gps.h
index cfdc8705..c04577b9 100644
--- a/gps.h
+++ b/gps.h
@@ -969,13 +969,14 @@ struct gps_data_t {
 #define WATCH_NEWSTYLE	0x10u	/* for test purposes only - will go away */
 
 extern /*@null@*/ struct gps_data_t *gps_open(const char *host, const char *port);
-int gps_close(struct gps_data_t *);
-int gps_query(struct gps_data_t *gpsdata, const char *fmt, ... );
-int gps_poll(struct gps_data_t *gpsdata);
-int gps_stream(struct gps_data_t *gpsdata, unsigned int flags);
-void gps_set_raw_hook(struct gps_data_t *gpsdata, void (*hook)(struct gps_data_t *sentence, char *buf, size_t len, int level));
-int gps_set_callback(struct gps_data_t *gpsdata, void (*callback)(struct gps_data_t *sentence, char *buf, size_t len, int level), pthread_t *handler);
-int gps_del_callback(struct gps_data_t *gpsdata, pthread_t *handler);
+extern int gps_close(struct gps_data_t *);
+extern int gps_query(struct gps_data_t *gpsdata, const char *fmt, ... );
+extern int gps_poll(struct gps_data_t *gpsdata);
+extern int gps_stream(struct gps_data_t *gpsdata, unsigned int flags);
+extern void gps_set_raw_hook(struct gps_data_t *gpsdata, void (*hook)(struct gps_data_t *sentence, char *buf, size_t len, int level));
+extern int gps_set_callback(struct gps_data_t *gpsdata, void (*callback)(struct gps_data_t *sentence, char *buf, size_t len, int level), pthread_t *handler);
+extern int gps_del_callback(struct gps_data_t *gpsdata, pthread_t *handler);
+extern char /*@observer@*/ *gps_errstr(const int);
 
 extern void gps_clear_fix(/*@ out @*/struct gps_fix_t *);
 extern void gps_merge_fix(/*@ out @*/struct gps_fix_t *,
@@ -1018,7 +1019,7 @@ extern int gps_unpack(char *, struct gps_data_t *);
 #define NL_NOPROTO	-3	/* can't get protocol entry */
 #define NL_NOSOCK	-4	/* can't create socket */
 #define NL_NOSOCKOPT	-5	/* error SETSOCKOPT SO_REUSEADDR */
-#define NL_NOCONNECT	-6	/* can't connect to host */
+#define NL_NOCONNECT	-6	/* can't connect to host/socket pair */
 
 #define DEFAULT_GPSD_PORT	"2947"	/* IANA assignment */
 #define DEFAULT_RTCM_PORT	"2101"	/* IANA assignment */
diff --git a/gpsctl.c b/gpsctl.c
index 0d2d3084..fb6c4bad 100644
--- a/gpsctl.c
+++ b/gpsctl.c
@@ -73,7 +73,7 @@ static void onsig(int sig)
 int main(int argc, char **argv)
 {
     int option, status;
-    char *err_str, *device = NULL, *devtype = NULL; 
+    char *device = NULL, *devtype = NULL; 
     char *speed = NULL, *control = NULL, *rate = NULL;
     bool to_binary = false, to_nmea = false, reset = false; 
     bool lowlevel=false, echo=false;
@@ -222,17 +222,8 @@ int main(int argc, char **argv)
 	/* Try to open the stream to gpsd. */
 	/*@i@*/gpsdata = gps_open(NULL, NULL);
 	if (gpsdata == NULL) {
-	    switch (errno) {
-	    case NL_NOSERVICE: err_str ="can't get service entry"; break;
-	    case NL_NOHOST:    err_str ="can't get host entry"; break;
-	    case NL_NOPROTO:   err_str ="can't get protocol entry"; break;
-	    case NL_NOSOCK:    err_str ="can't create socket"; break;
-	    case NL_NOSOCKOPT: err_str ="error SETSOCKOPT SO_REUSEADDR"; break;
-	    case NL_NOCONNECT: err_str ="can't connect"; break;
-	    default:           err_str ="Unknown"; break;
-	    } 
 	    gpsd_report(LOG_ERROR, "no gpsd running or network error: %s.\n", 
-			  err_str);
+			netlib_errstr(errno));
 	    lowlevel = true;
 	}
     }
diff --git a/gpsd.h-tail b/gpsd.h-tail
index c874faa7..d0c519f6 100644
--- a/gpsd.h-tail
+++ b/gpsd.h-tail
@@ -462,6 +462,7 @@ extern void gpsd_position_fix_dump(struct gps_device_t *, /*@out@*/char[], size_
 extern void gpsd_error_model(struct gps_device_t *, struct gps_fix_t *, struct gps_fix_t *);
 extern void gpsd_clear_data(struct gps_device_t *);
 extern int netlib_connectsock(const char *, const char *, const char *);
+extern char /*@observer@*/ *netlib_errstr(const int);
 extern char /*@observer@*/ *sock2ip(int);
 
 extern void ntpshm_init(struct gps_context_t *, bool);
diff --git a/gpsmon.c b/gpsmon.c
index 25293fdb..5df36f6c 100644
--- a/gpsmon.c
+++ b/gpsmon.c
@@ -172,8 +172,7 @@ static ssize_t readpkt(void)
 
     if (logfile != NULL) {
 	/*@ -shiftimplementation -sefparams +charint @*/
-	assert(fwrite(session.packet.outbuffer,
-		      sizeof(char), session.packet.outbuflen,
+	assert(fwrite(session.packet.outbuffer,		      sizeof(char), session.packet.outbuflen,
 		      logfile) >= 1);
 	/*@ +shiftimplementation +sefparams -charint @*/
     }
@@ -499,14 +498,15 @@ int main (int argc, char **argv)
     if (optind>=argc || source.device==NULL || strchr(argv[optind], ':')!=NULL) {
 
 	session.gpsdata.gps_fd = netlib_connectsock(source.server, source.port, "tcp");
-	if (session.gpsdata.gps_fd == -1) {
+	if (session.gpsdata.gps_fd < 0) {
 	    (void)fprintf(stderr,
-			  "%s: connection failure on %s:%s, error %d.\n",
-			  argv[0], source.server, source.port, session.gpsdata.gps_fd);
+			  "%s: connection failure on %s:%s, error %d = %s.\n",
+			  argv[0], source.server, source.port, session.gpsdata.gps_fd, netlib_errstr(session.gpsdata.gps_fd));
 	    exit(1);
 	}
 	controlfd = open(controlsock, O_RDWR);
 	/*@ -compdef @*/
+	// FIXME: This code needs to become protocol-agnostic
 	if (source.device != NULL)
 	    command((char *)buf, sizeof(buf), "F=%s\r\n", source.device);
 	else
diff --git a/gpxlogger.c b/gpxlogger.c
index edceb27f..fef55c50 100644
--- a/gpxlogger.c
+++ b/gpxlogger.c
@@ -283,33 +283,9 @@ static int socket_mainloop(void)
 
     gpsdata = gps_open(source.server, source.port);
     if (!gpsdata) {
-	char *err_str;
-	switch (errno) {
-	case NL_NOSERVICE:
-	    err_str = "can't get service entry";
-	    break;
-	case NL_NOHOST:
-	    err_str = "can't get host entry";
-	    break;
-	case NL_NOPROTO:
-	    err_str = "can't get protocol entry";
-	    break;
-	case NL_NOSOCK:
-	    err_str = "can't create socket";
-	    break;
-	case NL_NOSOCKOPT:
-	    err_str = "error SETSOCKOPT SO_REUSEADDR";
-	    break;
-	case NL_NOCONNECT:
-	    err_str = "can't connect to host";
-	    break;
-	default:
-	    err_str = "Unknown";
-	    break;
-	}
 	fprintf(stderr,
 		"%s: no gpsd running or network error: %d, %s\n",
-		progname, errno, err_str);
+		progname, errno, netlib_errstr(errno));
 	exit(1);
     }
 
diff --git a/lcdgps.c b/lcdgps.c
index 24cc8302..32989441 100644
--- a/lcdgps.c
+++ b/lcdgps.c
@@ -348,7 +348,6 @@ int main(int argc, char *argv[])
 {
     int option, rc;
     bool nojitter = false;
-    char *err_str = NULL;
     struct sockaddr_in localAddr, servAddr;
     struct hostent *h;
 
@@ -431,18 +430,9 @@ int main(int argc, char *argv[])
     /* Open the stream to gpsd. */
     /*@i@*/gpsdata = gps_open(source.server, source.port);
     if (!gpsdata) {
-	switch ( errno ) {
-	case NL_NOSERVICE:        err_str = "can't get service entry"; break;
-	case NL_NOHOST:   err_str = "can't get host entry"; break;
-	case NL_NOPROTO:  err_str = "can't get protocol entry"; break;
-	case NL_NOSOCK:   err_str = "can't create socket"; break;
-	case NL_NOSOCKOPT:        err_str = "error SETSOCKOPT SO_REUSEADDR"; break;
-	case NL_NOCONNECT:        err_str = "can't connect to host"; break;
-	default:                  err_str = "Unknown"; break;
-	}
 	(void)fprintf( stderr,
 		       "cgps: no gpsd running or network error: %d, %s\n",
-		       errno, err_str);
+		       errno, gps_errstr(errno));
 	exit(2);
     }
 
diff --git a/libgps.c b/libgps.c
index 2d038e9f..628a0b6a 100644
--- a/libgps.c
+++ b/libgps.c
@@ -588,6 +588,14 @@ int gps_del_callback(struct gps_data_t *gpsdata, pthread_t *handler)
 }
 #endif /* HAVE_LIBPTHREAD */
 
+extern char /*@observer@*/ *gps_errstr(const int err)
+{
+    /* 
+     * We might ad out own error codes in the future, e.g for
+     * protocol compatibility checks
+     */
+    return netlib_errstr(err); 
+}
 
 #ifdef TESTMAIN
 /*
diff --git a/libgps.xml b/libgps.xml
index 0b6756ee..a13d606c 100644
--- a/libgps.xml
+++ b/libgps.xml
@@ -66,6 +66,10 @@ C:
     <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
     <paramdef>unsigned int<parameter>flags</parameter></paramdef>
 </funcprototype>
+<funcprototype>
+<funcdef>char *<function>gps_errstr</function></funcdef>
+    <paramdef>int <parameter>err</parameter></paramdef>
+</funcprototype>
 <funcsynopsisinfo>
 
 Python:
@@ -184,6 +188,10 @@ function previously set with <function>gps_set_callback()</function>.
 After the invocation of this function no operation will be done when
 new data arrives.</para>
 
+<para><function>gps_errstr()</function> returns an ASCII string (in
+English) describing the error indicated by a nonzero return value from
+<function>gps_open()</function>.</para>
+
 <para>Consult <filename>gps.h</filename> to learn more about the data members 
 and associated timestamps.  Note that information will accumulate
 in the session structure over time, and the 'valid' field is not
diff --git a/netlib.c b/netlib.c
index 219ebd1d..5d97ebea 100644
--- a/netlib.c
+++ b/netlib.c
@@ -87,6 +87,19 @@ int netlib_connectsock(const char *host, const char *service, const char *protoc
     /*@ +type +mustfreefresh @*/
 }
 
+char /*@observer@*/ *netlib_errstr(const int err)
+{
+    switch (err) {
+    case NL_NOSERVICE:  return "can't get service entry"; break;
+    case NL_NOHOST:     return "can't get host entry"; break;
+    case NL_NOPROTO:    return "can't get protocol entry"; break;
+    case NL_NOSOCK:     return "can't create socket"; break;
+    case NL_NOSOCKOPT:  return "error SETSOCKOPT SO_REUSEADDR"; break;
+    case NL_NOCONNECT:  return "can't connect to host/port pair"; break;
+    default:		return "unknown error"; break;
+    }
+}
+
 char *sock2ip(int fd)
 {
     struct sockaddr fsin;
diff --git a/www/faq.html b/www/faq.html
index f56d29e8..46b9a5da 100644
--- a/www/faq.html
+++ b/www/faq.html
@@ -64,7 +64,7 @@ GPSD Frequently Asked Questions
 <ul>
 <li><a href='#bug-reporting'>How do I report bugs in GPSD?</a><br/>
 <li><a href='#oldcommands'>Why does the first A,E,O,P,T,U, or V command to a device always return "?"</a><br/>
-<li><a href="singleshot">Why does my single-shot query fail to return fix data?</a><br/>
+<li><a href="#singleshot">Why does my single-shot query fail to return fix data?</a><br/>
 <li><a href='#speed'>Why does my receiver report wildly fluctuating speed?</a><br/>
 <li><a href='#gpsdrive'>Why do I get implausibly low speeds when using gpsdrive?</a><br/>
 <li><a href='#flicker'>Why does the date field in <code>xgps</code> flicker to "n/a" part of the time even when there's a fix?</a><br/>
diff --git a/xgps.c b/xgps.c
index 1c66f251..9f24651c 100644
--- a/xgps.c
+++ b/xgps.c
@@ -1036,40 +1036,16 @@ get_resource(Widget w, char *name, char *default_value)
 void
 handle_gps(XtPointer client_data UNUSED, XtIntervalId *ignored UNUSED)
 {
-	char *err_str = NULL;
 	char error[128];
 	static bool dialog_posted = false;
 
 	/*@i@*/gpsdata = gps_open(source.server, source.port);
 	if (!gpsdata) {
-		switch (errno ){
-		case NL_NOSERVICE:
-			err_str = "can't get service entry";
-			break;
-		case NL_NOHOST:
-			err_str = "can't get host entry";
-			break;
-		case NL_NOPROTO:
-			err_str = "can't get protocol entry";
-			break;
-		case NL_NOSOCK:
-			err_str = "can't create socket";
-			break;
-		case NL_NOSOCKOPT:
-			err_str = "error SETSOCKOPT SO_REUSEADDR";
-			break;
-		case NL_NOCONNECT:
-			err_str = "can't connect to host";
-			break;
-		default:
-			err_str = "Unknown";
-			break;
-		}
 		if (!gps_lost && !dialog_posted) {
 			(void)snprintf(error, sizeof(error),
 			    "No GPS data available.\n\n%s\n\n"
 			    "Check the connection to gpsd and if "
-			    "gpsd is running.", err_str);
+			    "gpsd is running.", gps_errstr(errno));
 			(void)err_dialog(toplevel, error);
 			dialog_posted = true;
 		}