14 Aug 2004
3 3 The GPSD Project GPSD Documentation
libgpsd service library for GPS applications

    C:

    #include <gpsd.h>

int `gpsd_open_dgps` char * dgpsserver void `gpsd_init` struct gps_device_t *session struct * gps_context_t * char * device int `gpsd_activate` struct gps_device_t *session void `gpsd_deactivate` struct gps_device_t * session gps_mask_t `gpsd_poll` struct gps_device_t * session void `gpsd_wrap` struct gps_device_t * session

## DESCRIPTION

libgpsd is a service library which supports querying GPS devices; link it with the linker option -lgpsd. It is a set of low-level device-handling calls, which gpsd 1 itself uses. See gpsd 3 for a description of the high-level interface, which is almost certainly what you want.

Calling `gpsd_init()` initializes a session structure to hold the data collected by the GPS.

The second argument must be a context structure. The library will use it for information that need to be shared between sessions; presently this includes the leap-second correction and possibly a pointer to a shared-memory segment used to communicate with the Network Time Protocol daemon.

After the session structure has been set up, you may modify some of its members.

gpsd_device

  This member should hold the path name of the device.

baudrate

  Communication speed in bits per second. For NMEA or SiRF devices, the library automatically hunts through all plausible baud rates, stopping on the one where it sees valid packets. By setting this field you can designate a speed to be tried at the front of the hunt queue

raw_hook

  A hook function to be executed on each NMEA sentence or as it is read from the GPS. The data from non-NMEA GPSes like the EarthMate will be translated to an NMEA sentence before being passed to the hook. Parameters are a pointer to a gps_data structure full of parsed data, the sentence, and the length of the sentene..

`gpsd_activate()` initializes the connection to the GPS. `gpsd_deactivate()` closes the connection. These functions are provided so that long-running programs can release a connection when there is no activity requiring the GPS, and re-acquire it later.

`gpsd_poll()` queries the GPS and updates the part of the session structure that holds position, speed, GPS signal quality, and other data returned by the GPS. It returns a mask describing which fields have changed.

`gpsd_wrap()` ends the session, implicitly performing a `gpsd_deactivate()`.

The calling application must define one additional function: `gpsd_report()`. The library will use this to issue ordinary status messages. See `gpsd.h` in the source distribution for the set of logging levels.

The low-level functions do not allocate or free any dynamic storage. They can thus be used in a long-running application (such as gpsd 8 itself) with a guarantee that they won't cause memory leaks.

## BUGS

Writes to the context structure members are not guarded by a mutex.

## SEE ALSO

gpsd 8, gps 1, libgps 3.

## AUTHOR

Eric S. Raymond <esr@thyrsus.com> based partly on earlier work by Remco Treffkorn, Derrick Brashear, and Russ Nelson.