Debian Codegraph @

upstream/debian-unstable/man3/strverscmp.3

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