.\"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 libgps \- C service library for communicating with the GPS daemon .SH "SYNOPSIS" .ad l .hy 0 C: #include .sp .HP 30 struct\ gps_data_t\ *\fBgps_open\fR\ (char\ *\fIserver\fR, char\ *\ \fIport\fR); .HP 15 int\ \fBgps_query\fR\ (struct\ gps_data_t\ *\fIgpsdata\fR, char\ *\fIrequests\fR); .HP 23 void\ \fBgps_set_raw_hook\fR\ (struct\ gps_data_t\ *\fIgpsdata\fR, void\ (*\fIhook\fR)(struct\ gps_data_t\ *,\ char\ *buf)); .HP 14 int\ \fBgps_poll\fR\ (struct\ gps_data_t\ *\fIgpsdata\fR); .HP 16 void\ \fBgps_close\fR\ (struct\ gps_data_t\ *\fIgpsdata\fR); .HP 23 void\ \fBgps_set_callback\fR\ (struct\ gps_data_t\ *\fIgpsdata\fR, void\ (*\fIcallback\fR)(struct\ gps_data_t\ *sentence,\ char\ *buf), pthread_t\ *\fIhandler\fR); .HP 23 void\ \fBgps_del_callback\fR\ (struct\ gps_data_t\ *\fIgpsdata\fR, pthread\ *\fIhandler\fR); Python: import gps session = gps\&.gps(host="localhost", port="2947") session\&.set_raw_hook(raw_hook) session\&.query(commands) session\&.poll() del session .sp .ad .hy .SH "DESCRIPTION" .PP 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 \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 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 \fBlibgps\fR(3)\&. .PP Calling \fBgpsd_open()\fR initializes a GPS\-data structure to hold the data collected by the GPS, and returns a socket attached to \fBgpsd\fR(1)\&. \fBgpsd_open()\fR returns NULL on errors\&. errno is set depending on the error returned from the the socket layer; see \fIgps\&.h\fR for values and explanations\&. .PP \fBgpsd_close()\fR ends the session\&. .PP \fBgpsd_poll()\fR 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)\&. \fBgpsd_poll()\fR 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\&. .PP \fBgpsd_query()\fR 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 \fBgpsd\fR(1)\&. This function returns a 0 on success, or a \-1 if there was a Unix\-level read error\&. .PP \fBgps_set_raw_hook()\fR takes a function you specify and run it (synchronously) on the raw data pulled by a \fBgpsd_query()\fR or \fBgpsd_poll()\fR 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\&. .PP \fBgps_set_callback()\fR 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 \fBmy_function()\fR each time new data are available\&. \fBmy_function()\fR 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\&. .PP \fBgps_del_callback()\fR deregisters the callback function previously set with \fBgps_set_callback()\fR\&. After the invocation of this funcion no operation will be done when new data arrives\&. .PP Consult \fIgps\&.h\fR 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\&. .PP The Python implementation supports the same facilities as the C library\&. \fBgps_open()\fR 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\&. .SH "CODE EXAMPLE" .PP The following is an excerpted and simplified version of the libgps interface code from \fBxgps\fR(1)\&. The function \fBhandle_input()\fR is a trivial pies of code that calls gps_poll(gpsdata)\&. .nf 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); .fi .SH "SEE ALSO" .PP \fBgpsd\fR(8), \fBxgps\fR(1), \fBlibgps\fR(3)\&. \fBlibgpsmm\fR(3)\&. .SH "AUTHOR" .PP Eric S\&. Raymond , Thread\-callback methods in the C binding added by Alfredo Pironti \&.