4849 strlcpy(9F) points to the wrong header

          --- old/usr/src/man/man9f/string.9f
          +++ new/usr/src/man/man9f/string.9f
   1    1  '\" te
   2    2  .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
   3    3  .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4    4  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5    5  .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6      -.TH STRING 9F "Feb 27, 2009"
        6 +.TH STRING 9F "Jun 4, 2014"
   7    7  .SH NAME
   8    8  string, strcasecmp, strncasecmp, strncat, strlcat, strchr, strrchr, strcmp,
   9    9  strncmp, strcpy, strncpy, strlcpy, strfree, strspn, strdup, ddi_strdup, strlen,
  10   10  strnlen \- string operations
  11   11  .SH SYNOPSIS
  12   12  .LP
  13   13  .nf
  14   14  #include <sys/ddi.h>
       15 +#include <sys/sunddi.h>
  15   16  
  16   17  \fBint\fR \fBstrcasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  17   18  .fi
  18   19  
  19   20  .LP
  20   21  .nf
  21   22  \fBint\fR \fBstrncasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
  22   23  .fi
  23   24  
  24   25  .LP

  25   26  .nf
  26   27  \fBchar *\fR\fBstrncat\fR(\fBchar *\fR \fIs1\fR, \fBconst char *\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
  27   28  .fi
  28   29  
  29   30  .LP
  30   31  .nf
  31   32  \fBsize_t\fR \fBstrlcat\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
  32   33  .fi
  33   34  
  34   35  .LP
  35   36  .nf
  36   37  \fBchar *\fR\fBstrchr\fR(\fBconst char *\fR\fIstr\fR, \fBint\fR \fIchr\fR);
  37   38  .fi
  38   39  
  39   40  .LP
  40   41  .nf
  41   42  \fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIstr\fR, \fBint\fR \fIchr\fR);
  42   43  .fi
  43   44  
  44   45  .LP
  45   46  .nf
  46   47  \fBint\fR \fBstrcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  47   48  .fi
  48   49  
  49   50  .LP
  50   51  .nf
  51   52  \fBint\fR \fBstrncmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
  52   53  .fi
  53   54  
  54   55  .LP
  55   56  .nf
  56   57  \fBchar *\fR\fBstrcpy\fR(\fBchar *\fR \fIdst\fR, \fBconst char *\fR \fIsrc\fR);
  57   58  .fi
  58   59  
  59   60  .LP
  60   61  .nf
  61   62  \fBchar *\fR\fBstrncpy\fR(\fBchar *\fR \fIdst\fR, \fBconst char *\fR \fIsrc\fR, \fBsize_t\fR \fIn\fR);
  62   63  .fi
  63   64  
  64   65  .LP
  65   66  .nf
  66   67  \fBsize_t\fR \fBstrlcpy\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
  67   68  .fi
  68   69  
  69   70  .LP
  70   71  .nf
  71   72  \fBvoid\fR \fBstrfree\fR(\fBchar *\fR\fIs\fR);
  72   73  .fi
  73   74  
  74   75  .LP
  75   76  .nf
  76   77  \fBsize_t\fR \fBstrspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  77   78  .fi
  78   79  
  79   80  .LP
  80   81  .nf
  81   82  \fBchar *\fR\fBstrdup\fR(\fBconst char *\fR\fIs1\fR);
  82   83  .fi
  83   84  
  84   85  .LP
  85   86  .nf
  86   87  \fBchar *\fR\fBddi_strdup\fR(\fBconst char *\fR\fIs1\fR, \fBint\fR \fIflag\fR);
  87   88  .fi
  88   89  
  89   90  .LP
  90   91  .nf
  91   92  \fBsize_t\fR \fBstrlen\fR(\fBconst char *\fR\fIs\fR);
  92   93  .fi
  93   94  
  94   95  .LP
  95   96  .nf
  96   97  \fBsize_t\fR \fBstrnlen\fR(\fBconst char *\fR\fIs\fR, \fBsize_t\fR \fIn\fR);
  97   98  .fi
  98   99  
  99  100  .SH INTERFACE LEVEL
 100  101  .sp
 101  102  .LP
 102  103  Solaris DDI specific (Solaris DDI).
 103  104  .SH DESCRIPTION
 104  105  .sp
 105  106  .LP
 106  107  The arguments \fIs\fR, \fIs1\fR, and \fIs2\fR point to strings (arrays of
 107  108  characters terminated by a null character). The \fBstrcat()\fR,
 108  109  \fBstrncat()\fR, \fBstrlcat()\fR, \fBstrcpy()\fR, \fBstrncpy()\fR,
 109  110  \fBstrlcpy()\fR, and \fBstrfree()\fR functions all alter their first argument.
 110  111  Additionally, the \fBstrcpy()\fR function does not check for overflow of the
 111  112  array.
 112  113  .SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR"
 113  114  .sp
 114  115  .LP
 115  116  The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions are case-insensitive
 116  117  versions of  \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below.
 117  118  They assume the \fBASCII\fR character set and ignore differences in case when
 118  119  comparing lower and upper case characters.
 119  120  .SS "\fBstrncat()\fR, \fBstrlcat()\fR"
 120  121  .sp
 121  122  .LP
 122  123  The \fBstrncat()\fR function appends at most \fIn\fR characters of string
 123  124  \fIs2\fR, including the terminating null character, to the end of string
 124  125  \fIs1\fR. It returns a pointer to the null-terminated result. The initial
 125  126  character of  \fIs2\fR overrides the null character at the end of \fIs1\fR. If
 126  127  copying takes place between objects that overlap, the behavior of
 127  128  \fBstrncat()\fRand \fBstrlcat()\fR is undefined.
 128  129  .sp
 129  130  .LP
 130  131  The \fBstrlcat()\fR function appends  at most
 131  132  (\fIdstsize\fR-\fBstrlen\fR(\fIdst\fR)-1) characters of \fIsrc\fR to \fIdst\fR
 132  133  (\fIdstsize\fR being the  size of the  string buffer \fIdst\fR). If the string
 133  134  pointed to by \fIdst\fR contains a null-terminated string that fits into
 134  135  \fIdstsize\fR bytes when \fBstrlcat()\fR is called, the string pointed to by
 135  136  \fIdst\fR will be a null-terminated string that fits in \fIdstsize\fR bytes
 136  137  (including the terminating null character) when it completes, and the initial
 137  138  character of \fIsrc\fR will override the null character at  the end of
 138  139  \fIdst\fR. If the string pointed to by \fIdst\fR is longer than \fIdstsize\fR
 139  140  bytes when \fBstrlcat()\fR is called, the string pointed to by \fIdst\fR will
 140  141  not be changed. The function returns
 141  142  \fBmin\fR{\fIdstsize\fR,\fBstrlen\fR(\fIdst\fR)}+\fBstrlen\fR(\fIsrc\fR).
 142  143  Buffer overflow can be checked as  follows:
 143  144  .sp
 144  145  .in +2
 145  146  .nf
 146  147  if (strlcat(dst, src, dstsize) >= dstsize)
 147  148          return \(mi1;
 148  149  .fi
 149  150  .in -2
 150  151  
 151  152  .SS "\fBstrchr()\fR, \fBstrrchr()\fR"
 152  153  .sp
 153  154  .LP
 154  155  The \fBstrchr()\fR function returns a pointer to the first occurrence of
 155  156  \fIc\fR (converted to a  \fBchar\fR) in string \fIs\fR, or a null pointer if
 156  157  \fIc\fR does not occur in the string. The \fBstrrchr()\fR function returns a
 157  158  pointer to the last occurrence of \fIc\fR. The null character terminating a
 158  159  string is considered to be part of the string.
 159  160  .SS "\fBstrcmp()\fR, \fBstrncmp()\fR"
 160  161  .sp
 161  162  .LP
 162  163  The \fBstrcmp()\fR function compares two strings byte-by-byte, according to the
 163  164  ordering of your machine's character set.  The function returns an integer
 164  165  greater than, equal to, or less than 0, if  the string pointed to by \fIs1\fR
 165  166  is greater than, equal to, or less than the string pointed to by \fIs2\fR
 166  167  respectively. The sign of a non-zero return value is determined  by the sign of
 167  168  the difference between the values of the first pair of bytes that differ in the
 168  169  strings being compared. The \fBstrncmp()\fR function makes the same comparison
 169  170  but looks at a maximum of \fIn\fR bytes. Bytes following a null byte are not
 170  171  compared.
 171  172  .SS "\fBstrcpy()\fR, \fBstrncpy()\fR, \fBstrlcpy()\fR"
 172  173  .sp
 173  174  .LP
 174  175  The \fBstrcpy()\fR function copies string \fIs2\fR to \fIs1\fR, including the
 175  176  terminating null character, stopping after the null character has been copied.
 176  177  The \fBstrncpy()\fR function copies exactly \fIn\fR bytes, truncating \fIs2\fR
 177  178  or adding null characters to \fIs1\fR if necessary. The result will not be
 178  179  null-terminated if the length of \fIs2\fR is \fIn\fR or more. Each function
 179  180  returns \fIs1\fR.  If copying takes place between objects that overlap, the
 180  181  behavior of \fBstrcpy()\fR, \fBstrncpy()\fR, and \fBstrlcpy()\fR is undefined.
 181  182  .sp
 182  183  .LP
 183  184  The \fBstrlcpy()\fR function copies  at most \fIdstsize\fR\(mi1 characters
 184  185  (\fIdstsize\fR being the  size of the  string buffer \fIdst\fR) from \fIsrc\fR
 185  186  to \fIdst\fR,  truncating \fIsrc\fR if necessary.  The  result is always
 186  187  null-terminated. The function returns \fBstrlen\fR(\fIsrc\fR). Buffer overflow
 187  188  can be checked as  follows:
 188  189  .sp
 189  190  .in +2
 190  191  .nf
 191  192  if (strlcpy(dst, src, dstsize) >= dstsize)
 192  193          return \(mi1;
 193  194  .fi
 194  195  .in -2
 195  196  
 196  197  .SS "\fBstrfree()\fR"
 197  198  .sp
 198  199  .LP
 199  200  The \fBstrfree()\fR function frees the memory associated with the string
 200  201  pointed to by \fIs\fR.  This memory pointed to by \fIs\fR must be of size
 201  202  \fBstrlen\fR(\fIs\fR)+1, and must have been allocated (either directly or
 202  203  indirectly) by \fBkmem_alloc\fR(9F) or \fBkmem_zalloc\fR(9F).
 203  204  .SS "\fBstrspn()\fR"
 204  205  .sp
 205  206  .LP
 206  207  The \fBstrspn()\fR function returns the length of the initial segment of string
 207  208  \fIs1\fR that consists entirely of characters from string \fIs2\fR.
 208  209  .SS "\fBstrdup()\fR, \fBddi_strdup()\fR"
 209  210  .sp
 210  211  .LP
 211  212  The \fBddi_strdup()\fR function returns a pointer to a new string that is a
 212  213  duplicate of the string pointed to by \fIs1\fR. The returned pointer can be
 213  214  passed to \fBstrfree()\fR or \fBkmem_free\fR(9F). The space for the new string
 214  215  is obtained using \fBkmem_alloc()\fR. flag can be either \fBKM_SLEEP\fR or
 215  216  \fBKM_NOSLEEP\fR, and determines whether the caller can sleep for memory.
 216  217  \fBKM_SLEEP\fR allocations may sleep but are guaranteed to succeed.
 217  218  \fBKM_NOSLEEP\fR allocations are guaranteed not to sleep but may fail (return
 218  219  \fINULL\fR) if no memory is currently available.
 219  220  .sp
 220  221  .LP
 221  222  The \fBstrdup()\fR function behaves the same as the \fBddi_strdup()\fR when
 222  223  called with the \fBKM_SLEEP\fR flag. This means that \fBstrdup()\fR can sleep
 223  224  until memory is available and will always succeed.
 224  225  .SS "\fBstrlen()\fR, \fBstrnlen()\fR"
 225  226  .sp
 226  227  .LP
 227  228  The \fBstrlen()\fR function returns the number of bytes in \fIs\fR, not
 228  229  including the terminating null character.
 229  230  .sp
 230  231  .LP
 231  232  The \fBstrnlen()\fR function returns the smaller of \fIn\fR or the number of
 232  233  bytes in \fIs\fR, not including the terminating null character. The
 233  234  \fBstrnlen()\fR function never examines more than \fIn\fR bytes of the string
 234  235  pointed to by \fIs\fR.
 235  236  .SH CONTEXT
 236  237  .sp
 237  238  .LP
 238  239  The \fBstrdup()\fR and \fBddi_strdup()\fR functions can be called from user or
 239  240  kernel context.
 240  241  .sp
 241  242  .LP
 242  243  The \fBddi_strdup()\fR function can be called from interrupt context only if
 243  244  the \fBKM_NOSLEEP\fR flag is set.
 244  245  .sp
 245  246  .LP
 246  247  All the other string manipulation functions can be called from user, interrupt,
 247  248  or kernel context.
 248  249  .SH ATTRIBUTES
 249  250  .sp
 250  251  .LP
 251  252  See \fBattributes\fR(5) for descriptions of the following attributes:
 252  253  .sp
 253  254  
 254  255  .sp
 255  256  .TS
 256  257  box;
 257  258  c | c
 258  259  l | l .
 259  260  ATTRIBUTE TYPE  ATTRIBUTE VALUE
 260  261  _
 261  262  Interface Stability     Committed
 262  263  .TE
 263  264  
 264  265  .SH SEE ALSO
 265  266  .sp
 266  267  .LP
 267  268  \fBstring\fR(3C), \fBattributes\fR(5), \fBbcopy\fR(9F), \fBddi_copyin\fR(9F),
 268  269  \fBkmem_alloc\fR(9F)
 269  270  .sp
 270  271  .LP
 271  272  \fIWriting Device Drivers\fR
 272  273  .SH NOTES
 273  274  .sp
 274  275  .LP
 275  276  If copying takes place between objects that overlap, the behavior of
 276  277  \fBstrlcat()\fR, \fBstrncat()\fR, \fBstrcpy()\fR, \fBstrlcpy()\fR, and
 277  278  \fBstrncpy()\fR is undefined.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX