string/NetBSD/memset_s.3

   1 .\"
   2 .\" Copyright (c) 2012 The NetBSD Foundation, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to The NetBSD Foundation
   6 .\" by Alan Barrett
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  21 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 .\" POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\"     $NetBSD$
  30 .\"
  31 .Dd February 21, 2012
  32 .Dt MEMSET_S 3
  33 .Os
  34 .Sh NAME
  35 .Nm memset_s
  36 .Nd copy a value to all bytes of a memory buffer
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .Fd "#define __STDC_WANT_LIB_EXT1__ 1
  41 .In string.h
  42 .Ft errno_t
  43 .Fn memset_s "void *s" "rsize_t smax" "int c" "rsize_t n"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn memset_s
  47 function copies the value
  48 .Fa c
  49 (converted to an unsigned char)
  50 into each of the first
  51 .Fa n
  52 bytes of the memory buffer whose starting address is given by
  53 .Fa s .
  54 .Pp
  55 It is a runtime-constraints violation if
  56 .Fa s
  57 is a null pointer,
  58 or if either of
  59 .Fa smax
  60 or
  61 .Fa n
  62 is larger than
  63 .Dv RSIZE_MAX ,
  64 or if
  65 .Fa smax
  66 is smaller than
  67 .Fa n .
  68 If there is a runtime-constraints violation, and if
  69 .Fa s
  70 is not a null pointer,
  71 and if
  72 .Fa smax
  73 is not larger than
  74 .Dv RSIZE_MAX ,
  75 then, before reporting the runtime-constraints violation,
  76 .Fn memset_s
  77 copies
  78 .Fa smax
  79 bytes to the destination.
  80 .Pp
  81 In contrast to the
  82 .Xr memset 3
  83 function,
  84 calls to
  85 .Fn memset_s
  86 will never be
  87 .Dq optimised away
  88 by a compiler.
  89 This property is required by the following sentences in
  90 section K.3.7.4.1 of
  91 .St -isoC-2011 :
  92 .Bd -filled -offset indent
  93 Unlike
  94 .Fn memset ,
  95 any call to the
  96 .Fn memset_s
  97 function shall be evaluated strictly according to the rules of
  98 the abstract machine as described in (5.1.2.3).
  99 That is, any call to the
 100 .Fn memset_s
 101 function shall assume that the memory indicated by
 102 .Fa s
 103 and
 104 .Fa n
 105 may be accessible in the future and thus must contain
 106 the values indicated by
 107 .Fa c .
 108 .Ed
 109 .Sh RETURN VALUES
 110 The
 111 .Fn memset_s
 112 function returns zero for success, or a non-zero error code
 113 if there was a runtime-constraints violation.
 114 .Sh ERRORS
 115 .Fn memset_s
 116 returns the following error codes.
 117 It does not store the error code in the global
 118 .Va errno
 119 variable:
 120 .Bl -tag -width Er
 121 .It Bq Er EINVAL
 122 The
 123 .Fa s
 124 argument was a null pointer.
 125 .It Bq Er E2BIG
 126 One or both of
 127 .Fa smax
 128 or
 129 .Fa n
 130 was larger than
 131 .Dv RSIZE_MAX .
 132 .It Bq Er EOVERFLOW
 133 .Fa n
 134 was larger than
 135 .Fa smax .
 136 .El
 137 .
 138 .Sh SEE ALSO
 139 .Xr memset 3 .
 140 .Sh STANDARDS
 141 The
 142 .Fn memset_s
 143 function conforms to
 144 .St -isoC-2011 ,
 145 except that the
 146 .Fn set_constraint_handler_s
 147 interface is not supported.