diff options
| -rw-r--r-- | libgps.xml | 15 | ||||
| -rw-r--r-- | www/client-howto.txt | 12 |
2 files changed, 19 insertions, 8 deletions
@@ -126,14 +126,19 @@ error, -1 with errno not set if the socket to the daemon has closed, and 0 if no data is available.</para> <para><function>gps_waiting()</function> can be used to check whether -there is data from the daemon. The second argument is the maximum amount of -time to wait (in microseconds) on input before returning. It returns true if there -input waiting, false on timeout (no data waiting) or error -condition. This function is a convenience wrapper around a +there is data from the daemon. The second argument is the maximum +amount of time to wait (in microseconds) on input before returning. +It returns true if there input waiting, false on timeout (no data +waiting) or error condition. This function is a convenience wrapper +around a <citerefentry><refentrytitle>select</refentrytitle><manvolnum>2</manvolnum></citerefentry> call, and zeros <varname>errno</varname> on entry; you can test <varname>errno</varname> after exit to get more information about -error conditions.</para> +error conditions. Note that choosing a wait timeout of less than twice +the cycle time of your device will be hazardous, as the receiver probably +will not supply input often enough to prevent a spurious error indication. +For the typical 1-second cycle time of GPSes this implies a minimum 2-second +timeout.</para> <para><function>gps_stream()</function> asks <application>gpsd</application> to stream the reports it has at you, diff --git a/www/client-howto.txt b/www/client-howto.txt index 204ef755..9d5a9ffc 100644 --- a/www/client-howto.txt +++ b/www/client-howto.txt @@ -317,7 +317,12 @@ Each library has the following entry points: you have probably failed to understand the rest of the interface. * Nonblocking check to see if data from the daemon is waiting. Named - something like "waiting()". + something like "waiting()" and taking a wait timeout as argument. + Note that choosing a wait timeout of less than twice the cycle time + of your device will be hazardous, as the receiver will probably not + supply input often enough to prevent a spurious error indication. + For the typical 1-second cycle time of GPSes this implies a minimum + 2-second timeout. * Blocking read for data from the daemon. Named something like "read()" (this was "poll()" in older versions). @@ -401,8 +406,9 @@ non-blocking. This would only be appropriate for a batch-mode report generator. cgps.c shows what an interactive application using the library and -also processing user commands works. Observe the use of select(2) -to wait on either data from the daemon or a keystroke. +also hw processing user commands works. Note the use of the curses +nodelay function to ensure that wgetch() does not block the GPS +polling loop. == C++ examples == |