The header <stdlib.h> declares five types and several functions of general\r
utility, and defines several macros.\r
\r
- Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>\r
+ The files stddef.h and stdlib.h are "catch all" headers for definitions and declarations\r
+ that don't fit well in the other headers. There are two separate header files because\r
+ the contents of <stddef.h> are valid in both freestanding and hosted environment, while the\r
+ header <stdlib.h> contains elements that are only valid in a hosted environment.\r
+\r
+ The following macros are defined in this file:<BR>\r
+ @verbatim\r
+ EXIT_FAILURE An expression indicating application failure, used as an argument to exit().\r
+ EXIT_SUCCESS An expression indicating application success, used as an argument to exit().\r
+ RAND_MAX The maximum value returned by the rand function.\r
+ MB_CUR_MAX Maximum number of bytes in a multibyte character for the current locale.\r
+ ATEXIT_MAX Maximum number of routines that may be registered by the atexit function.\r
+ @endverbatim\r
+\r
+ The following types are defined in this file:<BR>\r
+ @verbatim\r
+ size_t Unsigned integer type of the result of the sizeof operator.\r
+ wchar_t The type of a wide character.\r
+ div_t Type of the value returned by the div function.\r
+ ldiv_t Type of the value returned by the ldiv function.\r
+ lldiv_t Type of the value returned by the lldiv function.\r
+ @endverbatim\r
+\r
+ The following functions are declared in this file:<BR>\r
+ @verbatim\r
+ ################ Communication with the environment\r
+ void abort (void) __noreturn;\r
+ int atexit (void (*)(void));\r
+ void exit (int status) __noreturn;\r
+ void _Exit (int status) __noreturn;\r
+ char *getenv (const char *name);\r
+ int setenv (register const char * name,\r
+ register const char * value, int rewrite);\r
+ int system (const char *string);\r
+\r
+ ################ Integer arithmetic functions\r
+ int abs (int j);\r
+ long labs (long j);\r
+ long long llabs (long long j);\r
+ div_t div (int numer, int denom);\r
+ ldiv_t ldiv (long numer, long denom);\r
+ lldiv_t lldiv (long long numer, long long denom);\r
+\r
+ ################ Pseudo-random sequence generation functions\r
+ int rand (void);\r
+ void srand (unsigned seed);\r
+\r
+ ################ Memory management functions\r
+ void *calloc (size_t Num, size_t Size);\r
+ void free (void *);\r
+ void *malloc (size_t);\r
+ void *realloc (void *Ptr, size_t NewSize);\r
+\r
+ ################ Searching and Sorting utilities\r
+ void *bsearch (const void *key, const void *base0,\r
+ size_t nmemb, size_t size,\r
+ int (*compar)(const void *, const void *));\r
+ void qsort (void *base, size_t nmemb, size_t size,\r
+ int (*compar)(const void *, const void *));\r
+\r
+ ################ Multibyte/wide character conversion functions\r
+ int mblen (const char *, size_t);\r
+ int mbtowc (wchar_t * __restrict, const char * __restrict, size_t);\r
+ int wctomb (char *, wchar_t);\r
+\r
+ ################ Multibyte/wide string conversion functions\r
+ size_t mbstowcs (wchar_t * __restrict dest,\r
+ const char * __restrict src, size_t limit);\r
+ size_t wcstombs (char * __restrict dest,\r
+ const wchar_t * __restrict src, size_t limit);\r
+\r
+ ################ Miscelaneous functions for *nix compatibility\r
+ char *realpath (char *file_name, char *resolved_name);\r
+ const char *getprogname (void);\r
+ void setprogname (const char *progname);\r
+\r
+ ############ Integer Numeric conversion functions\r
+ int atoi (const char *nptr);\r
+ long atol (const char *nptr);\r
+ long long atoll (const char *nptr);\r
+ long strtol (const char * __restrict nptr,\r
+ char ** __restrict endptr, int base);\r
+ unsigned long strtoul (const char * __restrict nptr,\r
+ char ** __restrict endptr, int base);\r
+ long long strtoll (const char * __restrict nptr,\r
+ char ** __restrict endptr, int base);\r
+ unsigned long long strtoull (const char * __restrict nptr,\r
+ char ** __restrict endptr, int base);\r
+\r
+ ######### Floating-point Numeric conversion functions\r
+ double atof (const char *);\r
+ double strtod (const char * __restrict nptr,\r
+ char ** __restrict endptr);\r
+ float strtof (const char * __restrict nptr,\r
+ char ** __restrict endptr);\r
+ long double strtold (const char * __restrict nptr,\r
+ char ** __restrict endptr);\r
+ @endverbatim\r
+\r
+ Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials are licensed and made available under\r
the terms and conditions of the BSD License that accompanies this distribution.\r
The full text of the license may be found at\r
- http://opensource.org/licenses/bsd-license.php.\r
+ http://opensource.org/licenses/bsd-license.\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
-\r
**/\r
#ifndef _STDLIB_H\r
#define _STDLIB_H\r
#include <sys/EfiCdefs.h>\r
\r
#ifdef _EFI_SIZE_T_\r
+ /** Unsigned integer type of the result of the sizeof operator. **/\r
typedef _EFI_SIZE_T_ size_t;\r
#undef _EFI_SIZE_T_\r
#undef _BSD_SIZE_T_\r
\r
#ifndef __cplusplus\r
#ifdef _EFI_WCHAR_T\r
+ /** Type of a wide (Unicode) character. **/\r
typedef _EFI_WCHAR_T wchar_t;\r
#undef _EFI_WCHAR_T\r
#undef _BSD_WCHAR_T_\r
\r
/// A structure type that is the type of the value returned by the div function.\r
typedef struct {\r
- int quot; /* quotient */\r
- int rem; /* remainder */\r
+ int quot; /**< quotient */\r
+ int rem; /**< remainder */\r
} div_t;\r
\r
/// A structure type that is the type of the value returned by the ldiv function.\r
long long rem;\r
} lldiv_t;\r
\r
-/** Expand to integer constant expressions that can be used as the argument to\r
+/** @{\r
+ Expand to integer constant expressions that can be used as the argument to\r
the exit function to return unsuccessful or successful termination status,\r
respectively, to the host environment.\r
**/\r
#define EXIT_FAILURE 1\r
#define EXIT_SUCCESS 0\r
+/*@}*/\r
\r
/** Expands to an integer constant expression that is the maximum value\r
returned by the rand function.\r
-\r
- The value of the RAND_MAX macro shall be at least 32767.\r
**/\r
#define RAND_MAX 0x7fffffff\r
\r
maximum number of bytes in a multibyte character for the extended character\r
set specified by the current locale (category LC_CTYPE), which is never\r
greater than MB_LEN_MAX.\r
+\r
+ Since UEFI only supports the Unicode Base Multilingual Plane (BMP),\r
+ correctly formed characters will only produce 1, 2, or 3-byte UTF-8 characters.\r
**/\r
-#define MB_CUR_MAX 2\r
+#define MB_CUR_MAX 3\r
\r
/** Maximum number of functions that can be registered by atexit.\r
\r
\r
@sa signal.h\r
**/\r
-void abort(void);\r
+void abort(void) __noreturn;\r
\r
/** The atexit function registers the function pointed to by func, to be\r
called without arguments at normal program termination.\r
\r
The implementation supports the registration of up to 32 functions.\r
\r
+ @param[in] Handler Pointer to the function to register as one of the\r
+ routines to call at application exit time.\r
+\r
@return The atexit function returns zero if the registration succeeds,\r
nonzero if it fails.\r
**/\r
-int atexit(void (*)(void));\r
+int atexit(void (*Handler)(void));\r
\r
/** The exit function causes normal program termination to occur. If more than\r
one call to the exit function is executed by a program,\r
streams are closed, and all files created by the tmpfile function\r
are removed.\r
\r
- Finally, control is returned to the host environment. If the value of\r
- status is zero, or EXIT_SUCCESS, status is returned unchanged. If the value\r
- of status is EXIT_FAILURE, EAPPLICATION is returned.\r
- Otherwise, status is returned unchanged.\r
+ Finally, control is returned to the host environment.\r
+\r
+ @param[in] status A value to be returned when the application exits.\r
+\r
+ @return If the value of status is zero, or EXIT_SUCCESS, status is\r
+ returned unchanged. If the value of status is EXIT_FAILURE,\r
+ RETURN_ABORTED is returned. Otherwise, status is returned unchanged.\r
**/\r
void exit(int status) __noreturn;\r
\r
\r
The status returned to the host environment is determined in the same way\r
as for the exit function.\r
+\r
+ @param[in] status A value to be returned when the application exits.\r
+\r
+ @return If the value of status is zero, or EXIT_SUCCESS, status is\r
+ returned unchanged. If the value of status is EXIT_FAILURE,\r
+ RETURN_ABORTED is returned. Otherwise, status is returned unchanged.\r
**/\r
void _Exit(int status) __noreturn;\r
\r
set of environment names and the method for altering the environment list\r
are determined by the underlying UEFI Shell implementation.\r
\r
+ @param[in] name Pointer to a string naming the environment variable to retrieve.\r
+\r
@return The getenv function returns a pointer to a string associated with\r
the matched list member. The string pointed to shall not be\r
modified by the program, but may be overwritten by a subsequent\r
**/\r
char *getenv(const char *name);\r
\r
+/** Add or update a variable in the environment list.\r
+\r
+ @param[in] name Address of a zero terminated name string.\r
+ @param[in] value Address of a zero terminated value string.\r
+ @param[in] rewrite TRUE allows overwriting existing values.\r
+\r
+ @retval 0 Returns 0 upon success.\r
+ @retval -1 Returns -1 upon failure, sets errno with more information.\r
+**/\r
+int\r
+setenv (\r
+ register const char * name,\r
+ register const char * value,\r
+ int rewrite\r
+ );\r
+\r
/** If string is a null pointer, the system function determines whether the\r
host environment has a command processor. If string is not a null pointer,\r
the system function passes the string pointed to by string to that command\r
document; this might then cause the program calling system to behave in a\r
non-conforming manner or to terminate.\r
\r
+ @param[in] string Pointer to the command string to be executed.\r
+\r
@return If the argument is a null pointer, the system function returns\r
nonzero only if a command processor is available. If the argument\r
is not a null pointer, and the system function does return, it\r
\r
/** Computes the absolute value of an integer j.\r
\r
+ @param[in] j The value to find the absolute value of.\r
+\r
@return The absolute value of j.\r
**/\r
int abs(int j);\r
\r
-/** Computes the absolute value of an integer j.\r
+/** Computes the absolute value of a long integer j.\r
+\r
+ @param[in] j The value to find the absolute value of.\r
\r
@return The absolute value of j.\r
**/\r
long labs(long j);\r
\r
-/** Computes the absolute value of an integer j.\r
+/** Computes the absolute value of a long long integer j.\r
+\r
+ @param[in] j The value to find the absolute value of.\r
\r
@return The absolute value of j.\r
**/\r
\r
/** Computes numer / denom and numer % denom in a single operation.\r
\r
+ @param[in] numer The numerator for the division.\r
+ @param[in] denom The denominator for the division.\r
+\r
@return Returns a structure of type div_t, comprising both the\r
quotient and the remainder.\r
**/\r
\r
/** Computes numer / denom and numer % denom in a single operation.\r
\r
+ @param[in] numer The numerator for the division.\r
+ @param[in] denom The denominator for the division.\r
+\r
@return Returns a structure of type ldiv_t, comprising both the\r
quotient and the remainder.\r
**/\r
\r
/** Computes numer / denom and numer % denom in a single operation.\r
\r
+ @param[in] numer The numerator for the division.\r
+ @param[in] denom The denominator for the division.\r
+\r
@return Returns a structure of type lldiv_t, comprising both the\r
quotient and the remainder.\r
**/\r
equivalent to:\r
- atoi: (int)strtol(nptr, (char **)NULL, 10)\r
\r
- @return The atoi function returns the converted value.\r
+ @param[in] nptr Pointer to the string to be converted.\r
+\r
+ @return The atoi function returns the converted value.\r
**/\r
int atoi(const char *nptr);\r
\r
equivalent to:\r
- atol: strtol(nptr, (char **)NULL, 10)\r
\r
- @return The atol function returns the converted value.\r
+ @param[in] nptr Pointer to the string to be converted.\r
+\r
+ @return The atol function returns the converted value.\r
**/\r
long atol(const char *nptr);\r
\r
is equivalent to:\r
- atoll: strtoll(nptr, (char **)NULL, 10)\r
\r
- @return The atoll function returns the converted value.\r
+ @param[in] nptr Pointer to the string to be converted.\r
+\r
+ @return The atoll function returns the converted value.\r
**/\r
long long\r
atoll(const char *nptr);\r
integer, and return the result.\r
\r
If the value of base is zero, the expected form of the subject sequence is\r
- that of an integer constant as described in 6.4.4.1, optionally preceded\r
+ that of an integer constant, optionally preceded\r
by a plus or minus sign, but not including an integer suffix. If the value\r
of base is between 2 and 36 (inclusive), the expected form of the subject\r
sequence is a sequence of letters and digits representing an integer with\r
conversion is performed; the value of nptr is stored in the object pointed\r
to by endptr, provided that endptr is not a null pointer.\r
\r
- @return The strtol, strtoll, strtoul, and strtoull functions return the\r
- converted value, if any. If no conversion could be performed, zero\r
- is returned. If the correct value is outside the range of\r
- representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,\r
- ULONG_MAX, or ULLONG_MAX is returned (according to the return type\r
- and sign of the value, if any), and the value of the macro ERANGE\r
- is stored in errno.\r
+ @param[in] nptr Pointer to the string to be converted.\r
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.\r
+ @param[in] base The base, 0 to 36, of the number represented by the input string.\r
+\r
+ @return The strtol, strtoll, strtoul, and strtoull functions return the\r
+ converted value, if any. If no conversion could be performed, zero\r
+ is returned. If the correct value is outside the range of\r
+ representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,\r
+ ULONG_MAX, or ULLONG_MAX is returned (according to the return type\r
+ and sign of the value, if any), and the value of the macro ERANGE\r
+ is stored in errno.\r
**/\r
long strtol(const char * __restrict nptr, char ** __restrict endptr, int base);\r
\r
\r
See the description for strtol for more information.\r
\r
- @return The strtoul function returns the converted value, if any. If no\r
- conversion could be performed, zero is returned. If the correct\r
- value is outside the range of representable values, ULONG_MAX is\r
- returned and the value of the macro ERANGE is stored in errno.\r
+ @param[in] nptr Pointer to the string to be converted.\r
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.\r
+ @param[in] base The base, 0 to 36, of the number represented by the input string.\r
+\r
+ @return The strtoul function returns the converted value, if any. If no\r
+ conversion could be performed, zero is returned. If the correct\r
+ value is outside the range of representable values, ULONG_MAX is\r
+ returned and the value of the macro ERANGE is stored in errno.\r
**/\r
unsigned long\r
strtoul(const char * __restrict nptr, char ** __restrict endptr, int base);\r
\r
See the description for strtol for more information.\r
\r
- @return The strtoll function returns the converted value, if any. If no\r
- conversion could be performed, zero is returned. If the correct\r
- value is outside the range of representable values, LLONG_MIN or\r
- LLONG_MAX is returned (according to the sign of the value, if any),\r
- and the value of the macro ERANGE is stored in errno.\r
+ @param[in] nptr Pointer to the string to be converted.\r
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.\r
+ @param[in] base The base, 0 to 36, of the number represented by the input string.\r
+\r
+ @return The strtoll function returns the converted value, if any. If no\r
+ conversion could be performed, zero is returned. If the correct\r
+ value is outside the range of representable values, LLONG_MIN or\r
+ LLONG_MAX is returned (according to the sign of the value, if any),\r
+ and the value of the macro ERANGE is stored in errno.\r
**/\r
long long\r
strtoll(const char * __restrict nptr, char ** __restrict endptr, int base);\r
\r
See the description for strtol for more information.\r
\r
- @return The strtoull function returns the converted value, if any. If no\r
- conversion could be performed, zero is returned. If the correct\r
- value is outside the range of representable values, ULLONG_MAX is\r
- returned and the value of the macro ERANGE is stored in errno.\r
+ @param[in] nptr Pointer to the string to be converted.\r
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.\r
+ @param[in] base The base, 0 to 36, of the number represented by the input string.\r
+\r
+ @return The strtoull function returns the converted value, if any. If no\r
+ conversion could be performed, zero is returned. If the correct\r
+ value is outside the range of representable values, ULLONG_MAX is\r
+ returned and the value of the macro ERANGE is stored in errno.\r
**/\r
unsigned long long\r
strtoull(const char * __restrict nptr, char ** __restrict endptr, int base);\r
\r
/* ######### Floating-point Numeric conversion functions ################ */\r
\r
-/**\r
+/** Convert the initial part of a string to double representation.\r
+\r
+ @param[in] nptr Pointer to the string to be converted.\r
\r
- @return\r
+ @return The floating-point value representing the string nptr.\r
**/\r
-double atof(const char *);\r
+double atof(const char *nptr);\r
\r
-/**\r
+/** @{\r
+ The strtod, strtof, and strtold functions convert the initial portion of\r
+ the string pointed to by nptr to double, float, and long double\r
+ representation, respectively. First, they decompose the input string into\r
+ three parts: an initial, possibly empty, sequence of white-space characters\r
+ (as specified by the isspace function), a subject sequence resembling a\r
+ floating-point constant or representing an infinity or NaN; and a final\r
+ string of one or more unrecognized characters, including the terminating\r
+ null character of the input string. Then, they attempt to convert the\r
+ subject sequence to a floating-point number, and return the result.\r
+*/\r
\r
- @return\r
+/** Convert a string to a double and point to the character after the last converted.\r
+\r
+ @param[in] nptr Pointer to the string to be converted.\r
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.\r
+\r
+ @return A floating-point value representing the string nptr.\r
+ A pointer to the final string is stored in the object pointed to\r
+ by endptr, provided that endptr is not a null pointer.\r
+ If the subject sequence is empty or does not have the expected\r
+ form, no conversion is performed; the value of nptr is stored in\r
+ the object pointed to by endptr, provided that endptr is not a null pointer.\r
**/\r
double strtod(const char * __restrict nptr, char ** __restrict endptr);\r
\r
-/**\r
+/** Convert a string to a float and point to the character after the last converted.\r
\r
- @return\r
+ @param[in] nptr Pointer to the string to be converted.\r
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.\r
+\r
+ @return A floating-point value representing the string nptr.\r
+ A pointer to the final string is stored in the object pointed to\r
+ by endptr, provided that endptr is not a null pointer.\r
+ If the subject sequence is empty or does not have the expected\r
+ form, no conversion is performed; the value of nptr is stored in\r
+ the object pointed to by endptr, provided that endptr is not a null pointer.\r
**/\r
float strtof(const char * __restrict nptr, char ** __restrict endptr);\r
\r
-/**\r
+/** Convert a string to a long double and point to the character after the last converted.\r
+\r
+ @param[in] nptr Pointer to the string to be converted.\r
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.\r
\r
- @return\r
+ @return A floating-point value representing the string nptr.\r
+ A pointer to the final string is stored in the object pointed to\r
+ by endptr, provided that endptr is not a null pointer.\r
+ If the subject sequence is empty or does not have the expected\r
+ form, no conversion is performed; the value of nptr is stored in\r
+ the object pointed to by endptr, provided that endptr is not a null pointer.\r
**/\r
long double\r
strtold(const char * __restrict nptr, char ** __restrict endptr);\r
+/*@}*/\r
\r
/* ################ Pseudo-random sequence generation functions ######### */\r
\r
pseudo-random numbers shall be repeated. If rand is called before any calls\r
to srand have been made, the same sequence shall be generated as when srand\r
is first called with a seed value of 1.\r
+\r
+ @param[in] seed The value used to "seed" the random number generator with.\r
**/\r
void srand(unsigned seed);\r
\r
/** The calloc function allocates space for an array of Num objects, each of\r
whose size is Size. The space is initialized to all bits zero.\r
\r
+ @param[in] Num The number of objects to allocate space for.\r
+ @param[in] Size The size, in bytes, of each object.\r
+\r
@return NULL is returned if the space could not be allocated and errno\r
contains the cause. Otherwise, a pointer to an 8-byte aligned\r
region of the requested size is returned.\r
realloc, the behavior is undefined.\r
\r
@param Ptr Pointer to a previously allocated region of memory to be freed.\r
-\r
**/\r
-void free(void *);\r
+void free(void *Ptr);\r
\r
/** The malloc function allocates space for an object whose size is specified\r
by size and whose value is indeterminate.\r
region of memory that is 8-byte aligned and of the specified size. The\r
region is allocated with type EfiLoaderData.\r
\r
- @param size Size, in bytes, of the region to allocate.\r
+ @param Size Size, in bytes, of the region to allocate.\r
\r
@return NULL is returned if the space could not be allocated and errno\r
contains the cause. Otherwise, a pointer to an 8-byte aligned\r
- EINVAL: Requested Size is zero.\r
- ENOMEM: Memory could not be allocated.\r
**/\r
-void *malloc(size_t);\r
+void *malloc(size_t Size);\r
\r
/** The realloc function changes the size of the object pointed to by Ptr to\r
the size specified by NewSize.\r
\r
/* ################ Searching and Sorting utilities ##################### */\r
\r
-/** The bsearch function searches an array of nmemb objects, the initial\r
- element of which is pointed to by base, for an element that matches the\r
- object pointed to by key. The size of each element of the array is\r
- specified by size.\r
+/** The bsearch function searches an array of Nmemb objects, the initial\r
+ element of which is pointed to by Base, for an element that matches the\r
+ object pointed to by Key. The size of each element of the array is\r
+ specified by Size.\r
\r
- The comparison function pointed to by compar is called with two arguments\r
- that point to the key object and to an array element, in that order. The\r
+ The comparison function pointed to by Compar is called with two arguments\r
+ that point to the Key object and to an array element, in that order. The\r
function returns an integer less than, equal to, or greater than zero if\r
- the key object is considered, respectively, to be less than, to match, or\r
+ the Key object is considered, respectively, to be less than, to match, or\r
to be greater than the array element. The array consists of: all the\r
elements that compare less than, all the elements that compare equal to,\r
and all the elements that compare greater than the key object,\r
in that order.\r
\r
- @return The bsearch function returns a pointer to a matching element of the\r
- array, or a null pointer if no match is found. If two elements\r
- compare as equal, which element is matched is unspecified.\r
+ @param[in] Key Pointer to the object to search for.\r
+ @param[in] Base Pointer to the first element of an array to search.\r
+ @param[in] Nmemb Number of objects in the search array.\r
+ @param[in] Size The size of each object in the search array.\r
+ @param[in] Compar Pointer to the function used to compare two objects.\r
+\r
+ @return The bsearch function returns a pointer to a matching element of the\r
+ array, or a null pointer if no match is found. If two elements\r
+ compare as equal, which element is matched is unspecified.\r
**/\r
-void *\r
-bsearch( const void *key, const void *base0,\r
- size_t nmemb, size_t size,\r
- int (*compar)(const void *, const void *)\r
-);\r
+void *bsearch( const void *Key, const void *Base,\r
+ size_t Nmemb, size_t Size,\r
+ int (*Compar)(const void *, const void *)\r
+ );\r
\r
-/** The qsort function sorts an array of nmemb objects, the initial element of\r
- which is pointed to by base. The size of each object is specified by size.\r
+/** The qsort function sorts an array of Nmemb objects, the initial element of\r
+ which is pointed to by Base. The size of each object is specified by Size.\r
\r
The contents of the array are sorted into ascending order according to a\r
- comparison function pointed to by compar, which is called with two\r
+ comparison function pointed to by Compar, which is called with two\r
arguments that point to the objects being compared. The function shall\r
return an integer less than, equal to, or greater than zero if the first\r
argument is considered to be respectively less than, equal to, or greater\r
\r
If two elements compare as equal, their order in the resulting sorted array\r
is unspecified.\r
+\r
+ @param[in,out] Base Pointer to the first element of an array to sort.\r
+ @param[in] Nmemb Number of objects in the array.\r
+ @param[in] Size The size of each object in the array.\r
+ @param[in] Compar Pointer to the function used to compare two objects.\r
**/\r
-void qsort( void *base, size_t nmemb, size_t size,\r
- int (*compar)(const void *, const void *));\r
+void qsort( void *base, size_t nmemb, size_t size,\r
+ int (*compar)(const void *, const void *));\r
\r
/* ################ Multibyte/wide character conversion functions ####### */\r
\r
-/**\r
+/** Determine the number of bytes comprising a multibyte character.\r
+\r
+ If S is not a null pointer, the mblen function determines the number of bytes\r
+ contained in the multibyte character pointed to by S. Except that the\r
+ conversion state of the mbtowc function is not affected, it is equivalent to\r
+ mbtowc((wchar_t *)0, S, N);\r
+\r
+ @param[in] S NULL to query whether multibyte characters have\r
+ state-dependent encodings. Otherwise, points to a\r
+ multibyte character.\r
+ @param[in] N The maximum number of bytes in a multibyte character.\r
+\r
+ @return If S is a null pointer, the mblen function returns a nonzero or\r
+ zero value, if multibyte character encodings, respectively, do\r
+ or do not have state-dependent encodings. If S is not a null\r
+ pointer, the mblen function either returns 0 (if S points to the\r
+ null character), or returns the number of bytes that are contained\r
+ in the multibyte character (if the next N or fewer bytes form a\r
+ valid multibyte character), or returns -1 (if they do not form a\r
+ valid multibyte character).\r
+**/\r
+int mblen(const char *S, size_t N);\r
+\r
+/** Convert a multibyte character into a wide character.\r
+\r
+ If S is not a null pointer, the mbtowc function inspects at most N bytes\r
+ beginning with the byte pointed to by S to determine the number of bytes\r
+ needed to complete the next multibyte character (including any shift\r
+ sequences). If the function determines that the next multibyte character\r
+ is complete and valid, it determines the value of the corresponding wide\r
+ character and then, if Pwc is not a null pointer, stores that value in\r
+ the object pointed to by Pwc. If the corresponding wide character is the\r
+ null wide character, the function is left in the initial conversion state.\r
+\r
+ @param[out] Pwc Pointer to a wide-character object to receive the converted character.\r
+ @param[in] S Pointer to a multibyte character to convert.\r
+ @param[in] N Maximum number of bytes in a multibyte character.\r
+\r
+ @return If S is a null pointer, the mbtowc function returns a nonzero or\r
+ zero value, if multibyte character encodings, respectively, do\r
+ or do not have state-dependent encodings. If S is not a null\r
+ pointer, the mbtowc function either returns 0 (if S points to\r
+ the null character), or returns the number of bytes that are\r
+ contained in the converted multibyte character (if the next N or\r
+ fewer bytes form a valid multibyte character), or returns -1\r
+ (if they do not form a valid multibyte character).\r
+\r
+ In no case will the value returned be greater than N or the value\r
+ of the MB_CUR_MAX macro.\r
+**/\r
+int mbtowc(wchar_t * __restrict Pwc, const char * __restrict S, size_t N);\r
+\r
+/** Convert a wide character into a multibyte character.\r
+\r
+ The wctomb function determines the number of bytes needed to represent the\r
+ multibyte character corresponding to the wide character given by WC\r
+ (including any shift sequences), and stores the multibyte character\r
+ representation in the array whose first element is pointed to by S (if S is\r
+ not a null pointer). At most MB_CUR_MAX characters are stored. If WC is a\r
+ null wide character, a null byte is stored, preceded by any shift sequence\r
+ needed to restore the initial shift state, and the function is left in the\r
+ initial conversion state.\r
+\r
+ @param[out] S Pointer to the object to receive the converted multibyte character.\r
+ @param[in] WC Wide character to be converted.\r
+\r
+ @return If S is a null pointer, the wctomb function returns a nonzero or\r
+ zero value, if multibyte character encodings, respectively, do or\r
+ do not have state-dependent encodings. If S is not a null pointer,\r
+ the wctomb function returns -1 if the value of WC does not\r
+ correspond to a valid multibyte character, or returns the number\r
+ of bytes that are contained in the multibyte character\r
+ corresponding to the value of WC.\r
+\r
+ In no case will the value returned be greater than the value of\r
+ the MB_CUR_MAX macro.\r
+**/\r
+int wctomb(char *S, wchar_t WC);\r
+\r
+/* ################ Multibyte/wide string conversion functions ########## */\r
+\r
+/** Convert a multibyte character string into a wide-character string.\r
+\r
+ The mbstowcs function converts a sequence of multibyte characters that\r
+ begins in the initial shift state from the array pointed to by Src into\r
+ a sequence of corresponding wide characters and stores not more than limit\r
+ wide characters into the array pointed to by Dest. No multibyte\r
+ characters that follow a null character (which is converted into a null\r
+ wide character) will be examined or converted. Each multibyte character\r
+ is converted as if by a call to the mbtowc function, except that the\r
+ conversion state of the mbtowc function is not affected.\r
+\r
+ No more than Limit elements will be modified in the array pointed to by Dest.\r
+ If copying takes place between objects that overlap,\r
+ the behavior is undefined.\r
+\r
+ @param[out] Dest Pointer to the array to receive the converted string.\r
+ @param[in] Src Pointer to the string to be converted.\r
+ @param[in] Limit Maximum number of elements to be written to Dest.\r
+\r
+ @return If an invalid multibyte character is encountered, the mbstowcs\r
+ function returns (size_t)(-1). Otherwise, the mbstowcs function\r
+ returns the number of array elements modified, not including a\r
+ terminating null wide character, if any.\r
+**/\r
+size_t mbstowcs(wchar_t * __restrict Dest, const char * __restrict Src, size_t Limit);\r
+\r
+/** Convert a wide-character string into a multibyte character string.\r
+\r
+ The wcstombs function converts a sequence of wide characters from the\r
+ array pointed to by Src into a sequence of corresponding multibyte\r
+ characters that begins in the initial shift state, and stores these\r
+ multibyte characters into the array pointed to by Dest, stopping if a\r
+ multibyte character would exceed the limit of Limit total bytes or if a\r
+ null character is stored. Each wide character is converted as if by\r
+ a call to the wctomb function, except that the conversion state of\r
+ the wctomb function is not affected.\r
+\r
+ No more than Limit bytes will be modified in the array pointed to by Dest.\r
+ If copying takes place between objects that overlap,\r
+ the behavior is undefined.\r
+\r
+ @param[out] Dest Pointer to the array to receive the converted string.\r
+ @param[in] Src Pointer to the string to be converted.\r
+ @param[in] Limit Maximum number of bytes to be written to Dest.\r
\r
- @return\r
+ @return If a wide character is encountered that does not correspond to a\r
+ valid multibyte character, the wcstombs function returns\r
+ (size_t)(-1). Otherwise, the wcstombs function returns the number\r
+ of bytes modified, not including a terminating null character,\r
+ if any.\r
**/\r
-int mblen(const char *, size_t);\r
+size_t wcstombs(char * __restrict Dest, const wchar_t * __restrict Src, size_t Limit);\r
+\r
+/* ############## Miscelaneous functions for *nix compatibility ########## */\r
+\r
+/** The realpath() function shall derive, from the pathname pointed to by\r
+ file_name, an absolute pathname that names the same file, whose resolution\r
+ does not involve '.', '..', or symbolic links. The generated pathname shall\r
+ be stored as a null-terminated string, up to a maximum of {PATH_MAX} bytes,\r
+ in the buffer pointed to by resolved_name.\r
+\r
+ If resolved_name is a null pointer, the behavior of realpath() is\r
+ implementation-defined.\r
\r
-/**\r
+ @param[in] file_name The filename to convert.\r
+ @param[in,out] resolved_name The resultant name.\r
\r
- @return\r
+ @retval NULL An error occured.\r
+ @retval resolved_name.\r
**/\r
-int mbtowc(wchar_t * __restrict, const char * __restrict, size_t);\r
+char * realpath(char *file_name, char *resolved_name);\r
\r
-/**\r
+/** The getprogname() function returns the name of the program. If the name\r
+ has not been set yet, it will return NULL.\r
\r
- @return\r
+ @return The getprogname function returns NULL if the program's name has not\r
+ been set, otherwise it returns the name of the program.\r
**/\r
-int wctomb(char *, wchar_t);\r
+const char * getprogname(void);\r
\r
-/* ################ Multibyte/wide string conversion functions ########## */\r
+/** The setprogname() function sets the name of the program.\r
+\r
+ @param[in] progname The name of the program. This memory must be retained\r
+ by the caller until no calls to "getprogname" will be\r
+ called.\r
+**/\r
+void setprogname(const char *progname);\r
+\r
+/* ############### Functions specific to this implementation ############# */\r
\r
-/**\r
+/* Determine the number of bytes needed to represent a Wide character\r
+ as a MBCS character.\r
\r
- @return\r
+ A single wide character may convert into a one, two, three, or four byte\r
+ narrow (MBCS or UTF-8) character. The number of MBCS bytes can be determined\r
+ as follows.\r
+\r
+ If WCS char < 0x00000080 One Byte\r
+ Else if WCS char < 0x0000D800 Two Bytes\r
+ Else Three Bytes\r
+\r
+ Since UEFI only supports the Unicode Base Multilingual Plane (BMP),\r
+ Four-byte characters are not supported.\r
+\r
+ @param[in] InCh Wide character to test.\r
+\r
+ @retval -1 Improperly formed character\r
+ @retval 0 InCh is 0x0000\r
+ @retval >0 Number of bytes needed for the MBCS character\r
+*/\r
+int\r
+EFIAPI\r
+OneWcToMcLen(const wchar_t InCh);\r
+\r
+/* Determine the number of bytes needed to represent a Wide character string\r
+ as a MBCS string of given maximum length. Will optionally return the number\r
+ of wide characters that would be consumed.\r
+\r
+ @param[in] Src Pointer to a wide character string.\r
+ @param[in] Limit Maximum number of bytes the converted string may occupy.\r
+ @param[out] NumChar Pointer to where to store the number of wide characters, or NULL.\r
+\r
+ @return The number of bytes required to convert Src to MBCS,\r
+ not including the terminating NUL. If NumChar is not NULL, the number\r
+ of characters represented by the return value will be written to\r
+ where it points.\r
**/\r
-size_t mbstowcs(wchar_t * __restrict , const char * __restrict, size_t);\r
+size_t\r
+EFIAPI\r
+EstimateWtoM(const wchar_t * Src, size_t Limit, size_t *NumChar);\r
+\r
+/** Determine the number of characters in a MBCS string.\r
\r
-/**\r
+ @param[in] Src The string to examine\r
\r
- @return\r
+ @return The number of characters represented by the MBCS string.\r
**/\r
-size_t wcstombs(char * __restrict, const wchar_t * __restrict, size_t);\r
+size_t\r
+EFIAPI\r
+CountMbcsChars(const char *Src);\r
\r
__END_DECLS\r
\r
projects / mirror_edk2.git / blobdiff