StdLib/Include/string.h

   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 */