NAME
	libgeome - Locate local user's geographical location

SYNOPSIS
	#include <libgeome.h>

	#define LIBGEOME_DATUM_LATITUDE   /* omitted */
	#define LIBGEOME_DATUM_LONGITUDE  /* omitted */
	#define LIBGEOME_DATUM_ALTITUDE   /* omitted */

	#define LIBGEOME_LAST_DATUM /* whatever the datum represented with the highest bit is */

	struct libgeome_data {
		uint64_t requested_data;
		double latitude;
		double longitude;
		double altitude;
	};

	struct libgeome_context {
		union {
			const void *cptr;
			void *ptr;
			int i;
			unsigned int u;
			size_t n;
		} user_data;
		void (*print_error)(struct libgeome_context *, const char *, ...);
		void (*print_abort)(struct libgeome_context *, const char *, ...);
		void (*print_debug)(struct libgeome_context *, const char *, ...);
	};

	struct libgeome_netservice {
	       uint64_t can_fetch;
	       size_t service_id;
	       size_t limit;
	       unsigned int alarm_seconds;
	       const char *path;
	       const char *const *args;
	       unsigned patterned : 1;
	};

	extern const struct libgeome_netservice libgeome_netservices[];
	extern const size_t libgeome_netservices_count;

	void libgeome_basic_context(struct libgeome_context *, const char *);

	int libgeome_get_from_time(struct libgeome_context *, struct libgeome_data *);
	int libgeome_get_from_timezone(struct libgeome_context *, struct libgeome_data *);
	int libgeome_get_from_file(struct libgeome_context *, struct libgeome_data *, const char *);
	int libgeome_get_from_command(struct libgeome_context *, struct libgeome_data *, size_t,
	                              unsigned int, const char *, const char *const *);
	int libgeome_get_from_netservice(struct libgeome_context *, struct libgeome_data *,
	                                 const struct libgeome_netservice *);

	/* less fundament features omitted */

	Link with -lgeome -lm.

DESCRIPTION
	libgeome is a library which provides functionally for looking up
	the local user's location on the Globe.

	To use libgeome, first create and initialise a struct libgeome_context
	which will be used for all other library calls. This can easily be done
	by creating a statically allocated struct libgeome_context and call the
	libgeome_basic_context(3) function with it as the first argument and
	the name of the program as the second argument, optionally with
	"libgeome" added make it clear where error messages are printed from.

	libgeome_get_from_file(3) can be used to check if the user has specified
	his location in /etc/geolocation (use NULL as the third argument) or any
	other file (specified by the third argument).

	The next best thing is to use libgeome_get_from_timezone(3) to get a
	rough location based on the user's timezone. But if this doesn't work,
	libgeome_get_from_time(3) must be used, which provides only gives an
	approximate longitude based one the current timezone, which is affected
	by daylight saving, which may be desirable for some applications but not
	for other applications.

	Unless the location was determined using the libgeome_get_from_file(3)
	function, it may be desirable to attempt to get a more accurate location
	using network location services. This should of course not be done
	without the user's consent as this connects to a third party service.
	The function libgeome_get_from_netservice(3) is used for this, and a
	list of services is provided in libgeome_netservices(3), with the number
	of services listed provided in libgeome_netservices_count(3). You can
	also add custom services, or run local program, using the
	libgeome_get_from_command(3) function. If it cannot parse the output,
	can reformat it as "%s %s\n", <latitude>, <longitude>.

	When alling a libgeome function, any struct libgeome_data must have
	its .requested_data set. This lets the called function 1) know what data
	to request, and 2) what fields are available in the application's
	version of the structure so that it doesn't write outside it if it is
	out of date. There for it is critical that the application doesn't
	simply set all but, but instead only recognised ones.

EXTENDED DESCRIPTION
   Runtime-optional dependencies
	libgeome_get_from_timezone(3) relies on timezone data compatible with
	the Time Zone Database from Internet Assigned Numbers Authority, also
	called tz or zoneinfo (as is used in /usr/share), and often distributed
	under the name tzdata (the data portion of the project).

	libgeome_netservices(3) relies on curl(1).