man3/strcmp.3

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