Debian Codegraph @

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