13(3) GPSD Documentation 3(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);
15 int gps_send(struct gps_data_t *gpsdata, char *fmt...);
17 int gps_read(struct gps_data_t *gpsdata);
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 intflags,
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:
38 import gps
40 session = gps.gps(host="localhost", port="2947")
42 session.stream(flags=gps.WATCH_JSON)
44 for report in session:
46 process(report)
47 del session
49
52 libgps is a service library which supports communicating with an
53 instance of the gpsd(8); link it with the linker option -lgps.
54 Warning
56 Take care to conditionalize your code on the major and minor API
57 version symbols in gps.h; ideally, force a compilation failure if
58 GPSD_API_MAJOR_VERSION is not a version you recognize. See the GPSD
59 project website for more information on the protocol and API
60 changes.
61 Calling gps_open() initializes a GPS-data structure to hold the data
63 collected by the GPS, and sets up access to gpsd(1) via either the
64 socket or shared-memory export. The shared-memory export is faster, but
65 does not carry information about device activation and deactivation
66 events and will not allow you to monitor device packet traffic.
67 gps_open() returns 0 on success, -1 on errors and is re-entrant. errno
69 is set depending on the error returned from the socket or shared-memory
70 interface; see gps.h for values and explanations; also see
71 gps_errstr(). The host address may be a DNS name, an IPv4 dotted quad,
72 an IPV6 address, or the special value GPSD_SHARED_MEMORY referring to
73 the shared-memory export; the library will do the right thing for any
74 of these.
75 gps_close() ends the session and should only be called after a
77 successful gps_open(). It returns 0 on success, -1 on errors. The
78 shared-memory interface close always returns 0, whereas a socket close
79 can result in an error. For a socket close error it will have set an
80 errno from the call to the system's close().
81 gps_send() writes a command to the daemon. It does nothing when using
83 the shared-memory export. The second argument must be a format string
84 containing elements from the command set documented at gpsd(1). It may
85 have % elements as for sprintf(3), which will be filled in from any
86 following arguments. This function returns a -1 if there was a
87 Unix-level write error, otherwise 0. Please read the LIMITATIONS
88 section for additional information and cautions. See gps_stream() as a
89 possible alternative.
90 gps_read() accepts a response, or sequence of responses, from the
92 daemon and interprets. This function does either a nonblocking read for
93 data from the daemon or a fetch from shared memory; it returns a count
94 of bytes read for success, -1 with errno set on a Unix-level read
95 error, -1 with errno not set if the socket to the daemon has closed or
96 if the shared-memory segment was unavailable, and 0 if no data is
97 available.
98 gps_waiting() can be used to check whether there is new data from the
100 daemon. The second argument is the maximum amount of time to wait (in
101 microseconds) on input before returning. It returns true if there is
102 input waiting, false on timeout (no data waiting) or error condition.
103 When using the socket export, this function is a convenience wrapper
104 around a select(2) call, and zeros errno on entry; you can test errno
105 after exit to get more information about error conditions. Warning:
106 under the shared-memory interface there is a tiny race window between
107 gps_waiting() and a following gps_read(); in that context, because the
108 latter does not block, it is probably better to write a simple read
109 loop.
110 gps_mainloop() enables the provided hook function to be continually
112 called whenever there is gpsd data. The second argument is the maximum
113 amount of time to wait (in microseconds) on input before exiting the
114 loop (and return a value of -1). It will also return a negative value
115 on various errors.
116 gps_unpack() parses JSON from the argument buffer into the target of
118 the session structure pointer argument. Included in case your
119 application wishes to manage socket I/O itself.
120 gps_data() returns the contents of the client data buffer (it returns
122 NULL when using the shared-memory export). Use with care; this may fail
123 to be a NUL-terminated string if WATCH_RAW is enabled.
124 gps_stream() asks gpsd to stream the reports it has at you, to be made
126 available when you poll (not available when using the shared-memory
127 export). The second argument is a flag mask that sets various policy
128 bits; see the list below. Calling gps_stream() more than once with
129 different flag masks is allowed.
130 WATCH_DISABLE
132 Disable the reporting modes specified by the other WATCH_ flags.
133 WATCH_ENABLE
135 Disable the reporting modes specified by the other WATCH_ flags.
136 This is the default.
137 WATCH_JSON
139 Enable JSON reporting of data. If WATCH_ENABLE is set, and no other
140 WATCH flags are set, this is the default.
141 WATCH_NMEA
143 Enable generated pseudo-NMEA reporting on binary devices.
144 WATCH_RARE
146 Enable reporting of binary packets in encoded hex.
147 WATCH_RAW
149 Enable literal passthrough of binary packets.
150 WATCH_SCALED
152 When reporting AIS or Subframe data, scale integer quantities to
153 floats if they have a divisor or rendering formula associated with
154 them.
155 WATCH_NEWSTYLE
157 Force issuing a JSON initialization and getting new-style
158 responses. This is the default.
159 WATCH_OLDSTYLE
161 Force issuing a W or R command and getting old-style responses.
162 Warning: this flag (and the capability) will be removed in a future
163 release.
164 WATCH_DEVICE
166 Restrict watching to a specified device, path given as second
167 argument.
168 gps_errstr() returns an ASCII string (in English) describing the error
170 indicated by a nonzero return value from gps_open().
171 Consult gps.h to learn more about the data members and associated
173 timestamps. Note that information will accumulate in the session
174 structure over time, and the 'valid' field is not automatically zeroed
175 by each gps_read(). It is up to the client to zero that field when
176 appropriate and to keep an eye on the fix and sentence timestamps.
177 The Python implementation supports the same facilities as the
179 socket-export calls in the C library; there is no shared-memory
180 interface. gps_open() is replaced by the initialization of a gps
181 session object; the other calls are methods of that object, and have
182 the same names as the corresponding C functions. However, it is simpler
183 just to use the session object as an iterator, as in the example given
184 below. Resources within the session object will be properly released
185 when it is garbage-collected.
186
188 By setting the environment variable GPSD_SHM_KEY, you can control the
189 key value used to create shared-memory segment used for communication
190 with gpsd. This will be useful mainly when isolating test instances of
191 gpsd from production ones.
192
194 The following is an excerpted and simplified version of the libgps
195 interface code from cgps(1).
196 struct gps_data_t gps_data;
198 ret = gps_open(hostName, hostPort, &gps_data);
200 (void) gps_stream(&gps_data, WATCH_ENABLE | WATCH_JSON, NULL);
202 /* Put this in a loop with a call to a high resolution sleep () in it. */
204 if (gps_waiting (&gps_data, 500)) {
205 errno = 0;
206 if (gps_read (&gps_data) == -1) {
207 ...
208 } else {
209 /* Display data from the GPS receiver. */
210 if (gps_data.set & ...
211 }
212 }
213 /* When you are done... */
215 (void) gps_stream(&gps_data, WATCH_DISABLE, NULL);
216 (void) gps_close (&gps_data);
217
219 On some systems (those which do not support implicit linking in
220 libraries) you may need to add -lm to your link line when you link
221 libgps. It is always safe to do this.
222 In the C API, incautious use of gps_send() may lead to subtle bugs. In
224 order to not bloat struct gps_data_t with space used by responses that
225 are not expected to be shipped in close sequence with each other, the
226 storage for fields associated with certain responses are combined in a
227 union.
228 The risky set of responses includes VERSION, DEVICELIST, RTCM2, RTCM3,
230 SUBFRAME, AIS, GST, and ERROR; it may not be limited to that set. The
231 logic of the daemon's watcher mode is careful to avoid dangerous
232 sequences, but you should read and understand the layout of struct
233 gps_data_t before using gps_send() to request any of these responses.
234
236 The gps_query() supported in major versions 1 and 2 of this library has
237 been removed. With the new streaming-oriented wire protocol behind this
238 library, it is extremely unwise to assume that the first transmission
239 from the daemon after a command is shipped to it will be the response
240 to command.
241 If you must send commands to the daemon explicitly, use gps_send() but
243 beware that this ties your code to the GPSD wire protocol. It is not
244 recommended.
245 In earlier versions of the API gps_read() was a blocking call and there
247 was a POLL_NONBLOCK option to make it nonblocking. gps_waiting() was
248 added to reduce the number of wrong ways to code a polling loop.
249 See the comment above the symbol GPSD_API_MAJOR_VERSION in gps.h for
251 recent changes.
252
254 gpsd(8), gps(1), libgpsmm(3).
255
257 Eric S. Raymond <esr@thyrsus.com>, C sample code Charles Curley
258 <charlescurley@charlescurley.com>
259The GPSD Project 14 Aug 2004 3(3)