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