sys/man/2/memory

   1 .TH MEMORY 2
   2 .SH NAME
   3 memccpy, memchr, memcmp, memcpy, memmove, memset, tsmemcmp \- memory operations
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .ta \w'\fLvoid* 'u
  10 .B
  11 void*   memccpy(void *s1, void *s2, int c, usize n)
  12 .PP
  13 .B
  14 void*   memchr(void *s, int c, usize n)
  15 .PP
  16 .B
  17 int     memcmp(void *s1, void *s2, usize n)
  18 .PP
  19 .B
  20 void*   memcpy(void *s1, void *s2, usize n)
  21 .PP
  22 .B
  23 void*   memmove(void *s1, void *s2, usize n)
  24 .PP
  25 .B
  26 void*   memset(void *s, int c, usize n)
  27 .PP
  28 .B #include <libsec.h>
  29 .PP
  30 .B
  31 int     tsmemcmp(void *s1, void *s2, ulong n)
  32 .SH DESCRIPTION
  33 These functions operate efficiently on memory areas
  34 (arrays of bytes bounded by a count, not terminated by a zero byte).
  35 They do not check for the overflow of any receiving memory area.
  36 .PP
  37 .I Memccpy
  38 copies bytes from memory area
  39 .I s2
  40 into
  41 .IR s1 ,
  42 stopping after the first occurrence of byte
  43 .I c
  44 has been copied, or after
  45 .I n
  46 bytes have been copied, whichever comes first.
  47 It returns a pointer to the byte after
  48 the copy of
  49 .I c
  50 in
  51 .IR s1 ,
  52 or zero if
  53 .I c
  54 was not found in the first
  55 .I n
  56 bytes of
  57 .IR s2 .
  58 .PP
  59 .I Memchr
  60 returns a pointer to the first
  61 occurrence of byte
  62 .I c
  63 in the first
  64 .I n
  65 bytes of memory area
  66 .IR s,
  67 or zero if
  68 .I c
  69 does not occur.
  70 .PP
  71 .I Memcmp
  72 compares its arguments, looking at the first
  73 .I n
  74 bytes only, and returns an integer
  75 less than, equal to, or greater than 0,
  76 according as
  77 .I s1
  78 is lexicographically less than, equal to, or
  79 greater than
  80 .IR s2 .
  81 The comparison is bytewise unsigned.
  82 .PP
  83 .I Memcpy
  84 copies
  85 .I n
  86 bytes from memory area
  87 .I s2
  88 to
  89 .IR s1 .
  90 It returns
  91 .IR s1 .
  92 .PP
  93 .I Memmove
  94 works like
  95 .IR memcpy ,
  96 except that it is guaranteed to work if
  97 .I s1
  98 and
  99 .IR s2
 100 overlap.
 101 .PP
 102 .I Memset
 103 sets the first
 104 .I n
 105 bytes in memory area
 106 .I s
 107 to the value of byte
 108 .IR c .
 109 It returns
 110 .IR s .
 111 .PP
 112 .I Tsmemcmp
 113 is a variant of
 114 .I memcmp
 115 that is safe against timing attacks.
 116 It does not stop when it sees a difference, this way it's runtime is function of
 117 .I n
 118 and not something that can lead clues to attackers.
 119 .SH SOURCE
 120 All these routines have portable C implementations in
 121 .BR /sys/src/libc/port .
 122 Most also have machine-dependent assembly language implementations in
 123 .BR /sys/src/libc/$objtype .
 124 .I Tsmemcmp
 125 is found on
 126 .BR /sys/src/libsec/port/tsmemcmp.c .
 127 .SH SEE ALSO
 128 .IR strcat (2)
 129 .SH BUGS
 130 ANSI C does not require
 131 .I memcpy
 132 to handle overlapping source and destination; on Plan 9, it does, so
 133 .I memmove
 134 and
 135 .I memcpy
 136 behave identically.
 137 .PP
 138 If
 139 .I memcpy
 140 and
 141 .I memmove
 142 are handed a negative count, they abort.
 143 .PP
 144 .I Memcmp
 145 should not be used to compare sensitive data as it's vulnerable to timing attacks. Instead,
 146 .I tsmemcmp
 147 should be used.