Debian Codegraph @

upstream/mageia-cauldron/man3/strcmp.3

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