1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "3" 3 "14 Aug 2004" "" ""
.SH NAME
libgpsd \- service library for GPS applications
.SH "SYNOPSIS"
.ad l
.hy 0
C:
#include <gpsd\&.h>
.sp
.HP 20
int\ \fBgpsd_open_dgps\fR\ (char\ *\ \fIdgpsserver\fR);
.HP 16
void\ \fBgpsd_init\fR\ (struct\ gps_device_t\ *\fIsession\fR, struct\ *\ \fIgps_context_t\ *\fR, char\ *\ \fIdevice\fR);
.HP 19
int\ \fBgpsd_activate\fR\ (struct\ gps_device_t\ *\ \fIsession\fR);
.HP 22
void\ \fBgpsd_deactivate\fR\ (struct\ gps_device_t\ *\ \fIsession\fR);
.HP 22
gps_mask_t\ \fBgpsd_poll\fR\ (struct\ gps_device_t\ *\ \fIsession\fR);
.HP 16
void\ \fBgpsd_wrap\fR\ (struct\ gps_device_t\ *\ \fIsession\fR);
.HP 18
void\ \fBgpsd_report\fR\ (int\ \fId\fR, const\ char\ *\ \fIfmt\fR, \fI\&.\&.\&.\fR);
.ad
.hy
.SH "DESCRIPTION"
.PP
\fIlibgps\fR 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 \fBgpsd\fR(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 \fBgpsd\fR(1) itself uses\&. See \fBgpsd\fR(3) for a description of the high\-level interface, which is almost certainly what you want\&.
.PP
Calling \fBgpsd_init()\fR initializes a session structure to hold the data collected by the GPS\&.
.PP
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\&.
.PP
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\&.
.PP
After the session structure has been set up, you may modify some of its members\&.
.TP
gpsd_device
This member should hold the path name of the device; it defaults to \fI/dev/gps\fR\&.
.TP
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
.TP
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\&.
.PP
\fBgpsd_activate()\fR initializes the connection to the GPS\&. \fBgpsd_deactivate()\fR 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\&.
.PP
\fBgpsd_poll()\fR 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\&.
.PP
\fBgpsd_wrap()\fR ends the session, implicitly performing a \fBgpsd_deactivate()\fR\&.
.PP
The calling application must define one additional function: \fBgpsd_report()\fR\&. 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\&.
.PP
The low\-level functions do not allocate or free any dynamic storage\&. They can thus be used in a long\-running application (such as \fBgpsd\fR(8) itself) with a guarantee that they won't cause memory leaks\&.
.SH "BUGS"
.PP
Writes to the context structure members are not guarded by a mutex\&.
.SH "SEE ALSO"
.PP
\fBgpsd\fR(8), \fBgps\fR(1), \fBlibgpsd\fR(3)\&.
.SH "AUTHOR"
.PP
Eric S\&. Raymond <esr@thyrsus\&.com> based partly on earlier work by Remco Treffkorn, Derrick Brashear, and Russ Nelson\&.
|
