man3/strverscmp.3

   1 '\" t
   2 .\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>
   3 .\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH strverscmp 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 strverscmp \- compare two version strings
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  16 .B #include <string.h>
  17 .P
  18 .BI "int strverscmp(const char *" s1 ", const char *" s2 );
  19 .fi
  20 .SH DESCRIPTION
  21 Often one has files
  22 .IR jan1 ", " jan2 ", ..., " jan9 ", " jan10 ", ..."
  23 and it feels wrong when
  24 .BR ls (1)
  25 orders them
  26 .IR jan1 ", " jan10 ", ..., " jan2 ", ..., " jan9 .
  27 .\" classical solution: "rename jan jan0 jan?"
  28 In order to rectify this, GNU introduced the
  29 .I \-v
  30 option to
  31 .BR ls (1),
  32 which is implemented using
  33 .BR versionsort (3),
  34 which again uses
  35 .BR strverscmp ().
  36 .P
  37 Thus, the task of
  38 .BR strverscmp ()
  39 is to compare two strings and find the "right" order, while
  40 .BR strcmp (3)
  41 finds only the lexicographic order.
  42 This function does not use
  43 the locale category
  44 .BR LC_COLLATE ,
  45 so is meant mostly for situations
  46 where the strings are expected to be in ASCII.
  47 .P
  48 What this function does is the following.
  49 If both strings are equal, return 0.
  50 Otherwise, find the position
  51 between two bytes with the property that before it both strings are equal,
  52 while directly after it there is a difference.
  53 Find the largest consecutive digit strings containing (or starting at,
  54 or ending at) this position.
  55 If one or both of these is empty,
  56 then return what
  57 .BR strcmp (3)
  58 would have returned (numerical ordering of byte values).
  59 Otherwise, compare both digit strings numerically, where digit strings with
  60 one or more leading zeros are interpreted as if they have a decimal point
  61 in front (so that in particular digit strings with more leading zeros
  62 come before digit strings with fewer leading zeros).
  63 Thus, the ordering is
  64 .IR 000 ", " 00 ", " 01 ", " 010 ", " 09 ", " 0 ", " 1 ", " 9 ", " 10 .
  65 .SH RETURN VALUE
  66 The
  67 .BR strverscmp ()
  68 function returns an integer
  69 less than, equal to, or greater than zero if
  70 .I s1
  71 is found, respectively, to be earlier than, equal to,
  72 or later than
  73 .IR s2 .
  74 .SH ATTRIBUTES
  75 For an explanation of the terms used in this section, see
  76 .BR attributes (7).
  77 .TS
  78 allbox;
  79 lbx lb lb
  80 l l l.
  81 Interface       Attribute       Value
  82 T{
  83 .na
  84 .nh
  85 .BR strverscmp ()
  86 T}      Thread safety   MT-Safe
  87 .TE
  88 .\" FIXME: The marking is different from that in the glibc manual,
  89 .\" which has:
  90 .\"
  91 .\"     strverscmp: MT-Safe locale
  92 .\"
  93 .\" glibc manual says strverscmp should have marking locale because it calls
  94 .\" isdigit() multiple times and isdigit() uses locale variable.
  95 .\" But isdigit() has two implementations. With different compiling conditions,
  96 .\" we may call isdigit() in macro, then strverscmp() should not have locale
  97 .\" problem.
  98 .SH STANDARDS
  99 GNU.
 100 .SH EXAMPLES
 101 The program below can be used to demonstrate the behavior of
 102 .BR strverscmp ().
 103 It uses
 104 .BR strverscmp ()
 105 to compare the two strings given as its command-line arguments.
 106 An example of its use is the following:
 107 .P
 108 .in +4n
 109 .EX
 110 $ \fB./a.out jan1 jan10\fP
 111 jan1 < jan10
 112 .EE
 113 .in
 114 .SS Program source
 115 \&
 116 .\" SRC BEGIN (strverscmp.c)
 117 .EX
 118 #define _GNU_SOURCE
 119 #include <stdio.h>
 120 #include <stdlib.h>
 121 #include <string.h>
 122 \&
 123 int
 124 main(int argc, char *argv[])
 125 {
 126     int res;
 127 \&
 128     if (argc != 3) {
 129         fprintf(stderr, "Usage: %s <string1> <string2>\en", argv[0]);
 130         exit(EXIT_FAILURE);
 131     }
 132 \&
 133     res = strverscmp(argv[1], argv[2]);
 134 \&
 135     printf("%s %s %s\en", argv[1],
 136            (res < 0) ? "<" : (res == 0) ? "==" : ">", argv[2]);
 137 \&
 138     exit(EXIT_SUCCESS);
 139 }
 140 .EE
 141 .\" SRC END
 142 .SH SEE ALSO
 143 .BR rename (1),
 144 .BR strcasecmp (3),
 145 .BR strcmp (3),
 146 .BR strcoll (3)