diff options
Diffstat (limited to 'man/man3/strcmp.3')
| -rw-r--r-- | man/man3/strcmp.3 | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/man/man3/strcmp.3 b/man/man3/strcmp.3 new file mode 100644 index 000000000..3e910d97b --- /dev/null +++ b/man/man3/strcmp.3 @@ -0,0 +1,208 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2020 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:08:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-08-31, aeb +.\" +.TH strcmp 3 (date) "Linux man-pages (unreleased)" +.SH NAME +strcmp, strncmp \- compare two strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.P +.BI "int strcmp(const char *" s1 ", const char *" s2 ); +.BI "int strncmp(const char " s1 [. n "], const char " s2 [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strcmp () +function compares the two strings +.I s1 +and +.IR s2 . +The locale is not taken into account (for a locale-aware comparison, see +.BR strcoll (3)). +The comparison is done using unsigned characters. +.P +.BR strcmp () +returns an integer indicating the result of the comparison, as follows: +.IP \[bu] 3 +0, if the +.I s1 +and +.I s2 +are equal; +.IP \[bu] +a negative value if +.I s1 +is less than +.IR s2 ; +.IP \[bu] +a positive value if +.I s1 +is greater than +.IR s2 . +.P +The +.BR strncmp () +function is similar, except it compares +only the first (at most) +.I n +bytes of +.I s1 +and +.IR s2 . +.SH RETURN VALUE +The +.BR strcmp () +and +.BR strncmp () +functions return an integer +less than, equal to, or greater than zero if +.I s1 +(or the first +.I n +bytes thereof) is found, respectively, to be less than, to +match, or be greater than +.IR s2 . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strcmp (), +.BR strncmp () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +POSIX.1 specifies only that: +.RS +.P +The sign of a nonzero return value shall be determined by the sign +of the difference between the values of the first pair of bytes +(both interpreted as type +.IR "unsigned char" ) +that differ in the strings being compared. +.RE +.P +In glibc, as in most other implementations, +the return value is the arithmetic result of subtracting +the last compared byte in +.I s2 +from the last compared byte in +.IR s1 . +(If the two characters are equal, this difference is 0.) +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH EXAMPLES +The program below can be used to demonstrate the operation of +.BR strcmp () +(when given two arguments) and +.BR strncmp () +(when given three arguments). +First, some examples using +.BR strcmp (): +.P +.in +4n +.EX +$ \fB./string_comp ABC ABC\fP +<str1> and <str2> are equal +$ \fB./string_comp ABC AB\fP # \[aq]C\[aq] is ASCII 67; \[aq]C\[aq] \- \[aq]\e0\[aq] = 67 +<str1> is greater than <str2> (67) +$ \fB./string_comp ABA ABZ\fP # \[aq]A\[aq] is ASCII 65; \[aq]Z\[aq] is ASCII 90 +<str1> is less than <str2> (\-25) +$ \fB./string_comp ABJ ABC\fP +<str1> is greater than <str2> (7) +$ .\fB/string_comp $\[aq]\e201\[aq] A\fP # 0201 \- 0101 = 0100 (or 64 decimal) +<str1> is greater than <str2> (64) +.EE +.in +.P +The last example uses +.BR bash (1)-specific +syntax to produce a string containing an 8-bit ASCII code; +the result demonstrates that the string comparison uses unsigned +characters. +.P +And then some examples using +.BR strncmp (): +.P +.in +4n +.EX +$ \fB./string_comp ABC AB 3\fP +<str1> is greater than <str2> (67) +$ \fB./string_comp ABC AB 2\fP +<str1> and <str2> are equal in the first 2 bytes +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (string_comp.c) +.EX +/* string_comp.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +int +main(int argc, char *argv[]) +{ + int res; +\& + if (argc < 3) { + fprintf(stderr, "Usage: %s <str1> <str2> [<len>]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (argc == 3) + res = strcmp(argv[1], argv[2]); + else + res = strncmp(argv[1], argv[2], atoi(argv[3])); +\& + if (res == 0) { + printf("<str1> and <str2> are equal"); + if (argc > 3) + printf(" in the first %d bytes\en", atoi(argv[3])); + printf("\en"); + } else if (res < 0) { + printf("<str1> is less than <str2> (%d)\en", res); + } else { + printf("<str1> is greater than <str2> (%d)\en", res); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR memcmp (3), +.BR strcasecmp (3), +.BR strcoll (3), +.BR string (3), +.BR strncasecmp (3), +.BR strverscmp (3), +.BR wcscmp (3), +.BR wcsncmp (3), +.BR ascii (7) |