Libraries

• 1. Introduction
• 2. Diagnostics
• 3. Character handling
• 4. Localization
• 5. Limits
• 6. Mathematical functions
• 7. Non-local jumps
• 8. Signal handling
• Variable numbers of arguments
• 10. Input and output
• 11. Formatted I/O
• 12. Character I/O
• 13. Unformatted I/O
• 14. Random access functions
• 15. General Utilities
• 16. String handling
• 17. Date and time
• 18. Summary

1. Introduction

There is no doubt that the Standard Committee's decision to define a set of library routines will prove to be a huge benefit to users of C. Previously there were no standard, accepted, definitions of library routines to provide support for the language. As a result, portability suffered seriously.

The library routines do not have to be present; they will only be present in a hosted environment-typically the case for applications programmers. Writers of embedded systems and the writers of the hosted environment libraries will not have the libraries present. They are using 'raw' C, in a freestanding environment, and this chapter will not be of much interest to them.

The descriptions (except for this introduction) are not meant to be read as a whole chapter, but as individual pieces. The material included here is meant more for information and convenient reference than as a full tutorial introduction. It would take a full book by itself to do real justice to the libraries.

1.1. Headers and standard types

A number of types and macros are used widely by the library functions. Where necessary, they are defined in the appropriate #include file for that function. The header will also declare appropriate types and prototypes for the library functions. Some important points should be noted here:

• All external identifiers and macro names declared in any of the library headers are reserved. They must not be used, or redefined, for any other purpose. In some cases they may be 'magic'-their names may be known to the compiler and cause it to use special methods to implement them.
• All identifiers that begin with an underscore are reserved.
• Headers may be included in any order, and more than once, but must be included outside of any external declaration or definition and before any use of the functions or macros defined inside them.
• Giving a 'bad value' to a function-say a null pointer, or a value outside the range of values expected by the function-results in undefined behaviour unless otherwise stated.

The Standard isn't quite as restrictive about identifiers as the list above is, but it's a brave move to make use of the loopholes. Play safe instead.

The Standard headers are:

A last general point is that many of the library routines may be implemented as macros, provided that there will be no problems to do with side-effects (as Chapter 7 describes). The Standard guarantees that, if a function is normally implemented as a macro, there will also be a true function provided to do the same job. To use the real function, either undefine the macro name with #undef, or enclose its name in parentheses, which ensures that it won't be treated as a macro:

1.2. Character set and cultural dependencies

The Committee has introduced features that attempt to cater for the use of C in environments which are not based on the character set of US ASCII and where there are cultural dependencies such as the use of comma or full stop to indicate the decimal point. Facilities have been provided (see Section 4) for setting a program's idea of its locale, which is used to control the behaviour of the library functions.

Providing full support for different native languages and customs is a difficult and poorly understood task; the facilities provided by the C library are only a first step on the road to a full solution.

In several places the 'C locale' is referred to. This is the only locale defined by the Standard and effectively provides support for the way that Old C worked. Other locale settings may provide different behaviour in implementation-defined ways.

1.3. The <stddef.h> Header

There are a small number of types and macros, found in <stddef.h>, which are widely used in other headers. They are described in the following paragraphs.

Subtracting one pointer from another gives a result whose type differs between different implementations. To allow safe use of the difference, the type is defined in <stddef.h> to be ptrdiff_t. Similarly, you can use size_t to store the result of sizeof.

For reasons which still escape us, there is an 'implementation defined null pointer constant' defined in <stddef.h> called NULL. Since the language explicitly defines the integer constant to be the value which can be assigned to, and compared with, a null pointer, this would seem to be unnecessary. However, it is very common practice among experienced C programmers to write this sort of thing:

Example 1

The expression s_tr.c must be capable of evaluation as an address constant (see Chapter  . If the member whose offset you want is a bitfield, then you're out of luck; offsetof has undefined behaviour in that case.

Note carefully the way that a size_t has to be cast to the longest possible unsigned type to ensure that not only is the argument to printf of the type that it expects (%luis the format string for unsigned long), but also no precision is lost. This is all because the type of size_t is not known to the programmer.

The last item declared in <stddef.h> is wchar_t, an integral type large enough to hold a wide character from any supported extended character sets.

1.4. The <errno.h> Header

This header defines errno along with the macros EDOM and ERANGE, which expand to nonzero integral constant expressions; their form is additionally guaranteed to be acceptable to #if directives. The latter two are used by the mathematical functions to report which kind of errors they encountered and are more fully described later.

errno is provided to tell you when library functions have detected an error. It is not necessarily, as it used to be, an external variable, but is now a modifiable lvalue that has type int. It is set to zero at program start-up, but from then on never reset unless explicitly assigned to; in particular, the library routines never reset it. If an error occurs in a library routine, errno is set to a particular value to indicate what went wrong, and the routine returns a value (often −1) to indicate that it failed. The usual use is like this:

Example 2

Note that assert returns no value.

3. Character handling

There are a variety of functions provided for testing and mapping characters. The testing functions, which are described first, allow you to test if a character is of a particular type, such as alphabetic, upper or lower case, numeric, a control character, a punctuation mark, printable or not and so on. The character testing functions return an integer, either zero if the character supplied is not of the category specified, or non-zero if it was. The functions all take an integer argument, which should either be an int, the value of which should be representable as unsigned char, or the integer constant EOF, as returned from functions such as getchar(). The behaviour is undefined if it is not.

These functions depend on the program's locale setting.

A printing character is a member of an implementation defined character set. Each printing character occupies one printing position. A control character is a member of an implementation defined character set, each of which is not a printing character. If the 7-bit ASCII character set is used, the printing characters are those that lie between space (0x20) and tilde (0x7e), the control characters are those between NUL (0x0) and US (0x1f), and the character DEL (0x7f).

The following is a summary of all the character testing functions. The header <ctype.h> must be included before any of them is used.

isalnum(int c)

True if c is alphabetic or a digit; specifically (isalpha(c)||isdigit(c)).

isalpha(int c)

True if (isupper(c)||islower(c)).

Also true for an implementation-defined set of characters which do not return true results from any of iscntrl, isdigit, ispunct or isspace. In the C locale, this extra set of characters is empty.

iscntrl(int c)

True if c is a control character.

isdigit(int c)

True if c is a decimal digit.

isgraph(int c)

True if c is any printing character except space.

islower(int c)

True if c is a lower case alphabetic letter. Also true for an implementation defined set of characters which do not return true results from any of iscntrl, isdigit, ispunct or isspace. In the C locale, this extra set of characters is empty.

isprint(int c)

True if c is a printing character (including space).

ispunct(int c)

True if c is any printing character that is neither a space nor a character which would return true from isalnum.

isspace(int c)

True if c is either a white space character (one of ' ' 'f' 'n' 'r' 't' 'v') or, in other than the C locale, characters which would not return true from isalnum

isupper(int c)

True if c is an upper case alphabetic character.

Also true for an implementation-defined set of characters which do not return true results from any of iscntrl, isdigit, ispunct or isspace. In the C locale, this extra set of characters is empty.

isxdigit(int c)

True if c is a valid hexadecimal digit.

Two additional functions map characters from one set into another. The function tolower will, if given a upper case character as its argument, return the lower case equivalent. For example,

If tolower is given any character other than an upper case letter, it will return that character.

The converse function toupper maps lower case alphabetic letters onto their upper case equivalent.

For each, the conversion is only performed if there is a corresponding character in the alternate case. In some locales, not all upper case characters have lower case equivalents, and vice versa.

6. Mathematical functions

If you are writing mathematical programs, involving floating point calculations and so on, then you will undoubtedly require access to the mathematics library. This set of functions all take double arguments, and return a double result. The functions and associated macros are defined in the include file <math.h>.

The macro HUGE_VAL is defined, which expands to a positive double expression, which is not necessarily representable as a float.

For all the functions, a domain error occurs if an input argument is outside the domain over which the function is defined. An example might be attempting to take the square root of a negative number. If this occurs, errno is set to the constant EDOM, and the function returns an implementation defined value.

If the result of the function cannot be represented as a double value then a range error occurs. If the magnitude of the result is too large, the functions return HUGE_VAL (the sign will be correct) and errno is set to ERANGE. If the result is too small, is returned and the value of errno is implementation defined.

The following list briefly describes each of the functions available:

double acos(double x);

Principal value of the arc cosine of x in the range 0-π radians.
Errors: EDOM if x is not in the range −1-1.

double asin(double x);

Principal value of the arc sine of x in the range -π/2-+π/2 radians.
Errors: EDOM if x is not in the range .

double atan(double x);

Principal value of the arc tangent of x in the range -π/2-+π/2 radians.

double atan2(double y, double x);

Principal value of the arc tangent of y/x in the range -π-+π radians, using the signs of both arguments to determine the quadrant of the return value.
Errors: EDOM may occur if both x and y are zero.

double cos(double x);

Cosine of x (x measured in radians).

double sin(double x);

Sine of x (x measured in radians).

double tan(double x);

Tangent of x (x measured in radians). When a range error occurs, the sign of the resulting HUGE_VAL is not guaranteed to be correct.

double cosh(double x);

Hyperbolic cosine of x
Errors: ERANGE occurs if the magnitude of x is too large.

double sinh(double x);

Hyperbolic sine of x
Errors: ERANGE occurs if the magnitude of x is too large.

double tanh(double x);

Hyperbolic tangent of x.

double exp(double x);

Exponential function of x. Errors: ERANGE occurs if the magnitude of x is too large.

double frexp(double value, int *exp);

Break a floating point number into a normalized fraction and an integral power of two. This integer is stored in the object pointed to by exp.

double ldexp(double x, int exp);

Multiply x by 2 to the power exp
Errors: ERANGE may occur.

double log(double x);

Natural logarithm of x
Errors: EDOM occurs if x is negative. ERANGE may occur if x is zero.

double log10(double x);

Base-ten logarithm of x
Errors: EDOM occurs if x is negative. ERANGE may occur if x is zero.

double modf(double value, double *iptr);

Break the argument value into integral and fractional parts, each of which has the same sign as the argument. It stores the integrbal part as a double in the object pointed to by iptr, and returns the fractional part.

double pow(double x, double y);

Compute x to the power y
Errors: EDOM occurs if x < 0 and y not integral, or if the result cannot be represented if x is 0, and y ≤ 0. ERANGE may also occur.

double sqrt(double x);

Compute the square root of x
Errors: EDOM occurs if x is negative.

double ceil(double x);

Smallest integer not less than x.

double fabs(double x);

Absolute value of x.

double floor(double x);

Largest integer not greater than x.

double fmod(double x, double y);

Floating point remainder of x/y
Errors: If y is zero, it is implementation defined whether fmod returns zero or a domain error occurs.

7. Non-local jumps

Provision is made for you to perform what is, in effect, a goto from one function to another. It isn't possible to do this by means of a goto and a label, since labels have only function scope. However, the macro setjmp and function longjmp provide an alternative, known as a non-local goto, or a non-local jump.

The file <setjmp.h> declares something called a jmp_buf, which is used by the cooperating macro and function to store the information necessary to make the jump. The declarations are as follows:

The setjmp macro is used to initialise the jmp_buf and returns zero on its initial call. The bizarre thing is that it returns again, later, with a non-zero value, when the corresponding longjmp call is made! The non-zero value is whatever value was supplied to the call of longjmp. This is best explained by way of an example:

Example 3

The val argument to longjmp is the value seen in the second and subsequent 'returns' from setjmp. It should normally be something other than 0; if you attempt to return 0 via longjmp, it will be changed to 1. It is therefore possible to tell whether the setjmp was called directly, or whether it was reached by calling longjmp.

If there has been no call to setjmp before calling longjmp, the effect of longjmp is undefined, almost certainly causing the program to crash. The longjmp function is never expected to return, in the normal sense, to the instructions immediately following the call. All accessible objects on 'return' from setjmp have the values that they had when longjmp was called, except for objects of automatic storage class that do not have volatile type; if they have been changed between the setjmp and longjmp calls, their values are indeterminate.

The longjmp function executes correctly in the contexts of interrupts, signals and any of their associated functions. If longjmp is invoked from a function called as a result of a signal arriving while handling another signal, the behaviour is undefined.

It's a serious error to longjmp to a function which is no longer active (i.e. it has already returned or another longjump call has transferred to a setjmp occurring earlier in a set of nested calls).

The Standard insists that, apart from appearing as the only expression in an expression statement, setjmp may only be used as the entire controlling expression in an if, switch, do, while, or for statement. A slight extension to that rule is that as long as it is the whole controlling expression (as above) the setjmp call may be the subject of the ! operator, or may be directly compared with an integral constant expression using one of the relational or equality operators. No more complex expressions may be employed. Examples are:

8. Signal handling

Two functions allow for asynchronous event handling to be provided. A signal is a condition that may be reported during program execution, and can be ignored, handled specially, or, as is the default, used to terminate the program. One function sends signals, another is used to determine how a signal will be processed. Many of the signals may be generated by the underlying hardware or operating system as well as by means of the signal-sending function raise.

The signals are defined in the include file <signal.h>.

SIGABRT

Abnormal termination, such as instigated by the abort function. (Abort.)

SIGFPE

Erroneous arithmetic operation, such as divide by 0 or overflow. (Floating point exception.)

SIGILL

An 'invalid object program' has been detected. This usually means that there is an illegal instruction in the program. (Illegal instruction.)

SIGINT

Interactive attention signal; on interactive systems this is usually generated by typing some 'break-in' key at the terminal. (Interrupt.)

SIGSEGV

Invalid storage access; most frequently caused by attempting to store some value in an object pointed to by a bad pointer. (Segment violation.)

SIGTERM

Termination request made to the program. (Terminate.)

Some implementations may have additional signals available, over and above this standard set. They will be given names that start SIG, and will have unique values, apart from the set above.

The function signal allows you to specify the action taken on receipt of a signal. Associated with each signal condition above, there is a pointer to a function provided to handle this signal. The signal function changes this pointer, and returns the original value. Thus the function is defined as

That is to say, signal is a function that returns a pointer to another function. This second function takes a single int argument and returns void. The second argument to signal is similarly a pointer to a function returning void which takes an int argument.

Two special values may be used as the func argument (the signal-handling function), SIG_DFL, the initial, default, signal handler; and SIG_IGN, which is used to ignore a signal. The implementation sets the state of all signals to one or other of these values at the start of the program.

If the call to signal succeeds, the previous value of func for the specified signal is returned. Otherwise, SIG_ERR is returned and errno is set.

When a signal event happens which is not being ignored, if the associated func is a pointer to a function, first the equivalent of signal(sig, SIG_DFL) is executed. This resets the signal handler to the default action, which is to terminate the program. If the signal was SIGILL then this resetting is implementation defined. Implementations may choose to 'block' further instances of the signal instead of doing the resetting.

Next, a call is made to the signal-handling function. If that function returns normally, then under most circumstances the program will resume at the point where the event occurred. However, if the value of sig was SIGFPE (a floating point exception), or any implementation defined computational exception, then the behaviour is undefined. The most usual thing to do in the handler for SIGFPE is to call one of the functions abort, exit, or longjmp.

The following program fragment shows the use of signal to perform a tidy exit to a program on receipt of the interrupt or 'interactive attention' signal.

Example 4

It is possible for a program to send signals to itself by means of the raise function. This is defined as follows

The signal sig is sent to the program.

Raise returns zero if successful, non-zero otherwise. The abort library function is essentially implementable as follows:

If a signal occurs for any reason other than calling abort or raise, the signal-handling function may only call signal or assign a value to a volatile static object of type sig_atomic_t. The type sig_atomic_t is declared in <signal.h>. It is the only type of object that can safely be modified as an atomic entity, even in the presence of asynchronous interrupts. This is a very onerous restriction imposed by the Standard, which, for example, invalidates the leave function in the example program above; although the function would work correctly in some environments, it does not follow the strict rules of the Standard.

Variable numbers of arguments

It is often desirable to implement a function where the number of arguments is not known, or is not constant, when the function is written. Such a function is printf, described in Section 11 [https://publications.gbdirect.co.uk/c_book/chapter9/formatted_io.html]. The following example shows the declaration of such a function.

Example 5

In order to access the arguments within the called function, the functions declared in the <stdarg.h> header file must be included. This introduces a new type, called a va_list, and three functions that operate on objects of this type, called va_start, va_arg, and va_end.

Before any attempt can be made to access a variable argument list, va_start must be called. It is defined as

The va_start macro initializes ap for subsequent use by the functions va_arg and va_end. The second argument to va_start, parmN is the identifier naming the rightmost parameter in the variable parameter list in the function definition (the one just before the , ). The identifier parmN must not be declared with register storage class or as a function or array type.

Once initialized, the arguments supplied can be accessed sequentially by means of the va arg macro. This is peculiar because the type returned is determined by an argument to the macro. Note that this is impossible to implement as a true function, only as a macro. It is defined as

Each call to this macro will extract the next argument from the argument list as a value of the specified type. The va_list argument must be the one initialized by va_start. If the next argument is not of the specified type, the behaviour is undefined. Take care here to avoid problems which could be caused by arithmetic conversions. Use of char or short as the second argument to va_arg is invariably an error: these types always promote up to one of signed int or unsigned int, and float converts to double. Note that it is implementation defined whether objects declared to have the types char, unsigned char, unsigned short and unsigned bitfields will promote to unsigned int, rather complicating the use of va_arg. This may be an area where some unexpected subtleties arise; only time will tell.

The behaviour is also undefined if va_arg is called when there were no further arguments.

The type argument must be a type name which can be converted into a pointer to such an object simply by appending a to it (this is so the macro can work). Simple types such as char are fine (because char * is a pointer to a character) but array of char won't work (char [] does not turn into 'pointer to array of char' by appending a ). Fortunately, arrays can easily be processed by remembering that an array name used as an actual argument to a function call is converted into a pointer. The correct type for an argument of type 'array of char' would be char *.

When all the arguments have been processed, the va_end function should be called. This will prevent the va_list supplied from being used any further. If va end is not used, the behaviour is undefined.

The entire argument list can be re-traversed by calling va_start again, after calling va_end. The va_end function is declared as

The following example shows the use of va_start, va_arg, and va_end to implement a function that returns the biggest of its integer arguments.

Example 6

12. Character I/O

A number of functions provide for character oriented I/O. Their declarations are:

Their descriptions are as follows.

12.1. Character input

These read an unsigned char from the input stream where specified, or otherwise stdin. In each case, the next character is obtained from the input stream. It is treated as an unsigned char and converted to an int, which is the return value. On End of File, the constant EOF is returned, and the end-of-file indicator is set for the associated stream. On error, EOF is returned, and the error indicator is set for the associated stream. Successive calls will obtain characters sequentially. The functions, if implemented as macros, may evaluate their stream argument more than once, so do not use side effects here.

There is also the supporting ungetc routine, which is used to push back a character on to a stream, causing it to become the next character to be read. This is not an output operation and can never cause the external contents of a file to be changed. A fflush, fseek, or rewind operation on the stream between the pushback and the read will cause the pushback to be forgotten. Only one character of pushback is guaranteed, and attempts to pushback EOF are ignored. In every case, pushing back a number of characters then reading or discarding them leaves the file position indicator unchanged. The file position indicator is decremented by every successful call to ungetc for a binary stream, but unspecified for a text stream, or a binary stream which is positioned at the beginning of the file.

12.2. Character output

These are identical in description to the input functions already described, except performing output. They return the character written, or EOF on error. There is no equivalent to End of File for an output file.

12.3. String output

These write strings to the output file; stream where specified, otherwise stdout. The terminating null is not written. Non-zero is returned on error, zero otherwise. Beware: puts appends a newline to the string output; fputs does not!

12.4. String input

Fgets reads a string into the array pointed to by s from the stream stream. It stops on either EOF or the first newline (which it reads), and appends a null character. At most n−1 characters are read (leaving room for the null).

Gets works similarly for the stream stdin, but discards the newline!

Both return s if successful, or a null pointer otherwise. In each case, if EOF is encountered before any characters have been read, the array is unchanged and a null pointer is returned. A read error in the middle of a string leaves the array contents undefined and a null pointer is returned.

13. Unformatted I/O

This is simple: only two functions provide this facility, one for reading and one for writing:

In each case, the appropriate read or write is performed on the data pointed to by ptr. Up to nelem elements, of size size, are transferred. Failure to transfer the full number is an error only when writing; End of File can prevent the full number on input. The number of elements actually transferred is returned. To distinguish between End of File on input, or an error, use feof or ferror.

If size or nelem is zero, fread does nothing except to return zero.

An example may help.

Example 7

14. Random access functions

The file I/O routines all work in the same way; unless the user takes explicit steps to change the file position indicator, files will be read and written sequentially. A read followed by a write followed by a read (if the file was opened in a mode to permit that) will cause the second read to start immediately following the end of the data just written. (Remember that stdio insists on the user inserting a buffer-flushing operation between each element of a read-write-read cycle.) To control this, the Random Access functions allow control over the implied read/write position in the file. The file position indicator is moved without the need for a read or a write, and indicates the byte to be the subject of the next operation on the file.

Three types of function exist which allow the file position indicator to be examined or changed. Their declarations and descriptions follow.

Ftell returns the current value (measured in characters) of the file position indicator if stream refers to a binary file. For a text file, a 'magic' number is returned, which may only be used on a subsequent call to fseek to reposition to the current file position indicator. On failure, -1L is returned and errno is set.

Rewind sets the current file position indicator to the start of the file indicated by stream. The file's error indicator is reset by a call of rewind. No value is returned.

Fseek allows the file position indicator for stream to be set to an arbitrary value (for binary files), or for text files, only to a position obtained from ftell, as follows:

• In the general case, the file position indicator is set to offset bytes (characters) from a point in the file determined by the value of ptrname. Offset may be negative. The values of ptrname may be SEEK_SET, which sets the file position indicator relative to the beginning of the file, SEEK_CUR, which sets the file position indicator relative to its current value, and SEEK_END, which sets the file position indicator relative to the end of the file. The latter is not necessarily guaranteed to work properly on binary streams.
• For text files, offset must either be zero or a value returned from a previous call to ftell for the same stream, and the value of ptrname must be SEEK_SET.
• Fseek clears the end of file indicator for the given stream and erases the memory of any ungetc. It works for both input and output.
• Zero is returned for success, non-zero for a forbidden request.

Note that for ftell and fseek it must be possible to encode the value of the file position indicator into a long. This may not work for very long files, so the Standard introduces fgetpos and fsetpos which have been specified in a way that removes the problem.

Fgetpos stores the current file position indicator for stream in the object pointed to by pos. The value stored is 'magic' and only used to return to the specified position for the same stream using fsetpos.

Fsetpos works as described above, also clearing the stream's end-of-file indicator and forgetting the effects of any ungetc operations.

For both functions, on success, zero is returned; on failure, non-zero is returned and errno is set.

14.1. Error handling

The standard I/O functions maintain two indicators with each open stream to show the end-of-file and error status of the stream. These can be interrogated and set by the following functions:

Clearerr clears the error and EOF indicators for the stream.

Feof returns non-zero if the stream's EOF indicator is set, zero otherwise.

Ferror returns non-zero if the stream's error indicator is set, zero otherwise.

Perror prints a single-line error message on the program's standard output, prefixed by the string pointed to by s, with a colon and a space appended. The error message is determined by the value of errno and is intended to give some explanation of the condition causing the error. For example, this program produces the error message shown:

Example 8

Well, we didn't say that the message had to be very meaningful!

15. General Utilities

These all involve the use of the header <stdlib.h>, which declares a number of types and macros and several functions of general use. The types and macros are as follows:

size_t

Described at the start of this chapter.

div_t

This is the type of the structure returned by div.

ldiv_t

This is the type of the structure returned by ldiv.

NULL

Again, described at the start of this chapter.

EXIT_FAILURE

EXIT_SUCCESS

These may be used as arguments to exit.

MB_CUR_MAX

The maximum number of bytes in a multibyte character from the extended character set specified by the current locale.

RAND_MAX

This is the maximum value returned by the rand function.

15.1. String conversion functions

Three functions take a string as an argument and convert it to a number of the type shown below:

For each of the functions, the number is converted and the result returned. None of them guarantees to set errno (although they may do in some implementations), and the results of a conversion which overflows or cannot be represented is undefined.

More sophisticated functions are:

All three functions work in a similar way. Leading white space is skipped, then a subject sequence, resembling an appropriate constant, is found, followed by a sequence of unrecognized characters. The trailing null at the end of a string is always unrecognized. The subject sequence can be empty. The subject sequences are determined as follows:

strtod

Optional or , followed by a digit sequence containing an optional decimal point character, followed by an optional exponent. No floating suffix will be recognized. If there is no decimal point present, it is assumed to follow the digit sequence.

strtol

Optional or , followed by a digit sequence. The digits are taken from the decimal digits or an upper or lower case letter in the range a-z of the English alphabet; the letters are given the values 10-35 respectively. The base argument determines which values are permitted, and may be zero, or otherwise 2-36. Only 'digits' with a value less than that of base are recognized. A base of 16 permits the characters 0x or 0X to follow the optional sign. A base of zero permits the input of characters in the form of a C integer constant. No integer suffix will be recognized.

strtoul

Identical to strtol but with no sign permitted.

If endptr is non-null, the address of the first unrecognized character is stored in the object that it points to. If the subject sequence is empty or has the wrong form, this is the value of nptr.

If a conversion can be performed, the functions convert the number and return its value, taking into account a leading sign where permitted. Otherwise they return zero. On overflow or error the action is as follows:

strtod

On overflow, returns HUGE_VAL according to the sign of the result; on underflow, returns zero. In either case, errno is set to ERANGE.

strtol

On overflow, LONG_MAX or LONG_MIN is returned according to the sign of the result, errno is set to ERANGE.

strtoul

On overflow, ULONG_MAX is returned, errno is set to ERANGE.

If the locale is not the 'C' locale, there may be other subject sequences recognised depending on the implementation.

15.2. Random number generation

Provision for pseudo-random number generation is made by the following functions.

Rand returns a pseudo-random number in the range to RAND_MAX, which has a value of at least .

Srand allows a given starting point in the sequence to be chosen according to the value of seed. If srand is not called before rand, the value of the seed is taken to be . The same sequence of values will always be returned from rand for a given value of seed.

The Standard describes an algorithm which may be used to implement rand and srand. In practice, most implementations will probably use this algorithm.

15.3. Memory allocation

These functions are used to allocate and free storage. The storage so obtained is only guaranteed to be large enough to store an object of the specified type and aligned appropriately so as not to cause addressing exceptions. No further assumptions can be made.

All of the memory allocation functions return a pointer to allocated storage of size size bytes. If there is no free storage, they return a null pointer. The differences between them are that calloc takes an argument nmemb which specifies the number of elements in an array, each of whose members is size bytes, and so allocates a larger piece of store (in general) than malloc. Also, the store allocated by malloc is not initialized, whereas calloc sets all bits in the storage to zero. This is not necessarily the equivalent representation of floating-point zero, or the null pointer.

Realloc is used to change the size of the thing pointed to by ptr, which may require some copying to be done and the old storage freed. The contents of the object pointed to by ptr is unchanged up to the smaller of the old and the new sizes. If ptr is null, the behaviour is identical to malloc with the appropriate size.

Free is used to free space previously obtained with one of the allocation routines. It is permissible to give free a null pointer as the argument, in which case nothing is done.

If an attempt is made to free store which was never allocated, or has already been freed, the behaviour is undefined. In many environments this causes an addressing exception which aborts the program, but this is not a reliable indicator.

15.4. Communication with the environment

A miscellany of functions is found here.

abort

Causes abnormal program termination to occur, by raising the SIGABRT signal. Abnormal termination is only prevented if the signal is being caught, and the signal handler does not return. Otherwise, output files may be flushed and temporary files may be removed according to implementation definition, and an 'unsuccessful termination' status returned to the host environment. This function cannot return.

atexit

The argument func becomes a function to be called, without arguments, when the program terminates. Up to at least 32 such functions may be registered, and are called on program termination in reverse order of their registration. Zero is returned for success, non-zero for failure.

exit

Normal program termination occurs when this is called. First, all of the functions registered using atexit are called, but beware-by now, main is considered to have returned and no objects with automatic storage duration may safely be used. Then, all the open output streams are flushed, then closed, and all temporary files created by tmpfile are removed. Finally, the program returns control to the host environment, returning an implementation-defined form of successful or unsuccessful termination status depending on whether the argument to exit was EXITSUCCESS or EXIT FAILURE respectively. For compatibility with Old C, zero can be used in place of EXITSUCCESS, but other values have implementation-defined effects. Exit cannot return.

getenv

The implementation-defined environment list is searched to find an item which corresponds to the string pointed to by name. A pointer to the item is returned-it points to an array which must not be modified by the program, but may be overwritten by a subsequent call to getenv. A null pointer is returned if no item matches.

The purpose and implementation of the environment list depends on the host environment.

system

An implementation-defined command processor is passed the string string. A null pointer will cause a return of zero if no command processor exists, non-zero otherwise. A non-null pointer causes the command to be processed. The effect of the command and the value returned are implementation defined.

15.5. Searching and sorting

Two functions exist in this category: one for searching an already sorted list, the other for sorting an unsorted list. They are completely general, handling arrays of arbitrary size with elements of arbitrary size.

To enable them to compare two elements, the user provides a comparison function, which is called with pointers to two of the elements as its arguments. It returns a value less than, equal to or greater than zero depending on whether the first pointer points to an element considered to be less than, equal to or greater than the object pointed to by the second pointer, respectively.

For both functions, nmemb is the number of elements in the array, size is the size in bytes of an array element and compar is the function to be called to compare them. Base is a pointer to the base of the array.

Qsort will sort the array into ascending order.

Bsearch assumes that the array is already sorted and returns a pointer to any element it finds that compares equal to the object pointed to by key. A null pointer is returned if no match is found.

15.6. Integer arithmetic functions

These provide ways of finding the absolute value of an integral argument and the quotient and remainder of a division, for both int and long types.

abs

labs

These return the absolute value of their argument-choose the appropriate one for your needs. The behaviour is undefined if the value cannot be represented-this can happen in two's complement systems where the most negative number has no positive equivalent.

div

ldiv

These divide the numerator by the denominator and return a structure of the indicated type. In each case the structure will contain a member called quot which contains the quotient of the division truncated towards zero, and a member called rem which will contain the remainder. The type of each member is int for div and long for ldiv. Provided that the result could be represented, quot*denominator+rem == numerator.

15.7. Functions using multibyte characters

The LC_CTYPE category of the current locale affects the behaviour of these functions. For an encoding that is state-dependent, each function is put in its initial state by a call in which its character pointer argument, s, is a null pointer. The internal state of the function is altered as necessary by subsequent calls when s is not a null pointer. If s is a null pointer, the functions return a non-zero value if encodings are state-dependent, otherwise zero. If the LC_CTYPE category is changed, the shift state of the functions will become indeterminate.

The functions are:

mblen

Returns the number of bytes that are contained in the multibyte character pointed to by s, or −1 if the first n bytes do not form a valid multibyte character. If s points to the null character, zero is returned.

mbtowc

Converts the multibyte character pointed to by s to the corresponding code of type wchar_t and stores the result in the object pointed to by pwc, unless pwc is a null pointer. Returns the number of bytes successfully converted, or −1 if the first n bytes do not form a valid multibye character. No more than n bytes pointed to by s are examined. The value returned will not be more than n or MB_CUR_MAX.

wctomb

Converts the code whose value is in wchar to a sequence of bytes representing the corresponding multibyte character, and stores the result in the array pointed to by s, if s is not a null pointer. Returns the number of bytes that are contained in the multibyte character, or −1 if the value in wchar does not correspond to a valid multibyte character. At most, MB_CUR_MAX bytes are processed.

mbstowcs

Converts the sequence of multibyte characters, beginning in the initial shift state, in the array pointed to by s, into a sequence of corresponding codes which are then stored in the array pointed to by pwcs. Not more than n values will be placed in pwcs. Returns −1 if an invalid multibyte character is encountered, otherwise returns the number of array elements modified, excluding the terminating null-code.

If the two objects overlap, the behaviour is undefined.

wcstombs

Converts the sequence of codes pointed to by pwcs to a sequence of multibyte characters, beginning in the initial shift state, which are then stored in the array pointed to by s. Conversion stops when either a null-code is encountered or n bytes have been written to s. Returns −1 if a code is encountered which does not correspond to a valid multibyte character, otherwise the number of bytes written, excluding the terminating null-code.

If the two objects overlap, the behaviour is undefined.

16. String handling

Numerous functions exist to handle strings. In C, a string is an array of characters terminated by a null. In all cases, the functions expect a pointer to the first character in the string. The header <string.h> declares these functions.

16.1. Copying

The functions for this purpose are:

memcpy

This copies n bytes from the place pointed to by s2 to the place pointed to by s1. If the objects overlap, the result is undefined. The value of s1 is returned.

memmove

Identical to memcpy, but works even for overlapping objects. It may be marginally slower, though.

strcpy

strncpy

Both of these copy the string pointed to by s2 into the string pointed to by s1, including the trailing null. Strncpy will copy at most n characters, and pad with trailing nulls if s2 is shorter than n characters. If the strings overlap, the behaviour is undefined. They return s1.

strcat

strncat

Both append the string in s2 to s1, overwriting the null at the end of s1. A final null is always written. At most n characters are copied from s2 by strncat, which means that for safety the destination string should have room for its original length (not counting the null) plus n + 1 characters. They return s1.

16.2. String and byte comparison

These comparison functions are used to compare arrays of bytes. This obviously includes the traditional C strings, which are an array of char (bytes) with a terminating null. All of these functions work by comparing a byte at a time, and stopping either when two bytes differ (in which case they return the sign of the difference between the two bytes), or the arrays are considered to be equal: no differences were found, and the length of the arrays was equal to the specified amount, or the null was found at the end of a string comparison.

For all except strxfrm, the value returned is less than, equal to or greater than zero depending on whether the first object was considered to be less than, equal to or greater than the second.

memcmp

Compares the first n characters in the objects pointed to by s1 and s2. It is very dodgy to compare structures in this way, because unions or 'holes' caused by alignment padding can contain junk.

strcmp

Compares the two strings. This is one of the most commonly used of the string-handling functions.

strncmp

As for strcmp, but compares at most n characters.

strxfrm

The string in from is converted (by some magic), and placed wherever to points. At most maxsize characters (including the trailing null) are written into the destination. The magic guarantees that two such transformed strings will give the same comparison with each other for the user's current locale when using strcmp, as when strcoll is applied to the original two strings.

In all cases, the length of the resulting string (not counting its terminating null) is returned. If the value is equal to or greater than maxsize, the contents of *to is undefined. If maxsize is zero, s1 may be a null pointer.

If the two objects overlap, the behaviour is undefined.

strcoll

This function compares the two strings according to the collating sequence specified by the current locale.

16.3. Character and string searching functions

memchr

Returns a pointer to the first occurrence in the initial n characters of *s of the (unsigned char)c. Returns null if there is no such occurrence.

strchr

Returns a pointer to the first occurrence of (char)c in *s, including the null in the search. Returns null if there is no such occurrence.

strcspn

Returns the length of the initial part of the string s1 which contains no characters from s2. The terminating null is not considered to be part of s2.

strpbrk

Returns a pointer to the first character in s1 which is any of the characters in s2, or null if there is none.

strrchr

Returns a pointer to the last occurrence in s1 of (char)c counting the null as part of s1, or null if there is none.

strspn

Returns the length of the initial part of s1 consisting entirely of characters from s1.

strstr

Returns a pointer to the first occurrence in s1 of the string s2, or null if there is none.

strtok

Breaks the string in s1 into 'tokens', each delimited by one of the characters from s2 and returns a pointer to the first token, or null if there is none. Subsequent calls with (char *)0 as the value of s1 return the next token in sequence, with the extra fun that s2 (and hence the delimiters) may differ on each subsequent call. A null pointer is returned if no tokens remain.

16.4. Miscellaneous functions

memset

Sets the n bytes pointed to by s to the value of (unsigned char)c. Returns s.

strlen

Returns the length of the string s not counting the terminating null. This is a very widely used function.

strerror

Returns a pointer to a string describing the error number errnum. This string may be changed by subsequent calls to strerror. Useful for finding out what the values in errno mean.

18. Summary

It will almost certainly be the standardization of the run-time library that has the most effect on the portability of C programs. Prospective users of C really should read through this chapter carefully and familiarize themselves with its contents. The lack of a widely implemented, portable library was historically the biggest single barrier to portability.

If you are writing programs for embedded systems, bad luck! The library is not defined for stand-alone applications, but in practice we can expect suppliers to produce a stand-alone library package too. It will probably come without the file handling, but there is no reason why, say, the string-handling functions should not work just as well in hosted and unhosted environments.