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.