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