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