Input and Output

We have dealt with this topic in detail in Chapter 13, which contains sections on I/O streams, sequential and random file access, formatted I/O, and error handling. A tabular list of the I/O functions will therefore suffice here. Table 17-1 lists general file access functions declared in the header stdio.h.

There are two complete sets of functions for input and output of characters and strings: the byte-character and the wide-character I/O functions (see “Byte-Oriented and Wide-Oriented Streams” for more information). The wide-character functions operate on characters with the type wchar_t, and are declared in the header wchar.h. Table 17-2 lists both sets.

For each function in the printf and scanf families, there is a secure alternative function whose name ends in the suffix _s.

Mathematical Functions

The standard library provides many mathematical functions. Most of them operate on real or complex floating-point numbers. However, there are also several functions with integer types, such as the functions to generate random numbers.

The functions to convert numeral strings into arithmetic types are listed in “String Processing”. The remaining math functions are described in the following subsections.

FP_ZERO  FP_NORMAL  FP_SUBNORMAL  FP_INFINITE  FP_NAN

if ( fpclassify( x ) == FP_INFINITE )  /* ... */ ;
if ( isinf( x ) )                      /* ... */ ;

#pragma STDC FP_CONTRACT  on_off_switch
#pragma STDC CX_LIMITED_RANGE  on_off_switch

#pragma STDC FENV_ACCESS ON

FE_DIVBYZERO  FE_INEXACT  FE_INVALID  FE_OVERFLOW  FE_UNDERFLOW

FE_DOWNWARD  FE_TONEAREST  FE_TOWARDZERO  FE_UPWARD

Character Classification and Conversion

The standard library provides a number of functions to classify characters and to perform conversions on them. The header ctype.h declares such functions for byte characters, with character codes from 0 to 255. The header wctype.h declares similar functions for wide characters, which have the type wchar_t. These functions are commonly implemented as macros.

The results of these functions, except for isdigit() and isxdigit(), depends on the current locale setting for the locale category LC_CTYPE. You can query or change the locale using the setlocale() function.

iswalpha(wc )
iswctype( wc, wctype("alpha") )

towupper( wc );
towctrans( wc, wctrans("toupper") );

String Processing

A string is a continuous sequence of characters terminated by '\0', the string terminator character. The length of a string is considered to be the number of characters before the string terminator. Strings can be either byte strings, which consist of byte characters, or wide strings, which consist of wide characters. Byte strings are stored in arrays of char, and wide strings are stored in arrays whose elements have one of the wide-character types: wchar_t, char16_t, or char32_t.

C does not have a basic type for strings, and hence has no operators to concatenate, compare, or assign values to strings. Instead, the standard library provides numerous functions, listed in Table 17-16, to perform these and other operations with strings. The header string.h declares the functions for conventional strings of char. The names of these functions begin with str. The header wchar.h declares the corresponding functions for strings of wide characters, with names beginning with wcs.

Like any other array, a string that occurs in an expression is implicitly converted into a pointer to its first element. Thus, when you pass a string as an argument to a function, the function receives only a pointer to the first character, and can determine the length of the string only by the position of the string terminator character.

Multibyte Characters

In multibyte character sets, each character is coded as a sequence of one or more bytes (see “Wide Characters and Multibyte Characters”). While each wide character is represented by one object of the type wchar_t, char16_t, or char32_t, the number of bytes necessary to represent a given character in a multibyte encoding is variable. However, the number of bytes that represent a multibyte character, including any necessary state-shift sequences, is never more than the value of the macro MB_CUR_MAX, which is defined in the header stdlib.h.

Standard library functions allow you to obtain the character code of the wide character corresponding to any multibyte character, and the multibyte representation of any wide character. Some multibyte encoding schemes are stateful; the interpretation of a given multibyte sequence may depend on its position with respect to control characters, called shift sequences, that are used in the multibyte stream or string. In such cases, the conversion of a multibyte character to a wide character, or the conversion of a multibyte string into a wide string, depends on the current shift state at the point where the first multibyte character is read. For the same reason, converting a wide character to a multibyte character, or a wide string to a multibyte string, may entail inserting appropriate shift sequences in the output. An example of a multibyte-encoding that uses shift sequences is BOCU-1, a MIME-compatible, compressed Unicode encoding that takes up less space than UTF-8. UTF-8 itself, on the other hand, does not use shift sequences.

Conversions between wide and multibyte characters or strings may be necessary when you read or write characters from a wide-oriented stream (see “Byte-Oriented and Wide-Oriented Streams”).

Table 17-17 lists all of the standard library functions for handling multibyte characters.

The letter r in the names of functions declared in wchar.h stands for “restartable.” The restartable functions—in contrast to those declared in stdlib.h, without the r in their names—take an additional argument, which is a pointer to an object that stores the shift state of the multibyte character or string argument.

Converting Between Numbers and Strings

The standard library provides a variety of functions to interpret a numeral string and return a numeric value. These functions are listed in Table 17-18. The numeral conversion functions differ both in their target types and in the string types they interpret. The functions for char strings are declared in the header stdlib.h, and those for wide strings in wchar.h. Furthermore, C99 introduced four functions to convert a string into a number of the widest available signed or unsigned integer type, intmax_t or uintmax_t. These four functions are declared in inttypes.h.

The functions strtol(), strtoll(), and strtod() can be more practical to use than the corresponding functions atol(), atoll(), and atof(), as they return the position of the next character in the source string after the character sequence that was interpreted as a numeral.

In addition to the functions listed in Table 17-18, you can also perform string-to-number conversions using one of the sscanf() functions with an appropriate format string. Similarly, you can use the sprintf() functions to perform the reverse conversion, generating a numeral string from a numeric argument. These functions are declared in the header stdio.h. Once again, the corresponding functions for wide strings are declared in the header wchar.h. Both sets of functions are listed in Table 17-19.

For each of these functions, there is a secure alternative function whose name ends in the suffix _s.

Searching and Sorting

Table 17-20 lists the standard library’s four general searching and sorting functions, which are declared in the header stdlib.h. The functions to search the contents of a string are listed in “String Processing”.

These functions feature an abstract interface that allows you to use them for arrays of any element type. One parameter of the qsort() and qsort_s() functions is a pointer to a call-back function that qsort() and qsort_s() can use to compare pairs of array elements. Usually you will need to define this function yourself. The bsearch() and bsearch_s() functions, which find the array element designated by a “key” argument, use the same technique, calling a user-defined function to compare array elements with the specified key.

The bsearch() and bsearch_s() functions use the binary search algorithm, and therefore require that the array be sorted beforehand. Although the names of the qsort() and qsort_s() functions suggest that they implement the quick-sort algorithm, the standard does not specify which sorting algorithm they use.

Memory Block Handling

The functions listed in Table 17-21 initialize, copy, search, and compare blocks of memory. The functions declared in the header string.h access a memory block byte by byte, and those declared in wchar.h read and write units of the type wchar_t. Accordingly, the size parameter of each function indicates the size of a memory block as a number of bytes, or as a number of wide characters.

Dynamic Memory Management

Many programs, including those that work with dynamic data structures, for example, depend on the ability to allocate and release blocks of memory at runtime. C programs can do that by means of the four dynamic memory management functions declared in the header stdlib.h, which are listed in Table 17-22. The use of these functions is described in detail in Chapter 12.

Date and Time

The header time.h declares the standard library functions to obtain the current date and time, to obtain the process’s running time, to perform certain conversions on date and time information, and to format it for output. A key function is time(), which yields the current calendar time in the form of an arithmetic value of the type time_t. This is usually encoded as the number of seconds elapsed since a specified moment in the past, called the epoch. The Unix epoch is 00:00:00 o’clock on January 1, 1970, UTC (Coordinated Universal Time, formerly called Greenwich Mean Time or GMT).

There are also standard functions to convert a calendar time value with the type time_t into a string or a structure of type struct tm. The structure type has members of type int for the second, minute, hour, day, month, year, day of the week, day of the year, and a daylight saving time flag (see the description of the gmtime() function in Chapter 18). Table 17-23 lists all the date and time functions.

The extremely flexible strftime() function uses a format string (in a similar way as the printf() functions) and the LC_TIME locale category to generate a date and time string. You can query or change the locale using the setlocale() function. The function wcsftime() is the wide-string version of strftime(), and is declared in the header wchar.h rather than time.h.

The diagram in Figure 17-1 offers an organized summary of the available date and time functions.

Figure 17-1. Date and time functions

Process Control

A process is a program that is being executed. Each process has a number of attributes, such as its open files. The exact attributes of processes are dependent on the given system. The standard library’s process control features can be divided into two kinds: those for communication with the operating system, and those concerned with signals.

Internationalization

The standard library supports the development of C programs that are able to adapt to local cultural conventions. For example, programs may use locale-specific character sets or formats for currency information.

All programs start in the default locale, named "C", which contains no country or language-specific information. During runtime, programs can change their locale or query information about the current locale. The information that makes up a locale is divided into categories, which you can query and set individually.

The functions that operate on the current locale are declared, along with the related types and macros, in the header locale.h. They are listed in Table 17-26.

Many functions make use of locale-specific information. The standard library function descriptions in Chapter 18 point out whenever a given function accesses locale settings. Such functions include the following:

• Character classification and case mapping functions

• Locale-sensitive string comparison (strcoll() and wcscoll())

• Date and time formatting (strftime() and wcsftime())

• Conversion of numeral strings

• Conversions between multibyte and wide characters

Nonlocal Jumps

The goto statement in C can be used to jump only within a function. For greater freedom, the header setjmp.h declares a pair of functions that permit jumps to any point in a program. Table 17-27 lists these functions.

When you call the function-like macro setjmp(), it stores a value in its argument with the type jmp_buf that acts as a bookmark to that point in the program. The jmp_buf object holds all the necessary parts of the current execution state (including registers and stack). When you pass a jmp_buf object to longjmp(), longjmp() restores the saved state, and the program continues at the point following the earlier setjmp() call. The longjmp() call must not occur after the function that called setjmp() returns. Furthermore, if any variables with automatic storage duration in the function that called setjmp() were modified after the setjmp() call (and were not declared as volatile), then their values after the longjmp() call are indeterminate.

The return value of setjmp() indicates whether the program has reached that point after the original setjmp() call, or through a longjmp() call: setjmp() itself returns 0. If setjmp() appears to return any other value, then that point in the program was reached by calling longjmp(). If the second argument in the longjmp() call—that is, the requested return value—is 0, it is replaced with 1 as the apparent return value after the corresponding setjmp() call.

Multithreading (C11)

The features provided by the C11 standard for programming multithreaded applications in C are described in detail in Chapter 14. The tables in this section simply present a summary of the C multithreading library. Note that support for multithreading and atomic operations is optional. An implementation that conforms to C11 must simply define the macros __STDC_NO_THREADS__ and __STDC_NO_ATOMICS__ if it does not provide the corresponding features.

Debugging

Using the macro assert() is a simple way to find logical mistakes during program development. This macro is defined in the header assert.h. It simply tests its scalar argument for a nonzero value. If the argument’s value is zero, assert() prints an error message that lists the argument expression, function, filename, and line number, and then calls abort() to stop the program. In the following example, the assert() calls perform some plausibility checks on the argument to be passed to free():

#include <stdlib.h>
#include <assert.h>
 
char *buffers[64] = { NULL };   // An array of pointers
int i;
 
/* ... allocate some memory buffers; work with them ... */
 
  assert( i >= 0 && i < 64 );     // Index out of range?
  assert( buffers[i] != NULL );   // Was the pointer used at all?
  free( buffers[i] );

Rather than trying to free a nonexistent buffer, this code aborts the program (here compiled as assert.c) with the following diagnostic output:

assert: assert.c:14: main: Assertion 'buffers[i] != ((void *)0)' failed.
Aborted

When you have finished testing, you can disable all assert() calls by defining the macro NDEBUG before the #include directive for assert.h. The macro does not need to have a replacement value. For example:

#define NDEBUG
#include <assert.h>
/* ... */

C11 has introduced the capability to test the assertion of an integer constant expression during compiling. This is done using _Static_assert declarations. For details and an example, see “_Static_assert Declarations”.

Error Messages

Various standard library functions set the global variable errno to a value indicating the type of error encountered during execution (see “errno.h”). The functions in Table 17-37 generate an appropriate error message for the current value of errno.

The function perror() prints the string passed to it as an argument, followed by a colon and the error message that corresponds to the value of errno. This error message is the one that strerror() would return if called with the same value of errno as its argument. Here is an example:

if ( remove("test1") != 0)  // If we can't delete the file ...
  perror( "Couldn't delete 'test1'" );

This perror() call produces the same output as the following statement:

fprintf( stderr, "Couldn't delete 'test1': %s\n", strerror( errno ) );

In this example, if the file test1 does not exist, a program compiled with GCC prints the following message:

    Couldn't delete 'test1': No such file or directory

The error message whose address is provided by the function strerror() may be replaced on a subsequent strerror() call. To avoid data races, multithreaded programs should therefore use the alternative function strerror_s(), which copies the error message to an array provided by the caller.