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   The files stddef.h and stdlib.h are "catch all" headers for definitions and declarations
   6   that don't fit well in the other headers.  There are two separate header files because
   7   the contents of <stddef.h> are valid in both freestanding and hosted environment, while the
   8   header <stdlib.h> contains elements that are only valid in a hosted environment.
   9
  10   The following macros are defined in this file:<BR>
  11   @verbatim
  12     EXIT_FAILURE    An expression indicating application failure, used as an argument to exit().
  13     EXIT_SUCCESS    An expression indicating application success, used as an argument to exit().
  14     RAND_MAX        The maximum value returned by the rand function.
  15     MB_CUR_MAX      Maximum number of bytes in a multibyte character for the current locale.
  16     ATEXIT_MAX      Maximum number of routines that may be registered by the atexit function.
  17   @endverbatim
  18
  19   The following types are defined in this file:<BR>
  20   @verbatim
  21     size_t      Unsigned integer type of the result of the sizeof operator.
  22     wchar_t     The type of a wide character.
  23     div_t       Type of the value returned by the div function.
  24     ldiv_t      Type of the value returned by the ldiv function.
  25     lldiv_t     Type of the value returned by the lldiv function.
  26   @endverbatim
  27
  28   The following functions are declared in this file:<BR>
  29   @verbatim
  30     ################  Communication with the environment
  31     void        abort   (void) __noreturn;
  32     int         atexit  (void (*)(void));
  33     void        exit    (int status) __noreturn;
  34     void        _Exit   (int status) __noreturn;
  35     char       *getenv  (const char *name);
  36     int         setenv  (register const char * name,
  37                          register const char * value, int rewrite);
  38     int         system  (const char *string);
  39
  40     ################  Integer arithmetic functions
  41     int         abs     (int j);
  42     long        labs    (long j);
  43     long long   llabs   (long long j);
  44     div_t       div     (int numer, int denom);
  45     ldiv_t      ldiv    (long numer, long denom);
  46     lldiv_t     lldiv   (long long numer, long long denom);
  47
  48     ################  Pseudo-random sequence generation functions
  49     int         rand    (void);
  50     void        srand   (unsigned seed);
  51
  52     ################  Memory management functions
  53     void       *calloc  (size_t Num, size_t Size);
  54     void        free    (void *);
  55     void       *malloc  (size_t);
  56     void       *realloc (void *Ptr, size_t NewSize);
  57
  58     ################  Searching and Sorting utilities
  59     void       *bsearch (const void *key,  const void *base0,
  60                          size_t nmemb,     size_t size,
  61                          int (*compar)(const void *, const void *));
  62     void        qsort   (void *base, size_t nmemb, size_t size,
  63                          int (*compar)(const void *, const void *));
  64
  65     ################  Multibyte/wide character conversion functions
  66     int         mblen   (const char *, size_t);
  67     int         mbtowc  (wchar_t * __restrict, const char * __restrict, size_t);
  68     int         wctomb  (char *, wchar_t);
  69
  70     ################  Multibyte/wide string conversion functions
  71     size_t      mbstowcs  (wchar_t * __restrict dest,
  72                            const char * __restrict src, size_t limit);
  73     size_t      wcstombs  (char * __restrict dest,
  74                            const wchar_t * __restrict src, size_t limit);
  75
  76     ################  Miscelaneous functions for *nix compatibility
  77     char       *realpath    (char *file_name, char *resolved_name);
  78     const char *getprogname (void);
  79     void        setprogname (const char *progname);
  80
  81     ############  Integer Numeric conversion functions
  82     int                   atoi      (const char *nptr);
  83     long                  atol      (const char *nptr);
  84     long long             atoll     (const char *nptr);
  85     long                  strtol    (const char * __restrict nptr,
  86                                      char ** __restrict endptr, int base);
  87     unsigned long         strtoul   (const char * __restrict nptr,
  88                                      char ** __restrict endptr, int base);
  89     long long             strtoll   (const char * __restrict nptr,
  90                                      char ** __restrict endptr, int base);
  91     unsigned long long    strtoull  (const char * __restrict nptr,
  92                                      char ** __restrict endptr, int base);
  93
  94     #########  Floating-point Numeric conversion functions
  95     double                atof      (const char *);
  96     double                strtod    (const char * __restrict nptr,
  97                                      char ** __restrict endptr);
  98     float                 strtof    (const char * __restrict nptr,
  99                                      char ** __restrict endptr);
 100     long double           strtold   (const char * __restrict nptr,
 101                                      char ** __restrict endptr);
 102   @endverbatim
 103
 104   Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
 105   This program and the accompanying materials are licensed and made available under
 106   the terms and conditions of the BSD License that accompanies this distribution.
 107   The full text of the license may be found at
 108   http://opensource.org/licenses/bsd-license.
 109
 110   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
 111   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 112 **/
 113 #ifndef _STDLIB_H
 114 #define _STDLIB_H
 115 #include  <sys/EfiCdefs.h>
 116
 117 #ifdef _EFI_SIZE_T_
 118   /** Unsigned integer type of the result of the sizeof operator. **/
 119   typedef _EFI_SIZE_T_  size_t;
 120   #undef _EFI_SIZE_T_
 121   #undef _BSD_SIZE_T_
 122 #endif
 123
 124 #ifndef __cplusplus
 125   #ifdef _EFI_WCHAR_T
 126     /** Type of a wide (Unicode) character. **/
 127     typedef _EFI_WCHAR_T wchar_t;
 128     #undef  _EFI_WCHAR_T
 129     #undef _BSD_WCHAR_T_
 130   #endif
 131 #endif
 132
 133 /// A structure type that is the type of the value returned by the div function.
 134 typedef struct {
 135   int quot;   /**< quotient */
 136   int rem;    /**< remainder */
 137 } div_t;
 138
 139 /// A structure type that is the type of the value returned by the ldiv function.
 140 typedef struct {
 141   long  quot;
 142   long  rem;
 143 } ldiv_t;
 144
 145 /// A structure type that is the type of the value returned by the lldiv function.
 146 typedef struct {
 147   long long quot;
 148   long long rem;
 149 } lldiv_t;
 150
 151 /** @{
 152     Expand to integer constant expressions that can be used as the argument to
 153     the exit function to return unsuccessful or successful termination status,
 154     respectively, to the host environment.
 155 **/
 156 #define EXIT_FAILURE  1
 157 #define EXIT_SUCCESS  0
 158 /*@}*/
 159
 160 /** Expands to an integer constant expression that is the maximum value
 161     returned by the rand function.
 162 **/
 163 #define RAND_MAX  0x7fffffff
 164
 165 /** Expands to a positive integer expression with type size_t that is the
 166     maximum number of bytes in a multibyte character for the extended character
 167     set specified by the current locale (category LC_CTYPE), which is never
 168     greater than MB_LEN_MAX.
 169 **/
 170 #define MB_CUR_MAX  2
 171
 172 /** Maximum number of functions that can be registered by atexit.
 173
 174     The C standard states that the implementation shall support the
 175     registration of at least 32 functions.
 176 **/
 177 #define ATEXIT_MAX  32
 178
 179 __BEGIN_DECLS
 180
 181 /* ################  Communication with the environment  ################## */
 182
 183 /** The abort function causes abnormal program termination to occur, unless
 184     the signal SIGABRT is being caught and the signal handler does not return.
 185
 186     Open streams with unwritten buffered data are not flushed, open
 187     streams are not closed, and temporary files are not removed by abort.
 188
 189     Unsuccessful termination is returned to the host environment by means of
 190     the function call, raise(SIGABRT).
 191
 192     @sa signal.h
 193 **/
 194 void    abort(void) __noreturn;
 195
 196 /** The atexit function registers the function pointed to by func, to be
 197     called without arguments at normal program termination.
 198
 199     The implementation supports the registration of up to 32 functions.
 200
 201     @param[in]  Handler   Pointer to the function to register as one of the
 202                           routines to call at application exit time.
 203
 204     @return   The atexit function returns zero if the registration succeeds,
 205               nonzero if it fails.
 206 **/
 207 int     atexit(void (*Handler)(void));
 208
 209 /** The exit function causes normal program termination to occur. If more than
 210     one call to the exit function is executed by a program,
 211     the behavior is undefined.
 212
 213     First, all functions registered by the atexit function are called, in the
 214     reverse order of their registration, except that a function is called
 215     after any previously registered functions that had already been called at
 216     the time it was registered. If, during the call to any such function, a
 217     call to the longjmp function is made that would terminate the call to the
 218     registered function, the behavior is undefined.
 219
 220     Next, all open streams with unwritten buffered data are flushed, all open
 221     streams are closed, and all files created by the tmpfile function
 222     are removed.
 223
 224     Finally, control is returned to the host environment.
 225
 226     @param[in]  status    A value to be returned when the application exits.
 227
 228     @return   If the value of status is zero, or EXIT_SUCCESS, status is
 229               returned unchanged. If the value of status is EXIT_FAILURE,
 230               RETURN_ABORTED is returned.  Otherwise, status is returned unchanged.
 231 **/
 232 void    exit(int status) __noreturn;
 233
 234 /** The _Exit function causes normal program termination to occur and control
 235     to be returned to the host environment.
 236
 237     No functions registered by the atexit function or signal handlers
 238     registered by the signal function are called.  Open streams with unwritten
 239     buffered data are not flushed, open streams are not closed, and temporary
 240     files are not removed by abort.
 241
 242     The status returned to the host environment is determined in the same way
 243     as for the exit function.
 244
 245     @param[in]  status    A value to be returned when the application exits.
 246
 247     @return   If the value of status is zero, or EXIT_SUCCESS, status is
 248               returned unchanged. If the value of status is EXIT_FAILURE,
 249               RETURN_ABORTED is returned.  Otherwise, status is returned unchanged.
 250 **/
 251 void    _Exit(int status) __noreturn;
 252
 253 /** The getenv function searches an environment list, provided by the host
 254     environment, for a string that matches the string pointed to by name.  The
 255     set of environment names and the method for altering the environment list
 256     are determined by the underlying UEFI Shell implementation.
 257
 258     @param[in]  name    Pointer to a string naming the environment variable to retrieve.
 259
 260     @return   The getenv function returns a pointer to a string associated with
 261               the matched list member.  The string pointed to shall not be
 262               modified by the program, but may be overwritten by a subsequent
 263               call to the getenv function.  If the specified name cannot be
 264               found, a null pointer is returned.
 265 **/
 266 char   *getenv(const char *name);
 267
 268 /** Add or update a variable in the environment list.
 269
 270     @param[in]  name     Address of a zero terminated name string.
 271     @param[in]  value    Address of a zero terminated value string.
 272     @param[in]  rewrite  TRUE allows overwriting existing values.
 273
 274     @retval  0  Returns 0 upon success.
 275     @retval -1  Returns -1 upon failure, sets errno with more information.
 276 **/
 277 int
 278 setenv (
 279   register const char * name,
 280   register const char * value,
 281   int rewrite
 282   );
 283
 284 /** If string is a null pointer, the system function determines whether the
 285     host environment has a command processor. If string is not a null pointer,
 286     the system function passes the string pointed to by string to that command
 287     processor to be executed in a manner which the implementation shall
 288     document; this might then cause the program calling system to behave in a
 289     non-conforming manner or to terminate.
 290
 291     @param[in]  string    Pointer to the command string to be executed.
 292
 293     @return   If the argument is a null pointer, the system function returns
 294               nonzero only if a command processor is available. If the argument
 295               is not a null pointer, and the system function does return, it
 296               returns an implementation-defined value.
 297 **/
 298 int     system(const char *string);
 299
 300
 301 /* ################  Integer arithmetic functions  ######################## */
 302
 303 /** Computes the absolute value of an integer j.
 304
 305     @param[in]  j   The value to find the absolute value of.
 306
 307     @return   The absolute value of j.
 308 **/
 309 int     abs(int j);
 310
 311 /** Computes the absolute value of a long integer j.
 312
 313     @param[in]  j   The value to find the absolute value of.
 314
 315     @return   The absolute value of j.
 316 **/
 317 long    labs(long j);
 318
 319 /** Computes the absolute value of a long long integer j.
 320
 321     @param[in]  j   The value to find the absolute value of.
 322
 323     @return   The absolute value of j.
 324 **/
 325 long long
 326         llabs(long long j);
 327
 328 /** Computes numer / denom and numer % denom in a single operation.
 329
 330     @param[in]  numer   The numerator for the division.
 331     @param[in]  denom   The denominator for the division.
 332
 333     @return   Returns a structure of type div_t, comprising both the
 334               quotient and the remainder.
 335 **/
 336 div_t   div(int numer, int denom);
 337
 338 /** Computes numer / denom and numer % denom in a single operation.
 339
 340     @param[in]  numer   The numerator for the division.
 341     @param[in]  denom   The denominator for the division.
 342
 343     @return   Returns a structure of type ldiv_t, comprising both the
 344               quotient and the remainder.
 345 **/
 346 ldiv_t  ldiv(long numer, long denom);
 347
 348 /** Computes numer / denom and numer % denom in a single operation.
 349
 350     @param[in]  numer   The numerator for the division.
 351     @param[in]  denom   The denominator for the division.
 352
 353     @return   Returns a structure of type lldiv_t, comprising both the
 354               quotient and the remainder.
 355 **/
 356 lldiv_t lldiv(long long numer, long long denom);
 357
 358 /* ############  Integer Numeric conversion functions  #################### */
 359
 360 /** The atoi function converts the initial portion of the string pointed to by
 361     nptr to int representation.  Except for the behavior on error, it is
 362     equivalent to:
 363       - atoi: (int)strtol(nptr, (char **)NULL, 10)
 364
 365     @param[in]  nptr  Pointer to the string to be converted.
 366
 367     @return   The atoi function returns the converted value.
 368 **/
 369 int     atoi(const char *nptr);
 370
 371 /** The atol function converts the initial portion of the string pointed to by
 372     nptr to long int representation.  Except for the behavior on error, it is
 373     equivalent to:
 374       - atol: strtol(nptr, (char **)NULL, 10)
 375
 376     @param[in]  nptr  Pointer to the string to be converted.
 377
 378     @return   The atol function returns the converted value.
 379 **/
 380 long    atol(const char *nptr);
 381
 382 /** The atoll function converts the initial portion of the string pointed to by
 383     nptr to long long int representation.  Except for the behavior on error, it
 384     is equivalent to:
 385       - atoll: strtoll(nptr, (char **)NULL, 10)
 386
 387     @param[in]  nptr  Pointer to the string to be converted.
 388
 389     @return   The atoll function returns the converted value.
 390 **/
 391 long long
 392         atoll(const char *nptr);
 393
 394 /** The strtol, strtoll, strtoul, and strtoull functions convert the initial
 395     portion of the string pointed to by nptr to long int, long long int,
 396     unsigned long int, and unsigned long long int representation, respectively.
 397     First, they decompose the input string into three parts: an initial,
 398     possibly empty, sequence of white-space characters (as specified by the
 399     isspace function), a subject sequence resembling an integer represented in
 400     some radix determined by the value of base, and a final string of one or
 401     more unrecognized characters, including the terminating null character of
 402     the input string. Then, they attempt to convert the subject sequence to an
 403     integer, and return the result.
 404
 405     If the value of base is zero, the expected form of the subject sequence is
 406     that of an integer constant, optionally preceded
 407     by a plus or minus sign, but not including an integer suffix. If the value
 408     of base is between 2 and 36 (inclusive), the expected form of the subject
 409     sequence is a sequence of letters and digits representing an integer with
 410     the radix specified by base, optionally preceded by a plus or minus sign,
 411     but not including an integer suffix. The letters from a (or A) through z
 412     (or Z) are ascribed the values 10 through 35; only letters and digits whose
 413     ascribed values are less than that of base are permitted. If the value of
 414     base is 16, the characters 0x or 0X may optionally precede the sequence of
 415     letters and digits, following the sign if present.
 416
 417     The subject sequence is defined as the longest initial subsequence of the
 418     input string, starting with the first non-white-space character, that is of
 419     the expected form. The subject sequence contains no characters if the input
 420     string is empty or consists entirely of white space, or if the first
 421     non-white-space character is other than a sign or a permissible letter or digit.
 422
 423     If the subject sequence has the expected form and the value of base is
 424     zero, the sequence of characters starting with the first digit is
 425     interpreted as an integer constant. If the subject sequence has the
 426     expected form and the value of base is between 2 and 36, it is used as the
 427     base for conversion, ascribing to each letter its value as given above. If
 428     the subject sequence begins with a minus sign, the value resulting from the
 429     conversion is negated (in the return type). A pointer to the final string
 430     is stored in the object pointed to by endptr, provided that endptr is
 431     not a null pointer.
 432
 433     In other than the "C" locale, additional locale-specific subject sequence
 434     forms may be accepted.
 435
 436     If the subject sequence is empty or does not have the expected form, no
 437     conversion is performed; the value of nptr is stored in the object pointed
 438     to by endptr, provided that endptr is not a null pointer.
 439
 440     @param[in]    nptr    Pointer to the string to be converted.
 441     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 442     @param[in]    base    The base, 0 to 36, of the number represented by the input string.
 443
 444     @return   The strtol, strtoll, strtoul, and strtoull functions return the
 445               converted value, if any. If no conversion could be performed, zero
 446               is returned. If the correct value is outside the range of
 447               representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,
 448               ULONG_MAX, or ULLONG_MAX is returned (according to the return type
 449               and sign of the value, if any), and the value of the macro ERANGE
 450               is stored in errno.
 451 **/
 452 long    strtol(const char * __restrict nptr, char ** __restrict endptr, int base);
 453
 454 /** The strtoul function converts the initial portion of the string pointed to
 455     by nptr to unsigned long int representation.
 456
 457     See the description for strtol for more information.
 458
 459     @param[in]    nptr    Pointer to the string to be converted.
 460     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 461     @param[in]    base    The base, 0 to 36, of the number represented by the input string.
 462
 463     @return   The strtoul function returns the converted value, if any. If no
 464               conversion could be performed, zero is returned. If the correct
 465               value is outside the range of representable values, ULONG_MAX is
 466               returned and the value of the macro ERANGE is stored in errno.
 467 **/
 468 unsigned long
 469         strtoul(const char * __restrict nptr, char ** __restrict endptr, int base);
 470
 471 /** The strtoll function converts the initial portion of the string pointed to
 472     by nptr to long long int representation.
 473
 474     See the description for strtol for more information.
 475
 476     @param[in]    nptr    Pointer to the string to be converted.
 477     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 478     @param[in]    base    The base, 0 to 36, of the number represented by the input string.
 479
 480     @return   The strtoll function returns the converted value, if any. If no
 481               conversion could be performed, zero is returned. If the correct
 482               value is outside the range of representable values, LLONG_MIN or
 483               LLONG_MAX is returned (according to the sign of the value, if any),
 484               and the value of the macro ERANGE is stored in errno.
 485 **/
 486 long long
 487         strtoll(const char * __restrict nptr, char ** __restrict endptr, int base);
 488
 489 /** The strtoull function converts the initial portion of the string pointed to
 490     by nptr to unsigned long long int representation.
 491
 492     See the description for strtol for more information.
 493
 494     @param[in]    nptr    Pointer to the string to be converted.
 495     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 496     @param[in]    base    The base, 0 to 36, of the number represented by the input string.
 497
 498     @return   The strtoull function returns the converted value, if any. If no
 499               conversion could be performed, zero is returned. If the correct
 500               value is outside the range of representable values, ULLONG_MAX is
 501               returned and the value of the macro ERANGE is stored in errno.
 502 **/
 503 unsigned long long
 504         strtoull(const char * __restrict nptr, char ** __restrict endptr, int base);
 505
 506 /* #########  Floating-point Numeric conversion functions  ################ */
 507
 508 /** Convert the initial part of a string to double representation.
 509
 510     @param[in]  nptr  Pointer to the string to be converted.
 511
 512     @return   The floating-point value representing the string nptr.
 513 **/
 514 double  atof(const char *nptr);
 515
 516 /** @{
 517     The strtod, strtof, and strtold functions convert the initial portion of
 518     the string pointed to by nptr to double, float, and long double
 519     representation, respectively. First, they decompose the input string into
 520     three parts: an initial, possibly empty, sequence of white-space characters
 521     (as specified by the isspace function), a subject sequence resembling a
 522     floating-point constant or representing an infinity or NaN; and a final
 523     string of one or more unrecognized characters, including the terminating
 524     null character of the input string. Then, they attempt to convert the
 525     subject sequence to a floating-point number, and return the result.
 526 */
 527
 528 /** Convert a string to a double and point to the character after the last converted.
 529
 530     @param[in]    nptr    Pointer to the string to be converted.
 531     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 532
 533     @return   A floating-point value representing the string nptr.
 534               A pointer to the final string is stored in the object pointed to
 535               by endptr, provided that endptr is not a null pointer.
 536               If the subject sequence is empty or does not have the expected
 537               form, no conversion is performed; the value of nptr is stored in
 538               the object pointed to by endptr, provided that endptr is not a null pointer.
 539 **/
 540 double  strtod(const char * __restrict nptr, char ** __restrict endptr);
 541
 542 /** Convert a string to a float and point to the character after the last converted.
 543
 544     @param[in]    nptr    Pointer to the string to be converted.
 545     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 546
 547     @return   A floating-point value representing the string nptr.
 548               A pointer to the final string is stored in the object pointed to
 549               by endptr, provided that endptr is not a null pointer.
 550               If the subject sequence is empty or does not have the expected
 551               form, no conversion is performed; the value of nptr is stored in
 552               the object pointed to by endptr, provided that endptr is not a null pointer.
 553 **/
 554 float   strtof(const char * __restrict nptr, char ** __restrict endptr);
 555
 556 /** Convert a string to a long double and point to the character after the last converted.
 557
 558     @param[in]    nptr    Pointer to the string to be converted.
 559     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 560
 561     @return   A floating-point value representing the string nptr.
 562               A pointer to the final string is stored in the object pointed to
 563               by endptr, provided that endptr is not a null pointer.
 564               If the subject sequence is empty or does not have the expected
 565               form, no conversion is performed; the value of nptr is stored in
 566               the object pointed to by endptr, provided that endptr is not a null pointer.
 567 **/
 568 long double
 569         strtold(const char * __restrict nptr, char ** __restrict endptr);
 570 /*@}*/
 571
 572 /* ################  Pseudo-random sequence generation functions  ######### */
 573
 574 /** The rand function computes a sequence of pseudo-random integers in the
 575     range 0 to RAND_MAX.
 576
 577     @return   The rand function returns a pseudo-random integer.
 578 **/
 579 int     rand(void);
 580
 581 /** The srand function uses the argument as a seed for a new sequence of
 582     pseudo-random numbers to be returned by subsequent calls to rand.
 583
 584     If srand is then called with the same seed value, the sequence of
 585     pseudo-random numbers shall be repeated. If rand is called before any calls
 586     to srand have been made, the same sequence shall be generated as when srand
 587     is first called with a seed value of 1.
 588
 589     @param[in]  seed    The value used to "seed" the random number generator with.
 590 **/
 591 void    srand(unsigned seed);
 592
 593 /* ################  Memory management functions  ######################### */
 594
 595 /** The calloc function allocates space for an array of Num objects, each of
 596     whose size is Size.  The space is initialized to all bits zero.
 597
 598     @param[in]  Num   The number of objects to allocate space for.
 599     @param[in]  Size  The size, in bytes, of each object.
 600
 601     @return   NULL is returned if the space could not be allocated and errno
 602               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 603               region of the requested size is returned.
 604 **/
 605 void   *calloc(size_t Num, size_t Size);
 606
 607 /** The free function causes the space pointed to by Ptr to be deallocated,
 608     that is, made available for further allocation.
 609
 610     If Ptr is a null pointer, no action occurs.  Otherwise, if the argument
 611     does not match a pointer earlier returned by the calloc, malloc, or realloc
 612     function, or if the space has been deallocated by a call to free or
 613     realloc, the behavior is undefined.
 614
 615     @param  Ptr     Pointer to a previously allocated region of memory to be freed.
 616 **/
 617 void    free(void *Ptr);
 618
 619 /** The malloc function allocates space for an object whose size is specified
 620     by size and whose value is indeterminate.
 621
 622     This implementation uses the UEFI memory allocation boot services to get a
 623     region of memory that is 8-byte aligned and of the specified size.  The
 624     region is allocated with type EfiLoaderData.
 625
 626     @param  Size    Size, in bytes, of the region to allocate.
 627
 628     @return   NULL is returned if the space could not be allocated and errno
 629               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 630               region of the requested size is returned.<BR>
 631               If NULL is returned, errno may contain:
 632               - EINVAL: Requested Size is zero.
 633               - ENOMEM: Memory could not be allocated.
 634 **/
 635 void   *malloc(size_t Size);
 636
 637 /** The realloc function changes the size of the object pointed to by Ptr to
 638     the size specified by NewSize.
 639
 640     The contents of the object are unchanged up to the lesser of the new and
 641     old sizes.  If the new size is larger, the value of the newly allocated
 642     portion of the object is indeterminate.
 643
 644     If Ptr is a null pointer, the realloc function behaves like the malloc
 645     function for the specified size.
 646
 647     If Ptr does not match a pointer earlier returned by the calloc, malloc, or
 648     realloc function, or if the space has been deallocated by a call to the free
 649     or realloc function, the behavior is undefined.
 650
 651     If the space cannot be allocated, the object pointed to by Ptr is unchanged.
 652
 653     If NewSize is zero and Ptr is not a null pointer, the object it points to
 654     is freed.
 655
 656     This implementation uses the UEFI memory allocation boot services to get a
 657     region of memory that is 8-byte aligned and of the specified size.  The
 658     region is allocated with type EfiLoaderData.
 659
 660     @param  Ptr     Pointer to a previously allocated region of memory to be resized.
 661     @param  NewSize Size, in bytes, of the new object to allocate space for.
 662
 663     @return   NULL is returned if the space could not be allocated and errno
 664               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 665               region of the requested size is returned.  If NewSize is zero,
 666               NULL is returned and errno will be unchanged.
 667 **/
 668 void   *realloc(void *Ptr, size_t NewSize);
 669
 670 /* ################  Searching and Sorting utilities  ##################### */
 671
 672 /** The bsearch function searches an array of Nmemb objects, the initial
 673     element of which is pointed to by Base, for an element that matches the
 674     object pointed to by Key. The size of each element of the array is
 675     specified by Size.
 676
 677     The comparison function pointed to by Compar is called with two arguments
 678     that point to the Key object and to an array element, in that order. The
 679     function returns an integer less than, equal to, or greater than zero if
 680     the Key object is considered, respectively, to be less than, to match, or
 681     to be greater than the array element. The array consists of: all the
 682     elements that compare less than, all the elements that compare equal to,
 683     and all the elements that compare greater than the key object,
 684     in that order.
 685
 686     @param[in]  Key     Pointer to the object to search for.
 687     @param[in]  Base    Pointer to the first element of an array to search.
 688     @param[in]  Nmemb   Number of objects in the search array.
 689     @param[in]  Size    The size of each object in the search array.
 690     @param[in]  Compar  Pointer to the function used to compare two objects.
 691
 692     @return   The bsearch function returns a pointer to a matching element of the
 693               array, or a null pointer if no match is found. If two elements
 694               compare as equal, which element is matched is unspecified.
 695 **/
 696 void   *bsearch(  const void *Key,  const void *Base,
 697                   size_t Nmemb,     size_t Size,
 698                   int (*Compar)(const void *, const void *)
 699         );
 700
 701 /** The qsort function sorts an array of Nmemb objects, the initial element of
 702     which is pointed to by Base.  The size of each object is specified by Size.
 703
 704     The contents of the array are sorted into ascending order according to a
 705     comparison function pointed to by Compar, which is called with two
 706     arguments that point to the objects being compared. The function shall
 707     return an integer less than, equal to, or greater than zero if the first
 708     argument is considered to be respectively less than, equal to, or greater
 709     than the second.
 710
 711     If two elements compare as equal, their order in the resulting sorted array
 712     is unspecified.
 713
 714     @param[in,out]  Base    Pointer to the first element of an array to sort.
 715     @param[in]      Nmemb   Number of objects in the array.
 716     @param[in]      Size    The size of each object in the array.
 717     @param[in]      Compar  Pointer to the function used to compare two objects.
 718 **/
 719 void    qsort( void *base, size_t nmemb, size_t size,
 720                int (*compar)(const void *, const void *));
 721
 722 /* ################  Multibyte/wide character conversion functions  ####### */
 723
 724 /** Determine the number of bytes comprising a multibyte character.
 725
 726   If S is not a null pointer, the mblen function determines the number of bytes
 727   contained in the multibyte character pointed to by S. Except that the
 728   conversion state of the mbtowc function is not affected, it is equivalent to
 729     mbtowc((wchar_t *)0, S, N);
 730
 731   @param[in]  S   NULL to query whether multibyte characters have
 732                   state-dependent encodings.  Otherwise, points to a
 733                   multibyte character.
 734   @param[in]  N   The maximum number of bytes in a multibyte character.
 735
 736   @return   If S is a null pointer, the mblen function returns a nonzero or
 737             zero value, if multibyte character encodings, respectively, do
 738             or do not have state-dependent encodings. If S is not a null
 739             pointer, the mblen function either returns 0 (if S points to the
 740             null character), or returns the number of bytes that are contained
 741             in the multibyte character (if the next N or fewer bytes form a
 742             valid multibyte character), or returns -1 (if they do not form a
 743             valid multibyte character).
 744 **/
 745 int     mblen(const char *S, size_t N);
 746
 747 /** Convert a multibyte character into a wide character.
 748
 749     If S is not a null pointer, the mbtowc function inspects at most N bytes
 750     beginning with the byte pointed to by S to determine the number of bytes
 751     needed to complete the next multibyte character (including any shift
 752     sequences). If the function determines that the next multibyte character
 753     is complete and valid, it determines the value of the corresponding wide
 754     character and then, if Pwc is not a null pointer, stores that value in
 755     the object pointed to by Pwc. If the corresponding wide character is the
 756     null wide character, the function is left in the initial conversion state.
 757
 758     @param[out]   Pwc Pointer to a wide-character object to receive the converted character.
 759     @param[in]    S   Pointer to a multibyte character to convert.
 760     @param[in]    N   Maximum number of bytes in a multibyte character.
 761
 762     @return   If S is a null pointer, the mbtowc function returns a nonzero or
 763               zero value, if multibyte character encodings, respectively, do
 764               or do not have state-dependent encodings. If S is not a null
 765               pointer, the mbtowc function either returns 0 (if S points to
 766               the null character), or returns the number of bytes that are
 767               contained in the converted multibyte character (if the next N or
 768               fewer bytes form a valid multibyte character), or returns -1
 769               (if they do not form a valid multibyte character).
 770
 771               In no case will the value returned be greater than N or the value
 772               of the MB_CUR_MAX macro.
 773 **/
 774 int     mbtowc(wchar_t * __restrict Pwc, const char * __restrict S, size_t N);
 775
 776 /** Convert a wide character into a multibyte character.
 777
 778     The wctomb function determines the number of bytes needed to represent the
 779     multibyte character corresponding to the wide character given by WC
 780     (including any shift sequences), and stores the multibyte character
 781     representation in the array whose first element is pointed to by S (if S is
 782     not a null pointer). At most MB_CUR_MAX characters are stored. If WC is a
 783     null wide character, a null byte is stored, preceded by any shift sequence
 784     needed to restore the initial shift state, and the function is left in the
 785     initial conversion state.
 786
 787     @param[out]   S   Pointer to the object to receive the converted multibyte character.
 788     @param[in]    WC  Wide character to be converted.
 789
 790     @return   If S is a null pointer, the wctomb function returns a nonzero or
 791               zero value, if multibyte character encodings, respectively, do or
 792               do not have state-dependent encodings. If S is not a null pointer,
 793               the wctomb function returns -1 if the value of WC does not
 794               correspond to a valid multibyte character, or returns the number
 795               of bytes that are contained in the multibyte character
 796               corresponding to the value of WC.
 797
 798               In no case will the value returned be greater than the value of
 799               the MB_CUR_MAX macro.
 800 **/
 801 int     wctomb(char *S, wchar_t WC);
 802
 803 /* ################  Multibyte/wide string conversion functions  ########## */
 804
 805 /** Convert a multibyte character string into a wide-character string.
 806
 807     The mbstowcs function converts a sequence of multibyte characters that
 808     begins in the initial shift state from the array pointed to by Src into
 809     a sequence of corresponding wide characters and stores not more than limit
 810     wide characters into the array pointed to by Dest.  No multibyte
 811     characters that follow a null character (which is converted into a null
 812     wide character) will be examined or converted. Each multibyte character
 813     is converted as if by a call to the mbtowc function, except that the
 814     conversion state of the mbtowc function is not affected.
 815
 816     No more than Limit elements will be modified in the array pointed to by Dest.
 817     If copying takes place between objects that overlap,
 818     the behavior is undefined.
 819
 820     @param[out]   Dest    Pointer to the array to receive the converted string.
 821     @param[in]    Src     Pointer to the string to be converted.
 822     @param[in]    Limit   Maximum number of elements to be written to Dest.
 823
 824     @return   If an invalid multibyte character is encountered, the mbstowcs
 825               function returns (size_t)(-1). Otherwise, the mbstowcs function
 826               returns the number of array elements modified, not including a
 827               terminating null wide character, if any.
 828 **/
 829 size_t  mbstowcs(wchar_t * __restrict Dest, const char * __restrict Src, size_t Limit);
 830
 831 /** Convert a wide-character string into a multibyte character string.
 832
 833     The wcstombs function converts a sequence of wide characters from the
 834     array pointed to by Src into a sequence of corresponding multibyte
 835     characters that begins in the initial shift state, and stores these
 836     multibyte characters into the array pointed to by Dest, stopping if a
 837     multibyte character would exceed the limit of Limit total bytes or if a
 838     null character is stored. Each wide character is converted as if by
 839     a call to the wctomb function, except that the conversion state of
 840     the wctomb function is not affected.
 841
 842     No more than Limit bytes will be modified in the array pointed to by Dest.
 843     If copying takes place between objects that overlap,
 844     the behavior is undefined.
 845
 846     @param[out]   Dest    Pointer to the array to receive the converted string.
 847     @param[in]    Src     Pointer to the string to be converted.
 848     @param[in]    Limit   Maximum number of elements to be written to Dest.
 849
 850     @return   If a wide character is encountered that does not correspond to a
 851               valid multibyte character, the wcstombs function returns
 852               (size_t)(-1). Otherwise, the wcstombs function returns the number
 853               of bytes modified, not including a terminating null character,
 854               if any.
 855 **/
 856 size_t  wcstombs(char * __restrict Dest, const wchar_t * __restrict Src, size_t Limit);
 857
 858 /* ################  Miscelaneous functions for *nix compatibility  ########## */
 859
 860 /** The realpath() function shall derive, from the pathname pointed to by
 861     file_name, an absolute pathname that names the same file, whose resolution
 862     does not involve '.', '..', or symbolic links. The generated pathname shall
 863     be stored as a null-terminated string, up to a maximum of {PATH_MAX} bytes,
 864     in the buffer pointed to by resolved_name.
 865
 866     If resolved_name is a null pointer, the behavior of realpath() is
 867     implementation-defined.
 868
 869     @param[in]      file_name         The filename to convert.
 870     @param[in,out]  resolved_name     The resultant name.
 871
 872     @retval NULL                    An error occured.
 873     @retval resolved_name.
 874 **/
 875 char * realpath(char *file_name, char *resolved_name);
 876
 877 /** The getprogname() function returns the name of the program.  If the name
 878     has not been set yet, it will return NULL.
 879
 880   @return   The getprogname function returns NULL if the program's name has not
 881             been set, otherwise it returns the name of the program.
 882 **/
 883 const char * getprogname(void);
 884
 885 /** The setprogname() function sets the name of the program.
 886
 887   @param[in]  progname    The name of the program.  This memory must be retained
 888                           by the caller until no calls to "getprogname" will be
 889                           called.
 890 **/
 891 void setprogname(const char *progname);
 892
 893 __END_DECLS
 894
 895 #endif  /* _STDLIB_H */