strcmp(3)

1strcmp(3)                  Library Functions Manual                  strcmp(3)
2
3
4

NAME

6       strcmp, strncmp - compare two strings
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <string.h>
13
14       int strcmp(const char *s1, const char *s2);
15       int strncmp(const char s1[.n], const char s2[.n], size_t n);
16

DESCRIPTION

18       The  strcmp()  function compares the two strings s1 and s2.  The locale
19       is not taken into account (for  a  locale-aware  comparison,  see  str‐
20       coll(3)).  The comparison is done using unsigned characters.
21
22       strcmp() returns an integer indicating the result of the comparison, as
23       follows:
24
25       •  0, if the s1 and s2 are equal;
26
27       •  a negative value if s1 is less than s2;
28
29       •  a positive value if s1 is greater than s2.
30
31       The strncmp() function is similar, except it compares  only  the  first
32       (at most) n bytes of s1 and s2.
33

RETURN VALUE

35       The strcmp() and strncmp() functions return an integer less than, equal
36       to, or greater than zero if s1 (or the first n bytes thereof) is found,
37       respectively, to be less than, to match, or be greater than s2.
38

ATTRIBUTES

40       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
41       tributes(7).
42
43       ┌────────────────────────────────────────────┬───────────────┬─────────┐
44       │Interface                                   │ Attribute     │ Value   │
45       ├────────────────────────────────────────────┼───────────────┼─────────┤
46       │strcmp(), strncmp()                         │ Thread safety │ MT-Safe │
47       └────────────────────────────────────────────┴───────────────┴─────────┘
48

VERSIONS

50       POSIX.1 specifies only that:
51
52              The sign of a nonzero return value shall be  determined  by  the
53              sign  of  the difference between the values of the first pair of
54              bytes (both interpreted as type unsigned char)  that  differ  in
55              the strings being compared.
56
57       In  glibc,  as  in  most other implementations, the return value is the
58       arithmetic result of subtracting the last compared byte in s2 from  the
59       last  compared  byte  in  s1.   (If  the two characters are equal, this
60       difference is 0.)
61

STANDARDS

63       C11, POSIX.1-2008.
64

HISTORY

66       POSIX.1-2001, C89, SVr4, 4.3BSD.
67

EXAMPLES

69       The program below can be used to demonstrate the operation of  strcmp()
70       (when  given two arguments) and strncmp() (when given three arguments).
71       First, some examples using strcmp():
72
73           $ ./string_comp ABC ABC
74           <str1> and <str2> are equal
75           $ ./string_comp ABC AB      # 'C' is ASCII 67; 'C' - '\0' = 67
76           <str1> is greater than <str2> (67)
77           $ ./string_comp ABA ABZ     # 'A' is ASCII 65; 'Z' is ASCII 90
78           <str1> is less than <str2> (-25)
79           $ ./string_comp ABJ ABC
80           <str1> is greater than <str2> (7)
81           $ ./string_comp $'\201' A   # 0201 - 0101 = 0100 (or 64 decimal)
82           <str1> is greater than <str2> (64)
83
84       The last example uses bash(1)-specific syntax to produce a string  con‐
85       taining  an  8-bit  ASCII code; the result demonstrates that the string
86       comparison uses unsigned characters.
87
88       And then some examples using strncmp():
89
90           $ ./string_comp ABC AB 3
91           <str1> is greater than <str2> (67)
92           $ ./string_comp ABC AB 2
93           <str1> and <str2> are equal in the first 2 bytes
94
95   Program source
96
97       /* string_comp.c
98
99          Licensed under GNU General Public License v2 or later.
100       */
101       #include <stdio.h>
102       #include <stdlib.h>
103       #include <string.h>
104
105       int
106       main(int argc, char *argv[])
107       {
108           int res;
109
110           if (argc < 3) {
111               fprintf(stderr, "Usage: %s <str1> <str2> [<len>]\n", argv[0]);
112               exit(EXIT_FAILURE);
113           }
114
115           if (argc == 3)
116               res = strcmp(argv[1], argv[2]);
117           else
118               res = strncmp(argv[1], argv[2], atoi(argv[3]));
119
120           if (res == 0) {
121               printf("<str1> and <str2> are equal");
122               if (argc > 3)
123                   printf(" in the first %d bytes\n", atoi(argv[3]));
124               printf("\n");
125           } else if (res < 0) {
126               printf("<str1> is less than <str2> (%d)\n", res);
127           } else {
128               printf("<str1> is greater than <str2> (%d)\n", res);
129           }
130
131           exit(EXIT_SUCCESS);
132       }
133