1 /** @file 2 The header <string.h> declares one type and several functions, and defines 3 one macro useful for manipulating arrays of character type and other objects 4 treated as arrays of character type. Various methods are used for 5 determining the lengths of the arrays, but in all cases a char * or void * 6 argument points to the initial (lowest addressed) character of the array. If 7 an array is accessed beyond the end of an object, the behavior is undefined. 8 9 Where an argument declared as size_t n specifies the length of the array for 10 a function, n can have the value zero on a call to that function. Unless 11 explicitly stated otherwise in the description of those functions, pointer 12 arguments on such a call must still have valid values. 13 14 For all functions declared in this header, each character shall be 15 interpreted as if it had the type unsigned char (and therefore every possible 16 object representation is valid and has a different value). 17 18 The following macros are defined in this file:<BR> 19 @verbatim 20 NULL 21 bcopy(a,b,c) ( memcpy((void *)b, (const void *)a, (size_t)c)) 22 bcmp(a,b,c) ( memcmp((void *)a, (void *)b, (size_t)c)) 23 @endverbatim 24 25 The following types are defined in this file:<BR> 26 @verbatim 27 size_t Unsigned integer type of the result of the sizeof operator. 28 @endverbatim 29 30 The following functions are declared in this file:<BR> 31 @verbatim 32 ################ Copying Functions 33 void *memcpy (void * __restrict s1, const void * __restrict s2, size_t n); 34 void *memmove (void *s1, const void *s2, size_t n); 35 char *strcpy (char * __restrict s1, const char * __restrict s2); 36 char *strncpy (char * __restrict s1, const char * __restrict s2, size_t n); 37 int strncpyX (char * __restrict s1, const char * __restrict s2, size_t n); 38 39 ################ Concatenation Functions 40 char *strcat (char * __restrict s1, const char * __restrict s2); 41 char *strncat (char * __restrict s1, const char * __restrict s2, size_t n); 42 int strncatX (char * __restrict s1, const char * __restrict s2, size_t n); 43 44 ################ Comparison Functions 45 int memcmp (const void *s1, const void *s2, size_t n); 46 int strcmp (const char *s1, const char *s2); 47 int strcoll (const char *s1, const char *s2); 48 int strncmp (const char *s1, const char *s2, size_t n); 49 size_t strxfrm (char * __restrict s1, const char * __restrict s2, size_t n); 50 51 ################ Search Functions 52 void *memchr (const void *s, int c, size_t n); 53 char *strchr (const char *s, int c); 54 size_t strcspn (const char *s1, const char *s2); 55 char *strpbrk (const char *s1, const char *s2); 56 char *strrchr (const char *s, int c); 57 size_t strspn (const char *s1 , const char *s2); 58 char *strstr (const char *s1 , const char *s2); 59 char *strtok (char * __restrict s1, const char * __restrict s2); 60 61 ################ Miscellaneous Functions 62 void *memset (void *s, int c, size_t n); 63 char *strerror (int num); 64 size_t strlen (const char *); 65 66 ################ BSD Compatibility Functions 67 char *strdup (const char *); 68 int strerror_r (int, char *, size_t); 69 int strcasecmp (const char *s1, const char *s2); 70 void *memccpy (void *, const void *, int, size_t); 71 int strncasecmp (const char *s1, const char *s2, size_t n); 72 size_t strlcpy (char *destination, const char *source, size_t size); 73 size_t strlcat (char *destination, const char *source, size_t size); 74 char *strsep (register char **stringp, register const char *delim); 75 @endverbatim 76 77 Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR> 78 This program and the accompanying materials are licensed and made available under 79 the terms and conditions of the BSD License that accompanies this distribution. 80 The full text of the license may be found at 81 http://opensource.org/licenses/bsd-license. 82 83 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 84 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 85 **/ 86 #ifndef _STRING_H 87 #define _STRING_H 88 #include <sys/EfiCdefs.h> 89 90 #ifdef _EFI_SIZE_T_ 91 typedef _EFI_SIZE_T_ size_t; 92 #undef _EFI_SIZE_T_ 93 #undef _BSD_SIZE_T_ 94 #endif 95 96 __BEGIN_DECLS 97 98 /* ################ Copying Functions ################################# */ 99 100 /** The memcpy function copies N characters from the object pointed to by Src 101 into the object pointed to by Dest. If copying takes place between objects 102 that overlap, the behavior is undefined. 103 104 @param[out] Dest Pointer to the destination of the copy operation. 105 @param[in] Src Pointer to the Source data to be copied. 106 @param[in] N Number of characters (bytes) to be copied. 107 108 @return The memcpy function returns the value of Dest. 109 **/ 110 void *memcpy(void * __restrict Dest, const void * __restrict Src, size_t N); 111 112 /** The memmove function copies N characters from the object pointed to by Src 113 into the object pointed to by Dest. Copying takes place as if the N 114 characters from the object pointed to by Src are first copied into a 115 temporary array of N characters that does not overlap the objects pointed 116 to by Dest and Src, and then the N characters from the temporary array are 117 copied into the object pointed to by Dest. 118 119 @param[out] Dest Pointer to the destination of the copy operation. 120 @param[in] Src Pointer to the Source data to be copied. 121 @param[in] N Number of characters (bytes) to be copied. 122 123 @return The memmove function returns the value of Dest. 124 **/ 125 void *memmove(void *Dest, const void *Src, size_t N); 126 127 /** The strcpy function copies the string pointed to by Src (including the 128 terminating null character) into the array pointed to by Dest. If copying 129 takes place between objects that overlap, the behavior is undefined. 130 131 @param[out] Dest Pointer to the destination of the copy operation. 132 @param[in] Src Pointer to the Source data to be copied. 133 134 @return The strcpy function returns the value of Dest. 135 **/ 136 char *strcpy(char * __restrict Dest, const char * __restrict Src); 137 138 /** The strncpy function copies not more than N characters (characters that 139 follow a null character are not copied) from the array pointed to by Src to 140 the array pointed to by Dest. If copying takes place between objects that 141 overlap, the behavior is undefined. 142 143 If the array pointed to by Src is a string that is shorter than N 144 characters, null characters are appended to the copy in the array pointed 145 to by Dest, until N characters in all have been written. 146 147 @param[out] Dest Pointer to the destination of the copy operation. 148 @param[in] Src Pointer to the Source data to be copied. 149 @param[in] N Number of characters (bytes) to be copied. 150 151 @return The strncpy function returns the value of Dest. 152 **/ 153 char *strncpy(char * __restrict Dest, const char * __restrict Src, size_t N); 154 155 /** The strncpyX function copies not more than N-1 characters (characters that 156 follow a null character are not copied) from the array pointed to by Src to 157 the array pointed to by Dest. Array Dest is guaranteed to be NULL terminated. 158 If copying takes place between objects that overlap, 159 the behavior is undefined. 160 161 strncpyX exists because normal strncpy does not indicate if the copy was 162 terminated because of exhausting the buffer or reaching the end of Src. 163 164 @param[out] Dest Pointer to the destination of the copy operation. 165 @param[in] Src Pointer to the Source data to be copied. 166 @param[in] N Number of characters (bytes) to be copied. 167 168 @return The strncpyX function returns 0 if the copy operation was 169 terminated because it reached the end of Dest. Otherwise, 170 a non-zero value is returned indicating how many characters 171 remain in Dest. 172 **/ 173 int strncpyX(char * __restrict Dest, const char * __restrict Src, size_t N); 174 175 /* ################ Concatenation Functions ########################### */ 176 177 /** The strcat function appends a copy of the string pointed to by Src 178 (including the terminating null character) to the end of the string pointed 179 to by Dest. The initial character of Src overwrites the null character at the 180 end of Dest. If copying takes place between objects that overlap, the 181 behavior is undefined. 182 183 @param[out] Dest Pointer to the destination of the concatenation operation. 184 @param[in] Src Pointer to the Source data to be concatenated. 185 186 @return The strcat function returns the value of Dest. 187 **/ 188 char *strcat(char * __restrict Dest, const char * __restrict Src); 189 190 /** The strncat function appends not more than N characters (a null character 191 and characters that follow it are not appended) from the array pointed to 192 by Src to the end of the string pointed to by Dest. The initial character of 193 Src overwrites the null character at the end of Dest. A terminating null 194 character is always appended to the result. If copying takes place 195 between objects that overlap, the behavior is undefined. 196 197 @param[out] Dest Pointer to the destination of the concatenation operation. 198 @param[in] Src Pointer to the Source data to be concatenated. 199 @param[in] N Max Number of characters (bytes) to be concatenated. 200 201 @return The strncat function returns the value of Dest. 202 **/ 203 char *strncat(char * __restrict Dest, const char * __restrict Src, size_t N); 204 205 /** The strncatX function appends not more than N characters (a null character 206 and characters that follow it are not appended) from the array pointed to 207 by Src to the end of the string pointed to by Dest. The initial character of 208 Src overwrites the null character at the end of Dest. The result is always 209 terminated with a null character. If copying takes place between objects 210 that overlap, the behavior is undefined. 211 212 strncatX exists because normal strncat does not indicate if the operation 213 was terminated because of exhausting N or reaching the end of Src. 214 215 @param[out] Dest Pointer to the destination of the concatenation operation. 216 @param[in] Src Pointer to the Source data to be concatenated. 217 @param[in] N Max Number of characters (bytes) to be concatenated. 218 219 @return The strncatX function returns 0 if the operation was terminated 220 because it reached the end of Dest. Otherwise, a non-zero value is 221 returned indicating how many characters remain in Dest. 222 **/ 223 int strncatX(char * __restrict s1, const char * __restrict s2, size_t n); 224 225 /* ################ Comparison Functions ############################## */ 226 227 /** The memcmp function compares the first N characters of the object pointed 228 to by S1 to the first N characters of the object pointed to by S2. 229 230 @param[out] S1 Pointer to the first object to be compared. 231 @param[in] S2 Pointer to the object to be compared to S1. 232 @param[in] N Max Number of characters (bytes) to be compared. 233 234 @return The memcmp function returns an integer greater than, equal to, or 235 less than zero, accordingly as the object pointed to by S1 is 236 greater than, equal to, or less than the object pointed to by S2. 237 **/ 238 int memcmp(const void *S1, const void *S2, size_t N); 239 240 /** The strcmp function compares the string pointed to by S1 to the string 241 pointed to by S2. 242 243 @param[out] S1 Pointer to the first string to be compared. 244 @param[in] S2 Pointer to the string to be compared to S1. 245 246 @return The strcmp function returns an integer greater than, equal to, or 247 less than zero, accordingly as the string pointed to by S1 is 248 greater than, equal to, or less than the string pointed to by S2. 249 **/ 250 int strcmp(const char *S1, const char *S2); 251 252 /** The strcoll function compares the string pointed to by S1 to the string 253 pointed to by S2, both interpreted as appropriate to the LC_COLLATE 254 category of the current locale. 255 256 @param[out] S1 Pointer to the first string to be compared. 257 @param[in] S2 Pointer to the string to be compared to S1. 258 259 @return The strcoll function returns an integer greater than, equal to, 260 or less than zero, accordingly as the string pointed to by S1 is 261 greater than, equal to, or less than the string pointed to by S2 262 when both are interpreted as appropriate to the current locale. 263 **/ 264 int strcoll(const char *S1, const char *S2); 265 266 /** The strncmp function compares not more than N characters (characters that 267 follow a null character are not compared) from the array pointed to by S1 268 to the array pointed to by S2. 269 270 @param[out] S1 Pointer to the first object to be compared. 271 @param[in] S2 Pointer to the object to be compared to S1. 272 @param[in] N Max Number of characters (bytes) to be compared. 273 274 @return The strncmp function returns an integer greater than, equal to, 275 or less than zero, accordingly as the possibly null-terminated 276 array pointed to by S1 is greater than, equal to, or less than 277 the possibly null-terminated array pointed to by S2. 278 **/ 279 int strncmp(const char *S1, const char *S2, size_t N); 280 281 /** The strxfrm function transforms the string pointed to by Src and places the 282 resulting string into the array pointed to by Dest. The transformation is 283 such that if the strcmp function is applied to two transformed strings, it 284 returns a value greater than, equal to, or less than zero, corresponding to 285 the result of the strcoll function applied to the same two original 286 strings. No more than N characters are placed into the resulting array 287 pointed to by Dest, including the terminating null character. If N is zero, 288 Dest is permitted to be a null pointer. If copying takes place between 289 objects that overlap, the behavior is undefined. 290 291 @param[out] Dest Pointer to the object to receive the transformed string. 292 @param[in] Src Pointer to the string to be transformed. 293 @param[in] N Max Number of characters (bytes) to be transformed. 294 295 @return The strxfrm function returns the length of the transformed string 296 (not including the terminating null character). If the value 297 returned is N or more, the contents of the array pointed to by Dest 298 are indeterminate. 299 **/ 300 size_t strxfrm(char * __restrict Dest, const char * __restrict Src, size_t N); 301 302 /* ################ Search Functions ################################## */ 303 304 /** The memchr function locates the first occurrence of C (converted to an 305 unsigned char) in the initial N characters (each interpreted as 306 unsigned char) of the object pointed to by S. 307 308 @param[in] S Pointer to the object to be searched. 309 @param[in] C The character value to search for. 310 @param[in] N Max Number of characters (bytes) to be searched. 311 312 @return The memchr function returns a pointer to the located character, 313 or a null pointer if the character does not occur in the object. 314 **/ 315 void *memchr(const void *S, int C, size_t N); 316 317 /** The strchr function locates the first occurrence of C (converted to a char) 318 in the string pointed to by S. The terminating null character is considered 319 to be part of the string. 320 321 @param[in] S Pointer to the object to be searched. 322 @param[in] C The character value to search for. 323 324 @return The strchr function returns a pointer to the located character, 325 or a null pointer if the character does not occur in the string. 326 **/ 327 char *strchr(const char *S, int C); 328 329 /** The strcspn function computes the length of the maximum initial segment of 330 the string pointed to by S1 which consists entirely of characters NOT from 331 the string pointed to by S2. 332 333 @param[in] S1 Pointer to the object to be searched. 334 @param[in] S2 Pointer to the list of characters to search for. 335 336 @return The strcspn function returns the length of the segment. 337 **/ 338 size_t strcspn(const char *S1, const char *S2); 339 340 /** The strpbrk function locates the first occurrence in the string pointed to 341 by S1 of any character from the string pointed to by S2. 342 343 @param[in] S1 Pointer to the object to be searched. 344 @param[in] S2 Pointer to the list of characters to search for. 345 346 @return The strpbrk function returns a pointer to the character, or a 347 null pointer if no character from S2 occurs in S1. 348 **/ 349 char *strpbrk(const char *S1, const char *S2); 350 351 /** The strrchr function locates the last occurrence of C (converted to a char) 352 in the string pointed to by S. The terminating null character is considered 353 to be part of the string. 354 355 @param[in] S Pointer to the object to be searched. 356 @param[in] C The character value to search for. 357 358 @return The strrchr function returns a pointer to the character, or a 359 null pointer if C does not occur in the string. 360 **/ 361 char *strrchr(const char *S, int C); 362 363 /** The strspn function computes the length of the maximum initial segment of 364 the string pointed to by S1 which consists entirely of characters from the 365 string pointed to by S2. 366 367 @param[in] S1 Pointer to the object to be searched. 368 @param[in] S2 Pointer to the list of characters to search for. 369 370 @return The strspn function returns the length of the segment. 371 **/ 372 size_t strspn(const char *S1 , const char *S2); 373 374 /** The strstr function locates the first occurrence in the string pointed to 375 by S1 of the sequence of characters (excluding the terminating null 376 character) in the string pointed to by S2. 377 378 @param[in] S1 Pointer to the object to be searched. 379 @param[in] S2 Pointer to the sequence of characters to search for. 380 381 @return The strstr function returns a pointer to the located string, or a 382 null pointer if the string is not found. If S2 points to a string 383 with zero length, the function returns S1. 384 **/ 385 char *strstr(const char *S1 , const char *S2); 386 387 /** Break a string into a sequence of tokens. 388 389 A sequence of calls to the strtok function breaks the string pointed to by 390 S1 into a sequence of tokens, each of which is delimited by a character 391 from the string pointed to by S2. The first call in the sequence has a 392 non-null first argument; subsequent calls in the sequence have a null first 393 argument. The separator string pointed to by S2 may be different from call 394 to call. 395 396 The first call in the sequence searches the string pointed to by S1 for the 397 first character that is not contained in the current separator string 398 pointed to by S2. If no such character is found, then there are no tokens 399 in the string pointed to by S1 and the strtok function returns a null 400 pointer. If such a character is found, it is the start of the first token. 401 402 The strtok function then searches from there for a character that is 403 contained in the current separator string. If no such character is found, 404 the current token extends to the end of the string pointed to by S1, and 405 subsequent searches for a token will return a null pointer. If such a 406 character is found, it is overwritten by a null character, which terminates 407 the current token. The strtok function saves a pointer to the following 408 character, from which the next search for a token will start. 409 410 Each subsequent call, with a null pointer as the value of the first 411 argument, starts searching from the saved pointer and behaves as 412 described above. 413 414 @param[in] S1 Pointer to the string to be tokenized. 415 @param[in] S2 Pointer to a list of separator characters. 416 417 @return The strtok function returns a pointer to the first character of a 418 token, or a null pointer if there is no token. 419 **/ 420 char *strtok(char * __restrict S1, const char * __restrict S2); 421 422 /* ################ Miscellaneous Functions ########################### */ 423 424 /** The memset function copies the value of C (converted to an unsigned char) 425 into each of the first N characters of the object pointed to by S. 426 427 @param[out] S Pointer to the first element of the object to be set. 428 @param[in] C Value to store in each element of S. 429 @param[in] N Number of elements in S to be set. 430 431 @return The memset function returns the value of S. 432 **/ 433 void *memset(void *S, int C, size_t N); 434 435 /** The strerror function maps the number in Num to a message string. 436 Typically, the values for Num come from errno, but strerror shall map 437 any value of type int to a message. 438 439 @param[in] Num A value to be converted to a message. 440 441 @return The strerror function returns a pointer to the string, the 442 contents of which are locale specific. The array pointed to 443 must not be modified by the program, but may be overwritten by 444 a subsequent call to the strerror function. 445 **/ 446 char *strerror(int Num); 447 448 /** The strlen function computes the length of the string pointed to by S. 449 450 @param[in] S Pointer to the string to determine the length of. 451 452 @return The strlen function returns the number of characters that 453 precede the terminating null character. 454 **/ 455 size_t strlen(const char *S); 456 457 458 /* ################ BSD Compatibility Functions ####################### */ 459 460 char *strdup (const char *); 461 int strerror_r(int, char *, size_t); 462 int strcasecmp(const char *s1, const char *s2); 463 void *memccpy (void *, const void *, int, size_t); 464 int strncasecmp(const char *s1, const char *s2, size_t n); 465 size_t strlcpy(char *destination, const char *source, size_t size); 466 size_t strlcat(char *destination, const char *source, size_t size); 467 468 // bcopy is is a void function with the src/dest arguments reversed, being used in socket lib 469 #define bcopy(a,b,c) ( memcpy((void *)b, (const void *)a, (size_t)c)) 470 471 // bcmp is same as memcmp, returns 0 for successful compare, non-zero otherwise 472 #define bcmp(a,b,c) ( memcmp((void *)a, (void *)b, (size_t)c)) 473 474 /* 475 * Get next token from string *stringp, where tokens are possibly-empty 476 * strings separated by characters from delim. 477 * 478 * Writes NULs into the string at *stringp to end tokens. 479 * delim need not remain constant from call to call. 480 * On return, *stringp points past the last NUL written (if there might 481 * be further tokens), or is NULL (if there are definitely no more tokens). 482 * 483 * If *stringp is NULL, strsep returns NULL. 484 */ 485 char * 486 strsep( 487 register char **stringp, 488 register const char *delim 489 ); 490 491 __END_DECLS 492 493 #endif /* _STRING_H */ 494