Clean up DEC files:

[mirror_edk2.git] / StdLib / Include / stdlib.h

/** @file\r
  The header <stdlib.h> declares five types and several functions of general\r
  utility, and defines several macros.\r
\r
  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>\r
  This program and the accompanying materials are licensed and made available under\r
  the terms and conditions of the BSD License that accompanies this distribution.\r
  The full text of the license may be found at\r
  http://opensource.org/licenses/bsd-license.php.\r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
#ifndef _STDLIB_H\r
#define _STDLIB_H\r
#include  <sys/EfiCdefs.h>\r
\r
#ifdef _EFI_SIZE_T_\r
  typedef _EFI_SIZE_T_  size_t;\r
  #undef _EFI_SIZE_T_\r
  #undef _BSD_SIZE_T_\r
#endif\r
\r
#ifndef __cplusplus\r
  #ifdef _EFI_WCHAR_T\r
    typedef _EFI_WCHAR_T wchar_t;\r
    #undef  _EFI_WCHAR_T\r
    #undef _BSD_WCHAR_T_\r
  #endif\r
#endif\r
\r
/// A structure type that is the type of the value returned by the div function.\r
typedef struct {\r
  int quot;   /* quotient */\r
  int rem;    /* remainder */\r
} div_t;\r
\r
/// A structure type that is the type of the value returned by the ldiv function.\r
typedef struct {\r
  long  quot;\r
  long  rem;\r
} ldiv_t;\r
\r
/// A structure type that is the type of the value returned by the lldiv function.\r
typedef struct {\r
  long long quot;\r
  long long rem;\r
} lldiv_t;\r
\r
/** Expand to integer constant expressions that can be used as the argument to\r
    the exit function to return unsuccessful or successful termination status,\r
    respectively, to the host environment.\r
**/\r
#define EXIT_FAILURE  1\r
#define EXIT_SUCCESS  0\r
\r
/** Expands to an integer constant expression that is the maximum value\r
    returned by the rand function.\r
\r
    The value of the RAND_MAX macro shall be at least 32767.\r
**/\r
#define RAND_MAX  0x7fffffff\r
\r
/** Expands to a positive integer expression with type size_t that is the\r
    maximum number of bytes in a multibyte character for the extended character\r
    set specified by the current locale (category LC_CTYPE), which is never\r
    greater than MB_LEN_MAX.\r
**/\r
#define MB_CUR_MAX  2\r
\r
/** Maximum number of functions that can be registered by atexit.\r
\r
    The C standard states that the implementation shall support the\r
    registration of at least 32 functions.\r
**/\r
#define ATEXIT_MAX  32\r
\r
__BEGIN_DECLS\r
\r
/* ################  Communication with the environment  ################## */\r
\r
/** The abort function causes abnormal program termination to occur, unless\r
    the signal SIGABRT is being caught and the signal handler does not return.\r
\r
    Open streams with unwritten buffered data are not flushed, open\r
    streams are not closed, and temporary files are not removed by abort.\r
\r
    Unsuccessful termination is returned to the host environment by means of\r
    the function call, raise(SIGABRT).\r
\r
    @sa signal.h\r
**/\r
void    abort(void);\r
\r
/** The atexit function registers the function pointed to by func, to be\r
    called without arguments at normal program termination.\r
\r
    The implementation supports the registration of up to 32 functions.\r
\r
    @return   The atexit function returns zero if the registration succeeds,\r
              nonzero if it fails.\r
**/\r
int     atexit(void (*)(void));\r
\r
/** The exit function causes normal program termination to occur. If more than\r
    one call to the exit function is executed by a program,\r
    the behavior is undefined.\r
\r
    First, all functions registered by the atexit function are called, in the\r
    reverse order of their registration, except that a function is called\r
    after any previously registered functions that had already been called at\r
    the time it was registered. If, during the call to any such function, a\r
    call to the longjmp function is made that would terminate the call to the\r
    registered function, the behavior is undefined.\r
\r
    Next, all open streams with unwritten buffered data are flushed, all open\r
    streams are closed, and all files created by the tmpfile function\r
    are removed.\r
\r
    Finally, control is returned to the host environment. If the value of\r
    status is zero, or EXIT_SUCCESS, status is returned unchanged. If the value\r
    of status is EXIT_FAILURE, EAPPLICATION is returned.\r
    Otherwise, status is returned unchanged.\r
**/\r
void    exit(int status) __noreturn;\r
\r
/** The _Exit function causes normal program termination to occur and control\r
    to be returned to the host environment.\r
\r
    No functions registered by the atexit function or signal handlers\r
    registered by the signal function are called.  Open streams with unwritten\r
    buffered data are not flushed, open streams are not closed, and temporary\r
    files are not removed by abort.\r
\r
    The status returned to the host environment is determined in the same way\r
    as for the exit function.\r
**/\r
void    _Exit(int status) __noreturn;\r
\r
/** The getenv function searches an environment list, provided by the host\r
    environment, for a string that matches the string pointed to by name.  The\r
    set of environment names and the method for altering the environment list\r
    are determined by the underlying UEFI Shell implementation.\r
\r
    @return   The getenv function returns a pointer to a string associated with\r
              the matched list member.  The string pointed to shall not be\r
              modified by the program, but may be overwritten by a subsequent\r
              call to the getenv function.  If the specified name cannot be\r
              found, a null pointer is returned.\r
**/\r
char   *getenv(const char *name);\r
\r
/** If string is a null pointer, the system function determines whether the\r
    host environment has a command processor. If string is not a null pointer,\r
    the system function passes the string pointed to by string to that command\r
    processor to be executed in a manner which the implementation shall\r
    document; this might then cause the program calling system to behave in a\r
    non-conforming manner or to terminate.\r
\r
    @return   If the argument is a null pointer, the system function returns\r
              nonzero only if a command processor is available. If the argument\r
              is not a null pointer, and the system function does return, it\r
              returns an implementation-defined value.\r
**/\r
int     system(const char *string);\r
\r
\r
/* ################  Integer arithmetic functions  ######################## */\r
\r
/** Computes the absolute value of an integer j.\r
\r
    @return   The absolute value of j.\r
**/\r
int     abs(int j);\r
\r
/** Computes the absolute value of an integer j.\r
\r
    @return   The absolute value of j.\r
**/\r
long    labs(long j);\r
\r
/** Computes the absolute value of an integer j.\r
\r
    @return   The absolute value of j.\r
**/\r
long long\r
        llabs(long long j);\r
\r
/** Computes numer / denom and numer % denom in a single operation.\r
\r
    @return   Returns a structure of type div_t, comprising both the\r
              quotient and the remainder.\r
**/\r
div_t   div(int numer, int denom);\r
\r
/** Computes numer / denom and numer % denom in a single operation.\r
\r
    @return   Returns a structure of type ldiv_t, comprising both the\r
              quotient and the remainder.\r
**/\r
ldiv_t  ldiv(long numer, long denom);\r
\r
/** Computes numer / denom and numer % denom in a single operation.\r
\r
    @return   Returns a structure of type lldiv_t, comprising both the\r
              quotient and the remainder.\r
**/\r
lldiv_t lldiv(long long numer, long long denom);\r
\r
/* ############  Integer Numeric conversion functions  #################### */\r
\r
/** The atoi function converts the initial portion of the string pointed to by\r
    nptr to int representation.  Except for the behavior on error, it is\r
    equivalent to:\r
      - atoi: (int)strtol(nptr, (char **)NULL, 10)\r
\r
  @return   The atoi function returns the converted value.\r
**/\r
int     atoi(const char *nptr);\r
\r
/** The atol function converts the initial portion of the string pointed to by\r
    nptr to long int representation.  Except for the behavior on error, it is\r
    equivalent to:\r
      - atol: strtol(nptr, (char **)NULL, 10)\r
\r
  @return   The atol function returns the converted value.\r
**/\r
long    atol(const char *nptr);\r
\r
/** The atoll function converts the initial portion of the string pointed to by\r
    nptr to long long int representation.  Except for the behavior on error, it\r
    is equivalent to:\r
      - atoll: strtoll(nptr, (char **)NULL, 10)\r
\r
  @return   The atoll function returns the converted value.\r
**/\r
long long\r
        atoll(const char *nptr);\r
\r
/** The strtol, strtoll, strtoul, and strtoull functions convert the initial\r
    portion of the string pointed to by nptr to long int, long long int,\r
    unsigned long int, and unsigned long long int representation, respectively.\r
    First, they decompose the input string into three parts: an initial,\r
    possibly empty, sequence of white-space characters (as specified by the\r
    isspace function), a subject sequence resembling an integer represented in\r
    some radix determined by the value of base, and a final string of one or\r
    more unrecognized characters, including the terminating null character of\r
    the input string. Then, they attempt to convert the subject sequence to an\r
    integer, and return the result.\r
\r
    If the value of base is zero, the expected form of the subject sequence is\r
    that of an integer constant as described in 6.4.4.1, optionally preceded\r
    by a plus or minus sign, but not including an integer suffix. If the value\r
    of base is between 2 and 36 (inclusive), the expected form of the subject\r
    sequence is a sequence of letters and digits representing an integer with\r
    the radix specified by base, optionally preceded by a plus or minus sign,\r
    but not including an integer suffix. The letters from a (or A) through z\r
    (or Z) are ascribed the values 10 through 35; only letters and digits whose\r
    ascribed values are less than that of base are permitted. If the value of\r
    base is 16, the characters 0x or 0X may optionally precede the sequence of\r
    letters and digits, following the sign if present.\r
\r
    The subject sequence is defined as the longest initial subsequence of the\r
    input string, starting with the first non-white-space character, that is of\r
    the expected form. The subject sequence contains no characters if the input\r
    string is empty or consists entirely of white space, or if the first\r
    non-white-space character is other than a sign or a permissible letter or digit.\r
\r
    If the subject sequence has the expected form and the value of base is\r
    zero, the sequence of characters starting with the first digit is\r
    interpreted as an integer constant. If the subject sequence has the\r
    expected form and the value of base is between 2 and 36, it is used as the\r
    base for conversion, ascribing to each letter its value as given above. If\r
    the subject sequence begins with a minus sign, the value resulting from the\r
    conversion is negated (in the return type). A pointer to the final string\r
    is stored in the object pointed to by endptr, provided that endptr is\r
    not a null pointer.\r
\r
    In other than the "C" locale, additional locale-specific subject sequence\r
    forms may be accepted.\r
\r
    If the subject sequence is empty or does not have the expected form, no\r
    conversion is performed; the value of nptr is stored in the object pointed\r
    to by endptr, provided that endptr is not a null pointer.\r
\r
  @return   The strtol, strtoll, strtoul, and strtoull functions return the\r
            converted value, if any. If no conversion could be performed, zero\r
            is returned. If the correct value is outside the range of\r
            representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,\r
            ULONG_MAX, or ULLONG_MAX is returned (according to the return type\r
            and sign of the value, if any), and the value of the macro ERANGE\r
            is stored in errno.\r
**/\r
long    strtol(const char * __restrict nptr, char ** __restrict endptr, int base);\r
\r
/** The strtoul function converts the initial portion of the string pointed to\r
    by nptr to unsigned long int representation.\r
\r
    See the description for strtol for more information.\r
\r
  @return   The strtoul function returns the converted value, if any. If no\r
            conversion could be performed, zero is returned. If the correct\r
            value is outside the range of representable values, ULONG_MAX is\r
            returned and the value of the macro ERANGE is stored in errno.\r
**/\r
unsigned long\r
        strtoul(const char * __restrict nptr, char ** __restrict endptr, int base);\r
\r
/** The strtoll function converts the initial portion of the string pointed to\r
    by nptr to long long int representation.\r
\r
    See the description for strtol for more information.\r
\r
  @return   The strtoll function returns the converted value, if any. If no\r
            conversion could be performed, zero is returned. If the correct\r
            value is outside the range of representable values, LLONG_MIN or\r
            LLONG_MAX is returned (according to the sign of the value, if any),\r
            and the value of the macro ERANGE is stored in errno.\r
**/\r
long long\r
        strtoll(const char * __restrict nptr, char ** __restrict endptr, int base);\r
\r
/** The strtoull function converts the initial portion of the string pointed to\r
    by nptr to unsigned long long int representation.\r
\r
    See the description for strtol for more information.\r
\r
  @return   The strtoull function returns the converted value, if any. If no\r
            conversion could be performed, zero is returned. If the correct\r
            value is outside the range of representable values, ULLONG_MAX is\r
            returned and the value of the macro ERANGE is stored in errno.\r
**/\r
unsigned long long\r
        strtoull(const char * __restrict nptr, char ** __restrict endptr, int base);\r
\r
/* #########  Floating-point Numeric conversion functions  ################ */\r
\r
/**\r
\r
  @return\r
**/\r
double  atof(const char *);\r
\r
/**\r
\r
  @return\r
**/\r
double  strtod(const char * __restrict nptr, char ** __restrict endptr);\r
\r
/**\r
\r
  @return\r
**/\r
float   strtof(const char * __restrict nptr, char ** __restrict endptr);\r
\r
/**\r
\r
  @return\r
**/\r
long double\r
        strtold(const char * __restrict nptr, char ** __restrict endptr);\r
\r
/* ################  Pseudo-random sequence generation functions  ######### */\r
\r
/** The rand function computes a sequence of pseudo-random integers in the\r
    range 0 to RAND_MAX.\r
\r
    @return   The rand function returns a pseudo-random integer.\r
**/\r
int     rand(void);\r
\r
/** The srand function uses the argument as a seed for a new sequence of\r
    pseudo-random numbers to be returned by subsequent calls to rand.\r
\r
    If srand is then called with the same seed value, the sequence of\r
    pseudo-random numbers shall be repeated. If rand is called before any calls\r
    to srand have been made, the same sequence shall be generated as when srand\r
    is first called with a seed value of 1.\r
**/\r
void    srand(unsigned seed);\r
\r
/* ################  Memory management functions  ######################### */\r
\r
/** The calloc function allocates space for an array of Num objects, each of\r
    whose size is Size.  The space is initialized to all bits zero.\r
\r
    @return   NULL is returned if the space could not be allocated and errno\r
              contains the cause.  Otherwise, a pointer to an 8-byte aligned\r
              region of the requested size is returned.\r
**/\r
void   *calloc(size_t Num, size_t Size);\r
\r
/** The free function causes the space pointed to by Ptr to be deallocated,\r
    that is, made available for further allocation.\r
\r
    If Ptr is a null pointer, no action occurs.  Otherwise, if the argument\r
    does not match a pointer earlier returned by the calloc, malloc, or realloc\r
    function, or if the space has been deallocated by a call to free or\r
    realloc, the behavior is undefined.\r
\r
    @param  Ptr     Pointer to a previously allocated region of memory to be freed.\r
\r
**/\r
void    free(void *);\r
\r
/** The malloc function allocates space for an object whose size is specified\r
    by size and whose value is indeterminate.\r
\r
    This implementation uses the UEFI memory allocation boot services to get a\r
    region of memory that is 8-byte aligned and of the specified size.  The\r
    region is allocated with type EfiLoaderData.\r
\r
    @param  size    Size, in bytes, of the region to allocate.\r
\r
    @return   NULL is returned if the space could not be allocated and errno\r
              contains the cause.  Otherwise, a pointer to an 8-byte aligned\r
              region of the requested size is returned.<BR>\r
              If NULL is returned, errno may contain:\r
              - EINVAL: Requested Size is zero.\r
              - ENOMEM: Memory could not be allocated.\r
**/\r
void   *malloc(size_t);\r
\r
/** The realloc function changes the size of the object pointed to by Ptr to\r
    the size specified by NewSize.\r
\r
    The contents of the object are unchanged up to the lesser of the new and\r
    old sizes.  If the new size is larger, the value of the newly allocated\r
    portion of the object is indeterminate.\r
\r
    If Ptr is a null pointer, the realloc function behaves like the malloc\r
    function for the specified size.\r
\r
    If Ptr does not match a pointer earlier returned by the calloc, malloc, or\r
    realloc function, or if the space has been deallocated by a call to the free\r
    or realloc function, the behavior is undefined.\r
\r
    If the space cannot be allocated, the object pointed to by Ptr is unchanged.\r
\r
    If NewSize is zero and Ptr is not a null pointer, the object it points to\r
    is freed.\r
\r
    This implementation uses the UEFI memory allocation boot services to get a\r
    region of memory that is 8-byte aligned and of the specified size.  The\r
    region is allocated with type EfiLoaderData.\r
\r
    @param  Ptr     Pointer to a previously allocated region of memory to be resized.\r
    @param  NewSize Size, in bytes, of the new object to allocate space for.\r
\r
    @return   NULL is returned if the space could not be allocated and errno\r
              contains the cause.  Otherwise, a pointer to an 8-byte aligned\r
              region of the requested size is returned.  If NewSize is zero,\r
              NULL is returned and errno will be unchanged.\r
**/\r
void   *realloc(void *Ptr, size_t NewSize);\r
\r
/* ################  Searching and Sorting utilities  ##################### */\r
\r
/** The bsearch function searches an array of nmemb objects, the initial\r
    element of which is pointed to by base, for an element that matches the\r
    object pointed to by key. The size of each element of the array is\r
    specified by size.\r
\r
    The comparison function pointed to by compar is called with two arguments\r
    that point to the key object and to an array element, in that order. The\r
    function returns an integer less than, equal to, or greater than zero if\r
    the key object is considered, respectively, to be less than, to match, or\r
    to be greater than the array element. The array consists of: all the\r
    elements that compare less than, all the elements that compare equal to,\r
    and all the elements that compare greater than the key object,\r
    in that order.\r
\r
  @return   The bsearch function returns a pointer to a matching element of the\r
            array, or a null pointer if no match is found. If two elements\r
            compare as equal, which element is matched is unspecified.\r
**/\r
void *\r
bsearch(  const void *key,  const void *base0,\r
          size_t nmemb,     size_t size,\r
          int (*compar)(const void *, const void *)\r
);\r
\r
/** The qsort function sorts an array of nmemb objects, the initial element of\r
    which is pointed to by base.  The size of each object is specified by size.\r
\r
    The contents of the array are sorted into ascending order according to a\r
    comparison function pointed to by compar, which is called with two\r
    arguments that point to the objects being compared. The function shall\r
    return an integer less than, equal to, or greater than zero if the first\r
    argument is considered to be respectively less than, equal to, or greater\r
    than the second.\r
\r
    If two elements compare as equal, their order in the resulting sorted array\r
    is unspecified.\r
**/\r
void qsort( void *base, size_t nmemb, size_t size,\r
            int (*compar)(const void *, const void *));\r
\r
/* ################  Multibyte/wide character conversion functions  ####### */\r
\r
/**\r
\r
  @return\r
**/\r
int     mblen(const char *, size_t);\r
\r
/**\r
\r
  @return\r
**/\r
int     mbtowc(wchar_t * __restrict, const char * __restrict, size_t);\r
\r
/**\r
\r
  @return\r
**/\r
int     wctomb(char *, wchar_t);\r
\r
/* ################  Multibyte/wide string conversion functions  ########## */\r
\r
/**\r
\r
  @return\r
**/\r
size_t  mbstowcs(wchar_t * __restrict , const char * __restrict, size_t);\r
\r
/**\r
\r
  @return\r
**/\r
size_t  wcstombs(char * __restrict, const wchar_t * __restrict, size_t);\r
\r
__END_DECLS\r
\r
#endif  /* _STDLIB_H */\r