man3/strcmp.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\" and Copyright 2020 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" References consulted:
   8 .\"     Linux libc source code
   9 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  10 .\"     386BSD man pages
  11 .\" Modified Sat Jul 24 18:08:52 1993 by Rik Faith (faith@cs.unc.edu)
  12 .\" Modified 2001-08-31, aeb
  13 .\"
  14 .TH strcmp 3 (date) "Linux man-pages (unreleased)"
  15 .SH NAME
  16 strcmp, strncmp \- compare two strings
  17 .SH LIBRARY
  18 Standard C library
  19 .RI ( libc ", " \-lc )
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <string.h>
  23 .PP
  24 .BI "int strcmp(const char *" s1 ", const char *" s2 );
  25 .BI "int strncmp(const char " s1 [. n "], const char " s2 [. n "], size_t " n );
  26 .fi
  27 .SH DESCRIPTION
  28 The
  29 .BR strcmp ()
  30 function compares the two strings
  31 .I s1
  32 and
  33 .IR s2 .
  34 The locale is not taken into account (for a locale-aware comparison, see
  35 .BR strcoll (3)).
  36 The comparison is done using unsigned characters.
  37 .PP
  38 .BR strcmp ()
  39 returns an integer indicating the result of the comparison, as follows:
  40 .IP \[bu] 3
  41 0, if the
  42 .I s1
  43 and
  44 .I s2
  45 are equal;
  46 .IP \[bu]
  47 a negative value if
  48 .I s1
  49 is less than
  50 .IR s2 ;
  51 .IP \[bu]
  52 a positive value if
  53 .I s1
  54 is greater than
  55 .IR s2 .
  56 .PP
  57 The
  58 .BR strncmp ()
  59 function is similar, except it compares
  60 only the first (at most)
  61 .I n
  62 bytes of
  63 .I s1
  64 and
  65 .IR s2 .
  66 .SH RETURN VALUE
  67 The
  68 .BR strcmp ()
  69 and
  70 .BR strncmp ()
  71 functions return an integer
  72 less than, equal to, or greater than zero if
  73 .I s1
  74 (or the first
  75 .I n
  76 bytes thereof) is found, respectively, to be less than, to
  77 match, or be greater than
  78 .IR s2 .
  79 .SH ATTRIBUTES
  80 For an explanation of the terms used in this section, see
  81 .BR attributes (7).
  82 .TS
  83 allbox;
  84 lbx lb lb
  85 l l l.
  86 Interface       Attribute       Value
  87 T{
  88 .na
  89 .nh
  90 .BR strcmp (),
  91 .BR strncmp ()
  92 T}      Thread safety   MT-Safe
  93 .TE
  94 .sp 1
  95 .SH VERSIONS
  96 POSIX.1 specifies only that:
  97 .RS
  98 .PP
  99 The sign of a nonzero return value shall be determined by the sign
 100 of the difference between the values of the first pair of bytes
 101 (both interpreted as type
 102 .IR "unsigned char" )
 103 that differ in the strings being compared.
 104 .RE
 105 .PP
 106 In glibc, as in most other implementations,
 107 the return value is the arithmetic result of subtracting
 108 the last compared byte in
 109 .I s2
 110 from the last compared byte in
 111 .IR s1 .
 112 (If the two characters are equal, this difference is 0.)
 113 .SH STANDARDS
 114 C11, POSIX.1-2008.
 115 .SH HISTORY
 116 POSIX.1-2001, C89, SVr4, 4.3BSD.
 117 .SH EXAMPLES
 118 The program below can be used to demonstrate the operation of
 119 .BR strcmp ()
 120 (when given two arguments) and
 121 .BR strncmp ()
 122 (when given three arguments).
 123 First, some examples using
 124 .BR strcmp ():
 125 .PP
 126 .in +4n
 127 .EX
 128 $ \fB./string_comp ABC ABC\fP
 129 <str1> and <str2> are equal
 130 $ \fB./string_comp ABC AB\fP      # \[aq]C\[aq] is ASCII 67; \[aq]C\[aq] \- \[aq]\e0\[aq] = 67
 131 <str1> is greater than <str2> (67)
 132 $ \fB./string_comp ABA ABZ\fP     # \[aq]A\[aq] is ASCII 65; \[aq]Z\[aq] is ASCII 90
 133 <str1> is less than <str2> (\-25)
 134 $ \fB./string_comp ABJ ABC\fP
 135 <str1> is greater than <str2> (7)
 136 $ .\fB/string_comp $\[aq]\e201\[aq] A\fP   # 0201 \- 0101 = 0100 (or 64 decimal)
 137 <str1> is greater than <str2> (64)
 138 .EE
 139 .in
 140 .PP
 141 The last example uses
 142 .BR bash (1)-specific
 143 syntax to produce a string containing an 8-bit ASCII code;
 144 the result demonstrates that the string comparison uses unsigned
 145 characters.
 146 .PP
 147 And then some examples using
 148 .BR strncmp ():
 149 .PP
 150 .in +4n
 151 .EX
 152 $ \fB./string_comp ABC AB 3\fP
 153 <str1> is greater than <str2> (67)
 154 $ \fB./string_comp ABC AB 2\fP
 155 <str1> and <str2> are equal in the first 2 bytes
 156 .EE
 157 .in
 158 .SS Program source
 159 \&
 160 .\" SRC BEGIN (string_comp.c)
 161 .EX
 162 /* string_comp.c
 163 \&
 164    Licensed under GNU General Public License v2 or later.
 165 */
 166 #include <stdio.h>
 167 #include <stdlib.h>
 168 #include <string.h>
 169 \&
 170 int
 171 main(int argc, char *argv[])
 172 {
 173     int res;
 174 \&
 175     if (argc < 3) {
 176         fprintf(stderr, "Usage: %s <str1> <str2> [<len>]\en", argv[0]);
 177         exit(EXIT_FAILURE);
 178     }
 179 \&
 180     if (argc == 3)
 181         res = strcmp(argv[1], argv[2]);
 182     else
 183         res = strncmp(argv[1], argv[2], atoi(argv[3]));
 184 \&
 185     if (res == 0) {
 186         printf("<str1> and <str2> are equal");
 187         if (argc > 3)
 188             printf(" in the first %d bytes\en", atoi(argv[3]));
 189         printf("\en");
 190     } else if (res < 0) {
 191         printf("<str1> is less than <str2> (%d)\en", res);
 192     } else {
 193         printf("<str1> is greater than <str2> (%d)\en", res);
 194     }
 195 \&
 196     exit(EXIT_SUCCESS);
 197 }
 198 .EE
 199 .\" SRC END
 200 .SH SEE ALSO
 201 .BR memcmp (3),
 202 .BR strcasecmp (3),
 203 .BR strcoll (3),
 204 .BR string (3),
 205 .BR strncasecmp (3),
 206 .BR strverscmp (3),
 207 .BR wcscmp (3),
 208 .BR wcsncmp (3),
 209 .BR ascii (7)