1LIBGPS(3)                     GPSD Documentation                     LIBGPS(3)
2
3
4

NAME

6       libgps - C service library for communicating with the GPS daemon
7

SYNOPSIS

9       C:
10
11       #include <gps.h>
12
13
14       int gps_open(char *server, char *port, struct gps_data_t *gpsdata);
15
16       int gps_send(struct gps_data_t *gpsdata, char *fmt...);
17
18       int gps_read(struct gps_data_t *gpsdata, char *message,
19                    int message_size);
20
21       bool gps_waiting(const struct gps_data_t *gpsdata, int timeout);
22
23       char *gps_data(const struct gps_data_t *gpsdata);
24
25       int gps_unpack(char *buf, struct gps_data_t *gpsdata);
26
27       int gps_close(struct gps_data_t *gpsdata);
28
29       int gps_stream(struct gps_data_t *gpsdata, unsigned intflags,
30                      void *data);
31
32       int gps_mainloop(struct gps_data_t *gpsdata, int timeout,
33                        void (*hook)(struct gps_data_t *gpsdata));
34
35       const char *gps_errstr(int err);
36
37
38                              Python:
39
40                              import gps
41
42                              session = gps.gps(host="localhost", port="2947")
43
44                              session.stream(flags=gps.WATCH_JSON)
45
46                              for report in session:
47                                  process(report)
48
49                              del session
50
51

DESCRIPTION

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
56           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
63       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
69       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
77       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
83       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
92       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
100       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
112       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
118       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
122       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
126       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
132       WATCH_DISABLE
133           Disable the reporting modes specified by the other WATCH_ flags.
134
135       WATCH_ENABLE
136           Enable the reporting modes specified by the other WATCH_ flags.
137           This is the default.
138
139       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
143       WATCH_NMEA
144           Enable generated pseudo-NMEA reporting on binary devices.
145
146       WATCH_RARE
147           Enable reporting of binary packets in encoded hex.
148
149       WATCH_RAW
150           Enable literal passthrough of binary packets.
151
152       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
157       WATCH_NEWSTYLE
158           Force issuing a JSON initialization and getting new-style
159           responses. This is the default.
160
161       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
166       WATCH_DEVICE
167           Restrict watching to a specified device. The device path string is
168           given as the third argument (data).
169
170       gps_errstr() returns an ASCII string (in English) describing the error
171       indicated by a nonzero return value from gps_open().
172
173       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
179       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

ENVIRONMENT VARIABLES

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

CODE EXAMPLE

195       The following is an excerpted and simplified version of the libgps
196       interface code from cgps(1).
197
198               struct gps_data_t gps_data;
199
200               ret = gps_open(hostName, hostPort, &gps_data);
201
202               (void) gps_stream(&gps_data, WATCH_ENABLE | WATCH_JSON, NULL);
203
204               /* 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
215               /* When you are done... */
216               (void) gps_stream(&gps_data, WATCH_DISABLE, NULL);
217               (void) gps_close (&gps_data);
218

LIMITATIONS

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
224       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
230       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

COMPATIBILITY

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
243       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
247       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
251       See the comment above the symbol GPSD_API_MAJOR_VERSION in gps.h for
252       recent changes.
253

SEE ALSO

255       gpsd(8), gps(1), libgpsmm(3).
256

AUTHOR

258       Eric S. Raymond <esr@thyrsus.com>, C sample code Charles Curley
259       <charlescurley@charlescurley.com>
260
261
262
263The GPSD Project                6 December 2020                      LIBGPS(3)
Impressum