StdLib/Include/stdlib.h

   1 /** @file
   2   The header <stdlib.h> declares five types and several functions of general
   3   utility, and defines several macros.
   4
   5   Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
   6   This program and the accompanying materials are licensed and made available under
   7   the terms and conditions of the BSD License that accompanies this distribution.
   8   The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php.
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15 #ifndef _STDLIB_H
  16 #define _STDLIB_H
  17 #include  <sys/EfiCdefs.h>
  18
  19 #ifdef _EFI_SIZE_T_
  20   typedef _EFI_SIZE_T_  size_t;
  21   #undef _EFI_SIZE_T_
  22   #undef _BSD_SIZE_T_
  23 #endif
  24
  25 #ifndef __cplusplus
  26   #ifdef _EFI_WCHAR_T
  27     typedef _EFI_WCHAR_T wchar_t;
  28     #undef  _EFI_WCHAR_T
  29     #undef _BSD_WCHAR_T_
  30   #endif
  31 #endif
  32
  33 /// A structure type that is the type of the value returned by the div function.
  34 typedef struct {
  35   int quot;   /* quotient */
  36   int rem;    /* remainder */
  37 } div_t;
  38
  39 /// A structure type that is the type of the value returned by the ldiv function.
  40 typedef struct {
  41   long  quot;
  42   long  rem;
  43 } ldiv_t;
  44
  45 /// A structure type that is the type of the value returned by the lldiv function.
  46 typedef struct {
  47   long long quot;
  48   long long rem;
  49 } lldiv_t;
  50
  51 /** Expand to integer constant expressions that can be used as the argument to
  52     the exit function to return unsuccessful or successful termination status,
  53     respectively, to the host environment.
  54 **/
  55 #define EXIT_FAILURE  1
  56 #define EXIT_SUCCESS  0
  57
  58 /** Expands to an integer constant expression that is the maximum value
  59     returned by the rand function.
  60
  61     The value of the RAND_MAX macro shall be at least 32767.
  62 **/
  63 #define RAND_MAX  0x7fffffff
  64
  65 /** Expands to a positive integer expression with type size_t that is the
  66     maximum number of bytes in a multibyte character for the extended character
  67     set specified by the current locale (category LC_CTYPE), which is never
  68     greater than MB_LEN_MAX.
  69 **/
  70 #define MB_CUR_MAX  2
  71
  72 /** Maximum number of functions that can be registered by atexit.
  73
  74     The C standard states that the implementation shall support the
  75     registration of at least 32 functions.
  76 **/
  77 #define ATEXIT_MAX  32
  78
  79 __BEGIN_DECLS
  80
  81 /* ################  Communication with the environment  ################## */
  82
  83 /** The abort function causes abnormal program termination to occur, unless
  84     the signal SIGABRT is being caught and the signal handler does not return.
  85
  86     Open streams with unwritten buffered data are not flushed, open
  87     streams are not closed, and temporary files are not removed by abort.
  88
  89     Unsuccessful termination is returned to the host environment by means of
  90     the function call, raise(SIGABRT).
  91
  92     @sa signal.h
  93 **/
  94 void    abort(void);
  95
  96 /** The atexit function registers the function pointed to by func, to be
  97     called without arguments at normal program termination.
  98
  99     The implementation supports the registration of up to 32 functions.
 100
 101     @return   The atexit function returns zero if the registration succeeds,
 102               nonzero if it fails.
 103 **/
 104 int     atexit(void (*)(void));
 105
 106 /** The exit function causes normal program termination to occur. If more than
 107     one call to the exit function is executed by a program,
 108     the behavior is undefined.
 109
 110     First, all functions registered by the atexit function are called, in the
 111     reverse order of their registration, except that a function is called
 112     after any previously registered functions that had already been called at
 113     the time it was registered. If, during the call to any such function, a
 114     call to the longjmp function is made that would terminate the call to the
 115     registered function, the behavior is undefined.
 116
 117     Next, all open streams with unwritten buffered data are flushed, all open
 118     streams are closed, and all files created by the tmpfile function
 119     are removed.
 120
 121     Finally, control is returned to the host environment. If the value of
 122     status is zero, or EXIT_SUCCESS, status is returned unchanged. If the value
 123     of status is EXIT_FAILURE, EAPPLICATION is returned.
 124     Otherwise, status is returned unchanged.
 125 **/
 126 void    exit(int status) __noreturn;
 127
 128 /** The _Exit function causes normal program termination to occur and control
 129     to be returned to the host environment.
 130
 131     No functions registered by the atexit function or signal handlers
 132     registered by the signal function are called.  Open streams with unwritten
 133     buffered data are not flushed, open streams are not closed, and temporary
 134     files are not removed by abort.
 135
 136     While this function does not return, it can NOT be marked as "__noreturn"
 137     without causing a warning to be emitted because the compilers can not
 138     determine that the function truly does not return.
 139
 140     The status returned to the host environment is determined in the same way
 141     as for the exit function.
 142 **/
 143 void    _Exit(int status);
 144
 145 /** The getenv function searches an environment list, provided by the host
 146     environment, for a string that matches the string pointed to by name.  The
 147     set of environment names and the method for altering the environment list
 148     are determined by the underlying UEFI Shell implementation.
 149
 150     @return   The getenv function returns a pointer to a string associated with
 151               the matched list member.  The string pointed to shall not be
 152               modified by the program, but may be overwritten by a subsequent
 153               call to the getenv function.  If the specified name cannot be
 154               found, a null pointer is returned.
 155 **/
 156 char   *getenv(const char *name);
 157
 158 /**
 159   Add or update a variable in the environment list
 160
 161   @param name     Address of a zero terminated name string
 162   @param value    Address of a zero terminated value string
 163   @param rewrite  TRUE allows overwriting existing values
 164
 165   @retval Returns 0 upon success
 166   @retval Returns -1 upon failure, sets errno with more information
 167
 168 **/
 169 int
 170 setenv (
 171   register const char * name,
 172   register const char * value,
 173   int rewrite
 174   );
 175
 176 /** If string is a null pointer, the system function determines whether the
 177     host environment has a command processor. If string is not a null pointer,
 178     the system function passes the string pointed to by string to that command
 179     processor to be executed in a manner which the implementation shall
 180     document; this might then cause the program calling system to behave in a
 181     non-conforming manner or to terminate.
 182
 183     @return   If the argument is a null pointer, the system function returns
 184               nonzero only if a command processor is available. If the argument
 185               is not a null pointer, and the system function does return, it
 186               returns an implementation-defined value.
 187 **/
 188 int     system(const char *string);
 189
 190
 191 /* ################  Integer arithmetic functions  ######################## */
 192
 193 /** Computes the absolute value of an integer j.
 194
 195     @return   The absolute value of j.
 196 **/
 197 int     abs(int j);
 198
 199 /** Computes the absolute value of an integer j.
 200
 201     @return   The absolute value of j.
 202 **/
 203 long    labs(long j);
 204
 205 /** Computes the absolute value of an integer j.
 206
 207     @return   The absolute value of j.
 208 **/
 209 long long
 210         llabs(long long j);
 211
 212 /** Computes numer / denom and numer % denom in a single operation.
 213
 214     @return   Returns a structure of type div_t, comprising both the
 215               quotient and the remainder.
 216 **/
 217 div_t   div(int numer, int denom);
 218
 219 /** Computes numer / denom and numer % denom in a single operation.
 220
 221     @return   Returns a structure of type ldiv_t, comprising both the
 222               quotient and the remainder.
 223 **/
 224 ldiv_t  ldiv(long numer, long denom);
 225
 226 /** Computes numer / denom and numer % denom in a single operation.
 227
 228     @return   Returns a structure of type lldiv_t, comprising both the
 229               quotient and the remainder.
 230 **/
 231 lldiv_t lldiv(long long numer, long long denom);
 232
 233 /* ############  Integer Numeric conversion functions  #################### */
 234
 235 /** The atoi function converts the initial portion of the string pointed to by
 236     nptr to int representation.  Except for the behavior on error, it is
 237     equivalent to:
 238       - atoi: (int)strtol(nptr, (char **)NULL, 10)
 239
 240   @return   The atoi function returns the converted value.
 241 **/
 242 int     atoi(const char *nptr);
 243
 244 /** The atol function converts the initial portion of the string pointed to by
 245     nptr to long int representation.  Except for the behavior on error, it is
 246     equivalent to:
 247       - atol: strtol(nptr, (char **)NULL, 10)
 248
 249   @return   The atol function returns the converted value.
 250 **/
 251 long    atol(const char *nptr);
 252
 253 /** The atoll function converts the initial portion of the string pointed to by
 254     nptr to long long int representation.  Except for the behavior on error, it
 255     is equivalent to:
 256       - atoll: strtoll(nptr, (char **)NULL, 10)
 257
 258   @return   The atoll function returns the converted value.
 259 **/
 260 long long
 261         atoll(const char *nptr);
 262
 263 /** The strtol, strtoll, strtoul, and strtoull functions convert the initial
 264     portion of the string pointed to by nptr to long int, long long int,
 265     unsigned long int, and unsigned long long int representation, respectively.
 266     First, they decompose the input string into three parts: an initial,
 267     possibly empty, sequence of white-space characters (as specified by the
 268     isspace function), a subject sequence resembling an integer represented in
 269     some radix determined by the value of base, and a final string of one or
 270     more unrecognized characters, including the terminating null character of
 271     the input string. Then, they attempt to convert the subject sequence to an
 272     integer, and return the result.
 273
 274     If the value of base is zero, the expected form of the subject sequence is
 275     that of an integer constant as described in 6.4.4.1, optionally preceded
 276     by a plus or minus sign, but not including an integer suffix. If the value
 277     of base is between 2 and 36 (inclusive), the expected form of the subject
 278     sequence is a sequence of letters and digits representing an integer with
 279     the radix specified by base, optionally preceded by a plus or minus sign,
 280     but not including an integer suffix. The letters from a (or A) through z
 281     (or Z) are ascribed the values 10 through 35; only letters and digits whose
 282     ascribed values are less than that of base are permitted. If the value of
 283     base is 16, the characters 0x or 0X may optionally precede the sequence of
 284     letters and digits, following the sign if present.
 285
 286     The subject sequence is defined as the longest initial subsequence of the
 287     input string, starting with the first non-white-space character, that is of
 288     the expected form. The subject sequence contains no characters if the input
 289     string is empty or consists entirely of white space, or if the first
 290     non-white-space character is other than a sign or a permissible letter or digit.
 291
 292     If the subject sequence has the expected form and the value of base is
 293     zero, the sequence of characters starting with the first digit is
 294     interpreted as an integer constant. If the subject sequence has the
 295     expected form and the value of base is between 2 and 36, it is used as the
 296     base for conversion, ascribing to each letter its value as given above. If
 297     the subject sequence begins with a minus sign, the value resulting from the
 298     conversion is negated (in the return type). A pointer to the final string
 299     is stored in the object pointed to by endptr, provided that endptr is
 300     not a null pointer.
 301
 302     In other than the "C" locale, additional locale-specific subject sequence
 303     forms may be accepted.
 304
 305     If the subject sequence is empty or does not have the expected form, no
 306     conversion is performed; the value of nptr is stored in the object pointed
 307     to by endptr, provided that endptr is not a null pointer.
 308
 309   @return   The strtol, strtoll, strtoul, and strtoull functions return the
 310             converted value, if any. If no conversion could be performed, zero
 311             is returned. If the correct value is outside the range of
 312             representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,
 313             ULONG_MAX, or ULLONG_MAX is returned (according to the return type
 314             and sign of the value, if any), and the value of the macro ERANGE
 315             is stored in errno.
 316 **/
 317 long    strtol(const char * __restrict nptr, char ** __restrict endptr, int base);
 318
 319 /** The strtoul function converts the initial portion of the string pointed to
 320     by nptr to unsigned long int representation.
 321
 322     See the description for strtol for more information.
 323
 324   @return   The strtoul function returns the converted value, if any. If no
 325             conversion could be performed, zero is returned. If the correct
 326             value is outside the range of representable values, ULONG_MAX is
 327             returned and the value of the macro ERANGE is stored in errno.
 328 **/
 329 unsigned long
 330         strtoul(const char * __restrict nptr, char ** __restrict endptr, int base);
 331
 332 /** The strtoll function converts the initial portion of the string pointed to
 333     by nptr to long long int representation.
 334
 335     See the description for strtol for more information.
 336
 337   @return   The strtoll function returns the converted value, if any. If no
 338             conversion could be performed, zero is returned. If the correct
 339             value is outside the range of representable values, LLONG_MIN or
 340             LLONG_MAX is returned (according to the sign of the value, if any),
 341             and the value of the macro ERANGE is stored in errno.
 342 **/
 343 long long
 344         strtoll(const char * __restrict nptr, char ** __restrict endptr, int base);
 345
 346 /** The strtoull function converts the initial portion of the string pointed to
 347     by nptr to unsigned long long int representation.
 348
 349     See the description for strtol for more information.
 350
 351   @return   The strtoull function returns the converted value, if any. If no
 352             conversion could be performed, zero is returned. If the correct
 353             value is outside the range of representable values, ULLONG_MAX is
 354             returned and the value of the macro ERANGE is stored in errno.
 355 **/
 356 unsigned long long
 357         strtoull(const char * __restrict nptr, char ** __restrict endptr, int base);
 358
 359 /* #########  Floating-point Numeric conversion functions  ################ */
 360
 361 /**
 362
 363   @return
 364 **/
 365 double  atof(const char *);
 366
 367 /**
 368
 369   @return
 370 **/
 371 double  strtod(const char * __restrict nptr, char ** __restrict endptr);
 372
 373 /**
 374
 375   @return
 376 **/
 377 float   strtof(const char * __restrict nptr, char ** __restrict endptr);
 378
 379 /**
 380
 381   @return
 382 **/
 383 long double
 384         strtold(const char * __restrict nptr, char ** __restrict endptr);
 385
 386 /* ################  Pseudo-random sequence generation functions  ######### */
 387
 388 /** The rand function computes a sequence of pseudo-random integers in the
 389     range 0 to RAND_MAX.
 390
 391     @return   The rand function returns a pseudo-random integer.
 392 **/
 393 int     rand(void);
 394
 395 /** The srand function uses the argument as a seed for a new sequence of
 396     pseudo-random numbers to be returned by subsequent calls to rand.
 397
 398     If srand is then called with the same seed value, the sequence of
 399     pseudo-random numbers shall be repeated. If rand is called before any calls
 400     to srand have been made, the same sequence shall be generated as when srand
 401     is first called with a seed value of 1.
 402 **/
 403 void    srand(unsigned seed);
 404
 405 /* ################  Memory management functions  ######################### */
 406
 407 /** The calloc function allocates space for an array of Num objects, each of
 408     whose size is Size.  The space is initialized to all bits zero.
 409
 410     @return   NULL is returned if the space could not be allocated and errno
 411               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 412               region of the requested size is returned.
 413 **/
 414 void   *calloc(size_t Num, size_t Size);
 415
 416 /** The free function causes the space pointed to by Ptr to be deallocated,
 417     that is, made available for further allocation.
 418
 419     If Ptr is a null pointer, no action occurs.  Otherwise, if the argument
 420     does not match a pointer earlier returned by the calloc, malloc, or realloc
 421     function, or if the space has been deallocated by a call to free or
 422     realloc, the behavior is undefined.
 423
 424     @param  Ptr     Pointer to a previously allocated region of memory to be freed.
 425
 426 **/
 427 void    free(void *);
 428
 429 /** The malloc function allocates space for an object whose size is specified
 430     by size and whose value is indeterminate.
 431
 432     This implementation uses the UEFI memory allocation boot services to get a
 433     region of memory that is 8-byte aligned and of the specified size.  The
 434     region is allocated with type EfiLoaderData.
 435
 436     @param  size    Size, in bytes, of the region to allocate.
 437
 438     @return   NULL is returned if the space could not be allocated and errno
 439               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 440               region of the requested size is returned.<BR>
 441               If NULL is returned, errno may contain:
 442               - EINVAL: Requested Size is zero.
 443               - ENOMEM: Memory could not be allocated.
 444 **/
 445 void   *malloc(size_t);
 446
 447 /** The realloc function changes the size of the object pointed to by Ptr to
 448     the size specified by NewSize.
 449
 450     The contents of the object are unchanged up to the lesser of the new and
 451     old sizes.  If the new size is larger, the value of the newly allocated
 452     portion of the object is indeterminate.
 453
 454     If Ptr is a null pointer, the realloc function behaves like the malloc
 455     function for the specified size.
 456
 457     If Ptr does not match a pointer earlier returned by the calloc, malloc, or
 458     realloc function, or if the space has been deallocated by a call to the free
 459     or realloc function, the behavior is undefined.
 460
 461     If the space cannot be allocated, the object pointed to by Ptr is unchanged.
 462
 463     If NewSize is zero and Ptr is not a null pointer, the object it points to
 464     is freed.
 465
 466     This implementation uses the UEFI memory allocation boot services to get a
 467     region of memory that is 8-byte aligned and of the specified size.  The
 468     region is allocated with type EfiLoaderData.
 469
 470     @param  Ptr     Pointer to a previously allocated region of memory to be resized.
 471     @param  NewSize Size, in bytes, of the new object to allocate space for.
 472
 473     @return   NULL is returned if the space could not be allocated and errno
 474               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 475               region of the requested size is returned.  If NewSize is zero,
 476               NULL is returned and errno will be unchanged.
 477 **/
 478 void   *realloc(void *Ptr, size_t NewSize);
 479
 480 /* ################  Searching and Sorting utilities  ##################### */
 481
 482 /** The bsearch function searches an array of nmemb objects, the initial
 483     element of which is pointed to by base, for an element that matches the
 484     object pointed to by key. The size of each element of the array is
 485     specified by size.
 486
 487     The comparison function pointed to by compar is called with two arguments
 488     that point to the key object and to an array element, in that order. The
 489     function returns an integer less than, equal to, or greater than zero if
 490     the key object is considered, respectively, to be less than, to match, or
 491     to be greater than the array element. The array consists of: all the
 492     elements that compare less than, all the elements that compare equal to,
 493     and all the elements that compare greater than the key object,
 494     in that order.
 495
 496   @return   The bsearch function returns a pointer to a matching element of the
 497             array, or a null pointer if no match is found. If two elements
 498             compare as equal, which element is matched is unspecified.
 499 **/
 500 void *
 501 bsearch(  const void *key,  const void *base0,
 502           size_t nmemb,     size_t size,
 503           int (*compar)(const void *, const void *)
 504 );
 505
 506 /** The qsort function sorts an array of nmemb objects, the initial element of
 507     which is pointed to by base.  The size of each object is specified by size.
 508
 509     The contents of the array are sorted into ascending order according to a
 510     comparison function pointed to by compar, which is called with two
 511     arguments that point to the objects being compared. The function shall
 512     return an integer less than, equal to, or greater than zero if the first
 513     argument is considered to be respectively less than, equal to, or greater
 514     than the second.
 515
 516     If two elements compare as equal, their order in the resulting sorted array
 517     is unspecified.
 518 **/
 519 void qsort( void *base, size_t nmemb, size_t size,
 520             int (*compar)(const void *, const void *));
 521
 522 /* ################  Multibyte/wide character conversion functions  ####### */
 523
 524 /** Determine the number of bytes comprising a multibyte character.
 525
 526   If s is not a null pointer, the mblen function determines the number of bytes
 527   contained in the multibyte character pointed to by s. Except that the
 528   conversion state of the mbtowc function is not affected, it is equivalent to
 529     mbtowc((wchar_t *)0, s, n);
 530
 531   The implementation shall behave as if no library function calls the mblen
 532   function.
 533
 534   @return   If s is a null pointer, the mblen function returns a nonzero or
 535             zero value, if multibyte character encodings, respectively, do
 536             or do not have state-dependent encodings. If s is not a null
 537             pointer, the mblen function either returns 0 (if s points to the
 538             null character), or returns the number of bytes that are contained
 539             in the multibyte character (if the next n or fewer bytes form a
 540             valid multibyte character), or returns -1 (if they do not form a
 541             valid multibyte character).
 542 **/
 543 int     mblen(const char *, size_t);
 544
 545 /** Convert a multibyte character into a wide character.
 546
 547     If s is not a null pointer, the mbtowc function inspects at most n bytes
 548     beginning with the byte pointed to by s to determine the number of bytes
 549     needed to complete the next multibyte character (including any shift
 550     sequences). If the function determines that the next multibyte character
 551     is complete and valid, it determines the value of the corresponding wide
 552     character and then, if pwc is not a null pointer, stores that value in
 553     the object pointed to by pwc. If the corresponding wide character is the
 554     null wide character, the function is left in the initial conversion state.
 555
 556     The implementation shall behave as if no library function calls the
 557     mbtowc function.
 558
 559     @return   If s is a null pointer, the mbtowc function returns a nonzero or
 560               zero value, if multibyte character encodings, respectively, do
 561               or do not have state-dependent encodings. If s is not a null
 562               pointer, the mbtowc function either returns 0 (if s points to
 563               the null character), or returns the number of bytes that are
 564               contained in the converted multibyte character (if the next n or
 565               fewer bytes form a valid multibyte character), or returns -1
 566               (if they do not form a valid multibyte character).
 567
 568               In no case will the value returned be greater than n or the value
 569               of the MB_CUR_MAX macro.
 570 **/
 571 int     mbtowc(wchar_t * __restrict, const char * __restrict, size_t);
 572
 573 /**
 574 The wctomb function determines the number of bytes needed to represent the multibyte
 575 character corresponding to the wide character given by wc (including any shift
 576 sequences), and stores the multibyte character representation in the array whose first
 577 element is pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters
 578 are stored. If wc is a null wide character, a null byte is stored, preceded by any shift
 579 sequence needed to restore the initial shift state, and the function is left in the initial
 580 conversion state.
 581
 582 The implementation shall behave as if no library function calls the wctomb function.
 583
 584   @return
 585 If s is a null pointer, the wctomb function returns a nonzero or zero value, if multibyte
 586 character encodings, respectively, do or do not have state-dependent encodings. If s is
 587 not a null pointer, the wctomb function returns -1 if the value of wc does not correspond
 588 to a valid multibyte character, or returns the number of bytes that are contained in the
 589 multibyte character corresponding to the value of wc.
 590
 591 In no case will the value returned be greater than the value of the MB_CUR_MAX macro.
 592
 593 **/
 594 int     wctomb(char *, wchar_t);
 595
 596 /* ################  Multibyte/wide string conversion functions  ########## */
 597
 598 /** Convert a multibyte character string into a wide-character string.
 599
 600     The mbstowcs function converts a sequence of multibyte characters that
 601     begins in the initial shift state from the array pointed to by src into
 602     a sequence of corresponding wide characters and stores not more than limit
 603     wide characters into the array pointed to by dest.  No multibyte
 604     characters that follow a null character (which is converted into a null
 605     wide character) will be examined or converted. Each multibyte character
 606     is converted as if by a call to the mbtowc function, except that the
 607     conversion state of the mbtowc function is not affected.
 608
 609     No more than limit elements will be modified in the array pointed to by dest.
 610     If copying takes place between objects that overlap,
 611     the behavior is undefined.
 612
 613   @return   If an invalid multibyte character is encountered, the mbstowcs
 614             function returns (size_t)(-1). Otherwise, the mbstowcs function
 615             returns the number of array elements modified, not including a
 616             terminating null wide character, if any.
 617
 618 **/
 619 size_t  mbstowcs(wchar_t * __restrict dest, const char * __restrict src, size_t limit);
 620
 621 /** Convert a wide-character string into a multibyte character string.
 622
 623     The wcstombs function converts a sequence of wide characters from the
 624     array pointed to by src into a sequence of corresponding multibyte
 625     characters that begins in the initial shift state, and stores these
 626     multibyte characters into the array pointed to by dest, stopping if a
 627     multibyte character would exceed the limit of limit total bytes or if a
 628     null character is stored. Each wide character is converted as if by
 629     a call to the wctomb function, except that the conversion state of
 630     the wctomb function is not affected.
 631
 632     No more than limit bytes will be modified in the array pointed to by dest.
 633     If copying takes place between objects that overlap,
 634     the behavior is undefined.
 635
 636   @return   If a wide character is encountered that does not correspond to a
 637             valid multibyte character, the wcstombs function returns
 638             (size_t)(-1). Otherwise, the wcstombs function returns the number
 639             of bytes modified, not including a terminating null character,
 640             if any.
 641 **/
 642 size_t  wcstombs(char * __restrict dest, const wchar_t * __restrict src, size_t limit);
 643
 644 __END_DECLS
 645
 646 #endif  /* _STDLIB_H */