chiark - git - mdw - mLib/blob - utils/versioncmp.3

   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>