string/FreeBSD/strcpy.3.patch

   1 --- strcpy.3.orig       2010-04-28 23:38:50.000000000 -0700
   2 +++ strcpy.3    2010-04-29 09:37:17.000000000 -0700
   3 @@ -43,13 +43,27 @@
   4  .Sh SYNOPSIS
   5  .In string.h
   6  .Ft char *
   7 -.Fn stpcpy "char * restrict dst" "const char * restrict src"
   8 +.Fo stpcpy
   9 +.Fa "char *s1"
  10 +.Fa "const char *s2"
  11 +.Fc
  12  .Ft char *
  13 -.Fn stpncpy "char * restrict dst" "const char * restrict src" "size_t len"
  14 +.Fo stpncpy
  15 +.Fa "char *restrict s1"
  16 +.Fa "const char *restrict s2"
  17 +.Fa "size_t n"
  18 +.Fc
  19  .Ft char *
  20 -.Fn strcpy "char * restrict dst" "const char * restrict src"
  21 +.Fo strcpy
  22 +.Fa "char *restrict s1"
  23 +.Fa "const char *restrict s2"
  24 +.Fc
  25  .Ft char *
  26 -.Fn strncpy "char * restrict dst" "const char * restrict src" "size_t len"
  27 +.Fo strncpy
  28 +.Fa "char *restrict s1"
  29 +.Fa "const char *restrict s2"
  30 +.Fa "size_t n"
  31 +.Fc
  32  .Sh DESCRIPTION
  33  The
  34  .Fn stpcpy
  35 @@ -57,38 +71,41 @@ and
  36  .Fn strcpy
  37  functions
  38  copy the string
  39 -.Fa src
  40 +.Fa s2
  41  to
  42 -.Fa dst
  43 +.Fa s1
  44  (including the terminating
  45  .Ql \e0
  46 -character.)
  47 +character).
  48  .Pp
  49  The
  50  .Fn stpncpy
  51  and
  52  .Fn strncpy
  53  functions copy at most
  54 -.Fa len
  55 +.Fa n
  56  characters from
  57 -.Fa src
  58 +.Fa s2
  59  into
  60 -.Fa dst .
  61 +.Fa s1 .
  62  If
  63 -.Fa src
  64 +.Fa s2
  65  is less than
  66 -.Fa len
  67 +.Fa n
  68  characters long,
  69  the remainder of
  70 -.Fa dst
  71 +.Fa s1
  72  is filled with
  73  .Ql \e0
  74  characters.
  75  Otherwise,
  76 -.Fa dst
  77 +.Fa s1
  78  is
  79  .Em not
  80  terminated.
  81 +.Pp
  82 +The source and destination strings should not overlap, as the
  83 +behavior is undefined.
  84  .Sh RETURN VALUES
  85  The
  86  .Fn strcpy
  87 @@ -96,7 +113,7 @@ and
  88  .Fn strncpy
  89  functions
  90  return
  91 -.Fa dst .
  92 +.Fa s1 .
  93  The
  94  .Fn stpcpy
  95  and
  96 @@ -104,15 +121,15 @@ and
  97  functions return a pointer to the terminating
  98  .Ql \e0
  99  character of
 100 -.Fa dst .
 101 +.Fa s1 .
 102  If
 103  .Fn stpncpy
 104  does not terminate
 105 -.Fa dst
 106 +.Fa s1
 107  with a
 108  .Dv NUL
 109  character, it instead returns a pointer to
 110 -.Li dst[n]
 111 +.Li s1[n]
 112  (which does not necessarily refer to a valid memory location.)
 113  .Sh EXAMPLES
 114  The following sets
 115 @@ -139,7 +156,7 @@ Note that it does
 116  .Em not
 117  .Tn NUL
 118  terminate
 119 -.Va chararray
 120 +.Va chararray ,
 121  because the length of the source string is greater than or equal
 122  to the length argument.
 123  .Pp
 124 @@ -169,21 +186,26 @@ This could be better achieved using
 125  as shown in the following example:
 126  .Pp
 127  .Dl "(void)strlcpy(buf, input, sizeof(buf));"
 128 -.Pp
 129 -Note that because
 130 -.Xr strlcpy 3
 131 -is not defined in any standards, it should
 132 -only be used when portability is not a concern.
 133  .Sh SECURITY CONSIDERATIONS
 134  The
 135 -.Fn strcpy
 136 -function is easily misused in a manner which enables malicious users
 137 +.Fn strcpy ,
 138 +.Fn strncpy ,
 139 +.Fn stpcpy ,
 140 +and
 141 +.Fn stpncpy
 142 +functions are easily misused in a manner which enables malicious users
 143  to arbitrarily change a running program's functionality through a
 144  buffer overflow attack.
 145  (See
 146  the FSA
 147  and
 148  .Sx EXAMPLES . )
 149 +.Pp
 150 +It is recommended that
 151 +.Xr strlcpy 3
 152 +be used instead as a way to avoid such problems.
 153 +.Xr strlcpy 3
 154 +is not defined in any standards, but it has been adopted by most major libc implementations.
 155  .Sh SEE ALSO
 156  .Xr bcopy 3 ,
 157  .Xr memccpy 3 ,