Debian Codegraph @

upstream/debian-trixie/man3/strcmp.3

raw
1 '\" t
2 .\" Copyright 1993 David Metcalfe ([email protected])
3 .\" and Copyright 2020 Michael Kerrisk <[email protected]>
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 ([email protected])
12 .\" Modified 2001-08-31, aeb
13 .\"
14 .TH strcmp 3 2024-06-15 "Linux man-pages 6.9.1"
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]\[rs]0\[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]\[rs]201\[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>]\[rs]n", 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\[rs]n", atoi(argv[3]));
188 printf("\[rs]n");
189 } else if (res < 0) {
190 printf("<str1> is less than <str2> (%d)\[rs]n", res);
191 } else {
192 printf("<str1> is greater than <str2> (%d)\[rs]n", 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)