GPS manager library
===================

Application that needs GPS data can use this API to manage GPS daemon start
and stop. This is needed in small handhelds where it is not good to have gpsd
running all the time (because of battery and memory constraints) and to
guarantee that only one gpsd process is running simultaneously even if multiple
processes need the GPS data.

The idea of the API is to allow multiple applications to use gpsd services
but only when there is at least one application that needs GPS data. If
no application is running, the gpsd is not started at all or gpsd stops itself
automatically (to save memory and battery life).

The client API contains following functions:

int gpsmgr_start(char *path, char **gps_device, char *ctrl_sock, int debug_level,
                 short port, gpsmgr_t *ctx);
  - starts gpsd if it is not running
  - path points to gpsd location, if it does not start with '/' then $PATH
    is used when searching the gpsd executable location
  - the API daemonizes the gpsd (uses fork/exec system call combination)
  - returns 0 if everything was ok, other value indicates error
    (see errno for more details)

int gpsmgr_stop(gpsmgr_t *ctx);
  - stops gpsd if it was running and there were no other application
    that wishes to use gpsd services, uses kill system call
  - ctx is the context returned in gpsmgr_start()
  - returns 0 if everything is ok, other value indicates error
    (see errno for more details)

int gpsmgr_is_gpsd_running(gpsmgr_t *ctx, int *num_of_clients, int mode);
  - can be called (optional) periodically in application in order to
    check if the gpsd is running and how many other processes are using
    gpsd service at the moment
  - returns 0 if gpsd is not running or error happed, 1 if gpsd is
    running, 2 if gpsd was not running but it can be started now
  - mode parameter has following semantics
       * if set to GPSMGR_MODE_JUST_CHECK, then the library just checks
       * if the gpsd is running. The value GPSMGR_MODE_LOCK_IF_POSSIBLE
       * means that the library locks the gpsd lockfile (which means
       * that gpsd is running) if the gpsd is not yet running. In this case
       * the caller should call gpsmgr_start() to really start the gpsd.
  - The return value 2 is only returned if mode is GPSMGR_MODE_LOCK_IF_POSSIBLE


Following test programs are provided:

  gpsmgr_test
      - simulates application, uses start() and stop() functions
      - starts gpsd simulator (gpsd_sim)

  gpsd_sim
      - dummy gpsd process, does nothing but loop

  check_lock
      - print currently active locks that the API is using


$Id:$

