United States

Compaq C

# Compaq C
Language Reference Manual

Previous | Contents | Index

# 9.14 General Utilities (<stdlib.h>)

The `<stdlib.h>` header file declares four types and several functions of general use, and defines several macros. The functions perform string conversion, random number generation, searching and sorting, memory management, and similar tasks.

Types

`size_t`

> An unsigned integral type of the result of the `sizeof` operator.

`wchar_t`

> An integral type whose range of values can represent distinct codes for all members of the largest extended character set specified among the supported locales.

`div_t`

> A structure type that is the type of the value returned by the `div` function.

`ldiv_t`

> A structure type that is the type of the value returned by the `ldiv` function.

Macros

`NULL`

> Expands to an implementation-defined null pointer constant.

`EXIT_FAILURE` / `EXIT_SUCCESS`

> Expand to integral expressions for use as the argument to the `exit` function to return unsuccessful or successful termination status, respectively, to the host environment. These macros are useful as return values from the main function as well.

`RAND_MAX`

> Expands to an integral constant expression whose value is the maximum value returned by the `rand` function.

`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_TYPE` ), and whose value is never greater than `MB_LEN_MAX` .

String Conversion Functions

`double atof(const char *nptr);`

> Converts the string pointed to by nptr to `double` representation and returns the converted value. Except for its behavior when an error occurs, this function is equivalent to:

>     strtod(nptr, (char **)NULL)

`int atoi(const char *nptr);`

> Converts the string pointed to by nptr to `int` representation and returns the converted value. Except for its behavior when an error occurs, this function is equivalent to:

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

`long int atol(const char *nptr);`

> Converts the string pointed to by nptr to `long int` representation and returns the converted value. Except for its behavior when an error occurs, this function is equivalent to:

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

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

> Converts the string pointed to by nptr to `double` representation.
> See your Compaq C library routine documentation for a detailed description of this function.

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

> Converts the string pointed to by nptr to `long int` representation.
> See your Compaq C library routine documentation for a detailed description of this function.

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

> Converts the string pointed to by nptr to `unsigned long int` representation.
> See your Compaq C library routine documentation for a detailed description of this function.

Pseudo-Random Sequence Generation Functions

`int rand(void);`

> Returns a sequence of pseudo-random integers in the range 0 to `RAND_MAX` .

`void srand(unsigned int seed);`

> Uses the argument as a seed for a new sequence of pseudo-random integers to be returned by subsequent calls to `rand` . If `srand` is then called with the same seed value, the sequence of pseudo-random integers is repeated. If `rand` is called before any calls to `srand` are made, the sequence generated is the same as when `srand` is first called with a seed value of 1. The `srand` function returns no value.

Memory Management Functions

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

> Allocates an area in memory for an array of nmemb items, each with size size. The area is initialized to all bits 0. The `calloc` function returns either a null pointer if unable to allocate, or a pointer to the allocated area.

`void free(void *ptr);`

> Deallocates the memory area pointed to by ptr that was allocated by a previous `calloc` , `malloc` , or `realloc` . If ptr is null, no action occurs. No value is returned.

`void *malloc(size_t size);`

> Allocates a contiguous area in memory for an object of size size. The area is not initialized. This function returns a pointer to the allocated area, or it returns a null pointer if unable to allocate.

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

> Changes the size of the area pointed to by ptr to the number of bytes specified by size. If ptr is null, the behavior of `realloc` is identical to `malloc` . The contents of the area are unchanged up to the lesser of the old and new sizes. This function returns either a null pointer if unable to resize, or a pointer to the possibly moved reallocated area.

Communication with the Environment

`void abort(void);`

> Causes abnormal program termination to occur, unless the `SIGABRT` signal is being caught and the signal handler does not return. The `abort` function cannot return to its caller.

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

> Registers the function pointed to by func to be called without arguments at normal program termination. Up to 32 functions can be registered. The `atexit` function returns 0 if the registration succeeds; otherwise, it returns nonzero.

`void exit(int status);`

> Causes normal program termination to occur. If a program executes more than one call to `exit` , the behavior is undefined. Upon execution, the following occurs:
> 1. All functions registered by `atexit` are called in the reverse order of their registration.
> 2. All open output streams are flushed, all open streams are closed, and all files created by `tmpfile` are removed.
> 3. Control is returned to the host environment. The value of status corresponds to an `errno` value:
>    - If the value status is 0 or `EXIT_SUCCESS` , a successful termination status is returned.
>    - If the value status is `EXIT_FAILURE` , an unsuccessful termination status is returned.
>    - Otherwise, an unsuccessful termination status is returned.

`char *getenv(const char *name);`

> Searches an environment list provided by the host environment.
> See your Compaq C library routine documentation for a detailed description of this function.

`int *system(const char *string);`

> Passes the string pointed to by string to the host environment for execution by a command processor. A null pointer can be specified to inquire whether a command processor exists. If the argument is a null pointer, the `system` function returns nonzero if a command processor is available or 0 if one is not available. If the argument is not a null pointer, the return value is the status returned by the command processor or 0 if a command processor is not available.
> See your Compaq C library routine documentation for a detailed description of this function.

Searching and Sorting Utilities

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

> Searches an array of nmemb objects for an element that matches the object pointed to by key. The first element of the array is pointed to by base; the size of each element is specified by size.
> You must first sort the array in ascending order according to the function pointed to by compar. The `bsearch` function calls the specified comparison function pointed to by compar with two arguments that point to the objects being compared (the key object and an array element). The comparison function returns:
> - An integer less than 0, if the first argument is less than the second argument
> - An integer greater than 0, if the first argument is greater than the second argument
> - An integer equal to 0, if the first argument equals the second argument
> The `bsearch` function returns a pointer to the matching element of the array, or a null pointer if no match is found.

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

> Sorts an array of nmemb objects in place. The first element of the array is pointed to by base; the size of each element is specified by size.
> The contents of the array are sorted in 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 comparison function returns:
> - An integer less than 0, if the first argument is less than the second argument
> - An integer greater than 0, if the first argument is greater than the second argument
> - An integer equal to 0, if the first argument equals the second argument
> If two compared elements are equal, their order in the sorted array is unspecified.
> The `qsort` function returns no value.

Integer Arithmetic Functions

`int abs(int j);`

> Returns the absolute value of an integer j.

`div_t div(int numer, int denom);`

> Computes the quotient and remainder of the division of numer by denom. The `div` function returns a structure of type `div_t` containing the quotient and remainder:

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

`long int labs(long int j);`

> Returns the absolute value of a long integer j.

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

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

Multibyte Character Functions

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

> If s is not a null pointer, `mblen` determines the number of bytes comprising the multibyte character pointed to by s. The `mblen` function is equivalent to the following, except that the shift state of the `mbtowc` is not affected:

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

> If s is a null pointer, the `mblen` function returns a nonzero value if multibyte character encodings have state-dependent encodings, and 0 if they do not.
> If s is not a null pointer, the `mblen` function returns one of the following values:
> - 0, if s points to the null character
> - The number of bytes that comprise the multibyte character, if the next n or fewer bytes form a valid multibyte character
> - --1, if they do not form a valid multibyte character

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

> If s is not a null pointer, `mbtowc` determines the number of bytes comprising 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 0.) If the multibyte character is valid and pwc is not a null pointer, `mbtowc` stores the code in the object pointed to by pwc. At most, n bytes of the array pointed to by s are examined.
> If s is a null pointer, the `mbtowc` function returns a nonzero value if multibyte character encodings have state-dependent encodings, and 0 if they do not.
> If s is not a null pointer, the `mbtowc` function returns one of the following values:
> - 0, if s points to the null character
> - The number of bytes that comprise the converted multibyte character, if the next n or fewer bytes form a valid multibyte character
> - --1, if they do not form a valid multibyte character

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

> Determines the number of bytes needed to represent the multibyte character corresponding to the code whose value is wchar, including any change in shift state. This function then 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 0, the `wctomb` function is left in the initial shift state.
> If s is a null pointer, the `wctomb` function returns a nonzero value if multibyte character encodings have state-dependent encodings, and 0 if they do not.
> If s is not a null pointer, the `wctomb` function returns one of the following values:
> - --1, if the value of wchar does not correspond to a valid multibyte character
> - the number of bytes that comprise the multibyte character corresponding to the value of wchar

Multibyte String Functions

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

> Converts a sequence of multibyte characters that begin 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. A null character is converted to a code value of zero. No multibyte characters that follow a null character are examined or converted. Each multibyte character is converted as if by a call to `mbtowc` , except that the shift state of `mbtowc` is not affected.
> 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.

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

> Converts 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. The conversion stops 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 `wctomb` , except that the shift state of `wctomb` is not affected.
> If a code is encountered that does not correspond to a valid multibyte character, the `wcstombs` function returns `(size_t) - 1` . Otherwise, it returns the number of bytes modified, not including a terminating null character, if any.

# 9.15 String Processing (<string.h>)

The `<string.h>` header file declares one type and several functions, and defines one macro useful for manipulating character arrays that other objects treat as character arrays.

There are two kinds of string functions declared. The first, with names beginning with `str` , manipulate character arrays; the second, with names beginning with `mem` , manipulate other objects treated as character arrays. Except for `memmove` , function behavior is undefined if copying takes place between overlapping objects.

Type

`size_t`

> An unsigned integral type of the result of the `sizeof` operator.

Macro

`NULL`

> Expands to an implementation-defined null pointer constant.

Functions

`void *memcpy(void *s1, const void *s2, size_t n);`

> Copies n characters from the object pointed to by s2 to the object pointed to by s1. The function returns s1.

`void *memmove(void *s1, const void *s2, size_t n);`

> Copies n characters from the object pointed to by s2 to the object pointed to by s1. Copying takes place as if the n characters from the object pointed to by s2 are first copied into a temporary array of n characters that does not overlap the object pointed to by s1 and s2, and then the n characters from the temporary array are copied into the object pointed to by s1. The `memmove` function returns s1.

`void *memchr(const void *s, int c, size_t n);`

> Locates the first occurrence of c (converted to an unsigned `char` ) in the first n unsigned characters of the object pointed to by s. The `memchr` function returns a pointer to the located character, or a null pointer if the character was not found.

`int memcmp(const void *s1, const void *s2, size_t n);`

> Compares the first n characters of the object pointed to by s1 to the first n characters of the object pointed to by s2. The `memcmp` function returns an integer less than, equal to, or greater than 0, depending on whether the object pointed to by s1 is less than, equal to, or greater than the object pointed to by s2.

`void *memset(void *s, int c, size_t n);`

> Copies the value of c (converted to an unsigned char) into each of the first n characters pointed to by s. The function returns s.

`char *strcpy(char *s1, const char *s2);`

> Copies the string pointed to by s2 (including the terminating null character) to the string pointed to by s1. The `strcpy` function returns s1.

`char *strncpy(char *s1, const char *s2, size_t n);`

> Copies no more than n characters from the string pointed to by s2 to the string pointed to by s1, up to but not including the null terminator of the string pointed to by s2; returns s1. If the string pointed to by s2 is less than n characters, `strncpy` pads the copy with null characters.

`char *strcat(char *s1, const char *s2);`

> Appends a copy of the the string pointed to by s2 (including the terminating null character) to the end of the string pointed to by s1. The `strcat` function returns s1. The first character of s2 overwrites the null character of s1.

`char *strncat(char *s1, const char *s2, size_t n);`

> Appends no more than n characters from the string pointed to by s2 (up to but not including a null character) to the string pointed to by s1. The `strncat` function returns s1. The first character of s2 overwrites the null character of s1. A terminating null character is appended to the result. The first character of s2 overwrites the null character of s1.

`int strcmp(const char *s1, const char *s2);`

> Compares the string pointed to by s1 to the string pointed to by s2. The `strcmp` function returns an integer less than, equal to, or greater than 0, depending on whether the string pointed to by s1 is less than, equal to, or greater than the string pointed to by s2.

`int strcoll(const char *s1, const char *s2);`

> Compares the string pointed to by s1 to the string pointed to by s2, both interpreted as appropriate to the `LC_COLLATE` category of the current locale (see Section 9.6). The `strcoll` function returns an integer less than, equal to, or greater than 0, depending on whether the string pointed to by s1 is less than, equal to, or greater than the string pointed to by s2, when both are interpreted as appropriate to the current locale.

`int strncmp(const char *s1, const char *s2, size_t n);`

> Compares no more than n characters from the string pointed to by s1 to the string pointed to by s2. The strings are compared until a null character is encountered, the strings differ, or n is reached. The `strncmp` function returns an integer less than, equal to, or greater than 0, depending on whether the string pointed to by s1 is less than, equal to, or greater than the string pointed to by s2.

Previous | Next | Contents | Index

privacy and legal statement