Debian Codegraph @

upstream/debian-trixie/man3/memcmp.3

raw
1 '\" t
2 .\" Copyright 1993 David Metcalfe ([email protected])
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" References consulted:
7 .\" Linux libc source code
8 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
9 .\" 386BSD man pages
10 .\" Modified Sat Jul 24 18:55:27 1993 by Rik Faith ([email protected])
11 .TH memcmp 3 2024-05-02 "Linux man-pages 6.9.1"
12 .SH NAME
13 memcmp \- compare memory areas
14 .SH LIBRARY
15 Standard C library
16 .RI ( libc ", " \-lc )
17 .SH SYNOPSIS
18 .nf
19 .B #include <string.h>
20 .P
21 .BI "int memcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n );
22 .fi
23 .SH DESCRIPTION
24 The
25 .BR memcmp ()
26 function compares the first \fIn\fP bytes (each interpreted as
27 .IR "unsigned char" )
28 of the memory areas \fIs1\fP and \fIs2\fP.
29 .SH RETURN VALUE
30 The
31 .BR memcmp ()
32 function returns an integer less than, equal to, or
33 greater than zero if the first \fIn\fP bytes of \fIs1\fP is found,
34 respectively, to be less than, to match, or be greater than the first
35 \fIn\fP bytes of \fIs2\fP.
36 .P
37 For a nonzero return value, the sign is determined by the sign of
38 the difference between the first pair of bytes (interpreted as
39 .IR "unsigned char" )
40 that differ in
41 .I s1
42 and
43 .IR s2 .
44 .P
45 If
46 .I n
47 is zero, the return value is zero.
48 .SH ATTRIBUTES
49 For an explanation of the terms used in this section, see
50 .BR attributes (7).
51 .TS
52 allbox;
53 lbx lb lb
54 l l l.
55 Interface Attribute Value
56 T{
57 .na
58 .nh
59 .BR memcmp ()
60 T} Thread safety MT-Safe
61 .TE
62 .SH STANDARDS
63 C11, POSIX.1-2008.
64 .SH HISTORY
65 POSIX.1-2001, C89, SVr4, 4.3BSD.
66 .SH CAVEATS
67 Do not use
68 .BR memcmp ()
69 to compare confidential data,
70 such as cryptographic secrets,
71 because the CPU time required for the comparison
72 depends on the contents of the addresses compared,
73 this function is subject to timing-based side-channel attacks.
74 In such cases,
75 a function that performs comparisons in deterministic time,
76 depending only on
77 .I n
78 (the quantity of bytes compared)
79 is required.
80 Some operating systems provide such a function (e.g., NetBSD's
81 .BR consttime_memequal ()),
82 but no such function is specified in POSIX.
83 On Linux, you may need to implement such a function yourself.
84 .SH SEE ALSO
85 .BR bstring (3),
86 .BR strcasecmp (3),
87 .BR strcmp (3),
88 .BR strcoll (3),
89 .BR strncasecmp (3),
90 .BR strncmp (3),
91 .BR wmemcmp (3)