]>
git.proxmox.com Git - mirror_edk2.git/blob - StdLib/Include/stdlib.h
2 The header <stdlib.h> declares five types and several functions of general
3 utility, and defines several macros.
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.
10 The following macros are defined in this file:<BR>
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.
19 The following types are defined in this file:<BR>
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.
28 The following functions are declared in this file:<BR>
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);
40 ################ Integer arithmetic functions
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);
48 ################ Pseudo-random sequence generation functions
50 void srand (unsigned seed);
52 ################ Memory management functions
53 void *calloc (size_t Num, size_t Size);
55 void *malloc (size_t);
56 void *realloc (void *Ptr, size_t NewSize);
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 *));
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);
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);
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);
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);
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);
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.
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.
115 #include <sys/EfiCdefs.h>
118 /** Unsigned integer type of the result of the sizeof operator. **/
119 typedef _EFI_SIZE_T_
size_t;
126 /** Type of a wide (Unicode) character. **/
127 typedef _EFI_WCHAR_T
wchar_t;
133 /// A structure type that is the type of the value returned by the div function.
135 int quot
; /**< quotient */
136 int rem
; /**< remainder */
139 /// A structure type that is the type of the value returned by the ldiv function.
145 /// A structure type that is the type of the value returned by the lldiv function.
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.
156 #define EXIT_FAILURE 1
157 #define EXIT_SUCCESS 0
160 /** Expands to an integer constant expression that is the maximum value
161 returned by the rand function.
163 #define RAND_MAX 0x7fffffff
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.
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.
175 /** Maximum number of functions that can be registered by atexit.
177 The C standard states that the implementation shall support the
178 registration of at least 32 functions.
180 #define ATEXIT_MAX 32
184 /* ################ Communication with the environment ################## */
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.
189 Open streams with unwritten buffered data are not flushed, open
190 streams are not closed, and temporary files are not removed by abort.
192 Unsuccessful termination is returned to the host environment by means of
193 the function call, raise(SIGABRT).
197 void abort(void) __noreturn
;
199 /** The atexit function registers the function pointed to by func, to be
200 called without arguments at normal program termination.
202 The implementation supports the registration of up to 32 functions.
204 @param[in] Handler Pointer to the function to register as one of the
205 routines to call at application exit time.
207 @return The atexit function returns zero if the registration succeeds,
210 int atexit(void (*Handler
)(void));
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.
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.
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
227 Finally, control is returned to the host environment.
229 @param[in] status A value to be returned when the application exits.
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.
235 void exit(int status
) __noreturn
;
237 /** The _Exit function causes normal program termination to occur and control
238 to be returned to the host environment.
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.
245 The status returned to the host environment is determined in the same way
246 as for the exit function.
248 @param[in] status A value to be returned when the application exits.
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.
254 void _Exit(int status
) __noreturn
;
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.
261 @param[in] name Pointer to a string naming the environment variable to retrieve.
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.
269 char *getenv(const char *name
);
271 /** Add or update a variable in the environment list.
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.
277 @retval 0 Returns 0 upon success.
278 @retval -1 Returns -1 upon failure, sets errno with more information.
282 register const char * name
,
283 register const char * value
,
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.
294 @param[in] string Pointer to the command string to be executed.
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.
301 int system(const char *string
);
304 /* ################ Integer arithmetic functions ######################## */
306 /** Computes the absolute value of an integer j.
308 @param[in] j The value to find the absolute value of.
310 @return The absolute value of j.
314 /** Computes the absolute value of a long integer j.
316 @param[in] j The value to find the absolute value of.
318 @return The absolute value of j.
322 /** Computes the absolute value of a long long integer j.
324 @param[in] j The value to find the absolute value of.
326 @return The absolute value of j.
331 /** Computes numer / denom and numer % denom in a single operation.
333 @param[in] numer The numerator for the division.
334 @param[in] denom The denominator for the division.
336 @return Returns a structure of type div_t, comprising both the
337 quotient and the remainder.
339 div_t div(int numer
, int denom
);
341 /** Computes numer / denom and numer % denom in a single operation.
343 @param[in] numer The numerator for the division.
344 @param[in] denom The denominator for the division.
346 @return Returns a structure of type ldiv_t, comprising both the
347 quotient and the remainder.
349 ldiv_t ldiv(long numer
, long denom
);
351 /** Computes numer / denom and numer % denom in a single operation.
353 @param[in] numer The numerator for the division.
354 @param[in] denom The denominator for the division.
356 @return Returns a structure of type lldiv_t, comprising both the
357 quotient and the remainder.
359 lldiv_t
lldiv(long long numer
, long long denom
);
361 /* ############ Integer Numeric conversion functions #################### */
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
366 - atoi: (int)strtol(nptr, (char **)NULL, 10)
368 @param[in] nptr Pointer to the string to be converted.
370 @return The atoi function returns the converted value.
372 int atoi(const char *nptr
);
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
377 - atol: strtol(nptr, (char **)NULL, 10)
379 @param[in] nptr Pointer to the string to be converted.
381 @return The atol function returns the converted value.
383 long atol(const char *nptr
);
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
388 - atoll: strtoll(nptr, (char **)NULL, 10)
390 @param[in] nptr Pointer to the string to be converted.
392 @return The atoll function returns the converted value.
395 atoll(const char *nptr
);
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.
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.
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.
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
436 In other than the "C" locale, additional locale-specific subject sequence
437 forms may be accepted.
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.
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.
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
455 long strtol(const char * __restrict nptr
, char ** __restrict endptr
, int base
);
457 /** The strtoul function converts the initial portion of the string pointed to
458 by nptr to unsigned long int representation.
460 See the description for strtol for more information.
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.
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.
472 strtoul(const char * __restrict nptr
, char ** __restrict endptr
, int base
);
474 /** The strtoll function converts the initial portion of the string pointed to
475 by nptr to long long int representation.
477 See the description for strtol for more information.
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.
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.
490 strtoll(const char * __restrict nptr
, char ** __restrict endptr
, int base
);
492 /** The strtoull function converts the initial portion of the string pointed to
493 by nptr to unsigned long long int representation.
495 See the description for strtol for more information.
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.
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.
507 strtoull(const char * __restrict nptr
, char ** __restrict endptr
, int base
);
509 /* ######### Floating-point Numeric conversion functions ################ */
511 /** Convert the initial part of a string to double representation.
513 @param[in] nptr Pointer to the string to be converted.
515 @return The floating-point value representing the string nptr.
517 double atof(const char *nptr
);
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.
531 /** Convert a string to a double and point to the character after the last converted.
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.
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.
543 double strtod(const char * __restrict nptr
, char ** __restrict endptr
);
545 /** Convert a string to a float and point to the character after the last converted.
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.
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.
557 float strtof(const char * __restrict nptr
, char ** __restrict endptr
);
559 /** Convert a string to a long double and point to the character after the last converted.
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.
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.
572 strtold(const char * __restrict nptr
, char ** __restrict endptr
);
575 /* ################ Pseudo-random sequence generation functions ######### */
577 /** The rand function computes a sequence of pseudo-random integers in the
580 @return The rand function returns a pseudo-random integer.
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.
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.
592 @param[in] seed The value used to "seed" the random number generator with.
594 void srand(unsigned seed
);
596 /* ################ Memory management functions ######################### */
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.
601 @param[in] Num The number of objects to allocate space for.
602 @param[in] Size The size, in bytes, of each object.
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.
608 void *calloc(size_t Num
, size_t Size
);
610 /** The free function causes the space pointed to by Ptr to be deallocated,
611 that is, made available for further allocation.
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.
618 @param Ptr Pointer to a previously allocated region of memory to be freed.
620 void free(void *Ptr
);
622 /** The malloc function allocates space for an object whose size is specified
623 by size and whose value is indeterminate.
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.
629 @param Size Size, in bytes, of the region to allocate.
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.
638 void *malloc(size_t Size
);
640 /** The realloc function changes the size of the object pointed to by Ptr to
641 the size specified by NewSize.
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.
647 If Ptr is a null pointer, the realloc function behaves like the malloc
648 function for the specified size.
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.
654 If the space cannot be allocated, the object pointed to by Ptr is unchanged.
656 If NewSize is zero and Ptr is not a null pointer, the object it points to
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.
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.
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.
671 void *realloc(void *Ptr
, size_t NewSize
);
673 /* ################ Searching and Sorting utilities ##################### */
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
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,
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.
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.
699 void *bsearch( const void *Key
, const void *Base
,
700 size_t Nmemb
, size_t Size
,
701 int (*Compar
)(const void *, const void *)
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.
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
714 If two elements compare as equal, their order in the resulting sorted array
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.
722 void qsort( void *base
, size_t nmemb
, size_t size
,
723 int (*compar
)(const void *, const void *));
725 /* ################ Multibyte/wide character conversion functions ####### */
727 /** Determine the number of bytes comprising a multibyte character.
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);
734 @param[in] S NULL to query whether multibyte characters have
735 state-dependent encodings. Otherwise, points to a
737 @param[in] N The maximum number of bytes in a multibyte character.
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).
748 int mblen(const char *S
, size_t N
);
750 /** Convert a multibyte character into a wide character.
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.
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.
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).
774 In no case will the value returned be greater than N or the value
775 of the MB_CUR_MAX macro.
777 int mbtowc(wchar_t * __restrict Pwc
, const char * __restrict S
, size_t N
);
779 /** Convert a wide character into a multibyte character.
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.
790 @param[out] S Pointer to the object to receive the converted multibyte character.
791 @param[in] WC Wide character to be converted.
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.
801 In no case will the value returned be greater than the value of
802 the MB_CUR_MAX macro.
804 int wctomb(char *S
, wchar_t WC
);
806 /* ################ Multibyte/wide string conversion functions ########## */
808 /** Convert a multibyte character string into a wide-character string.
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.
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.
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.
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.
832 size_t mbstowcs(wchar_t * __restrict Dest
, const char * __restrict Src
, size_t Limit
);
834 /** Convert a wide-character string into a multibyte character string.
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.
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.
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.
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,
859 size_t wcstombs(char * __restrict Dest
, const wchar_t * __restrict Src
, size_t Limit
);
861 /* ############## Miscelaneous functions for *nix compatibility ########## */
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.
869 If resolved_name is a null pointer, the behavior of realpath() is
870 implementation-defined.
872 @param[in] file_name The filename to convert.
873 @param[in,out] resolved_name The resultant name.
875 @retval NULL An error occured.
876 @retval resolved_name.
878 char * realpath(char *file_name
, char *resolved_name
);
880 /** The getprogname() function returns the name of the program. If the name
881 has not been set yet, it will return NULL.
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.
886 const char * getprogname(void);
888 /** The setprogname() function sets the name of the program.
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
894 void setprogname(const char *progname
);
896 /* ############### Functions specific to this implementation ############# */
898 /* Determine the number of bytes needed to represent a Wide character
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
905 If WCS char < 0x00000080 One Byte
906 Else if WCS char < 0x0000D800 Two Bytes
909 Since UEFI only supports the Unicode Base Multilingual Plane (BMP),
910 Four-byte characters are not supported.
912 @param[in] InCh Wide character to test.
914 @retval -1 Improperly formed character
915 @retval 0 InCh is 0x0000
916 @retval >0 Number of bytes needed for the MBCS character
920 OneWcToMcLen(const wchar_t InCh
);
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.
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.
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
937 EstimateWtoM(const wchar_t * Src
, size_t Limit
, size_t *NumChar
);
939 /** Determine the number of characters in a MBCS string.
941 @param[in] Src The string to examine
943 @return The number of characters represented by the MBCS string.
947 CountMbcsChars(const char *Src
);
951 #endif /* _STDLIB_H */