man: Move man pages, source and result, into main/

part of cleaning up the root directory.

1 files changed, 393 insertions, 0 deletions

diff --git a/man/libgps.xml b/man/libgps.xml
new file mode 100644
index 00000000..7e850c3d
--- /dev/null
+++ b/man/libgps.xml
@@ -0,0 +1,393 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+This file is Copyright (c) 2010 by the GPSD project
+SPDX-License-Identifier: BSD-2-clause
+-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<refentry>
+<refentryinfo><date>14 Aug 2004</date></refentryinfo>
+<refmeta>
+<refentrytitle>3</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo class="source">The GPSD Project</refmiscinfo>
+<refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>libgps</refname>
+<refpurpose>C service library for communicating with the GPS daemon</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+<funcsynopsis>
+<funcsynopsisinfo>
+
+C:
+
+#include &lt;gps.h&gt;
+
+</funcsynopsisinfo>
+<funcprototype>
+<funcdef>int <function>gps_open</function></funcdef>
+    <paramdef>char *<parameter>server</parameter></paramdef>
+    <paramdef>char * <parameter>port</parameter></paramdef>
+    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>int <function>gps_send</function></funcdef>
+    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
+    <paramdef>char *<parameter>fmt</parameter>...</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>int <function>gps_read</function></funcdef>
+    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>bool <function>gps_waiting</function></funcdef>
+    <paramdef>const struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
+    <paramdef>int <parameter>timeout</parameter></paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>char *<function>gps_data</function></funcdef>
+    <paramdef>const struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>int <function>gps_unpack</function></funcdef>
+    <paramdef>char *<parameter>buf</parameter></paramdef>
+    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>int <function>gps_close</function></funcdef>
+    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>int <function>gps_stream</function></funcdef>
+    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
+    <paramdef>unsigned int<parameter>flags</parameter></paramdef>
+    <paramdef>void *<parameter>data</parameter></paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>int <function>gps_mainloop</function></funcdef>
+    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
+    <paramdef>int <parameter>timeout</parameter></paramdef>
+    <paramdef>void (*<parameter>hook</parameter>)(struct gps_data_t *gpsdata)</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>const char *<function>gps_errstr</function></funcdef>
+    <paramdef>int <parameter>err</parameter></paramdef>
+</funcprototype>
+<funcsynopsisinfo>
+
+Python:
+
+import gps
+
+session = gps.gps(host="localhost", port="2947")
+
+session.stream(flags=gps.WATCH_JSON)
+
+for report in session:
+    process(report)
+
+del session
+
+</funcsynopsisinfo>
+</funcsynopsis>
+</refsynopsisdiv>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+
+<para><emphasis remap='B'>libgps</emphasis> is a service library which
+supports communicating with an instance of the
+<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum>
+</citerefentry>; link it with the linker option -lgps.</para>
+
+<warning><para>Take care to conditionalize your code on the major and
+minor API version symbols in <filename>gps.h</filename>; ideally,
+force a compilation failure if GPSD_API_MAJOR_VERSION is not a version
+you recognize.  See the GPSD project website for more information on
+the protocol and API changes.</para></warning>
+
+<para>Calling <function>gps_open()</function> initializes a GPS-data
+structure to hold the data collected by the GPS, and sets up access to
+<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum>
+</citerefentry>
+via either the socket or shared-memory export. The shared-memory
+export is faster, but does not carry information about device
+activation and deactivation events and will not allow you to monitor
+device packet traffic.</para>
+
+<para><function>gps_open()</function> returns 0 on success, -1 on
+errors and is re-entrant.  errno is set depending on the error
+returned from the socket or shared-memory interface; see
+<filename>gps.h</filename> for values and explanations; also see
+<function>gps_errstr()</function>. The host address may be a DNS name,
+an IPv4 dotted quad, an IPV6 address, or the special value
+<constant>GPSD_SHARED_MEMORY</constant> referring to the
+shared-memory export; the library will do the right thing for any of
+these.</para>
+
+<para><function>gps_close()</function> ends the session and should only be
+called after a successful <function>gps_open()</function>.
+It returns 0 on success, -1 on errors.  The shared-memory interface
+close always returns 0, whereas a socket close can result in an error.
+For a socket close error it will have set an errno from the call to the
+system's <function>close()</function>. </para>
+
+<para><function>gps_send()</function> writes a command to the daemon.
+It does nothing when using the shared-memory export.
+The second argument must be a format string containing elements from
+the command set documented at
+<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum>
+</citerefentry>.
+It may have % elements as for
+<citerefentry><refentrytitle>sprintf</refentrytitle><manvolnum>3</manvolnum>
+</citerefentry>,
+which will be filled in from any following arguments.  This function
+returns a -1 if there was a Unix-level write error, otherwise
+0. Please read the LIMITATIONS section for additional information and
+cautions. See <function>gps_stream()</function> as a possible
+alternative.</para>
+
+<para><function>gps_read()</function> accepts a response, or sequence
+of responses, from the daemon and interprets.  This function does
+either a nonblocking read for data from the daemon or a fetch from
+shared memory; it returns a count of bytes read for success, -1 with
+errno set on a Unix-level read error, -1 with errno not set if the
+socket to the daemon has closed or if the shared-memory segment was
+unavailable, and 0 if no data is available.</para>
+
+<para><function>gps_waiting()</function> can be used to check whether
+there is new data from the daemon. The second argument is the maximum
+amount of time to wait (in microseconds) on input before returning.
+It returns true if there is input waiting, false on timeout (no data
+waiting) or error condition. When using the socket export, this
+function is a convenience wrapper around a
+<citerefentry><refentrytitle>select</refentrytitle><manvolnum>2</manvolnum>
+</citerefentry>
+call, and zeros <varname>errno</varname> on entry; you can test
+<varname>errno</varname> after exit to get more information about
+error conditions.  Warning: under the shared-memory interface there is
+a tiny race window between <function>gps_waiting()</function> and a
+following <function>gps_read()</function>; in that context, because the
+latter does not block, it is probably better to write a simple read
+loop.</para>
+
+<para><function>gps_mainloop()</function> enables the provided hook
+function to be continually called whenever there is gpsd data.
+The second argument is the maximum amount of time to wait (in microseconds)
+on input before exiting the loop (and return a value of -1).
+It will also return a negative value on various errors.
+</para>
+
+<para><function>gps_unpack()</function> parses JSON from the argument
+buffer into the target of the session structure pointer argument.
+Included in case your application wishes to manage socket I/O
+itself.</para>
+
+<para><function>gps_data()</function> returns the contents of the
+client data buffer (it returns NULL when using the shared-memory
+export). Use with care; this may fail to be a NUL-terminated string if
+WATCH_RAW is enabled.</para>
+
+<para><function>gps_stream()</function> asks
+<application>gpsd</application> to stream the reports it has at you,
+to be made available when you poll (not available when using the
+shared-memory export). The second argument is a flag mask that sets
+various policy bits; see the list below.  Calling
+<function>gps_stream()</function> more than once with different flag
+masks is allowed.</para>
+
+<variablelist>
+<varlistentry>
+<term>WATCH_DISABLE</term>
+<listitem>
+<para>Disable the reporting modes specified by the other WATCH_ flags.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>WATCH_ENABLE</term>
+<listitem>
+<para>Disable the reporting modes specified by the other WATCH_ flags.
+This is the default.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>WATCH_JSON</term>
+<listitem>
+<para>Enable JSON reporting of data. If WATCH_ENABLE is set, and no
+other WATCH flags are set, this is the default.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>WATCH_NMEA</term>
+<listitem>
+<para>Enable generated pseudo-NMEA reporting on binary devices.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>WATCH_RARE</term>
+<listitem>
+<para>Enable reporting of binary packets in encoded hex.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>WATCH_RAW</term>
+<listitem>
+<para>Enable literal passthrough of binary packets.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>WATCH_SCALED</term>
+<listitem>
+<para>When reporting AIS or Subframe data, scale integer quantities to
+floats if they have a divisor or rendering formula associated with them.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>WATCH_NEWSTYLE</term>
+<listitem>
+<para>Force issuing a JSON initialization and getting new-style
+responses. This is the default. </para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>WATCH_OLDSTYLE</term>
+<listitem>
+<para>Force issuing a W or R command and getting old-style
+responses. Warning: this flag (and the capability) will be removed
+in a future release.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>WATCH_DEVICE</term>
+<listitem>
+<para>Restrict watching to a specified device, path given as second
+argument.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para><function>gps_errstr()</function> returns an ASCII string (in
+English) describing the error indicated by a nonzero return value from
+<function>gps_open()</function>.</para>
+
+<para>Consult <filename>gps.h</filename> 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 <function>gps_read()</function>.
+It is up to the client to zero that field when appropriate and to keep
+an eye on the fix and sentence timestamps.</para>
+
+<para>The Python implementation supports the same facilities as the
+socket-export calls in the C library; there is no shared-memory
+interface. <function>gps_open()</function> 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.
+However, it is simpler just to use the session object as an iterator,
+as in the example given below.  Resources within the session object
+will be properly released when it is garbage-collected.</para>
+</refsect1>
+
+<refsect1 id='environment'><title>ENVIRONMENT VARIABLES</title>
+
+<para>By setting the environment variable <envar>GPSD_SHM_KEY</envar>,
+you can control the key value used to create shared-memory segment
+used for communication with <application>gpsd</application>.  This
+will be useful mainly when isolating test instances of
+<application>gpsd</application> from production ones.</para>
+
+</refsect1>
+
+<refsect1 id='example'><title>CODE EXAMPLE</title>
+
+<para>The following is an excerpted and simplified version of the
+libgps interface code from
+<citerefentry><refentrytitle>cgps</refentrytitle><manvolnum>1</manvolnum>
+</citerefentry>.</para>
+
+<programlisting>
+    struct gps_data_t gps_data;
+
+    ret = gps_open(hostName, hostPort, &amp;gps_data);
+
+    (void) gps_stream(&amp;gps_data, WATCH_ENABLE | WATCH_JSON, NULL);
+
+    /* Put this in a loop with a call to a high resolution sleep () in it. */
+    if (gps_waiting (&amp;gps_data, 500)) {
+        errno = 0;
+        if (gps_read (&amp;gps_data) == -1) {
+            ...
+        } else {
+            /* Display data from the GPS receiver. */
+            if (gps_data.set &amp; ...
+        }
+    }
+
+    /* When you are done... */
+    (void) gps_stream(&amp;gps_data, WATCH_DISABLE, NULL);
+    (void) gps_close (&amp;gps_data);
+</programlisting>
+
+</refsect1>
+
+<refsect1 id='limitations'><title>LIMITATIONS</title>
+
+<para>On some systems (those which do not support implicit linking in
+libraries) you may need to add -lm to your link line when you link libgps.
+It is always safe to do this.</para>
+
+<para>In the C API, incautious use of <function>gps_send()</function>
+may lead to subtle bugs. In order to not bloat <structname>struct
+gps_data_t</structname> with space used by responses that are not
+expected to be shipped in close sequence with each other, the storage
+for fields associated with certain responses are combined in a
+union.</para>
+
+<para>The risky set of responses includes VERSION, DEVICELIST, RTCM2,
+RTCM3, SUBFRAME, AIS, GST, and ERROR; it may not be limited to that
+set.  The logic of the daemon's watcher mode is careful to avoid
+dangerous sequences, but you should read and understand the layout of
+<structname>struct gps_data_t</structname> before using
+<function>gps_send()</function> to request any of these
+responses.</para>
+
+</refsect1>
+
+<refsect1 id='compatibility'><title>COMPATIBILITY</title>
+
+<para>The <function>gps_query()</function> supported in major versions
+1 and 2 of this library has been removed.  With the new
+streaming-oriented wire protocol behind this library, it is extremely
+unwise to assume that the first transmission from the daemon after a
+command is shipped to it will be the response to command.</para>
+
+<para>If you must send commands to the daemon explicitly, use
+<function>gps_send()</function> but beware that this ties your code to
+the GPSD wire protocol. It is not recommended.</para>
+
+<para>In earlier versions of the API <function>gps_read()</function> was
+a blocking call and there was a POLL_NONBLOCK option to make it nonblocking.
+<function>gps_waiting()</function> was added to reduce the number of
+wrong ways to code a polling loop.</para>
+
+<para>See the comment above the symbol GPSD_API_MAJOR_VERSION
+in <filename>gps.h</filename> for recent changes.</para>
+</refsect1>
+
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para>
+<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum>
+</citerefentry>,
+<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum>
+</citerefentry>,
+<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum>
+</citerefentry>.
+</para>
+</refsect1>
+
+<refsect1 id='author'><title>AUTHOR</title>
+<para>Eric S. Raymond &lt;esr@thyrsus.com&gt;,
+ C sample code Charles Curley &lt;charlescurley@charlescurley.com&gt;</para>
+</refsect1>
+</refentry>
+