Provided by: gpsd_2.30-1ubuntu3_i386 bug

NAME

       libgps - C service library for communicating 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);

       void gps_set_callback (struct gps_data_t *gpsdata,
                              void (*callback)(struct gps_data_t *sentence, char *buf),
                              pthread_t *handler);

       void gps_del_callback (struct gps_data_t *gpsdata, pthread *handler);

       void rtcm_unpack (struct rtcm_t *rtcmp, char *buf);

                         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_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). gpsd_poll() returns the validity mask of the
       received structure. This function does a blocking read waiting for data
       from  the  daemon; it returns 0 for success, or -1 on a Unix-level read
       error.

       gpsd_query() writes  a  command  to  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 0 on success, or a -1 if there was a Unix-level
       read error.

       gps_set_raw_hook()   takes   a   function   you   specify  and  run  it
       (synchronously) on the raw data pulled by a gpsd_query() or gpsd_poll()
       call.  The  arguments  passed  to  this  hook  will  be  a pointer to a
       structure containing parsed data, and a  buffer  containining  the  raw
       gpsd response.

       gps_set_callback()   takes   a   function   you   specify  and  run  it
       asynchronously each time  new  data  arrives  from  gpsd,  using  POSIX
       threads.   For   example,   you   can   call  gps_set_callback(gpsdata,
       my_function, handler) once in your program,  and  from  there  on  your
       gpsdata  structure  will  be parsed by your my_function() each time new
       data are available. my_function() could change some global variables in
       your  program  based  on  received  data;  it is your responsibility to
       ensure that your program uses mutexes or other mechanisms to avoid race
       conditions.

       gps_del_callback()  deregisters  the  callback  function previously set
       with gps_set_callback().  After  the  invocation  of  this  funcion  no
       operation will be done when new data arrives.

       Consult  gps.h  to  learn  more  about  the data members and associated
       timestamps. Note  that  information  will  accumulate  in  the  session
       structure  over time, and the ’valid’ field is not automatically zeroed
       by each poll.  It  is  up  to  the  client  to  zero  that  field  when
       appropriate and to keep an eye on the fix and sentence timestamps.

       The  rtcm_unpack() will be useful when you are connected to an RTCM-104
       source in raw mode. Use it as part of a raw hook, calling it  with  the
       address  of  the struct rtcm_t element of your session structure buffer
       as first argument and the buffer as the second. It will unpack  a  line
       of  RTCM  data  into the structure. This function returns 0 when it has
       read the last line of an RTCM-104  message,  a  positive  int  when  it
       expects  more dump lines, and a negative int on parse failure. You must
       zero out the struct rtcm_t each time before this function is called  on
       a  new  header  (H)  line, as it relies on the message type field being
       initially zero and uses it to track what  kind  of  following  line  is
       expected.

       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, and have the same
       names as the corresponding C functions. Resources  within  the  session
       object will be properly released when it is garbage-collected.

CODE EXAMPLE

       The  following  is  an  excerpted  and simplified version of the libgps
       interface code from xgps(1). The function handle_input() is  a  trivial
       pies of code that calls gps_poll(gpsdata).

           gpsdata = gps_open(server, port);

           build_gui(toplevel);

           gps_set_raw_hook(gpsdata, update_panel);

           (void)gps_query(gpsdata, "w+x\n");

           (void)XtAppAddInput(app, gpsdata->gps_fd,
                   (XtPointer)XtInputReadMask, handle_input, NULL);
           (void)XtAppMainLoop(app);

           (void)gps_close(gpsdata);

SEE ALSO

        gpsd(8), xgps(1), libgps(3). libgpsmm(3).

AUTHOR

       Eric  S.  Raymond  <esr@thyrsus.com>,  Thread-callback methods in the C
       binding added by Alfredo Pironti <alfredio@users.sourceforge.net>.

                                  14 Aug 2004                             3(3)