Update or add comments to files and functions for use by Doxygen.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@12153 6f19259b-4bc3-4df7-8a09-765794883524
This commit is contained in:
@@ -2,21 +2,120 @@
|
||||
The header <stdlib.h> declares five types and several functions of general
|
||||
utility, and defines several macros.
|
||||
|
||||
The files stddef.h and stdlib.h are "catch all" headers for definitions and declarations
|
||||
that don't fit well in the other headers. There are two separate header files because
|
||||
the contents of <stddef.h> are valid in both freestanding and hosted environment, while the
|
||||
header <stdlib.h> contains elements that are only valid in a hosted environment.
|
||||
|
||||
The following macros are defined in this file:<BR>
|
||||
@verbatim
|
||||
EXIT_FAILURE An expression indicating application failure, used as an argument to exit().
|
||||
EXIT_SUCCESS An expression indicating application success, used as an argument to exit().
|
||||
RAND_MAX The maximum value returned by the rand function.
|
||||
MB_CUR_MAX Maximum number of bytes in a multibyte character for the current locale.
|
||||
ATEXIT_MAX Maximum number of routines that may be registered by the atexit function.
|
||||
@endverbatim
|
||||
|
||||
The following types are defined in this file:<BR>
|
||||
@verbatim
|
||||
size_t Unsigned integer type of the result of the sizeof operator.
|
||||
wchar_t The type of a wide character.
|
||||
div_t Type of the value returned by the div function.
|
||||
ldiv_t Type of the value returned by the ldiv function.
|
||||
lldiv_t Type of the value returned by the lldiv function.
|
||||
@endverbatim
|
||||
|
||||
The following functions are declared in this file:<BR>
|
||||
@verbatim
|
||||
################ Communication with the environment
|
||||
void abort (void) __noreturn;
|
||||
int atexit (void (*)(void));
|
||||
void exit (int status) __noreturn;
|
||||
void _Exit (int status) __noreturn;
|
||||
char *getenv (const char *name);
|
||||
int setenv (register const char * name,
|
||||
register const char * value, int rewrite);
|
||||
int system (const char *string);
|
||||
|
||||
################ Integer arithmetic functions
|
||||
int abs (int j);
|
||||
long labs (long j);
|
||||
long long llabs (long long j);
|
||||
div_t div (int numer, int denom);
|
||||
ldiv_t ldiv (long numer, long denom);
|
||||
lldiv_t lldiv (long long numer, long long denom);
|
||||
|
||||
################ Pseudo-random sequence generation functions
|
||||
int rand (void);
|
||||
void srand (unsigned seed);
|
||||
|
||||
################ Memory management functions
|
||||
void *calloc (size_t Num, size_t Size);
|
||||
void free (void *);
|
||||
void *malloc (size_t);
|
||||
void *realloc (void *Ptr, size_t NewSize);
|
||||
|
||||
################ Searching and Sorting utilities
|
||||
void *bsearch (const void *key, const void *base0,
|
||||
size_t nmemb, size_t size,
|
||||
int (*compar)(const void *, const void *));
|
||||
void qsort (void *base, size_t nmemb, size_t size,
|
||||
int (*compar)(const void *, const void *));
|
||||
|
||||
################ Multibyte/wide character conversion functions
|
||||
int mblen (const char *, size_t);
|
||||
int mbtowc (wchar_t * __restrict, const char * __restrict, size_t);
|
||||
int wctomb (char *, wchar_t);
|
||||
|
||||
################ Multibyte/wide string conversion functions
|
||||
size_t mbstowcs (wchar_t * __restrict dest,
|
||||
const char * __restrict src, size_t limit);
|
||||
size_t wcstombs (char * __restrict dest,
|
||||
const wchar_t * __restrict src, size_t limit);
|
||||
|
||||
################ Miscelaneous functions for *nix compatibility
|
||||
char *realpath (char *file_name, char *resolved_name);
|
||||
const char *getprogname (void);
|
||||
void setprogname (const char *progname);
|
||||
|
||||
############ Integer Numeric conversion functions
|
||||
int atoi (const char *nptr);
|
||||
long atol (const char *nptr);
|
||||
long long atoll (const char *nptr);
|
||||
long strtol (const char * __restrict nptr,
|
||||
char ** __restrict endptr, int base);
|
||||
unsigned long strtoul (const char * __restrict nptr,
|
||||
char ** __restrict endptr, int base);
|
||||
long long strtoll (const char * __restrict nptr,
|
||||
char ** __restrict endptr, int base);
|
||||
unsigned long long strtoull (const char * __restrict nptr,
|
||||
char ** __restrict endptr, int base);
|
||||
|
||||
######### Floating-point Numeric conversion functions
|
||||
double atof (const char *);
|
||||
double strtod (const char * __restrict nptr,
|
||||
char ** __restrict endptr);
|
||||
float strtof (const char * __restrict nptr,
|
||||
char ** __restrict endptr);
|
||||
long double strtold (const char * __restrict nptr,
|
||||
char ** __restrict endptr);
|
||||
@endverbatim
|
||||
|
||||
Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
|
||||
This program and the accompanying materials are licensed and made available under
|
||||
the terms and conditions of the BSD License that accompanies this distribution.
|
||||
The full text of the license may be found at
|
||||
http://opensource.org/licenses/bsd-license.php.
|
||||
http://opensource.org/licenses/bsd-license.
|
||||
|
||||
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
|
||||
|
||||
**/
|
||||
#ifndef _STDLIB_H
|
||||
#define _STDLIB_H
|
||||
#include <sys/EfiCdefs.h>
|
||||
|
||||
#ifdef _EFI_SIZE_T_
|
||||
/** Unsigned integer type of the result of the sizeof operator. **/
|
||||
typedef _EFI_SIZE_T_ size_t;
|
||||
#undef _EFI_SIZE_T_
|
||||
#undef _BSD_SIZE_T_
|
||||
@@ -24,6 +123,7 @@
|
||||
|
||||
#ifndef __cplusplus
|
||||
#ifdef _EFI_WCHAR_T
|
||||
/** Type of a wide (Unicode) character. **/
|
||||
typedef _EFI_WCHAR_T wchar_t;
|
||||
#undef _EFI_WCHAR_T
|
||||
#undef _BSD_WCHAR_T_
|
||||
@@ -32,8 +132,8 @@
|
||||
|
||||
/// A structure type that is the type of the value returned by the div function.
|
||||
typedef struct {
|
||||
int quot; /* quotient */
|
||||
int rem; /* remainder */
|
||||
int quot; /**< quotient */
|
||||
int rem; /**< remainder */
|
||||
} div_t;
|
||||
|
||||
/// A structure type that is the type of the value returned by the ldiv function.
|
||||
@@ -48,17 +148,17 @@ typedef struct {
|
||||
long long rem;
|
||||
} lldiv_t;
|
||||
|
||||
/** Expand to integer constant expressions that can be used as the argument to
|
||||
/** @{
|
||||
Expand to integer constant expressions that can be used as the argument to
|
||||
the exit function to return unsuccessful or successful termination status,
|
||||
respectively, to the host environment.
|
||||
**/
|
||||
#define EXIT_FAILURE 1
|
||||
#define EXIT_SUCCESS 0
|
||||
/*@}*/
|
||||
|
||||
/** Expands to an integer constant expression that is the maximum value
|
||||
returned by the rand function.
|
||||
|
||||
The value of the RAND_MAX macro shall be at least 32767.
|
||||
**/
|
||||
#define RAND_MAX 0x7fffffff
|
||||
|
||||
@@ -98,10 +198,13 @@ void abort(void) __noreturn;
|
||||
|
||||
The implementation supports the registration of up to 32 functions.
|
||||
|
||||
@param[in] Handler Pointer to the function to register as one of the
|
||||
routines to call at application exit time.
|
||||
|
||||
@return The atexit function returns zero if the registration succeeds,
|
||||
nonzero if it fails.
|
||||
**/
|
||||
int atexit(void (*)(void));
|
||||
int atexit(void (*Handler)(void));
|
||||
|
||||
/** The exit function causes normal program termination to occur. If more than
|
||||
one call to the exit function is executed by a program,
|
||||
@@ -118,14 +221,13 @@ int atexit(void (*)(void));
|
||||
streams are closed, and all files created by the tmpfile function
|
||||
are removed.
|
||||
|
||||
Finally, control is returned to the host environment. If the value of
|
||||
status is zero, or EXIT_SUCCESS, status is returned unchanged. If the value
|
||||
of status is EXIT_FAILURE, EAPPLICATION is returned.
|
||||
Otherwise, status is returned unchanged.
|
||||
Finally, control is returned to the host environment.
|
||||
|
||||
While this function does not return, it can NOT be marked as "__noreturn"
|
||||
without causing a warning to be emitted because the compilers can not
|
||||
determine that the function truly does not return.
|
||||
@param[in] status A value to be returned when the application exits.
|
||||
|
||||
@return If the value of status is zero, or EXIT_SUCCESS, status is
|
||||
returned unchanged. If the value of status is EXIT_FAILURE,
|
||||
RETURN_ABORTED is returned. Otherwise, status is returned unchanged.
|
||||
**/
|
||||
void exit(int status) __noreturn;
|
||||
|
||||
@@ -137,12 +239,14 @@ void exit(int status) __noreturn;
|
||||
buffered data are not flushed, open streams are not closed, and temporary
|
||||
files are not removed by abort.
|
||||
|
||||
While this function does not return, it can NOT be marked as "__noreturn"
|
||||
without causing a warning to be emitted because the compilers can not
|
||||
determine that the function truly does not return.
|
||||
|
||||
The status returned to the host environment is determined in the same way
|
||||
as for the exit function.
|
||||
|
||||
@param[in] status A value to be returned when the application exits.
|
||||
|
||||
@return If the value of status is zero, or EXIT_SUCCESS, status is
|
||||
returned unchanged. If the value of status is EXIT_FAILURE,
|
||||
RETURN_ABORTED is returned. Otherwise, status is returned unchanged.
|
||||
**/
|
||||
void _Exit(int status) __noreturn;
|
||||
|
||||
@@ -151,6 +255,8 @@ void _Exit(int status) __noreturn;
|
||||
set of environment names and the method for altering the environment list
|
||||
are determined by the underlying UEFI Shell implementation.
|
||||
|
||||
@param[in] name Pointer to a string naming the environment variable to retrieve.
|
||||
|
||||
@return The getenv function returns a pointer to a string associated with
|
||||
the matched list member. The string pointed to shall not be
|
||||
modified by the program, but may be overwritten by a subsequent
|
||||
@@ -159,16 +265,14 @@ void _Exit(int status) __noreturn;
|
||||
**/
|
||||
char *getenv(const char *name);
|
||||
|
||||
/**
|
||||
Add or update a variable in the environment list
|
||||
/** Add or update a variable in the environment list.
|
||||
|
||||
@param name Address of a zero terminated name string
|
||||
@param value Address of a zero terminated value string
|
||||
@param rewrite TRUE allows overwriting existing values
|
||||
|
||||
@retval Returns 0 upon success
|
||||
@retval Returns -1 upon failure, sets errno with more information
|
||||
@param[in] name Address of a zero terminated name string.
|
||||
@param[in] value Address of a zero terminated value string.
|
||||
@param[in] rewrite TRUE allows overwriting existing values.
|
||||
|
||||
@retval 0 Returns 0 upon success.
|
||||
@retval -1 Returns -1 upon failure, sets errno with more information.
|
||||
**/
|
||||
int
|
||||
setenv (
|
||||
@@ -184,6 +288,8 @@ setenv (
|
||||
document; this might then cause the program calling system to behave in a
|
||||
non-conforming manner or to terminate.
|
||||
|
||||
@param[in] string Pointer to the command string to be executed.
|
||||
|
||||
@return If the argument is a null pointer, the system function returns
|
||||
nonzero only if a command processor is available. If the argument
|
||||
is not a null pointer, and the system function does return, it
|
||||
@@ -196,17 +302,23 @@ int system(const char *string);
|
||||
|
||||
/** Computes the absolute value of an integer j.
|
||||
|
||||
@param[in] j The value to find the absolute value of.
|
||||
|
||||
@return The absolute value of j.
|
||||
**/
|
||||
int abs(int j);
|
||||
|
||||
/** Computes the absolute value of an integer j.
|
||||
/** Computes the absolute value of a long integer j.
|
||||
|
||||
@param[in] j The value to find the absolute value of.
|
||||
|
||||
@return The absolute value of j.
|
||||
**/
|
||||
long labs(long j);
|
||||
|
||||
/** Computes the absolute value of an integer j.
|
||||
/** Computes the absolute value of a long long integer j.
|
||||
|
||||
@param[in] j The value to find the absolute value of.
|
||||
|
||||
@return The absolute value of j.
|
||||
**/
|
||||
@@ -215,6 +327,9 @@ long long
|
||||
|
||||
/** Computes numer / denom and numer % denom in a single operation.
|
||||
|
||||
@param[in] numer The numerator for the division.
|
||||
@param[in] denom The denominator for the division.
|
||||
|
||||
@return Returns a structure of type div_t, comprising both the
|
||||
quotient and the remainder.
|
||||
**/
|
||||
@@ -222,6 +337,9 @@ div_t div(int numer, int denom);
|
||||
|
||||
/** Computes numer / denom and numer % denom in a single operation.
|
||||
|
||||
@param[in] numer The numerator for the division.
|
||||
@param[in] denom The denominator for the division.
|
||||
|
||||
@return Returns a structure of type ldiv_t, comprising both the
|
||||
quotient and the remainder.
|
||||
**/
|
||||
@@ -229,6 +347,9 @@ ldiv_t ldiv(long numer, long denom);
|
||||
|
||||
/** Computes numer / denom and numer % denom in a single operation.
|
||||
|
||||
@param[in] numer The numerator for the division.
|
||||
@param[in] denom The denominator for the division.
|
||||
|
||||
@return Returns a structure of type lldiv_t, comprising both the
|
||||
quotient and the remainder.
|
||||
**/
|
||||
@@ -241,7 +362,9 @@ lldiv_t lldiv(long long numer, long long denom);
|
||||
equivalent to:
|
||||
- atoi: (int)strtol(nptr, (char **)NULL, 10)
|
||||
|
||||
@return The atoi function returns the converted value.
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
|
||||
@return The atoi function returns the converted value.
|
||||
**/
|
||||
int atoi(const char *nptr);
|
||||
|
||||
@@ -250,7 +373,9 @@ int atoi(const char *nptr);
|
||||
equivalent to:
|
||||
- atol: strtol(nptr, (char **)NULL, 10)
|
||||
|
||||
@return The atol function returns the converted value.
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
|
||||
@return The atol function returns the converted value.
|
||||
**/
|
||||
long atol(const char *nptr);
|
||||
|
||||
@@ -259,7 +384,9 @@ long atol(const char *nptr);
|
||||
is equivalent to:
|
||||
- atoll: strtoll(nptr, (char **)NULL, 10)
|
||||
|
||||
@return The atoll function returns the converted value.
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
|
||||
@return The atoll function returns the converted value.
|
||||
**/
|
||||
long long
|
||||
atoll(const char *nptr);
|
||||
@@ -276,7 +403,7 @@ long long
|
||||
integer, and return the result.
|
||||
|
||||
If the value of base is zero, the expected form of the subject sequence is
|
||||
that of an integer constant as described in 6.4.4.1, optionally preceded
|
||||
that of an integer constant, optionally preceded
|
||||
by a plus or minus sign, but not including an integer suffix. If the value
|
||||
of base is between 2 and 36 (inclusive), the expected form of the subject
|
||||
sequence is a sequence of letters and digits representing an integer with
|
||||
@@ -310,13 +437,17 @@ long long
|
||||
conversion is performed; the value of nptr is stored in the object pointed
|
||||
to by endptr, provided that endptr is not a null pointer.
|
||||
|
||||
@return The strtol, strtoll, strtoul, and strtoull functions return the
|
||||
converted value, if any. If no conversion could be performed, zero
|
||||
is returned. If the correct value is outside the range of
|
||||
representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,
|
||||
ULONG_MAX, or ULLONG_MAX is returned (according to the return type
|
||||
and sign of the value, if any), and the value of the macro ERANGE
|
||||
is stored in errno.
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
@param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
|
||||
@param[in] base The base, 0 to 36, of the number represented by the input string.
|
||||
|
||||
@return The strtol, strtoll, strtoul, and strtoull functions return the
|
||||
converted value, if any. If no conversion could be performed, zero
|
||||
is returned. If the correct value is outside the range of
|
||||
representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,
|
||||
ULONG_MAX, or ULLONG_MAX is returned (according to the return type
|
||||
and sign of the value, if any), and the value of the macro ERANGE
|
||||
is stored in errno.
|
||||
**/
|
||||
long strtol(const char * __restrict nptr, char ** __restrict endptr, int base);
|
||||
|
||||
@@ -325,10 +456,14 @@ long strtol(const char * __restrict nptr, char ** __restrict endptr, int base
|
||||
|
||||
See the description for strtol for more information.
|
||||
|
||||
@return The strtoul function returns the converted value, if any. If no
|
||||
conversion could be performed, zero is returned. If the correct
|
||||
value is outside the range of representable values, ULONG_MAX is
|
||||
returned and the value of the macro ERANGE is stored in errno.
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
@param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
|
||||
@param[in] base The base, 0 to 36, of the number represented by the input string.
|
||||
|
||||
@return The strtoul function returns the converted value, if any. If no
|
||||
conversion could be performed, zero is returned. If the correct
|
||||
value is outside the range of representable values, ULONG_MAX is
|
||||
returned and the value of the macro ERANGE is stored in errno.
|
||||
**/
|
||||
unsigned long
|
||||
strtoul(const char * __restrict nptr, char ** __restrict endptr, int base);
|
||||
@@ -338,11 +473,15 @@ unsigned long
|
||||
|
||||
See the description for strtol for more information.
|
||||
|
||||
@return The strtoll function returns the converted value, if any. If no
|
||||
conversion could be performed, zero is returned. If the correct
|
||||
value is outside the range of representable values, LLONG_MIN or
|
||||
LLONG_MAX is returned (according to the sign of the value, if any),
|
||||
and the value of the macro ERANGE is stored in errno.
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
@param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
|
||||
@param[in] base The base, 0 to 36, of the number represented by the input string.
|
||||
|
||||
@return The strtoll function returns the converted value, if any. If no
|
||||
conversion could be performed, zero is returned. If the correct
|
||||
value is outside the range of representable values, LLONG_MIN or
|
||||
LLONG_MAX is returned (according to the sign of the value, if any),
|
||||
and the value of the macro ERANGE is stored in errno.
|
||||
**/
|
||||
long long
|
||||
strtoll(const char * __restrict nptr, char ** __restrict endptr, int base);
|
||||
@@ -352,40 +491,83 @@ long long
|
||||
|
||||
See the description for strtol for more information.
|
||||
|
||||
@return The strtoull function returns the converted value, if any. If no
|
||||
conversion could be performed, zero is returned. If the correct
|
||||
value is outside the range of representable values, ULLONG_MAX is
|
||||
returned and the value of the macro ERANGE is stored in errno.
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
@param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
|
||||
@param[in] base The base, 0 to 36, of the number represented by the input string.
|
||||
|
||||
@return The strtoull function returns the converted value, if any. If no
|
||||
conversion could be performed, zero is returned. If the correct
|
||||
value is outside the range of representable values, ULLONG_MAX is
|
||||
returned and the value of the macro ERANGE is stored in errno.
|
||||
**/
|
||||
unsigned long long
|
||||
strtoull(const char * __restrict nptr, char ** __restrict endptr, int base);
|
||||
|
||||
/* ######### Floating-point Numeric conversion functions ################ */
|
||||
|
||||
/**
|
||||
/** Convert the initial part of a string to double representation.
|
||||
|
||||
@return
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
|
||||
@return The floating-point value representing the string nptr.
|
||||
**/
|
||||
double atof(const char *);
|
||||
double atof(const char *nptr);
|
||||
|
||||
/**
|
||||
/** @{
|
||||
The strtod, strtof, and strtold functions convert the initial portion of
|
||||
the string pointed to by nptr to double, float, and long double
|
||||
representation, respectively. First, they decompose the input string into
|
||||
three parts: an initial, possibly empty, sequence of white-space characters
|
||||
(as specified by the isspace function), a subject sequence resembling a
|
||||
floating-point constant or representing an infinity or NaN; and a final
|
||||
string of one or more unrecognized characters, including the terminating
|
||||
null character of the input string. Then, they attempt to convert the
|
||||
subject sequence to a floating-point number, and return the result.
|
||||
*/
|
||||
|
||||
@return
|
||||
/** Convert a string to a double and point to the character after the last converted.
|
||||
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
@param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
|
||||
|
||||
@return A floating-point value representing the string nptr.
|
||||
A pointer to the final string is stored in the object pointed to
|
||||
by endptr, provided that endptr is not a null pointer.
|
||||
If the subject sequence is empty or does not have the expected
|
||||
form, no conversion is performed; the value of nptr is stored in
|
||||
the object pointed to by endptr, provided that endptr is not a null pointer.
|
||||
**/
|
||||
double strtod(const char * __restrict nptr, char ** __restrict endptr);
|
||||
|
||||
/**
|
||||
/** Convert a string to a float and point to the character after the last converted.
|
||||
|
||||
@return
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
@param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
|
||||
|
||||
@return A floating-point value representing the string nptr.
|
||||
A pointer to the final string is stored in the object pointed to
|
||||
by endptr, provided that endptr is not a null pointer.
|
||||
If the subject sequence is empty or does not have the expected
|
||||
form, no conversion is performed; the value of nptr is stored in
|
||||
the object pointed to by endptr, provided that endptr is not a null pointer.
|
||||
**/
|
||||
float strtof(const char * __restrict nptr, char ** __restrict endptr);
|
||||
|
||||
/**
|
||||
/** Convert a string to a long double and point to the character after the last converted.
|
||||
|
||||
@return
|
||||
@param[in] nptr Pointer to the string to be converted.
|
||||
@param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
|
||||
|
||||
@return A floating-point value representing the string nptr.
|
||||
A pointer to the final string is stored in the object pointed to
|
||||
by endptr, provided that endptr is not a null pointer.
|
||||
If the subject sequence is empty or does not have the expected
|
||||
form, no conversion is performed; the value of nptr is stored in
|
||||
the object pointed to by endptr, provided that endptr is not a null pointer.
|
||||
**/
|
||||
long double
|
||||
strtold(const char * __restrict nptr, char ** __restrict endptr);
|
||||
/*@}*/
|
||||
|
||||
/* ################ Pseudo-random sequence generation functions ######### */
|
||||
|
||||
@@ -403,6 +585,8 @@ int rand(void);
|
||||
pseudo-random numbers shall be repeated. If rand is called before any calls
|
||||
to srand have been made, the same sequence shall be generated as when srand
|
||||
is first called with a seed value of 1.
|
||||
|
||||
@param[in] seed The value used to "seed" the random number generator with.
|
||||
**/
|
||||
void srand(unsigned seed);
|
||||
|
||||
@@ -411,6 +595,9 @@ void srand(unsigned seed);
|
||||
/** The calloc function allocates space for an array of Num objects, each of
|
||||
whose size is Size. The space is initialized to all bits zero.
|
||||
|
||||
@param[in] Num The number of objects to allocate space for.
|
||||
@param[in] Size The size, in bytes, of each object.
|
||||
|
||||
@return NULL is returned if the space could not be allocated and errno
|
||||
contains the cause. Otherwise, a pointer to an 8-byte aligned
|
||||
region of the requested size is returned.
|
||||
@@ -426,9 +613,8 @@ void *calloc(size_t Num, size_t Size);
|
||||
realloc, the behavior is undefined.
|
||||
|
||||
@param Ptr Pointer to a previously allocated region of memory to be freed.
|
||||
|
||||
**/
|
||||
void free(void *);
|
||||
void free(void *Ptr);
|
||||
|
||||
/** The malloc function allocates space for an object whose size is specified
|
||||
by size and whose value is indeterminate.
|
||||
@@ -437,7 +623,7 @@ void free(void *);
|
||||
region of memory that is 8-byte aligned and of the specified size. The
|
||||
region is allocated with type EfiLoaderData.
|
||||
|
||||
@param size Size, in bytes, of the region to allocate.
|
||||
@param Size Size, in bytes, of the region to allocate.
|
||||
|
||||
@return NULL is returned if the space could not be allocated and errno
|
||||
contains the cause. Otherwise, a pointer to an 8-byte aligned
|
||||
@@ -446,7 +632,7 @@ void free(void *);
|
||||
- EINVAL: Requested Size is zero.
|
||||
- ENOMEM: Memory could not be allocated.
|
||||
**/
|
||||
void *malloc(size_t);
|
||||
void *malloc(size_t Size);
|
||||
|
||||
/** The realloc function changes the size of the object pointed to by Ptr to
|
||||
the size specified by NewSize.
|
||||
@@ -483,35 +669,40 @@ void *realloc(void *Ptr, size_t NewSize);
|
||||
|
||||
/* ################ Searching and Sorting utilities ##################### */
|
||||
|
||||
/** The bsearch function searches an array of nmemb objects, the initial
|
||||
element of which is pointed to by base, for an element that matches the
|
||||
object pointed to by key. The size of each element of the array is
|
||||
specified by size.
|
||||
/** The bsearch function searches an array of Nmemb objects, the initial
|
||||
element of which is pointed to by Base, for an element that matches the
|
||||
object pointed to by Key. The size of each element of the array is
|
||||
specified by Size.
|
||||
|
||||
The comparison function pointed to by compar is called with two arguments
|
||||
that point to the key object and to an array element, in that order. The
|
||||
The comparison function pointed to by Compar is called with two arguments
|
||||
that point to the Key object and to an array element, in that order. The
|
||||
function returns an integer less than, equal to, or greater than zero if
|
||||
the key object is considered, respectively, to be less than, to match, or
|
||||
the Key object is considered, respectively, to be less than, to match, or
|
||||
to be greater than the array element. The array consists of: all the
|
||||
elements that compare less than, all the elements that compare equal to,
|
||||
and all the elements that compare greater than the key object,
|
||||
in that order.
|
||||
|
||||
@return The bsearch function returns a pointer to a matching element of the
|
||||
array, or a null pointer if no match is found. If two elements
|
||||
compare as equal, which element is matched is unspecified.
|
||||
**/
|
||||
void *
|
||||
bsearch( const void *key, const void *base0,
|
||||
size_t nmemb, size_t size,
|
||||
int (*compar)(const void *, const void *)
|
||||
);
|
||||
@param[in] Key Pointer to the object to search for.
|
||||
@param[in] Base Pointer to the first element of an array to search.
|
||||
@param[in] Nmemb Number of objects in the search array.
|
||||
@param[in] Size The size of each object in the search array.
|
||||
@param[in] Compar Pointer to the function used to compare two objects.
|
||||
|
||||
/** The qsort function sorts an array of nmemb objects, the initial element of
|
||||
which is pointed to by base. The size of each object is specified by size.
|
||||
@return The bsearch function returns a pointer to a matching element of the
|
||||
array, or a null pointer if no match is found. If two elements
|
||||
compare as equal, which element is matched is unspecified.
|
||||
**/
|
||||
void *bsearch( const void *Key, const void *Base,
|
||||
size_t Nmemb, size_t Size,
|
||||
int (*Compar)(const void *, const void *)
|
||||
);
|
||||
|
||||
/** The qsort function sorts an array of Nmemb objects, the initial element of
|
||||
which is pointed to by Base. The size of each object is specified by Size.
|
||||
|
||||
The contents of the array are sorted into ascending order according to a
|
||||
comparison function pointed to by compar, which is called with two
|
||||
comparison function pointed to by Compar, which is called with two
|
||||
arguments that point to the objects being compared. The function shall
|
||||
return an integer less than, equal to, or greater than zero if the first
|
||||
argument is considered to be respectively less than, equal to, or greater
|
||||
@@ -519,165 +710,183 @@ bsearch( const void *key, const void *base0,
|
||||
|
||||
If two elements compare as equal, their order in the resulting sorted array
|
||||
is unspecified.
|
||||
|
||||
@param[in,out] Base Pointer to the first element of an array to sort.
|
||||
@param[in] Nmemb Number of objects in the array.
|
||||
@param[in] Size The size of each object in the array.
|
||||
@param[in] Compar Pointer to the function used to compare two objects.
|
||||
**/
|
||||
void qsort( void *base, size_t nmemb, size_t size,
|
||||
int (*compar)(const void *, const void *));
|
||||
void qsort( void *base, size_t nmemb, size_t size,
|
||||
int (*compar)(const void *, const void *));
|
||||
|
||||
/* ################ Multibyte/wide character conversion functions ####### */
|
||||
|
||||
/** Determine the number of bytes comprising a multibyte character.
|
||||
|
||||
If s is not a null pointer, the mblen function determines the number of bytes
|
||||
contained in the multibyte character pointed to by s. Except that the
|
||||
If S is not a null pointer, the mblen function determines the number of bytes
|
||||
contained in the multibyte character pointed to by S. Except that the
|
||||
conversion state of the mbtowc function is not affected, it is equivalent to
|
||||
mbtowc((wchar_t *)0, s, n);
|
||||
mbtowc((wchar_t *)0, S, N);
|
||||
|
||||
The implementation shall behave as if no library function calls the mblen
|
||||
function.
|
||||
@param[in] S NULL to query whether multibyte characters have
|
||||
state-dependent encodings. Otherwise, points to a
|
||||
multibyte character.
|
||||
@param[in] N The maximum number of bytes in a multibyte character.
|
||||
|
||||
@return If s is a null pointer, the mblen function returns a nonzero or
|
||||
@return If S is a null pointer, the mblen function returns a nonzero or
|
||||
zero value, if multibyte character encodings, respectively, do
|
||||
or do not have state-dependent encodings. If s is not a null
|
||||
pointer, the mblen function either returns 0 (if s points to the
|
||||
or do not have state-dependent encodings. If S is not a null
|
||||
pointer, the mblen function either returns 0 (if S points to the
|
||||
null character), or returns the number of bytes that are contained
|
||||
in the multibyte character (if the next n or fewer bytes form a
|
||||
in the multibyte character (if the next N or fewer bytes form a
|
||||
valid multibyte character), or returns -1 (if they do not form a
|
||||
valid multibyte character).
|
||||
**/
|
||||
int mblen(const char *, size_t);
|
||||
int mblen(const char *S, size_t N);
|
||||
|
||||
/** Convert a multibyte character into a wide character.
|
||||
|
||||
If s is not a null pointer, the mbtowc function inspects at most n bytes
|
||||
beginning with the byte pointed to by s to determine the number of bytes
|
||||
If S is not a null pointer, the mbtowc function inspects at most N bytes
|
||||
beginning with the byte pointed to by S to determine the number of bytes
|
||||
needed to complete the next multibyte character (including any shift
|
||||
sequences). If the function determines that the next multibyte character
|
||||
is complete and valid, it determines the value of the corresponding wide
|
||||
character and then, if pwc is not a null pointer, stores that value in
|
||||
the object pointed to by pwc. If the corresponding wide character is the
|
||||
character and then, if Pwc is not a null pointer, stores that value in
|
||||
the object pointed to by Pwc. If the corresponding wide character is the
|
||||
null wide character, the function is left in the initial conversion state.
|
||||
|
||||
The implementation shall behave as if no library function calls the
|
||||
mbtowc function.
|
||||
@param[out] Pwc Pointer to a wide-character object to receive the converted character.
|
||||
@param[in] S Pointer to a multibyte character to convert.
|
||||
@param[in] N Maximum number of bytes in a multibyte character.
|
||||
|
||||
@return If s is a null pointer, the mbtowc function returns a nonzero or
|
||||
@return If S is a null pointer, the mbtowc function returns a nonzero or
|
||||
zero value, if multibyte character encodings, respectively, do
|
||||
or do not have state-dependent encodings. If s is not a null
|
||||
pointer, the mbtowc function either returns 0 (if s points to
|
||||
or do not have state-dependent encodings. If S is not a null
|
||||
pointer, the mbtowc function either returns 0 (if S points to
|
||||
the null character), or returns the number of bytes that are
|
||||
contained in the converted multibyte character (if the next n or
|
||||
contained in the converted multibyte character (if the next N or
|
||||
fewer bytes form a valid multibyte character), or returns -1
|
||||
(if they do not form a valid multibyte character).
|
||||
|
||||
In no case will the value returned be greater than n or the value
|
||||
In no case will the value returned be greater than N or the value
|
||||
of the MB_CUR_MAX macro.
|
||||
**/
|
||||
int mbtowc(wchar_t * __restrict, const char * __restrict, size_t);
|
||||
int mbtowc(wchar_t * __restrict Pwc, const char * __restrict S, size_t N);
|
||||
|
||||
/**
|
||||
The wctomb function determines the number of bytes needed to represent the multibyte
|
||||
character corresponding to the wide character given by wc (including any shift
|
||||
sequences), and stores the multibyte character representation in the array whose first
|
||||
element is pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters
|
||||
are stored. If wc is a null wide character, a null byte is stored, preceded by any shift
|
||||
sequence needed to restore the initial shift state, and the function is left in the initial
|
||||
conversion state.
|
||||
/** Convert a wide character into a multibyte character.
|
||||
|
||||
The implementation shall behave as if no library function calls the wctomb function.
|
||||
The wctomb function determines the number of bytes needed to represent the
|
||||
multibyte character corresponding to the wide character given by WC
|
||||
(including any shift sequences), and stores the multibyte character
|
||||
representation in the array whose first element is pointed to by S (if S is
|
||||
not a null pointer). At most MB_CUR_MAX characters are stored. If WC is a
|
||||
null wide character, a null byte is stored, preceded by any shift sequence
|
||||
needed to restore the initial shift state, and the function is left in the
|
||||
initial conversion state.
|
||||
|
||||
@return
|
||||
If s is a null pointer, the wctomb function returns a nonzero or zero value, if multibyte
|
||||
character encodings, respectively, do or do not have state-dependent encodings. If s is
|
||||
not a null pointer, the wctomb function returns -1 if the value of wc does not correspond
|
||||
to a valid multibyte character, or returns the number of bytes that are contained in the
|
||||
multibyte character corresponding to the value of wc.
|
||||
@param[out] S Pointer to the object to receive the converted multibyte character.
|
||||
@param[in] WC Wide character to be converted.
|
||||
|
||||
In no case will the value returned be greater than the value of the MB_CUR_MAX macro.
|
||||
@return If S is a null pointer, the wctomb function returns a nonzero or
|
||||
zero value, if multibyte character encodings, respectively, do or
|
||||
do not have state-dependent encodings. If S is not a null pointer,
|
||||
the wctomb function returns -1 if the value of WC does not
|
||||
correspond to a valid multibyte character, or returns the number
|
||||
of bytes that are contained in the multibyte character
|
||||
corresponding to the value of WC.
|
||||
|
||||
In no case will the value returned be greater than the value of
|
||||
the MB_CUR_MAX macro.
|
||||
**/
|
||||
int wctomb(char *, wchar_t);
|
||||
int wctomb(char *S, wchar_t WC);
|
||||
|
||||
/* ################ Multibyte/wide string conversion functions ########## */
|
||||
|
||||
/** Convert a multibyte character string into a wide-character string.
|
||||
|
||||
The mbstowcs function converts a sequence of multibyte characters that
|
||||
begins in the initial shift state from the array pointed to by src into
|
||||
begins in the initial shift state from the array pointed to by Src into
|
||||
a sequence of corresponding wide characters and stores not more than limit
|
||||
wide characters into the array pointed to by dest. No multibyte
|
||||
wide characters into the array pointed to by Dest. No multibyte
|
||||
characters that follow a null character (which is converted into a null
|
||||
wide character) will be examined or converted. Each multibyte character
|
||||
is converted as if by a call to the mbtowc function, except that the
|
||||
conversion state of the mbtowc function is not affected.
|
||||
|
||||
No more than limit elements will be modified in the array pointed to by dest.
|
||||
No more than Limit elements will be modified in the array pointed to by Dest.
|
||||
If copying takes place between objects that overlap,
|
||||
the behavior is undefined.
|
||||
|
||||
@return If an invalid multibyte character is encountered, the mbstowcs
|
||||
function returns (size_t)(-1). Otherwise, the mbstowcs function
|
||||
returns the number of array elements modified, not including a
|
||||
terminating null wide character, if any.
|
||||
@param[out] Dest Pointer to the array to receive the converted string.
|
||||
@param[in] Src Pointer to the string to be converted.
|
||||
@param[in] Limit Maximum number of elements to be written to Dest.
|
||||
|
||||
@return If an invalid multibyte character is encountered, the mbstowcs
|
||||
function returns (size_t)(-1). Otherwise, the mbstowcs function
|
||||
returns the number of array elements modified, not including a
|
||||
terminating null wide character, if any.
|
||||
**/
|
||||
size_t mbstowcs(wchar_t * __restrict dest, const char * __restrict src, size_t limit);
|
||||
size_t mbstowcs(wchar_t * __restrict Dest, const char * __restrict Src, size_t Limit);
|
||||
|
||||
/** Convert a wide-character string into a multibyte character string.
|
||||
|
||||
The wcstombs function converts a sequence of wide characters from the
|
||||
array pointed to by src into a sequence of corresponding multibyte
|
||||
array pointed to by Src into a sequence of corresponding multibyte
|
||||
characters that begins in the initial shift state, and stores these
|
||||
multibyte characters into the array pointed to by dest, stopping if a
|
||||
multibyte character would exceed the limit of limit total bytes or if a
|
||||
multibyte characters into the array pointed to by Dest, stopping if a
|
||||
multibyte character would exceed the limit of Limit total bytes or if a
|
||||
null character is stored. Each wide character is converted as if by
|
||||
a call to the wctomb function, except that the conversion state of
|
||||
the wctomb function is not affected.
|
||||
|
||||
No more than limit bytes will be modified in the array pointed to by dest.
|
||||
No more than Limit bytes will be modified in the array pointed to by Dest.
|
||||
If copying takes place between objects that overlap,
|
||||
the behavior is undefined.
|
||||
|
||||
@return If a wide character is encountered that does not correspond to a
|
||||
valid multibyte character, the wcstombs function returns
|
||||
(size_t)(-1). Otherwise, the wcstombs function returns the number
|
||||
of bytes modified, not including a terminating null character,
|
||||
if any.
|
||||
@param[out] Dest Pointer to the array to receive the converted string.
|
||||
@param[in] Src Pointer to the string to be converted.
|
||||
@param[in] Limit Maximum number of elements to be written to Dest.
|
||||
|
||||
@return If a wide character is encountered that does not correspond to a
|
||||
valid multibyte character, the wcstombs function returns
|
||||
(size_t)(-1). Otherwise, the wcstombs function returns the number
|
||||
of bytes modified, not including a terminating null character,
|
||||
if any.
|
||||
**/
|
||||
size_t wcstombs(char * __restrict dest, const wchar_t * __restrict src, size_t limit);
|
||||
size_t wcstombs(char * __restrict Dest, const wchar_t * __restrict Src, size_t Limit);
|
||||
|
||||
/**
|
||||
The realpath() function shall derive, from the pathname pointed to by
|
||||
file_name, an absolute pathname that names the same file, whose resolution
|
||||
does not involve '.', '..', or symbolic links. The generated pathname shall
|
||||
be stored as a null-terminated string, up to a maximum of {PATH_MAX} bytes,
|
||||
in the buffer pointed to by resolved_name.
|
||||
/* ################ Miscelaneous functions for *nix compatibility ########## */
|
||||
|
||||
If resolved_name is a null pointer, the behavior of realpath() is
|
||||
implementation-defined.
|
||||
/** The realpath() function shall derive, from the pathname pointed to by
|
||||
file_name, an absolute pathname that names the same file, whose resolution
|
||||
does not involve '.', '..', or symbolic links. The generated pathname shall
|
||||
be stored as a null-terminated string, up to a maximum of {PATH_MAX} bytes,
|
||||
in the buffer pointed to by resolved_name.
|
||||
|
||||
@param[in] file_name The filename to convert.
|
||||
@param[in,out] resolved_name The resultant name.
|
||||
If resolved_name is a null pointer, the behavior of realpath() is
|
||||
implementation-defined.
|
||||
|
||||
@retval NULL An error occured.
|
||||
@return resolved_name.
|
||||
@param[in] file_name The filename to convert.
|
||||
@param[in,out] resolved_name The resultant name.
|
||||
|
||||
@retval NULL An error occured.
|
||||
@retval resolved_name.
|
||||
**/
|
||||
char * realpath(char *file_name, char *resolved_name);
|
||||
|
||||
/**
|
||||
The getprogname() function returns the name of the program. If the name
|
||||
has not been set yet, it will return NULL.
|
||||
/** The getprogname() function returns the name of the program. If the name
|
||||
has not been set yet, it will return NULL.
|
||||
|
||||
@retval The name of the program.
|
||||
@retval NULL The name has not been set.
|
||||
@return The getprogname function returns NULL if the program's name has not
|
||||
been set, otherwise it returns the name of the program.
|
||||
**/
|
||||
const char * getprogname(void);
|
||||
|
||||
/**
|
||||
The setprogname() function sets the name of the program.
|
||||
/** The setprogname() function sets the name of the program.
|
||||
|
||||
@param[in] The name of the program. This memory must be retained
|
||||
by the caller until no calls to "getprogname" will be
|
||||
called.
|
||||
@param[in] progname The name of the program. This memory must be retained
|
||||
by the caller until no calls to "getprogname" will be
|
||||
called.
|
||||
**/
|
||||
void setprogname(const char *progname);
|
||||
|
||||
|
Reference in New Issue
Block a user