1LIBGPS(3) GPSD Documentation LIBGPS(3)
2
6 libgps - C service library for communicating with the GPS daemon
7
9 C:
10 #include <gps.h>
12 int gps_open(char * server, char * port, struct gps_data_t * gpsdata)
14 int gps_send(struct gps_data_t * gpsdata, char * fmt, ...)
16 int gps_read(struct gps_data_t * gpsdata, char * message,
18 int message_size)
19 bool gps_waiting(const struct gps_data_t * gpsdata, int timeout)
21 char * gps_data(const struct gps_data_t * gpsdata)
23 int gps_unpack(char * buf, struct gps_data_t * gpsdata)
25 int gps_close(struct gps_data_t * gpsdata)
27 int gps_stream(struct gps_data_t * gpsdata, unsigned int flags,
29 void * data)
30 int gps_mainloop(struct gps_data_t * gpsdata, int timeout,
32 void (* hook)(struct gps_data_t *gpsdata))
33 const char * gps_errstr(int err)
35 Python:
37 import gps
39 session = gps.gps(host="localhost", port="2947")
40 session.stream(flags=gps.WATCH_JSON)
41 while 0 == session.read():
42 process(session)
43 del session
44
46 C
47 libgps is a service library which supports communicating with an
48 instance of the gpsd(8), link it with the linker option -lgps. Some
49 systems may also require -lm.
50 Warning
52 Take care to conditionalize your code on the major and minor API
53 version symbols in gps.h; ideally, force a compilation failure if
54 GPSD_API_MAJOR_VERSION is not a version you recognize. See the GPSD
55 project website for more information on the protocol and API
56 changes.
57 All the functions described here use the gps_data_t structure. Consult
59 gps.h to learn more about gps_data_t, its data members, associated
60 structures. associated timestamps. Note that information will
61 accumulate in the session structure over time, and the 'valid' field is
62 not automatically zeroed by each gps_read(). It is up to the client to
63 zero that field when appropriate and to keep an eye on the fix and
64 sentence timestamps.
65 Warning
67 gps_data_t sets floating point variables to NaN when the actual
68 variable value is unknown. Check all floats and doubles with
69 isfinite() before using them. isnan() is not sufficient!
70 gps_open()
72 Calling gps_open() initializes a gps_data_t structure to hold the
73 data collected by the GPS, and sets up access to gpsd(8) via either
74 the socket or shared-memory export. The shared-memory export is
75 faster, but does not carry information about device activation and
76 deactivation events and will not allow you to monitor device packet
77 traffic.
78 gps_open() returns 0 on success, -1 on errors and is re-entrant.
80 errno is set depending on the error returned from the socket or
81 shared-memory interface; see gps.h for values and explanations;
82 also see gps_errstr(). The host address may be a DNS name, an IPv4
83 dotted quad, an IPV6 address, or the special value
84 GPSD_SHARED_MEMORY referring to the shared-memory export; the
85 library will do the right thing for any of these.
86 gps_close()
88 gps_close() ends the session and should only be called after a
89 successful gps_open(). It returns 0 on success, -1 on errors. The
90 shared-memory interface close always returns 0, whereas a socket
91 close can result in an error. For a socket close error it will have
92 set an errno from the call to the system’s close().
93 gps_send()
95 gps_send() writes a command to the gpsd daemon. It does nothing
96 when using the shared-memory export. The second argument must be a
97 format string containing elements from the command set documented
98 at gpsd(8). It may have % elements as for sprintf(3), which will be
99 filled in from any following arguments. This function returns a -1
100 if there was a Unix-level write error, otherwise 0. Please read the
101 LIMITATIONS section for additional information and cautions. See
102 gps_stream() as a possible alternative.
103 gps_read()
105 gps_read() accepts a response, or sequence of responses, from the
106 gpsd daemon and decodes the response into a gps_data_t. By default,
107 this function does either a blocking read for data from the gpsd
108 daemon or a fetch from shared memory; it returns a count of bytes
109 read for success, -1 with errno set on a Unix-level read error, -1
110 with errno not set if the socket to the gpsd daemon has closed or
111 if the shared-memory segment was unavailable, and 0 if no data is
112 available.
113 The second argument to gps_read() is usually NULL, and the third
115 argument is zero. If your application wants to see the raw data
116 from the gpsd daemon then set the second argument to the address of
117 your message buffer, and the third argument is the size of your
118 buffer. Use with care; this may not to be a NUL-terminated string
119 if WATCH_RAW is enabled.
120 gps_waiting()
122 gps_waiting() can be used to check whether there is new data from
123 the gpsd daemon. The second argument is the maximum amount of time
124 to block (in microseconds) waiting on input before returning. It
125 returns true if there is input waiting, false on timeout (no data
126 waiting) or error condition. When using the socket export, this
127 function is a convenience wrapper around a select(2) call, and
128 zeros errno on entry; you can test errno after exit to get more
129 information about error conditions.
130 Warning: under the shared-memory interface there is a tiny race
132 window between gps_waiting() and a following gps_read(); in that
133 context, because the latter does not block, it is probably better
134 to write a simple read loop.
135 gps_mainloop()
137 gps_mainloop() enables the provided hook function to be continually
138 called whenever there is gpsd data. The second argument is the
139 maximum amount of time to wait (in microseconds) on input before
140 exiting the loop (and return a value of -1). It will also return a
141 negative value on various errors.
142 gps_unpack()
144 gps_unpack() parses JSON from the argument buffer into the target
145 of the session structure pointer argument. Included in case your
146 application wishes to manage socket I/O itself.
147 gps_data()
149 gps_data() returns the contents of the client data buffer (it
150 returns NULL when using the shared-memory export). Use with care;
151 this may not to be a NUL-terminated string if WATCH_RAW is enabled.
152 gps_stream()
154 gps_stream() asks gpsd to stream the reports it has at you, to be
155 made available when you poll (not available when using the
156 shared-memory export). The second argument is a flag mask that sets
157 various policy bits; see the list below. Calling gps_stream() more
158 than once with different flag masks is allowed.
159 WATCH_DEVICE
161 Restrict watching to a specified device. The device path string
162 is given as the third argument (data).
163 WATCH_DISABLE
165 Disable the reporting modes specified by the other WATCH_
166 flags.
167 WATCH_ENABLE
169 Enable the reporting modes specified by the other WATCH_ flags.
170 This is the default.
171 WATCH_JSON
173 Enable JSON reporting of data. If WATCH_ENABLE is set, and no
174 other WATCH flags are set, this is the default.
175 WATCH_NEWSTYLE
177 Force issuing a JSON initialization and getting new-style
178 responses. This is the default.
179 WATCH_NMEA
181 Enable generated pseudo-NMEA reporting on binary devices.
182 WATCH_OLDSTYLE
184 Force issuing a W or R command and getting old-style responses.
185 Warning: this flag (and the capability) will be removed in a
186 future release.
187 WATCH_RARE
189 Enable reporting of binary packets in encoded hex.
190 WATCH_RAW
192 Enable literal passthrough of binary packets.
193 WATCH_SCALED
195 When reporting AIS or Subframe data, scale integer quantities
196 to floats if they have a divisor or rendering formula
197 associated with them.
198 gps_errstr()
200 gps_errstr() returns an ASCII string (in English) describing the
201 error indicated by a nonzero return value from gps_open().
202 Python
204 The Python implementation supports the same facilities as the the C
205 library. gps_open() is replaced by the initialization of a gps session
206 object: session = gps.gps(...). The other calls are methods of that
207 object, and have the same names as the corresponding C functions.
208 In addtion to using gps.read() to read messages from gpsd, you can use
210 the session object as an iterator, as in the code fragment given below.
211 Python iterators implicitly call the function gps.\_\_next() which is
212 just a shim over gps.read(). There is other advantage to using the
213 implicit iterator and it does not allow the options that gps.read()
214 does.
215 import gps
217 session = gps.gps(host="localhost", port="2947")
218 session.stream(flags=gps.WATCH_JSON)
219 for report in session:
220 process(report)
221 del session
222 Resources within the session object will be properly released when it
224 is garbage-collected.
225 For further information on the Python gps module, read the comments in
227 the modules files. There is a complete Python example in the file
228 www/gpsd-client-example-code.adoc.
229
231 By setting the environment variable GPSD_SHM_KEY, you can control the
232 key value used to create shared-memory segment used for communication
233 with gpsd. This will be useful mainly when isolating test instances of
234 gpsd from production ones.
235
237 The following is a fully functional minimal C client. Check the C
238 source for the other gpsd clients for more ideas.
239 Unresolved directive in libgps.adoc - include::../www/example1.c.txt[]
241
243 On some systems (those which do not support implicit linking in
244 libraries) you may need to add -lm to your link line when you link
245 libgps. It is always safe to do this.
246 In the C API, incautious use of gps_send() may lead to subtle bugs. In
248 order to not bloat struct gps_data_t with space used by responses that
249 are not expected to be shipped in close sequence with each other, the
250 storage for fields associated with certain responses are combined in a
251 union.
252 The risky set of responses includes VERSION, DEVICELIST, RTCM2, RTCM3,
254 SUBFRAME, AIS, GST, and ERROR; it may not be limited to that set. The
255 logic of the gpsd daemon’s watcher mode is careful to avoid dangerous
256 sequences, but you should read and understand the layout of struct
257 gps_data_t before using gps_send() to request any of these responses.
258
260 The gps_query() supported in major versions 1 and 2 of this library has
261 been removed. With the new streaming-oriented wire protocol behind this
262 library, it is extremely unwise to assume that the first transmission
263 from the gpsd daemon after a command is shipped to it will be the
264 response to command.
265 If you must send commands to the gpsd daemon explicitly, use gps_send()
267 but beware that this ties your code to the GPSD wire protocol. It is
268 not recommended.
269 In some versions of the API gps_read() is a blocking call and there was
271 a POLL_NONBLOCK option to make it nonblocking. gps_waiting() was added
272 to reduce the number of wrong ways to code a polling loop.
273 See the comment above the symbol GPSD_API_MAJOR_VERSION in gps.h for
275 recent changes.
276
278 C sample code by Gary E. Miller gem@rellim.com and Charles Curley
279 charlescurley@charlescurley.com
280
282 gpsd(8), gps(1), gpsd_json(5), libgpsmm(3)
283
285 • GPSD Client Example Code
286 <https://gpsd.io/gpsd-client-example-code.html> An annotated
287 example client.
288 • GPSD Client HOWTO <https://gpsd.io/client-howto.html> A GPS client
290 HOWTO.
291 • Project web site: https://gpsd.io/
293
295 This file is Copyright 2013 by the GPSD project
296 SPDX-License-Identifier: BSD-2-clause
297
299 Eric S. Raymond
300GPSD, Version 3.25 2023-01-10 LIBGPS(3)