Draft 2002-06-14

<cstdlib>

The <cstdlib> header is a wrapper for the C standard <stdlib.h> header, which declares macros, types, and functions of general utility.

abort function

Terminate the program abnormally

void abort()

The abort function raises SIGABRT. Unless the program has registered a handler for the SIGABRT signal, the default action is to terminate the program.

See Also

exit function, raise in <csignal>, SIGABRT in <csignal>

abs function

Absolute value

int abs(int x)
long abs(long x)

The abs function returns the absolute value of x. The <cmath> header declares floating point versions of the abs function.

See Also

labs function, abs function in <cmath>

atexit function

Call a function at program termination

extern "C"   int atexit(void (*func)())
extern "C++" int atexit(void (*func)())

The atexit function registers a parameterless function, func, to be called when the program exits normally.

Registered functions are called in the opposite order of registration. A function can be registered more than once, in which case it will be called as many times as it was registered.

The atexit functions are not called if the program exits due to a signal, such as SIGABRT.

See Also

abort function, exit function

atof function

Convert a string to floating point

double atof(const char* s)

The atof function reads a floating point number from the string s, and returns the value of the floating point number. The conversion is similar to calling strtod(s, (char **) NULL).

See Also

atoi function, atol function, strtod function

atoi function

Convert a string to integer

int atoi(const char* s)

The atoi function reads an integer from the string s, and returns the value of the number. The conversion is similar to calling strtol(s, (char **) NULL, 10), and casting the result to an int.

See Also

atof function, atol function, strtod function

atol function

Convert a string to long integer

long atol(const char* s)

The atol function reads an integer from the string s, and returns the value of the number. The conversion is similar to calling strtol(s, (char **) NULL, 10).

See Also

atof function, atoi function, strtol function, strtoul func

bsearch function

Binary search

extern "C"
  void* bsearch(const void* key, const void* base,
                size_t count, size_t size,
                int (*compare)(const void*, const void*))
extern "C++"
  void* bsearch(const void* key, const void* base,
                size_t count, size_t size,
                int (*compare)(const void*, const void*))

The bsearch function uses binary search to search for key in the array base, where each element takes up size bytes. There are count elements in the array.

The compare function is called with key as the first argument, and a pointer into the array as the second. The function should return an integer: less than zero if key is less than the array element, greater than zero if the key is larger, or zero if the key is the same as the array element.

The bsearch function returns a pointer to the array element that matches key or NULL if no element matches.

See Also

qsort function, find in <algorithm>

calloc function

Allocate memory

void* calloc(size_t count, size_t size)

The calloc function allocates count elements, each of size bytes, and initializes the allocated memory to all zeros. It returns a pointer to the start of the newly allocated memory or NULL if there is insufficient memory to fulfill the request.

C++ programs should use the new operator instead of calling calloc.

See Also

free function, malloc function, realloc function

div function

Quotient and remainder

div_t div(int numerator, int denominator)
ldiv_t div(long numerator, long denominator)

The div function divides numerator by denominator and returns the quotient and the remainder in a structure.

See Also

div_t type, ldiv function, ldiv_t type

div_t type

Quotient and remainder type

struct div_t { int quot, rem; }

The div_t type is used only by the div function to return the quotient and remainder of an integer division. The structure can declare the quot and rem members in any order.

See Also

div function, ldiv_t type

exit function

Terminate the program normally

void exit(int code)

The exit function terminates the program normally. All functions registered with atexit are called in the opposite order of registration. The code is returned to the operating system. An exit code of 0 or EXIT_SUCCESS means successful completion. If code is EXIT_FAILURE, an indication of program failure is returned to the operating system. Other values of code are implementation-defined.

See Also

atexit function

EXIT_FAILURE macro

Exit status for unsuccessful termination

const int EXIT_FAILURE

Pass EXIT_FAILURE to exit to terminate the program normally, but informing the operating system that the program was unsuccessful.

See Also

exit function

EXIT_SUCCESS macro

Exit status for successful termination

const int EXIT_SUCCESS

Pass EXIT_SUCCESS to exit to terminate the program normally, and informing the operating system that the program was successful.

See Also

exit function

free function

Release allocated memory

void free(void* ptr)

The free function releases the memory pointed to by ptr. The pointer must have been returned by a call to malloc or calloc. After freeing the pointer, do not refer to the memory again.

See Also

calloc function, malloc function, realloc function

getenv function

Get environment variable

char* getenv(const char* name)

The getenv function gets the value of an environment variable. The environment is a system-defined list of name/value pairs. The getenv function searches the environment for name, and returns the associated value or NULL if the name is not found.

See Also

function

labs function

Absolute value

long labs(long x)

The labs function returns the absolute value of x.

See Also

abs function, abs function in <cmath>

ldiv function

Quotient and remainder

ldiv_t ldiv(long numerator, long denominator)

The ldiv function divides numerator by denominator and returns the quotient and remainder.

See Also

div function, ldiv_t type

ldiv_t type

Quotient and remainder type

struct ldiv_t { long quot, rem; }

The ldiv_t type is used only as the return type for the ldiv function and the overloaded div function. It stores the quotient and remainder of a long integer division.

See Also

div_t type, ldiv function

malloc function

Allocate memory

void* malloc(size_t size)

The malloc function allocates size bytes. It returns a pointer to the start of the newly allocated memory or NULL if there is insufficient memory to fulfill the request.

C++ programs should use the new operator instead of calling malloc.

See Also

calloc function, free function, realloc function

MB_CUR_MAX function

Maximum size of a multibyte character

int MB_CUR_MAX

The MB_CUR_MAX macro is the maximum number of bytes required to represent a multibyte character in the extended character set, using the current locale.

See Also

mblen function, mbtowc function, wctomb function, <clocale>

mblen function

Number of bytes in a multibyte character

int mblen(const char* s, size_t n)

The mblen function returns the length of the multibyte character pointed to by s. The character array s must have at least n characters, and they must form a valid multibyte character, or else -1 is returned. Zero is returned if s is an empty string.

If s is NULL, the return value is false (zero) if multibyte characters do not have state-dependent encodings; the return value is true (non-zero) if characters have state-dependent encodings.

See Also

MB_CUR_MAX macro, mbtowc function, mbrlen in <cwchar>

mbstowcs function

Convert multibyte string to wide string

size_t mbstowcs(whcar_t* dst, const char* src, size_t n)

The mbstowcs converts a multibyte string to a wide character string. The src parameter points to the null-terminated multibyte string. Up to n wide characters are stored in dst. If fewer than n characters are stored, a null wide character is appended to the wide character array.

The return value is the number of wide characters stored in dst. If any multibyte character in src is not valid, the return value is static_cast<size_t>(-1).

See Also

mbtowc function, wcstombc function, mbcrtowcs in <cwchar>

mbtowc function

Convert multibyte character to wide character

int mbtowc(wchar_t* pwc, const char* src, size_t n)

The mbtowc function counts the number of bytes in src that make up the first multibyte character. It examines only the first n bytes, and if those bytes do not form a valid multibyte character, the function returns -1. If the character is valid, and dst is not NULL, the corresponding wide character is stored in *dst. The byte count is returned.

If src is NULL, the return value is false (zero) if multibyte characters do not have state-dependent encodings; the return value is true (non-zero) if characters have state-dependent encodings.

See Also

mblen function, mbstowcs function, wctomb function, mbrtowc in <cwchar>

NULL macro

NULL pointer

#define NULL 0

The NULL macro expands to the integer 0, which represents a null pointer.

See Also

NULL in <cstddef>

qsort function

Sort an array

extern "C"
  void qsort(void* base, size_t count, size_t size,
             int (*compare)(const void*, const void*))
extern "C++"
  void qsort(void* base, size_t count, size_t size,
             int (*compare)(const void*, const void*))

The qsort function sorts into ascending order an array of count elements, each of size size bytes, where base is the pointer to the first element. The sort is not stable, that is, the relative order of identical elements is not necessarily preserved.

The compare function takes two pointers into the array and compares the elements. It returns an integer: negative if the first element is less than the second, positive if the first is greater than the second, or zero if the two elements are equal.

The name qsort derives from the original implementation, which used the quick sort algorithm. The current standard does not specify which sort algorithm is used, nor does it specify any performance characteristics of the sort algorithm.

See Also

bsearch function, sort in <algorithm>

rand function

Pseudo-random number generator

int rand()

The rand function returns a pseudo-random integer in the range 0 to RAND_MAX, inclusive.

See Also

srand function

RAND_MAX macro

Maximum value returned by rand

const int RAND_MAX

RAND_MAX is the maximum value that rand can return.

See Also

rand function

realloc function

Reallocate memory

void* realloc(void* ptr, size_t size)

The realloc function changes the size of the allocated memory that ptr points to. The new size is size bytes. The return value is a pointer to the newly resized memory block, which might be at a different address than the original block.

The contents of the original memory are preserved, up to the smaller of the new and old sizes. If the new size is larger than the old size, the extra memory above the old size is uninitialized.

If ptr is NULL, realloc behaves just like malloc(size). If size is zero, realloc frees ptr.

If there is insufficient memory to fulfill the request, the original memory is untouched, and NULL is returned.

See Also

calloc function, free function, malloc function

size_t type

Size type

typedef ... size_t

The size_t type is the type of the result of the sizeof operator. It is an unsigned integral type. The exact type is implementation-defined.

See Also

size_t in <cstddef>

srand function

Set seed for pseudo-random number generator

void srand(unsigned int seed)

The srand function saves seed as the seed for a new sequence of pseudo-random numbers, to be returned by successive calls to rand. The default seed is 1.

See Also

rand function

strtod function

Convert a string to double

double strtod(const char* s, char** end)

The strtod function converts a character string to a floating point number. The string s is divided into three parts: optional white space, the text of the floating point value, and a trailing part, which starts with the first character that cannot be part of a floating point number. The first part is skipped, and the second part is converted to a floating point value. If the second part is empty, zero is returned. If end is not NULL, *end is assigned a pointer to the start of the third part. If the third part is empty, *end points to the terminating null character.

If the result would overflow, plus or minus HUGE_VAL is returned, and errno is set to ERANGE. If the result causes underflow, zero is returned, and errno is set to ERANGE.

See Also

atoi function, stdtol function, strtoul function, wcstod in <cwchar>

strtol function

Convert a string to long integer

long int strtol(const char* s, char** end, int base)

The strtol function converts a character string to a long integer. The string s is divided into three parts: optional white space, the text of the integer value, and a trailing part, which starts with the first character that cannot be part of an integer. The first part is skipped, and the second part is converted to a long integer. If the second part is empty, zero is returned. If end is not NULL, *end is assigned a pointer to the start of the third part. If the third part is empty, *end points to the terminating null character.

If base is zero, the base is determined from the prefix of the integer text: a leading 0x or 0X means hexadecimal, a leading 0 means octal, and anything else is decimal. Otherwise, base must be between 2 and 36, where the letters a through z (in any case) represent digits with values 10 to 35. Only letters that are appropriate to the base are permitted, that is, the corresponding digit value must be less than the base.

If the resulting value is too large or too small to fit in a long int, the value LONG_MAX or LONG_MIN is returned, and errno is set to ERANGE.

See Also

atol function, strtod function, strtoul function, wcstol in <cwchar>

strtoul function

Convert a string to unsigned long

unsigned long strtoul(const char* s, char** end, int base)

The strtoul function converts a character string to an unsigned long integer. The string s is divided into three parts: optional white space, the text of the integer value, and a trailing part, which starts with the first character that cannot be part of an integer. The first part is skipped, and the second part is converted to a long integer. If the second part is empty, zero is returned. If end is not NULL, *end is assigned a pointer to the start of the third part. If the third part is empty, *end` points to the terminating null character.

If base is zero, the base is determined from the prefix of the integer text: a leading 0x or 0X means hexadecimal, a leading 0 means octal, and anything else is decimal. Otherwise, base must be between 2 and 36, where the letters a through z (in any case) represent digits with values 10 to 35. Only letters that are appropriate to the base are permitted, that is, the corresponding digit value must be less than the base.

If the resulting value is too large to fit in an unsigned long int, the value ULONG_MAX is returned, and errno is set to ERANGE.

See Also

atol function, strtod function, strtol function, wcstoul in <cwchar>

system function

Run a program

int system(const char* command)

The system function passes command to the host operating system to run as an external command. The use and interpretation of the command string is implementation-defined.

The return value is implementation-defined.

If command is NULL, the return value is true (non-zero) if a command processor is available; it is false (zero) if no command processor is available.

wctomb function

Convert a wide character to a multibyte character

int wctomb(char* s, wchar_t wc)

The wctomb function converts a wide character to a multibyte character. It first determines the number of bytes needed to represent wc as a multibyte character. If s is not NULL, the sequence of multibyte characters is stored there. At most MB_CUR_MAX bytes are stored, and the return value is the actual number of bytes written to s. If wc does not have a valid multibyte encoding, -1 is returned.

If s is NULL, the return value is true (non-zero) if multibyte characters have state-dependent encodings, or false (zero) if they do not.

See Also

mbtowc function, wcstombs function, wcrtomb in <cwchar>

wcstombs function

Convert a wide string to a multibyte string

size_t wcstombs(char* dst, const wchar_t* src, size_t n)

The wcstombs function converts a wide string src to a string dst of multibyte characters. At most n bytes of dst are written to. If the conversion of src requires fewer than n bytes, a trailing null byte is appended to dst.

If any wide characters cannot be represented as a multibyte character, static_cast<size_t>(-1) is returned. Otherwise, the return value is the number of bytes written to dst (not counting a trailing null byte).

See Also

mbstowcs function, wctomb function, wcsrtombs in <cwchar>