| 1 | .\" -*-nroff-*- |
| 2 | .TH versioncmp 3 "6 January 2007" "Straylight/Edgeware" "mLib utilities library" |
| 3 | .SH NAME |
| 4 | versioncmp \- compare Debian-format version numbers |
| 5 | .\" @versioncmp |
| 6 | .\" @VERSIONCMP |
| 7 | .SH SYNOPSIS |
| 8 | .nf |
| 9 | .B "#include <mLib/versioncmp.h>" |
| 10 | |
| 11 | .BI "int versioncmp(const char *" va ", const char *" vb ");" |
| 12 | .BI "int VERSIONCMP(const char *" va ", " op ", const char *" vb ");" |
| 13 | .fi |
| 14 | .SH DESCRIPTION |
| 15 | The |
| 16 | .B versioncmp |
| 17 | function compares version strings. |
| 18 | .PP |
| 19 | The format of version numbers considered is |
| 20 | .IP |
| 21 | .RI [ epoch |
| 22 | .BR : ] |
| 23 | .I main |
| 24 | .RB [ \- |
| 25 | .IR sub ] |
| 26 | .PP |
| 27 | The |
| 28 | .I main |
| 29 | part may contain colons or hyphens if there is an |
| 30 | .I epoch |
| 31 | or |
| 32 | .IR sub , |
| 33 | respectively. Version strings are compared componentwise: first epochs, |
| 34 | then main parts, and finally subparts. |
| 35 | .PP |
| 36 | The component comparison is done as follows. First, the initial |
| 37 | subsequence of nondigit characters is extracted from each string, and |
| 38 | these are compared lexicographically, using ASCII ordering, except that |
| 39 | letters precede non-letters. If both are the same, an initial sequence |
| 40 | of digits is extracted from the remaining parts of the version strings, |
| 41 | and these are compared numerically (an empty sequence being considered |
| 42 | to have the value zero). This process is repeated until we have a |
| 43 | winner or until both strings are exhausted. |
| 44 | .PP |
| 45 | The return value is 0 if the two strings are equal, \-1 if |
| 46 | .I va |
| 47 | is older than |
| 48 | .IR vb , |
| 49 | or +1 if |
| 50 | .I va |
| 51 | is newer than |
| 52 | .IR vb . |
| 53 | .PP |
| 54 | The |
| 55 | .B VERSIONCMP |
| 56 | macro provides a more convenient syntax for the |
| 57 | .B versioncmp |
| 58 | function, by allowing a relational operator to be written between the |
| 59 | operands. |
| 60 | .SH SEE ALSO |
| 61 | .BR mLib (3). |
| 62 | .PP |
| 63 | .IR "Debian Policy Manual" . |
| 64 | .SH AUTHOR |
| 65 | Mark Wooding, <mdw@distorted.org.uk> |