Easy C++ Manual

Easy C++ Manual

General utilities <stdlib.h>

The header <stdlib.h> declares four types, defines several macros and several functions of general utility, and defines several macros.

The type size_t is the unsigned integral type of the result of the sizeof operator.

The type wchar_t is an integral type whose range of values represent distinct codes for all members of the largest extended character set specified among the supported locales; the null character shall have the code value zero and each member of the basic character set shall have a code value equal to its value when used as the lone character in an integer character constant.

The type div_t is a structure type that is the type of the value returned by the div function.

The type ldiv_t is a structure type that is the type of the value returned by the ldiv function.

The macro NULL expands to an implementation-defined null pointer constant.

The macros EXIT_FAILURE and EXIT_SUCCESS expand to integral expressions that may be used as the argument to the exit function to return unsuccessful or successful termination status, respectively, to the host environment.

The macro RAND_MAX expands to an integral constant expression, the value of which is the maximum value returned by the rand function.

The macro MB_CUR_MAX expands to a positive integer expression whose value is the maximum number of bytes in a multibyte character for the extended character set specified by the current locale (category LC_CTYPE), and whose value is never greater than MB_LEN_MAX.

String conversion functions

Name atof

Syntax double atof(const char *nptr);

Description Convert the initial portion of the string pointed to by nptr to double representation. Except for the behaviour on error, it is equivalent to:

strtod(nptr, (char **)NULL)

Returns The converted value.

Name atoi

Syntax int atoi(const char *nptr);

Description Convert the initial portion of the string pointed to by nptr to int representation. Except for the behaviour on error, it is equivalent to:

(int)strtol(nptr, (char **)NULL, 10);

Returns The converted value.

Name atol

Syntax long int atol(const char *nptr);

Description Convert the initial portion of the string pointed to by nptr to long int representation. Except for the behaviour on error, it is equivalent to:

strtol(nptr, (char **)NULL, 10);

Returns The converted value.

Name strtod

Syntax double strtod(const char *nptr, char **endptr);

Description Convert the initial portion of the string pointed to by nptr to double representation. First it decomposes 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; and a final string of one or more unrecognised characters, including the terminating null character of the input string. Then, it attempts to convert the subject sequence to a floating-point number, and returns the result.

The expected form of the subject sequence is an optional plus or minus sign, then a nonempty sequence of digits optionally containing a decimal-point character, then an optional exponent part, but no floating suffix. The subject sequence is defined as the longest initial subsequence of the input string, starting with the first non-white-space character, that is of the expected form. the subject sequence contains no characters if the input string is empty or consists entirely of white space, or if the first non-white-space character is other than a sign, a digit, or a decimal-point character.

If the subject sequence has the expected form, the sequence of characters starting with the first digit or the decimal-point character (whichever occurs first) is interpreted as a floating constant according to the rules, except that the decimal-point character is used in place of a period, and that if neither an exponent part nor a decimal-point character appears, a decimal point is assumed to follow the last digit in the string. If the subject sequence begins with a minus sign, the value resulting from the conversion is negated. 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.

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, plus or minus HUGE_VAL is returned (according to the sign of the value), and the value of the macro ERANGE is stored in errno. If the correct value would cause an underflow, zero is returned and the value of the macro ERANGE is stored in errno.

Name strtol

Syntax long int strtol(const char *nptr, char **endptr, int base);

Description Convert the initial portion of the string pointed to by nptr to long int representation. First it decomposes 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 an integer represented in some radix determined by the value base, and a final string of one or more unrecognised characters including the terminating null character of the input string. Then, it attempts to convert the subject sequence to an integer, and returns the result.

If the value of base is zero, the expected form of the subject sequence is that of an integer constant, optionally preceded by a plus or minus sign, but not including an integer suffix. If the value base is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with the radix specified by base, optionally preceded by a plus or minus sign, but not including an integer suffix. The letters from a (or A) through z (or Z) are ascribed the values 10 to 35; only letters whose ascribed values are less than that of base are permitted, If the value of base is 16, the characters 0x or 0X may optionally precede the sequence of letters or digits, following the sign if present.

The subject sequence is defined as the longest initial subsequence of the input string, starting with the first non-white-space character, that is of the expected form. The subject sequence contains no characters if the input string is empty or consists entirely of white space, or if the first non-white-space character is other than a sign or a permissible letter or digit.

If the subject sequence has the expected form and the value of base is zero, the sequence of characters starting with the first digit is interpreted as an integer constant according to the rules. If the subject sequence has the expected form and base is between 2 and 36, it is used as the base for conversion, ascribing to each letter its value as given above. If the subject sequence begins with a minus sign, the value resulting from the conversion is negated. 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.

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, LONG_MAX or LONG_MIN is returned (according to the sign of the value), and the value of the macro ERANGE is stored in errno.

Name strtoul

Syntax unsigned long int strtoul(const char *nptr, char **endptr, int base);

Description Convert the initial portion of the string pointed to by nptr to unsigned long int representation. First it decomposes 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 an unsigned integer represented in some radix determined by the value of base, and a final string of one or more unrecognised characters , including the terminating null character of the input string. Then, it attempts to convert the subject sequence to an unsigned integer, and returns the result.

If the subject sequence has the expected form and the value of base is zero, the sequence of characters starting with the first digit is interpreted as an integer constant according to the rules. If the subject sequence has the expected form and the value of base is between 2 and 36, it is used as the base for conversion, ascribing to each letter its value as given above. If the subject sequence begins with a minus sign, the value resulting from the conversion is negated. 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.

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.

Pseudo-random sequence generation functions.

Name rand

Syntax int rand(void);

Description Compute a sequence of pseudo-random integers in the range 0 to RAND_MAX.

Returns A pseudo-random integer.

Name srand

Syntax void srand(unsigned int seed);

Description Use the argument as a seed for a new sequence of pseudo-random numbers to be returned by subsequent calls to rand. If srand is then called with the same seed value, the sequence of pseudo-random numbers will 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.

Returns Void.

Memory management functions

The order and contiguity of storage allocated by successive calls to the calloc, malloc and realloc functions is unspecified. The pointer returned if the allocation succeeds is suitable aligned so that it may be assigned to a pointer to any type of object and then used to access such an object or array of such objects in the space allocated (until the space is explicitly freed or reallocated). The pointer returned points to the start (lowest byte address) of the allocated space. If the space cannot be allocated, anull pointer is returned.

Name calloc

Syntax void *calloc(size_t nmemb, size_t size);

Description Allocate space for an array of nmemb objects, each of whose size is size. The space is initialised to all bits zero.

Returns Either a null pointer, or a pointer to the allocated space.

Name free

Syntax void free(void *ptr);

Description Cause the space pointed to by ptr to be deallocated, that is, made available for further allocation. If ptr is a null pointer, no action occurs. Otherwise, if the argument does not match the pointer earlier returned by the calloc, malloc or realloc function, or if the space has been deallocated by a call to free or realloc, the behaviour is undefined.

Returns Void.

Name malloc

Syntax void *malloc(size_t size);

Description Allocate space for an object whose size is specified by size and whose value is indeterminate.

Returns Either a null pointer or a pointer to the allocated space.

Name realloc

Syntax void *realloc(void *ptr, size_t size);

Description Change the size of the object pointed to by ptr to the size specified by size. The contents of the object will be unchanged up to the lesser of the new and old sizes. If the new size is larger, the value of the newly allocated portion of the object is indeterminate. If ptr is a null pointer the realloc function behaves like the malloc function for the specified size. Otherwise, if ptr does not match the pointer earlier returned by the calloc, malloc or realloc function, or if the space has been deallocated by a call to the free or realloc function, the behaviour is undefined. If the space cannot be allocated, the object pointed to by ptr is unchanged. If size is zero and ptr is not a null pointer, the object it points to is freed.

Returns Either a null pointer or a pointer to the possible moved allocated space.

Communication with the environment

Name abort

Syntax void abort(void);

Description Cause abnormal program termination to occur, unless the signal SIGABRT is being caught and the signal handler does not return. Whether open output streams are flushed or open streams closed or temporary files are removed is implementation-defined. An implementation-defined form of the status unsuccessful termination is returned to the host environment by means of the function call raise(SIGABRT).

Returns Cannot return to it's caller.

Name atexit

Syntax int atexit(void(*func)(void));

Description Register the function pointed to by func, to be called without arguments at normal program termination.

Returns Zero if the registration succeeds, nonzero if it fails.

Name exit

Syntax void exit(int status);

Description Cause normal program termination to occur. If more than one call to the exit function is executed by a program, the behaviour is undefined. First, all functions registered by the atexit function are called, in the reverse order of their registration. Next, all open output streams with unwritten buffered data are flushed, all open 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, an implementation-defined form of the status successful termination is returned. If the value of status is EXIT_FAILURE, an implementation-defined form of the status unsuccessful termination is returned. Otherwise the status returned is implementation-defined.

Returns Cannot return to it's caller.

Name getenv

Syntax char *getenv(const char *name );

Description Search an environment list, provided by the host environment, for a string that matches the string pointed to by name. The set of environment names and the method for altering the environment list are implementation defined. The implementation should behave as if no library function calls 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 call to the getenv function. If the specified name cannot be found, a null pointer is returned.

Name system

Syntax int system(const char *string);

Description Pass the string pointed to by string to the host environment to be executed by a command processor in an implementation-defined manner. A null pointer may be used for string to inquire whether a command processor exists.

Returns If the argument is a null pointer, the system function returns nonzero only if there is a command processor available. If the argument is not a null pointer, the system function returns zero for success or -2 for failure. Any other value is the return code from the executed command.

Searching and sorting utilities

Name bsearch

Syntax void *bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (*compar)(const void *, const void *));

Description Search 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 function shall return an integer less than, equal to, or greater than zero if the key object is considered, respectively, to be less than, to match, or to be greater than the array element. The array shall consist 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.

Returns A pointer to a matching element of the array, or a null pointer if no match is found. If two members compare as equal, which element is matched is unspecified.

Name qsort

Syntax void qsort(void *base, size_t nmemb, size_t size, int (*compar)(const void *, const void *));

Description Sort 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 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 than the second. If two elements compare as equal, their order in the sorted array is unspecified.

Returns Void.

Integer arithmetic functions

Name abs

Syntax int abs(int j);

Description Compute the absolute value of an integer j. If the result cannot be represented, the behaviour is undefined.

Returns The absolute value.

Name div

Syntax div_t div(int numer, int denom);

Description Compute the quotient and remainder of the division of the numerator numer by the denominator denom. If the division is inexact, the resulting quotient is the integer of lesser magnitude that is the nearest to the algebraic quotient. less than the magnitude of the mathematical quotient. If the result cannot be represented, the behaviour is undefined; otherwise quot * denom + rem shall equal numer.

Returns A structure of type div_t, comprising both the quotient and remainder. The structure shall contain the following members, in either order:

int quot; /* quotient */ int rem; /* remainder */

Name labs

Syntax long int labs(long int j);

Description Similar to the abs function, except that the argument and the returned value each have type long int.

Name ldiv

Syntax ldiv_t ldiv(long int numer, long int denom);

Description Similar to the div function, except that the arguments and members of the returned structure (which has type ldiv_t) all have type long int.

Multibyte character functions

The behaviour of the multibyte character functions is affected by LC_CTYPE category of the current locale. For a state-dependent encoding, each function is placed into its initial state by a call for which its character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null pointer cause the internal state of the function to be altered as necessary. A call with s as a null pointer causes these functions to return a nonzero value if encodings have state dependency, and zero otherwise. Changing the LC_CTYPE category causes the shift state of these functions to be indeterminate.

Name mblen

Syntax int mblen (const char *s, size_t n);

Description 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 shift state of the mbtowc function is not affected, it is equivalent to:

mbtowc((wchar_t *)0, s, n);

Returns 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 null character), or returns the number of bytes that are contained 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).

Name mbtowc

Syntax int mbtowc (wchar_t *pwc, const char *s, size_t n);

Description If s is not a null pointer, the mbtowc function determines the number of bytes that are contained in the multibyte character pointed to by s. It then determines the code for the value of type wchar_t that corresponds to that multibyte character. (The value of the code corresponding to the null character is zero.) If the multibyte character is valid and pwc is not a null pointer, the mbtowc function stores the code in the object pointed to by pwc. At most n bytes of the array pointed to by s will be examined. The implementation behaves as if no library function calls the mbtowc function.

Returns 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 the null character), or returns the number of bytes that are 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 of the MB_CUR_MAX macro.

Name wctomb

Syntax int wctomb (char *s, wchar_t wchar);

Description Determine the number of bytes needed to represent the multibyte character corresponding to the code whose value is wchar (including any change in shift state). It stores the multibyte character representation in the array object pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters are stored. If the value of wchar is zero, the wctomb function is left in the initial shift state.

Returns 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 wchar 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 wchar.

In no case will the value returned be greater than the value of the MB_CUR_MAX macro.

Multibyte string functions

The behaviour of the multibyte string functions is affected by the LC_CTYPE category of the current locale.

Name mbstowcs

Syntax size_t mbstowcs (wchar_t *pwcs, const char *s, size_t n);

Description Convert a sequence of multibyte characters that begins in the initial shift state from the array pointed to by s into a sequence of corresponding codes and stores not more than n codes into the array pointed to by pwcs. No multibyte characters that follow a null character (which is converted into a code with value zero) will be examined or converted. Each multibyte character is converted as if by a call to mbtowc, except that the shift state of the mbtowc function is not affected.

No more than n elements will be modified in the array pointed to by pwcs. If copying takes place between objects that overlap, the behaviour is undefined.

Returns If an invalid multibyte character is encountered, the mbstowcs function returns (size_t)-1. Otherwise, it returns the number of array elements modified, not including a terminating zero code, if any.

Name wcstombs

Syntax size_t wcstombs (char *s, const wchar_t *pwcs, size_t n);

Description Convert a sequence of codes that correspond to multibyte characters from the array pointed to by pwcs into a sequence of multibyte characters that begins in the initial shift state and stores these multibyte characters into the array pointed to by s, stopping if a multibyte character would exceed the limit of n total bytes or if a null character is stored. Each code is converted as if by a call to the wctomb function, except that the shift state of the wctomb function is not affected. No more than n bytes will be modified in the array pointed to by s. If copying takes place between objects that overlap, the behaviour is undefined.

Returns If a code 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.

APDL and ProAction