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 .P
  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 .P
  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 .P
  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 .SH VERSIONS
  95 POSIX.1 specifies only that:
  96 .RS
  97 .P
  98 The sign of a nonzero return value shall be determined by the sign
  99 of the difference between the values of the first pair of bytes
 100 (both interpreted as type
 101 .IR "unsigned char" )
 102 that differ in the strings being compared.
 103 .RE
 104 .P
 105 In glibc, as in most other implementations,
 106 the return value is the arithmetic result of subtracting
 107 the last compared byte in
 108 .I s2
 109 from the last compared byte in
 110 .IR s1 .
 111 (If the two characters are equal, this difference is 0.)
 112 .SH STANDARDS
 113 C11, POSIX.1-2008.
 114 .SH HISTORY
 115 POSIX.1-2001, C89, SVr4, 4.3BSD.
 116 .SH EXAMPLES
 117 The program below can be used to demonstrate the operation of
 118 .BR strcmp ()
 119 (when given two arguments) and
 120 .BR strncmp ()
 121 (when given three arguments).
 122 First, some examples using
 123 .BR strcmp ():
 124 .P
 125 .in +4n
 126 .EX
 127 $ \fB./string_comp ABC ABC\fP
 128 <str1> and <str2> are equal
 129 $ \fB./string_comp ABC AB\fP      # \[aq]C\[aq] is ASCII 67; \[aq]C\[aq] \- \[aq]\e0\[aq] = 67
 130 <str1> is greater than <str2> (67)
 131 $ \fB./string_comp ABA ABZ\fP     # \[aq]A\[aq] is ASCII 65; \[aq]Z\[aq] is ASCII 90
 132 <str1> is less than <str2> (\-25)
 133 $ \fB./string_comp ABJ ABC\fP
 134 <str1> is greater than <str2> (7)
 135 $ .\fB/string_comp $\[aq]\e201\[aq] A\fP   # 0201 \- 0101 = 0100 (or 64 decimal)
 136 <str1> is greater than <str2> (64)
 137 .EE
 138 .in
 139 .P
 140 The last example uses
 141 .BR bash (1)-specific
 142 syntax to produce a string containing an 8-bit ASCII code;
 143 the result demonstrates that the string comparison uses unsigned
 144 characters.
 145 .P
 146 And then some examples using
 147 .BR strncmp ():
 148 .P
 149 .in +4n
 150 .EX
 151 $ \fB./string_comp ABC AB 3\fP
 152 <str1> is greater than <str2> (67)
 153 $ \fB./string_comp ABC AB 2\fP
 154 <str1> and <str2> are equal in the first 2 bytes
 155 .EE
 156 .in
 157 .SS Program source
 158 \&
 159 .\" SRC BEGIN (string_comp.c)
 160 .EX
 161 /* string_comp.c
 162 \&
 163    Licensed under GNU General Public License v2 or later.
 164 */
 165 #include <stdio.h>
 166 #include <stdlib.h>
 167 #include <string.h>
 168 \&
 169 int
 170 main(int argc, char *argv[])
 171 {
 172     int res;
 173 \&
 174     if (argc < 3) {
 175         fprintf(stderr, "Usage: %s <str1> <str2> [<len>]\en", argv[0]);
 176         exit(EXIT_FAILURE);
 177     }
 178 \&
 179     if (argc == 3)
 180         res = strcmp(argv[1], argv[2]);
 181     else
 182         res = strncmp(argv[1], argv[2], atoi(argv[3]));
 183 \&
 184     if (res == 0) {
 185         printf("<str1> and <str2> are equal");
 186         if (argc > 3)
 187             printf(" in the first %d bytes\en", atoi(argv[3]));
 188         printf("\en");
 189     } else if (res < 0) {
 190         printf("<str1> is less than <str2> (%d)\en", res);
 191     } else {
 192         printf("<str1> is greater than <str2> (%d)\en", res);
 193     }
 194 \&
 195     exit(EXIT_SUCCESS);
 196 }
 197 .EE
 198 .\" SRC END
 199 .SH SEE ALSO
 200 .BR memcmp (3),
 201 .BR strcasecmp (3),
 202 .BR strcoll (3),
 203 .BR string (3),
 204 .BR strncasecmp (3),
 205 .BR strverscmp (3),
 206 .BR wcscmp (3),
 207 .BR wcsncmp (3),
 208 .BR ascii (7)