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

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for version number comparison
   4 .\"
   5 .\" (c) 2007, 2009, 2020, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH versioncmp 3mLib "6 January 2007" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @versioncmp
  33 .\" @VERSIONCMP
  34 .
  35 .\"--------------------------------------------------------------------------
  36 .SH NAME
  37 versioncmp \- compare Debian-format version numbers
  38 .
  39 .\"--------------------------------------------------------------------------
  40 .SH SYNOPSIS
  41 .
  42 .nf
  43 .B "#include <mLib/versioncmp.h>"
  44 .PP
  45 .BI "int versioncmp(const char *" va ", const char *" vb ");"
  46 .BI "int VERSIONCMP(const char *" va ", " op ", const char *" vb ");"
  47 .fi
  48 .
  49 .\"--------------------------------------------------------------------------
  50 .SH DESCRIPTION
  51 .
  52 The
  53 .B versioncmp
  54 function compares version strings.
  55 .PP
  56 The format of version numbers considered is
  57 .IP
  58 .RI [ epoch
  59 .BR : ]
  60 .I main
  61 .RB [ \-
  62 .IR sub ]
  63 .PP
  64 The
  65 .I main
  66 part may contain colons or hyphens if there is an
  67 .I epoch
  68 or
  69 .IR sub ,
  70 respectively.  Version strings are compared componentwise: first epochs,
  71 then main parts, and finally subparts.
  72 .PP
  73 The component comparison is done as follows.  First, the initial
  74 subsequence of nondigit characters is extracted from each string, and
  75 these are compared lexicographically, using ASCII ordering, except that
  76 letters precede non-letters.  If both are the same, an initial sequence
  77 of digits is extracted from the remaining parts of the version strings,
  78 and these are compared numerically (an empty sequence being considered
  79 to have the value zero).  This process is repeated until we have a
  80 winner or until both strings are exhausted.
  81 .PP
  82 The return value is 0 if the two strings are equal, \-1 if
  83 .I va
  84 is older than
  85 .IR vb ,
  86 or +1 if
  87 .I va
  88 is newer than
  89 .IR vb .
  90 .PP
  91 The
  92 .B VERSIONCMP
  93 macro provides a more convenient syntax for the
  94 .B versioncmp
  95 function, by allowing a relational operator to be written between the
  96 operands.
  97 .
  98 .\"--------------------------------------------------------------------------
  99 .SH SEE ALSO
 100 .
 101 .BR mLib (3).
 102 .PP
 103 .IR "Debian Policy Manual" .
 104 .
 105 .\"--------------------------------------------------------------------------
 106 .SH AUTHOR
 107 .
 108 Mark Wooding, <mdw@distorted.org.uk>
 109 .
 110 .\"----- That's all, folks --------------------------------------------------