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 shall 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 Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
  19 This program and the accompanying materials are licensed and made available under
  20 the terms and conditions of the BSD License that accompanies this distribution.
  21 The full text of the license may be found at
  22 http://opensource.org/licenses/bsd-license.php.
  23
  24 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  25 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  26
  27 **/
  28 #ifndef _STRING_H
  29 #define _STRING_H
  30 #include  <sys/EfiCdefs.h>
  31
  32 #ifdef _EFI_SIZE_T_
  33   typedef _EFI_SIZE_T_  size_t;
  34   #undef _EFI_SIZE_T_
  35   #undef _BSD_SIZE_T_
  36 #endif
  37
  38 __BEGIN_DECLS
  39
  40 /* ################   Copying Functions   ################################# */
  41
  42 /** The memcpy function copies n characters from the object pointed to by s2
  43     into the object pointed to by s1. If copying takes place between objects
  44     that overlap, the behavior is undefined.
  45
  46     @return   The memcpy function returns the value of s1.
  47 **/
  48 void     *memcpy(void * __restrict s1, const void * __restrict s2, size_t n);
  49
  50 /** The memmove function copies n characters from the object pointed to by s2
  51     into the object pointed to by s1. Copying takes place as if the n
  52     characters from the object pointed to by s2 are first copied into a
  53     temporary array of n characters that does not overlap the objects pointed
  54     to by s1 and s2, and then the n characters from the temporary array are
  55     copied into the object pointed to by s1.
  56
  57     @return   The memmove function returns the value of s1.
  58 **/
  59 void     *memmove(void *s1, const void *s2, size_t n);
  60
  61 /** The strcpy function copies the string pointed to by s2 (including the
  62     terminating null character) into the array pointed to by s1. If copying
  63     takes place between objects that overlap, the behavior is undefined.
  64
  65     @return   The strcpy function returns the value of s1.
  66 **/
  67 char     *strcpy(char * __restrict s1, const char * __restrict s2);
  68
  69 /** The strncpy function copies not more than n characters (characters that
  70     follow a null character are not copied) from the array pointed to by s2 to
  71     the array pointed to by s1. If copying takes place between objects that
  72     overlap, the behavior is undefined.
  73
  74     If the array pointed to by s2 is a string that is shorter than n
  75     characters, null characters are appended to the copy in the array pointed
  76     to by s1, until n characters in all have been written.
  77
  78     @return   The strncpy function returns the value of s1.
  79 **/
  80 char     *strncpy(char * __restrict s1, const char * __restrict s2, size_t n);
  81
  82 /** The strncpyX function copies not more than n-1 characters (characters that
  83     follow a null character are not copied) from the array pointed to by s2 to
  84     the array pointed to by s1. Array s1 is guaranteed to be NULL terminated.
  85     If copying takes place between objects that overlap,
  86     the behavior is undefined.
  87
  88     strncpyX exists because normal strncpy does not indicate if the copy was
  89     terminated because of exhausting the buffer or reaching the end of s2.
  90
  91     @return   The strncpyX function returns 0 if the copy operation was
  92               terminated because it reached the end of s1.  Otherwise,
  93               a non-zero value is returned indicating how many characters
  94               remain in s1.
  95 **/
  96 int       strncpyX(char * __restrict s1, const char * __restrict s2, size_t n);
  97
  98 /* ################   Concatenation Functions   ########################### */
  99
 100 /** The strcat function appends a copy of the string pointed to by s2
 101     (including the terminating null character) to the end of the string pointed
 102     to by s1. The initial character of s2 overwrites the null character at the
 103     end of s1. If copying takes place between objects that overlap, the
 104     behavior is undefined.
 105
 106     @return   The strcat function returns the value of s1.
 107 **/
 108 char     *strcat(char * __restrict s1, const char * __restrict s2);
 109
 110 /** The strncat function appends not more than n characters (a null character
 111     and characters that follow it are not appended) from the array pointed to
 112     by s2 to the end of the string pointed to by s1. The initial character of
 113     s2 overwrites the null character at the end of s1. A terminating null
 114     character is always appended to the result. If copying takes place
 115     between objects that overlap, the behavior is undefined.
 116
 117     @return   The strncat function returns the value of s1.
 118 **/
 119 char     *strncat(char * __restrict s1, const char * __restrict s2, size_t n);
 120
 121 /** The strncatX function appends not more than n characters (a null character
 122     and characters that follow it are not appended) from the array pointed to
 123     by s2 to the end of the string pointed to by s1. The initial character of
 124     s2 overwrites the null character at the end of s1. The result is always
 125     terminated with a null character. If copying takes place between objects
 126     that overlap, the behavior is undefined.
 127
 128     strncatX exists because normal strncat does not indicate if the operation
 129     was terminated because of exhausting n or reaching the end of s2.
 130
 131     @return   The strncatX function returns 0 if the operation was terminated
 132               because it reached the end of s1.  Otherwise, a non-zero value is
 133               returned indicating how many characters remain in s1.
 134 **/
 135 int       strncatX(char * __restrict s1, const char * __restrict s2, size_t n);
 136
 137 /* ################   Comparison Functions   ############################## */
 138
 139 /** The memcmp function compares the first n characters of the object pointed
 140     to by s1 to the first n characters of the object pointed to by s2.
 141
 142     @return   The memcmp function returns an integer greater than, equal to, or
 143               less than zero, accordingly as the object pointed to by s1 is
 144               greater than, equal to, or less than the object pointed to by s2.
 145 **/
 146 int       memcmp(const void *s1, const void *s2, size_t n);
 147
 148 /** The strcmp function compares the string pointed to by s1 to the string
 149     pointed to by s2.
 150
 151     @return   The strcmp function returns an integer greater than, equal to, or
 152               less than zero, accordingly as the string pointed to by s1 is
 153               greater than, equal to, or less than the string pointed to by s2.
 154 **/
 155 int       strcmp(const char *s1, const char *s2);
 156
 157 /** The strcoll function compares the string pointed to by s1 to the string
 158     pointed to by s2, both interpreted as appropriate to the LC_COLLATE
 159     category of the current locale.
 160
 161     @return   The strcoll function returns an integer greater than, equal to,
 162               or less than zero, accordingly as the string pointed to by s1 is
 163               greater than, equal to, or less than the string pointed to by s2
 164               when both are interpreted as appropriate to the current locale.
 165 **/
 166 int       strcoll(const char *s1, const char *s2);
 167
 168 /** The strncmp function compares not more than n characters (characters that
 169     follow a null character are not compared) from the array pointed to by s1
 170     to the array pointed to by s2.
 171
 172     @return   The strncmp function returns an integer greater than, equal to,
 173               or less than zero, accordingly as the possibly null-terminated
 174               array pointed to by s1 is greater than, equal to, or less than
 175               the possibly null-terminated array pointed to by s2.
 176 **/
 177 int       strncmp(const char *s1, const char *s2, size_t n);
 178
 179 /** The strxfrm function transforms the string pointed to by s2 and places the
 180     resulting string into the array pointed to by s1. The transformation is
 181     such that if the strcmp function is applied to two transformed strings, it
 182     returns a value greater than, equal to, or less than zero, corresponding to
 183     the result of the strcoll function applied to the same two original
 184     strings. No more than n characters are placed into the resulting array
 185     pointed to by s1, including the terminating null character. If n is zero,
 186     s1 is permitted to be a null pointer. If copying takes place between
 187     objects that overlap, the behavior is undefined.
 188
 189     @return   The strxfrm function returns the length of the transformed string
 190               (not including the terminating null character). If the value
 191               returned is n or more, the contents of the array pointed to by s1
 192               are indeterminate.
 193 **/
 194 size_t    strxfrm(char * __restrict s1, const char * __restrict s2, size_t n);
 195
 196 /* ################   Search Functions   ################################## */
 197
 198 /** The memchr function locates the first occurrence of c (converted to an
 199     unsigned char) in the initial n characters (each interpreted as
 200     unsigned char) of the object pointed to by s.
 201
 202     @return   The memchr function returns a pointer to the located character,
 203               or a null pointer if the character does not occur in the object.
 204 **/
 205 void     *memchr(const void *s, int c, size_t n);
 206
 207 /** The strchr function locates the first occurrence of c (converted to a char)
 208     in the string pointed to by s. The terminating null character is considered
 209     to be part of the string.
 210
 211     @return   The strchr function returns a pointer to the located character,
 212               or a null pointer if the character does not occur in the string.
 213 **/
 214 char     *strchr(const char *s, int c);
 215
 216 /** The strcspn function computes the length of the maximum initial segment of
 217     the string pointed to by s1 which consists entirely of characters NOT from
 218     the string pointed to by s2.
 219
 220     @return   The strcspn function returns the length of the segment.
 221 **/
 222 size_t    strcspn(const char *s1, const char *s2);
 223
 224 /** The strpbrk function locates the first occurrence in the string pointed to
 225     by s1 of any character from the string pointed to by s2.
 226
 227     @return   The strpbrk function returns a pointer to the character, or a
 228               null pointer if no character from s2 occurs in s1.
 229 **/
 230 char     *strpbrk(const char *s1, const char *s2);
 231
 232 /** The strrchr function locates the last occurrence of c (converted to a char)
 233     in the string pointed to by s. The terminating null character is considered
 234     to be part of the string.
 235
 236     @return   The strrchr function returns a pointer to the character, or a
 237               null pointer if c does not occur in the string.
 238 **/
 239 char     *strrchr(const char *s, int c);
 240
 241 /** The strspn function computes the length of the maximum initial segment of
 242     the string pointed to by s1 which consists entirely of characters from the
 243     string pointed to by s2.
 244
 245     @return   The strspn function returns the length of the segment.
 246 **/
 247 size_t    strspn(const char *s1 , const char *s2);
 248
 249 /** The strstr function locates the first occurrence in the string pointed to
 250     by s1 of the sequence of characters (excluding the terminating null
 251     character) in the string pointed to by s2.
 252
 253     @return   The strstr function returns a pointer to the located string, or a
 254               null pointer if the string is not found. If s2 points to a string
 255               with zero length, the function returns s1.
 256 **/
 257 char     *strstr(const char *s1 , const char *s2);
 258
 259 /** A sequence of calls to the strtok function breaks the string pointed to by
 260     s1 into a sequence of tokens, each of which is delimited by a character
 261     from the string pointed to by s2. The first call in the sequence has a
 262     non-null first argument; subsequent calls in the sequence have a null first
 263     argument. The separator string pointed to by s2 may be different from call
 264     to call.
 265
 266     The first call in the sequence searches the string pointed to by s1 for the
 267     first character that is not contained in the current separator string
 268     pointed to by s2. If no such character is found, then there are no tokens
 269     in the string pointed to by s1 and the strtok function returns a null
 270     pointer. If such a character is found, it is the start of the first token.
 271
 272     The strtok function then searches from there for a character that is
 273     contained in the current separator string. If no such character is found,
 274     the current token extends to the end of the string pointed to by s1, and
 275     subsequent searches for a token will return a null pointer. If such a
 276     character is found, it is overwritten by a null character, which terminates
 277     the current token. The strtok function saves a pointer to the following
 278     character, from which the next search for a token will start.
 279
 280     Each subsequent call, with a null pointer as the value of the first
 281     argument, starts searching from the saved pointer and behaves as
 282     described above.
 283
 284     @return   The strtok function returns a pointer to the first character of a
 285               token, or a null pointer if there is no token.
 286 **/
 287 char     *strtok(char * __restrict s1, const char * __restrict s2);
 288
 289 /* ################   Miscellaneous Functions   ########################### */
 290
 291 /** The memset function copies the value of c (converted to an unsigned char)
 292     into each of the first n characters of the object pointed to by s.
 293
 294     @return   The memset function returns the value of s.
 295 **/
 296 void     *memset(void *s, int c, size_t n);
 297
 298 /** The strerror function maps the number in errnum to a message string.
 299     Typically, the values for errnum come from errno, but strerror shall map
 300     any value of type int to a message.
 301
 302     The implementation shall behave as if no library function calls the
 303     strerror function.
 304
 305     @return   The strerror function returns a pointer to the string, the
 306               contents of which are locale specific.  The array pointed to
 307               shall not be modified by the program, but may be overwritten by
 308               a subsequent call to the strerror function.
 309 **/
 310 char     *strerror(int num);
 311
 312 /** The strlen function computes the length of the string pointed to by s.
 313
 314     @return   The strlen function returns the number of characters that
 315               precede the terminating null character.
 316 **/
 317 size_t    strlen(const char *);
 318
 319
 320 /* ################   BSD Compatibility Functions   ####################### */
 321
 322 char   *strdup    (const char *);
 323 int     strerror_r(int, char *, size_t);
 324 int     strcasecmp(const char *s1, const char *s2);
 325 void   *memccpy   (void *, const void *, int, size_t);
 326 int     strncasecmp(const char *s1, const char *s2, size_t n);
 327 size_t  strlcpy(char *destination, const char *source, size_t size);
 328 size_t  strlcat(char *destination, const char *source, size_t size);
 329
 330 // bcopy is is a void function with the src/dest arguments reversed, being used in socket lib
 331 #define bcopy(a,b,c) ( memcpy((void *)b, (const void *)a, (size_t)c))
 332
 333 // bcmp is same as memcmp, returns 0 for successful compare, non-zero otherwise
 334 #define bcmp(a,b,c) ( memcmp((void *)a, (void *)b, (size_t)c))
 335
 336 /*
 337  * Get next token from string *stringp, where tokens are possibly-empty
 338  * strings separated by characters from delim.
 339  *
 340  * Writes NULs into the string at *stringp to end tokens.
 341  * delim need not remain constant from call to call.
 342  * On return, *stringp points past the last NUL written (if there might
 343  * be further tokens), or is NULL (if there are definitely no more tokens).
 344  *
 345  * If *stringp is NULL, strsep returns NULL.
 346  */
 347 char *
 348 strsep(
 349   register char **stringp,
 350   register const char *delim
 351   );
 352
 353 __END_DECLS
 354
 355 #endif  /* _STRING_H */