diff options
| author | darylm503 <darylm503@6f19259b-4bc3-4df7-8a09-765794883524> | 2011-08-17 22:54:56 +0000 |
|---|---|---|
| committer | darylm503 <darylm503@6f19259b-4bc3-4df7-8a09-765794883524> | 2011-08-17 22:54:56 +0000 |
| commit | 61403bd7ce134c5c1ca0cba4091cff1534926bd2 (patch) | |
| tree | 6e67bfd0fc4328c888edc4c099d756b3c4d38093 | |
| parent | 4ae5165ce62a930c531af098c3e8676840c18123 (diff) | |
| download | edk2-platforms-61403bd7ce134c5c1ca0cba4091cff1534926bd2.tar.xz | |
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
| -rw-r--r-- | StdLib/Include/stdio.h | 3 | ||||
| -rw-r--r-- | StdLib/Include/stdlib.h | 539 | ||||
| -rw-r--r-- | StdLib/Include/string.h | 428 | ||||
| -rw-r--r-- | StdLib/Include/sys/EfiSysCall.h | 316 | ||||
| -rw-r--r-- | StdLib/Include/time.h | 100 | ||||
| -rw-r--r-- | StdLib/Include/wchar.h | 1323 | ||||
| -rw-r--r-- | StdLib/Include/wctype.h | 303 |
7 files changed, 2443 insertions, 569 deletions
diff --git a/StdLib/Include/stdio.h b/StdLib/Include/stdio.h index 7f3204bf74..f916f9e34f 100644 --- a/StdLib/Include/stdio.h +++ b/StdLib/Include/stdio.h @@ -715,8 +715,7 @@ int setvbuf (FILE * __restrict fp, char * __restrict Buff, int BufMode, si @param[in] stream An open File specifier to which the output is sent.
@param[in] format A multi-byte character sequence containing characters
to be copied unchanged, and conversion specifiers
- which convert their associated arguments. Copied and
- converted characters are sent to the output stream.
+ which convert their associated arguments.
@param ... Variable number of parameters as required by format.
@return The fprintf function returns the number of characters
diff --git a/StdLib/Include/stdlib.h b/StdLib/Include/stdlib.h index d51d4bffd2..1166847867 100644 --- a/StdLib/Include/stdlib.h +++ b/StdLib/Include/stdlib.h @@ -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.
+
+ @param[in] status A value to be returned when the application exits.
- 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.
+ @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
-
- @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
+/** Add or update a variable in the environment list.
- @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.
+
+ @param[in] nptr Pointer to the string to be converted.
- @return
+ @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.
+*/
+
+/** 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
+ @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.
+
+ @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
+ @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.
+ @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.
+
+ @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 *)
-);
+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 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);
+
+/* ################ Miscelaneous functions for *nix compatibility ########## */
-/**
- 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.
+/** 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.
- If resolved_name is a null pointer, the behavior of realpath() is
- implementation-defined.
+ If resolved_name is a null pointer, the behavior of realpath() is
+ implementation-defined.
- @param[in] file_name The filename to convert.
- @param[in,out] resolved_name The resultant name.
+ @param[in] file_name The filename to convert.
+ @param[in,out] resolved_name The resultant name.
- @retval NULL An error occured.
- @return resolved_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);
diff --git a/StdLib/Include/string.h b/StdLib/Include/string.h index 517b9e6e98..0c809441e8 100644 --- a/StdLib/Include/string.h +++ b/StdLib/Include/string.h @@ -1,29 +1,87 @@ /** @file
- The header <string.h> declares one type and several functions, and defines
- one macro useful for manipulating arrays of character type and other objects
- treated as arrays of character type. Various methods are used for
- determining the lengths of the arrays, but in all cases a char * or void *
- argument points to the initial (lowest addressed) character of the array. If
- an array is accessed beyond the end of an object, the behavior is undefined.
-
- Where an argument declared as size_t n specifies the length of the array for
- a function, n can have the value zero on a call to that function. Unless
- explicitly stated otherwise in the description of those functions, pointer
- arguments on such a call shall still have valid values.
-
- For all functions declared in this header, each character shall be
- interpreted as if it had the type unsigned char (and therefore every possible
- object representation is valid and has a different value).
-
-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.
-
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-
+ The header <string.h> declares one type and several functions, and defines
+ one macro useful for manipulating arrays of character type and other objects
+ treated as arrays of character type. Various methods are used for
+ determining the lengths of the arrays, but in all cases a char * or void *
+ argument points to the initial (lowest addressed) character of the array. If
+ an array is accessed beyond the end of an object, the behavior is undefined.
+
+ Where an argument declared as size_t n specifies the length of the array for
+ a function, n can have the value zero on a call to that function. Unless
+ explicitly stated otherwise in the description of those functions, pointer
+ arguments on such a call must still have valid values.
+
+ For all functions declared in this header, each character shall be
+ interpreted as if it had the type unsigned char (and therefore every possible
+ object representation is valid and has a different value).
+
+ The following macros are defined in this file:<BR>
+ @verbatim
+ NULL
+ bcopy(a,b,c) ( memcpy((void *)b, (const void *)a, (size_t)c))
+ bcmp(a,b,c) ( memcmp((void *)a, (void *)b, (size_t)c))
+ @endverbatim
+
+ The following types are defined in this file:<BR>
+ @verbatim
+ size_t Unsigned integer type of the result of the sizeof operator.
+ @endverbatim
+
+ The following functions are declared in this file:<BR>
+ @verbatim
+ ################ Copying Functions
+ void *memcpy (void * __restrict s1, const void * __restrict s2, size_t n);
+ void *memmove (void *s1, const void *s2, size_t n);
+ char *strcpy (char * __restrict s1, const char * __restrict s2);
+ char *strncpy (char * __restrict s1, const char * __restrict s2, size_t n);
+ int strncpyX (char * __restrict s1, const char * __restrict s2, size_t n);
+
+ ################ Concatenation Functions
+ char *strcat (char * __restrict s1, const char * __restrict s2);
+ char *strncat (char * __restrict s1, const char * __restrict s2, size_t n);
+ int strncatX (char * __restrict s1, const char * __restrict s2, size_t n);
+
+ ################ Comparison Functions
+ int memcmp (const void *s1, const void *s2, size_t n);
+ int strcmp (const char *s1, const char *s2);
+ int strcoll (const char *s1, const char *s2);
+ int strncmp (const char *s1, const char *s2, size_t n);
+ size_t strxfrm (char * __restrict s1, const char * __restrict s2, size_t n);
+
+ ################ Search Functions
+ void *memchr (const void *s, int c, size_t n);
+ char *strchr (const char *s, int c);
+ size_t strcspn (const char *s1, const char *s2);
+ char *strpbrk (const char *s1, const char *s2);
+ char *strrchr (const char *s, int c);
+ size_t strspn (const char *s1 , const char *s2);
+ char *strstr (const char *s1 , const char *s2);
+ char *strtok (char * __restrict s1, const char * __restrict s2);
+
+ ################ Miscellaneous Functions
+ void *memset (void *s, int c, size_t n);
+ char *strerror (int num);
+ size_t strlen (const char *);
+
+ ################ BSD Compatibility Functions
+ char *strdup (const char *);
+ int strerror_r (int, char *, size_t);
+ int strcasecmp (const char *s1, const char *s2);
+ void *memccpy (void *, const void *, int, size_t);
+ int strncasecmp (const char *s1, const char *s2, size_t n);
+ size_t strlcpy (char *destination, const char *source, size_t size);
+ size_t strlcat (char *destination, const char *source, size_t size);
+ char *strsep (register char **stringp, register const char *delim);
+ @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.
+
+ 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 _STRING_H
#define _STRING_H
@@ -39,239 +97,311 @@ __BEGIN_DECLS /* ################ Copying Functions ################################# */
-/** The memcpy function copies n characters from the object pointed to by s2
- into the object pointed to by s1. If copying takes place between objects
+/** The memcpy function copies N characters from the object pointed to by Src
+ into the object pointed to by Dest. If copying takes place between objects
that overlap, the behavior is undefined.
- @return The memcpy function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the copy operation.
+ @param[in] Src Pointer to the Source data to be copied.
+ @param[in] N Number of characters (bytes) to be copied.
+
+ @return The memcpy function returns the value of Dest.
**/
-void *memcpy(void * __restrict s1, const void * __restrict s2, size_t n);
+void *memcpy(void * __restrict Dest, const void * __restrict Src, size_t N);
-/** The memmove function copies n characters from the object pointed to by s2
- into the object pointed to by s1. Copying takes place as if the n
- characters from the object pointed to by s2 are first copied into a
- temporary array of n characters that does not overlap the objects pointed
- to by s1 and s2, and then the n characters from the temporary array are
- copied into the object pointed to by s1.
+/** The memmove function copies N characters from the object pointed to by Src
+ into the object pointed to by Dest. Copying takes place as if the N
+ characters from the object pointed to by Src are first copied into a
+ temporary array of N characters that does not overlap the objects pointed
+ to by Dest and Src, and then the N characters from the temporary array are
+ copied into the object pointed to by Dest.
- @return The memmove function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the copy operation.
+ @param[in] Src Pointer to the Source data to be copied.
+ @param[in] N Number of characters (bytes) to be copied.
+
+ @return The memmove function returns the value of Dest.
**/
-void *memmove(void *s1, const void *s2, size_t n);
+void *memmove(void *Dest, const void *Src, size_t N);
-/** The strcpy function copies the string pointed to by s2 (including the
- terminating null character) into the array pointed to by s1. If copying
+/** The strcpy function copies the string pointed to by Src (including the
+ terminating null character) into the array pointed to by Dest. If copying
takes place between objects that overlap, the behavior is undefined.
- @return The strcpy function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the copy operation.
+ @param[in] Src Pointer to the Source data to be copied.
+
+ @return The strcpy function returns the value of Dest.
**/
-char *strcpy(char * __restrict s1, const char * __restrict s2);
+char *strcpy(char * __restrict Dest, const char * __restrict Src);
-/** The strncpy function copies not more than n characters (characters that
- follow a null character are not copied) from the array pointed to by s2 to
- the array pointed to by s1. If copying takes place between objects that
+/** The strncpy function copies not more than N characters (characters that
+ follow a null character are not copied) from the array pointed to by Src to
+ the array pointed to by Dest. If copying takes place between objects that
overlap, the behavior is undefined.
- If the array pointed to by s2 is a string that is shorter than n
+ If the array pointed to by Src is a string that is shorter than N
characters, null characters are appended to the copy in the array pointed
- to by s1, until n characters in all have been written.
+ to by Dest, until N characters in all have been written.
- @return The strncpy function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the copy operation.
+ @param[in] Src Pointer to the Source data to be copied.
+ @param[in] N Number of characters (bytes) to be copied.
+
+ @return The strncpy function returns the value of Dest.
**/
-char *strncpy(char * __restrict s1, const char * __restrict s2, size_t n);
+char *strncpy(char * __restrict Dest, const char * __restrict Src, size_t N);
-/** The strncpyX function copies not more than n-1 characters (characters that
- follow a null character are not copied) from the array pointed to by s2 to
- the array pointed to by s1. Array s1 is guaranteed to be NULL terminated.
+/** The strncpyX function copies not more than N-1 characters (characters that
+ follow a null character are not copied) from the array pointed to by Src to
+ the array pointed to by Dest. Array Dest is guaranteed to be NULL terminated.
If copying takes place between objects that overlap,
the behavior is undefined.
strncpyX exists because normal strncpy does not indicate if the copy was
- terminated because of exhausting the buffer or reaching the end of s2.
+ terminated because of exhausting the buffer or reaching the end of Src.
+
+ @param[out] Dest Pointer to the destination of the copy operation.
+ @param[in] Src Pointer to the Source data to be copied.
+ @param[in] N Number of characters (bytes) to be copied.
@return The strncpyX function returns 0 if the copy operation was
- terminated because it reached the end of s1. Otherwise,
+ terminated because it reached the end of Dest. Otherwise,
a non-zero value is returned indicating how many characters
- remain in s1.
+ remain in Dest.
**/
-int strncpyX(char * __restrict s1, const char * __restrict s2, size_t n);
+int strncpyX(char * __restrict Dest, const char * __restrict Src, size_t N);
/* ################ Concatenation Functions ########################### */
-/** The strcat function appends a copy of the string pointed to by s2
+/** The strcat function appends a copy of the string pointed to by Src
(including the terminating null character) to the end of the string pointed
- to by s1. The initial character of s2 overwrites the null character at the
- end of s1. If copying takes place between objects that overlap, the
+ to by Dest. The initial character of Src overwrites the null character at the
+ end of Dest. If copying takes place between objects that overlap, the
behavior is undefined.
- @return The strcat function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the concatenation operation.
+ @param[in] Src Pointer to the Source data to be concatenated.
+
+ @return The strcat function returns the value of Dest.
**/
-char *strcat(char * __restrict s1, const char * __restrict s2);
+char *strcat(char * __restrict Dest, const char * __restrict Src);
-/** The strncat function appends not more than n characters (a null character
+/** The strncat function appends not more than N characters (a null character
and characters that follow it are not appended) from the array pointed to
- by s2 to the end of the string pointed to by s1. The initial character of
- s2 overwrites the null character at the end of s1. A terminating null
+ by Src to the end of the string pointed to by Dest. The initial character of
+ Src overwrites the null character at the end of Dest. A terminating null
character is always appended to the result. If copying takes place
between objects that overlap, the behavior is undefined.
- @return The strncat function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the concatenation operation.
+ @param[in] Src Pointer to the Source data to be concatenated.
+ @param[in] N Max Number of characters (bytes) to be concatenated.
+
+ @return The strncat function returns the value of Dest.
**/
-char *strncat(char * __restrict s1, const char * __restrict s2, size_t n);
+char *strncat(char * __restrict Dest, const char * __restrict Src, size_t N);
-/** The strncatX function appends not more than n characters (a null character
+/** The strncatX function appends not more than N characters (a null character
and characters that follow it are not appended) from the array pointed to
- by s2 to the end of the string pointed to by s1. The initial character of
- s2 overwrites the null character at the end of s1. The result is always
+ by Src to the end of the string pointed to by Dest. The initial character of
+ Src overwrites the null character at the end of Dest. The result is always
terminated with a null character. If copying takes place between objects
that overlap, the behavior is undefined.
strncatX exists because normal strncat does not indicate if the operation
- was terminated because of exhausting n or reaching the end of s2.
+ was terminated because of exhausting N or reaching the end of Src.
+
+ @param[out] Dest Pointer to the destination of the concatenation operation.
+ @param[in] Src Pointer to the Source data to be concatenated.
+ @param[in] N Max Number of characters (bytes) to be concatenated.
@return The strncatX function returns 0 if the operation was terminated
- because it reached the end of s1. Otherwise, a non-zero value is
- returned indicating how many characters remain in s1.
+ because it reached the end of Dest. Otherwise, a non-zero value is
+ returned indicating how many characters remain in Dest.
**/
int strncatX(char * __restrict s1, const char * __restrict s2, size_t n);
/* ################ Comparison Functions ############################## */
-/** The memcmp function compares the first n characters of the object pointed
- to by s1 to the first n characters of the object pointed to by s2.
+/** The memcmp function compares the first N characters of the object pointed
+ to by S1 to the first N characters of the object pointed to by S2.
+
+ @param[out] S1 Pointer to the first object to be compared.
+ @param[in] S2 Pointer to the object to be compared to S1.
+ @param[in] N Max Number of characters (bytes) to be compared.
@return The memcmp function returns an integer greater than, equal to, or
- less than zero, accordingly as the object pointed to by s1 is
- greater than, equal to, or less than the object pointed to by s2.
+ less than zero, accordingly as the object pointed to by S1 is
+ greater than, equal to, or less than the object pointed to by S2.
**/
-int memcmp(const void *s1, const void *s2, size_t n);
+int memcmp(const void *S1, const void *S2, size_t N);
-/** The strcmp function compares the string pointed to by s1 to the string
- pointed to by s2.
+/** The strcmp function compares the string pointed to by S1 to the string
+ pointed to by S2.
+
+ @param[out] S1 Pointer to the first string to be compared.
+ @param[in] S2 Pointer to the string to be compared to S1.
@return The strcmp function returns an integer greater than, equal to, or
- less than zero, accordingly as the string pointed to by s1 is
- greater than, equal to, or less than the string pointed to by s2.
+ less than zero, accordingly as the string pointed to by S1 is
+ greater than, equal to, or less than the string pointed to by S2.
**/
-int strcmp(const char *s1, const char *s2);
+int strcmp(const char *S1, const char *S2);
-/** The strcoll function compares the string pointed to by s1 to the string
- pointed to by s2, both interpreted as appropriate to the LC_COLLATE
+/** The strcoll function compares the string pointed to by S1 to the string
+ pointed to by S2, both interpreted as appropriate to the LC_COLLATE
category of the current locale.
+ @param[out] S1 Pointer to the first string to be compared.
+ @param[in] S2 Pointer to the string to be compared to S1.
+
@return The strcoll function returns an integer greater than, equal to,
- or less than zero, accordingly as the string pointed to by s1 is
- greater than, equal to, or less than the string pointed to by s2
+ or less than zero, accordingly as the string pointed to by S1 is
+ greater than, equal to, or less than the string pointed to by S2
when both are interpreted as appropriate to the current locale.
**/
-int strcoll(const char *s1, const char *s2);
+int strcoll(const char *S1, const char *S2);
+
+/** The strncmp function compares not more than N characters (characters that
+ follow a null character are not compared) from the array pointed to by S1
+ to the array pointed to by S2.
-/** The strncmp function compares not more than n characters (characters that
- follow a null character are not compared) from the array pointed to by s1
- to the array pointed to by s2.
+ @param[out] S1 Pointer to the first object to be compared.
+ @param[in] S2 Pointer to the object to be compared to S1.
+ @param[in] N Max Number of characters (bytes) to be compared.
@return The strncmp function returns an integer greater than, equal to,
or less than zero, accordingly as the possibly null-terminated
- array pointed to by s1 is greater than, equal to, or less than
- the possibly null-terminated array pointed to by s2.
+ array pointed to by S1 is greater than, equal to, or less than
+ the possibly null-terminated array pointed to by S2.
**/
-int strncmp(const char *s1, const char *s2, size_t n);
+int strncmp(const char *S1, const char *S2, size_t N);
-/** The strxfrm function transforms the string pointed to by s2 and places the
- resulting string into the array pointed to by s1. The transformation is
+/** The strxfrm function transforms the string pointed to by Src and places the
+ resulting string into the array pointed to by Dest. The transformation is
such that if the strcmp function is applied to two transformed strings, it
returns a value greater than, equal to, or less than zero, corresponding to
the result of the strcoll function applied to the same two original
- strings. No more than n characters are placed into the resulting array
- pointed to by s1, including the terminating null character. If n is zero,
- s1 is permitted to be a null pointer. If copying takes place between
+ strings. No more than N characters are placed into the resulting array
+ pointed to by Dest, including the terminating null character. If N is zero,
+ Dest is permitted to be a null pointer. If copying takes place between
objects that overlap, the behavior is undefined.
+ @param[out] Dest Pointer to the object to receive the transformed string.
+ @param[in] Src Pointer to the string to be transformed.
+ @param[in] N Max Number of characters (bytes) to be transformed.
+
@return The strxfrm function returns the length of the transformed string
(not including the terminating null character). If the value
- returned is n or more, the contents of the array pointed to by s1
+ returned is N or more, the contents of the array pointed to by Dest
are indeterminate.
**/
-size_t strxfrm(char * __restrict s1, const char * __restrict s2, size_t n);
+size_t strxfrm(char * __restrict Dest, const char * __restrict Src, size_t N);
/* ################ Search Functions ################################## */
-/** The memchr function locates the first occurrence of c (converted to an
- unsigned char) in the initial n characters (each interpreted as
- unsigned char) of the object pointed to by s.
+/** The memchr function locates the first occurrence of C (converted to an
+ unsigned char) in the initial N characters (each interpreted as
+ unsigned char) of the object pointed to by S.
+
+ @param[in] S Pointer to the object to be searched.
+ @param[in] C The character value to search for.
+ @param[in] N Max Number of characters (bytes) to be searched.
@return The memchr function returns a pointer to the located character,
or a null pointer if the character does not occur in the object.
**/
-void *memchr(const void *s, int c, size_t n);
+void *memchr(const void *S, int C, size_t N);
-/** The strchr function locates the first occurrence of c (converted to a char)
- in the string pointed to by s. The terminating null character is considered
+/** The strchr function locates the first occurrence of C (converted to a char)
+ in the string pointed to by S. The terminating null character is considered
to be part of the string.
+ @param[in] S Pointer to the object to be searched.
+ @param[in] C The character value to search for.
+
@return The strchr function returns a pointer to the located character,
or a null pointer if the character does not occur in the string.
**/
-char *strchr(const char *s, int c);
+char *strchr(const char *S, int C);
/** The strcspn function computes the length of the maximum initial segment of
- the string pointed to by s1 which consists entirely of characters NOT from
- the string pointed to by s2.
+ the string pointed to by S1 which consists entirely of characters NOT from
+ the string pointed to by S2.
+
+ @param[in] S1 Pointer to the object to be searched.
+ @param[in] S2 Pointer to the list of characters to search for.
@return The strcspn function returns the length of the segment.
**/
-size_t strcspn(const char *s1, const char *s2);
+size_t strcspn(const char *S1, const char *S2);
/** The strpbrk function locates the first occurrence in the string pointed to
- by s1 of any character from the string pointed to by s2.
+ by S1 of any character from the string pointed to by S2.
+
+ @param[in] S1 Pointer to the object to be searched.
+ @param[in] S2 Pointer to the list of characters to search for.
@return The strpbrk function returns a pointer to the character, or a
- null pointer if no character from s2 occurs in s1.
+ null pointer if no character from S2 occurs in S1.
**/
-char *strpbrk(const char *s1, const char *s2);
+char *strpbrk(const char *S1, const char *S2);
-/** The strrchr function locates the last occurrence of c (converted to a char)
- in the string pointed to by s. The terminating null character is considered
+/** The strrchr function locates the last occurrence of C (converted to a char)
+ in the string pointed to by S. The terminating null character is considered
to be part of the string.
+ @param[in] S Pointer to the object to be searched.
+ @param[in] C The character value to search for.
+
@return The strrchr function returns a pointer to the character, or a
- null pointer if c does not occur in the string.
+ null pointer if C does not occur in the string.
**/
-char *strrchr(const char *s, int c);
+char *strrchr(const char *S, int C);
/** The strspn function computes the length of the maximum initial segment of
- the string pointed to by s1 which consists entirely of characters from the
- string pointed to by s2.
+ the string pointed to by S1 which consists entirely of characters from the
+ string pointed to by S2.
+
+ @param[in] S1 Pointer to the object to be searched.
+ @param[in] S2 Pointer to the list of characters to search for.
@return The strspn function returns the length of the segment.
**/
-size_t strspn(const char *s1 , const char *s2);
+size_t strspn(const char *S1 , const char *S2);
/** The strstr function locates the first occurrence in the string pointed to
- by s1 of the sequence of characters (excluding the terminating null
- character) in the string pointed to by s2.
+ by S1 of the sequence of characters (excluding the terminating null
+ character) in the string pointed to by S2.
+
+ @param[in] S1 Pointer to the object to be searched.
+ @param[in] S2 Pointer to the sequence of characters to search for.
@return The strstr function returns a pointer to the located string, or a
- null pointer if the string is not found. If s2 points to a string
- with zero length, the function returns s1.
+ null pointer if the string is not found. If S2 points to a string
+ with zero length, the function returns S1.
**/
-char *strstr(const char *s1 , const char *s2);
+char *strstr(const char *S1 , const char *S2);
+
+/** Break a string into a sequence of tokens.
-/** A sequence of calls to the strtok function breaks the string pointed to by
- s1 into a sequence of tokens, each of which is delimited by a character
- from the string pointed to by s2. The first call in the sequence has a
+ A sequence of calls to the strtok function breaks the string pointed to by
+ S1 into a sequence of tokens, each of which is delimited by a character
+ from the string pointed to by S2. The first call in the sequence has a
non-null first argument; subsequent calls in the sequence have a null first
- argument. The separator string pointed to by s2 may be different from call
+ argument. The separator string pointed to by S2 may be different from call
to call.
- The first call in the sequence searches the string pointed to by s1 for the
+ The first call in the sequence searches the string pointed to by S1 for the
first character that is not contained in the current separator string
- pointed to by s2. If no such character is found, then there are no tokens
- in the string pointed to by s1 and the strtok function returns a null
+ pointed to by S2. If no such character is found, then there are no tokens
+ in the string pointed to by S1 and the strtok function returns a null
pointer. If such a character is found, it is the start of the first token.
The strtok function then searches from there for a character that is
contained in the current separator string. If no such character is found,
- the current token extends to the end of the string pointed to by s1, and
+ the current token extends to the end of the string pointed to by S1, and
subsequent searches for a token will return a null pointer. If such a
character is found, it is overwritten by a null character, which terminates
the current token. The strtok function saves a pointer to the following
@@ -281,40 +411,48 @@ char *strstr(const char *s1 , const char *s2); argument, starts searching from the saved pointer and behaves as
described above.
+ @param[in] S1 Pointer to the string to be tokenized.
+ @param[in] S2 Pointer to a list of separator characters.
+
@return The strtok function returns a pointer to the first character of a
token, or a null pointer if there is no token.
**/
-char *strtok(char * __restrict s1, const char * __restrict s2);
+char *strtok(char * __restrict S1, const char * __restrict S2);
/* ################ Miscellaneous Functions ########################### */
-/** The memset function copies the value of c (converted to an unsigned char)
- into each of the first n characters of the object pointed to by s.
+/** The memset function copies the value of C (converted to an unsigned char)
+ into each of the first N characters of the object pointed to by S.
+
+ @param[out] S Pointer to the first element of the object to be set.
+ @param[in] C Value to store in each element of S.
+ @param[in] N Number of elements in S to be set.
- @return The memset function returns the value of s.
+ @return The memset function returns the value of S.
**/
-void *memset(void *s, int c, size_t n);
+void *memset(void *S, int C, size_t N);
-/** The strerror function maps the number in errnum to a message string.
- Typically, the values for errnum come from errno, but strerror shall map
+/** The strerror function maps the number in Num to a message string.
+ Typically, the values for Num come from errno, but strerror shall map
any value of type int to a message.
- The implementation shall behave as if no library function calls the
- strerror function.
+ @param[in] Num A value to be converted to a message.
@return The strerror function returns a pointer to the string, the
contents of which are locale specific. The array pointed to
- shall not be modified by the program, but may be overwritten by
+ must not be modified by the program, but may be overwritten by
a subsequent call to the strerror function.
**/
-char *strerror(int num);
+char *strerror(int Num);
+
+/** The strlen function computes the length of the string pointed to by S.
-/** The strlen function computes the length of the string pointed to by s.
+ @param[in] S Pointer to the string to determine the length of.
@return The strlen function returns the number of characters that
precede the terminating null character.
**/
-size_t strlen(const char *);
+size_t strlen(const char *S);
/* ################ BSD Compatibility Functions ####################### */
diff --git a/StdLib/Include/sys/EfiSysCall.h b/StdLib/Include/sys/EfiSysCall.h index a49eeda1fc..bfbd14e1c5 100644 --- a/StdLib/Include/sys/EfiSysCall.h +++ b/StdLib/Include/sys/EfiSysCall.h @@ -1,17 +1,74 @@ /** @file
Function declarations for UEFI "system calls".
- Concept derived from NetBSD's unistd.h file.
+ The following macros are defined in this file:<BR>
+@verbatim
+ STDIN_FILENO 0 standard input file descriptor
+ STDOUT_FILENO 1 standard output file descriptor
+ STDERR_FILENO 2 standard error file descriptor
+ F_OK 0 test for existence of file
+ X_OK 0x01 test for execute or search permission
+ W_OK 0x02 test for write permission
+ R_OK 0x04 test for read permission
+ SEEK_SET 0 set file offset to offset
+ SEEK_CUR 1 set file offset to current plus offset
+ SEEK_END 2 set file offset to EOF plus offset
+ VALID_OPEN 1
+ VALID_CLOSED 0
+ VALID_DONT_CARE -1
+@endverbatim
+
+ The following types are defined in this file:<BR>
+@verbatim
+ struct stat; Structure declared in <sys/stat.h>
+@endverbatim
+
+ The following functions are declared in this file:<BR>
+@verbatim
+ ############### System Calls used in stdio.
+ int close (int fd);
+ ssize_t read (int fd, void *buf, size_t n);
+ ssize_t write (int fd, const void *buf, size_t n);
+ int unlink (const char *name);
+ int dup2 (int, int);
+ int rmdir (const char *);
+ int isatty (int);
+
+ ############### System Calls which are also declared in sys/fcntl.h.
+ int open (const char *name, int oflags, int mode);
+ int creat (const char *, mode_t);
+ int fcntl (int, int, ...);
+
+ ############### System Calls which are also declared in stat.h.
+ int mkdir (const char *, mode_t);
+ int fstat (int, struct stat *);
+ int lstat (const char *, struct stat *);
+ int stat (const char *, void *);
+ int chmod (const char *, mode_t);
+
+ ############### System Calls which are also declared in sys/types.h.
+ off_t lseek (int, off_t, int);
+ int truncate (const char *, off_t);
+ int ftruncate (int, off_t); // IEEE Std 1003.1b-93
+
+ ############### EFI-specific Functions.
+ int DeleteOnClose (int fd); Mark an open file to be deleted when closed.
+ int FindFreeFD (int MinFd);
+ BOOLEAN ValidateFD (int fd, int IsOpen);
+
+ ############### Functions added for compatibility.
+ char *getcwd (char *, size_t);
+ int chdir (const char *);
+@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 _EFI_SYS_CALL_H
#define _EFI_SYS_CALL_H
@@ -21,27 +78,27 @@ struct stat; /* Structure declared in <sys/stat.h> */
-#define STDIN_FILENO 0 /* standard input file descriptor */
-#define STDOUT_FILENO 1 /* standard output file descriptor */
-#define STDERR_FILENO 2 /* standard error file descriptor */
+#define STDIN_FILENO 0 /**< standard input file descriptor */
+#define STDOUT_FILENO 1 /**< standard output file descriptor */
+#define STDERR_FILENO 2 /**< standard error file descriptor */
/* access function */
-#define F_OK 0 /* test for existence of file */
-#define X_OK 0x01 /* test for execute or search permission */
-#define W_OK 0x02 /* test for write permission */
-#define R_OK 0x04 /* test for read permission */
+#define F_OK 0 /**< test for existence of file */
+#define X_OK 0x01 /**< test for execute or search permission */
+#define W_OK 0x02 /**< test for write permission */
+#define R_OK 0x04 /**< test for read permission */
/* whence values for lseek(2)
Always ensure that these are consistent with <stdio.h> and <unistd.h>!
*/
#ifndef SEEK_SET
- #define SEEK_SET 0 /* set file offset to offset */
+ #define SEEK_SET 0 /**< set file offset to offset */
#endif
#ifndef SEEK_CUR
- #define SEEK_CUR 1 /* set file offset to current plus offset */
+ #define SEEK_CUR 1 /**< set file offset to current plus offset */
#endif
#ifndef SEEK_END
- #define SEEK_END 2 /* set file offset to EOF plus offset */
+ #define SEEK_END 2 /**< set file offset to EOF plus offset */
#endif
// Parameters for the ValidateFD function.
@@ -50,44 +107,234 @@ struct stat; /* Structure declared in <sys/stat.h> */ #define VALID_DONT_CARE -1
__BEGIN_DECLS
-
/* EFI versions of BSD system calls used in stdio */
-int close (int fd);
-ssize_t read (int fd, void *buf, size_t n);
-ssize_t write (int fd, const void *buf, size_t n);
-int unlink (const char *name);
-int dup2 (int, int);
-int rmdir (const char *);
-int isatty (int);
+
+ /** Close a file or device.
+
+ @param[in] fd File Descriptor for the file or device to close.
+
+ @retval 0 Successful completion.
+ @retval -1 An error occurred, identified by errno.
+ - EBADF fd is not a valid File Descriptor.
+ - EINTR The function was interrupted by a signal.
+ - EIO An I/O error occurred.
+ **/
+ int close (int fd);
+
+ /** Read from a file or device.
+
+ @param[in] fd File Descriptor for the file or device to read.
+ @param[in] buf Buffer to read data into.
+ @param[in] N Maximum number of bytes to read.
+
+ @return On successful completion, read returns a non-negative integer
+ indicating the number of bytes actually read. Otherwise, it
+ returns -1 and sets errno as follows:
+ - EAGAIN
+ - EWOULDBLOCK
+ - EBADF
+ - EBADMSG
+ - EINTR
+ - EINVAL
+ - EIO
+ - EISDIR
+ - EOVERFLOW
+ - ECONNRESET
+ - ENOTCONN
+ - ETIMEDOUT
+ - ENOBUFS
+ - ENOMEM
+ - ENXIO
+ **/
+ ssize_t read (int fd, void *buf, size_t n);
+
+ /** Write to a file or device.
+
+ @param[in] fd File Descriptor for the file or device to write.
+ @param[in] buf Buffer to write data from.
+ @param[in] N Maximum number of bytes to write.
+
+ @return On successful completion, write returns a non-negative integer
+ indicating the number of bytes actually written. Otherwise, it
+ returns -1 and sets errno as follows:
+ - EAGAIN
+ - EWOULDBLOCK
+ - EBADF
+ - EFBIG
+ - EINTR
+ - EINVAL
+ - EIO
+ - ENOSPC
+ - EPIPE
+ - ERANGE
+ - ECONNRESET
+ - ENOBUFS
+ - ENXIO
+ - ENETDOWN
+ - ENETUNREACH
+ **/
+ ssize_t write (int fd, const void *buf, size_t n);
+
+ /** Unlink (delete) a file.
+
+ @param[in] name The name of the file to be deleted.
+
+ @retval 0 Successful completion.
+ @retval -1 Unable to perform operation, errno contains further
+ information. The file name is unchanged.
+ **/
+ int unlink (const char *name);
+
+ /** Make file descriptor Fd2 a duplicate of file descriptor Fd1.
+
+ @param[in] Fd1 File descriptor to be duplicated
+ @param[in] Fd2 File descriptor to become a duplicate of Fd1.
+
+ @retval 0 Successful completion.
+ @retval -1 Unable to perform operation, errno contains further
+ information.
+ **/
+ int dup2 (int Fd1, int Fd2);
+
+ /** Remove a directory.
+
+ @param[in] Path Path to the directory to be deleted.
+
+ @retval 0 Successful completion.
+ @retval -1 Unable to perform operation, errno contains further
+ information. The named directory remains unchanged.
+ **/
+ int rmdir (const char *Path);
+
+ /** Determine if fd refers to an interactive terminal device.
+
+ @param[in] fd The file descriptor to be tested.
+
+ @retval 0 The file descriptor, fd, is not for a terminal. errno is set
+ indicating the cause for failure.
+ - EBADF fd is not a valid open file descriptor.
+ - ENOTTY fd does not refer to a terminal.
+ @retval 1 The file descriptor, fd, is for a terminal.
+ **/
+ int isatty (int fd);
/* These system calls are also declared in sys/fcntl.h */
#ifndef __FCNTL_SYSCALLS_DECLARED
#define __FCNTL_SYSCALLS_DECLARED
+
+ /** Open or create a file named by name.
+
+ The file name may be one of:
+ - An absolute path beginning with '/'.
+ - A relative path beginning with "." or ".." or a directory name
+ - A file name
+ - A mapped path which begins with a name followed by a colon, ':'.
+
+ Mapped paths are use to refer to specific mass storage volumes or devices.
+ In a Shell-hosted environment, the map command will list valid map names
+ for both file system and block devices. Mapped paths can also refer to
+ devices such as the UEFI console. Supported UEFI console mapped paths are:
+ - stdin: Standard Input (from the System Table)
+ - stdout: Standard Output (from the System Table)
+ - stderr: Standard Error Output (from the System Table)
+
+ @param[in] name
+ @param[in] oflags
+ @param[in] mode
+
+ @return
+ **/
int open (const char *name, int oflags, int mode);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int creat (const char *, mode_t);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int fcntl (int, int, ...);
#endif // __FCNTL_SYSCALLS_DECLARED
/* These system calls are also declared in stat.h */
#ifndef __STAT_SYSCALLS_DECLARED
#define __STAT_SYSCALLS_DECLARED
+
+ /**
+ @param[in]
+
+ @return
+ **/
int mkdir (const char *, mode_t);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int fstat (int, struct stat *);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int lstat (const char *, struct stat *);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int stat (const char *, void *);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int chmod (const char *, mode_t);
#endif // __STAT_SYSCALLS_DECLARED
// These are also declared in sys/types.h
#ifndef __OFF_T_SYSCALLS_DECLARED
#define __OFF_T_SYSCALLS_DECLARED
+
+ /**
+ @param[in]
+
+ @return
+ **/
off_t lseek (int, off_t, int);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int truncate (const char *, off_t);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int ftruncate (int, off_t); // IEEE Std 1003.1b-93
#endif /* __OFF_T_SYSCALLS_DECLARED */
/* EFI-specific Functions. */
-int DeleteOnClose(int fd); /* Mark an open file to be deleted when closed. */
+
+ /**
+ @param[in]
+
+ @return
+ **/
+ int DeleteOnClose(int fd); /* Mark an open file to be deleted when closed. */
/* Find and reserve a free File Descriptor.
@@ -97,7 +344,7 @@ int DeleteOnClose(int fd); /* Mark an open file to be deleted when clos @return Returns -1 if there are no free FDs. Otherwise returns the
found fd.
*/
-int FindFreeFD (int MinFd);
+ int FindFreeFD (int MinFd);
/* Validate that fd refers to a valid file descriptor.
IsOpen is interpreted as follows:
@@ -108,15 +355,26 @@ int FindFreeFD (int MinFd); @retval TRUE fd is VALID
@retval FALSE fd is INVALID
*/
-BOOLEAN ValidateFD (int fd, int IsOpen);
+ BOOLEAN ValidateFD (int fd, int IsOpen);
-char *getcwd (char *, size_t);
-int chdir (const char *);
-/* These system calls don't YET have EFI implementations. */
-int access (const char *path, int amode);
-int reboot (int, char *);
+ /**
+ @param[in]
+
+ @return
+ **/
+ char *getcwd (char *, size_t);
+ /**
+ @param[in]
+
+ @return
+ **/
+ int chdir (const char *);
+
+/* These system calls don't YET have EFI implementations. */
+ int access (const char *path, int amode);
+ int reboot (int, char *);
__END_DECLS
#endif /* _EFI_SYS_CALL_H */
diff --git a/StdLib/Include/time.h b/StdLib/Include/time.h index a0ebbb9881..ecef1e2f61 100644 --- a/StdLib/Include/time.h +++ b/StdLib/Include/time.h @@ -33,6 +33,40 @@ if Daylight Saving Time is not in effect, and negative if the information
is not available.
+ The following macros are defined in this file:<BR>
+ @verbatim
+ NULL
+ CLOCKS_PER_SEC The number of values per second returned by the clock function.
+ @endverbatim
+
+ The following types are defined in this file:<BR>
+ @verbatim
+ size_t Unsigned integer type of the result of the sizeof operator.
+ clock_t Arithmetic type capable of representing a time from the clock function.
+ time_t Arithmetic type capable of representing a time.
+ struct tm Holds the components of a calendar time; or broken-down time.
+ @endverbatim
+
+ The following functions are declared in this file:<BR>
+ @verbatim
+ ############### Time Manipulation Functions
+ clock_t clock (void);
+ double difftime (time_t time1, time_t time0);
+ time_t mktime (struct tm *timeptr);
+ time_t time (time_t *timer);
+
+ ################# Time Conversion Functions
+ char * asctime (const struct tm *timeptr);
+ char * ctime (const time_t *timer);
+ struct tm * gmtime (const time_t *timer);
+ time_t timegm (struct tm*);
+ struct tm * localtime (const time_t *timer);
+ size_t strftime (char * __restrict s, size_t maxsize,
+ const char * __restrict format,
+ const struct tm * __restrict timeptr);
+ char * strptime (const char *, const char * format, struct tm*);
+ @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.
@@ -41,7 +75,6 @@ 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 _TIME_H
#define _TIME_H
@@ -55,26 +88,25 @@ #undef _BSD_SIZE_T_
#endif
-/** An arithmetic type capable of representing values returned by clock(); **/
#ifdef _EFI_CLOCK_T
+ /** An arithmetic type capable of representing values returned by clock(); **/
typedef _EFI_CLOCK_T clock_t;
#undef _EFI_CLOCK_T
#endif
-/** An arithmetic type capable of representing values returned as calendar time
- values, such as that returned by mktime();
-**/
#ifdef _EFI_TIME_T
+ /** An arithmetic type capable of representing values returned as calendar time
+ values, such as that returned by mktime();
+ **/
typedef _EFI_TIME_T time_t;
#undef _EFI_TIME_T
#endif
-/** Value added to tm_year to get the full year value. TM_YEAR_BASE + 110 --> 2010
-**/
+/** Value added to tm_year to get the full year value. TM_YEAR_BASE + 110 --> 2010 **/
#define TM_YEAR_BASE 1900
-/** Values for the tm_wday member of struct tm.
- @{
+/** @{
+ Values for the tm_wday member of struct tm.
**/
#define TM_SUNDAY 0
#define TM_MONDAY 1
@@ -83,10 +115,10 @@ #define TM_THURSDAY 4
#define TM_FRIDAY 5
#define TM_SATURDAY 6
-/** @} **/
+/*@}*/
-/** Values for the tm_mon member of struct tm.
- @{
+/** @{
+ Values for the tm_mon member of struct tm.
**/
#define TM_JANUARY 0
#define TM_FEBRUARY 1
@@ -100,7 +132,7 @@ #define TM_OCTOBER 9
#define TM_NOVEMBER 10
#define TM_DECEMBER 11
-/** @} **/
+/*@}*/
/** A structure holding the components of a calendar time, called the
broken-down time. The first nine (9) members are as mandated by the
@@ -133,17 +165,21 @@ struct tm { the macro CLOCKS_PER_SEC. If the processor time used is not
available or its value cannot be represented, the function
returns the value (clock_t)(-1).
-
- On IA32 or X64 platforms, the value returned is the number of
- CPU TimeStamp Counter ticks since the appliation started.
**/
clock_t clock(void);
-/**
+/** Compute the difference between two calendar times: time1 - time0.
+
+ @param[in] time1 An arithmetic calendar time.
+ @param[in] time2 Another arithmetic calendar time.
+
+ @return The difference between the two times expressed in seconds.
**/
double difftime(time_t time1, time_t time0);
-/** The mktime function converts the broken-down time, expressed as local time,
+/** Convert a broken-down time into an arithmetic calendar time.
+
+ The mktime function converts the broken-down time, expressed as local time,
in the structure pointed to by timeptr into a calendar time value with the
same encoding as that of the values returned by the time function. The
original values of the tm_wday and tm_yday components of the structure are
@@ -155,6 +191,8 @@ double difftime(time_t time1, time_t time0); the final value of tm_mday is not set until tm_mon and tm_year
are determined.
+ @param[in] timeptr Pointer to a broken-down time to be converted.
+
@return The mktime function returns the specified calendar time encoded
as a value of type time_t. If the calendar time cannot be
represented, the function returns the value (time_t)(-1).
@@ -163,7 +201,10 @@ time_t mktime(struct tm *timeptr); /** The time function determines the current calendar time.
- The encoding of the value is unspecified.
+ The encoding of the value is unspecified and undocumented.
+
+ @param[out] timer An optional pointer to an object in which to
+ store the calendar time.
@return The time function returns the implementation's best approximation
of the current calendar time. The value (time_t)(-1) is returned
@@ -176,23 +217,33 @@ time_t time(time_t *timer); /* ################# Time Conversion Functions ########################## */
/** The asctime function converts the broken-down time in the structure pointed
- to by timeptr into a string in the form
+ to by timeptr into a string in the form<BR>
+ @verbatim
Sun Sep 16 01:03:52 1973\n\0
+ @endverbatim
+
+ @param[in] timeptr A pointer to a broken-down time to convert.
@return The asctime function returns a pointer to the string.
**/
char * asctime(const struct tm *timeptr);
-/** The ctime function converts the calendar time pointed to by timer to local
+/** The ctime function converts the calendar time pointed to by timer to a local
time in the form of a string. It is equivalent to asctime(localtime(timer))
+ @param[in] timer Pointer to a calendar time value to convert into a
+ string representation.
+
@return The ctime function returns the pointer returned by the asctime
function with that broken-down time as argument.
**/
char * ctime(const time_t *timer);
/** The gmtime function converts the calendar time pointed to by timer into a
- brokendown time, expressed as UTC.
+ broken-down time, expressed as UTC.
+
+ @param[in] timer Pointer to a calendar time value to convert into a
+ broken-down time.
@return The gmtime function returns a pointer to the broken-down time,
or a null pointer if the specified time cannot be converted to UTC.
@@ -201,6 +252,9 @@ struct tm * gmtime(const time_t *timer); /** The timegm function is the opposite of gmtime.
+ @param[in] tm Pointer to a broken-down time to convert into a
+ calendar time.
+
@return The calendar time expressed as UTC.
**/
time_t timegm(struct tm*);
@@ -208,6 +262,8 @@ time_t timegm(struct tm*); /** The localtime function converts the calendar time pointed to by timer into
a broken-down time, expressed as local time.
+ @param[in] timer Pointer to a calendar time value to be converted.
+
@return The localtime function returns a pointer to the broken-down time,
or a null pointer if the specified time cannot be converted to
local time.
diff --git a/StdLib/Include/wchar.h b/StdLib/Include/wchar.h index bab02b05b9..7a064ee0b4 100644 --- a/StdLib/Include/wchar.h +++ b/StdLib/Include/wchar.h @@ -9,15 +9,155 @@ in this file causes copying to take place between objects that overlap, the
behavior is undefined.
- Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
+ The following macros are defined in this file:<BR>
+ @verbatim
+ NULL Actually defined in <sys/EfiCdefs.h>
+ WCHAR_MIN Minimum value of a wide char.
+ WCHAR_MAX Maximum value of a wide char.
+ WEOF Wide char version of end-of-file.
+ @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 Type of wide characters.
+ wint_t Type capable of holding all wchar_t values and WEOF.
+ mbstate_t Type of object holding multibyte conversion state.
+ struct tm Incomplete declaration of the broken-down time structure.
+ @endverbatim
+
+ The following functions are declared in this file:<BR>
+@verbatim
+ ############### Formatted Input/Output Functions
+ int fwprintf (FILE * __restrict stream,
+ const wchar_t * __restrict format, ...);
+ int fwscanf (FILE * __restrict stream,
+ const wchar_t * __restrict format, ...);
+ int swprintf (wchar_t * __restrict s, size_t n,
+ const wchar_t * __restrict format, ...);
+ int swscanf (const wchar_t * __restrict s,
+ const wchar_t * __restrict format, ...);
+ int vfwprintf (FILE * __restrict stream,
+ const wchar_t * __restrict format, va_list arg);
+ int vfwscanf (FILE * __restrict stream,
+ const wchar_t * __restrict format, va_list arg);
+ int vswprintf (wchar_t * __restrict s, size_t n,
+ const wchar_t * __restrict format, va_list arg);
+ int vswscanf (const wchar_t * __restrict s,
+ const wchar_t * __restrict format, va_list arg);
+ int vwprintf (const wchar_t * __restrict format, va_list arg);
+ int vwscanf (const wchar_t * __restrict format, va_list arg);
+ int wprintf (const wchar_t * __restrict format, ...);
+ int wscanf (const wchar_t * __restrict format, ...);
+
+ ################### Input/Output Functions
+ wint_t fgetwc (FILE *stream);
+ wchar_t *fgetws (wchar_t * __restrict S, int n,
+ FILE * __restrict stream);
+ wint_t fputwc (wchar_t c, FILE *stream);
+ int fputws (const wchar_t * __restrict S,
+ FILE * __restrict stream);
+ int fwide (FILE *stream, int mode);
+ wint_t getwc (FILE *stream);
+ wint_t getwchar (void);
+ wint_t putwc (wchar_t c, FILE *stream);
+ wint_t putwchar (wchar_t c);
+ wint_t ungetwc (wint_t c, FILE *stream);
+
+ ################### Numeric Conversions
+ double wcstod (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr);
+ float wcstof (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr);
+ long double wcstold (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr);
+ long int wcstol (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr, int base);
+ long long int wcstoll (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr, int base);
+ unsigned long int wcstoul (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr, int base);
+ unsigned long long int wcstoull (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr, int base);
+
+ ####################### String Copying
+ wchar_t *wcscpy (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2);
+ wchar_t *wcsncpy (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2, size_t n);
+ wchar_t *wmemcpy (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2, size_t n);
+ wchar_t *wmemmove (wchar_t *s1, const wchar_t *s2, size_t n);
+
+ ################### String Concatenation
+ wchar_t *wcscat (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2);
+ wchar_t *wcsncat (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2, size_t n);
+
+ ##################### String Comparison
+ int wcscmp (const wchar_t *s1, const wchar_t *s2);
+ int wcscoll (const wchar_t *s1, const wchar_t *s2);
+ int wcsncmp (const wchar_t *s1, const wchar_t *s2, size_t n);
+ size_t wcsxfrm (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2, size_t n);
+ int wmemcmp (const wchar_t *s1, const wchar_t *s2, size_t n);
+
+ ##################### String Searching
+ wchar_t *wcschr (const wchar_t *S, wchar_t c);
+ size_t wcscspn (const wchar_t *s1, const wchar_t *s2);
+ wchar_t *wcspbrk (const wchar_t *s1, const wchar_t *s2);
+ wchar_t *wcsrchr (const wchar_t *S, wchar_t c);
+ size_t wcsspn (const wchar_t *s1, const wchar_t *s2);
+ wchar_t *wcsstr (const wchar_t *s1, const wchar_t *s2);
+ wchar_t *wcstok (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2,
+ wchar_t ** __restrict ptr);
+ wchar_t *wmemchr (const wchar_t *S, wchar_t c, size_t n);
+
+ ################### String Manipulation
+ size_t wcslen (const wchar_t *S);
+ wchar_t *wmemset (wchar_t *S, wchar_t c, size_t n);
+
+ ################# Date and Time Conversion
+ size_t wcsftime (wchar_t * __restrict S, size_t maxsize,
+ const wchar_t * __restrict format,
+ const struct tm * __restrict timeptr);
+
+ ############# Multibyte <--> Wide Character Conversion
+ wint_t btowc (int c);
+ int wctob (wint_t c);
+ int mbsinit (const mbstate_t *ps);
+
+ ####### Restartable Multibyte <--> Wide Character Conversion
+ size_t mbrlen (const char * __restrict S, size_t n,
+ mbstate_t * __restrict ps);
+ size_t mbrtowc (wchar_t * __restrict pwc, const char * __restrict S,
+ size_t n, mbstate_t * __restrict ps);
+ size_t wcrtomb (char * __restrict S, wchar_t wc,
+ mbstate_t * __restrict ps);
+ size_t mbsrtowcs (wchar_t * __restrict dst,
+ const char ** __restrict src, size_t len,
+ mbstate_t * __restrict ps);
+ size_t wcsrtombs (char * __restrict dst,
+ const wchar_t ** __restrict src,
+ size_t len, mbstate_t * __restrict ps);
+@endverbatim
+
+ @note Properly constructed programs will take the following into consideration:
+ - wchar_t and wint_t may be the same integer type.
+ - WEOF might be a different value than that of EOF.
+ - WEOF might not be negative.
+ - mbstate_t objects are not intended to be inspected by programs.
+
+ 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 _WCHAR_H
#define _WCHAR_H
@@ -32,253 +172,974 @@ #endif
#ifdef _EFI_SIZE_T_
- typedef _EFI_SIZE_T_ size_t;
+ typedef _EFI_SIZE_T_ size_t; /**< Unsigned integer type of the result of the sizeof operator. */
#undef _BSD_SIZE_T_
#undef _EFI_SIZE_T_
#endif
#ifndef __cplusplus
#ifdef _EFI_WCHAR_T
- typedef _EFI_WCHAR_T wchar_t;
+ /** An integer type capable of representing all distinct codes in the
+ UCS-2 encoding supported by UEFI.
+ **/
+ typedef _EFI_WCHAR_T wchar_t;
#undef _BSD_WCHAR_T_
#undef _EFI_WCHAR_T
#endif
#endif
-/* mbstate_t is an opaque object, that must not be an array type, used to keep
- conversion state during multibyte stream conversions.
- */
#ifdef _BSD_MBSTATE_T_
+ /** mbstate_t is an opaque object, that is not an array type, used to keep
+ conversion state during multibyte stream conversions.
+ */
typedef _BSD_MBSTATE_T_ mbstate_t;
#undef _BSD_MBSTATE_T_
#endif
-/* wint_t is an integer type unchanged by default argument promotions that can
- hold any value corresponding to members of the extended character set, as
- well as at least one value that does not correspond to any member of the
- extended character set: WEOF.
-*/
#ifdef _EFI_WINT_T
- typedef _EFI_WINT_T wint_t;
+ /** wint_t is an integer type unchanged by default argument promotions that can
+ hold any value corresponding to members of the extended character set, as
+ well as at least one value that does not correspond to any member of the
+ extended character set: WEOF.
+ */
+ typedef _EFI_WINT_T wint_t;
#undef _BSD_WINT_T_
#undef _EFI_WINT_T
#endif
-/* Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and
- a maximum value defined by __USHRT_MAX (65535 on IA processors).
-*/
#ifndef WCHAR_MIN
- #define WCHAR_MIN 0
- #define WCHAR_MAX __USHRT_MAX
-#endif
-
-/* limits of wint_t */
-#ifndef WINT_MIN
- #define WINT_MIN _EFI_WINT_MIN /* wint_t */
- #define WINT_MAX _EFI_WINT_MAX /* wint_t */
+ /** @{
+ Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and
+ a maximum value defined by __USHRT_MAX (65535 on IA processors).
+ */
+ #define WCHAR_MIN 0
+ #define WCHAR_MAX __USHRT_MAX
+ /*@}*/
#endif
-/* WEOF expands to a constant expression of type wint_t whose value does not
- correspond to any member of the extended character set. It is accepted
- (and returned) by several functions, declared in this file, to indicate
- end-of-file, that is, no more input from a stream. It is also used as a
- wide character value that does not correspond to any member of the
- extended character set.
-*/
#ifndef WEOF
+ /** WEOF expands to a constant expression of type wint_t whose value does not
+ correspond to any member of the extended character set. It is accepted
+ (and returned) by several functions, declared in this file, to indicate
+ end-of-file, that is, no more input from a stream. It is also used as a
+ wide character value that does not correspond to any member of the
+ extended character set.
+ */
#define WEOF ((wint_t)-1)
#endif
-/* tm is declared here as an incomplete structure type. The full structure
- declaration is in <time.h>.
+/* limits of wint_t -- These are NOT specified by ISO/IEC 9899 */
+#ifndef WINT_MIN
+ #define WINT_MIN _EFI_WINT_MIN /* wint_t */
+ #define WINT_MAX _EFI_WINT_MAX /* wint_t */
+#endif
+
+/** Type struct tm is declared here as an incomplete structure type for use as an argument
+ type by the wcsftime function. The full structure declaration is in <time.h>.
*/
struct tm;
/* ############### Formatted Input/Output Functions ##################### */
-/**
-The fwprintf function writes output to the stream pointed to by stream, under
-control of the wide string pointed to by format that specifies how subsequent arguments
-are converted for output. If there are insufficient arguments for the format, the behavior
-is undefined. If the format is exhausted while arguments remain, the excess arguments
-are evaluated (as always) but are otherwise ignored. The fwprintf function returns
-when the end of the format string is encountered.
-
-The fwprintf function returns the number of wide characters transmitted, or a negative
-value if an output or encoding error occurred.
+/** The fwprintf function writes output to the stream pointed to by stream,
+ under control of the wide string pointed to by format that specifies how
+ subsequent arguments are converted for output. If there are insufficient
+ arguments for the format, the behavior is undefined. If the format is
+ exhausted while arguments remain, the excess arguments are evaluated
+ (as always) but are otherwise ignored. The fwprintf function returns
+ when the end of the format string is encountered.
+
+ The format is composed of zero or more directives: ordinary wide characters
+ (not %), which are copied unchanged to the output stream; and conversion
+ specifications, each of which results in fetching zero or more subsequent
+ arguments, converting them, if applicable, according to the corresponding
+ conversion specifier, and then writing the result to the output stream.
+
+ Each conversion specification is introduced by the wide character %. After
+ the %, the following appear in sequence:
+ — Zero or more flags (in any order) that modify the meaning of the
+ conversion specification.
+ — An optional minimum field width. If the converted value has fewer wide
+ characters than the field width, it is padded with spaces (by default)
+ on the left (or right, if the left adjustment flag, described later,
+ has been given) to the field width. The field width takes the form of
+ an asterisk * (described later) or a nonnegative decimal integer.
+ — An optional precision that gives the minimum number of digits to appear
+ for the d, i, o, u, x, and X conversions, the number of digits to
+ appear after the decimal-point wide character for e, E, f, and F
+ conversions, the maximum number of significant digits for the g and G
+ conversions, or the maximum number of wide characters to be written
+ for s conversions. The precision takes the form of a period (.)
+ followed either by an asterisk * (described later) or by an optional
+ decimal integer; if only the period is specified, the precision is
+ taken as zero. If a precision appears with any other conversion
+ specifier, the behavior is undefined.
+ — An optional length modifier that specifies the size of the argument.
+ — A conversion specifier wide character that specifies the type of
+ conversion to be applied.
+
+ As noted above, a field width, or precision, or both, may be indicated by
+ an asterisk. In this case, an int argument supplies the field width or
+ precision. The arguments specifying field width, or precision, or both,
+ must appear (in that order) before the argument (if any) to be converted.
+ A negative field width argument is taken as a - flag followed by a positive
+ field width. A negative precision argument is taken as if the precision
+ were omitted.
+
+ The flag wide characters and their meanings are:<BR>
+ - The result of the conversion is left-justified within the field.
+ (It is right-justified if this flag is not specified.)
+ + The result of a signed conversion always begins with a plus or minus
+ sign. (It begins with a sign only when a negative value is converted
+ if this flag is not specified.)
+ space If the first wide character of a signed conversion is not a sign, or
+ if a signed conversion results in no wide characters, a space is
+ prefixed to the result. If the space and + flags both appear, the
+ space flag is ignored.
+ # The result is converted to an ‘‘alternative form’’. For o conversion,
+ it increases the precision, if and only if necessary, to force the
+ first digit of the result to be a zero (if the value and precision
+ are both 0, a single 0 is printed). For x (or X) conversion, a
+ nonzero result has 0x (or 0X) prefixed to it. For e, E, f, F, g,
+ and G conversions, the result of converting a floating-point number
+ always contains a decimal-point wide character, even if no digits
+ follow it. (Normally, a decimal-point wide character appears in the
+ result of these conversions only if a digit follows it.) For g and G
+ conversions, trailing zeros are not removed from the result. For
+ other conversions, the behavior is undefined.
+ 0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading zeros
+ (following any indication of sign or base) are used to pad to the
+ field width rather than performing space padding, except when
+ converting an infinity or NaN. If the 0 and - flags both appear,
+ the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a
+ precision is specified, the 0 flag is ignored. For other conversions,
+ the behavior is undefined.
+
+ The length modifiers and their meanings are:<BR>
+ hh Specifies that a following d, i, o, u, x, or X conversion specifier
+ applies to a signed char or unsigned char argument (the argument
+ will have been promoted according to the integer promotions, but its
+ value shall be converted to signed char or unsigned char before
+ printing); or that a following n conversion specifier applies to a
+ pointer to a signed char argument.
+ h Specifies that a following d, i, o, u, x, or X conversion specifier
+ applies to a short int or unsigned short int argument (the argument
+ will have been promoted according to the integer promotions, but its
+ value shall be converted to short int or unsigned short int before
+ printing); or that a following n conversion specifier applies to a
+ pointer to a short int argument.
+ l (ell) Specifies that a following d, i, o, u, x, or X conversion
+ specifier applies to a long int or unsigned long int argument;
+ that a following n conversion specifier applies to a pointer to a
+ long int argument; that a following c conversion specifier
+ applies to a wint_t argument; that a following s conversion
+ specifier applies to a pointer to a wchar_t argument; or has no
+ effect on a following e, E, f, F, g, or G conversion specifier.
+ ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion
+ specifier applies to a long long int or unsigned long long int
+ argument; or that a following n conversion specifier applies
+ to a pointer to a long long int argument.
+ j Specifies that a following d, i, o, u, x, or X conversion specifier
+ applies to an intmax_t or uintmax_t argument; or that a following
+ n conversion specifier applies to a pointer to an intmax_t argument.
+ z Specifies that a following d, i, o, u, x, or X conversion specifier
+ applies to a size_t or the corresponding signed integer type
+ argument; or that a following n conversion specifier applies to a
+ pointer to a signed integer type corresponding to size_t argument.
+ t Specifies that a following d, i, o, u, x, or X conversion specifier
+ applies to a ptrdiff_t or the corresponding unsigned integer type
+ argument; or that a following n conversion specifier applies to a
+ pointer to a ptrdiff_t argument.
+ L Specifies that a following a, A, e, E, f, F, g, or G conversion
+ specifier applies to a long double argument.
+
+ If a length modifier appears with any conversion specifier other than as
+ specified above, the behavior is undefined.
+
+ The conversion specifiers and their meanings are:<BR>
+ d,i The int argument is converted to signed decimal in the
+ style [-]dddd. The precision specifies the minimum number of digits
+ to appear; if the value being converted can be represented in fewer
+ digits, it is expanded with leading zeros. The default precision
+ is 1. The result of converting a zero value with a precision of
+ zero is no wide characters.
+ o,u,x,X The unsigned int argument is converted to unsigned octal (o),
+ unsigned decimal (u), or unsigned hexadecimal notation (x or X) in
+ the style dddd; the letters abcdef are used for x conversion and
+ the letters ABCDEF for X conversion. The precision specifies the
+ minimum number of digits to appear; if the value being converted
+ can be represented in fewer digits, it is expanded with leading
+ zeros. The default precision is 1. The result of converting a zero
+ value with a precision of zero is no wide characters.
+ f,F A double argument representing a floating-point number is converted
+ to decimal notation in the style [-]ddd.ddd, where the number of
+ digits after the decimal-point wide character is equal to the
+ precision specification. If the precision is missing, it is taken
+ as 6; if the precision is zero and the # flag is not specified, no
+ decimal-point wide character appears. If a decimal-point wide
+ character appears, at least one digit appears before it. The value
+ is rounded to the appropriate number of digits.<BR>
+ A double argument representing an infinity is converted to [-]inf.
+ A double argument representing a NaN is converted to [-]nan.
+ The F conversion specifier produces INF or NAN instead
+ of inf or nan, respectively.
+ e,E A double argument representing a floating-point number is converted
+ in the style [-]d.ddd e±dd, where there is one digit (which is
+ nonzero if the argument is nonzero) before the decimal-point wide
+ character and the number of digits after it is equal to the
+ precision; if the precision is missing, it is taken as 6; if the
+ precision is zero and the # flag is not specified, no decimal-point
+ wide character appears. The value is rounded to the appropriate
+ number of digits. The E conversion specifier produces a number with
+ E instead of e introducing the exponent. The exponent always
+ contains at least two digits, and only as many more digits as
+ necessary to represent the exponent. If the value is zero, the
+ exponent is zero. A double argument representing an infinity or NaN
+ is converted in the style of an f or F conversion specifier.
+ g,G A double argument representing a floating-point number is converted
+ in style f or e (or in style F or E in the case of a G conversion
+ specifier), depending on the value converted and the precision.
+ Let P equal the precision if nonzero, 6 if the precision is
+ omitted, or 1 if the precision is zero. Then, if a conversion with
+ style E would have an exponent of X:
+ - if P > X = -4, the conversion is with style f (or F) and
+ precision P - (X + 1).
+ - otherwise, the conversion is with style e (or E) and
+ precision P - 1.
+ Finally, unless the # flag is used, any trailing zeros are removed
+ from the fractional portion of the result and the decimal-point
+ wide character is removed if there is no fractional portion
+ remaining. A double argument representing an infinity or NaN is
+ converted in the style of an f or F conversion specifier.
+ c If no l length modifier is present, the int argument is converted
+ to a wide character as if by calling btowc and the resulting wide
+ character is written. If an l length modifier is present, the
+ wint_t argument is converted to wchar_t and written.
+ s If no l length modifier is present, the argument shall be a pointer
+ to the initial element of a character array containing a multibyte
+ character sequence beginning in the initial shift state. Characters
+ from the array are converted as if by repeated calls to the mbrtowc
+ function, with the conversion state described by an mbstate_t
+ object initialized to zero before the first multibyte character is
+ converted, and written up to (but not including) the terminating
+ null wide character. If the precision is specified, no more than
+ that many wide characters are written. If the precision is not
+ specified or is greater than the size of the converted array, the
+ converted array shall contain a null wide character.<BR>
+ If an l length modifier is present, the argument shall be a pointer
+ to the initial element of an array of wchar_t type. Wide characters
+ from the array are written up to (but not including) a terminating
+ null wide character. If the precision is specified, no more than
+ that many wide characters are written. If the precision is not
+ specified or is greater than the size of the array, the array
+ shall contain a null wide character.
+ p The argument shall be a pointer to void. The value of the pointer
+ is converted to a sequence of printing wide characters, in an
+ implementation-defined manner.
+ n The argument shall be a pointer to signed integer into which is
+ written the number of wide characters written to the output stream
+ so far by this call to fwprintf. No argument is converted, but one
+ is consumed. If the conversion specification includes any flags, a
+ field width, or a precision, the behavior is undefined.
+ % A % wide character is written. No argument is converted. The
+ complete conversion specification is %%.
+
+
+ @param[in] stream An open File specifier to which the output is sent.
+ @param[in] format A wide character sequence containing characters
+ to be copied unchanged, and conversion specifiers
+ which convert their associated arguments.
+ @param ... Variable number of parameters as required by format.
+
+ @return The fwprintf function returns the number of wide characters
+ transmitted, or a negative value if an output or encoding error
+ occurred.
**/
int fwprintf(FILE * __restrict stream, const wchar_t * __restrict format, ...);
-/**
-The fwscanf function reads input from the stream pointed to by stream, under
-control of the wide string pointed to by format that specifies the admissible input
-sequences and how they are to be converted for assignment, using subsequent arguments
-as pointers to the objects to receive the converted input. If there are insufficient
-arguments for the format, the behavior is undefined. If the format is exhausted while
-arguments remain, the excess arguments are evaluated (as always) but are otherwise
-ignored.
-
-The fwscanf function returns the value of the macro EOF if an input failure occurs
-before any conversion. Otherwise, the function returns the number of input items
-assigned, which can be fewer than provided for, or even zero, in the event of an early
-matching failure.
+/** The fwscanf function reads input from the stream pointed to by stream,
+ under control of the wide string pointed to by format that specifies
+ the admissible input sequences and how they are to be converted for
+ assignment, using subsequent arguments as pointers to the objects to
+ receive the converted input. If there are insufficient arguments for
+ the format, the behavior is undefined. If the format is exhausted while
+ arguments remain, the excess arguments are evaluated (as always) but are
+ otherwise ignored.
+
+ The format is composed of zero or more directives: one or more white-space
+ wide characters, an ordinary wide character (neither % nor a white-space
+ wide character), or a conversion specification. Each conversion
+ specification is introduced by the wide character %. After the %, the
+ following appear in sequence:
+ - An optional assignment-suppressing wide character *.
+ - An optional decimal integer greater than zero that specifies the
+ maximum field width (in wide characters).
+ - An optional length modifier that specifies the size of the receiving object.
+ - A conversion specifier wide character that specifies the type of
+ conversion to be applied.
+
+ The fwscanf function executes each directive of the format in turn. If a
+ directive fails, as detailed below, the function returns. Failures are
+ described as input failures (due to the occurrence of an encoding error
+ or the unavailability of input characters), or matching failures
+ (due to inappropriate input).
+
+ A directive composed of white-space wide character(s) is executed by
+ reading input up to the first non-white-space wide character (which remains
+ unread), or until no more wide characters can be read.
+
+ A directive that is an ordinary wide character is executed by reading the
+ next wide character of the stream. If that wide character differs from the
+ directive, the directive fails and the differing and subsequent wide
+ characters remain unread. Similarly, if end-of-file, an encoding error, or
+ a read error prevents a wide character from being read, the directive fails.
+
+ A directive that is a conversion specification defines a set of matching
+ input sequences, as described below for each specifier. A conversion
+ specification is executed in the following steps:
+ - Input white-space wide characters (as specified by the iswspace
+ function) are skipped, unless the specification includes
+ a [, c, or n specifier.
+ - An input item is read from the stream, unless the specification
+ includes an n specifier. An input item is defined as the longest
+ sequence of input wide characters which does not exceed any specified
+ field width and which is, or is a prefix of, a matching input sequence.
+ The first wide character, if any, after the input item remains unread.
+ If the length of the input item is zero, the execution of the directive
+ fails; this condition is a matching failure unless end-of-file, an
+ encoding error, or a read error prevented input from the stream, in
+ which case it is an input failure.
+ - Except in the case of a % specifier, the input item (or, in the case of
+ a %n directive, the count of input wide characters) is converted to a
+ type appropriate to the conversion specifier. If the input item is not
+ a matching sequence, the execution of the directive fails: this
+ condition is a matching failure. Unless assignment suppression was
+ indicated by a *, the result of the conversion is placed in the object
+ pointed to by the first argument following the format argument that has
+ not already received a conversion result. If this object does not have
+ an appropriate type, or if the result of the conversion cannot be
+ represented in the object, the behavior is undefined.
+
+ The length modifiers and their meanings are:<BR>
+ hh Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to signed char
+ or unsigned char.
+ h Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to short int
+ or unsigned short int.
+ l (ell) Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to long int or
+ unsigned long int; that a following e, E, f, F, g, or G conversion
+ specifier applies to an argument with type pointer to double; or
+ that a following c, s, or [ conversion specifier applies to an
+ argument with type pointer to wchar_t.
+ ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type
+ pointer to long long int or unsigned long long int.
+ j Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to intmax_t
+ or uintmax_t.
+ z Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to size_t or the
+ corresponding signed integer type.
+ t Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to ptrdiff_t or
+ the corresponding unsigned integer type.
+ L Specifies that a following e, E, f, F, g, or G conversion specifier
+ applies to an argument with type pointer to long double.
+
+ If a length modifier appears with any conversion specifier other than as
+ specified above, the behavior is undefined.
+
+ The conversion specifiers and their meanings are:<BR>
+ d Matches an optionally signed decimal integer, whose format is the
+ same as expected for the subject sequence of the wcstol function
+ with the value 10 for the base argument. The corresponding argument
+ shall be a pointer to signed integer.
+ i Matches an optionally signed integer, whose format is the same as
+ expected for the subject sequence of the wcstol function with the
+ value 0 for the base argument. The corresponding argument shall be
+ a pointer to signed integer.
+ o Matches an optionally signed octal integer, whose format is the
+ same as expected for the subject sequence of the wcstoul function
+ with the value 8 for the base argument. The corresponding argument
+ shall be a pointer to unsigned integer.
+ u Matches an optionally signed decimal integer, whose format is the
+ same as expected for the subject sequence of the wcstoul function
+ with the value 10 for the base argument. The corresponding argument
+ shall be a pointer to unsigned integer.
+ x Matches an optionally signed hexadecimal integer, whose format is
+ the same as expected for the subject sequence of the wcstoul
+ function with the value 16 for the base argument. The corresponding
+ argument shall be a pointer to unsigned integer.
+ e,f,g Matches an optionally signed floating-point number, infinity, or
+ NaN, whose format is the same as expected for the subject sequence
+ of the wcstod function. The corresponding argument shall be a
+ pointer to float.
+ c Matches a sequence of wide characters of exactly the number
+ specified by the field width (1 if no field width is present in the
+ directive).<BR>
+ If no l length modifier is present, characters from the input field
+ are converted as if by repeated calls to the wcrtomb function, with
+ the conversion state described by an mbstate_t object initialized
+ to zero before the first wide character is converted. The
+ corresponding argument shall be a pointer to the initial element of
+ a character array large enough to accept the sequence. No null
+ character is added.<BR>
+ If an l length modifier is present, the corresponding argument
+ shall be a pointer to the initial element of an array of
+ wchar_t large enough to accept the sequence.
+ No null wide character is added.
+ s Matches a sequence of non-white-space wide characters.
+ If no l length modifier is present, characters from the input field
+ are converted as if by repeated calls to the wcrtomb function, with
+ the conversion state described by an mbstate_t object initialized
+ to zero before the first wide character is converted. The
+ corresponding argument shall be a pointer to the initial element of
+ a character array large enough to accept the sequence and a
+ terminating null character, which will be added automatically.<BR>
+ If an l length modifier is present, the corresponding argument
+ shall be a pointer to the initial element of an array of wchar_t
+ large enough to accept the sequence and the terminating null wide
+ character, which will be added automatically.
+ [ Matches a nonempty sequence of wide characters from a set of
+ expected characters (the scanset).<BR>
+ If no l length modifier is present, characters from the input field
+ are converted as if by repeated calls to the wcrtomb function, with
+ the conversion state described by an mbstate_t object initialized
+ to zero before the first wide character is converted. The
+ corresponding argument shall be a pointer to the initial element of
+ a character array large enough to accept the sequence and a
+ terminating null character, which will be added automatically.<BR>
+ If an l length modifier is present, the corresponding argument
+ shall be a pointer to the initial element of an array of wchar_t
+ large enough to accept the sequence and the terminating null wide
+ character, which will be added automatically.<BR>
+ The conversion specifier includes all subsequent wide characters
+ in the format string, up to and including the matching right
+ bracket (]). The wide characters between the brackets
+ (the scanlist) compose the scanset, unless the wide character after
+ the left bracket is a circumflex (^), in which case the scanset
+ contains all wide characters that do not appear in the scanlist
+ between the circumflex and the right bracket. If the conversion
+ specifier begins with [] or [^], the right bracket wide character
+ is in the scanlist and the next following right bracket wide
+ character is the matching right bracket that ends the specification;
+ otherwise the first following right bracket wide character is the
+ one that ends the specification. If a - wide character is in the
+ scanlist and is not the first, nor the second where the first wide
+ character is a ^, nor the last character,
+ the - is added to the scanset.
+ p Matches the set of sequences produced by the %p conversion of the
+ fwprintf function. The corresponding argument is a pointer to a
+ pointer to void. The input item is converted to a pointer value. If
+ the input item is a value converted earlier during the same program
+ execution, the pointer that results will compare equal to that
+ value.
+ n No input is consumed. The corresponding argument is a pointer to
+ signed integer into which is to be written the number of wide
+ characters read from the input stream so far by this call to the
+ fwscanf function. Execution of a %n directive does not increment
+ the assignment count returned at the completion of execution of the
+ fwscanf function. No argument is converted, but one is consumed.
+ % Matches a single % wide character; no conversion or assignment
+ occurs. The complete conversion specification shall be %%.
+
+ The conversion specifiers E, F, G, and X are also valid and behave the same
+ as, respectively, e, f, g, and x.
+
+ Trailing white space (including new-line wide characters) is left unread
+ unless matched by a directive. The success of literal matches and
+ suppressed assignments is not directly determinable other than via
+ the %n directive.
+
+ @param[in] stream An open File specifier from which the input is read.
+ @param[in] format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments. Converted
+ items are stored according to their associated arguments.
+ @param ... Variable number of parameters, as required by format,
+ specifying the objects to receive the converted input.
+
+ @return The fwscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ function returns the number of input items assigned, which can be
+ fewer than provided for, or even zero, in the event of an early
+ matching failure.
**/
int fwscanf(FILE * __restrict stream, const wchar_t * __restrict format, ...);
-/**
-The swprintf function is equivalent to fwprintf, except that the argument s
-specifies an array of wide characters into which the generated output is to be written,
-rather than written to a stream. No more than n wide characters are written, including a
-terminating null wide character, which is always added (unless n is zero).
-
-The swprintf function returns the number of wide characters written in the array, not
-counting the terminating null wide character, or a neg ative value if an encoding error
-occurred or if n or more wide characters were requested to be written.
+/** Formatted wide-character output to a buffer.
+
+ The swprintf function is equivalent to fwprintf, except that the argument s
+ specifies an array of wide characters into which the generated output is to
+ be written, rather than written to a stream. No more than n wide characters
+ are written, including a terminating null wide character, which is always
+ added (unless n is zero).
+
+ @param[out] s A pointer to the array to receive the formatted output.
+ @param[in] n Maximum number of characters to write into buffer s.
+ @param[in] format A wide character sequence containing characters
+ to be copied unchanged, and conversion specifiers
+ which convert their associated arguments. Copied and
+ converted characters are written to the array pointed
+ to by s.
+ @param ... Variable number of parameters as required by format.
+
+ @return The swprintf function returns the number of wide characters
+ written in the array, not counting the terminating null wide
+ character, or a negative value if an encoding error occurred or
+ if n or more wide characters were requested to be written.
**/
int swprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, ...);
-/**
+/** Formatted wide input from a string.
+
+ The swscanf function is equivalent to fwscanf, except that the argument
+ Buff specifies a wide string from which the input is to be obtained, rather
+ than from a stream. Reaching the end of the wide string is equivalent to
+ encountering end-of-file for the fwscanf function.
+
+ @param[in] Buff Pointer to the string from which to obtain input.
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[out] ... Variable number of parameters, as required by format,
+ specifying the objects to receive the converted input.
+
+ @return The swscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ swscanf function returns the number of input items assigned,
+ which can be fewer than provided for, or even zero, in the event
+ of an early matching failure.
**/
-int swscanf(const wchar_t * __restrict s, const wchar_t * __restrict format, ...);
-
-/**
+int swscanf(const wchar_t * __restrict Buff, const wchar_t * __restrict Format, ...);
+
+/** Print formatted values from an argument list.
+
+The vfwprintf function is equivalent to fwprintf, with the variable argument list
+replaced by Args, which shall have been initialized by the va_start macro (and
+possibly subsequent va_arg calls). The vfwprintf function does not invoke the
+va_end macro.
+
+ @param[in] Stream The output stream to receive the formatted output.
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[in] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vfwprintf function returns the number of wide characters
+ transmitted, or a negative value if an output or encoding
+ error occurred.
**/
-int vfwprintf(FILE * __restrict stream, const wchar_t * __restrict format, va_list arg);
-
-/**
+int vfwprintf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);
+
+/** Formatted input from a stream.
+
+ The vfwscanf function is equivalent to fwscanf, with the variable argument
+ list replaced by Args, which must have been initialized by the va_start
+ macro (and possibly subsequent va_arg calls). The vfwscanf function does
+ not invoke the va_end macro.
+
+ @param[in] Stream The input stream.
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[in] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vfwscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ vfwscanf function returns the number of input items assigned,
+ which can be fewer than provided for, or even zero, in the event
+ of an early matching failure.
**/
-int vfwscanf(FILE * __restrict stream, const wchar_t * __restrict format, va_list arg);
-
-/**
+int vfwscanf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);
+
+/** Formatted print, to a buffer, from an argument list.
+
+ The vswprintf function is equivalent to swprintf, with the variable
+ argument list replaced by Args, which must have been initialized by the
+ va_start macro (and possibly subsequent va_arg calls). The vswprintf
+ function does not invoke the va_end macro.
+
+ @param[in] S A pointer to the array to receive the formatted output.
+ @param[in] N Maximum number of characters to write into array S.
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[in] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vswprintf function returns the number of wide characters
+ written in the array, not counting the terminating null wide
+ character, or a neg ative value if an encoding error occurred or
+ if n or more wide characters were requested to be generated.
**/
-int vswprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, va_list arg);
-
-/**
+int vswprintf(wchar_t * __restrict S, size_t N, const wchar_t * __restrict Format, va_list Args);
+
+/** Formatted input from a string, using an argument list.
+
+ The vswscanf function is equivalent to swscanf, with the variable argument
+ list replaced by Args, which must have been initialized by the va_start
+ macro. The vswscanf function does not invoke the va_end macro.
+
+ @param[in] S Pointer to the string from which to obtain input.
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[out] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vswscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ vswscanf function returns the number of input items assigned,
+ which can be fewer than provided for, or even zero, in the event
+ of an early matching failure.
**/
-int vswscanf(const wchar_t * __restrict s, const wchar_t * __restrict format, va_list arg);
+int vswscanf(const wchar_t * __restrict S, const wchar_t * __restrict Format, va_list Args);
-/**
-**/
-int vwprintf(const wchar_t * __restrict format, va_list arg);
+/** Formatted print, to stdout, from an argument list.
-/**
+ The vwprintf function is equivalent to wprintf, with the variable argument
+ list replaced by Args, which must have been initialized by the va_start
+ macro. The vwprintf function does not invoke the va_end macro.
+
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[out] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vwprintf function returns the number of wide characters
+ transmitted, or a negative value if an output or encoding error
+ occurred.
+**/
+int vwprintf(const wchar_t * __restrict Format, va_list Args);
+
+/** Formatted input, from stdin, to an argument list.
+
+ The vwscanf function is equivalent to wscanf, with the variable argument
+ list replaced by arg, which shall have been initialized by the va_start
+ macro. The vwscanf function does not invoke the va_end macro.
+
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[out] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vwscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ vwscanf function returns the number of input items assigned,
+ which can be fewer than provided for, or even zero, in the event
+ of an early matching failure.
**/
-int vwscanf(const wchar_t * __restrict format, va_list arg);
+int vwscanf(const wchar_t * __restrict Format, va_list Args);
-/**
+/** Formatted print to stdout.
+
+ The wprintf function is equivalent to fwprintf with the argument stdout
+ specifying the output stream.
+
+ @param[in] format A wide character sequence containing characters
+ to be copied unchanged, and conversion specifiers
+ which convert their associated arguments.
+ @param ... Variable number of parameters as required by format.
+
+ @return The wprintf function returns the number of wide characters
+ transmitted, or a negative value if an output or encoding error
+ occurred.
**/
-int wprintf(const wchar_t * __restrict format, ...);
+int wprintf(const wchar_t * __restrict Format, ...);
-/**
+/** Formatted input from stdin.
+
+ The wscanf function is equivalent to fwscanf with the argument stdin
+ specifying the input stream.
+
+ @param[in] format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments. Converted
+ items are stored according to their associated arguments.
+ @param ... Variable number of parameters, as required by format,
+ specifying the objects to receive the converted input.
+
+ @return The wscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ wscanf function returns the number of input items assigned,
+ which can be fewer than provided for, or even zero, in the event
+ of an early matching failure.
**/
int wscanf(const wchar_t * __restrict format, ...);
/* ################### Input/Output Functions ########################### */
-/**
-**/
-wint_t fgetwc(FILE *stream);
+/** Get a character from an input Stream.
-/**
+If the end-of-file indicator for the input stream pointed to by stream is not set and a
+next wide character is present, the fgetwc function obtains that wide character as a
+wchar_t converted to a wint_t and advances the associated file position indicator for
+the stream (if defined).
+
+ @param[in] Stream An input stream from which to obtain a character.
+
+ @return If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the endof-
+file indicator for the stream is set and the fgetwc function returns WEOF. Otherwise,
+the fgetwc function returns the next wide character from the input stream pointed to by
+stream. If a read error occurs, the error indicator for the stream is set and the fgetwc
+function returns WEOF. If an encoding error occurs (including too few bytes), the value of
+the macro EILSEQ is stored in errno and the fgetwc function returns WEOF.
**/
-wchar_t *fgetws(wchar_t * __restrict s, int n, FILE * __restrict stream);
+wint_t fgetwc(FILE *Stream);
+
+/** Read a string from an input stream into a buffer.
+
+ The fgetws function reads at most one less than the number of
+ wide characters specified by n from the stream pointed to by
+ stream into the array pointed to by s. No additional wide
+ characters are read after a new-line wide character (which is
+ retained) or after end-of-file. A null wide character is written
+ immediately after the last wide character read into the array.
+
+ @param[out] S A pointer to the array to receive the input string.
+ @param[in] Limit The maximum number of characters to put into Buff,
+ including the terminating null character.
+ @param[in] Stream An input stream from which to obtain a character.
+
+ @return The fgetws function returns S if successful. If end-of-file is
+ encountered and no characters have been read into the array, the
+ contents of the array remain unchanged and a null pointer is
+ returned. If a read or encoding error occurs during the
+ operation, the array contents are indeterminate and a
+ null pointer is returned.
+**/
+wchar_t *fgetws(wchar_t * __restrict S, int Limit, FILE * __restrict Stream);
-/**
+/** Write a character to an output stream.
+
+The fputwc function writes the wide character specified by c to the output stream
+pointed to by stream, at the position indicated by the associated file position indicator
+for the stream (if defined), and advances the indicator appropriately. If the file cannot
+support positioning requests, or if the stream was opened with append mode, the
+character is appended to the output stream.
+
+ @param[in] C The character to be written to Stream.
+ @param[in] Stream The output stream that C is to be written to.
+
+ @return The fputwc function returns the wide character written. If a write error occurs, the
+error indicator for the stream is set and fputwc returns WEOF. If an encoding error
+occurs, the value of the macro EILSEQ is stored in errno and fputwc returns WEOF.
**/
-wint_t fputwc(wchar_t c, FILE *stream);
+wint_t fputwc(wchar_t C, FILE *Stream);
-/**
+/** Write a string to an output stream.
+
+The fputws function writes the wide string pointed to by S to the stream pointed to by
+Stream. The terminating null wide character is not written.
+
+ @param[in] String The character string to be written to Stream.
+ @param[in] Stream The output stream that String is to be written to.
+
+ @return The fputws function returns EOF if a write or encoding error occurs; otherwise, it
+returns a nonnegative value.
**/
-int fputws(const wchar_t * __restrict s, FILE * __restrict stream);
+int fputws(const wchar_t * __restrict S, FILE * __restrict Stream);
-/**
+/** Query or set a stream's orientation.
+
+The fwide function determines the orientation of the stream pointed to by stream. If
+Mode is greater than zero, the function first attempts to make the stream wide oriented. If
+Mode is less than zero, the function first attempts to make the stream byte oriented.
+Otherwise, Mode is zero and the function does not alter the orientation of the stream.
+
+ @param[in] Stream The stream to be queried.
+ @param[in] Mode Control value selecting between quering or setting
+ the Stream's orientation.
+ @return The fwide function returns a value greater than zero if, after the call, the stream has
+wide orientation, a value less than zero if the stream has byte orientation, or zero if the
+stream has no orientation.
**/
-int fwide(FILE *stream, int mode);
+int fwide(FILE *Stream, int Mode);
-/**
+/** Get a character from an input stream.
+
+The getwc function is equivalent to fgetwc, except that if it is implemented as a
+macro, it may evaluate Stream more than once, so the argument should never be an
+expression with side effects.
+
+ @param[in] Stream The stream to be read.
+
+ @return The getwc function returns the next wide character from the input stream pointed to by
+stream, or WEOF.
**/
-wint_t getwc(FILE *stream);
+wint_t getwc(FILE *Stream);
-/**
+/** Get a character from stdin.
+
+ The getwchar function is equivalent to getwc with the argument stdin.
+
+ @return The getwchar function returns the next wide character from the
+ input stream pointed to by stdin, or WEOF.
**/
wint_t getwchar(void);
-/**
-**/
-wint_t putwc(wchar_t c, FILE *stream);
+/** Write a character to an output stream.
-/**
-**/
-wint_t putwchar(wchar_t c);
+The putwc function is equivalent to fputwc, except that if it is implemented as a
+macro, it may evaluate Stream more than once, so the Stream argument should never be an
+expression with side effects.
-/**
+ @param[in] C The wide character to be written to Stream.
+ @param[in] Stream The output stream that C is to be written to.
+
+ @return The putwc function returns the wide character written, or WEOF.
**/
-wint_t ungetwc(wint_t c, FILE *stream);
+wint_t putwc(wchar_t C, FILE *Stream);
-/* ################### Numeric Conversions ########################### */
+/** Write a character to stdout.
-/**
-**/
-double wcstod(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);
+The putwchar function is equivalent to putwc with the second argument stdout.
-/**
-**/
-float wcstof(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);
+ @param[in] C The wide character to be written to stdout.
-/**
+ @return The putwchar function returns the character written, or WEOF.
**/
-long double wcstold(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);
-
-/**
+wint_t putwchar(wchar_t C);
+
+/** Return a character to the input Stream as if it had not been read.
+
+The ungetwc function pushes the wide character specified by C back onto the input
+stream pointed to by Stream. Pushed-back wide characters will be returned by
+subsequent reads on that stream in the reverse order of their pushing. A successful
+intervening call (with the stream pointed to by Stream) to a file positioning function
+(fseek, fsetpos, or rewind) discards any pushed-back wide characters for the
+stream. The external storage corresponding to the stream is unchanged.
+
+One wide character of pushback is guaranteed, even if the call to the ungetwc function
+follows just after a call to a formatted wide character input function fwscanf,
+vfwscanf, vwscanf, or wscanf. If the ungetwc function is called too many times
+on the same stream without an intervening read or file positioning operation on that
+stream, the operation may fail.
+
+If the value of C equals that of the macro WEOF, the operation fails and the input stream is
+unchanged.
+
+A successful call to the ungetwc function clears the end-of-file indicator for the stream.
+The value of the file position indicator for the stream after reading or discarding all
+pushed-back wide characters is the same as it was before the wide characters were pushed
+back. For a text or binary stream, the value of its file position indicator after a successful
+call to the ungetwc function is unspecified until all pushed-back wide characters are
+read or discarded.
+
+ @param[in] C The wide character to push back onto the Stream.
+ @param[in] Stream The output stream that C is to be pushed back onto.
+
+ @return The ungetwc function returns the character pushed back,
+ or WEOF if the operation fails.
**/
-long int wcstol( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
+wint_t ungetwc(wint_t C, FILE *Stream);
-/**
-**/
-long long int wcstoll( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
+/* ################### Numeric Conversions ########################### */
-/**
+/** @{
+The wcstod, wcstof, and wcstold functions convert the initial portion of the wide
+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 wide characters (as specified by the iswspace
+function), a subject sequence resembling a floating-point constant or representing an
+infinity or NaN; and a final wide string of one or more unrecognized wide characters,
+including the terminating null wide character of the input wide string. Then, they attempt
+to convert the subject sequence to a floating-point number, and return the result.
+
+ @param[in] Nptr Pointer to the string to convert to a floating-point value.
+ @param[in] EndPtr Optional pointer to an object in which to store a pointer
+ to the final wide string.
+
+The 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, plus or
+minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the return
+type and sign of the value), and the value of the macro ERANGE is stored in errno. If
+the result underflows (7.12.1), the functions return a value whose magnitude is no greater
+than the smallest normalized positive number in the return type. A pointer to the
+final wide string is stored in the object pointed to by endptr, provided that endptr is
+not a null pointer.
**/
-unsigned long int wcstoul( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
-
-/**
+double wcstod (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
+float wcstof (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
+long double wcstold (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
+/*@}*/
+
+/** @{
+The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial
+portion of the wide string pointed to by nptr to long int, long long int,
+unsigned long int, and unsigned long long int representation,
+respectively. First, they decompose the input string into three parts: an initial, possibly
+empty, sequence of white-space wide characters (as specified by the iswspace
+function), a subject sequence resembling an integer represented in some radix determined
+by the value of base, and a final wide string of one or more unrecognized wide
+characters, including the terminating null wide character of the input wide string. Then,
+they attempt to convert the subject sequence to an integer, and return the result.
+
+ @param[in] Nptr Pointer to the string to convert to a floating-point value.
+ @param[in] EndPtr Optional pointer to an object in which to store a pointer
+ to the final wide string.
+ @param[in] Base Base, 0 to 36, of the value represented by the string
+ pointed to by Nptr.
+
+ @return The wcstol, wcstoll, wcstoul, and wcstoull 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
+sign of the value, if any), and the value of the macro ERANGE is stored in errno.
**/
-unsigned long long int wcstoull( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
+long int wcstol ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
+long long int wcstoll ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
+unsigned long int wcstoul ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
+unsigned long long int wcstoull( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
+/*@}*/
/* ####################### String Copying ############################### */
-/** The wcscpy function copies the wide string pointed to by s2 (including the
- terminating null wide character) into the array pointed to by s1.
+/** The wcscpy function copies the wide string pointed to by Src (including the
+ terminating null wide character) into the array pointed to by Dest.
- @return The wcscpy function returns the value of s1.
+ @return The wcscpy function returns the value of Dest.
**/
-wchar_t *wcscpy(wchar_t * __restrict s1, const wchar_t * __restrict s2);
+wchar_t *wcscpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src);
/** The wcsncpy function copies not more than n wide characters (those that
follow a null wide character are not copied) from the array pointed to by
- s2 to the array pointed to by s1.
+ Src to the array pointed to by Dest.
- If the array pointed to by s2 is a wide string that is shorter than n wide
+ If the array pointed to by Src is a wide string that is shorter than n wide
characters, null wide characters are appended to the copy in the array
- pointed to by s1, until n wide characters in all have been written.
+ pointed to by Dest, until n wide characters in all have been written.
- @return The wcsncpy function returns the value of s1.
+ @return The wcsncpy function returns the value of Dest.
**/
-wchar_t *wcsncpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
+wchar_t *wcsncpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
/** The wmemcpy function copies n wide characters from the object pointed to by
- s2 to the object pointed to by s1.
+ Src to the object pointed to by Dest.
- Use this function if you know that s1 and s2 DO NOT Overlap. Otherwise,
+ Use this function if you know that Dest and Src DO NOT Overlap. Otherwise,
use wmemmove.
- @return The wmemcpy function returns the value of s1.
+ @return The wmemcpy function returns the value of Dest.
**/
-wchar_t *wmemcpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
+wchar_t *wmemcpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
/** The wmemmove function copies n wide characters from the object pointed to by
- s2 to the object pointed to by s1. The objects pointed to by s1 and s2 are
+ Src to the object pointed to by Dest. The objects pointed to by Dest and Src are
allowed to overlap.
Because the UEFI BaseMemoryLib function CopyMem explicitly handles
@@ -286,33 +1147,33 @@ wchar_t *wmemcpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t implemented identically.
For programming clarity, it is recommended that you use wmemcpy if you know
- that s1 and s2 DO NOT Overlap. If s1 and s2 might possibly overlap, then
+ that Dest and Src DO NOT Overlap. If Dest and Src might possibly overlap, then
use wmemmove.
- @return The wmemmove function returns the value of s1.
+ @return The wmemmove function returns the value of Dest.
**/
-wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2, size_t n);
+wchar_t *wmemmove(wchar_t *Dest, const wchar_t *Src, size_t n);
/* ################### String Concatenation ########################## */
-/** The wcscat function appends a copy of the wide string pointed to by s2
+/** The wcscat function appends a copy of the wide string pointed to by Src
(including the terminating null wide character) to the end of the wide
- string pointed to by s1. The initial wide character of s2 overwrites the
- null wide character at the end of s1.
+ string pointed to by Dest. The initial wide character of Src overwrites the
+ null wide character at the end of Dest.
- @return The wcscat function returns the value of s1.
+ @return The wcscat function returns the value of Dest.
**/
-wchar_t *wcscat(wchar_t * __restrict s1, const wchar_t * __restrict s2);
+wchar_t *wcscat(wchar_t * __restrict Dest, const wchar_t * __restrict Src);
/** The wcsncat function appends not more than n wide characters (a null wide
character and those that follow it are not appended) from the array pointed
- to by s2 to the end of the wide string pointed to by s1. The initial wide
- character of s2 overwrites the null wide character at the end of s1.
+ to by Src to the end of the wide string pointed to by Dest. The initial wide
+ character of Src overwrites the null wide character at the end of Dest.
A terminating null wide character is always appended to the result.
- @return The wcsncat function returns the value of s1.
+ @return The wcsncat function returns the value of Dest.
**/
-wchar_t *wcsncat(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
+wchar_t *wcsncat(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
/* ##################### String Comparison ############################# */
@@ -377,15 +1238,15 @@ int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n); /* ##################### String Searching ############################## */
-/** The wcschr function locates the first occurrence of c in the wide string
- pointed to by s. The terminating null wide character is considered to be
+/** The wcschr function locates the first occurrence of C in the wide string
+ pointed to by S. The terminating null wide character is considered to be
part of the wide string.
@return The wcschr function returns a pointer to the located wide
character, or a null pointer if the wide character does not occur
in the wide string.
**/
-wchar_t *wcschr(const wchar_t *s, wchar_t c);
+wchar_t *wcschr(const wchar_t *S, wchar_t C);
/** The wcscspn function computes the length of the maximum initial segment of
the wide string pointed to by s1 which consists entirely of wide characters
@@ -405,14 +1266,14 @@ size_t wcscspn(const wchar_t *s1, const wchar_t *s2); **/
wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
-/** The wcsrchr function locates the last occurrence of c in the wide string
- pointed to by s. The terminating null wide character is considered to be
+/** The wcsrchr function locates the last occurrence of C in the wide string
+ pointed to by S. The terminating null wide character is considered to be
part of the wide string.
@return The wcsrchr function returns a pointer to the wide character,
- or a null pointer if c does not occur in the wide string.
+ or a null pointer if C does not occur in the wide string.
**/
-wchar_t *wcsrchr(const wchar_t *s, wchar_t c);
+wchar_t *wcsrchr(const wchar_t *S, wchar_t C);
/** The wcsspn function computes the length of the maximum initial segment of
the wide string pointed to by s1 which consists entirely of wide characters
@@ -469,53 +1330,72 @@ wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); **/
wchar_t *wcstok(wchar_t * __restrict s1, const wchar_t * __restrict s2, wchar_t ** __restrict ptr);
-/** The wmemchr function locates the first occurrence of c in the initial n
- wide characters of the object pointed to by s.
+/** The wmemchr function locates the first occurrence of C in the initial n
+ wide characters of the object pointed to by S.
@return The wmemchr function returns a pointer to the located wide
character, or a null pointer if the wide character does not occur
in the object.
**/
-wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n);
+wchar_t *wmemchr(const wchar_t *S, wchar_t C, size_t n);
/* ################### String Manipulation ############################# */
-/** The wcslen function computes the length of the wide string pointed to by s.
+/** The wcslen function computes the length of the wide string pointed to by S.
@return The wcslen function returns the number of wide characters that
precede the terminating null wide character.
**/
-size_t wcslen(const wchar_t *s);
+size_t wcslen(const wchar_t *S);
-/** The wmemset function copies the value of c into each of the first n wide
- characters of the object pointed to by s.
+/** The wmemset function copies the value of C into each of the first n wide
+ characters of the object pointed to by S.
- @return The wmemset function returns the value of s.
+ @return The wmemset function returns the value of S.
**/
-wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);
+wchar_t *wmemset(wchar_t *S, wchar_t C, size_t n);
/* ################# Date and Time Conversion ########################### */
/**
+The wcsftime function is equivalent to the strftime function, except that:
+ - The argument s points to the initial element of an array of wide characters into which
+the generated output is to be placed.
+ - The argument maxsize indicates the limiting number of wide characters.
+ - The argument format is a wide string and the conversion specifiers are replaced by
+corresponding sequences of wide characters.
+ - The return value indicates the number of wide characters.
+
+If the total number of resulting wide characters including the terminating null wide
+character is not more than maxsize, the wcsftime function returns the number of
+wide characters placed into the array pointed to by s not including the terminating null
+wide character. Otherwise, zero is returned and the contents of the array are
+indeterminate.
**/
-size_t wcsftime(wchar_t * __restrict s, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);
+size_t wcsftime(wchar_t * __restrict S, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);
/* ############# Multibyte <--> Wide Character Conversion ############### */
-/**
+/** The btowc function determines whether C constitutes a valid single-byte
+ character in the initial shift state.
+
+ @return The btowc function returns WEOF if c has the value EOF or if
+ (unsigned char)C does not constitute a valid single-byte
+ character in the initial shift state. Otherwise, it returns the
+ wide character representation of that character.
**/
-wint_t btowc(int c);
+wint_t btowc(int C);
-/** The wctob function determines whether c corresponds to a member of the extended
+/** The wctob function determines whether C corresponds to a member of the extended
character set whose multibyte character representation is a single byte when in the initial
shift state.
- @return The wctob function returns EOF if c does not correspond to a multibyte
+ @return The wctob function returns EOF if C does not correspond to a multibyte
character with length one in the initial shift state. Otherwise, it
returns the single-byte representation of that character as an
unsigned char converted to an int.
**/
-int wctob(wint_t c);
+int wctob(wint_t C);
/** If ps is not a null pointer, the mbsinit function determines whether the
pointed-to mbstate_t object describes an initial conversion state.
@@ -528,19 +1408,98 @@ int mbsinit(const mbstate_t *ps); /* ####### Restartable Multibyte <--> Wide Character Conversion ######### */
-/**
+/** The mbrlen function is equivalent to the call:<BR>
+@verbatim
+ mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)
+@endverbatim
+ where internal is the mbstate_t object for the mbrlen function, except that
+ the expression designated by ps is evaluated only once.
+
+ @return The mbrlen function returns a value between zero and n,
+ inclusive, (size_t)(-2), or (size_t)(-1).
**/
-size_t mbrlen(const char * __restrict s, size_t n, mbstate_t * __restrict ps);
+size_t mbrlen(const char * __restrict S, size_t n, mbstate_t * __restrict ps);
/**
+If S is a null pointer, the mbrtowc function is equivalent to the call:<BR>
+@verbatim
+ mbrtowc(NULL, "", 1, ps)
+@endverbatim
+
+In this case, the values of the parameters pwc and n are ignored.
+
+If S is not a null pointer, the mbrtowc 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 null wide
+character, the resulting state described is the initial conversion state.
+
+ @retval 0 if the next n or fewer bytes complete the multibyte
+ character that corresponds to the null wide
+ character (which is the value stored).
+ @retval between_1_and_n_inclusive if the next n or fewer bytes complete
+ a valid multibyte character (which is the value
+ stored); the value returned is the number of bytes
+ that complete the multibyte character.
+ @retval (size_t)(-2) if the next n bytes contribute to an incomplete
+ (but potentially valid) multibyte character, and
+ all n bytes have been processed (no value is stored).
+ @retval (size_t)(-1) if an encoding error occurs, in which case the next
+ n or fewer bytes do not contribute to a complete and
+ valid multibyte character (no value is stored); the
+ value of the macro EILSEQ is stored in errno, and
+ the conversion state is unspecified.
**/
-size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict s, size_t n, mbstate_t * __restrict ps);
+size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict S, size_t n, mbstate_t * __restrict ps);
/**
+If S is a null pointer, the wcrtomb function is equivalent to the call:<BR>
+@verbatim
+ wcrtomb(buf, L'\0', ps)
+@endverbatim
+where buf is an internal buffer.
+
+If S is not a null pointer, the wcrtomb function determines the number of bytes needed
+to represent the multibyte character that corresponds 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. At most MB_CUR_MAX bytes 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; the resulting state described is the initial conversion state.
+
+ @return The wcrtomb function returns the number of bytes stored in the
+ array object (including any shift sequences). When wc is not a
+ valid wide character, an encoding error occurs: the function
+ stores the value of the macro EILSEQ in errno and
+ returns (size_t)(-1); the conversion state is unspecified.
**/
-size_t wcrtomb(char * __restrict s, wchar_t wc, mbstate_t * __restrict ps);
+size_t wcrtomb(char * __restrict S, wchar_t wc, mbstate_t * __restrict ps);
/**
+The mbsrtowcs function converts a sequence of multibyte characters that begins in the
+conversion state described by the object pointed to by ps, from the array indirectly
+pointed to by src into a sequence of corresponding wide characters. If dst is not a null
+pointer, the converted characters are stored into the array pointed to by dst. Conversion
+continues up to and including a terminating null character, which is also stored.
+Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
+not form a valid multibyte character, or (if dst is not a null pointer) when len wide
+characters have been stored into the array pointed to by dst. Each conversion takes
+place as if by a call to the mbrtowc function.
+
+If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
+pointer (if conversion stopped due to reaching a terminating null character) or the address
+just past the last multibyte character converted (if any). If conversion stopped due to
+reaching a terminating null character and if dst is not a null pointer, the resulting state
+described is the initial conversion state.
+
+ @return If the input conversion encounters a sequence of bytes that do
+ not form a valid multibyte character, an encoding error occurs:
+ the mbsrtowcs function stores the value of the macro EILSEQ in
+ errno and returns (size_t)(-1); the conversion state is
+ unspecified. Otherwise, it returns the number of multibyte
+ characters successfully converted, not including the terminating
+ null character (if any).
**/
size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps);
diff --git a/StdLib/Include/wctype.h b/StdLib/Include/wctype.h index 3df726a353..eac084cbc3 100644 --- a/StdLib/Include/wctype.h +++ b/StdLib/Include/wctype.h @@ -1,5 +1,46 @@ /** @file
- Wide character classification functions and macros.
+ Wide character classification and mapping utilities.
+
+ The following macros are defined in this file:<BR>
+@verbatim
+ WEOF Wide char version of end-of-file.
+@endverbatim
+
+ The following types are defined in this file:<BR>
+@verbatim
+ wint_t Type capable of holding all wchar_t values and WEOF.
+ wctrans_t A type for holding locale-specific character mappings.
+ wctype_t Type for holding locale-specific character classifications.
+@endverbatim
+
+ The following functions are declared in this file:<BR>
+@verbatim
+ ############### Wide Character Classification Functions
+ int iswalnum (wint_t);
+ int iswalpha (wint_t);
+ int iswcntrl (wint_t);
+ int iswdigit (wint_t);
+ int iswgraph (wint_t);
+ int iswlower (wint_t);
+ int iswprint (wint_t);
+ int iswpunct (wint_t);
+ int iswblank (wint_t);
+ int iswspace (wint_t);
+ int iswupper (wint_t);
+ int iswxdigit (wint_t);
+
+ ############### Extensible Wide Character Classification Functions
+ wctype_t wctype (const char *);
+ int iswctype (wint_t, wctype_t);
+
+ ############### Wide Character Case Mapping Utilities
+ wint_t towlower (wint_t);
+ wint_t towupper (wint_t);
+
+ ############### Extensible Wide Character Case Mapping Utilities
+ wctrans_t wctrans (const char *);
+ wint_t towctrans (wint_t, wctrans_t);
+@endverbatim
Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials are licensed and made available under
@@ -45,44 +86,258 @@ #include <machine/ansi.h>
#ifdef _EFI_WINT_T
+ /** wint_t is an integer type unchanged by default argument promotions that can
+ hold any value corresponding to members of the extended character set, as
+ well as at least one value that does not correspond to any member of the
+ extended character set: WEOF.
+ */
typedef _EFI_WINT_T wint_t;
#undef _BSD_WINT_T_
#undef _EFI_WINT_T
#endif
#ifdef _BSD_WCTRANS_T_
-typedef wint_t (*wctrans_t)(wint_t);
-#undef _BSD_WCTRANS_T_
+ /** A scalar type for holding locale-specific character mappings. */
+ typedef wint_t (*wctrans_t)(wint_t);
+ #undef _BSD_WCTRANS_T_
#endif
#ifdef _BSD_WCTYPE_T_
-typedef _BSD_WCTYPE_T_ wctype_t;
-#undef _BSD_WCTYPE_T_
+ /** A scalar type capable of holding values representing locale-specific
+ character classifications. */
+ typedef _BSD_WCTYPE_T_ wctype_t;
+ #undef _BSD_WCTYPE_T_
#endif
#ifndef WEOF
-#define WEOF ((wint_t)-1)
+ /** WEOF expands to a constant expression of type wint_t whose value does not
+ correspond to any member of the extended character set. It is accepted
+ (and returned) by several functions, declared in this file, to indicate
+ end-of-file, that is, no more input from a stream. It is also used as a
+ wide character value that does not correspond to any member of the
+ extended character set.
+ */
+ #define WEOF ((wint_t)-1)
#endif
__BEGIN_DECLS
-int /*EFIAPI*/ iswalnum(wint_t);
-int /*EFIAPI*/ iswalpha(wint_t);
-int /*EFIAPI*/ iswcntrl(wint_t);
-int /*EFIAPI*/ iswctype(wint_t, wctype_t);
-int /*EFIAPI*/ iswdigit(wint_t);
-int /*EFIAPI*/ iswgraph(wint_t);
-int /*EFIAPI*/ iswlower(wint_t);
-int /*EFIAPI*/ iswprint(wint_t);
-int /*EFIAPI*/ iswpunct(wint_t);
-int /*EFIAPI*/ iswblank(wint_t);
-int /*EFIAPI*/ iswspace(wint_t);
-int /*EFIAPI*/ iswupper(wint_t);
-int /*EFIAPI*/ iswxdigit(wint_t);
-wint_t /*EFIAPI*/ towctrans(wint_t, wctrans_t);
-wint_t /*EFIAPI*/ towlower(wint_t);
-wint_t /*EFIAPI*/ towupper(wint_t);
-wctrans_t /*EFIAPI*/ wctrans(const char *);
-wctype_t /*EFIAPI*/ wctype(const char *);
+ /** Test for any wide character for which iswalpha or iswdigit is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswalnum (wint_t WC);
+
+ /** Test for any wide character for which iswupper or iswlower is TRUE,
+ OR, a locale-specific character where none of iswcntrl, iswdigit,
+ iswpunct, or iswspace is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswalpha (wint_t WC);
+
+ /** Test for any wide control character.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswcntrl (wint_t WC);
+
+ /** Test if the value of WC is a wide character that corresponds to a decimal digit.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswdigit (wint_t WC);
+
+ /** Test for wide characters for which iswprint is TRUE and iswspace is FALSE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswgraph (wint_t WC);
+
+ /** The iswlower function tests for any wide character that corresponds to a
+ lowercase letter or is one of a locale-specific set of wide characters
+ for which none of iswcntrl, iswdigit, iswpunct, or iswspace is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswlower (wint_t WC);
+
+ /** Test for any printing wide character.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswprint (wint_t WC);
+
+ /** The iswpunct function tests for any printing wide character that is one
+ of a locale-specific set of punctuation wide characters for which
+ neither iswspace nor iswalnum is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswpunct (wint_t WC);
+
+ /** Test for standard blank characters or locale-specific characters
+ for which iswspace is TRUE and are used to separate words within a line
+ of text. In the "C" locale, iswblank only returns TRUE for the standard
+ blank characters space (L' ') and horizontal tab (L'\t').
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswblank (wint_t WC);
+
+ /** The iswspace function tests for any wide character that corresponds to a
+ locale-specific set of white-space wide characters for which none of
+ iswalnum, iswgraph, or iswpunct is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswspace (wint_t WC);
+
+ /** Tests for any wide character that corresponds to an uppercase letter or
+ is one of a locale-specific set of wide characters for which none of
+ iswcntrl, iswdigit, iswpunct, or iswspace is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswupper (wint_t WC);
+
+ /** The iswxdigit function tests for any wide character that corresponds to a
+ hexadecimal-digit character.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswxdigit (wint_t WC);
+
+ /** Construct a value that describes a class of wide characters, identified
+ by the string pointed to by Desc. The constructed value is suitable for
+ use as the second argument to the iswctype function.
+
+ The following strings name classes of wide characters that the iswctype
+ function is able to test against. These strings are valid in all locales
+ as Desc arguments to wctype().
+ - "alnum"
+ - "alpha"
+ - "blank"
+ - "cntrl"
+ - "digit"
+ - "graph"
+ - "lower"
+ - "print"
+ - "punct"
+ - "space"
+ - "upper"
+ - "xdigit
+
+ @param[in] Desc A pointer to a multibyte character string naming a
+ class of wide characters.
+
+ @return If Desc identifies a valid class of wide characters in the
+ current locale, the wctype function returns a nonzero value that
+ is valid as the second argument to the iswctype function;
+ otherwise, it returns zero.
+ */
+ wctype_t wctype (const char *Desc);
+
+ /** Determine whether the wide character WC has the property described by Wct.
+
+ @param[in] WC The wide character to be classified.
+ @param[in] Wct A value describing a class of wide characters.
+
+ @return The iswctype function returns nonzero (TRUE) if and only if the
+ value of the wide character WC has the property described by Wct.
+ */
+ int iswctype (wint_t WC, wctype_t Wct);
+
+ /** Convert an uppercase letter to a corresponding lowercase letter.
+
+ @param[in] WC The wide character to be converted.
+
+ @return If the argument is a wide character for which iswupper is TRUE
+ and there are one or more corresponding wide characters, as
+ specified by the current locale, for which iswlower is TRUE, the
+ towlower function returns one of the corresponding wide
+ characters (always the same one for any given locale); otherwise,
+ the argument is returned unchanged.
+ */
+ wint_t towlower (wint_t WC);
+
+ /** Convert a lowercase letter to a corresponding uppercase letter.
+
+ @param[in] WC The wide character to be converted.
+
+ @return If the argument is a wide character for which iswlower is TRUE
+ and there are one or more corresponding wide characters, as
+ specified by the current locale, for which iswupper is TRUE, the
+ towupper function returns one of the corresponding wide
+ characters (always the same one for any given locale); otherwise,
+ the argument is returned unchanged.
+ */
+ wint_t towupper (wint_t WC);
+
+ /** Construct a value that describes a mapping between wide characters
+ identified by the string argument, S.
+
+ The strings listed below are valid in all locales as the S argument to
+ the wctrans function.
+ - "tolower"
+ - "toupper"
+
+ @param[in] S A pointer to a multibyte character string naming a
+ mapping between wide characters.
+
+ @return If S identifies a valid mapping of wide characters in the current
+ locale, the wctrans function returns a nonzero value that is
+ valid as the second argument to the towctrans function;
+ otherwise, it returns zero.
+ */
+ wctrans_t wctrans (const char *S);
+
+ /** Map the wide character WC using the mapping described by WTr. The current
+ locale will be the same as during the call to wctrans that returned
+ the value WTr.
+
+ @param[in] WC The wide character to be converted.
+ @param[in] WTr A value describing a mapping of wide characters in the
+ current locale.
+
+ @return Returns the mapped value of WC using the mapping selected by WTr.
+ */
+ wint_t towctrans (wint_t WC, wctrans_t WTr);
__END_DECLS
#endif /* _WCTYPE_H_ */
|