From: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Date: Mon, 16 Dec 2024 01:00:45 +0000 (+0100)
Subject: man/man3/strverscmp.3: This is NOT the ordering used by ls -v
X-Git-Tag: man-pages-6.10~52
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=39b7829cc9582fc2d84c5cfbd625dc84474d771c;p=thirdparty%2Fman-pages.git

man/man3/strverscmp.3: This is NOT the ordering used by ls -v

Compare, given:
	#include <stdlib.h>
	#include <stdio.h>
	#include <string.h>
	int compar(const char **l, const char **r) {
		return strverscmp(*l, *r);
	}
	int main(int argc, char ** argv) {
		qsort(argv + 1, argc - 1, sizeof(*argv), compar);
		for(int i = 1; i <  argc; ++i)
			puts(argv[i]);
	}
yields:
	$ /bin/ls -v1 a*  # coreutils ls
	a-1.0a
	a-1.0.1a
	$ ../vers a*      # as above
	a-1.0.1a
	a-1.0a
	$ ls -v1 a*       # voreutils ls @ 5781698 with strverscmp()-equivalent sorting
	a-1.0.1a
	a-1.0a
compare also the results for real data like
	netstat-nat-1.{0,1{,.1},2,3.1,4{,.{1,2,3,4,5,6,7,8,9,10}}}.tar.gz

Thus, coreutils ls -v (and sort -V) does NOT use strverscmp(3);
it uses a modified Debian version comparison algorithm with additional
suffix processing and `ls -v`-specific exceptions.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Message-Id: <myuppkwnltqtxduoop7g7wfuyou5cdo6sotocrvyztmqnazvph@tarta.nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

diff --git a/man/man3/strverscmp.3 b/man/man3/strverscmp.3
index 41bc1ddbd..e028d6788 100644
--- a/man/man3/strverscmp.3
+++ b/man/man3/strverscmp.3
@@ -18,25 +18,14 @@ Standard C library
 .BI "int strverscmp(const char *" s1 ", const char *" s2 );
 .fi
 .SH DESCRIPTION
-Often one has files
+For a dataset like
 .IR jan1 ", " jan2 ", ..., " jan9 ", " jan10 ", ..."
-and it feels wrong when
-.BR ls (1)
-orders them
+sorting it lexicographically yields
 .IR jan1 ", " jan10 ", ..., " jan2 ", ..., " jan9 .
 .\" classical solution: "rename jan jan0 jan?"
-In order to rectify this, GNU introduced the
-.I \-v
-option to
-.BR ls (1),
-which is implemented using
-.BR versionsort (3),
-which again uses
-.BR strverscmp ().
-.P
-Thus, the task of
+The task of
 .BR strverscmp ()
-is to compare two strings and find the "right" order, while
+is to compare two strings yielding the former order, while
 .BR strcmp (3)
 finds only the lexicographic order.
 This function does not use
@@ -44,6 +33,10 @@ the locale category
 .BR LC_COLLATE ,
 so is meant mostly for situations
 where the strings are expected to be in ASCII.
+This is different from the ordering produced by
+.BR sort (1)
+.BR -V .
+.\" sort -V sorts a-1.0a < a-1.0.1a; strverscmp() does not
 .P
 What this function does is the following.
 If both strings are equal, return 0.