man3/memcmp.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\" Modified Sat Jul 24 18:55:27 1993 by Rik Faith (faith@cs.unc.edu)
  10 .TH MEMCMP 3 2021-03-22 "Linux man-pages (unreleased)"
  11 .SH NAME
  12 memcmp \- compare memory areas
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <string.h>
  19 .PP
  20 .BI "int memcmp(const void *" s1 ", const void *" s2 ", size_t " n );
  21 .fi
  22 .SH DESCRIPTION
  23 The
  24 .BR memcmp ()
  25 function compares the first \fIn\fP bytes (each interpreted as
  26 .IR "unsigned char" )
  27 of the memory areas \fIs1\fP and \fIs2\fP.
  28 .SH RETURN VALUE
  29 The
  30 .BR memcmp ()
  31 function returns an integer less than, equal to, or
  32 greater than zero if the first \fIn\fP bytes of \fIs1\fP is found,
  33 respectively, to be less than, to match, or be greater than the first
  34 \fIn\fP bytes of \fIs2\fP.
  35 .PP
  36 For a nonzero return value, the sign is determined by the sign of
  37 the difference between the first pair of bytes (interpreted as
  38 .IR "unsigned char" )
  39 that differ in
  40 .I s1
  41 and
  42 .IR s2 .
  43 .PP
  44 If
  45 .I n
  46 is zero, the return value is zero.
  47 .SH ATTRIBUTES
  48 For an explanation of the terms used in this section, see
  49 .BR attributes (7).
  50 .ad l
  51 .nh
  52 .TS
  53 allbox;
  54 lbx lb lb
  55 l l l.
  56 Interface       Attribute       Value
  57 T{
  58 .BR memcmp ()
  59 T}      Thread safety   MT-Safe
  60 .TE
  61 .hy
  62 .ad
  63 .sp 1
  64 .SH STANDARDS
  65 POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
  66 .SH NOTES
  67 Do not use
  68 .BR memcmp ()
  69 to compare security critical data, such as cryptographic secrets,
  70 because the required CPU time depends on the number of equal bytes.
  71 Instead, a function that performs comparisons in constant time is required.
  72 Some operating systems provide such a function (e.g., NetBSD's
  73 .BR consttime_memequal ()),
  74 but no such function is specified in POSIX.
  75 On Linux, it may be necessary to implement such a function oneself.
  76 .SH SEE ALSO
  77 .BR bcmp (3),
  78 .BR bstring (3),
  79 .BR strcasecmp (3),
  80 .BR strcmp (3),
  81 .BR strcoll (3),
  82 .BR strncasecmp (3),
  83 .BR strncmp (3),
  84 .BR wmemcmp (3)