Provided by: gpsd_2.30-1ubuntu3_i386 bug

NAME

       libgpsd - service library for GPS applications

SYNOPSIS

       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);

       void gpsd_report (int d, const char * fmt, ...);

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 low-level interface, 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.

       You may optionally specify a DGPS server, either as a string containing
       a  server name or a string containining server name followed by a colon
       and a port name or number. To specify no DGPS, pass the null pointer.

       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; it defaults
              to /dev/gps.

       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, the length  of  the
              sentence, and a rawness level.

       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. Use first argument of 0 for errors,  1  for  ordinary  status
       messages, and 2 or higher for debugging messages.

       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), xgps(1), libgpsd(3).

AUTHOR

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

                                  14 Aug 2004                             3(3)