From 0ed6b110889286a7773f893b6d36e02e3fcefceb Mon Sep 17 00:00:00 2001 From: Nate Bargmann Date: Sun, 16 May 2021 21:10:31 -0500 Subject: [PATCH] Update Doxygen comments and main page --- doc/index.doxygen | 70 +++++++-- src/locator.c | 384 +++++++++++++++++++++++++++------------------- 2 files changed, 282 insertions(+), 172 deletions(-) diff --git a/doc/index.doxygen b/doc/index.doxygen index 366239c12..1d6103f0d 100644 --- a/doc/index.doxygen +++ b/doc/index.doxygen @@ -1,10 +1,5 @@ /*! \mainpage Hamlib API Reference -\section auth Authors - -Stéphane Fillod, F8CFE, and Frank Singleton, VK3FCS and the Hamlib Group -\n Documentation revisions by Martin Ewing, AA6E, Nate Bargmann, N0NB, Michael Black, W9MDB - \section s1 Preface This document describes the Hamlib library Application Programming Interface @@ -14,18 +9,24 @@ We attempt to document the complete API of the core modules of Hamlib, i.e. the API seen by end-user application developers. You may navigate the documentation through the tabs at the top of this page. +\note This documentation is a work in progress. + Please report any problems to hamlib-developer@lists.sourceforge.net. \section txtfil Distributed information files These text files are distributed with the Hamlib package. -Readme files: \subpage Rdme "General"; +\li Readme files: \subpage Rdme "General"; \subpage Rdmebeta "Beta Tester"; \subpage Rdmedevel "Developer"; -\subpage Rdmewin "MS Windows" +\subpage Rdmewin "MS Windows"; +\subpage Rdmeosx "Mac OS X"; +\subpage Rdmefrq "Frequency range changes"; +\subpage Rdmemulti "Multicast support"; +\subpage Security "Security policy"; -Other files: \subpage INSTALL; +\li Other files: \subpage INSTALL; \subpage AUTHORS; \subpage COPYING; \subpage COPYING.LIB; @@ -44,10 +45,20 @@ Other files: \subpage INSTALL; \section slic Documentation License \li \subpage doclicense + +\section auth Authors + +\li Stéphane Fillod, F8CFE, and Frank Singleton, VK3FCS and the Hamlib Group +\li Documentation revisions by Martin Ewing, AA6E, Nate Bargmann, N0NB, +Michael Black, W9MDB and many others. */ + + +/* Subpage definitions follow. */ + /*! \page doclicense License for Documentation This documentation is free; you can redistribute it without -any restrictions. The modification or derived work must retain +any restrictions. The modification or derived work must retain copyright and list all authors. This documentation is distributed in the hope that it will be @@ -58,48 +69,81 @@ of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. /*! \page Rdme README (general) \verbinclude README */ + /*! \page Rdmebeta README.betatester \verbinclude README.betatester */ + /*! \page Rdmedevel README.developer \verbinclude README.developer */ + /*! \page Rdmewin Cross-compiling Hamlib on Linux for MS Windows This page contains the `scripts/README.build-Windows` instructions and the -`scripts/build-w32.sh` file that describe cross-compiling Hamlib for MS -Windows 32 bit on Debian GNU/Linux. +`scripts/build-w32.sh` and `scripts/build-w64.h` files that describe +cross-compiling Hamlib for MS Windows 32 and 64 bit versions on Debian +GNU/Linux. +\tableofcontents \section Build README.build-Windows \verbinclude README.build-Windows \subsection W32 The build-w32.sh script -\verbinclude build-w32.sh +\include{lineno} build-w32.sh \subsection W64 The build-w64.sh script -\verbinclude build-w64.sh +\include{lineno} build-w64.sh */ + +/*! \page Rdmeosx README.osx +\verbinclude README.osx +*/ + +/*! \page Rdmefrq README.freqranges +\verbinclude README.freqranges +*/ + +/*! \page Rdmemulti README.multicast +\verbinclude README.multicast +*/ + +/* FIXME: figure out how to include Markdown for HTML output. */ +/*! \page Security SECURITY.md +\include SECURITY.md +*/ + /*! \page INSTALL INSTALL \verbinclude INSTALL */ + /*! \page AUTHORS AUTHORS \verbinclude AUTHORS */ + /*! \page COPYING COPYING \verbinclude COPYING */ + /*! \page COPYING.LIB COPYING.LIB \verbinclude COPYING.LIB */ + /*! \page LICENSE LICENSE \verbinclude LICENSE */ + /*! \page NEWS NEWS \verbinclude NEWS */ + /*! \page PLAN PLAN \verbinclude PLAN */ + /*! \page THANKS THANKS \verbinclude THANKS */ + +/* Defined API groups--sections included with addtogroup in sources. */ + /*! Define groups for Doxygen * \defgroup rig Rig (transceiver) API * \defgroup rig_internal Rig (transceiver) Internal API diff --git a/src/locator.c b/src/locator.c index b76795490..07bd653b7 100644 --- a/src/locator.c +++ b/src/locator.c @@ -1,17 +1,3 @@ -/** - * \addtogroup utilities - * @{ - */ - -/** - * \file src/locator.c - * \brief locator and bearing conversion interface - * \author Stephane Fillod and the Hamlib Group - * \date 2000-2010 - * - * Hamlib Interface - locator, bearing, and conversion calls - */ - /* * Hamlib Interface - locator and bearing conversion calls * Copyright (c) 2001-2010 by Stephane Fillod @@ -47,12 +33,49 @@ * */ -/*! \page hamlib Hamlib general purpose API - * - * Here are grouped some often used functions, like locator conversion - * routines. + +/** + * \addtogroup utilities + * @{ */ +/** + * \file src/locator.c + * + * \brief QRA locator (Maidenhead grid square) and latitude/longitude bearing + * conversion interface. + * + * \author Stephane Fillod + * \author Nate Bargmann + * \author Dave Hines + * \author The Hamlib Group + * \date 2000-2020 + */ + +/** + * \page hamlib Hamlib general purpose API + * + * Hamlib function call interface for determining QRA locator (Maidenhead grid + * square), bearing, and conversion between QRA locator and latitude/longitude + * formats. + * + * \par Sources used in writing these routines + * + * \parblock + * Code to determine bearing and range was taken from the Great Circle, + * by Steven R. Sampson, N5OWK.
+ * Ref: "Air Navigation", Air Force Manual 51-40, 1 February 1987
+ * Ref: "ARRL Satellite Experimenters Handbook", August 1990 + * + * Code to calculate distance and azimuth between two QRA locators, taken from + * wwl, by IK0ZSN, Mirko Caserta. + * + * New bearing code added by N0NB was found at: + * http://williams.best.vwh.net/avform.htm#Crs + * \endparblock + */ + + #ifdef HAVE_CONFIG_H # include "config.h" #endif @@ -67,74 +90,93 @@ #include -#ifndef DOC_HIDDEN - +/** \brief Standard definition of a radian. */ #define RADIAN (180.0 / M_PI) -/* arc length for 1 degree, 60 Nautical Miles */ +/** \brief arc length for 1 degree in kilometers, i.e. 60 Nautical Miles */ #define ARC_IN_KM 111.2 + /* The following is contributed by Dave Hines M1CXW * * begin dph */ -/* - * These are the constants used when converting between Maidenhead grid - * locators and longitude/latitude values. MAX_LOCATOR_PAIRS is the maximum - * number of locator character pairs to convert. This number MUST NOT exceed - * the number of pairs of values in loc_char_range[]. - * Setting MAX_LOCATOR_PAIRS to 3 will convert the currently defined 6 - * character locators. A value of 4 will convert the extended 8 character - * locators described in section 3L of "The IARU region 1 VHF managers - * handbook". Values of 5 and 6 will extent the format even more, to the - * longest definition I have seen for locators, see - * http://www.btinternet.com/~g8yoa/geog/non-ra.html - * Beware that there seems to be no universally accepted standard for 10 & 12 - * character locators. + +/* At this time documenting a single static variable as in loc_char_range[] + * below is not supported by Doxygen. Hide this section until support exists + * or a work-around becomes available. + */ +#ifndef DOC_HIDDEN + +/** + * \brief Constants used when converting between Maidenhead grid + * locators and longitude/latitude values. * - * The ranges of characters which will be accepted by locator2longlat, and - * generated by longlat2locator, are specified by the loc_char_range[] array. - * This array may be changed without requiring any other code changes. + * \ref MAX_LOCATOR_PAIRS is the maximum number of locator character pairs to + * convert. This number MUST NOT exceed the number of pairs of values in + * loc_char_range[]. Setting \ref MAX_LOCATOR_PAIRS to 3 will convert the + * currently defined 6 character locators. A value of 4 will convert the + * extended 8 character locators described in section 3L of "The IARU region 1 + * VHF managers handbook". Values of 5 and 6 will extent the format even + * more, to the longest definition I have seen for locators, see + * http://www.btinternet.com/~g8yoa/geog/non-ra.html (currently a dead + * link. -N0NB). Be aware that there seems to be no universally accepted + * standard for 10 & 12 character locators. + * + * The ranges of characters which will be accepted by locator2longlat(), and + * generated by longlat2locator(), are specified by the \ref loc_char_range[] + * array. This array may be changed without requiring any other code changes. * * For the fifth pair to range from aa to xx use: - * const static int loc_char_range[] = { 18, 10, 24, 10, 24, 10 }; + * \code const static int loc_char_range[] = { 18, 10, 24, 10, 24, 10 };\endcode * * For the fifth pair to range from aa to yy use: - * const static int loc_char_range[] = { 18, 10, 24, 10, 25, 10 }; - * - * MAX_LOCATOR_PAIRS now sets the limit locator2longlat() will convert and - * sets the maximum length longlat2locator() will generate. Each function - * properly handles any value from 1 to 6 so MAX_LOCATOR_PAIRS should be - * left at 6. MIN_LOCATOR_PAIRS sets a floor on the shortest locator that - * should be handled. -N0NB + * \code const static int loc_char_range[] = { 18, 10, 24, 10, 25, 10 };\endcode */ const static int loc_char_range[] = { 18, 10, 24, 10, 24, 10 }; +#endif /* !DOC_HIDDEN */ + +/** \def MAX_LOCATOR_PAIRS + * + * \brief Longest locator to process, e.g. AA00AA00AA00. + * + * Sets the limit locator2longlat() will convert and sets the maximum length + * longlat2locator() will generate. Each function properly handles any value + * from `1` to `6` so \ref MAX_LOCATOR_PAIRS should be left at `6`. + * + * \def MIN_LOCATOR_PAIRS + * + * \brief Shortest locator to process, e.g. AA. + * + * Sets a floor on the shortest locator that should be handled. + */ #define MAX_LOCATOR_PAIRS 6 #define MIN_LOCATOR_PAIRS 1 /* end dph */ -#endif /* !DOC_HIDDEN */ - /** - * \brief Convert DMS to decimal degrees - * \param degrees Degrees, whole degrees - * \param minutes Minutes, whole minutes - * \param seconds Seconds, decimal seconds - * \param sw South or West + * \brief Convert Degrees Minutes Seconds (DMS) notation to decimal degrees + * (D.DDD) angle. * - * Convert degree/minute/second angle to decimal degrees angle. - * \a degrees >360, \a minutes > 60, and \a seconds > 60.0 are allowed, - * but resulting angle won't be normalized. + * \param degrees Degrees, whole degrees. + * \param minutes Minutes, whole minutes. + * \param seconds Seconds, decimal seconds. + * \param sw South or West. * - * When the variable sw is passed a value of 1, the returned decimal - * degrees value will be negative (south or west). When passed a - * value of 0 the returned decimal degrees value will be positive - * (north or east). + * Convert a Degrees Minutes Seconds (DMS) notation value to a decimal degrees + * (D.DDD) angle value. * - * \return The angle in decimal degrees. + * \note For the parameters \a degrees >360, \a minutes > 60, and \a seconds > + * 60.0 are allowed, but the resulting angle will not be normalized. + * + * When the variable \a sw is passed a value of 1, the returned decimal + * degrees value will be negative (*South* or *West*). When passed a value of 0 + * the returned decimal degrees value will be positive (*North* or *East*). + * + * \return The signed angle in decimal degrees (D.DDD). * * \sa dec2dms() */ @@ -173,23 +215,25 @@ double HAMLIB_API dms2dec(int degrees, int minutes, double seconds, int sw) /** - * \brief Convert D M.MMM notation to decimal degrees - * \param degrees Degrees, whole degrees - * \param minutes Minutes, decimal minutes - * \param sw South or West + * \brief Convert degrees decimal minutes (D M.MMM) notation to decimal + * degrees (D.DDD) angle. * - * Convert a degrees, decimal minutes notation common on - * many GPS units to its decimal degrees value. + * \param degrees Degrees, whole degrees. + * \param minutes Minutes, decimal minutes. + * \param seconds Seconds, decimal seconds. + * \param sw South or West. * - * \a degrees > 360, \a minutes > 60.0 are allowed, but - * resulting angle won't be normalized. + * Convert a degrees decimal minutes (D M.MMM) notation common on many GPS + * units to a decimal degrees (D.DDD) angle value. * - * When the variable sw is passed a value of 1, the returned decimal - * degrees value will be negative (south or west). When passed a - * value of 0 the returned decimal degrees value will be positive - * (north or east). + * \note For the parameters \a degrees > 360, \a minutes > 60.0, \a seconds > + * 60.0 are allowed, but the resulting angle will not be normalized. * - * \return The angle in decimal degrees. + * When the variable \a sw is passed a value of 1, the returned decimal + * degrees value will be negative (*South* or *West*). When passed a value of + * 0 the returned decimal degrees value will be positive (*North* or *East*). + * + * \return The signed angle in decimal degrees (D.DDD). * * \sa dec2dmmm() */ @@ -223,29 +267,33 @@ double HAMLIB_API dmmm2dec(int degrees, double minutes, double seconds, int sw) /** - * \brief Convert decimal degrees angle into DMS notation - * \param dec Decimal degrees - * \param degrees Pointer for the calculated whole Degrees - * \param minutes Pointer for the calculated whole Minutes - * \param seconds Pointer for the calculated decimal Seconds - * \param sw Pointer for the calculated SW flag + * \brief Convert a decimal degrees (D.DDD) angle into Degrees Minutes + * Seconds (DMS) notation. * - * Convert decimal degrees angle into its degree/minute/second - * notation. + * \param dec Decimal degrees (D.DDD). + * \param degrees Pointer for the calculated whole Degrees. + * \param minutes Pointer for the calculated whole Minutes. + * \param seconds Pointer for the calculated decimal Seconds. + * \param sw Pointer for the calculated SW (South/West) flag. * - * When \a dec < -180 or \a dec > 180, the angle will be normalized - * within these limits and the sign set appropriately. + * Convert decimal degrees angle (D.DDD) into its Degree Minute Second (DMS) + * notation. * - * Upon return dec2dms guarantees 0 >= \a degrees <= 180, - * 0 >= \a minutes < 60, and 0.0 >= \a seconds < 60.0. + * When \a dec < -180 or \a dec > 180, the angle will be normalized within + * these limits and the sign set appropriately. * - * When \a dec is < 0.0 \a sw will be set to 1. When \a dec is - * >= 0.0 \a sw will be set to 0. This flag allows the application - * to determine whether the DMS angle should be treated as negative - * (south or west). + * Upon return, guarantees 0 >= \a degrees <= 180, 0 >= \a minutes < 60, and + * 0.0 >= \a seconds < 60.0. * - * \retval -RIG_EINVAL if any of the pointers are NULL. - * \retval RIG_OK if conversion went OK. + * When \a dec is < 0.0 \a sw will be set to 1. When \a dec is >= 0.0 \a sw + * will be set to 0. This flag allows the application to determine whether + * the DMS angle should be treated as negative (*South* or *West*). + * + * \return RIG_OK if the operation has been successful, otherwise a **negative + * value** if an error occurred (in which case, cause is set appropriately). + * + * \retval RIG_OK The conversion was successful. + * \retval RIG_EINVAL Either of the pointers are NULL. * * \sa dms2dec() */ @@ -317,28 +365,33 @@ int HAMLIB_API dec2dms(double dec, /** - * \brief Convert a decimal angle into D M.MMM notation - * \param dec Decimal degrees - * \param degrees Pointer for the calculated whole Degrees - * \param minutes Pointer for the calculated decimal Minutes - * \param sw Pointer for the calculated SW flag + * \brief Convert a decimal degrees (D.DDD) angle into degrees decimal minutes + * (D M.MMM) notation. * - * Convert a decimal angle into its degree, decimal minute - * notation common on many GPS units. + * \param dec Decimal degrees angle. + * \param degrees Pointer for the calculated whole Degrees. + * \param minutes Pointer for the calculated decimal Minutes. + * \param sw Pointer for the calculated SW flag. * - * When passed a value < -180 or > 180, the value will be normalized - * within these limits and the sign set apropriately. + * Convert a decimal angle into its degree, decimal minute + * notation common on many GPS units. * - * Upon return dec2dmmm guarantees 0 >= \a degrees <= 180, - * 0.0 >= \a minutes < 60.0. + * When passed a value < -180 or > 180, the value will be normalized + * within these limits and the sign set apropriately. * - * When \a dec is < 0.0 \a sw will be set to 1. When \a dec is - * >= 0.0 \a sw will be set to 0. This flag allows the application - * to determine whether the D M.MMM angle should be treated as negative - * (south or west). + * Upon return dec2dmmm guarantees 0 >= \a degrees <= 180, + * 0.0 >= \a minutes < 60.0. * - * \retval -RIG_EINVAL if any of the pointers are NULL. - * \retval RIG_OK if conversion went OK. + * When \a dec is < 0.0 \a sw will be set to 1. When \a dec is + * >= 0.0 \a sw will be set to 0. This flag allows the application + * to determine whether the D M.MMM angle should be treated as negative + * (south or west). + * + * \return RIG_OK if the operation has been successful, otherwise a **negative + * value** if an error occurred (in which case, cause is set appropriately). + * + * \retval RIG_OK The conversion was successful. + * \retval RIG_EINVAL Either of the pointers are NULL. * * \sa dmmm2dec() */ @@ -369,23 +422,27 @@ int HAMLIB_API dec2dmmm(double dec, int *degrees, double *minutes, int *sw) /** - * \brief Convert Maidenhead grid locator to Longitude/Latitude - * \param longitude Pointer for the calculated Longitude - * \param latitude Pointer for the calculated Latitude - * \param locator The Maidenhead grid locator--2 through 12 char + nul string + * \brief Convert QRA locator (Maidenhead grid square) to Longitude/Latitude. * - * Convert Maidenhead grid locator to Longitude/Latitude (decimal degrees). - * The locator should be in 2 through 12 chars long format. - * \a locator2longlat is case insensitive, however it checks for - * locator validity. + * \param longitude Pointer for the calculated Longitude. + * \param latitude Pointer for the calculated Latitude. + * \param locator The QRA locator--2 through 12 characters + nul string. * - * Decimal long/lat is computed to center of grid square, i.e. given - * EM19 will return coordinates equivalent to the southwest corner - * of EM19mm. + * Convert a QRA locator string to Longitude/Latitude in decimal degrees + * (D.DDD). The locator should be 2 through 12 chars long format. + * \a locator2longlat is case insensitive, however it checks for locator + * validity. * - * \retval -RIG_EINVAL if locator exceeds RR99xx99xx99 or exceeds length - * limit--currently 1 to 6 lon/lat pairs. - * \retval RIG_OK if conversion went OK. + * Decimal long/lat is computed to center of grid square, i.e. given + * `EM19` will return coordinates equivalent to the southwest corner + * of `EM19mm`. + * + * \return RIG_OK if the operation has been successful, otherwise a **negative + * value** if an error occurred (in which case, cause is set appropriately). + * + * \retval RIG_OK The conversion was successful. + * \retval RIG_EINVAL The QRA locator exceeds RR99xx99xx99 or exceeds length + * limit--currently 1 to 6 lon/lat pairs--or is otherwise malformed. * * \bug The fifth pair ranges from aa to xx, there is another convention * that ranges from aa to yy. At some point both conventions should be @@ -461,23 +518,29 @@ int HAMLIB_API locator2longlat(double *longitude, /** - * \brief Convert longitude/latitude to Maidenhead grid locator - * \param longitude Longitude, decimal degrees - * \param latitude Latitude, decimal degrees - * \param locator Pointer for the Maidenhead Locator - * \param pair_count Precision expressed as lon/lat pairs in the locator + * \brief Convert longitude/latitude to QRA locator (Maidenhead grid square). * - * Convert longitude/latitude (decimal degrees) to Maidenhead grid locator. - * \a locator must point to an array at least \a pair_count * 2 char + '\\0'. + * \param longitude Longitude, decimal degrees. + * \param latitude Latitude, decimal degrees. + * \param locator Pointer for the QRA Locator. + * \param pair_count Requested precision expressed as lon/lat pairs in the + * returned QRA locator string. * - * \retval -RIG_EINVAL if \a locator is NULL or \a pair_count exceeds - * length limit. Currently 1 to 6 lon/lat pairs. - * \retval RIG_OK if conversion went OK. + * Convert longitude/latitude given in decimal degrees (D.DDD) to a QRA + * locator (Maidenhead grid square). \a locator must point to an array length + * that is at least \a pair_count * 2 char + '\\0'. + * + * \return RIG_OK if the operation has been successful, otherwise a **negative + * value** if an error occurred (in which case, cause is set appropriately). + * + * \retval RIG_OK The conversion was successful. + * \retval RIG_EINVAL if \a locator is NULL or \a pair_count exceeds length + * limit. Currently 1 to 6 lon/lat pairs. * * \bug \a locator is not tested for overflow. * \bug The fifth pair ranges from aa to yy, there is another convention - * that ranges from aa to xx. At some point both conventions should be - * supported. + * that ranges from aa to xx. At some point both conventions should be + * supported. * * \sa locator2longlat() */ @@ -531,26 +594,28 @@ int HAMLIB_API longlat2locator(double longitude, /** * \brief Calculate the distance and bearing between two points. - * \param lon1 The local Longitude, decimal degrees - * \param lat1 The local Latitude, decimal degrees - * \param lon2 The remote Longitude, decimal degrees - * \param lat2 The remote Latitude, decimal degrees - * \param distance Pointer for the distance, km - * \param azimuth Pointer for the bearing, decimal degrees * - * Calculate the QRB between \a lon1, \a lat1 and \a lon2, \a lat2. + * \param lon1 The local Longitude, decimal degrees. + * \param lat1 The local Latitude, decimal degrees, + * \param lon2 The remote Longitude, decimal degrees. + * \param lat2 The remote Latitude, decimal degrees. + * \param distance Pointer for the distance, km. + * \param azimuth Pointer for the bearing, decimal degrees. * - * This version will calculate the QRB to a precision sufficient - * for 12 character locators. Antipodal points, which are easily - * calculated, are considered equidistant and the bearing is - * simply resolved to be true north (0.0°). + * Calculate the distance and bearing (QRB) between \a lon1, \a lat1 and + * \a lon2, \a lat2. * - * \retval -RIG_EINVAL if NULL pointer passed or lat and lon values + * This version will calculate the QRB to a precision sufficient for 12 + * character locators. Antipodal points, which are easily calculated, are + * considered equidistant and the bearing is simply resolved to be true north, + * e.g. \a azimuth = 0.0. + * + * \return RIG_OK if the operation has been successful, otherwise a **negative + * value** if an error occurred (in which case, cause is set appropriately). + * + * \retval RIG_OK The calculations were successful. + * \retval RIG_EINVAL If a NULL pointer passed or \a lat and \a lon values * exceed -90 to 90 or -180 to 180. - * \retval RIG_OK if calculations are successful. - * - * \return The distance in kilometers and azimuth in decimal degrees - * for the short path are stored in \a distance and \a azimuth. * * \sa distance_long_path(), azimuth_long_path() */ @@ -664,12 +729,13 @@ int HAMLIB_API qrb(double lon1, /** * \brief Calculate the long path distance between two points. - * \param distance The shortpath distance * - * Calculate the long path (respective of the short path) - * of a given distance. + * \param distance The shortpath distance in kilometers. * - * \return the distance in kilometers for the opposite path. + * Calculate the long path (opposite bearing of the short path) of a given + * distance. + * + * \return The distance in kilometers for the opposite path. * * \sa qrb() */ @@ -683,13 +749,13 @@ double HAMLIB_API distance_long_path(double distance) /** * \brief Calculate the long path bearing between two points. - * \param azimuth The shortpath bearing--0.0 to 360.0 degrees * - * Calculate the long path (respective of the short path) - * of a given bearing. + * \param azimuth The shortpath bearing--0.0 to 360.0 degrees. * - * \return the azimuth in decimal degrees for the opposite path or - * -RIG_EINVAL upon input error (outside the range of 0.0 to 360.0). + * Calculate the long path (opposite of the short path) of a given bearing. + * + * \return the azimuth in decimal degrees for the opposite path or RIG_EINVAL + * (negated value) upon input error (outside the range of 0.0 to 360.0). * * \sa qrb() */