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 - 2012, 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     Since UEFI only supports the Unicode Base Multilingual Plane (BMP),
 171     correctly formed characters will only produce 1, 2, or 3-byte UTF-8 characters.
 172 **/
 173 #define MB_CUR_MAX  3
 174
 175 /** Maximum number of functions that can be registered by atexit.
 176
 177     The C standard states that the implementation shall support the
 178     registration of at least 32 functions.
 179 **/
 180 #define ATEXIT_MAX  32
 181
 182 __BEGIN_DECLS
 183
 184 /* ################  Communication with the environment  ################## */
 185
 186 /** The abort function causes abnormal program termination to occur, unless
 187     the signal SIGABRT is being caught and the signal handler does not return.
 188
 189     Open streams with unwritten buffered data are not flushed, open
 190     streams are not closed, and temporary files are not removed by abort.
 191
 192     Unsuccessful termination is returned to the host environment by means of
 193     the function call, raise(SIGABRT).
 194
 195     @sa signal.h
 196 **/
 197 void    abort(void) __noreturn;
 198
 199 /** The atexit function registers the function pointed to by func, to be
 200     called without arguments at normal program termination.
 201
 202     The implementation supports the registration of up to 32 functions.
 203
 204     @param[in]  Handler   Pointer to the function to register as one of the
 205                           routines to call at application exit time.
 206
 207     @return   The atexit function returns zero if the registration succeeds,
 208               nonzero if it fails.
 209 **/
 210 int     atexit(void (*Handler)(void));
 211
 212 /** The exit function causes normal program termination to occur. If more than
 213     one call to the exit function is executed by a program,
 214     the behavior is undefined.
 215
 216     First, all functions registered by the atexit function are called, in the
 217     reverse order of their registration, except that a function is called
 218     after any previously registered functions that had already been called at
 219     the time it was registered. If, during the call to any such function, a
 220     call to the longjmp function is made that would terminate the call to the
 221     registered function, the behavior is undefined.
 222
 223     Next, all open streams with unwritten buffered data are flushed, all open
 224     streams are closed, and all files created by the tmpfile function
 225     are removed.
 226
 227     Finally, control is returned to the host environment.
 228
 229     @param[in]  status    A value to be returned when the application exits.
 230
 231     @return   If the value of status is zero, or EXIT_SUCCESS, status is
 232               returned unchanged. If the value of status is EXIT_FAILURE,
 233               RETURN_ABORTED is returned.  Otherwise, status is returned unchanged.
 234 **/
 235 void    exit(int status) __noreturn;
 236
 237 /** The _Exit function causes normal program termination to occur and control
 238     to be returned to the host environment.
 239
 240     No functions registered by the atexit function or signal handlers
 241     registered by the signal function are called.  Open streams with unwritten
 242     buffered data are not flushed, open streams are not closed, and temporary
 243     files are not removed by abort.
 244
 245     The status returned to the host environment is determined in the same way
 246     as for the exit function.
 247
 248     @param[in]  status    A value to be returned when the application exits.
 249
 250     @return   If the value of status is zero, or EXIT_SUCCESS, status is
 251               returned unchanged. If the value of status is EXIT_FAILURE,
 252               RETURN_ABORTED is returned.  Otherwise, status is returned unchanged.
 253 **/
 254 void    _Exit(int status) __noreturn;
 255
 256 /** The getenv function searches an environment list, provided by the host
 257     environment, for a string that matches the string pointed to by name.  The
 258     set of environment names and the method for altering the environment list
 259     are determined by the underlying UEFI Shell implementation.
 260
 261     @param[in]  name    Pointer to a string naming the environment variable to retrieve.
 262
 263     @return   The getenv function returns a pointer to a string associated with
 264               the matched list member.  The string pointed to shall not be
 265               modified by the program, but may be overwritten by a subsequent
 266               call to the getenv function.  If the specified name cannot be
 267               found, a null pointer is returned.
 268 **/
 269 char   *getenv(const char *name);
 270
 271 /** Add or update a variable in the environment list.
 272
 273     @param[in]  name     Address of a zero terminated name string.
 274     @param[in]  value    Address of a zero terminated value string.
 275     @param[in]  rewrite  TRUE allows overwriting existing values.
 276
 277     @retval  0  Returns 0 upon success.
 278     @retval -1  Returns -1 upon failure, sets errno with more information.
 279 **/
 280 int
 281 setenv (
 282   register const char * name,
 283   register const char * value,
 284   int rewrite
 285   );
 286
 287 /** If string is a null pointer, the system function determines whether the
 288     host environment has a command processor. If string is not a null pointer,
 289     the system function passes the string pointed to by string to that command
 290     processor to be executed in a manner which the implementation shall
 291     document; this might then cause the program calling system to behave in a
 292     non-conforming manner or to terminate.
 293
 294     @param[in]  string    Pointer to the command string to be executed.
 295
 296     @return   If the argument is a null pointer, the system function returns
 297               nonzero only if a command processor is available. If the argument
 298               is not a null pointer, and the system function does return, it
 299               returns an implementation-defined value.
 300 **/
 301 int     system(const char *string);
 302
 303
 304 /* ################  Integer arithmetic functions  ######################## */
 305
 306 /** Computes the absolute value of an integer j.
 307
 308     @param[in]  j   The value to find the absolute value of.
 309
 310     @return   The absolute value of j.
 311 **/
 312 int     abs(int j);
 313
 314 /** Computes the absolute value of a long integer j.
 315
 316     @param[in]  j   The value to find the absolute value of.
 317
 318     @return   The absolute value of j.
 319 **/
 320 long    labs(long j);
 321
 322 /** Computes the absolute value of a long long integer j.
 323
 324     @param[in]  j   The value to find the absolute value of.
 325
 326     @return   The absolute value of j.
 327 **/
 328 long long
 329         llabs(long long j);
 330
 331 /** Computes numer / denom and numer % denom in a single operation.
 332
 333     @param[in]  numer   The numerator for the division.
 334     @param[in]  denom   The denominator for the division.
 335
 336     @return   Returns a structure of type div_t, comprising both the
 337               quotient and the remainder.
 338 **/
 339 div_t   div(int numer, int denom);
 340
 341 /** Computes numer / denom and numer % denom in a single operation.
 342
 343     @param[in]  numer   The numerator for the division.
 344     @param[in]  denom   The denominator for the division.
 345
 346     @return   Returns a structure of type ldiv_t, comprising both the
 347               quotient and the remainder.
 348 **/
 349 ldiv_t  ldiv(long numer, long denom);
 350
 351 /** Computes numer / denom and numer % denom in a single operation.
 352
 353     @param[in]  numer   The numerator for the division.
 354     @param[in]  denom   The denominator for the division.
 355
 356     @return   Returns a structure of type lldiv_t, comprising both the
 357               quotient and the remainder.
 358 **/
 359 lldiv_t lldiv(long long numer, long long denom);
 360
 361 /* ############  Integer Numeric conversion functions  #################### */
 362
 363 /** The atoi function converts the initial portion of the string pointed to by
 364     nptr to int representation.  Except for the behavior on error, it is
 365     equivalent to:
 366       - atoi: (int)strtol(nptr, (char **)NULL, 10)
 367
 368     @param[in]  nptr  Pointer to the string to be converted.
 369
 370     @return   The atoi function returns the converted value.
 371 **/
 372 int     atoi(const char *nptr);
 373
 374 /** The atol function converts the initial portion of the string pointed to by
 375     nptr to long int representation.  Except for the behavior on error, it is
 376     equivalent to:
 377       - atol: strtol(nptr, (char **)NULL, 10)
 378
 379     @param[in]  nptr  Pointer to the string to be converted.
 380
 381     @return   The atol function returns the converted value.
 382 **/
 383 long    atol(const char *nptr);
 384
 385 /** The atoll function converts the initial portion of the string pointed to by
 386     nptr to long long int representation.  Except for the behavior on error, it
 387     is equivalent to:
 388       - atoll: strtoll(nptr, (char **)NULL, 10)
 389
 390     @param[in]  nptr  Pointer to the string to be converted.
 391
 392     @return   The atoll function returns the converted value.
 393 **/
 394 long long
 395         atoll(const char *nptr);
 396
 397 /** The strtol, strtoll, strtoul, and strtoull functions convert the initial
 398     portion of the string pointed to by nptr to long int, long long int,
 399     unsigned long int, and unsigned long long int representation, respectively.
 400     First, they decompose the input string into three parts: an initial,
 401     possibly empty, sequence of white-space characters (as specified by the
 402     isspace function), a subject sequence resembling an integer represented in
 403     some radix determined by the value of base, and a final string of one or
 404     more unrecognized characters, including the terminating null character of
 405     the input string. Then, they attempt to convert the subject sequence to an
 406     integer, and return the result.
 407
 408     If the value of base is zero, the expected form of the subject sequence is
 409     that of an integer constant, optionally preceded
 410     by a plus or minus sign, but not including an integer suffix. If the value
 411     of base is between 2 and 36 (inclusive), the expected form of the subject
 412     sequence is a sequence of letters and digits representing an integer with
 413     the radix specified by base, optionally preceded by a plus or minus sign,
 414     but not including an integer suffix. The letters from a (or A) through z
 415     (or Z) are ascribed the values 10 through 35; only letters and digits whose
 416     ascribed values are less than that of base are permitted. If the value of
 417     base is 16, the characters 0x or 0X may optionally precede the sequence of
 418     letters and digits, following the sign if present.
 419
 420     The subject sequence is defined as the longest initial subsequence of the
 421     input string, starting with the first non-white-space character, that is of
 422     the expected form. The subject sequence contains no characters if the input
 423     string is empty or consists entirely of white space, or if the first
 424     non-white-space character is other than a sign or a permissible letter or digit.
 425
 426     If the subject sequence has the expected form and the value of base is
 427     zero, the sequence of characters starting with the first digit is
 428     interpreted as an integer constant. If the subject sequence has the
 429     expected form and the value of base is between 2 and 36, it is used as the
 430     base for conversion, ascribing to each letter its value as given above. If
 431     the subject sequence begins with a minus sign, the value resulting from the
 432     conversion is negated (in the return type). A pointer to the final string
 433     is stored in the object pointed to by endptr, provided that endptr is
 434     not a null pointer.
 435
 436     In other than the "C" locale, additional locale-specific subject sequence
 437     forms may be accepted.
 438
 439     If the subject sequence is empty or does not have the expected form, no
 440     conversion is performed; the value of nptr is stored in the object pointed
 441     to by endptr, provided that endptr is not a null pointer.
 442
 443     @param[in]    nptr    Pointer to the string to be converted.
 444     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 445     @param[in]    base    The base, 0 to 36, of the number represented by the input string.
 446
 447     @return   The strtol, strtoll, strtoul, and strtoull functions return the
 448               converted value, if any. If no conversion could be performed, zero
 449               is returned. If the correct value is outside the range of
 450               representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,
 451               ULONG_MAX, or ULLONG_MAX is returned (according to the return type
 452               and sign of the value, if any), and the value of the macro ERANGE
 453               is stored in errno.
 454 **/
 455 long    strtol(const char * __restrict nptr, char ** __restrict endptr, int base);
 456
 457 /** The strtoul function converts the initial portion of the string pointed to
 458     by nptr to unsigned long int representation.
 459
 460     See the description for strtol for more information.
 461
 462     @param[in]    nptr    Pointer to the string to be converted.
 463     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 464     @param[in]    base    The base, 0 to 36, of the number represented by the input string.
 465
 466     @return   The strtoul function returns the converted value, if any. If no
 467               conversion could be performed, zero is returned. If the correct
 468               value is outside the range of representable values, ULONG_MAX is
 469               returned and the value of the macro ERANGE is stored in errno.
 470 **/
 471 unsigned long
 472         strtoul(const char * __restrict nptr, char ** __restrict endptr, int base);
 473
 474 /** The strtoll function converts the initial portion of the string pointed to
 475     by nptr to long long int representation.
 476
 477     See the description for strtol for more information.
 478
 479     @param[in]    nptr    Pointer to the string to be converted.
 480     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 481     @param[in]    base    The base, 0 to 36, of the number represented by the input string.
 482
 483     @return   The strtoll function returns the converted value, if any. If no
 484               conversion could be performed, zero is returned. If the correct
 485               value is outside the range of representable values, LLONG_MIN or
 486               LLONG_MAX is returned (according to the sign of the value, if any),
 487               and the value of the macro ERANGE is stored in errno.
 488 **/
 489 long long
 490         strtoll(const char * __restrict nptr, char ** __restrict endptr, int base);
 491
 492 /** The strtoull function converts the initial portion of the string pointed to
 493     by nptr to unsigned long long int representation.
 494
 495     See the description for strtol for more information.
 496
 497     @param[in]    nptr    Pointer to the string to be converted.
 498     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 499     @param[in]    base    The base, 0 to 36, of the number represented by the input string.
 500
 501     @return   The strtoull function returns the converted value, if any. If no
 502               conversion could be performed, zero is returned. If the correct
 503               value is outside the range of representable values, ULLONG_MAX is
 504               returned and the value of the macro ERANGE is stored in errno.
 505 **/
 506 unsigned long long
 507         strtoull(const char * __restrict nptr, char ** __restrict endptr, int base);
 508
 509 /* #########  Floating-point Numeric conversion functions  ################ */
 510
 511 /** Convert the initial part of a string to double representation.
 512
 513     @param[in]  nptr  Pointer to the string to be converted.
 514
 515     @return   The floating-point value representing the string nptr.
 516 **/
 517 double  atof(const char *nptr);
 518
 519 /** @{
 520     The strtod, strtof, and strtold functions convert the initial portion of
 521     the string pointed to by nptr to double, float, and long double
 522     representation, respectively. First, they decompose the input string into
 523     three parts: an initial, possibly empty, sequence of white-space characters
 524     (as specified by the isspace function), a subject sequence resembling a
 525     floating-point constant or representing an infinity or NaN; and a final
 526     string of one or more unrecognized characters, including the terminating
 527     null character of the input string. Then, they attempt to convert the
 528     subject sequence to a floating-point number, and return the result.
 529 */
 530
 531 /** Convert a string to a double and point to the character after the last converted.
 532
 533     @param[in]    nptr    Pointer to the string to be converted.
 534     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 535
 536     @return   A floating-point value representing the string nptr.
 537               A pointer to the final string is stored in the object pointed to
 538               by endptr, provided that endptr is not a null pointer.
 539               If the subject sequence is empty or does not have the expected
 540               form, no conversion is performed; the value of nptr is stored in
 541               the object pointed to by endptr, provided that endptr is not a null pointer.
 542 **/
 543 double  strtod(const char * __restrict nptr, char ** __restrict endptr);
 544
 545 /** Convert a string to a float and point to the character after the last converted.
 546
 547     @param[in]    nptr    Pointer to the string to be converted.
 548     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 549
 550     @return   A floating-point value representing the string nptr.
 551               A pointer to the final string is stored in the object pointed to
 552               by endptr, provided that endptr is not a null pointer.
 553               If the subject sequence is empty or does not have the expected
 554               form, no conversion is performed; the value of nptr is stored in
 555               the object pointed to by endptr, provided that endptr is not a null pointer.
 556 **/
 557 float   strtof(const char * __restrict nptr, char ** __restrict endptr);
 558
 559 /** Convert a string to a long double and point to the character after the last converted.
 560
 561     @param[in]    nptr    Pointer to the string to be converted.
 562     @param[out]   endptr  If not NULL, points to an object to receive a pointer to the final string.
 563
 564     @return   A floating-point value representing the string nptr.
 565               A pointer to the final string is stored in the object pointed to
 566               by endptr, provided that endptr is not a null pointer.
 567               If the subject sequence is empty or does not have the expected
 568               form, no conversion is performed; the value of nptr is stored in
 569               the object pointed to by endptr, provided that endptr is not a null pointer.
 570 **/
 571 long double
 572         strtold(const char * __restrict nptr, char ** __restrict endptr);
 573 /*@}*/
 574
 575 /* ################  Pseudo-random sequence generation functions  ######### */
 576
 577 /** The rand function computes a sequence of pseudo-random integers in the
 578     range 0 to RAND_MAX.
 579
 580     @return   The rand function returns a pseudo-random integer.
 581 **/
 582 int     rand(void);
 583
 584 /** The srand function uses the argument as a seed for a new sequence of
 585     pseudo-random numbers to be returned by subsequent calls to rand.
 586
 587     If srand is then called with the same seed value, the sequence of
 588     pseudo-random numbers shall be repeated. If rand is called before any calls
 589     to srand have been made, the same sequence shall be generated as when srand
 590     is first called with a seed value of 1.
 591
 592     @param[in]  seed    The value used to "seed" the random number generator with.
 593 **/
 594 void    srand(unsigned seed);
 595
 596 /* ################  Memory management functions  ######################### */
 597
 598 /** The calloc function allocates space for an array of Num objects, each of
 599     whose size is Size.  The space is initialized to all bits zero.
 600
 601     @param[in]  Num   The number of objects to allocate space for.
 602     @param[in]  Size  The size, in bytes, of each object.
 603
 604     @return   NULL is returned if the space could not be allocated and errno
 605               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 606               region of the requested size is returned.
 607 **/
 608 void   *calloc(size_t Num, size_t Size);
 609
 610 /** The free function causes the space pointed to by Ptr to be deallocated,
 611     that is, made available for further allocation.
 612
 613     If Ptr is a null pointer, no action occurs.  Otherwise, if the argument
 614     does not match a pointer earlier returned by the calloc, malloc, or realloc
 615     function, or if the space has been deallocated by a call to free or
 616     realloc, the behavior is undefined.
 617
 618     @param  Ptr     Pointer to a previously allocated region of memory to be freed.
 619 **/
 620 void    free(void *Ptr);
 621
 622 /** The malloc function allocates space for an object whose size is specified
 623     by size and whose value is indeterminate.
 624
 625     This implementation uses the UEFI memory allocation boot services to get a
 626     region of memory that is 8-byte aligned and of the specified size.  The
 627     region is allocated with type EfiLoaderData.
 628
 629     @param  Size    Size, in bytes, of the region to allocate.
 630
 631     @return   NULL is returned if the space could not be allocated and errno
 632               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 633               region of the requested size is returned.<BR>
 634               If NULL is returned, errno may contain:
 635               - EINVAL: Requested Size is zero.
 636               - ENOMEM: Memory could not be allocated.
 637 **/
 638 void   *malloc(size_t Size);
 639
 640 /** The realloc function changes the size of the object pointed to by Ptr to
 641     the size specified by NewSize.
 642
 643     The contents of the object are unchanged up to the lesser of the new and
 644     old sizes.  If the new size is larger, the value of the newly allocated
 645     portion of the object is indeterminate.
 646
 647     If Ptr is a null pointer, the realloc function behaves like the malloc
 648     function for the specified size.
 649
 650     If Ptr does not match a pointer earlier returned by the calloc, malloc, or
 651     realloc function, or if the space has been deallocated by a call to the free
 652     or realloc function, the behavior is undefined.
 653
 654     If the space cannot be allocated, the object pointed to by Ptr is unchanged.
 655
 656     If NewSize is zero and Ptr is not a null pointer, the object it points to
 657     is freed.
 658
 659     This implementation uses the UEFI memory allocation boot services to get a
 660     region of memory that is 8-byte aligned and of the specified size.  The
 661     region is allocated with type EfiLoaderData.
 662
 663     @param  Ptr     Pointer to a previously allocated region of memory to be resized.
 664     @param  NewSize Size, in bytes, of the new object to allocate space for.
 665
 666     @return   NULL is returned if the space could not be allocated and errno
 667               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 668               region of the requested size is returned.  If NewSize is zero,
 669               NULL is returned and errno will be unchanged.
 670 **/
 671 void   *realloc(void *Ptr, size_t NewSize);
 672
 673 /* ################  Searching and Sorting utilities  ##################### */
 674
 675 /** The bsearch function searches an array of Nmemb objects, the initial
 676     element of which is pointed to by Base, for an element that matches the
 677     object pointed to by Key. The size of each element of the array is
 678     specified by Size.
 679
 680     The comparison function pointed to by Compar is called with two arguments
 681     that point to the Key object and to an array element, in that order. The
 682     function returns an integer less than, equal to, or greater than zero if
 683     the Key object is considered, respectively, to be less than, to match, or
 684     to be greater than the array element. The array consists of: all the
 685     elements that compare less than, all the elements that compare equal to,
 686     and all the elements that compare greater than the key object,
 687     in that order.
 688
 689     @param[in]  Key     Pointer to the object to search for.
 690     @param[in]  Base    Pointer to the first element of an array to search.
 691     @param[in]  Nmemb   Number of objects in the search array.
 692     @param[in]  Size    The size of each object in the search array.
 693     @param[in]  Compar  Pointer to the function used to compare two objects.
 694
 695     @return   The bsearch function returns a pointer to a matching element of the
 696               array, or a null pointer if no match is found. If two elements
 697               compare as equal, which element is matched is unspecified.
 698 **/
 699 void   *bsearch(  const void *Key,  const void *Base,
 700                   size_t Nmemb,     size_t Size,
 701                   int (*Compar)(const void *, const void *)
 702         );
 703
 704 /** The qsort function sorts an array of Nmemb objects, the initial element of
 705     which is pointed to by Base.  The size of each object is specified by Size.
 706
 707     The contents of the array are sorted into ascending order according to a
 708     comparison function pointed to by Compar, which is called with two
 709     arguments that point to the objects being compared. The function shall
 710     return an integer less than, equal to, or greater than zero if the first
 711     argument is considered to be respectively less than, equal to, or greater
 712     than the second.
 713
 714     If two elements compare as equal, their order in the resulting sorted array
 715     is unspecified.
 716
 717     @param[in,out]  Base    Pointer to the first element of an array to sort.
 718     @param[in]      Nmemb   Number of objects in the array.
 719     @param[in]      Size    The size of each object in the array.
 720     @param[in]      Compar  Pointer to the function used to compare two objects.
 721 **/
 722 void    qsort( void *base, size_t nmemb, size_t size,
 723                int (*compar)(const void *, const void *));
 724
 725 /* ################  Multibyte/wide character conversion functions  ####### */
 726
 727 /** Determine the number of bytes comprising a multibyte character.
 728
 729   If S is not a null pointer, the mblen function determines the number of bytes
 730   contained in the multibyte character pointed to by S. Except that the
 731   conversion state of the mbtowc function is not affected, it is equivalent to
 732     mbtowc((wchar_t *)0, S, N);
 733
 734   @param[in]  S   NULL to query whether multibyte characters have
 735                   state-dependent encodings.  Otherwise, points to a
 736                   multibyte character.
 737   @param[in]  N   The maximum number of bytes in a multibyte character.
 738
 739   @return   If S is a null pointer, the mblen function returns a nonzero or
 740             zero value, if multibyte character encodings, respectively, do
 741             or do not have state-dependent encodings. If S is not a null
 742             pointer, the mblen function either returns 0 (if S points to the
 743             null character), or returns the number of bytes that are contained
 744             in the multibyte character (if the next N or fewer bytes form a
 745             valid multibyte character), or returns -1 (if they do not form a
 746             valid multibyte character).
 747 **/
 748 int     mblen(const char *S, size_t N);
 749
 750 /** Convert a multibyte character into a wide character.
 751
 752     If S is not a null pointer, the mbtowc function inspects at most N bytes
 753     beginning with the byte pointed to by S to determine the number of bytes
 754     needed to complete the next multibyte character (including any shift
 755     sequences). If the function determines that the next multibyte character
 756     is complete and valid, it determines the value of the corresponding wide
 757     character and then, if Pwc is not a null pointer, stores that value in
 758     the object pointed to by Pwc. If the corresponding wide character is the
 759     null wide character, the function is left in the initial conversion state.
 760
 761     @param[out]   Pwc Pointer to a wide-character object to receive the converted character.
 762     @param[in]    S   Pointer to a multibyte character to convert.
 763     @param[in]    N   Maximum number of bytes in a multibyte character.
 764
 765     @return   If S is a null pointer, the mbtowc function returns a nonzero or
 766               zero value, if multibyte character encodings, respectively, do
 767               or do not have state-dependent encodings. If S is not a null
 768               pointer, the mbtowc function either returns 0 (if S points to
 769               the null character), or returns the number of bytes that are
 770               contained in the converted multibyte character (if the next N or
 771               fewer bytes form a valid multibyte character), or returns -1
 772               (if they do not form a valid multibyte character).
 773
 774               In no case will the value returned be greater than N or the value
 775               of the MB_CUR_MAX macro.
 776 **/
 777 int     mbtowc(wchar_t * __restrict Pwc, const char * __restrict S, size_t N);
 778
 779 /** Convert a wide character into a multibyte character.
 780
 781     The wctomb function determines the number of bytes needed to represent the
 782     multibyte character corresponding to the wide character given by WC
 783     (including any shift sequences), and stores the multibyte character
 784     representation in the array whose first element is pointed to by S (if S is
 785     not a null pointer). At most MB_CUR_MAX characters are stored. If WC is a
 786     null wide character, a null byte is stored, preceded by any shift sequence
 787     needed to restore the initial shift state, and the function is left in the
 788     initial conversion state.
 789
 790     @param[out]   S   Pointer to the object to receive the converted multibyte character.
 791     @param[in]    WC  Wide character to be converted.
 792
 793     @return   If S is a null pointer, the wctomb function returns a nonzero or
 794               zero value, if multibyte character encodings, respectively, do or
 795               do not have state-dependent encodings. If S is not a null pointer,
 796               the wctomb function returns -1 if the value of WC does not
 797               correspond to a valid multibyte character, or returns the number
 798               of bytes that are contained in the multibyte character
 799               corresponding to the value of WC.
 800
 801               In no case will the value returned be greater than the value of
 802               the MB_CUR_MAX macro.
 803 **/
 804 int     wctomb(char *S, wchar_t WC);
 805
 806 /* ################  Multibyte/wide string conversion functions  ########## */
 807
 808 /** Convert a multibyte character string into a wide-character string.
 809
 810     The mbstowcs function converts a sequence of multibyte characters that
 811     begins in the initial shift state from the array pointed to by Src into
 812     a sequence of corresponding wide characters and stores not more than limit
 813     wide characters into the array pointed to by Dest.  No multibyte
 814     characters that follow a null character (which is converted into a null
 815     wide character) will be examined or converted. Each multibyte character
 816     is converted as if by a call to the mbtowc function, except that the
 817     conversion state of the mbtowc function is not affected.
 818
 819     No more than Limit elements will be modified in the array pointed to by Dest.
 820     If copying takes place between objects that overlap,
 821     the behavior is undefined.
 822
 823     @param[out]   Dest    Pointer to the array to receive the converted string.
 824     @param[in]    Src     Pointer to the string to be converted.
 825     @param[in]    Limit   Maximum number of elements to be written to Dest.
 826
 827     @return   If an invalid multibyte character is encountered, the mbstowcs
 828               function returns (size_t)(-1). Otherwise, the mbstowcs function
 829               returns the number of array elements modified, not including a
 830               terminating null wide character, if any.
 831 **/
 832 size_t  mbstowcs(wchar_t * __restrict Dest, const char * __restrict Src, size_t Limit);
 833
 834 /** Convert a wide-character string into a multibyte character string.
 835
 836     The wcstombs function converts a sequence of wide characters from the
 837     array pointed to by Src into a sequence of corresponding multibyte
 838     characters that begins in the initial shift state, and stores these
 839     multibyte characters into the array pointed to by Dest, stopping if a
 840     multibyte character would exceed the limit of Limit total bytes or if a
 841     null character is stored. Each wide character is converted as if by
 842     a call to the wctomb function, except that the conversion state of
 843     the wctomb function is not affected.
 844
 845     No more than Limit bytes will be modified in the array pointed to by Dest.
 846     If copying takes place between objects that overlap,
 847     the behavior is undefined.
 848
 849     @param[out]   Dest    Pointer to the array to receive the converted string.
 850     @param[in]    Src     Pointer to the string to be converted.
 851     @param[in]    Limit   Maximum number of bytes to be written to Dest.
 852
 853     @return   If a wide character is encountered that does not correspond to a
 854               valid multibyte character, the wcstombs function returns
 855               (size_t)(-1). Otherwise, the wcstombs function returns the number
 856               of bytes modified, not including a terminating null character,
 857               if any.
 858 **/
 859 size_t  wcstombs(char * __restrict Dest, const wchar_t * __restrict Src, size_t Limit);
 860
 861 /* ##############  Miscelaneous functions for *nix compatibility  ########## */
 862
 863 /** The realpath() function shall derive, from the pathname pointed to by
 864     file_name, an absolute pathname that names the same file, whose resolution
 865     does not involve '.', '..', or symbolic links. The generated pathname shall
 866     be stored as a null-terminated string, up to a maximum of {PATH_MAX} bytes,
 867     in the buffer pointed to by resolved_name.
 868
 869     If resolved_name is a null pointer, the behavior of realpath() is
 870     implementation-defined.
 871
 872     @param[in]      file_name         The filename to convert.
 873     @param[in,out]  resolved_name     The resultant name.
 874
 875     @retval NULL                    An error occured.
 876     @retval resolved_name.
 877 **/
 878 char * realpath(char *file_name, char *resolved_name);
 879
 880 /** The getprogname() function returns the name of the program.  If the name
 881     has not been set yet, it will return NULL.
 882
 883   @return   The getprogname function returns NULL if the program's name has not
 884             been set, otherwise it returns the name of the program.
 885 **/
 886 const char * getprogname(void);
 887
 888 /** The setprogname() function sets the name of the program.
 889
 890   @param[in]  progname    The name of the program.  This memory must be retained
 891                           by the caller until no calls to "getprogname" will be
 892                           called.
 893 **/
 894 void setprogname(const char *progname);
 895
 896 /* ###############  Functions specific to this implementation  ############# */
 897
 898 /*  Determine the number of bytes needed to represent a Wide character
 899     as a MBCS character.
 900
 901     A single wide character may convert into a one, two, three, or four byte
 902     narrow (MBCS or UTF-8) character.  The number of MBCS bytes can be determined
 903     as follows.
 904
 905     If WCS char      < 0x00000080      One Byte
 906     Else if WCS char < 0x0000D800      Two Bytes
 907     Else                               Three Bytes
 908
 909     Since UEFI only supports the Unicode Base Multilingual Plane (BMP),
 910     Four-byte characters are not supported.
 911
 912     @param[in]    InCh      Wide character to test.
 913
 914     @retval     -1      Improperly formed character
 915     @retval      0      InCh is 0x0000
 916     @retval     >0      Number of bytes needed for the MBCS character
 917 */
 918 int
 919 EFIAPI
 920 OneWcToMcLen(const wchar_t InCh);
 921
 922 /*  Determine the number of bytes needed to represent a Wide character string
 923     as a MBCS string of given maximum length.  Will optionally return the number
 924     of wide characters that would be consumed.
 925
 926     @param[in]    Src       Pointer to a wide character string.
 927     @param[in]    Limit     Maximum number of bytes the converted string may occupy.
 928     @param[out]   NumChar   Pointer to where to store the number of wide characters, or NULL.
 929
 930     @return     The number of bytes required to convert Src to MBCS,
 931                 not including the terminating NUL.  If NumChar is not NULL, the number
 932                 of characters represented by the return value will be written to
 933                 where it points.
 934 **/
 935 size_t
 936 EFIAPI
 937 EstimateWtoM(const wchar_t * Src, size_t Limit, size_t *NumChar);
 938
 939 /** Determine the number of characters in a MBCS string.
 940
 941     @param[in]    Src     The string to examine
 942
 943     @return   The number of characters represented by the MBCS string.
 944 **/
 945 size_t
 946 EFIAPI
 947 CountMbcsChars(const char *Src);
 948
 949 __END_DECLS
 950
 951 #endif  /* _STDLIB_H */