fanotify_init.2, fanotify.7: Document FAN_REPORT_TID

[thirdparty/man-pages.git] / man3 / strverscmp.3

diff --git a/man3/strverscmp.3 b/man3/strverscmp.3
index 338665de57d316b1b8d5081ede21c05163e9f5e1..7201591593f28b2c7c22a5b67eb9f3c71be7ba85 100644 (file)
--- a/man3/strverscmp.3
+++ b/man3/strverscmp.3
@@ -1,4 +1,5 @@
 .\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>
+.\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
 .\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
@@ -22,15 +23,14 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
 .\"
-.TH STRVERSCMP 3  2001-12-19 "GNU" "Linux Programmer's Manual"
+.TH STRVERSCMP 3  2017-09-15 "GNU" "Linux Programmer's Manual"
 .SH NAME
 strverscmp \- compare two version strings
 .SH SYNOPSIS
 .nf
 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
-.br
 .B #include <string.h>
-.sp
+.PP
 .BI "int strverscmp(const char *" s1 ", const char *" s2 );
 .fi
 .SH DESCRIPTION
@@ -49,7 +49,7 @@ which is implemented using
 .BR versionsort (3),
 which again uses
 .BR strverscmp ().
-
+.PP
 Thus, the task of
 .BR strverscmp ()
 is to compare two strings and find the "right" order, while
@@ -60,10 +60,10 @@ the locale category
 .BR LC_COLLATE ,
 so is meant mostly for situations
 where the strings are expected to be in ASCII.
-
+.PP
 What this function does is the following.
 If both strings are equal, return 0.
-Otherwise find the position
+Otherwise, find the position
 between two bytes with the property that before it both strings are equal,
 while directly after it there is a difference.
 Find the largest consecutive digit strings containing (or starting at,
@@ -87,8 +87,70 @@ less than, equal to, or greater than zero if
 is found, respectively, to be earlier than, equal to,
 or later than
 .IR s2 .
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface      Attribute       Value
+T{
+.BR strverscmp ()
+T}     Thread safety   MT-Safe
+.TE
+.\" FIXME: The marking is different from that in the glibc manual,
+.\" which has:
+.\"
+.\"     strverscmp: MT-Safe locale
+.\"
+.\" glibc manual says strverscmp should have marking locale because it calls
+.\" isdigit() multiple times and isdigit() uses locale variable.
+.\" But isdigit() has two implementations. With different compiling conditions,
+.\" we may call isdigit() in macro, then strverscmp() should not have locale
+.\" problem.
 .SH CONFORMING TO
 This function is a GNU extension.
+.SH EXAMPLE
+The program below can be used to demonstrate the behavior of
+.BR strverscmp ().
+It uses
+.BR strverscmp ()
+to compare the two strings given as its command-line arguments.
+An example of its use is the following:
+.PP
+.in +4n
+.EX
+$ \fB./a.out jan1 jan10\fP
+jan1 < jan10
+.EE
+.in
+.SS Program source
+\&
+.EX
+#define _GNU_SOURCE
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(int argc, char *argv[])
+{
+    int res;
+
+    if (argc != 3) {
+        fprintf(stderr, "Usage: %s <string1> <string2>\\n", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+
+    res = strverscmp(argv[1], argv[2]);
+
+    printf("%s %s %s\\n", argv[1],
+            (res < 0) ? "<" : (res == 0) ? "==" : ">", argv[2]);
+
+    exit(EXIT_SUCCESS);
+}
+.EE
 .SH SEE ALSO
 .BR rename (1),
 .BR strcasecmp (3),