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