StdLib/Include/stdlib.h

   1 /** @file
   2   The header <stdlib.h> declares five types and several functions of general
   3   utility, and defines several macros.
   4
   5   Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
   6   This program and the accompanying materials are licensed and made available under
   7   the terms and conditions of the BSD License that accompanies this distribution.
   8   The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php.
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15 #ifndef _STDLIB_H
  16 #define _STDLIB_H
  17 #include  <sys/EfiCdefs.h>
  18
  19 #ifdef _EFI_SIZE_T_
  20   typedef _EFI_SIZE_T_  size_t;
  21   #undef _EFI_SIZE_T_
  22   #undef _BSD_SIZE_T_
  23 #endif
  24
  25 #ifndef __cplusplus
  26   #ifdef _EFI_WCHAR_T
  27     typedef _EFI_WCHAR_T wchar_t;
  28     #undef  _EFI_WCHAR_T
  29     #undef _BSD_WCHAR_T_
  30   #endif
  31 #endif
  32
  33 /// A structure type that is the type of the value returned by the div function.
  34 typedef struct {
  35   int quot;   /* quotient */
  36   int rem;    /* remainder */
  37 } div_t;
  38
  39 /// A structure type that is the type of the value returned by the ldiv function.
  40 typedef struct {
  41   long  quot;
  42   long  rem;
  43 } ldiv_t;
  44
  45 /// A structure type that is the type of the value returned by the lldiv function.
  46 typedef struct {
  47   long long quot;
  48   long long rem;
  49 } lldiv_t;
  50
  51 /** Expand to integer constant expressions that can be used as the argument to
  52     the exit function to return unsuccessful or successful termination status,
  53     respectively, to the host environment.
  54 **/
  55 #define EXIT_FAILURE  1
  56 #define EXIT_SUCCESS  0
  57
  58 /** Expands to an integer constant expression that is the maximum value
  59     returned by the rand function.
  60
  61     The value of the RAND_MAX macro shall be at least 32767.
  62 **/
  63 #define RAND_MAX  0x7fffffff
  64
  65 /** Expands to a positive integer expression with type size_t that is the
  66     maximum number of bytes in a multibyte character for the extended character
  67     set specified by the current locale (category LC_CTYPE), which is never
  68     greater than MB_LEN_MAX.
  69 **/
  70 #define MB_CUR_MAX  2
  71
  72 /** Maximum number of functions that can be registered by atexit.
  73
  74     The C standard states that the implementation shall support the
  75     registration of at least 32 functions.
  76 **/
  77 #define ATEXIT_MAX  32
  78
  79 __BEGIN_DECLS
  80
  81 /* ################  Communication with the environment  ################## */
  82
  83 /** The abort function causes abnormal program termination to occur, unless
  84     the signal SIGABRT is being caught and the signal handler does not return.
  85
  86     Open streams with unwritten buffered data are not flushed, open
  87     streams are not closed, and temporary files are not removed by abort.
  88
  89     Unsuccessful termination is returned to the host environment by means of
  90     the function call, raise(SIGABRT).
  91
  92     @sa signal.h
  93 **/
  94 void    abort(void);
  95
  96 /** The atexit function registers the function pointed to by func, to be
  97     called without arguments at normal program termination.
  98
  99     The implementation supports the registration of up to 32 functions.
 100
 101     @return   The atexit function returns zero if the registration succeeds,
 102               nonzero if it fails.
 103 **/
 104 int     atexit(void (*)(void));
 105
 106 /** The exit function causes normal program termination to occur. If more than
 107     one call to the exit function is executed by a program,
 108     the behavior is undefined.
 109
 110     First, all functions registered by the atexit function are called, in the
 111     reverse order of their registration, except that a function is called
 112     after any previously registered functions that had already been called at
 113     the time it was registered. If, during the call to any such function, a
 114     call to the longjmp function is made that would terminate the call to the
 115     registered function, the behavior is undefined.
 116
 117     Next, all open streams with unwritten buffered data are flushed, all open
 118     streams are closed, and all files created by the tmpfile function
 119     are removed.
 120
 121     Finally, control is returned to the host environment. If the value of
 122     status is zero, or EXIT_SUCCESS, status is returned unchanged. If the value
 123     of status is EXIT_FAILURE, EAPPLICATION is returned.
 124     Otherwise, status is returned unchanged.
 125 **/
 126 void    exit(int status) __noreturn;
 127
 128 /** The _Exit function causes normal program termination to occur and control
 129     to be returned to the host environment.
 130
 131     No functions registered by the atexit function or signal handlers
 132     registered by the signal function are called.  Open streams with unwritten
 133     buffered data are not flushed, open streams are not closed, and temporary
 134     files are not removed by abort.
 135
 136     The status returned to the host environment is determined in the same way
 137     as for the exit function.
 138 **/
 139 void    _Exit(int status) __noreturn;
 140
 141 /** The getenv function searches an environment list, provided by the host
 142     environment, for a string that matches the string pointed to by name.  The
 143     set of environment names and the method for altering the environment list
 144     are determined by the underlying UEFI Shell implementation.
 145
 146     @return   The getenv function returns a pointer to a string associated with
 147               the matched list member.  The string pointed to shall not be
 148               modified by the program, but may be overwritten by a subsequent
 149               call to the getenv function.  If the specified name cannot be
 150               found, a null pointer is returned.
 151 **/
 152 char   *getenv(const char *name);
 153
 154 /** If string is a null pointer, the system function determines whether the
 155     host environment has a command processor. If string is not a null pointer,
 156     the system function passes the string pointed to by string to that command
 157     processor to be executed in a manner which the implementation shall
 158     document; this might then cause the program calling system to behave in a
 159     non-conforming manner or to terminate.
 160
 161     @return   If the argument is a null pointer, the system function returns
 162               nonzero only if a command processor is available. If the argument
 163               is not a null pointer, and the system function does return, it
 164               returns an implementation-defined value.
 165 **/
 166 int     system(const char *string);
 167
 168
 169 /* ################  Integer arithmetic functions  ######################## */
 170
 171 /** Computes the absolute value of an integer j.
 172
 173     @return   The absolute value of j.
 174 **/
 175 int     abs(int j);
 176
 177 /** Computes the absolute value of an integer j.
 178
 179     @return   The absolute value of j.
 180 **/
 181 long    labs(long j);
 182
 183 /** Computes the absolute value of an integer j.
 184
 185     @return   The absolute value of j.
 186 **/
 187 long long
 188         llabs(long long j);
 189
 190 /** Computes numer / denom and numer % denom in a single operation.
 191
 192     @return   Returns a structure of type div_t, comprising both the
 193               quotient and the remainder.
 194 **/
 195 div_t   div(int numer, int denom);
 196
 197 /** Computes numer / denom and numer % denom in a single operation.
 198
 199     @return   Returns a structure of type ldiv_t, comprising both the
 200               quotient and the remainder.
 201 **/
 202 ldiv_t  ldiv(long numer, long denom);
 203
 204 /** Computes numer / denom and numer % denom in a single operation.
 205
 206     @return   Returns a structure of type lldiv_t, comprising both the
 207               quotient and the remainder.
 208 **/
 209 lldiv_t lldiv(long long numer, long long denom);
 210
 211 /* ############  Integer Numeric conversion functions  #################### */
 212
 213 /** The atoi function converts the initial portion of the string pointed to by
 214     nptr to int representation.  Except for the behavior on error, it is
 215     equivalent to:
 216       - atoi: (int)strtol(nptr, (char **)NULL, 10)
 217
 218   @return   The atoi function returns the converted value.
 219 **/
 220 int     atoi(const char *nptr);
 221
 222 /** The atol function converts the initial portion of the string pointed to by
 223     nptr to long int representation.  Except for the behavior on error, it is
 224     equivalent to:
 225       - atol: strtol(nptr, (char **)NULL, 10)
 226
 227   @return   The atol function returns the converted value.
 228 **/
 229 long    atol(const char *nptr);
 230
 231 /** The atoll function converts the initial portion of the string pointed to by
 232     nptr to long long int representation.  Except for the behavior on error, it
 233     is equivalent to:
 234       - atoll: strtoll(nptr, (char **)NULL, 10)
 235
 236   @return   The atoll function returns the converted value.
 237 **/
 238 long long
 239         atoll(const char *nptr);
 240
 241 /** The strtol, strtoll, strtoul, and strtoull functions convert the initial
 242     portion of the string pointed to by nptr to long int, long long int,
 243     unsigned long int, and unsigned long long int representation, respectively.
 244     First, they decompose the input string into three parts: an initial,
 245     possibly empty, sequence of white-space characters (as specified by the
 246     isspace function), a subject sequence resembling an integer represented in
 247     some radix determined by the value of base, and a final string of one or
 248     more unrecognized characters, including the terminating null character of
 249     the input string. Then, they attempt to convert the subject sequence to an
 250     integer, and return the result.
 251
 252     If the value of base is zero, the expected form of the subject sequence is
 253     that of an integer constant as described in 6.4.4.1, optionally preceded
 254     by a plus or minus sign, but not including an integer suffix. If the value
 255     of base is between 2 and 36 (inclusive), the expected form of the subject
 256     sequence is a sequence of letters and digits representing an integer with
 257     the radix specified by base, optionally preceded by a plus or minus sign,
 258     but not including an integer suffix. The letters from a (or A) through z
 259     (or Z) are ascribed the values 10 through 35; only letters and digits whose
 260     ascribed values are less than that of base are permitted. If the value of
 261     base is 16, the characters 0x or 0X may optionally precede the sequence of
 262     letters and digits, following the sign if present.
 263
 264     The subject sequence is defined as the longest initial subsequence of the
 265     input string, starting with the first non-white-space character, that is of
 266     the expected form. The subject sequence contains no characters if the input
 267     string is empty or consists entirely of white space, or if the first
 268     non-white-space character is other than a sign or a permissible letter or digit.
 269
 270     If the subject sequence has the expected form and the value of base is
 271     zero, the sequence of characters starting with the first digit is
 272     interpreted as an integer constant. If the subject sequence has the
 273     expected form and the value of base is between 2 and 36, it is used as the
 274     base for conversion, ascribing to each letter its value as given above. If
 275     the subject sequence begins with a minus sign, the value resulting from the
 276     conversion is negated (in the return type). A pointer to the final string
 277     is stored in the object pointed to by endptr, provided that endptr is
 278     not a null pointer.
 279
 280     In other than the "C" locale, additional locale-specific subject sequence
 281     forms may be accepted.
 282
 283     If the subject sequence is empty or does not have the expected form, no
 284     conversion is performed; the value of nptr is stored in the object pointed
 285     to by endptr, provided that endptr is not a null pointer.
 286
 287   @return   The strtol, strtoll, strtoul, and strtoull functions return the
 288             converted value, if any. If no conversion could be performed, zero
 289             is returned. If the correct value is outside the range of
 290             representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,
 291             ULONG_MAX, or ULLONG_MAX is returned (according to the return type
 292             and sign of the value, if any), and the value of the macro ERANGE
 293             is stored in errno.
 294 **/
 295 long    strtol(const char * __restrict nptr, char ** __restrict endptr, int base);
 296
 297 /** The strtoul function converts the initial portion of the string pointed to
 298     by nptr to unsigned long int representation.
 299
 300     See the description for strtol for more information.
 301
 302   @return   The strtoul function returns the converted value, if any. If no
 303             conversion could be performed, zero is returned. If the correct
 304             value is outside the range of representable values, ULONG_MAX is
 305             returned and the value of the macro ERANGE is stored in errno.
 306 **/
 307 unsigned long
 308         strtoul(const char * __restrict nptr, char ** __restrict endptr, int base);
 309
 310 /** The strtoll function converts the initial portion of the string pointed to
 311     by nptr to long long int representation.
 312
 313     See the description for strtol for more information.
 314
 315   @return   The strtoll function returns the converted value, if any. If no
 316             conversion could be performed, zero is returned. If the correct
 317             value is outside the range of representable values, LLONG_MIN or
 318             LLONG_MAX is returned (according to the sign of the value, if any),
 319             and the value of the macro ERANGE is stored in errno.
 320 **/
 321 long long
 322         strtoll(const char * __restrict nptr, char ** __restrict endptr, int base);
 323
 324 /** The strtoull function converts the initial portion of the string pointed to
 325     by nptr to unsigned long long int representation.
 326
 327     See the description for strtol for more information.
 328
 329   @return   The strtoull function returns the converted value, if any. If no
 330             conversion could be performed, zero is returned. If the correct
 331             value is outside the range of representable values, ULLONG_MAX is
 332             returned and the value of the macro ERANGE is stored in errno.
 333 **/
 334 unsigned long long
 335         strtoull(const char * __restrict nptr, char ** __restrict endptr, int base);
 336
 337 /* #########  Floating-point Numeric conversion functions  ################ */
 338
 339 /**
 340
 341   @return
 342 **/
 343 double  atof(const char *);
 344
 345 /**
 346
 347   @return
 348 **/
 349 double  strtod(const char * __restrict nptr, char ** __restrict endptr);
 350
 351 /**
 352
 353   @return
 354 **/
 355 float   strtof(const char * __restrict nptr, char ** __restrict endptr);
 356
 357 /**
 358
 359   @return
 360 **/
 361 long double
 362         strtold(const char * __restrict nptr, char ** __restrict endptr);
 363
 364 /* ################  Pseudo-random sequence generation functions  ######### */
 365
 366 /** The rand function computes a sequence of pseudo-random integers in the
 367     range 0 to RAND_MAX.
 368
 369     @return   The rand function returns a pseudo-random integer.
 370 **/
 371 int     rand(void);
 372
 373 /** The srand function uses the argument as a seed for a new sequence of
 374     pseudo-random numbers to be returned by subsequent calls to rand.
 375
 376     If srand is then called with the same seed value, the sequence of
 377     pseudo-random numbers shall be repeated. If rand is called before any calls
 378     to srand have been made, the same sequence shall be generated as when srand
 379     is first called with a seed value of 1.
 380 **/
 381 void    srand(unsigned seed);
 382
 383 /* ################  Memory management functions  ######################### */
 384
 385 /** The calloc function allocates space for an array of Num objects, each of
 386     whose size is Size.  The space is initialized to all bits zero.
 387
 388     @return   NULL is returned if the space could not be allocated and errno
 389               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 390               region of the requested size is returned.
 391 **/
 392 void   *calloc(size_t Num, size_t Size);
 393
 394 /** The free function causes the space pointed to by Ptr to be deallocated,
 395     that is, made available for further allocation.
 396
 397     If Ptr is a null pointer, no action occurs.  Otherwise, if the argument
 398     does not match a pointer earlier returned by the calloc, malloc, or realloc
 399     function, or if the space has been deallocated by a call to free or
 400     realloc, the behavior is undefined.
 401
 402     @param  Ptr     Pointer to a previously allocated region of memory to be freed.
 403
 404 **/
 405 void    free(void *);
 406
 407 /** The malloc function allocates space for an object whose size is specified
 408     by size and whose value is indeterminate.
 409
 410     This implementation uses the UEFI memory allocation boot services to get a
 411     region of memory that is 8-byte aligned and of the specified size.  The
 412     region is allocated with type EfiLoaderData.
 413
 414     @param  size    Size, in bytes, of the region to allocate.
 415
 416     @return   NULL is returned if the space could not be allocated and errno
 417               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 418               region of the requested size is returned.<BR>
 419               If NULL is returned, errno may contain:
 420               - EINVAL: Requested Size is zero.
 421               - ENOMEM: Memory could not be allocated.
 422 **/
 423 void   *malloc(size_t);
 424
 425 /** The realloc function changes the size of the object pointed to by Ptr to
 426     the size specified by NewSize.
 427
 428     The contents of the object are unchanged up to the lesser of the new and
 429     old sizes.  If the new size is larger, the value of the newly allocated
 430     portion of the object is indeterminate.
 431
 432     If Ptr is a null pointer, the realloc function behaves like the malloc
 433     function for the specified size.
 434
 435     If Ptr does not match a pointer earlier returned by the calloc, malloc, or
 436     realloc function, or if the space has been deallocated by a call to the free
 437     or realloc function, the behavior is undefined.
 438
 439     If the space cannot be allocated, the object pointed to by Ptr is unchanged.
 440
 441     If NewSize is zero and Ptr is not a null pointer, the object it points to
 442     is freed.
 443
 444     This implementation uses the UEFI memory allocation boot services to get a
 445     region of memory that is 8-byte aligned and of the specified size.  The
 446     region is allocated with type EfiLoaderData.
 447
 448     @param  Ptr     Pointer to a previously allocated region of memory to be resized.
 449     @param  NewSize Size, in bytes, of the new object to allocate space for.
 450
 451     @return   NULL is returned if the space could not be allocated and errno
 452               contains the cause.  Otherwise, a pointer to an 8-byte aligned
 453               region of the requested size is returned.  If NewSize is zero,
 454               NULL is returned and errno will be unchanged.
 455 **/
 456 void   *realloc(void *Ptr, size_t NewSize);
 457
 458 /* ################  Searching and Sorting utilities  ##################### */
 459
 460 /** The bsearch function searches an array of nmemb objects, the initial
 461     element of which is pointed to by base, for an element that matches the
 462     object pointed to by key. The size of each element of the array is
 463     specified by size.
 464
 465     The comparison function pointed to by compar is called with two arguments
 466     that point to the key object and to an array element, in that order. The
 467     function returns an integer less than, equal to, or greater than zero if
 468     the key object is considered, respectively, to be less than, to match, or
 469     to be greater than the array element. The array consists of: all the
 470     elements that compare less than, all the elements that compare equal to,
 471     and all the elements that compare greater than the key object,
 472     in that order.
 473
 474   @return   The bsearch function returns a pointer to a matching element of the
 475             array, or a null pointer if no match is found. If two elements
 476             compare as equal, which element is matched is unspecified.
 477 **/
 478 void *
 479 bsearch(  const void *key,  const void *base0,
 480           size_t nmemb,     size_t size,
 481           int (*compar)(const void *, const void *)
 482 );
 483
 484 /** The qsort function sorts an array of nmemb objects, the initial element of
 485     which is pointed to by base.  The size of each object is specified by size.
 486
 487     The contents of the array are sorted into ascending order according to a
 488     comparison function pointed to by compar, which is called with two
 489     arguments that point to the objects being compared. The function shall
 490     return an integer less than, equal to, or greater than zero if the first
 491     argument is considered to be respectively less than, equal to, or greater
 492     than the second.
 493
 494     If two elements compare as equal, their order in the resulting sorted array
 495     is unspecified.
 496 **/
 497 void qsort( void *base, size_t nmemb, size_t size,
 498             int (*compar)(const void *, const void *));
 499
 500 /* ################  Multibyte/wide character conversion functions  ####### */
 501
 502 /**
 503
 504   @return
 505 **/
 506 int     mblen(const char *, size_t);
 507
 508 /**
 509
 510   @return
 511 **/
 512 int     mbtowc(wchar_t * __restrict, const char * __restrict, size_t);
 513
 514 /**
 515
 516   @return
 517 **/
 518 int     wctomb(char *, wchar_t);
 519
 520 /* ################  Multibyte/wide string conversion functions  ########## */
 521
 522 /**
 523
 524   @return
 525 **/
 526 size_t  mbstowcs(wchar_t * __restrict , const char * __restrict, size_t);
 527
 528 /**
 529
 530   @return
 531 **/
 532 size_t  wcstombs(char * __restrict, const wchar_t * __restrict, size_t);
 533
 534 __END_DECLS
 535
 536 #endif  /* _STDLIB_H */