]>
git.proxmox.com Git - mirror_edk2.git/blob - StdLib/Include/stdlib.h
2 The header <stdlib.h> declares five types and several functions of general
3 utility, and defines several macros.
5 Copyright (c) 2010 - 2011, 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.
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.
17 #include <sys/EfiCdefs.h>
20 typedef _EFI_SIZE_T_
size_t;
27 typedef _EFI_WCHAR_T
wchar_t;
33 /// A structure type that is the type of the value returned by the div function.
35 int quot
; /* quotient */
36 int rem
; /* remainder */
39 /// A structure type that is the type of the value returned by the ldiv function.
45 /// A structure type that is the type of the value returned by the lldiv function.
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.
55 #define EXIT_FAILURE 1
56 #define EXIT_SUCCESS 0
58 /** Expands to an integer constant expression that is the maximum value
59 returned by the rand function.
61 The value of the RAND_MAX macro shall be at least 32767.
63 #define RAND_MAX 0x7fffffff
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.
72 /** Maximum number of functions that can be registered by atexit.
74 The C standard states that the implementation shall support the
75 registration of at least 32 functions.
81 /* ################ Communication with the environment ################## */
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.
86 Open streams with unwritten buffered data are not flushed, open
87 streams are not closed, and temporary files are not removed by abort.
89 Unsuccessful termination is returned to the host environment by means of
90 the function call, raise(SIGABRT).
94 void abort(void) __noreturn
;
96 /** The atexit function registers the function pointed to by func, to be
97 called without arguments at normal program termination.
99 The implementation supports the registration of up to 32 functions.
101 @return The atexit function returns zero if the registration succeeds,
104 int atexit(void (*)(void));
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.
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.
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
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.
126 While this function does not return, it can NOT be marked as "__noreturn"
127 without causing a warning to be emitted because the compilers can not
128 determine that the function truly does not return.
130 void exit(int status
) __noreturn
;
132 /** The _Exit function causes normal program termination to occur and control
133 to be returned to the host environment.
135 No functions registered by the atexit function or signal handlers
136 registered by the signal function are called. Open streams with unwritten
137 buffered data are not flushed, open streams are not closed, and temporary
138 files are not removed by abort.
140 While this function does not return, it can NOT be marked as "__noreturn"
141 without causing a warning to be emitted because the compilers can not
142 determine that the function truly does not return.
144 The status returned to the host environment is determined in the same way
145 as for the exit function.
147 void _Exit(int status
) __noreturn
;
149 /** The getenv function searches an environment list, provided by the host
150 environment, for a string that matches the string pointed to by name. The
151 set of environment names and the method for altering the environment list
152 are determined by the underlying UEFI Shell implementation.
154 @return The getenv function returns a pointer to a string associated with
155 the matched list member. The string pointed to shall not be
156 modified by the program, but may be overwritten by a subsequent
157 call to the getenv function. If the specified name cannot be
158 found, a null pointer is returned.
160 char *getenv(const char *name
);
163 Add or update a variable in the environment list
165 @param name Address of a zero terminated name string
166 @param value Address of a zero terminated value string
167 @param rewrite TRUE allows overwriting existing values
169 @retval Returns 0 upon success
170 @retval Returns -1 upon failure, sets errno with more information
175 register const char * name
,
176 register const char * value
,
180 /** If string is a null pointer, the system function determines whether the
181 host environment has a command processor. If string is not a null pointer,
182 the system function passes the string pointed to by string to that command
183 processor to be executed in a manner which the implementation shall
184 document; this might then cause the program calling system to behave in a
185 non-conforming manner or to terminate.
187 @return If the argument is a null pointer, the system function returns
188 nonzero only if a command processor is available. If the argument
189 is not a null pointer, and the system function does return, it
190 returns an implementation-defined value.
192 int system(const char *string
);
195 /* ################ Integer arithmetic functions ######################## */
197 /** Computes the absolute value of an integer j.
199 @return The absolute value of j.
203 /** Computes the absolute value of an integer j.
205 @return The absolute value of j.
209 /** Computes the absolute value of an integer j.
211 @return The absolute value of j.
216 /** Computes numer / denom and numer % denom in a single operation.
218 @return Returns a structure of type div_t, comprising both the
219 quotient and the remainder.
221 div_t div(int numer
, int denom
);
223 /** Computes numer / denom and numer % denom in a single operation.
225 @return Returns a structure of type ldiv_t, comprising both the
226 quotient and the remainder.
228 ldiv_t ldiv(long numer
, long denom
);
230 /** Computes numer / denom and numer % denom in a single operation.
232 @return Returns a structure of type lldiv_t, comprising both the
233 quotient and the remainder.
235 lldiv_t
lldiv(long long numer
, long long denom
);
237 /* ############ Integer Numeric conversion functions #################### */
239 /** The atoi function converts the initial portion of the string pointed to by
240 nptr to int representation. Except for the behavior on error, it is
242 - atoi: (int)strtol(nptr, (char **)NULL, 10)
244 @return The atoi function returns the converted value.
246 int atoi(const char *nptr
);
248 /** The atol function converts the initial portion of the string pointed to by
249 nptr to long int representation. Except for the behavior on error, it is
251 - atol: strtol(nptr, (char **)NULL, 10)
253 @return The atol function returns the converted value.
255 long atol(const char *nptr
);
257 /** The atoll function converts the initial portion of the string pointed to by
258 nptr to long long int representation. Except for the behavior on error, it
260 - atoll: strtoll(nptr, (char **)NULL, 10)
262 @return The atoll function returns the converted value.
265 atoll(const char *nptr
);
267 /** The strtol, strtoll, strtoul, and strtoull functions convert the initial
268 portion of the string pointed to by nptr to long int, long long int,
269 unsigned long int, and unsigned long long int representation, respectively.
270 First, they decompose the input string into three parts: an initial,
271 possibly empty, sequence of white-space characters (as specified by the
272 isspace function), a subject sequence resembling an integer represented in
273 some radix determined by the value of base, and a final string of one or
274 more unrecognized characters, including the terminating null character of
275 the input string. Then, they attempt to convert the subject sequence to an
276 integer, and return the result.
278 If the value of base is zero, the expected form of the subject sequence is
279 that of an integer constant as described in 6.4.4.1, optionally preceded
280 by a plus or minus sign, but not including an integer suffix. If the value
281 of base is between 2 and 36 (inclusive), the expected form of the subject
282 sequence is a sequence of letters and digits representing an integer with
283 the radix specified by base, optionally preceded by a plus or minus sign,
284 but not including an integer suffix. The letters from a (or A) through z
285 (or Z) are ascribed the values 10 through 35; only letters and digits whose
286 ascribed values are less than that of base are permitted. If the value of
287 base is 16, the characters 0x or 0X may optionally precede the sequence of
288 letters and digits, following the sign if present.
290 The subject sequence is defined as the longest initial subsequence of the
291 input string, starting with the first non-white-space character, that is of
292 the expected form. The subject sequence contains no characters if the input
293 string is empty or consists entirely of white space, or if the first
294 non-white-space character is other than a sign or a permissible letter or digit.
296 If the subject sequence has the expected form and the value of base is
297 zero, the sequence of characters starting with the first digit is
298 interpreted as an integer constant. If the subject sequence has the
299 expected form and the value of base is between 2 and 36, it is used as the
300 base for conversion, ascribing to each letter its value as given above. If
301 the subject sequence begins with a minus sign, the value resulting from the
302 conversion is negated (in the return type). A pointer to the final string
303 is stored in the object pointed to by endptr, provided that endptr is
306 In other than the "C" locale, additional locale-specific subject sequence
307 forms may be accepted.
309 If the subject sequence is empty or does not have the expected form, no
310 conversion is performed; the value of nptr is stored in the object pointed
311 to by endptr, provided that endptr is not a null pointer.
313 @return The strtol, strtoll, strtoul, and strtoull functions return the
314 converted value, if any. If no conversion could be performed, zero
315 is returned. If the correct value is outside the range of
316 representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,
317 ULONG_MAX, or ULLONG_MAX is returned (according to the return type
318 and sign of the value, if any), and the value of the macro ERANGE
321 long strtol(const char * __restrict nptr
, char ** __restrict endptr
, int base
);
323 /** The strtoul function converts the initial portion of the string pointed to
324 by nptr to unsigned long int representation.
326 See the description for strtol for more information.
328 @return The strtoul function returns the converted value, if any. If no
329 conversion could be performed, zero is returned. If the correct
330 value is outside the range of representable values, ULONG_MAX is
331 returned and the value of the macro ERANGE is stored in errno.
334 strtoul(const char * __restrict nptr
, char ** __restrict endptr
, int base
);
336 /** The strtoll function converts the initial portion of the string pointed to
337 by nptr to long long int representation.
339 See the description for strtol for more information.
341 @return The strtoll function returns the converted value, if any. If no
342 conversion could be performed, zero is returned. If the correct
343 value is outside the range of representable values, LLONG_MIN or
344 LLONG_MAX is returned (according to the sign of the value, if any),
345 and the value of the macro ERANGE is stored in errno.
348 strtoll(const char * __restrict nptr
, char ** __restrict endptr
, int base
);
350 /** The strtoull function converts the initial portion of the string pointed to
351 by nptr to unsigned long long int representation.
353 See the description for strtol for more information.
355 @return The strtoull function returns the converted value, if any. If no
356 conversion could be performed, zero is returned. If the correct
357 value is outside the range of representable values, ULLONG_MAX is
358 returned and the value of the macro ERANGE is stored in errno.
361 strtoull(const char * __restrict nptr
, char ** __restrict endptr
, int base
);
363 /* ######### Floating-point Numeric conversion functions ################ */
369 double atof(const char *);
375 double strtod(const char * __restrict nptr
, char ** __restrict endptr
);
381 float strtof(const char * __restrict nptr
, char ** __restrict endptr
);
388 strtold(const char * __restrict nptr
, char ** __restrict endptr
);
390 /* ################ Pseudo-random sequence generation functions ######### */
392 /** The rand function computes a sequence of pseudo-random integers in the
395 @return The rand function returns a pseudo-random integer.
399 /** The srand function uses the argument as a seed for a new sequence of
400 pseudo-random numbers to be returned by subsequent calls to rand.
402 If srand is then called with the same seed value, the sequence of
403 pseudo-random numbers shall be repeated. If rand is called before any calls
404 to srand have been made, the same sequence shall be generated as when srand
405 is first called with a seed value of 1.
407 void srand(unsigned seed
);
409 /* ################ Memory management functions ######################### */
411 /** The calloc function allocates space for an array of Num objects, each of
412 whose size is Size. The space is initialized to all bits zero.
414 @return NULL is returned if the space could not be allocated and errno
415 contains the cause. Otherwise, a pointer to an 8-byte aligned
416 region of the requested size is returned.
418 void *calloc(size_t Num
, size_t Size
);
420 /** The free function causes the space pointed to by Ptr to be deallocated,
421 that is, made available for further allocation.
423 If Ptr is a null pointer, no action occurs. Otherwise, if the argument
424 does not match a pointer earlier returned by the calloc, malloc, or realloc
425 function, or if the space has been deallocated by a call to free or
426 realloc, the behavior is undefined.
428 @param Ptr Pointer to a previously allocated region of memory to be freed.
433 /** The malloc function allocates space for an object whose size is specified
434 by size and whose value is indeterminate.
436 This implementation uses the UEFI memory allocation boot services to get a
437 region of memory that is 8-byte aligned and of the specified size. The
438 region is allocated with type EfiLoaderData.
440 @param size Size, in bytes, of the region to allocate.
442 @return NULL is returned if the space could not be allocated and errno
443 contains the cause. Otherwise, a pointer to an 8-byte aligned
444 region of the requested size is returned.<BR>
445 If NULL is returned, errno may contain:
446 - EINVAL: Requested Size is zero.
447 - ENOMEM: Memory could not be allocated.
449 void *malloc(size_t);
451 /** The realloc function changes the size of the object pointed to by Ptr to
452 the size specified by NewSize.
454 The contents of the object are unchanged up to the lesser of the new and
455 old sizes. If the new size is larger, the value of the newly allocated
456 portion of the object is indeterminate.
458 If Ptr is a null pointer, the realloc function behaves like the malloc
459 function for the specified size.
461 If Ptr does not match a pointer earlier returned by the calloc, malloc, or
462 realloc function, or if the space has been deallocated by a call to the free
463 or realloc function, the behavior is undefined.
465 If the space cannot be allocated, the object pointed to by Ptr is unchanged.
467 If NewSize is zero and Ptr is not a null pointer, the object it points to
470 This implementation uses the UEFI memory allocation boot services to get a
471 region of memory that is 8-byte aligned and of the specified size. The
472 region is allocated with type EfiLoaderData.
474 @param Ptr Pointer to a previously allocated region of memory to be resized.
475 @param NewSize Size, in bytes, of the new object to allocate space for.
477 @return NULL is returned if the space could not be allocated and errno
478 contains the cause. Otherwise, a pointer to an 8-byte aligned
479 region of the requested size is returned. If NewSize is zero,
480 NULL is returned and errno will be unchanged.
482 void *realloc(void *Ptr
, size_t NewSize
);
484 /* ################ Searching and Sorting utilities ##################### */
486 /** The bsearch function searches an array of nmemb objects, the initial
487 element of which is pointed to by base, for an element that matches the
488 object pointed to by key. The size of each element of the array is
491 The comparison function pointed to by compar is called with two arguments
492 that point to the key object and to an array element, in that order. The
493 function returns an integer less than, equal to, or greater than zero if
494 the key object is considered, respectively, to be less than, to match, or
495 to be greater than the array element. The array consists of: all the
496 elements that compare less than, all the elements that compare equal to,
497 and all the elements that compare greater than the key object,
500 @return The bsearch function returns a pointer to a matching element of the
501 array, or a null pointer if no match is found. If two elements
502 compare as equal, which element is matched is unspecified.
505 bsearch( const void *key
, const void *base0
,
506 size_t nmemb
, size_t size
,
507 int (*compar
)(const void *, const void *)
510 /** The qsort function sorts an array of nmemb objects, the initial element of
511 which is pointed to by base. The size of each object is specified by size.
513 The contents of the array are sorted into ascending order according to a
514 comparison function pointed to by compar, which is called with two
515 arguments that point to the objects being compared. The function shall
516 return an integer less than, equal to, or greater than zero if the first
517 argument is considered to be respectively less than, equal to, or greater
520 If two elements compare as equal, their order in the resulting sorted array
523 void qsort( void *base
, size_t nmemb
, size_t size
,
524 int (*compar
)(const void *, const void *));
526 /* ################ Multibyte/wide character conversion functions ####### */
528 /** Determine the number of bytes comprising a multibyte character.
530 If s is not a null pointer, the mblen function determines the number of bytes
531 contained in the multibyte character pointed to by s. Except that the
532 conversion state of the mbtowc function is not affected, it is equivalent to
533 mbtowc((wchar_t *)0, s, n);
535 The implementation shall behave as if no library function calls the mblen
538 @return If s is a null pointer, the mblen function returns a nonzero or
539 zero value, if multibyte character encodings, respectively, do
540 or do not have state-dependent encodings. If s is not a null
541 pointer, the mblen function either returns 0 (if s points to the
542 null character), or returns the number of bytes that are contained
543 in the multibyte character (if the next n or fewer bytes form a
544 valid multibyte character), or returns -1 (if they do not form a
545 valid multibyte character).
547 int mblen(const char *, size_t);
549 /** Convert a multibyte character into a wide character.
551 If s is not a null pointer, the mbtowc function inspects at most n bytes
552 beginning with the byte pointed to by s to determine the number of bytes
553 needed to complete the next multibyte character (including any shift
554 sequences). If the function determines that the next multibyte character
555 is complete and valid, it determines the value of the corresponding wide
556 character and then, if pwc is not a null pointer, stores that value in
557 the object pointed to by pwc. If the corresponding wide character is the
558 null wide character, the function is left in the initial conversion state.
560 The implementation shall behave as if no library function calls the
563 @return If s is a null pointer, the mbtowc function returns a nonzero or
564 zero value, if multibyte character encodings, respectively, do
565 or do not have state-dependent encodings. If s is not a null
566 pointer, the mbtowc function either returns 0 (if s points to
567 the null character), or returns the number of bytes that are
568 contained in the converted multibyte character (if the next n or
569 fewer bytes form a valid multibyte character), or returns -1
570 (if they do not form a valid multibyte character).
572 In no case will the value returned be greater than n or the value
573 of the MB_CUR_MAX macro.
575 int mbtowc(wchar_t * __restrict
, const char * __restrict
, size_t);
578 The wctomb function determines the number of bytes needed to represent the multibyte
579 character corresponding to the wide character given by wc (including any shift
580 sequences), and stores the multibyte character representation in the array whose first
581 element is pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters
582 are stored. If wc is a null wide character, a null byte is stored, preceded by any shift
583 sequence needed to restore the initial shift state, and the function is left in the initial
586 The implementation shall behave as if no library function calls the wctomb function.
589 If s is a null pointer, the wctomb function returns a nonzero or zero value, if multibyte
590 character encodings, respectively, do or do not have state-dependent encodings. If s is
591 not a null pointer, the wctomb function returns -1 if the value of wc does not correspond
592 to a valid multibyte character, or returns the number of bytes that are contained in the
593 multibyte character corresponding to the value of wc.
595 In no case will the value returned be greater than the value of the MB_CUR_MAX macro.
598 int wctomb(char *, wchar_t);
600 /* ################ Multibyte/wide string conversion functions ########## */
602 /** Convert a multibyte character string into a wide-character string.
604 The mbstowcs function converts a sequence of multibyte characters that
605 begins in the initial shift state from the array pointed to by src into
606 a sequence of corresponding wide characters and stores not more than limit
607 wide characters into the array pointed to by dest. No multibyte
608 characters that follow a null character (which is converted into a null
609 wide character) will be examined or converted. Each multibyte character
610 is converted as if by a call to the mbtowc function, except that the
611 conversion state of the mbtowc function is not affected.
613 No more than limit elements will be modified in the array pointed to by dest.
614 If copying takes place between objects that overlap,
615 the behavior is undefined.
617 @return If an invalid multibyte character is encountered, the mbstowcs
618 function returns (size_t)(-1). Otherwise, the mbstowcs function
619 returns the number of array elements modified, not including a
620 terminating null wide character, if any.
623 size_t mbstowcs(wchar_t * __restrict dest
, const char * __restrict src
, size_t limit
);
625 /** Convert a wide-character string into a multibyte character string.
627 The wcstombs function converts a sequence of wide characters from the
628 array pointed to by src into a sequence of corresponding multibyte
629 characters that begins in the initial shift state, and stores these
630 multibyte characters into the array pointed to by dest, stopping if a
631 multibyte character would exceed the limit of limit total bytes or if a
632 null character is stored. Each wide character is converted as if by
633 a call to the wctomb function, except that the conversion state of
634 the wctomb function is not affected.
636 No more than limit bytes will be modified in the array pointed to by dest.
637 If copying takes place between objects that overlap,
638 the behavior is undefined.
640 @return If a wide character is encountered that does not correspond to a
641 valid multibyte character, the wcstombs function returns
642 (size_t)(-1). Otherwise, the wcstombs function returns the number
643 of bytes modified, not including a terminating null character,
646 size_t wcstombs(char * __restrict dest
, const wchar_t * __restrict src
, size_t limit
);
649 The realpath() function shall derive, from the pathname pointed to by
650 file_name, an absolute pathname that names the same file, whose resolution
651 does not involve '.', '..', or symbolic links. The generated pathname shall
652 be stored as a null-terminated string, up to a maximum of {PATH_MAX} bytes,
653 in the buffer pointed to by resolved_name.
655 If resolved_name is a null pointer, the behavior of realpath() is
656 implementation-defined.
658 @param[in] file_name The filename to convert.
659 @param[in,out] resolved_name The resultant name.
661 @retval NULL An error occured.
662 @return resolved_name.
664 char * realpath(char *file_name
, char *resolved_name
);
667 The getprogname() function returns the name of the program. If the name
668 has not been set yet, it will return NULL.
670 @retval The name of the program.
671 @retval NULL The name has not been set.
673 const char * getprogname(void);
676 The setprogname() function sets the name of the program.
678 @param[in] The name of the program. This memory must be retained
679 by the caller until no calls to "getprogname" will be
682 void setprogname(const char *progname
);
686 #endif /* _STDLIB_H */