3(3)

NAME
libgps - service library for communicationg with the GPS daemon

SYNOPSIS

C:

#include <gps.h>

struct gps_data_t *gps_open (char *server, char * port);

int gps_query (struct gps_data_t *gpsdata, char *requests);

void gps_set_raw_hook (struct gps_data_t *gpsdata, void (*hook)(struct gps_data_t *, char *buf));

int gps_poll (struct gps_data_t *gpsdata);

void gps_close (struct gps_data_t *gpsdata);

Python:

import gps

session = gps.gps(host="localhost", port="2947")

session.set_raw_hook(raw_hook)

session.query(commands)

session.poll()

del session

DESCRIPTION

libgps is a service library which supports querying GPS devices; link it with the linker option -lgps. There are two interfaces supported in it; one high-level interface that goes through gpsd(1) and is intended for concurrent use by several applications, and one low-level interface that speaks directly with the serial or USB device to which the GPS is attached. This page describes the high-level interface that is safe for multiple applications to use simultaneously; it is probably the one you want. The low-level interface is documented at libgps(3).

Calling gpsd_open() initializes a GPS-data structure to hold the data collected by the GPS, and returns a socket attached to gpsd(1). gpsd_open() returns NULL on errors. errno is set depending on the error returned from the the socket layer; see gps.h for values and explanations.

gpsd_close() ends the session.

gpsd_query() queries the daemon, accepts a one-line response, and updates parts of the GPS-data structure that correspond to data changed since the last call. The second argument must be a string containing letters from the command set documented at gpsd(1). This function returns a 1 if any data changed since the last query, a 0 if no data changed, or a -1 if there was a Unix-level read error.

gpsd_poll() accepts a response, or sequence of responses, from the daemon and interprets it as though it were a query response (the return value is as for a query). It is meant to be used after the user has issued an 'R' or 'W' command with gpsd_query(), telling the daemon to stream updates to the client. gpsd_poll() returns -1 if there was an error, 0 if no data was read or no changes or 1 if gpsdata has changes.

Several member groups within the GPS-data structure have last-modified timestamps and change-flag members associated with them; these get updated on each query or poll as well. Consult gps.h to learn about the data members and associated timestamps.

The Python implementation supports the same facilities as the C library. gps_open() is replaced by the initialization of a gps session object; the other calls are methods of that object. Resources within the session object will be properly released when it is garbage-collected.

SEE ALSO

 gpsd(1) libgps(3)

AUTHOR

Eric S. Raymond <esr@thyrsus.com>.