Programming languages — C (INTERNATIONAL STANDARD ISO/IEC 9899:TC3) - page 15

7.19.7.11 The

ungetc

function

Synopsis

1

#include <stdio.h>

int ungetc(int c, FILE *stream);

Description

2

The

ungetc

function pushes the character specified by

c

(converted to an

unsigned

char

) back onto the input stream pointed to by

stream

. Pushed-back characters will be

returned by subsequent reads on that stream in the reverse order of their pushing. A
successful intervening call (with the stream pointed to by

stream

) to a file positioning

function (

fseek

,

fsetpos

, or

rewind

) discards any pushed-back characters for the

stream. The external storage corresponding to the stream is unchanged.

3

One character of pushback is guaranteed. If the

ungetc

function is called too many

times on the same stream without an intervening read or file positioning operation on that
stream, the operation may fail.

4

If the value of

c

equals that of the macro

EOF

, the operation fails and the input stream is

unchanged.

5

A successful call to the

ungetc

function clears the end-of-file indicator for the stream.

The value of the file position indicator for the stream after reading or discarding all
pushed-back characters shall be the same as it was before the characters were pushed
back. For a text stream, the value of its file position indicator after a successful call to the

ungetc

function is unspecified until all pushed-back characters are read or discarded.

For a binary stream, its file position indicator is decremented by each successful call to
the

ungetc

function; if its value was zero before a call, it is indeterminate after the

call.

256)

Returns

6

The

ungetc

function returns the character pushed back after conversion, or

EOF

if the

operation fails.

Forward references: file positioning functions (7.19.9).

256) See ‘‘future library directions’’ (7.26.9).

300 Library

§7.19.7.11

7.19.8 Direct input/output functions

7.19.8.1 The

fread

function

Synopsis

1

#include <stdio.h>

size_t fread(void * restrict ptr,

size_t size, size_t nmemb,

FILE * restrict stream);

Description

2

The

fread

function reads, into the array pointed to by

ptr

, up to

nmemb

elements

whose size is specified by

size

, from the stream pointed to by

stream

. For each

object,

size

calls are made to the

fgetc

function and the results stored, in the order

read, in an array of

unsigned char

exactly overlaying the object. The file position

indicator for the stream (if defined) is advanced by the number of characters successfully
read. If an error occurs, the resulting value of the file position indicator for the stream is
indeterminate. If a partial element is read, its value is indeterminate.

Returns

3

The

fread

function returns the number of elements successfully read, which may be

less than

nmemb

if a read error or end-of-file is encountered. If

size

or

nmemb

is zero,

fread

returns zero and the contents of the array and the state of the stream remain

unchanged.

7.19.8.2 The

fwrite

function

Synopsis

1

#include <stdio.h>

size_t fwrite(const void * restrict ptr,

size_t size, size_t nmemb,

FILE * restrict stream);

Description

2

The

fwrite

function writes, from the array pointed to by

ptr

, up to

nmemb

elements

whose size is specified by

size

, to the stream pointed to by

stream

. For each object,

size

calls are made to the

fputc

function, taking the values (in order) from an array of

unsigned char

exactly overlaying the object. The file position indicator for the

stream (if defined) is advanced by the number of characters successfully written. If an
error occurs, the resulting value of the file position indicator for the stream is
indeterminate.

§7.19.8.2 Library

301

Returns

3

The

fwrite

function returns the number of elements successfully written, which will be

less than

nmemb

only if a write error is encountered. If

size

or

nmemb

is zero,

fwrite

returns zero and the state of the stream remains unchanged.

7.19.9 File positioning functions

7.19.9.1 The

fgetpos

function

Synopsis

1

#include <stdio.h>

int fgetpos(FILE * restrict stream,

fpos_t * restrict pos);

Description

2

The

fgetpos

function stores the current values of the parse state (if any) and file

position indicator for the stream pointed to by

stream

in the object pointed to by

pos

.

The values stored contain unspecified information usable by the

fsetpos

function for

repositioning the stream to its position at the time of the call to the

fgetpos

function.

Returns

3

If successful, the

fgetpos

function returns zero; on failure, the

fgetpos

function

returns nonzero and stores an implementation-defined positive value in

errno

.

Forward references: the

fsetpos

function (7.19.9.3).

7.19.9.2 The

fseek

function

Synopsis

1

#include <stdio.h>

int fseek(FILE *stream, long int offset, int whence);

Description

2

The

fseek

function sets the file position indicator for the stream pointed to by

stream

.

If a read or write error occurs, the error indicator for the stream is set and

fseek

fails.

3

For a binary stream, the new position, measured in characters from the beginning of the
file, is obtained by adding

offset

to the position specified by

whence

. The specified

position is the beginning of the file if

whence

is

SEEK_SET

, the current value of the file

position indicator if

SEEK_CUR

, or end-of-file if

SEEK_END

. A binary stream need not

meaningfully support

fseek

calls with a

whence

value of

SEEK_END

.

4

For a text stream, either

offset

shall be zero, or

offset

shall be a value returned by

an earlier successful call to the

ftell

function on a stream associated with the same file

and

whence

shall be

SEEK_SET

.

302 Library

§7.19.9.2

5

After determining the new position, a successful call to the

fseek

function undoes any

effects of the

ungetc

function on the stream, clears the end-of-file indicator for the

stream, and then establishes the new position. After a successful

fseek

call, the next

operation on an update stream may be either input or output.

Returns

6

The

fseek

function returns nonzero only for a request that cannot be satisfied.

Forward references: the

ftell

function (7.19.9.4).

7.19.9.3 The

fsetpos

function

Synopsis

1

#include <stdio.h>

int fsetpos(FILE *stream, const fpos_t *pos);

Description

2

The

fsetpos

function sets the

mbstate_t

object (if any) and file position indicator

for the stream pointed to by

stream

according to the value of the object pointed to by

pos

, which shall be a value obtained from an earlier successful call to the

fgetpos

function on a stream associated with the same file. If a read or write error occurs, the
error indicator for the stream is set and

fsetpos

fails.

3

A successful call to the

fsetpos

function undoes any effects of the

ungetc

function

on the stream, clears the end-of-file indicator for the stream, and then establishes the new
parse state and position. After a successful

fsetpos

call, the next operation on an

update stream may be either input or output.

Returns

4

If successful, the

fsetpos

function returns zero; on failure, the

fsetpos

function

returns nonzero and stores an implementation-defined positive value in

errno

.

7.19.9.4 The

ftell

function

Synopsis

1

#include <stdio.h>

long int ftell(FILE *stream);

Description

2

The

ftell

function obtains the current value of the file position indicator for the stream

pointed to by

stream

. For a binary stream, the value is the number of characters from

the beginning of the file. For a text stream, its file position indicator contains unspecified
information, usable by the

fseek

function for returning the file position indicator for the

stream to its position at the time of the

ftell

call; the difference between two such

return values is not necessarily a meaningful measure of the number of characters written

§7.19.9.4 Library

303

or read.

Returns

3

If successful, the

ftell

function returns the current value of the file position indicator

for the stream.

On failure, the

ftell

function returns −1L and stores an

implementation-defined positive value in

errno

.

7.19.9.5 The

rewind

function

Synopsis

1

#include <stdio.h>

void rewind(FILE *stream);

Description

2

The

rewind

function sets the file position indicator for the stream pointed to by

stream

to the beginning of the file. It is equivalent to

(void)fseek(stream, 0L, SEEK_SET)

except that the error indicator for the stream is also cleared.

Returns

3

The

rewind

function returns no value.

7.19.10 Error-handling functions

7.19.10.1 The

clearerr

function

Synopsis

1

#include <stdio.h>

void clearerr(FILE *stream);

Description

2

The

clearerr

function clears the end-of-file and error indicators for the stream pointed

to by

stream

.

Returns

3

The

clearerr

function returns no value.

304 Library

§7.19.10.1

7.19.10.2 The

feof

function

Synopsis

1

#include <stdio.h>

int feof(FILE *stream);

Description

2

The

feof

function tests the end-of-file indicator for the stream pointed to by

stream

.

Returns

3

The

feof

function returns nonzero if and only if the end-of-file indicator is set for

stream

.

7.19.10.3 The

ferror

function

Synopsis

1

#include <stdio.h>

int ferror(FILE *stream);

Description

2

The

ferror

function tests the error indicator for the stream pointed to by

stream

.

Returns

3

The

ferror

function returns nonzero if and only if the error indicator is set for

stream

.

7.19.10.4 The

perror

function

Synopsis

1

#include <stdio.h>

void perror(const char *s);

Description

2

The

perror

function maps the error number in the integer expression

errno

to an

error message. It writes a sequence of characters to the standard error stream thus: first
(if

s

is not a null pointer and the character pointed to by

s

is not the null character), the

string pointed to by

s

followed by a colon (

:

) and a space; then an appropriate error

message string followed by a new-line character. The contents of the error message
strings are the same as those returned by the

strerror

function with argument

errno

.

Returns

3

The

perror

function returns no value.

Forward references: the

strerror

function (7.21.6.2).

§7.19.10.4 Library

305

7.20 General utilities

<stdlib.h>

1

The header

<stdlib.h>

declares five types and several functions of general utility, and

defines several macros.

257)

2

The types declared are

size_t

and

wchar_t

(both described in 7.17),

div_t

which is a structure type that is the type of the value returned by the

div

function,

ldiv_t

which is a structure type that is the type of the value returned by the

ldiv

function, and

lldiv_t

which is a structure type that is the type of the value returned by the

lldiv

function.

3

The macros defined are

NULL

(described in 7.17);

EXIT_FAILURE

and

EXIT_SUCCESS

which expand to integer constant expressions that can be used as the argument to the

exit

function to return unsuccessful or successful termination status, respectively, to the

host environment;

RAND_MAX

which expands to an integer constant expression that is the maximum value returned by
the

rand

function; and

MB_CUR_MAX

which expands to a positive integer expression with type

size_t

that is the maximum

number of bytes in a multibyte character for the extended character set specified by the
current locale (category

LC_CTYPE

), which is never greater than

MB_LEN_MAX

.

257) See ‘‘future library directions’’ (7.26.10).

306 Library

§7.20

7.20.1 Numeric conversion functions

1

The functions

atof

,

atoi

,

atol

, and

atoll

need not affect the value of the integer

expression

errno

on an error. If the value of the result cannot be represented, the

behavior is undefined.

7.20.1.1 The

atof

function

Synopsis

1

#include <stdlib.h>

double atof(const char *nptr);

Description

2

The

atof

function converts the initial portion of the string pointed to by

nptr

to

double

representation. Except for the behavior on error, it is equivalent to

strtod(nptr, (char **)NULL)

Returns

3

The

atof

function returns the converted value.

Forward references: the

strtod

,

strtof

, and

strtold

functions (7.20.1.3).

7.20.1.2 The

atoi

,

atol

, and

atoll

functions

Synopsis

1

#include <stdlib.h>

int atoi(const char *nptr);

long int atol(const char *nptr);

long long int atoll(const char *nptr);

Description

2

The

atoi

,

atol

, and

atoll

functions convert the initial portion of the string pointed

to by

nptr

to

int

,

long int

, and

long long int

representation, respectively.

Except for the behavior on error, they are equivalent to

atoi: (int)strtol(nptr, (char **)NULL, 10)

atol: strtol(nptr, (char **)NULL, 10)

atoll: strtoll(nptr, (char **)NULL, 10)

Returns

3

The

atoi

,

atol

, and

atoll

functions return the converted value.

Forward references: the

strtol

,

strtoll

,

strtoul

, and

strtoull

functions

(7.20.1.4).

§7.20.1.2 Library

307

7.20.1.3 The

strtod

,

strtof

, and

strtold

functions

Synopsis

1

#include <stdlib.h>

double strtod(const char * restrict nptr,

char ** restrict endptr);

float strtof(const char * restrict nptr,

char ** restrict endptr);

long double strtold(const char * restrict nptr,

char ** restrict endptr);

Description

2

The

strtod

,

strtof

, and

strtold

functions convert the initial portion of the string

pointed to by

nptr

to

double

,

float

, and

long double

representation,

respectively. First, they decompose 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 or representing an infinity or NaN;
and a final string of one or more unrecognized characters, including the terminating null
character of the input string. Then, they attempt to convert the subject sequence to a
floating-point number, and return the result.

3

The expected form of the subject sequence is an optional plus or minus sign, then one of
the following:

— a   nonempty sequence of decimal digits optionally containing a decimal-point

character, then an optional exponent part as defined in 6.4.4.2;

— a

0x

or

0X

, then a nonempty sequence of hexadecimal digits optionally containing a

decimal-point character, then an optional binary exponent part as defined in 6.4.4.2;

—

INF

or

INFINITY

, ignoring case

—

NAN

or

NAN(

n-char-sequence

opt

)

, ignoring case in the

NAN

part, where:

n-char-sequence:

digit
nondigit
n-char-sequence digit
n-char-sequence nondigit

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 not of the expected form.

4

If the subject sequence has the expected form for a floating-point number, 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 of 6.4.4.2, except that the

308 Library

§7.20.1.3

decimal-point character is used in place of a period, and that if neither an exponent part
nor a decimal-point character appears in a decimal floating point number, or if a binary
exponent part does not appear in a hexadecimal floating point number, an exponent part
of the appropriate type with value zero is assumed to follow the last digit in the string. If
the subject sequence begins with a minus sign, the sequence is interpreted as negated.

258)

A character sequence

INF

or

INFINITY

is interpreted as an infinity, if representable in

the return type, else like a floating constant that is too large for the range of the return
type. A character sequence

NAN

or

NAN(

n-char-sequence

opt

)

, is interpreted as a quiet

NaN, if supported in the return type, else like a subject sequence part that does not have
the expected form; the meaning of the n-char sequences is implementation-defined.

259)

A

pointer to the final string is stored in the object pointed to by

endptr

, provided that

endptr

is not a null pointer.

5

If the subject sequence has the hexadecimal form and

FLT_RADIX

is a power of 2, the

value resulting from the conversion is correctly rounded.

6

In other than the

"C"

locale, additional locale-specific subject sequence forms may be

accepted.

7

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.

Recommended practice

8

If the subject sequence has the hexadecimal form,

FLT_RADIX

is not a power of 2, and

the result is not exactly representable, the result should be one of the two numbers in the
appropriate internal format that are adjacent to the hexadecimal floating source value,
with the extra stipulation that the error should have a correct sign for the current rounding
direction.

9

If the subject sequence has the decimal form and at most

DECIMAL_DIG

(defined in

<float.h>

) significant digits, the result should be correctly rounded. If the subject

sequence D has the decimal form and more than

DECIMAL_DIG

significant digits,

consider the two bounding, adjacent decimal strings L and U , both having

DECIMAL_DIG

significant digits, such that the values of L, D, and U satisfy L

≤

D

≤

U .

The result should be one of the (equal or adjacent) values that would be obtained by
correctly rounding L and U according to the current rounding direction, with the extra

258) It is unspecified whether a minus-signed sequence is converted to a negative number directly or by

negating the value resulting from converting the corresponding unsigned sequence (see F.5); the two
methods may yield different results if rounding is toward positive or neg ative infinity. In either case,
the functions honor the sign of zero if floating-point arithmetic supports signed zeros.

259) An implementation may use the n-char sequence to determine extra information to be represented in

the NaN’s significand.

§7.20.1.3 Library

309

stipulation that the error with respect to D should have a correct sign for the current
rounding direction.

260)

Returns

10

The functions return 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

,

HUGE_VALF

, or

HUGE_VALL

is returned (according to the return

type and sign of the value), and the value of the macro

ERANGE

is stored in

errno

. If

the result underflows (7.12.1), the functions return a value whose magnitude is no greater
than the smallest normalized positive number in the return type; whether

errno

acquires

the value

ERANGE

is implementation-defined.

7.20.1.4 The

strtol

,

strtoll

,

strtoul

, and

strtoull

functions

Synopsis

1

#include <stdlib.h>

long int strtol(

const char * restrict nptr,

char ** restrict endptr,

int base);

long long int strtoll(

const char * restrict nptr,

char ** restrict endptr,

int base);

unsigned long int strtoul(

const char * restrict nptr,

char ** restrict endptr,

int base);

unsigned long long int strtoull(

const char * restrict nptr,

char ** restrict endptr,

int base);

Description

2

The

strtol

,

strtoll

,

strtoul

, and

strtoull

functions convert the initial

portion of the string pointed to by

nptr

to

long int

,

long long int

,

unsigned

long int

, and

unsigned long long int

representation, respectively. First,

they decompose the input string into three parts: an initial, possibly empty, sequence of
white-space characters (as specified by the

isspace

function), a subject sequence

260)

DECIMAL_DIG

, defined in

<float.h>

, should be sufficiently large that L and U will usually round

to the same internal floating value, but if not will round to adjacent values.

310 Library

§7.20.1.4

resembling an integer represented in some radix determined by the value of

base

, and a

final string of one or more unrecognized characters, including the terminating null
character of the input string. Then, they attempt to convert the subject sequence to an
integer, and return the result.

3

If the value of

base

is zero, the expected form of the subject sequence is that of an

integer constant as described in 6.4.4.1, optionally preceded by a plus or minus sign, but
not including an integer suffix. If the value of

base

is between 2 and 36 (inclusive), 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 through 35; only letters and digits 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 and digits, following the sign if present.

4

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.

5

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 of 6.4.4.1. 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 (in the return type). A pointer to the final string is stored in the
object pointed to by

endptr

, provided that

endptr

is not a null pointer.

6

In other than the

"C"

locale, additional locale-specific subject sequence forms may be

accepted.

7

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

8

The

strtol

,

strtoll

,

strtoul

, and

strtoull

functions return 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_MIN

,

LONG_MAX

,

LLONG_MIN

,

LLONG_MAX

,

ULONG_MAX

, or

ULLONG_MAX

is returned (according to the return type

and sign of the value, if any), and the value of the macro

ERANGE

is stored in

errno

.

§7.20.1.4 Library

311

7.20.2 Pseudo-random sequence generation functions

7.20.2.1 The

rand

function

Synopsis

1

#include <stdlib.h>

int rand(void);

Description

2

The

rand

function computes a sequence of pseudo-random integers in the range 0 to

RAND_MAX

.

3

The implementation shall behave as if no library function calls the

rand

function.

Returns

4

The

rand

function returns a pseudo-random integer.

Environmental limits

5

The value of the

RAND_MAX

macro shall be at least 32767.

7.20.2.2 The

srand

function

Synopsis

1

#include <stdlib.h>

void srand(unsigned int seed);

Description

2

The

srand

function uses 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 shall 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.

3

The implementation shall behave as if no library function calls the

srand

function.

Returns

4

The

srand

function returns no value.

5

EXAMPLE The following functions define a portable implementation of

rand

and

srand

.

static unsigned long int next = 1;

int rand(void)

// RAND_MAX

assumed to be 32767

{

next = next * 1103515245 + 12345;

return (unsigned int)(next/65536) % 32768;

}

312 Library

§7.20.2.2

void srand(unsigned int seed)

{

next = seed;

}

7.20.3 Memory management functions

1

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 suitably aligned so that it may be assigned to a pointer to any type of object
and then used to access such an object or an array of such objects in the space allocated
(until the space is explicitly deallocated). The lifetime of an allocated object extends
from the allocation until the deallocation. Each such allocation shall yield a pointer to an
object disjoint from any other object. The pointer returned points to the start (lowest byte
address) of the allocated space. If the space cannot be allocated, a null pointer is
returned. If the size of the space requested is zero, the behavior is implementation-
defined: either a null pointer is returned, or the behavior is as if the size were some
nonzero value, except that the returned pointer shall not be used to access an object.

7.20.3.1 The

calloc

function

Synopsis

1

#include <stdlib.h>

void *calloc(size_t nmemb, size_t size);

Description

2

The

calloc

function allocates space for an array of

nmemb

objects, each of whose size

is

size

. The space is initialized to all bits zero.

261)

Returns

3

The

calloc

function returns either a null pointer or a pointer to the allocated space.

7.20.3.2 The

free

function

Synopsis

1

#include <stdlib.h>

void free(void *ptr);

Description

2

The

free

function causes 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 a pointer earlier returned by the

calloc

,

malloc

, or

261) Note that this need not be the same as the representation of floating-point zero or a null pointer

constant.

§7.20.3.2 Library

313

realloc

function, or if the space has been deallocated by a call to

free

or

realloc

,

the behavior is undefined.

Returns

3

The

free

function returns no value.

7.20.3.3 The

malloc

function

Synopsis

1

#include <stdlib.h>

void *malloc(size_t size);

Description

2

The

malloc

function allocates space for an object whose size is specified by

size

and

whose value is indeterminate.

Returns

3

The

malloc

function returns either a null pointer or a pointer to the allocated space.

7.20.3.4 The

realloc

function

Synopsis

1

#include <stdlib.h>

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

Description

2

The

realloc

function deallocates the old object pointed to by

ptr

and returns a

pointer to a new object that has the size specified by

size

. The contents of the new

object shall be the same as that of the old object prior to deallocation, up to the lesser of
the new and old sizes. Any bytes in the new object beyond the size of the old object have
indeterminate values.

3

If

ptr

is a null pointer, the

realloc

function behaves like the

malloc

function for the

specified size. Otherwise, if

ptr

does not match a 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 behavior is undefined. If memory for the new

object cannot be allocated, the old object is not deallocated and its value is unchanged.

Returns

4

The

realloc

function returns a pointer to the new object (which may have the same

value as a pointer to the old object), or a null pointer if the new object could not be
allocated.

314 Library

§7.20.3.4

7.20.4 Communication with the environment

7.20.4.1 The

abort

function

Synopsis

1

#include <stdlib.h>

void abort(void);

Description

2

The

abort

function causes abnormal program termination to occur, unless the signal

SIGABRT

is being caught and the signal handler does not return. Whether open streams

with unwritten buffered data are flushed, open streams are 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

3

The

abort

function does not return to its caller.

7.20.4.2 The

atexit

function

Synopsis

1

#include <stdlib.h>

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

Description

2

The

atexit

function registers the function pointed to by

func

, to be called without

arguments at normal program termination.

Environmental limits

3

The implementation shall support the registration of at least 32 functions.

Returns

4

The

atexit

function returns zero if the registration succeeds, nonzero if it fails.

Forward references: the

exit

function (7.20.4.3).

7.20.4.3 The

exit

function

Synopsis

1

#include <stdlib.h>

void exit(int status);

Description

2

The

exit

function causes normal program termination to occur. If more than one call to

the

exit

function is executed by a program, the behavior is undefined.

§7.20.4.3 Library

315

3

First, all functions registered by the

atexit

function are called, in the reverse order of

their registration,

262)

except that a function is called after any previously registered

functions that had already been called at the time it was registered. If, during the call to
any such function, a call to the

longjmp

function is made that would terminate the call

to the registered function, the behavior is undefined.

4

Next, all open streams with unwritten buffered data are flushed, all open streams are
closed, and all files created by the

tmpfile

function are removed.

5

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

6

The

exit

function cannot return to its caller.

7.20.4.4 The

_Exit

function

Synopsis

1

#include <stdlib.h>

void _Exit(int status);

Description

2

The

_Exit

function causes normal program termination to occur and control to be

returned to the host environment. No functions registered by the

atexit

function or

signal handlers registered by the

signal

function are called. The status returned to the

host environment is determined in the same way as for the

exit

function (7.20.4.3).

Whether open streams with unwritten buffered data are flushed, open streams are closed,
or temporary files are removed is implementation-defined.

Returns

3

The

_Exit

function cannot return to its caller.

262) Each function is called as many times as it was registered, and in the correct order with respect to

other registered functions.

316 Library

§7.20.4.4

7.20.4.5 The

getenv

function

Synopsis

1

#include <stdlib.h>

char *getenv(const char *name);

Description

2

The

getenv

function searches 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.

3

The implementation shall behave as if no library function calls the

getenv

function.

Returns

4

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.

7.20.4.6 The

system

function

Synopsis

1

#include <stdlib.h>

int system(const char *string);

Description

2

If

string

is a null pointer, the

system

function determines whether the host

environment has a command processor. If

string

is not a null pointer, the

system

function passes the string pointed to by

string

to that command processor to be

executed in a manner which the implementation shall document; this might then cause the
program calling

system

to behave in a non-conforming manner or to terminate.

Returns

3

If the argument is a null pointer, the

system

function returns nonzero only if a

command processor is available. If the argument is not a null pointer, and the

system

function does return, it returns an implementation-defined value.

§7.20.4.6 Library

317

7.20.5 Searching and sorting utilities

1

These utilities make use of a comparison function to search or sort arrays of unspecified
type. Where an argument declared as

size_t nmemb

specifies the length of the array

for a function,

nmemb

can have the value zero on a call to that function; the comparison

function is not called, a search finds no matching element, and sorting performs no
rearrangement. Pointer arguments on such a call shall still have valid values, as described
in 7.1.4.

2

The implementation shall ensure that the second argument of the comparison function
(when called from

bsearch

), or both arguments (when called from

qsort

), are

pointers to elements of the array.

263)

The first argument when called from

bsearch

shall equal

key

.

3

The comparison function shall not alter the contents of the array. The implementation
may reorder elements of the array between calls to the comparison function, but shall not
alter the contents of any individual element.

4

When the same objects (consisting of

size

bytes, irrespective of their current positions

in the array) are passed more than once to the comparison function, the results shall be
consistent with one another. That is, for

qsort

they shall define a total ordering on the

array, and for

bsearch

the same object shall always compare the same way with the

key.

5

A sequence point occurs immediately before and immediately after each call to the
comparison function, and also between any call to the comparison function and any
movement of the objects passed as arguments to that call.

7.20.5.1 The

bsearch

function

Synopsis

1

#include <stdlib.h>

void *bsearch(const void *key, const void *base,

size_t nmemb, size_t size,

int (*compar)(const void *, const void *));

Description

2

The

bsearch

function searches 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

263) That is, if the value passed is

p

, then the following expressions are always nonzero:

((char *)p - (char *)base) % size == 0

(char *)p >= (char *)base

(char *)p < (char *)base + nmemb * size

318 Library

§7.20.5.1

size of each element of the array is specified by

size

.

3

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.

264)

Returns

4

The

bsearch

function returns a pointer to a matching element of the array, or a null

pointer if no match is found. If two elements compare as equal, which element is
matched is unspecified.

7.20.5.2 The

qsort

function

Synopsis

1

#include <stdlib.h>

void qsort(void *base, size_t nmemb, size_t size,

int (*compar)(const void *, const void *));

Description

2

The

qsort

function sorts an array of

nmemb

objects, the initial element of which is

pointed to by

base

. The size of each object is specified by

size

.

3

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.

4

If two elements compare as equal, their order in the resulting sorted array is unspecified.

Returns

5

The

qsort

function returns no value.

264) In practice, the entire array is sorted according to the comparison function.

§7.20.5.2 Library

319

7.20.6 Integer arithmetic functions

7.20.6.1 The

abs

,

labs

and

llabs

functions

Synopsis

1

#include <stdlib.h>

int abs(int j);

long int labs(long int j);

long long int llabs(long long int j);

Description

2

The

abs

,

labs

, and

llabs

functions compute the absolute value of an integer

j

. If the

result cannot be represented, the behavior is undefined.

265)

Returns

3

The

abs

,

labs

, and

llabs

, functions return the absolute value.

7.20.6.2 The

div

,

ldiv

, and

lldiv

functions

Synopsis

1

#include <stdlib.h>

div_t div(int numer, int denom);

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

lldiv_t lldiv(long long int numer, long long int denom);

Description

2

The

div

,

ldiv

, and

lldiv

, functions compute

numer / denom

and

numer %

denom

in a single operation.

Returns

3

The

div

,

ldiv

, and

lldiv

functions return a structure of type

div_t

,

ldiv_t

, and

lldiv_t

, respectively, comprising both the quotient and the remainder. The structures

shall contain (in either order) the members

quot

(the quotient) and

rem

(the remainder),

each of which has the same type as the arguments

numer

and

denom

. If either part of

the result cannot be represented, the behavior is undefined.

265) The absolute value of the most negative number cannot be represented in two’s complement.

320 Library

§7.20.6.2

7.20.7 Multibyte/wide character conversion functions

1

The behavior of the multibyte character functions is affected by the

LC_CTYPE

category

of the current locale. For a state-dependent encoding, each function is placed into its
initial conversion 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 conversion

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.

266)

Changing the

LC_CTYPE

category causes the conversion state of these

functions to be indeterminate.

7.20.7.1 The

mblen

function

Synopsis

1

#include <stdlib.h>

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

Description

2

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 conversion state of the

mbtowc

function is not affected, it is equivalent to

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

3

The implementation shall behave as if no library function calls the

mblen

function.

Returns

4

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).

Forward references: the

mbtowc

function (7.20.7.2).

266) If the locale employs special bytes to change the shift state, these bytes do not produce separate wide

character codes, but are grouped with an adjacent multibyte character.

§7.20.7.1 Library

321

7.20.7.2 The

mbtowc

function

Synopsis

1

#include <stdlib.h>

int mbtowc(wchar_t * restrict pwc,

const char * restrict s,

size_t n);

Description

2

If

s

is not a null pointer, the

mbtowc

function inspects at most

n

bytes beginning with

the byte pointed to by

s

to determine the number of bytes needed to complete the next

multibyte character (including any shift sequences). If the function determines that the
next multibyte character is complete and valid, it determines the value of the
corresponding wide character and then, if

pwc

is not a null pointer, stores that value in

the object pointed to by

pwc

. If the corresponding wide character is the null wide

character, the function is left in the initial conversion state.

3

The implementation shall behave as if no library function calls the

mbtowc

function.

Returns

4

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).

5

In no case will the value returned be greater than

n

or the value of the

MB_CUR_MAX

macro.

7.20.7.3 The

wctomb

function

Synopsis

1

#include <stdlib.h>

int wctomb(char *s, wchar_t wc);

Description

2

The

wctomb

function determines the number of bytes needed to represent the multibyte

character corresponding to the wide character given by

wc

(including any shift

sequences), and stores the multibyte character representation in the array whose first
element is pointed to by

s

(if

s

is not a null pointer). At most

MB_CUR_MAX

characters

are stored. If

wc

is a null wide character, a null byte is stored, preceded by any shift

sequence needed to restore the initial shift state, and the function is left in the initial
conversion state.

322 Library

§7.20.7.3

3

The implementation shall behave as if no library function calls the

wctomb

function.

Returns

4

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

wc

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

wc

.

5

In no case will the value returned be greater than the value of the

MB_CUR_MAX

macro.

7.20.8 Multibyte/wide string conversion functions

1

The behavior of the multibyte string functions is affected by the

LC_CTYPE

category of

the current locale.

7.20.8.1 The

mbstowcs

function

Synopsis

1

#include <stdlib.h>

size_t mbstowcs(wchar_t * restrict pwcs,

const char * restrict s,

size_t n);

Description

2

The

mbstowcs

function converts a sequence of multibyte characters that begins in the

initial shift state from the array pointed to by

s

into a sequence of corresponding wide

characters and stores not more than

n

wide characters into the array pointed to by

pwcs

.

No multibyte characters that follow a null character (which is converted into a null wide
character) will be examined or converted. Each multibyte character is converted as if by
a call to the

mbtowc

function, except that the conversion state of the

mbtowc

function is

not affected.

3

No more than

n

elements will be modified in the array pointed to by

pwcs

. If copying

takes place between objects that overlap, the behavior is undefined.

Returns

4

If an invalid multibyte character is encountered, the

mbstowcs

function returns

(size_t)(-1)

. Otherwise, the

mbstowcs

function returns the number of array

elements modified, not including a terminating null wide character, if any.

267)

267) The array will not be null-terminated if the value returned is

n

.

§7.20.8.1 Library

323

7.20.8.2 The

wcstombs

function

Synopsis

1

#include <stdlib.h>

size_t wcstombs(char * restrict s,

const wchar_t * restrict pwcs,

size_t n);

Description

2

The

wcstombs

function converts a sequence of wide characters from the array pointed

to by

pwcs

into a sequence of corresponding 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 wide character is converted as if by a call to the

wctomb

function, except that the conversion state of the

wctomb

function is not affected.

3

No more than

n

bytes will be modified in the array pointed to by

s

. If copying takes place

between objects that overlap, the behavior is undefined.

Returns

4

If a wide character 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.

267)

324 Library

§7.20.8.2

7.21 String handling

<string.h>

7.21.1 String function conventions

1

The header

<string.h>

declares one type and several functions, and defines one

macro useful for manipulating arrays of character type and other objects treated as arrays
of character type.

268)

The type is

size_t

and the macro is

NULL

(both described in

7.17). Various methods are used for determining the lengths of the arrays, but in all cases
a

char *

or

void *

argument points to the initial (lowest addressed) character of the

array. If an array is accessed beyond the end of an object, the behavior is undefined.

2

Where an argument declared as

size_t n

specifies the length of the array for a

function,

n

can have the value zero on a call to that function. Unless explicitly stated

otherwise in the description of a particular function in this subclause, pointer arguments
on such a call shall still have valid values, as described in 7.1.4. On such a call, a
function that locates a character finds no occurrence, a function that compares two
character sequences returns zero, and a function that copies characters copies zero
characters.

3

For all functions in this subclause, each character shall be interpreted as if it had the type

unsigned char

(and therefore every possible object representation is valid and has a

different value).

7.21.2 Copying functions

7.21.2.1 The

memcpy

function

Synopsis

1

#include <string.h>

void *memcpy(void * restrict s1,

const void * restrict s2,

size_t n);

Description

2

The

memcpy

function copies

n

characters from the object pointed to by

s2

into the

object pointed to by

s1

. If copying takes place between objects that overlap, the behavior

is undefined.

Returns

3

The

memcpy

function returns the value of

s1

.

268) See ‘‘future library directions’’ (7.26.11).

§7.21.2.1 Library

325

7.21.2.2 The

memmove

function

Synopsis

1

#include <string.h>

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

Description

2

The

memmove

function copies

n

characters from the object pointed to by

s2

into 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 objects pointed to by

s1

and

s2

, and then the

n

characters from the

temporary array are copied into the object pointed to by

s1

.

Returns

3

The

memmove

function returns the value of

s1

.

7.21.2.3 The

strcpy

function

Synopsis

1

#include <string.h>

char *strcpy(char * restrict s1,

const char * restrict s2);

Description

2

The

strcpy

function copies the string pointed to by

s2

(including the terminating null

character) into the array pointed to by

s1

. If copying takes place between objects that

overlap, the behavior is undefined.

Returns

3

The

strcpy

function returns the value of

s1

.

7.21.2.4 The

strncpy

function

Synopsis

1

#include <string.h>

char *strncpy(char * restrict s1,

const char * restrict s2,

size_t n);

Description

2

The

strncpy

function copies not more than

n

characters (characters that follow a null

character are not copied) from the array pointed to by

s2

to the array pointed to by

326 Library

§7.21.2.4

s1

.

269)

If copying takes place between objects that overlap, the behavior is undefined.

3

If the array pointed to by

s2

is a string that is shorter than

n

characters, null characters

are appended to the copy in the array pointed to by

s1

, until

n

characters in all have been

written.

Returns

4

The

strncpy

function returns the value of

s1

.

7.21.3 Concatenation functions

7.21.3.1 The

strcat

function

Synopsis

1

#include <string.h>

char *strcat(char * restrict s1,

const char * restrict s2);

Description

2

The

strcat

function appends a copy of the string pointed to by

s2

(including the

terminating null character) to the end of the string pointed to by

s1

. The initial character

of

s2

overwrites the null character at the end of

s1

. If copying takes place between

objects that overlap, the behavior is undefined.

Returns

3

The

strcat

function returns the value of

s1

.

7.21.3.2 The

strncat

function

Synopsis

1

#include <string.h>

char *strncat(char * restrict s1,

const char * restrict s2,

size_t n);

Description

2

The

strncat

function appends not more than

n

characters (a null character and

characters that follow it are not appended) from the array pointed to by

s2

to the end of

the string pointed to by

s1

. The initial character of

s2

overwrites the null character at the

end of

s1

. A terminating null character is always appended to the result.

270)

If copying

269) Thus, if there is no null character in the first

n

characters of the array pointed to by

s2

, the result will

not be null-terminated.

270) Thus, the maximum number of characters that can end up in the array pointed to by

s1

is

strlen(s1)+n+1

.

§7.21.3.2 Library

327

takes place between objects that overlap, the behavior is undefined.

Returns

3

The

strncat

function returns the value of

s1

.

Forward references: the

strlen

function (7.21.6.3).

7.21.4 Comparison functions

1

The sign of a nonzero value returned by the comparison functions

memcmp

,

strcmp

,

and

strncmp

is determined by the sign of the difference between the values of the first

pair of characters (both interpreted as

unsigned char

) that differ in the objects being

compared.

7.21.4.1 The

memcmp

function

Synopsis

1

#include <string.h>

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

Description

2

The

memcmp

function compares the first

n

characters of the object pointed to by

s1

to

the first

n

characters of the object pointed to by

s2

.

271)

Returns

3

The

memcmp

function returns an integer greater than, equal to, or less than zero,

accordingly as the object pointed to by

s1

is greater than, equal to, or less than the object

pointed to by

s2

.

7.21.4.2 The

strcmp

function

Synopsis

1

#include <string.h>

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

Description

2

The

strcmp

function compares the string pointed to by

s1

to the string pointed to by

s2

.

Returns

3

The

strcmp

function returns an integer greater than, equal to, or less than zero,

accordingly as the string pointed to by

s1

is greater than, equal to, or less than the string

271) The contents of ‘‘holes’’ used as padding for purposes of alignment within structure objects are

indeterminate. Strings shorter than their allocated space and unions may also cause problems in
comparison.

328 Library

§7.21.4.2

pointed to by

s2

.

7.21.4.3 The

strcoll

function

Synopsis

1

#include <string.h>

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

Description

2

The

strcoll

function 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.

Returns

3

The

strcoll

function returns an integer greater than, equal to, or less than zero,

accordingly as the string pointed to by

s1

is greater than, equal to, or less than the string

pointed to by

s2

when both are interpreted as appropriate to the current locale.

7.21.4.4 The

strncmp

function

Synopsis

1

#include <string.h>

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

Description

2

The

strncmp

function compares not more than

n

characters (characters that follow a

null character are not compared) from the array pointed to by

s1

to the array pointed to

by

s2

.

Returns

3

The

strncmp

function returns an integer greater than, equal to, or less than zero,

accordingly as the possibly null-terminated array pointed to by

s1

is greater than, equal

to, or less than the possibly null-terminated array pointed to by

s2

.

7.21.4.5 The

strxfrm

function

Synopsis

1

#include <string.h>

size_t strxfrm(char * restrict s1,

const char * restrict s2,

size_t n);

Description

2

The

strxfrm

function transforms the string pointed to by

s2

and places the resulting

string into the array pointed to by

s1

. The transformation is such that if the

strcmp

function is applied to two transformed strings, it returns a value greater than, equal to, or

§7.21.4.5 Library

329

less than zero, corresponding to the result of the

strcoll

function applied to the same

two original strings. No more than

n

characters are placed into the resulting array

pointed to by

s1

, including the terminating null character. If

n

is zero,

s1

is permitted to

be a null pointer. If copying takes place between objects that overlap, the behavior is
undefined.

Returns

3

The

strxfrm

function returns the length of the transformed string (not including the

terminating null character). If the value returned is

n

or more, the contents of the array

pointed to by

s1

are indeterminate.

4

EXAMPLE The value of the following expression is the size of the array needed to hold the
transformation of the string pointed to by

s

.

1 + strxfrm(NULL, s, 0)

7.21.5 Search functions

7.21.5.1 The

memchr

function

Synopsis

1

#include <string.h>

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

Description

2

The

memchr

function locates the first occurrence of

c

(converted to an

unsigned

char

) in the initial

n

characters (each interpreted as

unsigned char

) of the object

pointed to by

s

.

Returns

3

The

memchr

function returns a pointer to the located character, or a null pointer if the

character does not occur in the object.

7.21.5.2 The

strchr

function

Synopsis

1

#include <string.h>

char *strchr(const char *s, int c);

Description

2

The

strchr

function locates the first occurrence of

c

(converted to a

char

) in the

string pointed to by

s

. The terminating null character is considered to be part of the

string.

Returns

3

The

strchr

function returns a pointer to the located character, or a null pointer if the

character does not occur in the string.

330 Library

§7.21.5.2

7.21.5.3 The

strcspn

function

Synopsis

1

#include <string.h>

size_t strcspn(const char *s1, const char *s2);

Description

2

The

strcspn

function computes the length of the maximum initial segment of the string

pointed to by

s1

which consists entirely of characters not from the string pointed to by

s2

.

Returns

3

The

strcspn

function returns the length of the segment.

7.21.5.4 The

strpbrk

function

Synopsis

1

#include <string.h>

char *strpbrk(const char *s1, const char *s2);

Description

2

The

strpbrk

function locates the first occurrence in the string pointed to by

s1

of any

character from the string pointed to by

s2

.

Returns

3

The

strpbrk

function returns a pointer to the character, or a null pointer if no character

from

s2

occurs in

s1

.

7.21.5.5 The

strrchr

function

Synopsis

1

#include <string.h>

char *strrchr(const char *s, int c);

Description

2

The

strrchr

function locates the last occurrence of

c

(converted to a

char

) in the

string pointed to by

s

. The terminating null character is considered to be part of the

string.

Returns

3

The

strrchr

function returns a pointer to the character, or a null pointer if

c

does not

occur in the string.

§7.21.5.5 Library

331