Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 208 insertions, 0 deletions

diff --git a/man/man3/strcmp.3 b/man/man3/strcmp.3
new file mode 100644
index 0000000..ba9eefb
--- /dev/null
+++ b/man/man3/strcmp.3
@@ -0,0 +1,208 @@
+'\" t
+.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
+.\" and Copyright 2020 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\"     Linux libc source code
+.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
+.\"     386BSD man pages
+.\" Modified Sat Jul 24 18:08:52 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Modified 2001-08-31, aeb
+.\"
+.TH strcmp 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+strcmp, strncmp \- compare two strings
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <string.h>
+.P
+.BI "int strcmp(const char *" s1 ", const char *" s2 );
+.BI "int strncmp(const char " s1 [. n "], const char " s2 [. n "], size_t " n );
+.fi
+.SH DESCRIPTION
+The
+.BR strcmp ()
+function compares the two strings
+.I s1
+and
+.IR s2 .
+The locale is not taken into account (for a locale-aware comparison, see
+.BR strcoll (3)).
+The comparison is done using unsigned characters.
+.P
+.BR strcmp ()
+returns an integer indicating the result of the comparison, as follows:
+.IP \[bu] 3
+0, if the
+.I s1
+and
+.I s2
+are equal;
+.IP \[bu]
+a negative value if
+.I s1
+is less than
+.IR s2 ;
+.IP \[bu]
+a positive value if
+.I s1
+is greater than
+.IR s2 .
+.P
+The
+.BR strncmp ()
+function is similar, except it compares
+only the first (at most)
+.I n
+bytes of
+.I s1
+and
+.IR s2 .
+.SH RETURN VALUE
+The
+.BR strcmp ()
+and
+.BR strncmp ()
+functions return an integer
+less than, equal to, or greater than zero if
+.I s1
+(or the first
+.I n
+bytes thereof) is found, respectively, to be less than, to
+match, or be greater than
+.IR s2 .
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR strcmp (),
+.BR strncmp ()
+T}	Thread safety	MT-Safe
+.TE
+.SH VERSIONS
+POSIX.1 specifies only that:
+.RS
+.P
+The sign of a nonzero return value shall be determined by the sign
+of the difference between the values of the first pair of bytes
+(both interpreted as type
+.IR "unsigned char" )
+that differ in the strings being compared.
+.RE
+.P
+In glibc, as in most other implementations,
+the return value is the arithmetic result of subtracting
+the last compared byte in
+.I s2
+from the last compared byte in
+.IR s1 .
+(If the two characters are equal, this difference is 0.)
+.SH STANDARDS
+C11, POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, C89, SVr4, 4.3BSD.
+.SH EXAMPLES
+The program below can be used to demonstrate the operation of
+.BR strcmp ()
+(when given two arguments) and
+.BR strncmp ()
+(when given three arguments).
+First, some examples using
+.BR strcmp ():
+.P
+.in +4n
+.EX
+$ \fB./string_comp ABC ABC\fP
+<str1> and <str2> are equal
+$ \fB./string_comp ABC AB\fP      # \[aq]C\[aq] is ASCII 67; \[aq]C\[aq] \- \[aq]\e0\[aq] = 67
+<str1> is greater than <str2> (67)
+$ \fB./string_comp ABA ABZ\fP     # \[aq]A\[aq] is ASCII 65; \[aq]Z\[aq] is ASCII 90
+<str1> is less than <str2> (\-25)
+$ \fB./string_comp ABJ ABC\fP
+<str1> is greater than <str2> (7)
+$ .\fB/string_comp $\[aq]\e201\[aq] A\fP   # 0201 \- 0101 = 0100 (or 64 decimal)
+<str1> is greater than <str2> (64)
+.EE
+.in
+.P
+The last example uses
+.BR bash (1)-specific
+syntax to produce a string containing an 8-bit ASCII code;
+the result demonstrates that the string comparison uses unsigned
+characters.
+.P
+And then some examples using
+.BR strncmp ():
+.P
+.in +4n
+.EX
+$ \fB./string_comp ABC AB 3\fP
+<str1> is greater than <str2> (67)
+$ \fB./string_comp ABC AB 2\fP
+<str1> and <str2> are equal in the first 2 bytes
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (string_comp.c)
+.EX
+/* string_comp.c
+\&
+   Licensed under GNU General Public License v2 or later.
+*/
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+\&
+int
+main(int argc, char *argv[])
+{
+    int res;
+\&
+    if (argc < 3) {
+        fprintf(stderr, "Usage: %s <str1> <str2> [<len>]\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    if (argc == 3)
+        res = strcmp(argv[1], argv[2]);
+    else
+        res = strncmp(argv[1], argv[2], atoi(argv[3]));
+\&
+    if (res == 0) {
+        printf("<str1> and <str2> are equal");
+        if (argc > 3)
+            printf(" in the first %d bytes\en", atoi(argv[3]));
+        printf("\en");
+    } else if (res < 0) {
+        printf("<str1> is less than <str2> (%d)\en", res);
+    } else {
+        printf("<str1> is greater than <str2> (%d)\en", res);
+    }
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR memcmp (3),
+.BR strcasecmp (3),
+.BR strcoll (3),
+.BR string (3),
+.BR strncasecmp (3),
+.BR strverscmp (3),
+.BR wcscmp (3),
+.BR wcsncmp (3),
+.BR ascii (7)