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