Chapter 18. Standard Library Functions

This chapter describes in alphabetical order the functions available in the standard ANSI C libraries. Most of the functions described here were included in the 1989 ANSI standard or in the 1995 “Normative Addendum” and are currently supported by all major compilers. The ISO/IEC 9899:1999 standard (“C99”) introduced several new functions, which are also widely supported by today’s compilers. The same cannot be said of the new, mostly optional features, such as multithreading and bounds-checking functions, introduced by the new ISO/IEC standard 9899:2011. The new functions introduced in that standard are labeled “C11” in this chapter.

Each description includes the function’s purpose and return value, the function prototype, the header file in which the function is declared, and a brief example. For the sake of brevity, the examples do not always show a main() function or the #include directives that indicate the header file with the function’s declaration. When using the functions described in this chapter, remember that you must provide a declaration of each standard function used in your program by including the appropriate header file. Also, any filename may also contain a relative or absolute directory path. For more information about errors and exceptions that can occur in standard function calls, see the sections on the standard headers math.h, fenv.h, and errno.h in Chapter 16.

In C11 implementations that support the “secure” alternative functions—that is, the bounds-checking functions with names ending in _s—the following rule applies: before the include directive that includes the header containing the declaration of the desired function, the macro __STDC_WANT_LIB_EXT1__ must be defined as equal to 1. For more information on using the secure functions, see “Functions with Bounds-Checking”.

_Exit

C99

Ends program execution without calling atexit() functions or signal handlers.

#include <stdlib.h>
_Noreturn void _Exit( int status );

The _Exit() function terminates the program normally but without calling any cleanup functions that you have installed using atexit() or at_quick_exit(), or signal handlers you have installed using signal(). _Exit() returns a status value to the operating system in the same way as the exit() function does.

Whether _Exit() flushes the program’s file buffers or removes its temporary files may vary from one implementation to another.

Example

int main (int argc, char *argv[])
{
  if (argc < 3)
  {
    fprintf(stderr, "Missing required arguments.\n");
    _Exit(-1);
  }
  /* ... */
}

Example

struct record { long id;
                int data[256];
                struct record *next;
              };
/* ... */
struct record *new = (struct record *)malloc( sizeof(struct record) );
if ( new == NULL )            // Check whether malloc failed!
{
  fprintf( stderr, "%s: out of memory!\n", __func__ );
  abort();
}
else /* ... */

Example

   char name[15]= "NN";

   set_constraint_handler_s(abort_handler_s);
   strcpy_s( name, sizeof(name), "Abraham Lincoln");

Because the array name is too small for the string being copied, this code snippet results in an error message like the following:

Runtime-constraint: Range error
abort -- terminating

Example

int amount = -1234;
char currencysym[2] = "$";
char sign[2]        = "-";
div_t dollarsandcents = { 0, 0 };

if ( amount >= 0 )
  sign[0] = '\0';

dollarsandcents = div(abs( amount ), 100 );

printf( "The balance is %s%s%d.%2d\n", sign, currencysym,
        dollarsandcents.quot, dollarsandcents.rem );

This code produces the following output:

The balance is -$12.34

Example

/*
 * Calculate the pitch of a roof given
 * the sloping width from eaves to ridge and
 * the horizontal width of the floor below it.
 */
#define PI 3.141593
#define DEG_PER_RAD (180.0/PI)

double floor_width = 30.0;
double roof_width = 34.6;

double roof_pitch = acos( floor_width / roof_width ) * DEG_PER_RAD ;
printf( "The pitch of the roof is %2.0f degrees.\n", roof_pitch );

This code produces the following output:

The pitch of the roof is 30 degrees.

Example

double x, y1, y2;

puts("acosh(x) is equal to log( x + sqrt(x*x − 1))\n");
puts("Enter some numbers greater than or equal to 1.0"
     "\n(type any letter to quit):");
while ( scanf("%lf", &x) == 1)
{
  errno = 0;
  y1 = acosh(x);
  if ( errno == EDOM)
  {
    perror("acosh");   break;
  }
  y2 = log( x + sqrt( x*x − 1));
  printf("x = %f;  acosh(x) = %f;  log(x + sqrt(x*x-1)) = %f\n",
          x, y1, y2);
}

This code produces the following output:

Enter some numbers greater than or equal to 1.0
(type any letter to quit):
1.5
x = 1.500000;  acosh(x) = 0.962424;  log(x + sqrt(x*x-1)) = 0.962424
0.5
acosh: Numerical argument out of domain

Example

time_t now;
time( &now );          /* Get the time (seconds since 1/1/70) */
printf( "Date: %.24s GMT\n", asctime( gmtime( &now ) ));

Typical output:

Date: Sun Aug 28 14:22:05 2005 GMT

Example

time_t now;
struct tm timeStruct;
char timeStr[26];

time(&now);                        // Date and time as an integer.
localtime_s(&now, &timeStruct);    // Convert to a structure.
if( asctime_s( timeStr, sizeof(timeStr), &timeStruct) == 0)
   printf("Date and time: %s", timeStr);

Typical output:

Date and time: Thu Jan 29 08:30:09 2015

Example

/*
 * Calculate the altitude of the sun (its angle upward from the horizon)
 * given the height of a vertical object and the length of the object's
 * shadow.
 */
#define PI 3.141593
#define DEG_PER_RAD (180.0/PI)

float height = 2.20F;
float length = 1.23F;
float altitude = asinf( height / sqrtf( height*height + length*length));
printf( "The sun's altitude is %2.0f\xB0.\n", altitude * DEG_PER_RAD);

This code produces the following output:

The sun's altitude is 61°.

Example

puts("   x          asinh(x)        log( x + sqrt(x*x+1))\n"
     "-------------------------------------------------------");
for ( double x = -2.0; x < 2.1; x += 0.5)
  printf("%6.2f %15f %20f\n", x, asinh(x), log( x + sqrt(x*x+1)));

This code produces the following output:

   x          asinh(x)        log( x + sqrt(x*x+1))
-------------------------------------------------------
 -2.00       -1.443635            -1.443635
 -1.50       -1.194763            -1.194763
 -1.00       -0.881374            -0.881374
 -0.50       -0.481212            -0.481212
  0.00        0.000000             0.000000
  0.50        0.481212             0.481212
  1.00        0.881374             0.881374
  1.50        1.194763             1.194763
  2.00        1.443635             1.443635

Example

int units_in_stock = 10;
int units_shipped = 9;
/* ... */
  units_shipped++;
  units_in_stock--;
/* ... */
  units_in_stock -= units_shipped;
  assert(units_in_stock >= 0);

This code produces the following output:

inventory: inventory.c:110: main: Assertion 'units_in_stock >= 0' failed.
Aborted.

Example

void nexit(void) { puts("Program terminated normally."); }
void qexit(void) { puts("Programm terminated by \"quick_exit()\"."); }

int main(void)
{
   int a = -1;
   atexit( nexit);
   at_quick_exit( qexit);

   if( a < 0)
     quick_exit(EXIT_FAILURE);

   return 0;
}

This example would generate the following console output:

Program terminated by "quick_exit()".

Example

#ifdef PI
  printf("The symbol PI was already defined.\n");
  long double pi = (long double) PI;
#else
  long double pi = 4.0L * atanl( 1.0L );   // Because tan(pi/4) = 1
#endif
  printf( "Assume pi equals %.17Lf.\n", pi);

This code produces the following output:

Assume pi equals 3.14159265358979324.

Example

/*
 * Calculate an acute angle of a right triangle, given
 * the adjacent and opposite sides.
 */
#define PI 3.141593
#define DEG_PER_RAD (180.0/PI)

double adjacent = 3.0;
double opposite = 4.0;
double angle = atan2( opposite, adjacent ) * DEG_PER_RAD;

printf( "The acute angles of a 3-4-5 right triangle are %4.2f\xB0 "
        "and %4.2f\xB0.\n", angle, 90.0 - angle );

This code produces the following output:

The acute angles of a 3-4-5 right triangle are 53.13° and 36.87°.

Example

double x[ ] = { -1.0, -0.5, 0.0, 0.5, 0.99, 1.0, 1.01 };

puts("            x              atanh(x) \n"
     "  ---------------------------------------");
for ( int i = 0; i < sizeof(x) / sizeof(x[0]); ++i )
{
  errno = 0;
  printf("%+15.2f %+20.10f\n", x[i], atanh(x[i]) );
  if ( errno)
    perror("atanh");
}

This code produces the following output:

            x              atanh(x)
  ---------------------------------------
          -1.00                 -inf
atanh: Numerical argument out of domain
          -0.50        -0.5493061443
          +0.00        +0.0000000000
          +0.50        +0.5493061443
          +0.99        +2.6466524124
          +1.00                 +inf
atanh: Numerical argument out of domain
          +1.01                 +nan
atanh: Numerical argument out of domain

Example

int main()
{
  void f1(void), f2(void);

  printf("Registering the \"at-exit\" functions f1 and f2:");

  if ( atexit(f1) || atexit(f2) )
    printf(" failed.\n");
  else
    printf(" done.\n");

  printf("Exiting now.\n");
  exit(0);           // Equivalent to return 0;
}
void f1(void)
{ printf("Running the \"at-exit\" function f1().\n"); }
void f2(void)
{ printf("Running the \"at-exit\" function f2().\n"); }

This code produces the following output:

Registering the "at-exit" functions f1 and f2: done.
Exiting now.
Running the "at-exit" function f2().
Running the "at-exit" function f1().

Example

char string[ ] = " -1.02857e+2 \260C";  // symbol for degrees Celsius
double z;

z = atof(string);
printf( "\"%s\" becomes  %.2f\n", string, z );

This code produces the following output:

" -1.02857e+2 °C" becomes -102.86

Example

char *s = " -135792468.00 Balance on Dec. 31";
printf("\"%s\" becomes %ld\n", s, atol(s));

These statements produce the output:

" -135792468.00 Balance on Dec. 31" becomes -135792468

Example

This example illustrates a possible implementation of the *= operator for objects of the type atomic_long. This corresponds to the code sequence indicated in the footnote to Section 6.5.16.2 of the C11 standard.

long mulwith( volatile atomic_long *alPtr, long val)
{
   long old = *alPtr, new;

   do { new = old * val; }
   while (!atomic_compare_exchange_weak(alPtr, &old, new));

   return new;
}

Example

Implements a spin-lock mutex using atomic_exchange().

atomic_bool lock = ATOMIC_VAR_INIT(false);  // false if not locked;
                                            // true if locked.
void func(char *msg)
{
   static int count;                        // Initial value is 0.
   while( atomic_exchange(&lock, true))     // Spin until we lock.
       ;
   ++count;                                 // Critical section ...
   printf("%3u. %s\n", count, msg);
   lock = false;                            // Release the lock.
}

#define NUM_THREADS 20
int main()
{
    struct { thrd_t th; char msg[32]; } th_arr[NUM_THREADS];

    for( int i = 0; i < NUM_THREADS; ++i)
    {
       sprintf( th_arr[i].msg,"Thread %2u", i);
       if( thrd_create( &th_arr[i].th, (thrd_start_t)func,
                        (void*)th_arr[i].msg) != thrd_success)
           return EXIT_FAILURE;
    }
    for( int i = 0; i < NUM_THREADS; ++i)
        thrd_join( th_arr[i].th, NULL);
    return EXIT_SUCCESS;
}

Sample output:

  1. Thread  0
  2. Thread 12
  3. Thread  9
  ... (17 more lines)

Table 18-1. Compound atomic-fetch operations
op	Operation
add	Addition (+)
sub	Subtraction (-)
or	Bitwise OR (\|)
xor	Bitwise exclusive OR (^)
and	Bitwise AND (&)

Example

This code implements a semaphore using atomic_fence_sub() and atomic_fence_add().

#define MAX_READERS 5    // Number of data-reading threads.

// Semaphore counts the number of idle resources (here: readers),
// or -1 if locked by writer. Busy readers == MAX_READERS - count.
atomic_int count = ATOMIC_VAR_INIT(MAX_READERS);

int data = 0;            // Valid data are positive.

// 1 millisecond = 1,000,000 nanoseconds
const struct timespec ms = { .tv_nsec = 1000*1000 };

void reader(int* idPtr)
{
    int id = *idPtr;
    while(1)
    {
        // Check semaphore; decrement and read if count > 0.
        while( atomic_fetch_sub(&count, 1) <= 0)
        {  atomic_fetch_add(&count, 1);  thrd_yield(); }

        if( data > 0)                 // Read valid data.
            printf("Reader %d is reading %d\n", id, data);
        if( data < 0)                 // End marker: stop looping.
            break;

        atomic_fetch_add(&count, 1); // Release our reader slot.
        thrd_sleep(&ms,NULL);        // Simulate data processing.
    }
}

void writer(void) // Writes positive values; ends with a negative value.
{
    const int N = 20;                 // Number of data values to write.
    for(int n = 0; n <= N; ++n)
    {
        int d = n < N ? 10+n : -1;     // Prepare data or end marker.
        // When no readers are busy, lock the semaphore (count = -1):
        while( atomic_fetch_sub(&count,MAX_READERS+1) != MAX_READERS)
            atomic_fetch_add(&count, MAX_READERS+1);
        printf("Writer is writing %d\n", d),     // Critical section.
        data = d;
        atomic_fetch_add(&count, MAX_READERS+1); // Release the
                                                 // semaphores.
        thrd_sleep(&ms,NULL);                // Simulate data production.
    }
}

int main(void)
{
    thrd_t wth;
    struct { thrd_t th; int id; } th_arr[MAX_READERS];

    // Writer thread:
    if( thrd_create( &wth,(thrd_start_t)writer, NULL) != thrd_success)
       return EXIT_FAILURE;

    // Reader threads:
    for( int i = 0; i < MAX_READERS; ++i)
    {
       th_arr[i].id = i;
       if( thrd_create( &th_arr[i].th, (thrd_start_t)reader,
                        &th_arr[i].id) != thrd_success)
           return EXIT_FAILURE;
    }

    thrd_join( wth, NULL);
    for( int i = 0; i < MAX_READERS; ++i)
        thrd_join( th_arr[i].th, NULL);
    return EXIT_SUCCESS;
}

Example

See the example for atomic_flag_test_and_set() in this chapter.

Example

A spin-lock using atomic_flag_test_and_set().

atomic_flag lock = ATOMIC_FLAG_INIT;    // false if not locked;
                                        // true if locked.
void th_func(char *msg)
{
   static int count;                    // Initial value is 0

   while( atomic_flag_test_and_set(&lock))      // Spin until we lock.
       ;
   ++count;                                     // Critical section ...
   printf("%3u. %s\n", count, msg);
   atomic_flag_clear(&lock);                    // Release lock.
}

Example

atomic_long count;
atomic_init(&count, 0L);

Example

_Atomic(int_least64_t) avar64 = ATOMIC_VAR_INIT(0);
if( atomic_is_lock_free(&avar64))
{  /* ... avar64 is lock-free; use without a mutex  ... */  }

Example

struct Data { double x; } data[10];      // Shared data
atomic_int ai = ATOMIC_VAR_INIT(0);
...
// In first thread:
   for( int i = 0; i < 10; ++i)          // Operation A
       data[i].x = 0.5 *i;
   atomic_store_explicit(&ai,10, memory_order_release);
...
// In second thread:
    int n = atomic_load_explicit(&ai, memory_order_acquire);
    if( n > 0)
    {
        for( int i = 0; i < n; ++i)      // Operation B
           printf("%8.2lf", data[i].x);
        putchar('\n');
    }
    else
        printf("\nData not yet available.\n");

Example

static_assert(ATOMIC_INT_LOCK_FREE == 2,
              "atomic_int must be lock-free in the signal handler.");

atomic_int guide = ATOMIC_VAR_INIT(0),
           data  = ATOMIC_VAR_INIT(0);

void SIGTERM_handler(int sig)
{

    if( atomic_load_explicit( &guide, memory_order_relaxed) == 1)
    {
        atomic_signal_fence(memory_order_acquire);
        int d = atomic_load_explicit( &data, memory_order_relaxed);
        assert(d == 100);            // Condition fulfilled!
    // ...
    }
    _Exit(0);
}

int main(void)
{
    if( signal(SIGTERM, SIGTERM_handler) == SIG_ERR)
        perror("signal"), exit(1);
// ...
    atomic_store_explicit( &data, 100, memory_order_relaxed);
    atomic_signal_fence( memory_order_release);
    atomic_store_explicit( &guide, 1, memory_order_relaxed);
// ...
    return 0;
}

Example

See the example for atomic_load() in this chapter.

Example

Here’s a variation on the example for atomic_load() in this chapter, but using an acquire fence.

struct Data { double x; } data[10];        // Shared data.
atomic_int ai = ATOMIC_VAR_INIT(0);
...
// In first thread:
   for( int i = 0; i < 10; ++i)            // Operation A.
       data[i].x = 0.5 *i;
// atomic_fetch_add_explicit(&ai,10, memory_order_release);
// Replacing above line with:
   atomic_thread_fence(memory_order_release);
   atomic_fetch_add_explicit(&ai,10, memory_order_relaxed);
...
// In second thread:
    int n1 = 0;
    // ...
    int n2 = atomic_load_explicit(&ai, memory_order_relaxed);
    if( n2 > n1)
    {
        atomic_thread_fence(memory_order_acquire);
        for( int i = n1; i < n2; ++i)      // Operation B.
           printf("%8.2lf", data[i].x);    // Process the data.
        putchar('\n');
        n1 = n2;
    }
    else                                   // No fence necessary.
        printf("\nNo new data available.\n");

Example

#include <stdio.h>
#include <stdlib.h>

typedef struct  { unsigned long id;
                  int data;
                } record ;

int main()
{
  //Declare comparison function:
  int id_cmp(const void *s1, const void *s2);

  record recordset[] = { {3, 5}, {5, -5}, {4, 10}, {2,  2}, {1, -17} };
  record querykey;
  record *found = NULL;
  int recordcount = sizeof( recordset ) / sizeof ( record );

  printf( "Query record number: ");
  scanf( "%lu", &querykey.id );

  printf( "\nRecords before sorting:\n\n"
          "%8s %8s %8s\n", "Index", "ID", "Data" );

  for ( int i = 0; i < recordcount ; i++ )
    printf( "%8d %8u %8d\n", i, recordset[i].id, recordset[i].data );

  qsort( recordset, recordcount, sizeof( record ), id_cmp );

  printf( "\nRecords after sorting:\n\n"
          "%8s %8s %8s\n", "Index", "ID", "Data" );
  for ( int i = 0; i < recordcount ; i++ )
    printf( "%8d %8u %8d\n", i, recordset[i].id, recordset[i].data );

  found = (record *) bsearch( &querykey, recordset, recordcount,
                             sizeof( record ), id_cmp  );
  if ( found == NULL )
    printf( "No record with the ID %lu found.\n", querykey.id );
  else
    printf( "The data value in record %lu is %d.\n",
            querykey.id, found->data );

} // End of main().

int id_cmp(const void *s1, const void *s2)
/* Compares records by ID, not data content. */
{
  record *p1 = (record *)s1;
  record *p2 = (record *)s2;

  if      ( p1->id <  p2->id ) return -1;
  else if ( p1->id == p2->id ) return  0;
  else return 1;
}

This example produces the following output:

Query record number: 4

Records before sorting:

   Index       ID     Data
       0        3        5
       1        5       -5
       2        4       10
       3        2        2
       4        1      -17

Records after sorting:

   Index       ID     Data
       0        1      -17
       1        2        2
       2        3        5
       3        4       10
       4        5       -5
The data value in record 4 is 10.

Example

typedef struct  { unsigned long id;
                  const char* value;
                } record;

int main(void)
{
   // Declaration of the comparison function:
   int cmp(const void *r1, const void *r2, void *ct);

   record data[] = { {1789,"George"}, {1809,"James"},
                     {1797,"John"}, {1801,"Thomas"} };
   size_t datacount = sizeof(data) / sizeof(data[0]);
   record querykey = { .id=1801 };
   record *found = NULL;

   // Sort the array:
   qsort_s( data, datacount, sizeof(data[0]), cmp, NULL );
   // Search the array:
   found = bsearch_s( &querykey, data, datacount, sizeof(data[0]),
                      cmp, NULL );
   if( found == NULL )
     printf( "No record with the ID %lu found.\n", querykey.id );
   else
     printf( "The record %lu contains the value %s.\n",
             querykey.id, found->value );
} // End of main().

int cmp(const void *r1, const void *r2, void *ct)
// Compares the IDs of the records, not their data values.
// The context parameter ct is not used here.
{
   const record *p1 = (const record *)r1;
   const record *p2 = (const record *)r2;

   if      ( p1->id <  p2->id ) return -1;
   else if ( p1->id == p2->id ) return  0;
   else return 1;
}

Example

/* Build a table of wide characters for the first 128 byte values */
wchar_t low_table[128];

for ( int i = 0; i < 128 ; i++ )
  low_table[ i ] = (wchar_t)btowc( i );

Example

   char16_t c16Str[] = u"Grüße";
   char mbChar[MB_CUR_MAX];
   mbstate_t mbstate = {0};

   if( setlocale(LC_ALL, "en_US.UTF-8") == NULL)
       fputs("Unable to set the locale.\n", stderr);

   for( int i = 0; c16Str[i] != 0; ++i)
   {
      size_t nBytes = c16rtomb( mbChar, c16Str[i], &mbstate );
      printf("0x%04X %lc  Multibyte: [", c16Str[i], c16Str[i]);
      for( size_t j=0; j < nBytes; ++j)
         printf(" 0x%02X", (unsigned char)mbChar[j]);
      puts(" ]");
   }

Examples from the output of this code:

0x0047 G  Multibyte: [ 0x47 ]
0x0072 r  Multibyte: [ 0x72 ]
0x00FC ü  Multibyte: [ 0xC3 0xBC ]
0x00DF ß  Multibyte: [ 0xC3 0x9F ]
0x0065 e  Multibyte: [ 0x65 ]

Example

See the example for c16rtomb() in this chapter (note that, for 32-bit characters, you would use the format specifier 0x%08X in the first printf() statement).

Example

The absolute value of a complex number is its absolute distance from the origin in the complex plane—in other words, a positive real number, as this example demonstrates:

double complex z[4];
z[0] = 3.0 + 4.0 * I;
z[1] = conj( z[0] );
z[2] =  z[0] * I;
z[3] = -( z[0] );

for (int i = 0; i < 4 ; i++ )
  {
    double a = creal(z[i]);
    double b = cimag(z[i]);
    printf ( "The absolute value of (%4.2f %+4.2f × I) is ", a, b );

    double absolute_z = cabs(z[i]);
    printf ( "%4.2f.\n", absolute_z );
  }

The output of the sample code is as follows:

The absolute value of (3.00 +4.00 × I) is 5.00.
The absolute value of (3.00 -4.00 × I) is 5.00.
The absolute value of (-4.00 +3.00 × I) is 5.00.
The absolute value of (-3.00 -4.00 × I) is 5.00.

Example

double complex v, z ;
double a = 0.0, b = 0.0;

puts("Calculate the arc cosine of a complex number, cacos(z)\n");
puts("Enter the real and imaginary parts of a complex number:");
if ( scanf("%lf %lf", &a, &b) == 2)
{
  z = a + b * I;
  printf( "z = %.2f %+.2f*I.\n", creal(z), cimag(z) );

  v = cacos(z);
  printf( "The cacos(z) function yields %.2f %+.2f*I.\n",
          creal(v), cimag(v) );
  printf("The inverse function, ccos(cacos(z)), yields %.2f %+.2f*I.\n",
          creal( ccos(v)), cimag( ccos(v)) );
}
else
  printf("Invalid input. \n");

Example

double complex v, z ;
double a = 0.0, b = 0.0;

puts("Calculate the inverse hyperbolic cosine of a complex number,"
     " cacosh(z)\n");
puts("Enter the real and imaginary parts of a complex number:");
if ( scanf("%lf %lf", &a, &b) == 2)
{
  z = a + b * I;
  printf( "z = %.2f %+.2f*I.\n", creal(z), cimag(z) );

  v = cacosh(z);
  printf( "The cacosh(z) function yields %.2f %+.2f*I.\n",
          creal(v), cimag(v) );
  printf( "The inverse function, ccosh(cacosh(z)),"
          " yields %.2f %+.2f*I.\n",
          creal( ccosh(v)), cimag( ccosh(v)) );
}
else
  printf("Invalid input.\n");

Example

once_flag flag = ONCE_FLAG_INIT;

void doOnce(void) { puts("Function doOnce()."); }

int th_func(void * arg)
{
    puts((char*)arg);
    call_once(&flag, doOnce);
    return 0;
}

int main()
{
    thrd_t th1, th2, th3;

    if (   thrd_create(&th1, th_func, "Thread 1") != thrd_success
        || thrd_create(&th2, th_func, "Thread 2") != thrd_success
        || thrd_create(&th3, th_func, "Thread 3") != thrd_success )
    {
        fprintf(stderr,"Error creating thread.\n");  return 0xff;
    }
    puts("Hello ...");

    thrd_join(th1, NULL);
    thrd_join(th2, NULL);
    thrd_join(th3, NULL);
    return 0;
}

Possible output of this program:

Thread 1
Thread 2
Hello ...
Function doOnce().
Thread 3

Example

size_t n;
int *p;
printf("\nHow many integers do you want to enter? ");
scanf("%u", &n);
p = (int *)calloc(n, sizeof(int)); /* Allocate some memory */
if (p == NULL)
  printf("\nInsufficient memory.");
else
  /* read integers into array elements ... */

Example

/* Convert a complex number from Cartesian to polar coordinates. */
double complex z = -4.4 + 3.3 * I;
double radius = cabs( z );
double argument = carg( z );

double x = creal( z );
double y = cimag( z );

printf( "Cartesian (x, y): (%4.1f, %4.1f)\n", x, y );
printf( "Polar (r, theta): (%4.1f, %4.1f)\n", radius, argument );

This code produces the following output:

Cartesian (x, y): (-4.4,  3.3)
Polar (r, theta): ( 5.5,  2.5)

Example

puts("Results of the casin() function for integer values:");
float complex z = 0;
for ( int n = -3;  n <= 3;  ++n)
{
  z = casinf(n);
  printf("  casin(%+d) = %+.2f %+.2f*I\n", n, crealf(z), cimagf(z) );
}

This code produces the following output:

Results of the casin() function for integer values:
  casin(-3) = -1.57 +1.76*I
  casin(-2) = -1.57 +1.32*I
  casin(-1) = -1.57 -0.00*I
  casin(+0) = +0.00 +0.00*I
  casin(+1) = +1.57 -0.00*I
  casin(+2) = +1.57 +1.32*I
  casin(+3) = +1.57 +1.76*I

Example

double complex v, w, z ;
double a = 0.0, b = 0.0;

puts("Enter the real and imaginary parts of a complex number:");
if ( scanf("%lf %lf", &a, &b) == 2)
{
  z = a + b * I;
  printf( "z = %.2f %+.2f*I.\n", creal(z), cimag(z) );

  v = casin(z);
  w = casinh(z);
  printf( "z is the sine of %.2f %+.2f*I\n",  creal(v), cimag(v) );
  printf( "and the hyperbolic sine of %.2f %+.2f*I.\n",
          creal(w), cimag(w) );
}
else
  printf("Invalid input. \n");

Example

double complex v, w, z ;
double a = 0.0, b = 0.0;

puts("Enter the real and imaginary parts of a complex number:");
if ( scanf("%lf %lf", &a, &b) == 2)
{
  z = a + b * I;
  printf( "z = %.2f %+.2f*I.\n", creal(z), cimag(z) );

  v = catan(z);
  w = catanh(z);
  printf( "z is the tangent of %.2f %+.2f*I\n",  creal(v), cimag(v) );
  printf( "and the hyperbolic tangent of %.2f %+.2f*I.\n",
          creal(w), cimag(w) );
}
else
  printf("Invalid input. \n");

This code produces output like the following:

Enter the real and imaginary parts of a complex number:30 30
z = 30.00 +30.00*I.
z is the tangent of 1.55 +0.02*I
and the hyperbolic tangent of 0.02 +1.55*I.

Example

See the example for catan() in this chapter.

Example

#define KM_PER_AU (149597870.691) // An astronomical unit is the mean
                                  // distance between Earth and Sun:
                                  // about 150 million km.
#define DY_PER_YR (365.24)

double dist_au, dist_km, period_dy, period_yr;

printf("How long is a solar year on your planet (in Earth days)?\n");
scanf( "%lf", &period_dy );

period_yr = period_dy / DY_PER_YR;
dist_au = cbrt( period_yr * period_yr );    // by Kepler's Third Law
dist_km = dist_au * KM_PER_AU;

printf("Then your planet must be about %.0lf km from the Sun.\n",
                                                       dist_km );

Example

/* Demonstrate the exponential definition
 * of the complex cosine function.
 */
double complex z = 2.2 + 3.3 * I;
double complex c, d;

c = ccos( z );
d = 0.5 * ( cexp( z * I ) + cexp( − z * I ));

printf("The ccos() function returns %.2f %+.2f × I.\n",
        creal(c), cimag(c) );
printf("Using the cexp() function, the result is %.2f %+.2f × I.\n",
        creal(d), cimag(d) );

This code produces the following output:

The ccos() function returns -7.99 -10.95 × I.
Using the cexp() function, the result is -7.99 -10.95 × I.

Example

double complex v, w, z = 1.2 − 3.4 * I;

v = ccosh( z );
w = 0.5 * ( cexp(z) + cexp(-z) );

printf( "The ccosh() function returns %.2f %+.2f*I.\n",
        creal(v), cimag(v) );
printf( "Using the cexp() function, the result is %.2f %+.2f*I.\n",
        creal(w), cimag(w) );

This code produces the following output:

The ccosh() function returns -1.75 +0.39*I.
Using the cexp() function, the result is -1.75 +0.39*I.

Example

/* Amount due = unit price * count * VAT, rounded up to the next cent */
div_t total = { 0, 0 };
int count = 17;
int price = 9999;           // 9999 cents is $99.99
double vat_rate = 0.055;    // Value-added tax of 5.5%

total = div( (int)ceil( (count * price) * (1 + vat_rate)), 100);

printf("Total due: $%d.%2d\n", total.quot, total.rem);

This code produces the following output:

Total due: $1793.33

Tip

The natural exponential function cexp() is the inverse of the natural logarithm, clog().

Example

// Demonstrate Euler's theorem in the form
// e^(I*z) = cos(z) + I * sin(z)

double complex z = 2.2 + 3.3 * I;
double complex c, d;

c = cexp( z * I );
d = ccos( z ) + csin( z ) * I ;

printf( "cexp( z*I ) yields %.2f %+.2f × I.\n",
        creal(c), cimag(c) );
printf( "ccos( z ) + csin( z ) * I yields %.2f %+.2f × I.\n",
        creal(d), cimag(d) );

This code produces the following output:

cexp( z*I ) yields -0.02 +0.03 × I.
ccos( z ) + csin( z ) * I yields -0.02 +0.03 × I.

Example

double complex z = 4.5 − 6.7 * I;

printf( "The complex variable z is equal to %.2f %+.2f × I.\n",
        creal(z),cimag(z) );

This code produces the following output:

The complex variable z is equal to 4.50 -6.70 × I.

Example

FILE *fp;
int c;
if ((fp = fopen("infile.dat", "r")) == NULL)
  fprintf(stderr, "Couldn't open input file.\n");
else
{
  c = fgetc(fp);   // fgetc() returns a character on success;
  if (c == EOF)    // EOF means either an error or end-of-file.
  {
    if ( feof(fp))
      fprintf(stderr, "End of input file reached.\n");
    else if ( ferror(fp))
      fprintf(stderr, "Error on reading from input file.\n");
    clearerr(fp);    // Same function clears both conditions.
  }
  else
  { /* ... */ }      // Process the character that we read.
}

Example

#include <stdio.h>
#include <time.h>
time_t start, stop;
clock_t ticks; long count;

int main()
{
   time(&start);
   for (count = 0; count <= 50000000; ++count)
  {
    if (count % 1000000 != 0) continue;   // measure only full millions
    ticks = clock();
    printf("Performed %ld million integer divisions; "
           "used %0.2f seconds of CPU time.\n",  count / 1000000,
           (double)ticks/CLOCKS_PER_SEC);
  }
  time(&stop);
  printf("Finished in about %.0f seconds.\n", difftime(stop, start));
  return 0;
}

This program produces 51 lines of output, ending with something like this:

Performed 50 million integer divisions; used 2.51 seconds of CPU time.
Finished in about 6 seconds.

Example

double complex z = clog( -1.0);       // z = 0.0 + 3.1415926 * I

Example

// Wake up three threads waiting for one condition variable using
// cnd_signal() and cnd_broadcast().
#include <stdio.h>
#include <threads.h>
#include <stdatomic.h>

cnd_t cv;
mtx_t mtx;         // Mutex for the condition variable cv
atomic_bool go = ATOMIC_VAR_INIT(0);         // Initially false

int th_func(void * arg)                      // Thread function
{
    mtx_lock(&mtx);
    printf("%s waiting ... \n", (char*)arg );

    while( !go)
        if( cnd_wait(&cv, &mtx) != thrd_success)
            return -1;

    printf("%s finished.\n", (char*)arg);
    mtx_unlock(&mtx);
    return 0;
}

int main(void)
{
    thrd_t th1, th2, th3;

    if( cnd_init(&cv) != thrd_success
        || mtx_init(&mtx, mtx_plain) != thrd_success)
    {
        fputs("Initialization error.\n", stderr); return 1;
    }

    if(    thrd_create(&th1, th_func, "Thread 1") != thrd_success
        || thrd_create(&th2, th_func, "Thread 2") != thrd_success
        || thrd_create(&th3, th_func, "Thread 3") != thrd_success)
    {
        fputs("Thread error.\n", stderr); return 2;
    }

    struct timespec duration = { .tv_sec = 1 };
    thrd_sleep( &duration, NULL);       // Wait 1 second.

    go = 1;
    puts("cnd_signal ...");
    if ( cnd_signal(&cv) != thrd_success)
    {  fputs("Signal error.\n", stderr); return 3;  }

    thrd_sleep( &duration, NULL);        // Wait 1 second.
    puts("cnd_broadcast ...");
    if ( cnd_broadcast(&cv) != thrd_success)
    {  fputs("Broadcast error.\n", stderr); return 4;  }

    thrd_join(th1, NULL);  thrd_join(th2, NULL);  thrd_join(th3, NULL);

    cnd_destroy( &cv);
    mtx_destroy( &mtx);
    return 0;
}

Possible output of this program:

Thread 1 waiting ...
Thread 2 waiting ...
Thread 3 waiting ...
cnd_signal ...
Thread 1 finished.
cnd_broadcast ...
Thread 3 finished.
Thread 2 finished.

Example

cnd_t cv;          // A condition variable.

int func()
{
    if( cnd_init(&cv) != thrd_success)
    {
        fputs("Initialization error.\n", stderr); return -1;
    }
// ...   Use the condition variable ...

    cnd_destroy( &cv);
    return 0;
}

Example

See the examples for cnd_destroy() and cnd_broadcast() in this chapter.

Example

See the example for cnd_broadcast() in this chapter, and Example 14-4 in Chapter 14.

Note

The parameter ts specifies a point in Coordinated Universal Time, or UTC (also called Greenwich Mean Time). The current time in UTC can be obtained using the function timespec_get().

The return value is thrd_success if no error occurs, thrd_timedout if the time limit elapsed, or thrd_error if an error occurred.

Example

cnd_t cv;
mtx_t mtx;                   // Mutex for the condition variable cv
atomic_bool go = ATOMIC_VAR_INIT(0);           // Initially false.

int th_func(void * millisec)                   // Thread function.
{
    int res = thrd_success;
    struct timespec ts;
    timespec_get( &ts, TIME_UTC);              // The current time
    ts.tv_nsec  += *(long*)millisec * 1E6;     // + millions of ns.

    mtx_lock(&mtx);
    puts("Waiting ...");
    while( !go && res == thrd_success)
       res = cnd_timedwait(&cv, &mtx, &ts);
    switch( res)
    {
        case thrd_success:
           puts("Working ... done.");  break;
        case thrd_timedout:
           puts("Timed out.");   break;
        default:
           puts("cnd_timedwait: error.");
    };
    mtx_unlock(&mtx);
    return res;
}

int main(void)
{
    thrd_t th1, th2;
    long tm_limit1 = 100, tm_limit2 = 500;   // In milliseconds.

    if( cnd_init(&cv) != thrd_success
        || mtx_init(&mtx, mtx_plain) != thrd_success)
    {
        fputs("Initialization error.\n", stderr); return 1;
    }

    if(    thrd_create(&th1, th_func, &tm_limit1) != thrd_success
        || thrd_create(&th2, th_func, &tm_limit2) != thrd_success)
    {
        fputs("Thread error.\n", stderr); return 2;
    }

    struct timespec dura = { 0 };
    dura.tv_nsec = 200 *1E6;         // 200 million nanoseconds.
    thrd_sleep( &dura, NULL);        // Wait 200 milliseconds.

    go = 1;
    puts("Sending broadcast ...");
    cnd_broadcast(&cv);

    thrd_join(th1, NULL);  thrd_join(th2, NULL);
    cnd_destroy( &cv);
    mtx_destroy( &mtx);
    return 0;
}

Typical output:

Waiting ...
Waiting ...
Timed out.
Sending broadcast ...
Working ... done.

Example

See the example for cnd_broadcast() in this chapter.

Example

See the example for cabs() in this chapter.

Example

/* Test for signed zero values */
double x = copysign(0.0, -1.0);
double y = copysign(0.0, +1.0);

printf( "x is %+.1f; y is %+.1f.\n", x, y);
printf( "%+.1f is %sequal to %+.1f.\n",
         x, ( x == y ) ? "" : "not ", y);

This code produces the following output:

x is -0.0; y is +0.0.
-0.0 is equal to +0.0.

Example

/*
 * Calculate the sloping width of a roof
 * given the horizontal width
 * and the angle from the horizontal.
 */
#define PI 3.141593
#define DEG_PER_RAD (180.0/PI)

double roof_pitch = 20.0;            // In degrees
double floor_width = 30.0;           // In feet, say.
double roof_width = 1.0 / cos(roof_pitch / DEG_PER_RAD) * floor_width;

printf( "The sloping width of the roof is %4.2f ft.\n", roof_width );

This code produces the following output:

The sloping width of the roof is 31.93 ft.

Example

double x, sum = 1.0;
unsigned max_n;
printf("Cosh(x) is the sum as n goes from 0 to infinity "
       "of x^(2*n) / (2*n)!\n");
    // That's x raised to the power of 2*n, divided by 2*n factorial.
printf("Enter x and a maximum for n (separated by a space): ");
if (scanf(" %lf %u", &x, &max_n) < 2)
{
    printf("Couldn't read two numbers.\n");
    return -1;
}
printf("cosh(%.2f) = %.4f;\n", x, cosh(x));
for ( unsigned n = 1 ; n <= max_n ; n++ )
{
    unsigned factor = 2 * n;         // Calculate (2*n)!
    unsigned divisor = factor;
    while ( factor > 1 )
    {
        factor--;
        divisor *= factor;
    }
    sum += pow(x, 2 * n) / divisor;   // Accumulate the series
}
printf("Approximation by series of %u terms = %.4f.\n", max_n+1, sum);

With the numbers 1.72 and 3 as input, the program produces the following output:

cosh(1.72) = 2.8818;
Approximation by series of 4 terms = 2.8798.

Example

double complex z = 0.0 + 2.7 * I;
double complex w = 2.7 + 0.0 * I;

double complex c = cpow(w, z);   // Raise e to the power of i*2.7

printf("%.2f %+.2f × I raised to the power of %.2f %+.2f × I \n"
       "is %.2f %+.2f × I.\n",
       creal(w), cimag(w), creal(z), cimag(z), creal(c), cimag(c));

This code produces the following output:

2.70 +0.00 × I raised to the power of 0.00 +2.70 × I
is -0.90 +0.44 × I.

Example

double complex z = -INFINITY − 2.7 * I;

double complex c = cproj(z);
printf("%.2f %+.2f * I is projected to %.2f %+.2f * I.\n",
       creal(z), cimag(z), creal(c), cimag(c));

This code produces the following output:

-inf -2.70 * I is projected to inf -0.00 * I.

Example

double complex z = 4.5 − 6.7 * I;

printf( "The complex variable z is equal to %.2f %+.2f × I.\n",
                                               creal(z), cimag(z) );

This code produces the following output:

The complex variable z is equal to 4.50 -6.70 × I.

Example

// Demonstrate the exponential definition of the complex sine function.
double complex z = 4.3 − 2.1 * I;
double complex c, d;

c = csin( z );
d = ( cexp( z * I ) − cexp( − z * I )) / (2 * I);

printf("The csin() function returns %.2f %+.2f × I.\n",
       creal(c), cimag(c) );
printf("Using the cexp() function, the result is %.2f %+.2f × I.\n",
       creal(d), cimag(d) );

This code produces the following output:

The csin() function returns -3.80 +1.61 × I.
Using the cexp() function, the result is -3.80 +1.61 × I.

Example

double complex v, w, z = -1.2 + 3.4 * I;

v = csinh( z );
w = 0.5 * ( cexp(z) − cexp(−z) );

printf( "The csinh() function returns %.2f %+.2f*I.\n",
        creal(v), cimag(v) );
printf( "Using the cexp() function, the result is %.2f %+.2f*I.\n",
        creal(w), cimag(w) );

This code produces the following output:

The csinh() function returns 1.46 -0.46*I.
Using the cexp() function, the result is 1.46 -0.46*I.

Example

double complex z = 1.35 − 2.46 * I;
double complex c, d;

c = csqrt( z );
d = c * c;

printf("If the square root of %.2f %+.2f × I equals %.2f %+.2f × I,"
       "\n", creal(z), cimag(z), creal(c), cimag(c) );
printf("then %.2f %+.2f × I squared should equal %.2f %+.2f × I.\n",
       creal(c), cimag(c), creal(d), cimag(d) );

This code produces the following output:

If the square root of 1.35 -2.46 × I equals 1.44 -0.85 × I,
then 1.44 -0.85 × I squared should equal 1.35 -2.46 × I.

Example

double complex z = − 0.53 + 0.62 * I;
double complex c, d;

c = ctan( z );
d = csin( z ) / ccos( z );

printf("The ctan() function returns %.2f %+.2f × I.\n",
       creal(c), cimag(c) );
printf("Using the csin() and ccos() functions yields %.2f %+.2f × I.\n",
       creal(d), cimag(d) );

This code produces the following output:

The ctan() function returns -0.37 +0.67 × I.
Using the csin() and ccos() functions yields -0.37 +0.67 × I.

Example

double complex v, w, z =  -0.5 + 1.23 * I;

v = ctanh( z );
w = csinh( z ) / ccosh( z );

printf("The ctanh() function returns %.2f %+.2f*I.\n",
                                     creal(v), cimag(v) );
printf("Using the csinh() and ccosh() functions yields %.2f %+.2f*I.\n",
        creal(w), cimag(w) );

This code produces the following output:

The ctanh() function returns -1.53 +0.82*I.
Using the csinh() and ccosh() functions yields -1.53 +0.82*I.

Example

void logerror(int errorcode)
{
  time_t eventtime;

  time(&eventtime);
  fprintf( stderr, "%s: Error number %d occurred.\n",
           ctime(&eventtime), errorcode );
}

This code produces output like the following:

Wed Sep  9 14:58:03 2015
: Error number 23 occurred.

The output contains a line break because the string produced by ctime() ends in a newline character.

Example

#define __STDC_WANT_LIB_EXT1__  1
#include <time.h>
// ...

   time_t now = 0;
   char timeStr[26];

   time(&now);                 // Date and time as an integer.
   if(ctime_s( timeStr, sizeof(timeStr), &now) == 0)
      printf("Date and time: %s", timeStr);

Typical output for this code is:

Date and time: Sun May 17 14:40:04 2015

Example

See the sample program for clock() in this chapter.

Example

int people, apples;
div_t  share;

for ( apples = -3 ; apples < 6 ; apples += 3 )
{
  if ( apples == 0 )
    continue;                   // Don't bother dividing up nothing.
  for ( people = -2 ; people < 4 ; people += 2 )
  {
    if ( people == 0 )
      continue;                 // Don't try to divide by zero.
    share = div( apples, people );

     printf( "If there are %+i of us and %+i apples, "
             "we each get %+i with %+i left over.\n",
             people, apples, share.quot, share.rem );
   }
}

As the output of the preceding code illustrates, any nonzero remainder has the same sign as the dividend:

If there are -2 of us and -3 apples, we each get +1 with -1 left over.
If there are +2 of us and -3 apples, we each get -1 with -1 left over.
If there are -2 of us and +3 apples, we each get -1 with +1 left over.
If there are +2 of us and +3 apples, we each get +1 with +1 left over.

Example

/*
 * Given a normal distribution with mean 0 and standard deviation 1,
 * calculate the probability that the random variable is within the
 * range [0, 1.125]
 */
double sigma = 1.0;        // The standard deviation
double bound = 1.125;
double probability;        // probability that mean <= value <= bound

probability = 0.5 *erf( bound / (sigma * sqrt(2.0)) );

Example

FILE *f_in, *f_out;

enum { X_OK = 0, X_ARGS, X_NOIN, X_NOOUT };

if ( argc != 3 ) {
  fprintf( stderr, "Usage: program input-file output-file\n");
  exit( X_ARGS );
}

f_in  = fopen(argv[1], "r");
if ( f_in == NULL ) {
  fprintf( stderr, "Unable to open input file.\n");
  exit( X_NOIN );
}
f_out = fopen(argv[2], "a+");
if ( f_out == NULL ) {
  fprintf( stderr, "Unable to open output file.\n");
  exit( X_NOOUT );
}

/* ... read, process, write, close files ... */

exit( X_OK );

Tip

The natural exponential function exp() is the inverse of the natural logarithm function, log().

Example

/* Amount owed = principal * e^(interest_rate * time) */
int principal = 10000;      // Initial debt is ten thousand dollars.
int balance = 0;
double rate = 0.055;        // Interest rate is 5.5% annually.
double time = 1.5;          // Period is eighteen months.

balance = principal * exp( rate * time );
printf("Invest %d dollars at %.1f%% compound interest, and "
       "in %.1f years you'll have %d dollars.\n",
       principal, rate*100.0, time, balance );

This code produces the following output:

Invest 10000 dollars at 5.5% compound interest, and in 1.5 years
you'll have 10859 dollars.

Tip

The base 2 exponential function exp2() is the inverse of the base 2 logarithm function, log2().

Example

// The famous grains-of-rice-on-a-chessboard problem.
// The sultan loses a chess game. The wager was one grain for square 1
// on the chessboard, then double the last number for each successive
// square. How much rice in all?

int squares = 64;
long double gramspergrain = 0.0025L;    // A grain of rice weighs 25 mg.
long double sum = 0.0L;

for ( int i = 0; i < squares; i++ )
    sum += gramspergrain * exp2l( (long double)i );

  printf( "The sultan's wager costs him %.3Lf metric tons of rice.\n",
          sum / 1000000.0L );             // A million grams per ton.

This code produces the following output:

The sultan's wager costs him 46116860184.274 metric tons of rice.

Example

/* let y = (−e^(−2x) − 1 ) / (e^(−2x) + 1), for certain values of x */

double w, x, y;
if (( x > 1.0E-12 ) && ( x < 1.0 ))
{
  w = expm1( -(x+x) );
  y = − w / ( w + 2.0 );
}
else
  /* ... handle other values of x ... */

Example

float x = 4.0F * atanf( 1.0F );
long double y = 4.0L * atanl( 1.0L );

if ( x == y )
  printf( "x and y are exactly equal.\n" );
else if ( fabs( x − y ) < 0.0001 * fabsl( y ) )
  printf( "x and y are approximately equal:\n"
          "x is %.8f; y is %.8Lf.\n", x, y );

This code produces the following output:

x and y are approximately equal:
x is 3.14159274; y is 3.14159265.

Example

/* Print a file to the console, line by line. */
FILE *fp_infile;
char linebuffer[512];

if (( fp_infile= fopen("input.dat", "r")) == NULL )
{
  fprintf(stderr, "Couldn't open input file.\n");
  return -1;
}

while ( fgets( linebuffer, sizeof(linebuffer), fp_infile ) != NULL )
  fputs( linebuffer, stdout );
if ( ! feof(fp_infile) )   // This means "if not end of file"
  fprintf( stderr, "Error reading from input file.\n" );

if ( fclose(fp_infile) != 0 )
{
  fprintf(stderr, "Error closing input file.\n");
  return -2;
}

Example

/* Make sure an argument is within the domain of asin() */

double sign, argument, result;
/* ... */

sign = copysign( 1.0, argument );      // Save the sign ...
argument = copysign( argument, 1.0 );  // then use only positive values
argument = 1.0 − fdim( 1.0, argument );     // Trim excess beyond 1.0
result = asin( copysign(argument, sign) );  // Restore sign and
                                            // call asin()

Example

double x, y, result;
int exceptions;

#pragma STDC FENV_ACCESS ON
feclearexcept( FE_ALL_EXCEPT );
result = somefunction( x, y );   // This function may raise exceptions!
exceptions = fetestexcept( FE_INEXACT | FE_UNDERFLOW );

if ( exceptions & FE_UNDERFLOW )
{
  /* ... handle the underflow ... */
}
else if ( exceptions & FE_INEXACT )
{
  /* ... handle the inexact result ... */
}

Example

The fegetenv() and fesetenv() functions can be used to provide continuity of the floating-point environment between different locations in a program:

static fenv_t  fpenv;   // Global environment variables.
static jmp_buf env;
/* ... */

#pragma STDC FENV_ACCESS ON
fegetenv(&fpenv);        // Store a copy of the floating-point
                         // environment

if ( setjmp(env) == 0 )  // setjmp() returns 0 when actually called
{
  /* ... Proceed normally; floating-point environment unchanged ... */
}
else                  // Nonzero return value means longjmp() occurred
{
  fesetenv(&fpenv);   // Restore floating-point environment
                      // to known state
  /* ... */
}

Example

/* Temporarily store the state of the FE_INEXACT, FE_UNDERFLOW
 * and FE_OVERFLOW flags
 */
fexcept_t fpexcepts;

#pragma STDC FENV_ACCESS ON
/* Save state: */
fegetexceptflag( &fpexcepts, FE_INEXACT | FE_UNDERFLOW | FE_OVERFLOW );

feclearexcept( FE_INEXACT | FE_UNDERFLOW | FE_OVERFLOW );

/* ... Perform calculations that might raise those exceptions ... */

/* ... Handle (or ignore) the exceptions our calculations raised ... */

/* Restore state as saved: */
fesetexceptflag( &fpexcepts, FE_INEXACT | FE_UNDERFLOW | FE_OVERFLOW );

Example

See the examples for fmod() and fesetround() in this chapter.

Example

/*
 * Compute the hypotenuse of a right triangle, avoiding intermediate
 * overflow or underflow.
 *
 * (This example ignores the case of one argument having
 * great magnitude and the other small, causing both overflow
 * and underflow!)
 */
double hypotenuse(double sidea, double sideb)
{
#pragma STDC FENV_ACCESS ON
  double  sum, scale, ascaled, bscaled, invscale;
  fenv_t  fpenv;
  int     fpeflags;

  if ( signbit( sidea ) ) sidea = fabs( sidea );
  if ( signbit( sideb ) ) sideb = fabs( sideb );

  feholdexcept(&fpenv);  // Save previous environment,
                         // clear exceptions,
                         // switch to nonstop processing.
  invscale = 1.0;
  sum = sidea * sidea + sideb * sideb;   // First try whether a^2 + b^2
                                         // causes any exceptions.

  fpeflags = fetestexcept(FE_UNDERFLOW | FE_OVERFLOW);    // Did it?
  if ( fpeflags & FE_OVERFLOW && sidea > 1.0 && sideb > 1.0 )
  {
    /* a^2 + b^2 caused an overflow. Scale the triangle down. */
    feclearexcept(FE_OVERFLOW);
    scale = scalbn(1.0, (DBL_MIN_EXP /2 ));
    invscale = 1.0 / scale;
    ascaled = scale * sidea;
    bscaled = scale * sideb;
    sum = ascaled * ascaled + bscaled * bscaled;
  }
  else if (fpeflags & FE_UNDERFLOW && sidea < 1.0 && sideb < 1.0 )
  {
    /* a^2 + b^2 caused an underflow. Scale the triangle up. */
    feclearexcept(FE_UNDERFLOW);
    scale = scalbn(1.0, (DBL_MAX_EXP /2 ));
    invscale = 1.0 / scale;
    ascaled = scale * sidea;
    bscaled = scale * sideb;
    sum = ascaled * ascaled + bscaled * bscaled;
  }

  feupdateenv(&fpenv);        // restore the caller's environment, and
                            // raise any new exceptions

  /* c = (1/scale) * sqrt((a * scale)^2 + (b * scale)^2): */
  return invscale * sqrt(sum);
}

Example

See the examples for clearerr() and fclose() in this chapter.

Example

Although user programs rarely need to raise a floating-point exception by artificial means, the following example illustrates how to do so:

int result, except_set, except_test;

#pragma STDC FENV_ACCESS ON
feclearexcept (FE_ALL_EXCEPT);
except_set = FE_OVERFLOW;
result = feraiseexcept( except_set );
if ( result != 0 )
{
  printf( "feraisexcept() failed (%d)\n", result );
  exit( result );
}
except_test = fetestexcept( except_set );
if ( except_test != except_set )
  printf( "Tried to raise flags %X, but only raised flags %X.\n",
          except_set, except_test );

Example

See the examples for clearerr() and fclose() in this chapter.

Example

See the example for fegetenv() in this chapter.

Example

See the example for fegetexceptflag() in this chapter.

Example

/*
 * Save, set, and restore the rounding direction.
 * Report an error and abort if setting the rounding direction fails.
 */
#pragma STDC FENV_ACCESS ON
int prev_rounding_dir;
int result;
prev_rounding_dir = fegetround();
result = fesetround( FE_TOWARDZERO );

/* ... perform a calculation that requires rounding toward 0 ... */

fesetround( prev_rounding_dir );
#pragma STDC FENV_ACCESS OFF

See also the example for fmod() in this chapter.

Example

See the examples for feclearexcept() and feholdexcept() in this chapter.

Example

See the example for feholdexcept() in this chapter.

Example

In the following example, the program fflush.c writes two lines of text to a file. If the macro FLUSH is defined, the program flushes the file output buffer to disk after each line. If not, only the first output line is explicitly flushed. Then the program raises a signal to simulate a fatal error so that we can observe the effect with and without the second fflush() call.

/* fflush.c: Tests the effect of flushing output file buffers. */
FILE *fp;

#ifdef FLUSH
char filename[ ] = "twice.txt";
#else
char filename[ ] = "once.txt";
#endif /* FLUSH */

fp = fopen( filename, "w" );
if ( fp == NULL)
  fprintf( stderr, "Failed to open file '%s' to write.\n", filename );

fputs( "Going once ...\n", fp );
fflush( fp );              // Flush the output unconditionally

fputs( "Going twice ...\n", fp );

#ifdef FLUSH
fflush( fp );              // Now flush only if compiled with '-DFLUSH'
#endif

raise( SIGKILL );          // End the program abruptly.

fputs( "Gone.\n", fp );    // These three lines will never be executed.
fclose( fp );
exit( 0 );

When we compile and test the program, the output looks like this:

$cc -DFLUSH -o fflushtwice fflush.c
$ ./fflushtwice
Killed
$ cc -o fflushonce fflush.c
$ ./fflushonce
Killed
$ ls -l
-rw-r--r--    1 tony     tony          781 Jul 22 12:36 fflush.c
-rwxr-xr-x    1 tony     tony        12715 Jul 22 12:38 fflushonce
-rwxr-xr-x    1 tony     tony        12747 Jul 22 12:37 fflushtwice
-rw-r--r--    1 tony     tony           15 Jul 22 12:38 once.txt
-rw-r--r--    1 tony     tony           31 Jul 22 12:37 twice.txt

The two cc commands have created two different executables, named fflushonce and fflushtwice, and each version of the program has run and killed itself in the process of generating an output file. The contents of the two output files, once.txt and twice.txt, are different:

$cat twice.txt
Going once ...
Going twice ...
$ cat once.txt
Going once ...
$

When the fputs() call returned, the output string was still in the file buffer, waiting for the operating system to write it to disk. Without the second fflush() call, the intervening “kill” signal caused the system to abort the program, closing all its files, before the disk write occurred.

Example

FILE *fp;
int c;
char buffer[1024];
int i = 0;

/* ... Open input file ... */

while ( i < 1023 )
{
  c = fgetc( fp );       // Returns a character on success;
  if (c == EOF)          // EOF means either an error or end-of-file.
  {
    if (feof( fp ))
      fprintf( stderr, "End of input.\n" );
    else if ( ferror( fp ))
      fprintf( stderr, "Input error.\n" );
    clearerr( fp );      // Clear the file's error or EOF flag.
    break;
  }
  else
  {
    buffer[i++] = (char) c;  // Use value as char *after* checking
                             // for EOF.
  }
}
buffer[i] = '\0';        // Terminate string.

Example

FILE *datafile; fpos_t bookmark;

if ((datafile = fopen(".testfile", "r+")) == NULL)
{
  fprintf( stderr, "Unable to open file %s.\n",".testfile" );
  return 1;
}

if ( fgetpos( datafile, &bookmark ))    // Save initial position
  perror( "Saving file position" );
else
{
  /* ... Read data, modify data ... */

  if ( fsetpos( datafile, &bookmark ))    // Back to initial position
    perror( "Restoring file position" );

  /* ... write data back at the original position in the file ... */
}

Example

FILE *titlefile;
char title[256];
int counter = 0;

if ((titlefile = fopen("titles.txt", "r")) == NULL)
  perror( "Opening title file" );
else
{
  while ( fgets( title, 256, titlefile ) != NULL )
  {
    title[ strlen(title) -1 ] = '\0';   // Trim off newline character.
    printf( "%3d: \"%s\"\n", ++counter, title );
  }
  /* fgets() returned NULL: either EOF or an error occurred. */
  if ( feof(titlefile) )
    printf("Total: %d titles.\n", counter);
}

If the working directory contains an appropriate text file, the program produces output like this:

  1: "The Amazing Maurice"
  2: "La condition humaine"
  3: "Die Eroberung der Maschinen"
Total: 3 titles.

Example

char file_in[ ]  = "local_in.txt",
     file_out[ ] = "local_out.txt";
FILE *fp_in_wide, *fp_out_wide;
wint_t wc;

if ( setlocale( LC_CTYPE, "" ) == NULL)
  fwprintf( stderr,
            L"Sorry, couldn't change to the system's native locale.\n"),
  exit(1);

if (( fp_in_wide = fopen( file_in, "r" )) == NULL )
  fprintf( stderr, "Error opening the file %s\n", file_in), exit(2);

if (( fp_out_wide = fopen( file_out, "w" )) == NULL )
  fprintf( stderr, "Error opening the file %s\n", file_out), exit(3);

fwide( fp_in_wide, 1);       // Not strictly necessary, since first
fwide( fp_out_wide, 1);      // file access also sets wide or byte mode.

while (( wc = fgetwc( fp_in_wide )) != WEOF )
{
  // ... process each wide character read ...

  if ( fputwc( (wchar_t)wc, fp_out_wide) == WEOF)
    break;
}
if ( ferror( fp_in_wide))
  fprintf( stderr, "Error reading the file %s\n", file_in);
if ( ferror( fp_out_wide))
  fprintf( stderr, "Error writing to the file %s\n", file_out);

Example

FILE *fp_in_wide;
wchar_t buffer[4096];
wchar_t *line = buffer;

if (( fp_in_wide = fopen( "local.doc", "r" )) == NULL )
  perror( "Opening input file" );
fwide( fp_in_wide );

line = fgetws( buffer, sizeof(buffer), fp_in_wide );
if ( line == NULL )
  perror( "Reading from input file" );

Example

/* Scale a point by independent x and y factors */
struct point { int x, y; };

int width_orig = 1024, height_orig = 768;
int width_new = 800, height_new = 600;

struct point scale( struct point orig )
{
  struct point new;
  new.x = (int)floor(orig.x * (double)width_new  / (double)width_orig);
  new.y = (int)floor(orig.y * (double)height_new / (double)height_orig);
  return new;
}

Example

double x, y, z;

x = nextafter( 3.0, 4.0 ); // Smallest possible double value
                           // greater than 3
y = 1.0/3.0;
z = -1.0;

printf( "x = %.15G\n"
        "y = %.15G\n"
        "z = %.15G\n", x, y, z );

#ifdef FP_FAST_FMA

printf( "fma( x, y, z) = %.15G\n", fma( x, y, z) );

#else     // i.e., not def FP_FAST_FMA

double product = x * y;

printf( "x times y = %.15G\n", product );
printf( "%.15G + z = %.15G\n", product, product + z );

#endif   // def FP_FAST_FMA

fmax

C99

Determines the greater of two floating-point numbers.

#include <math.h>
double fmax( double x, double y );
float fmaxf( float x, float y );
long double fmaxl( long double x , long double y );

The fmax() functions return the value of the greater argument.

Example

// Let big equal the second-greatest-possible double value ...
const double big = nextafter( DBL_MAX, 0.0 );
// ... and small the second-least possible-double value:
const double small = nextafter( DBL_MIN, 0.0 );

double a, b, c;

/* ... */

if ( fmin( fmin( a, b ), c ) <= small )
  printf( "At least one value is too small.\n" );
if ( fmax( fmax( a, b ), c ) >= big )
  printf( "At least one value is too great.\n" );

Example

See the example for fmax().

Example

double people = -2.25, apples = 3.3, eachgets = 0.0, someleft = 0.0;
int saverounding = fegetround();       // Save previous setting

fesetround(FE_TOWARDZERO);

eachgets = rint( apples / people );
someleft = fmod( apples, people );

printf( "If there are %+.2f of us and %+.2f apples, \n"
        "each of us gets %+.2f, with %+.2f left over.\n",
        people, apples, eachgets, someleft );

fesetround( saverounding );            // Restore previous setting

This code produces the following output:

If there are -2.25 of us and +3.30 apples,
each of us gets -1.00, with +1.05 left over.

Table 18-2. File access modes
Mode string	Access mode	Notes
`"r"` `"r+"`	Read Read and write	The file must already exist
`"w"` `"w+"`	Write Write and read	If the file does not exist, `fopen()` creates it; if it does exist, `fopen()` erases its contents on opening
`"a"` `"a+"`	Append Append and read	If the file does not exist, `fopen()` creates it

Example

FILE *in, *out;
int c;

if ( argc != 3 )
  fprintf( stderr, "Usage: program input-file output-file\n"), exit(1);

// If "-" appears in place of input filename, use stdin:
in  = (strcmp(argv[1], "-") == 0) ? stdin  : fopen(argv[1], "r");
if ( in == NULL )
  { perror( "Opening input file" ); return -1; }

// If "-" appears in place of output filename, use stdout:
out = (strcmp(argv[2], "-") == 0) ? stdout : fopen(argv[2], "a+");
if ( out == NULL )
  { perror( "Opening output file" ); return -1; }

while (( c = fgetc( in )) != EOF)
  if ( fputc(c, out) == EOF )
    break;

if ( !feof( in ))
  perror( "Error while copying" );
fclose(in), fclose(out);

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
// ...

  FILE *fp;   errno_t err;  char filename[] = "new.txt";

  // Open a new file for writing and reading:
  err = fopen_s( &fp, filename, "w+x");
  if( err != 0)
  {
     fprintf(stderr, "Unable to create the file \"%s\".\n", filename);
     exit(err);
  }
  // ... The file is open.

Example

double minimum( double a, double b )
{
  register int aclass = fpclassify( a );
  register int bclass = fpclassify( b );

  if ( aclass == FP_NAN || bclass == FP_NAN )
    return NAN;

  if ( aclass == FP_INFINITE )        // -Inf is less than anything;
    return ( signbit( a ) ? a : b );  // +inf is greater than anything.

  if ( bclass == FP_INFINITE )
    return ( signbit( b ) ? b : a );

  return ( a < b ? a : b );
}

Example

FILE *fp_log;
time_t sec;

fp_log = fopen("example.log", "a");
if ( fp != NULL)
{
  time(&sec);
  fprintf( fp_log, "%.24s Opened log file.\n", ctime( &sec ) );
}

This code appends a line like the following to the file example.log:

Wed Dec  9 21:10:43 2015 Opened log file.

Example

#define CYCLES 10000
#define DOTS 4

printf("Performing %d modulo operations ", CYCLES );
for (int count = 0; count < CYCLES; ++count)
{
    if ( count % ( CYCLES / DOTS ) != 0) continue;
    fputc( '.', stdout );            // Mark every nth cycle
}
printf( " done.\n" );

This code produces the following output:

Performing 10000 modulo operations .... done.

Example

See the examples for fclose() and fflush() in this chapter.

Example

See the example for fgetwc() in this chapter.

Example

FILE *fpw;
char fname_wide[] = "widetest.txt";
int widemodeflag = 1;
int result;

wchar_t widestring[] =
                  L"How many umlauts are there in Fahrvergnügen?\n";

if ((fpw = fopen(fname_wide, "a")) == NULL)
  { perror( "Opening output file" ); return -1; }

// Set file to wide-character orientation:
widemodeflag = fwide(fpw, widemodeflag);
if ( widemodeflag <= 0 )
{
  fprintf(stderr, "Unable to set output file %s to wide characters\n",
          fname_wide);
  (void)fclose(fpw);
  return -1;
}

// Write wide-character string to the file:
result = fputws( widestring, fpw );

Example

typedef struct {
  char name[64];
  /* ... more members ... */
} item;

#define CACHESIZE 32              // Size as a number of array elements.

FILE *fp;
int readcount = 0;
item itemcache[CACHESIZE];        // An array of "items".

if (( fp = fopen( "items.dat", "r+" )) == NULL )
  { perror( "Opening data file" ); return -1; }

/* Read up to CACHESIZE "item" records from the file.*/

readcount = fread( itemcache, sizeof (item), CACHESIZE, fp );

Example

char *ptr;

/* Obtain a block of 4096 bytes ... */
ptr = calloc(4096, sizeof(char));

if ( ptr == NULL )
  fprintf( stderr, "Insufficient memory.\n" ), abort();
else
{
/* ... use the memory block ... */
  strncpy( ptr, "Imagine this is a long string.\n", 4095 );
  fputs( stdout, ptr );
/* ... and release it. */
  free( ptr );
}

Example

time_t sec;
char fname[ ] = "test.dat";
if ( freopen( fname, "w", stdout ) == NULL )
  fprintf( stderr, "Unable to redirect stdout.\n" );
else
{
  time(&sec);
  printf( "%.24s: This file opened as stdout.\n", ctime(&sec) );
}

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
// ...

   char filename[] = "redirect.txt";
   FILE *fp;
   // Redirect standard output to the file redirect.txt:
   errno_t err = freopen_s( &fp, filename, "w", stdout);
   if( err != 0)
   { fprintf( stderr, "Unable to redirect stdout to %s\n",
              filename);
     exit(err);
   }
   printf("This text is being written to the file %s.\n", filename);
   fclose(stdout);

Example

double fourthrt( double x )
{
  int exponent, exp_mod_4;
  double mantissa = frexp( x, &exponent );

  exp_mod_4 = exponent % 4;
  exponent -= ( exp_mod_4 );      // Get an exponent that's
                                  // divisible by four ...
  for ( int i = abs( exp_mod_4 ); i > 0; i-- )
  {
    if ( exp_mod_4 > 0 )       // ... and compensate in the mantissa.
      mantissa *= 2.0;
    else
      mantissa /= 2.0;
  }
  return ldexp( sqrt( sqrt( mantissa )), exponent / 4 );
}

Example

The example code reads information about a user from a file, which we will suppose contains a line of colon-separated strings like this:

tony:x:1002:31:Tony Crawford,,:/home/tony:/bin/bash

Here is the code:

struct pwrecord {        // Structure for contents of passwd fields.
  unsigned int uid;
  unsigned int gid;
  char  user[32];
  char  pw  [32];
  char  realname[128];
  char  home    [128];
  char  shell   [128];
};

/* ... */

FILE *fp;
int results = 0;
struct pwrecord record;
struct pwrecord *recptr = &record;
char  gecos[256] = "";

/* ... Open the password file to read ... */

record = (struct pwrecord) { UINT_MAX, UINT_MAX, "", "", "", "", "" };

/* 1. Read login name, password, UID and GID. */
results = fscanf( fp, "%31[^:]:%31[^:]:%u:%u:",
                  recptr->user, recptr->pw,
                   &recptr->uid, &recptr->gid );

This function call reads the first part of the input string, tony:x:1002:31:, and copies the two strings "tony" and "x" and assigns two unsigned int values, 1002 and 31, to the corresponding structure members. The return value is 4. The remainder of the code is then as follows:

if ( results < 4 )
{
  fprintf( stderr, "Unable to parse line.\n" );
  fscanf( fp, "%*[^\n]\n" );          // Read and discard rest of line.
}

/* 2. Read the "gecos" field, which may contain nothing, or just the
 *    real name, or comma-separated sub-fields.
 */
results = fscanf( fp, "%255[^:]:", gecos );
if ( results < 1 )
  strcpy( recptr->realname,  "[No real name available]" );
else
  sscanf( gecos, "%127[^,]", recptr->realname ); // Truncate at
                                                 // first comma.

/* 3. Read two more fields before the end of the line. */

results = fscanf( fp, "%127[^:]:%127[^:\n]\n",
                  recptr->home, recptr->shell );
if ( results < 2 )
{
  fprintf( stderr, "Unable to parse line.\n" );
  fscanf( fp, "%*[^\n]\n" );        // Read and discard rest of line.
}
printf( "The user account %s with UID %u belongs to %s.\n",
         recptr->user, recptr->uid, recptr->realname );

For our sample input line, the printf() call produces the following output:

The user account tony with UID 1002 belongs to Tony Crawford.

If the implementation supports the secure functions, the function fscanf_s() can also be used as an alternative to fscanf(). The first fscanf_s() call in the preceding example would then be as follows:

/* 1. Read login name, password, UID and GID. */
results = fscanf_s( fp, "%31[^:]:%31[^:]:%u:%u:",
                    recptr->user, sizeof(recptr->user),
                    recptr->pw, sizeof(recptr->pw),
                    &recptr->uid, &recptr->gid );

Table 18-3. Values for fseek()’s origin argument
Value of origin	Macro name	Offset is relative to
0	`SEEK_SET`	The beginning of the file
1	`SEEK_CUR`	The current position
2	`SEEK_END`	The end of the file

Example

typedef struct {  long id;
                  double value;
               } record;
FILE *fp;
record cur_rec = (record) { 0, 0.0 };
int reclength_file = sizeof(record);
long seek_id = 123L;

if ((fp = fopen("records", "r")) == NULL)
  perror( "Unable to open records file" );
else do
{
  if ( 1 > fread( &cur_rec.id, sizeof (long), 1, fp ))
    fprintf( stderr, "Record with ID %ld not found\n", seek_id );
  else      // Skip rest of record
    if ( fseek( fp, reclength_file − sizeof(long), 1 ))
      perror( "fseek failed" );
} while ( cur_rec.id != seek_id );

Example

See the example for fgetpos() in this chapter.

Tip

To save the access position in a multibyte stream, use the fgetpos() function, which also saves the stream’s multibyte parsing state.

Example

This example searches in a file, whose name is the second command-line argument, for a string, which the user can specify in the first command-line argument.

#define MAX_LINE 256

FILE *fp;
long lOffset = 0L;
char sLine[MAX_LINE] = "";
char *result = NULL;
int lineno = 0;
/* ... */
if ((fp = fopen(argv[2], "r")) == NULL)
{
  fprintf(stderr, "Unable to open file %s\n", argv[2]);
  exit( -1 );
}
do
{
  lOffset = ftell( fp );    // Bookmark the beginning of
                            // the line we're about to read.
  if ( -1L == lOffset )
    fprintf( stderr, "Unable to obtain offset in %s\n", argv[2] );
  else
    lineno++;

  if ( ! fgets(sLine,MAX_LINE,fp )) // Read next line from file.
    break;
} while ( strstr( sLine, argv[1] ) == NULL ); // Test for argument
                                              // in sLine.
/* Dropped out of loop: Found search keyword or EOF */
if ( feof(fp) || ferror(fp) )
{
    fprintf( stderr,"Unable to find \"%s\" in %s\n", argv[1], argv[2] );
    rewind(fp);
}
else
{
    printf( "%s (%d): %s\n", argv[2], lineno, sLine );
    fseek( fp, lOffset, 0 );    // Set file pointer at beginning of
                                // the line containing the keyword
}

The following example runs this program on its own source file, searching for a line containing the word “the”. As you can see, the first occurrence of “the” is in line 22. The program finds that line and displays it:

tony@luna:~/ch18$ ./ftell the ftell.c
ftell.c (22):      lOffset = ftell(fp);    // Bookmark the beginning of

Example

See the example for fputws() in this chapter.

Example

wchar_t name_local[ ]   = L"Ka\u0142u\u017Cny";
char    name_portable[ ]= "Kaluzny";
char    locale[ ]       = "pl_PL.UTF-8";
char *  newlocale;

newlocale = setlocale( LC_ALL, locale );
if ( newlocale == NULL )
  fprintf( stderr, "Sorry, couldn't change the locale to %s.\n"
           "The current locale is %s.\n",
           locale, setlocale( LC_ALL, NULL ));

fwprintf( stdout,
          L"Customer's name: %ls (Single-byte transliteration: %s)\n",
          name_local, name_portable );

If the specified Polish locale is available, this example produces the output:

Customer's name: Kałużny (Single-byte transliteration: Kaluzny)

Example

See the example for wscanf() in this chapter.

Example

typedef struct {
  char name[64];
  /* ... more structure members ... */
} item;

#define CACHESIZE 32              // Size as a number of array elements.

FILE *fp;
int writecount = 0;
item itemcache[CACHESIZE];        // An array of "items".

/* ... Edit the items in the array ... */

if (( fp = fopen( "items.dat", "w" )) == NULL )
  { perror ( "Opening data file" ); return -1; }

/* Write up to CACHESIZE "item" records to the file.*/

writecount = fwrite( itemcache, sizeof (item), CACHESIZE, fp );

Example

FILE *inputs[16];
int nextchar, i = 0;

/* ... open 16 input streams ... */

do {
  nextchar = getc( inputs[i++] );       // Warning: getc() is a macro!
  /* ... process the character ... */
} while (i < 16);

The do...while statement in this example skips over some files in the array if getc() evaluates its argument more than once. Here is a safer version, without side effects in the argument to getc():

for ( i = 0; i < 16; i++ ) {
  nextchar = getc( inputs[i] );
  /* ... process the character ... */
}

Example

char file_name[256};
int answer;

/* ... */

fprintf( stderr, "Are you sure you want to replace the file \"%s\"?\n",
         file_name );
answer = tolower(getchar());
if ( answer != 'y' )
  exit( -1 );

Example

#define MAXPATH 1024;
char sPath[MAXPATH] = "";
char *pTmp;

if (( pTmp = getenv( "PATH" )) != NULL )
  strncpy( sPath, pTmp, MAXPATH − 1 );       // Save a copy for our use.
else
  fprintf( stderr, "No PATH variable set.\n") ;

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
// ...
  char envStr[512];
  size_t len;
  if( getenv_s( &len, envStr, sizeof(envStr),"PATH") == 0)
     printf("PATH variable (%u characters): \n%s\n", len, envStr);
  else if( len > 0)
     printf("The PATH variable (%u characters) is more than "
            "%u bytes long.\n", len, sizeof(envStr));
  else
     printf("PATH variable not found.\n");

Warning

The gets() function provides no way to limit the input length, and if the stdin stream happens to deliver a long input line, gets() will attempt to store characters past the end of the available buffer. Such buffer overflows are a potential security risk. Use fgets() instead, which has a parameter to control the maximum input length.

The C11 standard retires the function gets(), replacing it with the function gets_s(), which has an additional parameter for the size of the input buffer.

Example

char buffer[1024];

/* Replaced gets() with fgets() to avoid potential buffer overflow
 * OLD:  while ( gets( buffer ) != NULL )
 * NEW: below
 */
while ( fgets( buffer, sizeof(buffer), stdin ) != NULL )
{
  /* ... process the line; remember that fgets(), unlike gets(),
     retains the newline character at the end of the string ... */
}

Warning

An alternative to gets_s() to process lines of any length correctly is the function fgets(), which does not discard any characters read. fgets() also stores newline characters ('\n') that it reads.

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
// ...

   char text[100];
   puts("Enter a line of text:");
   if( gets_s(text, sizeof(text)) == NULL)
      fputs("Unable to read the text.\n", stderr);
   else
      printf("Your text:\n%s\n", text);

Example

wint_t wc;

if ( setlocale( LC_CTYPE, "" ) == NULL)
{
  fwprintf( stderr,
            L"Sorry, couldn't change to the system's native locale.\n");
  return 1;
}
while ( (wc = getwc( stdin)) != WEOF )
{
  wc = towupper(wc);
  putwc( (wchar_t)wc, stdout);
}

Example

wint_t wc;

if ( setlocale( LC_CTYPE, "" ) == NULL)
{
  fwprintf( stderr,
            L"Sorry, couldn't change to the system's native locale.\n");
  return 1;
}
while ( (wc = getwchar()) != WEOF ) // or:  (wc = getwc( stdin))
{
  wc = towupper(wc);
  putwchar((wchar_t)wc);        // or:  putwc( (wchar_t)wc, stdout);
}

Example

The following program prints a string showing the offset of the local time zone from UTC:

time_t     rawtime;
struct tm  utc_tm, local_tm, *ptr_tm;
char       buffer[1024] = "";

time( &rawtime );                    // Get current time as an integer.
ptr_tm = gmtime( &rawtime );        // Convert to UTC in a struct tm.
memcpy( &utc_tm, ptr_tm, sizeof(struct tm) );   // Save a local copy.
ptr_tm = localtime( &rawtime );      // Do the same for local time zone.
memcpy( &local_tm, ptr_tm, sizeof(struct tm) );

if ( strftime( buffer, sizeof(buffer),
               "It's %A, %B %d, %Y, %R o'clock, UTC.", &utc_tm ) )
  puts( buffer );
if ( strftime( buffer, sizeof(buffer),
               "Here it's %A, %B %d, %Y, %R o'clock, UTC %z.",
               &local_tm ) )
  puts( buffer );

This code produces output like the following:

It's Tuesday, March 24, 2015, 22:26 o'clock, UTC.
Here it's Wednesday, March 25, 2015, 00:26 o'clock, UTC +0200.

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <time.h>
// ...

   time_t now;   struct tm tmStruct;   char timeStr[26];

   time(&now);                        // Current time as an integer.
   if( gmtime_s(&now, &tmStruct) != NULL          // Convert to UTC.
       && asctime_s( timeStr, sizeof(timeStr), &tmStruct) == 0)
     printf("The current universal time (UTC): %s\n", timeStr);

Typical output:

The current universal time (UTC): Sun May 17 14:58:09 2015

Example

double x, y, h;            // Three sides of a triangle

printf( "How many kilometers do you want to go westward? " );
scanf( "%lf", &x );

printf( "And how many southward? " );
scanf( "%lf", &y );

errno = 0;
h = hypot( x, y );

if ( errno )
  perror( __FILE__ );
else
  printf( "Then you'll be %4.2lf km from where you started.\n", h );

If the user answers the prompts with 3.33 and 4.44, the program prints this output:

Then you'll be 5.55 km from where you started.

Example

// Handle runtime constraint violations using only
// the return value of secure functions.
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
// ...

   char message[20] = "Hello, ",
        name[20];
   set_constraint_handler_s(ignore_handler_s);

   printf("Please enter your name: ");
   if( gets_s( name, sizeof(name)) == NULL)
   { /* Error: user entered more than 19 characters.*/ }
   else if( strcat_s( message, sizeof(message), name) != 0)
   { /* Error: message array is too small.*/ }
   else
     puts( message);

Example

int exponent = 0;
double x = -1.509812734e200;

while ( exponent < INT_MAX )
{
  exponent = ilogb( x );
  printf( "The exponent of %g is %d.\n", x, exponent );

  if ( x < 0.0 && x * x > 1.0 )
    x /= 1e34;
  else
    x += 1.1, x *= 2.2e34 ;
}

This code produces some 15 output lines, including these samples:

The exponent of -1.50981e+200 is 664.
The exponent of -1.50981e+30 is 100.
The exponent of -0.000150981 is -13.
The exponent of 2.41967e+34 is 114.
The exponent of inf is 2147483647.

Example

intmax_t quantity1 = 9182734;
intmax_t quantity2 = 1438756;

printf( "The difference between the two quantities is %ji.\n",
        imaxabs( quantity2 − quantity1 ));

Example

intmax_t people = 110284, apples = 9043291;
imaxdiv_t  share;

if ( people == 0 )              // Avoid dividing by zero.
    { printf( "There's no one here to take the apples.\n" ); return -1; }
else
  share = imaxdiv( apples, people );

printf( "If there are %ji of us and %ji apples,\n"
        "each of us gets %ji, with %ji left over.\n",
        people, apples, share.quot, share.rem );

This example prints the following output:

If there are 110284 of us and 9091817 apples,
each of us gets 82, with 3 left over.

Example

See the example for isprint() in this chapter.

Tip

Which characters are considered alphabetic depends on the current locale setting for the localization category LC_CTYPE, which you can query or change using the setlocale() function.

In the C locale, which is the default locale setting, the alphabetic characters are those for which isupper() or islower() returns true. These are the 26 lowercase and 26 uppercase letters of the Latin alphabet, which are the letters in the basic source and execution character sets (see “Character Sets”).

Accented characters, umlauts, and the like are considered alphabetic only in certain locales. Moreover, other locales may have characters that are alphabetic but neither uppercase nor lowercase, or both uppercase and lowercase.

In all locales, the isalpha() classification is mutually exclusive with iscntrl(), isdigit(), ispunct(), and isspace().

Example

See the example for isprint() in this chapter.

Example

This program trims trailing blank characters from the user’s input:

#define MAX_STRING 80

char raw_name[MAX_STRING];
int i;

printf( "Enter your name, please: " );
fgets( raw_name, sizeof(raw_name), stdin );

/* Trim trailing blanks: */

i = ( strlen(raw_name) − 1 );   // Index the last character.
while ( i >= 0 )                // Index must not go
{                               // below first character.
  if (  raw_name[i] == '\n' )
    raw_name[i] = '\0';         // Chomp off the newline character.
  else if ( isblank( raw_name[i] ) )
    raw_name[i] = '\0';         // Lop off trailing spaces and tabs.
  else
    break;                      // Real data found; stop truncating.
  --i;                          // Count down.
}

See also the example for isprint() in this chapter.

Example

See the example for isprint() in this chapter.

Example

See the example for isprint() in this chapter.

Example

double vsum( int n, ... )
// n is the number of arguments in the list
{
  va_list argptr;
  double sum = 0.0, next = 0.0;
  va_start( argptr, n );
  while ( n-- )
  {
    next = va_arg( argptr, double );
    sum += next;
    if ( isfinite( sum ) == 0 )
      break;                // If sum reaches infinity, stop adding.
  }
  va_end( argptr );
  return sum;
}

Example

See the example for isprint() in this chapter.

Example

/* Can a, b, and c be three sides of a triangle? */
double a, b, c, temp;
/* First get the longest "side" in a. */
if ( isgreater( a, b ) )
   temp = a; a = b; b = temp;
if ( isgreater( a, c ) )
   temp = a; a = c; c = temp;
/* Then see if a is longer than the sum of the other two sides: */
if ( isgreaterequal( a, b + c ) )
  printf( "The three numbers %.2lf, %.2lf, and %.2lf "
          "are not sides of a triangle.\n", a, b, c );

Example

This function takes a shortcut if it encounters an infinite addend:

double vsum( int n, va_list argptr )
{
  double sum = 0.0, next = 0.0;
  va_start( argptr, n );

  for ( int i = 0; i < n; i ++ )
  {
    next = va_arg( argptr, double );
    if ( isinf( next ) )
      return next;
    sum += next;
  }
  va_end( argptr );
  return sum;
}

Example

double minimum( double a, double b )
{
  if ( islessgreater( a, b ) )
    return ( isless( a, b ) ? a : b );
  if ( a == b )
    return a;
  feraiseexcept( FE_INVALID );
  return NAN;
}

Example

See the example for isprint() in this chapter.

Example

double dMax( double a, double b )
{
  // NaN overrides all comparison:
  if ( isnan( a ) ) return a;
  if ( isnan( b ) ) return b;
  // Anything is greater than -inf:
  if ( isinf( a ) && signbit( a ) ) return b;
  if ( isinf( b ) && signbit( b ) ) return a;

  return ( a > b ? a : b );
}

Example

double maximum( double a, double b )
{
  if ( isnormal( a ) && isnormal( b ) )    // Handle normal case first.
    return ( a >= b ) ? a : b ;

  else if ( isnan( a ) || isnan( b ) )
  {
    /* ... */

Example

unsigned int c;

printf("\nThe current locale for the 'is ...' functions is '%s'.\n",
       setlocale(LC_CTYPE, NULL));

printf("Here is a table of the 'is ...' values for the characters"
       " from 0 to 127 in this locale:\n\n");

for ( c = 0; c < 128; c++ ) // Loop iteration for each table row.
{
  if ( c % 24 == 0 )        // Repeat table header every 24 rows.
  {
    printf("Code char alnum alpha blank cntrl digit graph lower"
           " print punct space\n");
    printf("---------------------------------------------------"
           "------------------\n");
  }
  printf(  "%4u %4c %3c %5c %5c %5c %5c %5c %5c %5c %5c %5c\n",
       c,                              // Print numeric character code.
       ( isprint( c )  ?  c  : ' ' ),  // Print the glyph, or a space
                                       // if it's not printable.
       ( isalnum( c )  ? 'X' : '-' ),  // In a column for each category,
       ( isalpha( c )  ? 'X' : '-' ),  // print X for yes or - for no.
       ( isblank( c )  ? 'X' : '-' ),
       ( iscntrl( c )  ? 'X' : '-' ),
       ( isdigit( c )  ? 'X' : '-' ),
       ( isgraph( c )  ? 'X' : '-' ),
       ( islower( c )  ? 'X' : '-' ),
       ( isprint( c )  ? 'X' : '-' ),
       ( ispunct( c )  ? 'X' : '-' ),
       ( isspace( c )  ? 'X' : '-' ) );
}  // end of loop for each character value

The following selected lines from the table produced by this program include at least one member and one nonmember of each category:

Code char alnum alpha blank cntrl digit graph lower print punct space
---------------------------------------------------------------------
  31        -     -     -     X     -     -     -     -     -     -
  32        -     -     X     -     -     -     -     X     -     X
  33    !   -     -     -     -     -     X     -     X     X     -

  48    0   X     -     -     -     X     X     -     X     -     -

  65    A   X     X     -     -     -     X     -     X     -     -

 122    z   X     X     -     -     -     X     X     X     -     -

Example

See the example for isprint() in this chapter.

Table 18-4. Whitespace characters in the default locale, C
Character	ASCII name	Decimal value
`'\t'`	Horizontal tabulator	9
`'\n'`	Line feed	10
`'\v'`	Vertical tabulator	11
`'\f'`	Form feed	12
`'\r'`	Carriage return	13
`' '`	Space	32

Example

char buffer[1024];
char *ptr = buffer;

while ( fgets( buffer, sizeof(buffer), stdin ) != NULL )
{
  ptr = buffer;
  while ( isspace( *ptr ))             // Skip over leading whitespace.
    ptr++;
  printf( "The line read: %s\n", ptr );
}

See also the example for isprint() in this chapter.

Example

double maximum( double a, double b )
{
  if ( isinf( a ) )         // +Inf > anything; -Inf < anything
    return ( signbit( a ) ? b : a );

  if ( isinf( b ) )
    return ( signbit( b ) ? a : b );

  if ( isunordered( a, b ) )
  {
    feraiseexcept( FE_INVALID );
    return NAN;
  }
  return ( a > b ? a : b );
}

Example

See the examples for setlocale() and isprint() in this chapter.

Example

wint_t wc;
int i, dummy;

setlocale( LC_CTYPE, "" );

wprintf( L"\nThe current locale for the 'is ...' functions is '%s'.\n",
         setlocale( LC_CTYPE, NULL ) );
wprintf( L"These are the alphanumeric wide characters"
         " in this locale:\n\n" );

for ( wc = 0, i = 0; wc < 1024; wc++ )
  if ( iswalnum( wc ) )
    {
      if ( i % 25 == 0 )
        {
          wprintf( L"... more ...\n" );
          dummy = getchar();           // Wait before printing more
          wprintf( L"Wide character     Code\n" );
          wprintf( L"-----------------------\n" );
        }
      wprintf(   L"%5lc            %4lu\n", wc, wc );
      i++;
    }
wprintf( L"-----------------------\n" );
return 0;

Here are samples from the output of this code. Which characters can be displayed correctly on the screen depends on the font used:

The current locale for the 'is ...' functions is 'de_DE.UTF-8'.
These are the alphanumeric wide characters in this locale:

Wide character     Code
-----------------------
     0               48
     1               49
     2               50
...
     þ              254
     ÿ              255
     Ā              256
     ā              257
     Ă              258
     ă              259
     Ą              260
     ą              261

Tip

Which characters are considered alphabetic depends on the current locale setting for the localization category LC_CTYPE, which you can query or change using the setlocale() function. In all locales, the iswalpha() classification is mutually exclusive with iswcntrl(), iswdigit(), iswpunct() and iswspace().

Accented characters, umlauts, and the like are considered alphabetic only in certain locales. Moreover, other locales may have wide characters that are alphabetic but neither uppercase nor lowercase, or both uppercase and lowercase.

Example

wint_t wc;

if ( setlocale( LC_CTYPE, "" ) == NULL)
{
  fwprintf( stderr,
            L"Sorry, couldn't change to the system's native locale.\n");
  return 1;
}
wprintf( L"The current locale for the 'isw ...' functions is '%s'.\n",
         setlocale(LC_CTYPE, NULL));

wprintf( L"Here is a table of the 'isw ...' values for the characters "
         L"from 128 to 255 in this locale:\n\n");

for ( wc = 128; wc < 255; ++wc ) // Loop iteration for each table row.
{
  if ( (wc-128) % 24 == 0 )      // Repeat table header every 24 rows.
  {
    wprintf(L"Code char alnum alpha blank cntrl digit graph lower"
            L" print punct space\n");
    wprintf(L"---------------------------------------------------"
            L"------------------\n");
  }
  wprintf(L"%4u %4lc %3c %5c %5c %5c %5c %5c %5c %5c %5c %5c %5c %5c\n",
       wc,                              // Print numeric character code.
       ( iswprint( wc )  ? wc  : ' ' ), // Print the glyph, or a space
                                        // if it's not printable.
       ( iswalnum( wc )  ? 'X' : '-' ), // In a column for each
       ( iswalpha( wc )  ? 'X' : '-' ), // category, print X for
       ( iswblank( wc )  ? 'X' : '-' ), // yes or - for no.
       ( iswcntrl( wc )  ? 'X' : '-' ),
       ( iswdigit( wc )  ? 'X' : '-' ),
       ( iswgraph( wc )  ? 'X' : '-' ),
       ( iswlower( wc )  ? 'X' : '-' ),
       ( iswprint( wc )  ? 'X' : '-' ),
       ( iswpunct( wc )  ? 'X' : '-' ),
       ( iswspace( wc )  ? 'X' : '-' ) );
}  // end of loop for each character value

The following selected lines from the table produced by this program illustrate members of various categories:

Code char alnum alpha blank cntrl digit graph lower print punct space
---------------------------------------------------------------------
 128        -     -     -     X     -     -     -     -     -     -
 162    ¢   -     -     -     -     -     X     -     X     X     -
 163    £   -     -     -     -     -     X     -     X     X     -
 169    ©   -     -     -     -     -     X     -     X     X     -
 170    ª   X     X     -     -     -     X     -     X     -     -
 171    «   -     -     -     -     -     X     -     X     X     -
 180    ´   -     -     -     -     -     X     -     X     X     -
 181    μ   X     X     -     -     -     X     X     X     -     -
 182    ¶   -     -     -     -     -     X     -     X     X     -
 185    ¹   -     -     -     -     -     X     -     X     X     -
 186    º   X     X     -     -     -     X     -     X     -     -
 191    ¿   -     -     -     -     -     X     -     X     X     -
 192    À   X     X     -     -     -     X     -     X     -     -

Example

See the example for iswalpha() in this chapter.

Example

See the example for iswalpha() in this chapter.

Table 18-5. Wide-character properties
Character property	iswctype() call	Equivalent single function call
`"alnum"`	`iswctype(wc, wctype("alnum"))`	`iswalnum(wc)`
`"alpha"`	`iswctype(wc, wctype("alpha"))`	`iswalpha(wc)`
`"blank"`	`iswctype(wc, wctype("blank"))`	`iswblank(wc)`
`"cntrl"`	`iswctype(wc, wctype("cntrl"))`	`iswcntrl(wc)`
`"digit"`	`iswctype(wc, wctype("digit"))`	`iswdigit(wc)`
`"graph"`	`iswctype(wc, wctype("graph"))`	`iswgraph(wc)`
`"lower"`	`iswctype(wc, wctype("lower"))`	`iswlower(wc)`
`"print"`	`iswctype(wc, wctype("print"))`	`iswprint(wc)`
`"punct"`	`iswctype(wc, wctype("punct"))`	`iswpunct(wc)`
`"space"`	`iswctype(wc, wctype("space"))`	`iswspace(wc)`
`"upper"`	`iswctype(wc, wctype("upper"))`	`iswupper(wc)`
`"xdigit"`	`iswctype(wc, wctype("xdigit"))`	`iswxdigit(wc)`

Example

wint_t wc = L'ß';

setlocale( LC_CTYPE, "de_DE.UTF-8" );
if ( iswctype( wc, wctype( "alpha" )) )
{
  if ( iswctype( wc, wctype( "lower" ) ))
    wprintf( L"The character %lc is lowercase.\n", wc );
  if ( iswctype( wc, wctype( "upper" ) ))
    wprintf( L"The character %lc is uppercase.\n", wc );
}

Example

See the example for iswalpha() in this chapter.

Example

See the example for iswalpha() in this chapter.

Example

See the example for iswalpha() in this chapter.

Example

See the example for iswalpha() in this chapter.

Example

See the example for iswalpha() in this chapter.

Example

See the example for iswalpha() in this chapter.

Example

See the example for iswalpha() in this chapter.

Example

See the example for iswalpha() in this chapter.

Example

See the example for isprint() in this chapter.

Example

See the example for abs() in this chapter.

Example

See the example for frexp() in this chapter.

Example

See the example for div() in this chapter.

Example

See the example for abs() in this chapter.

Example

See the example for div() in this chapter.

Example

See the example for the analogous function lrint().

Example

See the example for lround() in this chapter.

Example

long long cents;         // Amount in cents or customary fraction of
                         // currency unit.
struct lconv *locinfo;
wchar_t number[128] = { L'\0' },  prefix[32]  = { L'\0' },
        suffix[32]  = { L'\0' };

// Use system's current locale.
char *localename = setlocale( LC_MONETARY, "" );

locinfo = localeconv();

/* ... */

if ( cents >= 0 ) // For positive amounts,
                  // use 'p_...' members of lconv structure.
{
  if ( locinfo->p_cs_precedes )    // If currency symbol before number
  {                                // ... prepare prefix
     mbstowcs( prefix, locinfo->currency_symbol, 32 );
     if ( locinfo->p_sep_by_space )
        wcscat( prefix, L" " );    // ... maybe with a space.
   }
/* ... else etc. ... */

Example

See the example for gmtime() in this chapter.

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <time.h>
// ...

   time_t now;   struct tm timeStruct;   char timeStr[26];

   time(&now);               // Current time as an integer.
   // Convert to local time as a struct tm:
   if( localtime_s(&now, &timeStruct) != NULL)
   {
      timeStruct.tm_year += 1;                // One year later.
      if(asctime_s( timeStr, sizeof(timeStr), &timeStruct) == 0)
         printf("A year from today: %s", timeStr);
   }

Example

The following code prints some sample values for base 2, base e, and base 10 logarithms:

double x[] = { 1E-100, 0.5, 2, exp(1), 10, 1E+100 };

puts("       x           log2(x)           log(x)          log10(x)\n"
     " -------------------------------------------------------------");
for ( int i = 0; i < sizeof(x) / sizeof(x[0]); ++i )
{
  printf("%#10.3G %+17.10G %+17.10G %+17.10G\n",
         x[i], log2(x[i]), log(x[i]), log10(x[i]) );
}

This code produces the following output:

       x           log2(x)            log(x)           log10(x)
 ---------------------------------------------------------------
 1.00E-100      -332.1928095      -230.2585093              -100
     0.500                -1     -0.6931471806     -0.3010299957
      2.00                +1     +0.6931471806     +0.3010299957
      2.72      +1.442695041                +1     +0.4342944819
      10.0      +3.321928095      +2.302585093                +1
 1.00E+100      +332.1928095      +230.2585093              +100

Example

See the example for log() in this chapter.

Example

// atanh(x) is defined as 0.5 * ( log(x+1) − log(−x+1).
// Rounding errors can result in different results
// for different methods.

puts("   x         atanh(x)     atanh(x) − 0.5*(log1p(x) − log1p(−x))\n"
     "--------------------------------------------------------------");
for ( double x = -0.8; x < 1.0; x += 0.4)
{
  double y = atanh(x);
  printf("%6.2f %14f %20E\n", x, y, y − 0.5*(log1p(x) − log1p(-x)) );
}

This code produces the following output:

   x          atanh(x)     atanh(x) − 0.5*(log1p(x) − log1p(−x))
---------------------------------------------------------------
 -0.80       -1.098612        -1.376937E-17
 -0.40       -0.423649        -1.843144E-18
  0.00        0.000000         0.000000E+00
  0.40        0.423649         7.589415E-19
  0.80        1.098612        -4.640385E-17

Example

double x[] = { 0, 0.7, 1.8, 1234, INFINITY };

for ( int i = 0; i < sizeof( x ) / sizeof( double ); i++ )
{
  errno = 0;
  printf( "The base 2 log of  %.1f is %.3f.\n", x[i], log2( x[i] ) );
  if ( errno == EDOM || errno == ERANGE )
    perror( __FILE__ );
}

This code produces the following output:

The base 2 log of  0.0 is -inf.
log2.c: Numerical result out of range
The base 2 log of  0.7 is -0.515.
The base 2 log of  1.8 is 0.848.
The base 2 log of  1234.0 is 10.269.
The base 2 log of  inf is inf.

Example

double x[] = { 0, 0, 0.7, 1.8, 1234, INFINITY };

x[1] = nexttoward( 0.0, 1.0 );

for ( int i = 0; i < sizeof( x ) / sizeof( double ); i++ )
{
  printf( "The exponent in the binary representation of %g is %g.\n",
          x[i], logb( x[i] ) );
  if ( errno == EDOM || errno == ERANGE )
    perror( __FILE__ );
}

This code produces the following output:

The exponent in the binary representation of 0 is -inf.
The exponent in the binary representation of 4.94066e-324 is -1074.
The exponent in the binary representation of 0.7 is -1.
The exponent in the binary representation of 1.8 is 0.
The exponent in the binary representation of 1234 is 10.
The exponent in the binary representation of inf is inf.

Example

See the example for setjmp().

Example

double t_ambient;          // Ambient temperature in Celsius.
int t_display;             // Display permits integer values.
char tempstring[128];
int saverounding = fegetround();

/* ... Read t_ambient from some thermometer somewhere ... */

fesetround(FE_TONEAREST); // Round toward nearest integer, up or down.

t_display = (int)lrint( t_ambient );
snprintf( tempstring, 128, "Current temperature: %d° C\n", t_display );

fesetround( saverounding );  // Restore rounding direction.

Example

long costnow;         // Total cost in cents.
long realcost;
double rate;          // Annual interest rate.
int period;           // Time to defray cost.

/* ... obtain the interest rate to use for calculation ... */

realcost = lround( (double)costnow * exp( rate * (double)period ));

printf( "Financed over %d years, the real cost will be $%ld.%2ld.\n",
        period, realcost/100, realcost % 100 );

Example

struct linelink { char *line;
                  struct linelink *next;
                };
struct linelink *head = NULL, *tail = NULL;

char buffer[2048];
FILE *fp_in;
/* ... 0pen input file ... */
while ( NULL != fgets(buffer, sizeof(buffer), fp_in ))
{
  if ( head == NULL ) /* Chain not yet started; add first link */
  {
    head = tail = malloc( sizeof(struct linelink));
    if ( head != NULL )
    {
      head->line = malloc( strlen( buffer  ) + 1 );
      if ( head->line != NULL )
      { strcpy( head->line, buffer); head->next = NULL; }
      else
        { fprintf( stderr, "Out of memory\n" ); return -1; }
    }
    else
      { fprintf( stderr, "Out of memory\n" ); return -1; }
  }
  else  /* Chain already started; add another link ... */

Example

size_t mbsrcat( char * restrict s1, char * restrict s2,
                mbstate_t * restrict p_s1state, size_t n )
/* mbsrcat: multibyte string restartable concatenation.
 * Appends s2 to s1, respecting final shift state of destination string,
 * indicated by *p_s1state. String s2 must start in the initial shift
 * state.
 * Returns: number of bytes written, or (size_t)-1 on encoding error.
 * Max. total length (incl. terminating null byte) is <= n;
 * stores ending state of concatenated string in *s1state.
 */
{
  int result;
  size_t i = strlen( s1 );
  size_t j = 0;

  if ( i >= n − (MB_CUR_MAX+1)) // Sanity check: room for 1 multibyte
                                // char + string terminator.
    return 0;                   // Report 0 bytes written.

  // Shift s1 down to initial state:

  if ( !mbsinit( p_s1state ))   // If not initial state, then append
  {                             // shift sequence to get initial state.
    if ( ( result = wcrtomb ( s1+i, L'\0', p_s1state )) == -1 )
      {                         // Encoding error:
        s1[i] = '\0';           // Try restoring termination.
        return (size_t)-1;      // Report error to caller.
      }
    else
      i += result;
  }
  // Copy only whole multibyte characters at a time.
  // Get length of next char w/o changing state:
  while (( result = mblen( s2+j, MB_CUR_MAX )) <= (n − ( 1 + i )) )
  {
    if ( result == 0  ) break;
    if ( result == -1 )
    {                      // Encoding error:
      s1[i] = '\0';        // Terminate now.
      return (size_t)-1;   // Report error to caller.
    }
                       // Next character fits; copy it and update state:
    strncpy( s1+i, s2+j, mbrlen( s2+j, MB_CUR_MAX, p_s1state ));
    i += result;
    j += result;
  }
  s1[i] = '\0';
  return j;
}

Example

See the example for mblen() in this chapter.

Example

// The function mbsToC16s() uses mbrtoc16() to convert a string of
// multibyte characters into a string of 16-bit characters
// (typically in UTF-16 encoding).
// Return value: the number of char16_t characters produced, or
//              -1 if an error occurred.

int mbsToC16s( const char *mbStr, char16_t *c16Str, size_t len)
{
   if( mbStr == NULL || c16Str == NULL || len == 0) // Sanity checks.
       return -1;

   mbstate_t mbstate = {0};
   char16_t c16;
   int count = 0, i = 0, rv = 0,
       nBytes = (int)strlen(mbStr)+1;

   do {
      rv = (int)mbrtoc16(&c16, mbStr+i, nBytes-i, &mbstate);
      switch( rv)
      {
        case  0:  c16Str[count] = 0; i = nBytes;  // End of string.
                  break;
        case -1:                           // Encoding error.
        case -2:  count = -1;
                  break;
        default:
          if( count < (int)len-1 )
          {
             c16Str[count++] = c16;
             if( rv > 0)  i += rv;      // rv != -3
          }
          else count = -1;
      }
   } while( count > 0 && i < nBytes);

   return count;
}

A sample function call:

int main(void)
{
   if( setlocale(LC_ALL, "en_US.utf8") == NULL)
      fputs("Unable to set the locale.\n", stderr);

    char *u8Str = u8"Grüße";
    char16_t c16Str[100];
    int nChars = 0;

    nChars = mbsToC16s( u8Str, c16Str, 100);
    if( nChars < 0)
        fputs("Error ...", stderr);
    else
    {
      printf("%d UTF-16 characters.\n", nChars);
// ...
}

Example

See the example for mbrtoc16() in this chapter.

Example

size_t mbstoupper( char *s1, char *s2, size_t n )
/* Copies the multibyte string from s2 to s1, converting all the
   characters to uppercase on the way.
   Because there are no standard functions for case-mapping in multibyte
   encodings, converts to and from the wide-character encoding (using the
   current locale setting for the LC_CTYPE category). The source string
   must begin in the initial shift state.
   Returns: the number of bytes written;
   or (size_t)-1 on an encoding error.
 */
{
  char *inptr = s2, *outptr = s1;
  wchar_t thiswc[1];
  size_t inresult, outresult;

  mbstate_t states[2], *instate = &states[0], *outstate = &states[1];

  memset( states, '\0', sizeof states );

  do
  {
    inresult = mbrtowc( thiswc, inptr, MB_CUR_MAX, instate );
    switch ( inresult )
      {
      case (size_t)-2: // The (MB_CUR_MAX) bytes at inptr do not make
                       // a complete mb character. Maybe there is a
                       // redundant sequence of shift codes. Treat the
                       //  same as an encoding error.
        *outptr = '\0';
        return (size_t)-1;

      case (size_t)-1:   // Found an invalid mb sequence at inptr:
        return inresult; // pass the error to the caller.

      case 0:         // Got a null character. Make a last null wc.
                      // The default action, with wcrtomb, does this
                      // nicely, so *no break statement* necessary here.

      default:        // Read <result> mb characters to get one wide
                      // character.
        /* Check for length limit before writing anything but a null.
           Note: Using inresult as an approximation for the output
           length.
           The actual output length could conceivably be different
           due to a different succession of state-shift sequences.
        */
        if (( outptr − s1 ) + inresult + MB_CUR_MAX > n )
        {   // i.e., if bytes written + bytes to write + termination > n,
            // then terminate now by simulating a null-character input.
          thiswc[0] = L'\0';
          inresult = 0;
        }
        inptr += inresult;
        if (( outresult = wcrtomb( outptr,
                                  (wchar_t)towupper(thiswc[0]),
                                   outstate )) == -1 )
        {                               // Encoding error on output:
          *outptr = '\0';               // Terminate and return error.
          return outresult;
        }
        else
          outptr += outresult;
      }
  } while ( inresult );               // Drop out after handling '\0'.
  return outptr - s1;
}

Example

See the example for mblen() in this chapter.

Warning

If the return value is equal to the specified maximum n, the wide-character string is not terminated with a null character!

Example

size_t result;

char mbstring[ ] = "This is originally a multibyte string.\n";
const char *mbsptr = mbstring;

wchar_t widestring[256] = { L'\0' };

mbstate_t state;
memset( &state, '\0', sizeof state );

printf( "The current locale is %s.\n", setlocale( LC_CTYPE, "" ));

result = mbsrtowcs( widestring, &mbsptr, 256, &state );
if ( result == (size_t)-1 )
{
  fputs( "Encoding error in multibyte string", stderr );
  return -1;
}
else
{
  printf( "Converted %u multibyte characters. The result:\n", result );
  printf( "%ls", widestring );
}

Example

   const char *mbptr = "Any multibyte string";
   wchar_t wcstr[10];      // A buffer for wide characters
   size_t  len;            // and its capacity.
   mbstate_t state = {0};

   if( mbsrtowcs_s( &len, wcstr, 10, &mbptr, 9, &state) != 0)
      printf("The array contains an invalid multibyte character.\n");
   else
   {
      printf("Length: %u; text: %ls\n", len, wcstr);
      printf("The remaining characters: %s\n", mbptr);
   }

The output from this code is:

Length: 9; text: Any multi
The remaining characters: byte string

Tip

The mbstowcs() function terminates the resulting wide-character string with a null wide character (L'\0') only if it has not yet written the maximum number of wide characters specified by the third argument! If the return value is the same as the specified limit, then the resulting wide string has not been terminated.

If mbstowcs() encounters an invalid multibyte character, it returns (size_t)(-1).

Example

See the example for localeconv() in this chapter.

Example

   char    mbstr[] = "Any multibyte string";
   wchar_t wcstr[10];      // A buffer for wide characters
   size_t  len;            // and the number of characters.

   if( mbstowcs_s( &len, wcstr, 10, mbstr, 9) != 0)
      printf("The array contains an invalid multibyte character.\n");
   else
      printf("Length: %u; text: %ls\n", len, wcstr);

Output:

Length: 9; text: Any multi

Example

The following example converts an array of multibyte characters into wide characters one at a time, and prints each one:

int i = 0, n = 0;
wchar_t wc;
char mbstring[256] = "This is originally a multibyte string.\n";

printf( "The current locale is %s.\n", setlocale(LC_CTYPE, "" ));

while ( (n = mbtowc( &wc, &mbstring[i], MB_CUR_MAX )) != 0 )
{
  if ( n == -1 )
  {
    fputs( "Encoding error in multibyte string", stderr );
    break;
  }
  printf( "%lc", (wint_t)wc );
  i += n;
}

Example

char *found, buffer[4096] = "";
int ch = ' ';

fgets( buffer, sizeof(buffer), stdin );

/* Replace any spaces in the string read with underscores: */
while (( found = memchr( buffer, ch, strlen(buffer) )) != NULL )
  *found = '_';

Example

long setone[5] = { 1, 3, 5, 7, 9 };
long settwo[5] = { 0, 2, 4, 6, 8 };

for ( int i = 0; i < 5; i++ )
  settwo[i] += 1;

if ( memcmp( &setone, &settwo, sizeof(settwo) ) == 0 )
  printf( "The two arrays are identical, byte for byte.\n" );

Example

typedef struct record {
  char  name[32];
  double data;
  struct record *next, *prev;
} Rec_t;

Rec_t template = { "Another fine product", -0.0, NULL, NULL };
Rec_t *tmp_new;

if (( tmp_new  = malloc( sizeof(Rec_t) )) != NULL )
  memcpy( tmp_new, &template, sizeof(Rec_t) );
  // Equivalent to
  // memcpy_s( tmp_new, sizeof(Rec_t), &template, sizeof(Rec_t) );
  // or *tmp_new = template;
else
  fprintf( stderr, "Out of memory!\n" );

Example

char a[30] = "That's not what I said." ;
    memmove( a+7, a+11, 13 );      // Move 13 bytes, 'w' through '\0'
// Or with memmove_s():
//  memmove_s( a+7, 13, a+11, 13 );
puts( a );

These lines produce the following output:

That's what I said.

Example

char str[] = "Account number: 1234567890";
char digits[] = "0123456789";

size_t pos = strcspn( str, digits);  // Position of the first digit.
// puts( memset( str+pos, 'x', 7));
// or
if( memset_s( str+pos, strlen(str)-pos, 'x', 7) == 0)
   puts(str)

These statements produce the following output:

Account number: xxxxxxx890

Example

  time_t seconds;
  struct tm sometime;

  sometime.tm_sec   = 10;
  sometime.tm_min   = 80;
  sometime.tm_hour  = 40;
  sometime.tm_mday  = 23;
  sometime.tm_mon   = 1;
  sometime.tm_year  = 105;
  sometime.tm_wday  = 11;
  sometime.tm_yday  = 111;
  sometime.tm_isdst = -1;

  seconds = mktime( &sometime );

  if ( seconds == -1 )
  {
    printf( "mktime() couldn't make sense of its input.\n" );
    return -1;
  }

  printf( "The return value, %ld, represents %s",
          (long)seconds, ctime(&seconds) );

  printf( "The structure has been adjusted as follows:\n"
          "tm_sec   == %d\n"
          "tm_min   == %d\n"
          "tm_hour  == %d\n"
          "tm_mday  == %d\n"
          "tm_mon   == %d\n"
          "tm_year  == %d\n"
          "tm_wday  == %d\n"
          "tm_yday  == %d\n"
          "tm_isdst == %d\n",

          sometime.tm_sec,
          sometime.tm_min,
          sometime.tm_hour,
          sometime.tm_mday,
          sometime.tm_mon,
          sometime.tm_year,
          sometime.tm_wday,
          sometime.tm_yday,
          sometime.tm_isdst );

  printf( "The structure now represents %s", asctime( &sometime ));
}

This program produces the following output:

The return value, 1109262010, represents Thu Feb 24 17:20:10 2005
The structure has been adjusted as follows:
tm_sec   == 10
tm_min   == 20
tm_hour  == 17
tm_mday  == 24
tm_mon   == 1
tm_year  == 105
tm_wday  == 4
tm_yday  == 54
tm_isdst == 0
The structure now represents Thu Feb 24 17:20:10 2005

Tip

There is no type-generic macro for the modf() functions.

Example

double x, integer = 0.0, fraction = 0.0;
x = 1.23;
fraction = modf( x, &integer );
printf("%10f = %f + %f\n", x , integer, fraction );

x = -1.23;
fraction = modf( x, &integer );
printf("%10f = %f + %f\n", x , integer, fraction );

The example produces the following output:

  1.230000 = 1.000000 + 0.230000
 -1.230000 = -1.000000 + -0.230000

Example

See the examples for mtx_init() and cnd_broadcast() in this chapter.

Table 18-6. Mutex types
`mutextype`	Properties of the mutex
`mtx_plain`	A plain, non-recursive mutex
`mtx_timed`	A non-recursive mutex that supports timeouts
`mtx_plain` \| `mtx_recursive`	A recursive mutex
`mtx_timed` \| `mtx_recursive`	A recursive mutex that supports timeouts

Example

mtx_t mtx;                     // A mutex.

int main()
{
   if( mtx_init( &mtx, mtx_plain) != thrd_success)
   {
      fputs( "Error initializing the mutex.\n", stderr);
      return -1;
   }
// Here on success.
// ... Threads use the mutex ...
// ... Wait for threads to end ...

   mtx_destroy(&mtx);
   return 0;
}

Example

See the example for mtx_timedlock() in this chapter.

Example

mtx_t mtx;
int func(void * thrd);                         // Thread function.

int main()
{
    thrd_t th;
    if( mtx_init(&mtx, mtx_timed) != thrd_success)
    {  fputs("Initialization error.\n", stderr); return 1; }

    mtx_lock(&mtx);                            // Lock the mutex.
    if( thrd_create(&th, func, "Thread A") != thrd_success)
    {  fputs("Thread error.\n", stderr); return 2; }

    thrd_join(th, NULL);
    mtx_destroy( &mtx);
    return 0;
}

int func(void * thrd)
{
    struct timespec ts;
    timespec_get( &ts, TIME_UTC);              // The current time;
    ts.tv_sec += 3;                            // 3 seconds from now.

    printf("%s waiting ...\n", (char*)thrd);
    int res = mtx_timedlock(&mtx, &ts);
    switch(res)
    {
        case thrd_success:
           puts("Obtained mutex\n... releasing ...");
           mtx_unlock(&mtx);  break;
        case thrd_timedout:
           puts("Timed out.");   break;
        default:
           puts("mtx_timedlock: error.");
    };
    return res;
}

This code produces the following output:

Thread A waiting ...
Timed out.

Example

#define NUM_THREADS 3

mtx_t mtx;
struct timespec duration = { .tv_nsec = 1 };      // One nanosecond.

int func(void * thrd_num)                         // Thread function.
{
   int num = *(int*)thrd_num;
   int res, count = 1;

   while( (res = mtx_trylock(&mtx)) == thrd_busy)
   {   ++count;  thrd_sleep( &duration, NULL); }

   if( res == thrd_success)
   {
     printf("Thread %d succeeded after %d attempts.\n", num, count);
     thrd_sleep( &duration, NULL);
     mtx_unlock(&mtx);
     return 0;
   }
   else return -1;
}

int main(void)
{
   struct { thrd_t th; int id; } th_arr[NUM_THREADS];

   if( mtx_init(&mtx, mtx_plain) != thrd_success)
      return 1;

   // Create threads:
   for( int i = 0; i < NUM_THREADS; ++i)
   {
      th_arr[i].id = i;
      if( thrd_create( &th_arr[i].th, func, &th_arr[i].id) !=
          thrd_success)
          return -2;
    }
    // Wait for threads to finish:
    for( int i = 0; i < NUM_THREADS; ++i)
        thrd_join( th_arr[i].th, NULL);

    mtx_destroy( &mtx);
    return 0;
}

Possible output of this program:

Thread 0 succeeded after 1 attempts.
Thread 2 succeeded after 2 attempts.
Thread 1 succeeded after 4 attempts.

Example

See the example for mtx_trylock() in this chapter.

Example

if ( fesetround( FE_TOWARDZERO) == 0)
  printf("The current rounding mode is \"round toward 0.\"\n");
else
  printf("The rounding mode is unchanged.\n");

printf("nearbyint(1.9) = %4.1f    nearbyint(-1.9) = %4.1f\n",
       nearbyint(1.9), nearbyint(-1.9) );

printf("round(1.9) = %4.1f        round(-1.9) = %4.1f\n",
        round(1.9), round(-1.9) );

This code produces the following output:

The current rounding mode is "round toward 0."
nearbyint(1.9) =  1.0    nearbyint(-1.9) = -1.0
round(1.9) =  2.0        round(-1.9) = -2.0

Example

double x = nextafter( 0.0, 1.0 );
printf("The smallest positive number "
       "with the type double: %E\n", x);

This code produces output like the following:

The smallest positive number with the type double: 4.940656E-324

Example

float x = nexttowardf( 0.0F, -1E-100L );
printf("The greatest negative floating-point number \n"
       "(i.e., the closest to zero) with type float: %E\n", x);

This code produces output like the following:

The greatest negative floating-point number
(i.e., the closest to zero) with type float: -1.401298E-45

Example

#define MSGLEN_MAX 256
FILE *fp;
char msgbuf[MSGLEN_MAX] = "";

if (( fp = fopen( "nonexistentfile", "r" )) == NULL )
{
  snprintf( msgbuf, MSGLEN_MAX, "%s, function %s, file %s, line %d",
            argv[0], __func__, __FILE__, __LINE__ );
  perror( msgbuf );
  return errno;
}

Assuming that there is no file available named nonexistentfile, this code results in output like the following on stderr:

./perror, function main, file perror.c, line 18: No such file
or directory

Example

See the example for cosh() in this chapter.

Conversion specification syntax

For a general overview of data output with printf(), see “Formatted Output”. This section describes the syntax of conversion specifications in the printf() format string in detail. The conversion specifications have the following syntax:

%[flags][field width][.precision][length modifier]specifier

The flags consist of one or more of the characters +, ' ' (space), -, 0, or #. Their meanings are as follows:

+

Add a plus sign before positive numbers.

' '

Add a space before positive numbers (not applicable in conjunction with +).

-

Align the output with the left end of the field.

0

Pad the field with leading zeros to the left of the numeric output (not applicable in conjunction with -). Ignored for integer types if precision is specified.

#

Use alternative conversion rules for the following conversion specifiers:

A, a, E, e, F, f, G, g: Format floating-point numbers with a decimal point, even if no digits follow.
G, g: Do not truncate trailing zeros.
X, x, o: Format nonzero hexadecimal integers with the 0X or 0x prefix; format octal integers with the 0 prefix.

The optional field width is a positive integer that specifies the minimum number of characters that the given data item occupies in the output string. If the flags include a minus sign, then the converted argument value is aligned left in the field; otherwise, it is aligned right. The remaining field width is padded with spaces (or zeros, if the flags include 0). If the converted data item is longer than the specified field width, it is inserted in the output string in its entirety.

If an asterisk (*) appears in place of the field width, then the argument to be converted for output must be preceded by an additional argument with the type int, which indicates the field width for the converted output.

For the conversion specifiers f, F, e, E, a, and A, precision specifies the number of decimal places to present. For the conversion specifier g, precision indicates the number of significant digits. The result is rounded. The default value for precision is 6.

For integers—that is, the conversion specifiers u, d, i, x, and o—precision specifies a minimum number of digits to present. The converted value is padded with leading zeros if necessary. The default value for precision in this case is 1. If you convert a zero integer value with zero precision, the result is no characters.

For the conversion specifier s, indicating a string argument, precision specifies the maximum length of the string to be inserted in the output.

If an asterisk (*) appears in place of a precision value, then the argument to be converted for output must be preceded by an additional argument with the type int, which indicates the precision for the converted output. If asterisks appear both for field width and for precision, then the argument to be converted must be preceded by two additional int arguments, the first for field width and the second for precision.

The length modifier qualifies the conversion specifier to indicate the corresponding argument’s type more specifically. Each length modifier value is applicable only to certain conversion specifier values. If they are mismatched, the function’s behavior is undefined. The permissible length modifier values and their meaning for the appropriate conversion specifiers are listed in Table 18-7.

Table 18-7. printf() conversion specifier modifiers
Modifier	With conversion specifier	Corresponding argument’s type
`hh`	`d`, `i`, `o`, `u`, `x`, or `X`	`signed char` or `unsigned char`
`hh`	`n`	`signed char *`
`h`	`d`, `i`, `o`, `u`, `x`, or `X`	`short int` or `unsigned short int`
`h`	`n`	`short int *`
`l` (ell)	`d`, `i`, `o`, `u`, `x`, or `X`	`long int` or `unsigned long int`
`l` (ell)	`c`	`wint_t`
`l` (ell)	`n`	`long int *`
`l` (ell)	s	`wchar_t *`
`l` (ell)	`a`, `A`, `e`, `E`, `f`, `F`, `g`, or `G`	(The modifier is permitted, but has no effect)
`ll` (two ells)	`d`, `i`, `o`, `u`, `x`, or `X`	`long long` or `unsigned long long`
`ll` (two ells)	`n`	`long long *`
`j`	`d`, `i`, `o`, `u`, `x`, or `X`	`intmax_t` or `uintmax_t`
`j`	`n`	`intmax_t *`
`z`	`d`, `i`, `o`, `u`, `x`, or `X`	`size_t` or the corresponding signed integer type
`z`	`n`	`size_t *` or a pointer to the corresponding signed integer type
`t`	`d`, `i`, `o`, `u`, `x`, or `X`	`ptrdiff`_`t` or the corresponding unsigned integer type
`t`	`n`	`ptrdiff`_`t *` or a pointer to the corresponding unsigned integer type
`L`	`a`, `A`, `e`, `E`, `f`, `F`, `g`, or `G`	`long double`

The conversion specifier indicates the type of the argument and how it is to be converted. The corresponding function argument must have a compatible type; otherwise, the behavior of printf() is undefined. The conversion specifier values are listed in Table 18-8.

Table 18-8. printf() conversion specifiers
Conversion specifier	Argument type	Output notation
`d`, `i`	`int`	Decimal
`u`	`unsigned int`	Decimal
`o`	`unsigned int`	Octal
`x`, `X`	`unsigned int`	Hexadecimal
`f`, `F`	`float` or `double`	Floating decimal point
`e`, `E`	`float` or `double`	Exponential notation
`g`, `G`	`float` or `double`	Floating decimal point or exponential notation, whichever is shorter
`a`, `A`	`float` or `double`	Hexadecimal exponential notation
`c`	`char` or `int`	Single character
`s`	char *	The string addressed by the pointer argument
`n`	int *	No output; instead, `printf()` stores the number of characters in the output string so far in the variable addressed by the argument
`p`	Any pointer type	The pointer value, in hexadecimal notation
`%`	None	A percent sign (`%`)

The exact meaning of the a and A conversion specifiers, introduced in C99, is somewhat complicated. They convert a floating-point argument into an exponential notation in which the significant digits are hexadecimal, preceded by the 0x (or 0X) prefix, and with one digit to the left of the decimal point character. The exponential multiplier, separated from the significant digits by a p (or P), is represented as a decimal exponent to base FLT_RADIX. The symbolic constant FLT_RADIX, defined in float.h, indicates the base of the floating-point environment’s exponent representation; this is usually 2, for binary exponent representation. Here is an example using the a conversion specifier:

double pi = 3.1415926;
double bignumber = 8 * 8 * 8 * pi * pi * pi;
printf("512 times pi cubed equals %.2e, or %.2a.\n",
                                  bignumber, bignumber);

This printf() call produces the following output:

512 times pi cubed equals 1.59e+04, or 0x1.f0p+13.

The first representation shown here, produced by the e conversion specifier, reads “one point five nine times ten to the fourth power,” and the second, produced by a, as “hexadecimal one point F zero times two to the (decimal) thirteenth power.”

For floating-point arguments, and for the x or X conversion specifiers, the case of the conversion specifier determines the case of any letters in the resulting output: the x (or X) in the hexadecimal prefix; the hexadecimal digits greater than 9; the e (or E) in exponential notation; infinity (or INFINITY) and nan (or NAN); and p (or P) in hexadecimal exponential notation.

In Chapter 2, we described the types with specific characteristics defined in stdint.h, such as intmax_t for the given implementation’s largest integer type, int_fast32_t for its fastest integer type of at least 32 bits, and the like (see Table 2-5). The header file stdint.h also defines macros for the corresponding conversion specifiers for use in the printf() functions. These conversion specifier macros are listed in Table 18-9.

Table 18-9. Conversion specifier macros for integer types defined in stdint.h
Type	Meaning	printf() conversion specifiers
`intN_t` `uintN_t`	An integer type whose width is exactly `N` bits	`PRId``N`, `PRIi``N` `PRIo``N`, `PRIu``N`, `PRIx``N`, `PRIX``N`
`int_leastN_t` `uint_leastN_t`	An integer type whose width is at least `N` bits	`PRIdLEAST``N`, `PRIiLEAST``N` `PRIoLEAST``N`, `PRIuLEAST``N`, `PRIxLEAST``N`, `PRIXLEAST``N`
`int_fastN_t` `uint_fastN_t`	The fastest type to process whose width is at least `N` bits	`PRIdFAST``N`, `PRIiFAST``N` `PRIoFAST``N`, `PRIuFAST``N`, `PRIxFAST``N`, `PRIXFAST``N`
`intmax_t` `uintmax_t`	The widest integer type implemented	`PRIdMAX`, `PRIiMAX` `PRIoMAX`, `PRIuMAX`, `PRIxMAX`, `PRIXMAX`
`intptr_t` `uintptr_t`	An integer type wide enough to store the value of a pointer	`PRIdPTR`, `PRIiPTR` `PRIoPTR`, `PRIuPTR`, `PRIxPTR`, `PRIXPTR`

The macros in Table 18-9 expand to string literals. Therefore, when you use one in a printf() format string, you must close the quotation marks surrounding the format string on either side of the macro. Here is an example:

int_fast16_t counter = 1001;
while ( --counter )
  printf( "Only %" PRIiFAST16 " nights to go.\n", counter );

The preprocessor expands the macro and concatenates the resulting string literal with the adjacent ones on either side of it.

Example

The following example illustrates the use of the %n conversion specification to count the characters in the output string:

void print_line( double x)
{
  int n1, n2;
  printf("x = %5.2f   exp(x) = %n%10.5f%n\n", x, &n1, exp(x), &n2);
  assert( n2-n1 <= 10);     // Did printf() stretch the field width?
}

int main()
{
  print_line( 11.22);
  return 0;
}

The code produces the following output:

x = 11.22   exp(x) = 74607.77476
printf_ex: printf_ex.c:20: print_line: Assertion `n2-n1 <= 10' failed.
Aborted

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
char *res = NULL;

// ...
  printf_s("Result: %s\n", res);   // The current constraint handler
                                   // will be called if res == NULL.

Example

This is a simple search-and-replace filter to eliminate backtick characters in text files:

int c;
FILE *fp;

if (( fp = fopen( "textfile", "r+" )) == NULL )
{
  fprintf( stderr, "Couldn't open input file.\n" );
  exit(-1);
}

while (( c = getc( fp )) != EOF ) // Read a character until EOF
{
  if ( c == '`' )              // If it's a backtick ...
  {
    fseek( fp, -1, SEEK_CUR ); // back up to the place it was read from,
    putc( '\'', fp );          // and replace it with a single-quote
    fflush( fp );              // character.
  }
}
fclose( fp );

Example

The following example code reads the beginning of a file repetitively, and reports its progress on stdout.

long count; const long CYCLES = 5000;
FILE *fp = fopen( "infile.txt", "r" );
char readback[1024];

for (count = 0; count <= CYCLES; ++count)
{
 /* Start output with '\r' to reuse same screen line. */
  printf( "\rPerformed %li file reads. ", count );

  rewind( fp );
  fgets( readback, 1024, fp );

/* Scroll a new screen line every hundred cycles. */
  if (count % 100 != 0) continue;
  putchar( '\n' );
}
puts( "Done." );

Example

See the examples for qsort(), setjmp(), and signal() in this chapter.

Example

See the examples for getwc() and fgetwc() in this chapter.

Example

See the example for getwchar() in this chapter.

Example

int strptrcmp( const void *sp1, const void *sp2 );

int main()
{
  char *words[] = { "Then",   "he",   "shouted", "What", "I",
                    "didn't", "hear", "what",    "you",  "said" };

  int n = sizeof(words) / sizeof(char *);

  qsort( words, n, sizeof(char *), strptrcmp );

  for ( int j = 0 ; j < n ; j++ )
    puts( words[j] );
}

int strptrcmp( const void *sp1, const void *sp2 )
// Compare two strings by reference.
{
  // qsort() passes a pointer to the pointer:
  // dereference it to pass a char * to strcmp.
  const char * s1 = *(char **)sp1;
  const char * s2 = *(char **)sp2;
  return strcmp( s1, s2 );
}

This program sorts the words in the array in alphabetical order. As the output shows, any capital letter is less than any lowercase letter, and "he" is less than "hear":

I
Then
What
didn't
he
hear
said
shouted
what
you

See also the example for bsearch() in this chapter, as well as Example 4-1.

Example

See the example for bsearch_s() in this chapter.

Example

See the example for at_quick_exit().

Tip

Macros for values of the argument sig are defined in the standard header signal.h, and are described under signal() in this chapter.

Example

See the example for signal() in this chapter.

Example

printf( "Think of a number between one and twenty.\n"
        "Press Enter when you're ready." );
getchar();

srand( (unsigned)time( NULL ) );

for ( int i = 0; i < 3; i++ )       // We get three guesses.
{
  printf( "Is it %u? (y or n) ", 1 + rand() % 20 );
  if ( tolower( getchar() ) == 'y' )
  {
    printf( "Ha! I knew it!\n" );
    exit( 0 );
  }
  getchar();                        // Discard newline character.
}
printf( "I give up.\n" );

Example

typedef struct { int len;
                 float array[];
               } DynArray_t;

DynArray_t *daPtr = malloc( sizeof(DynArray_t) + 10*sizeof(float) );
if ( daPtr == NULL ) return -1;

daPtr->len = 10;

for ( int i = 0; i < daPtr->len; ++i )
  daPtr->array[i] = 1.0F/(i+1);
/* daPtr->array[10] = 0.1F             // Invalid array index! */

DynArray_t *daResizePtr = realloc( daPtr,
                               sizeof(DynArray_t) + 11*sizeof(float));
if ( daResizePtr != NULL )
{
  daPtr = daResizePtr ;
  daPtr->len = 11;
  daPtr->array[10] = 0.1F / 12;        // OK now.
}
else
  /* We'll just have to get along with the array of 10 floats. */

Example

double apples, people, share, left;
printf( "\nHow many people? ");
scanf( "%lf", &people );
printf( "\nHow many apples? ");
scanf( "%lf", &apples );

left = remainder( apples, people );    // left may be negative!
share = ( apples − left ) / people;

printf( "If there are %.1lf of us and %.1lf apples, "
        "each of us gets %.1lf of %s, with %.1lf left over.\n",
        people, apples, share, ( share < 1 ) ? "one" : "them", left );

Example

char fname_tmp[L_tmpnam] = "";
FILE *fp;
int result;

tmpnam( fname_tmp );
fp = fopen( fname_tmp, "w+" );

/* ... write something in the file, edit it ... */

fclose( fp );

result = rename( fname_tmp, "finished.txt" );
if ( result )          // Delete previous "finished.txt" and try again.
{
  remove( "finished.txt" );
  result = rename( fname_tmp, "finished.txt" );
  if ( result )                   // Give up and log the error.
    fprintf( stderr, "Error %d on trying to rename output file\n",
                                                         errno );
}

Example

double apples = 0.0, people = 0.0, left = 0.0, share = 0.0;
int quotient = 0;

printf( "\nHow many people? ");
scanf( "%lf", &people );

printf( "\nHow many apples? ");
scanf( "%lf", &apples );

share = nearbyint( apples / people );
left = remquo( apples, people, &quotient );

printf( "If there are %.2lf of us and %.2lf apples, "
        "each of us gets %.2lf apple%s, with %.2lf left over.\n",
        people, apples, share, ( share == 1 ) ? "" : "s", left );
printf( "remquo() stored %d as the quotient "
        " of the division (modulo 8).\n", quotient );

printf( "Test: share modulo 8 − quotient = %d\n",
        (int) share % 8 − quotient );

Example

See the example for remove() in this chapter.

Example

This example prints the contents of a file twice, converting each character to lowercase the first time through, and to uppercase the second time:

FILE *fp; int c;

if (( fp = fopen( argv[1], "r" )) == NULL )
  fprintf( stderr, "Failed to open file %s\n", argv[1] );
else
{
  puts( "Contents of the file in lowercase:" );
  while (( c = fgetc( fp )) != EOF )
    putchar( tolower( c ));

  rewind( fp );

  puts( "Same again in uppercase:" );
  while (( c = fgetc( fp )) != EOF )
    putchar( toupper( c ));

  fclose( fp );
}

Example

struct round_modes { int id; char *str; }  arrModes[ ] =
{
  #ifdef FE_TONEAREST
   { FE_TONEAREST,
     "FE_TONEAREST: round to nearest representable value" },
  #endif
  #ifdef FE_DOWNWARD
   { FE_DOWNWARD, "FE_DOWNWARD: round toward -Inf" },
  #endif
  #ifdef FE_UPWARD
   { FE_UPWARD, "FE_UPWARD: round toward +Inf" },
  #endif
  #ifdef FE_TOWARDZERO
   { FE_TOWARDZERO, "FE_TOWARDZERO: round toward 0" }
  #endif
};

int nModes = sizeof( arrModes) / sizeof(*arrModes);

#pragma STDC FENV_ACCESS ON

for ( int i = 0; i < nModes; ++i)
{
  if ( fesetround( arrModes[i].id) != 0)
    break;
  printf( "Rounding mode: %s\n", arrModes[i].str );

  printf( "rint(1.4)  = %4.1f    rint(1.5)  = %4.1f\n",
          rint(1.4), rint(1.5) );
  printf( "rint(-1.4) = %4.1f    rint(-1.5) = %4.1f\n",
          rint(-1.4), rint(-1.5) );
}

If the implementation supports all four rounding modes, this code produces the following output:

Rounding mode: FE_TONEAREST: round to nearest representable value
rint(1.4)  =  1.0    rint(1.5)  =  2.0
rint(-1.4) = -1.0    rint(-1.5) = -2.0
Rounding mode: FE_DOWNWARD: round toward -Inf
rint(1.4)  =  1.0    rint(1.5)  =  1.0
rint(-1.4) = -2.0    rint(-1.5) = -2.0
Rounding mode: FE_UPWARD: round toward +Inf
rint(1.4)  =  2.0    rint(1.5)  =  2.0
rint(-1.4) = -1.0    rint(-1.5) = -1.0
Rounding mode: FE_TOWARDZERO: round toward 0
rint(1.4)  =  1.0    rint(1.5)  =  1.0
rint(-1.4) = -1.0    rint(-1.5) = -1.0

Example

See the example for nearbyint() in this chapter.

Example

See the example for feholdexcept() in this chapter.

Conversion specification syntax

For a general overview of data conversion with scanf(), see “Formatted Input”. This section describes the syntax of conversion specifications in the scanf() format string in detail. The conversion specifications have the following syntax:

%[*][field width][length modifier]specifier

Before processing each conversion specification in the format string, scanf() skips over any whitespace characters in the input stream (except with the conversion specifiers c and [], which we will describe in a moment). For each conversion specification, scanf() reads one or more characters from the input stream. As soon as scanf() reads a character that cannot be interpreted under the current conversion specification, reading is interrupted, as if the first character after the data to be converted had not been read. Then scanf() converts the characters that belong to the field, and assigns the result to the variable addressed by the corresponding pointer argument.

If a conversion specification contains an asterisk after the percent sign (%*...), then the result of the conversion is not assigned to a variable but simply discarded.

The optional field width is a positive integer that specifies the maximum number of characters to read and convert for the given conversion specification.

Table 18-10. scanf() conversion specifier modifiers
Modifier	With conversion specifier	Corresponding argument’s type
`hh`	`d`, `i`, `o`, `u`, `x`, `X`, or `n`	`signed char ` or `unsigned char `
`h`	`d`, `i`, `o`, `u`, `x`, `X`, or `n`	`short int ` or `unsigned short int `
`l` (ell)	`d`, `i`, `o`, `u`, `x`, `X`, or `n`	`long int ` or `unsigned long int `
`l` (ell)	`c`, `s`, or `[`...`]`	`wchar_t *`; conversion as by `mbrtowc()`
`l` (ell)	`a`, `A`, `e`, `E`, `f`, `F`, `g`, or `G`	double *
`ll` (two ells)	`d`, `i`, `o`, `u`, `x`, `X`, or `n`	`long long ` or `unsigned long long `
`j`	`d`, `i`, `o`, `u`, `x`, `X`, or `n`	`intmax_t ` or `uintmax_t `
`z`	`d`, `i`, `o`, `u`, `x`, `X`, or `n`	`size_t *` or a pointer to the corresponding signed integer type
`t`	`d`, `i`, `o`, `u`, `x`, `X`, or `n`	`ptrdiff_t *` or a pointer to the corresponding unsigned integer type
`L`	`a`, `A`, `e`, `E`, `f`, `F`, `g`, or `G`	long double *

The conversion specifier indicates the type of the argument and how the input characters are to be interpreted. The corresponding function argument must have a compatible type; otherwise, the behavior of scanf() is undefined. The conversion specifier values are listed in Table 18-11.

Table 18-11. scanf() conversion specifiers
Conversion specifier	Argument type	Input notation
`d`	`signed int *`	Decimal with optional sign
`i`	`signed int *`	Decimal, octal, or hexadecimal, with optional sign
`u`	`unsigned int *`	Decimal with optional sign
`o`	`unsigned int *`	Octal with optional sign
`x`	`unsigned int *`	Hexadecimal with optional sign and/or `0x` (or `0X`) prefix
`a`, `e`, `f`, or `g`	`float *`	Floating-point
`c`	`char ` or `int `	One character, or several if a field width greater than one is specified
`s`	`char *`	Consecutive non-whitespace characters
`[``scanset``]`	`char *`	Consecutive characters from the specified set
`n`	`int *`	No input read; instead, `scanf()` stores the number of characters read from input so far in the variable addressed by the argument
`p`	`void *`	The system’s notation for a pointer value; converts inversely as `printf()`
`%`	None	A single percent sign (`%`); no value stored

For a description of the character sequences that are interpreted as floating-point numbers, including decimal and hexadecimal exponential notation, see “Floating-Point Constants”.

If you use the conversion specifier c without a field width, it matches one character. If you specify a field width, as in the conversion specification %7c, then scanf() reads the specified number of characters, including whitespace characters, and assigns them to successive elements of an array of char addressed by the corresponding pointer argument, but does not append a terminating null character. It is up to you to make sure that the argument points to the first element of an array of sufficient size to accommodate the number of characters indicated by the field width.

If you use the conversion specifier c together with the length modifier l, then scanf() reads one or more bytes (according to the specified field width, if any), converting them as it goes from multibyte characters to wide characters in the same way as successive calls to the mbrtowc() function would, starting with an mbstate_t object corresponding to the initial parsing state. If you specify a field width, scanf() reads the specified number of bytes, and assigns the corresponding wide characters to successive elements of an array of wchar_t addressed by the corresponding pointer argument, but does not append a terminating null wide character ((L'\0')). It is up to you to make sure that the argument points to the first element of an array of sufficient size to accommodate the number of wide characters stored.

The conversion specifier s is similar to c, with these exceptions:

scanf() with an s specifier stops reading at the first whitespace character, or when it has read the number of bytes indicated by the field length, if specified.
scanf() with an s specifier appends a null character (or wide character, if the l modifier is present) to the sequence of characters (or wide characters) stored. The pointer argument must point to the first element of an array that is large enough to accommodate the characters read plus the null character.

The conversion specifier [...] is similar to s, with the following exceptions: rather than matching any sequence of non-whitespace characters, it matches any sequence of the characters in the set that appear between the square brackets, called the scanset. (The scanset may or may not include whitespace characters.) If the first character after the opening bracket is a caret (^), then it is not a member of the scanset but inverts the meaning of the set of characters that follows; the conversion specifier matches any sequence of the characters that do not appear in the list that follows the caret.

If the first character after the opening bracket (or after the opening bracket and an initial caret) of a [...] specifier is a right bracket (]), then that right bracket is interpreted as a member of the character list that defines the scanset, not as the closing delimiter. If the characters between the brackets (or between the initial caret and the closing bracket) include a hyphen (-) that is neither in the first nor the last position, then it is left up to the given implementation to define whether scanf() interprets the hyphen in a special way—for example, as indicating a range of characters. For example, the conversion specifier %[0-9] may match any sequence of digits, or any sequence of the characters 0, -, and 9—or the implementation may define the hyphen in some other way.

The scanf() function stops reading the input stream in whichever of the following events occurs first:

The entire format string has been processed.
A matching failure: the first non-whitespace character in an input field did not match the conversion specification, or a character in the input did not match the corresponding position in the format string.
An input failure: no input could be read from the input stream, or an encoding error occurred.

Any non-whitespace character in the format string that is not part of a conversion specification is processed by reading a character from the input stream, and testing for a literal match. If the characters do not match, scanf() returns, leaving the input stream as if the mismatched character had not been read. A whitespace character in the format string matches any sequence of whitespace characters in the input stream, including an empty string.

The scanf() function returns the number of data items assigned to variables, not counting assignments due to %n conversion specifications. If an input failure occurs before any input item can be converted, scanf() returns EOF.

Example

double x, y;
char operation[16] = "";
scanf("%15s%lf%*[^0123456789]%lf", operation, &x, &y);

The format string in this scanf() call contains four conversion specifications. Let us assume that a user enters the following sequence of characters when this call occurs:

Divide 1.5e3 by 52.25\n

For the first conversion specification, %15s, scanf() reads each character up to the first space, and hence stores the string "Divide", terminated by a null character, in the array operation. After the space, the sequence 1.5e3 matches the conversion specification %lf, and scanf() assigns the value 1500.0 to the double variable x. After the next space, each of the characters 'b', 'y', and ' ' (the space) is in the very large scanset of the conversion specification %*[^01234567890]; the first character that does not match is the digit character '5'. Because the conversion specification contains the asterisk, scanf() discards the characters read, then reads to the next whitespace character, '\n', for the conversion specification %lf, and assigns the value 52.25 to the variable y.

For another example, see fscanf() in this chapter (fscanf() reads a specified file rather than stdin, but is otherwise similar to scanf()).

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
// ...

  char article[64] = "";
  int quantity = 0;
  printf("Enter article name and quantity: ");
  if( scanf_s("%s %d", article, sizeof(article), &quantity) < 2)
     fputs("Invalid entry.\n", stderr);
  else
  {   /* Process input.    */

Example

// Use a custom handler:
void myConstraintHandler(const char* msg, void * ptr, errno_t error)
{
   printf("A runtime constraint violation "
          "occurred: \n%s; ", msg);
   printf("error code: %d\n", error);  fflush(stdout);
   exit(error);
}

void func( const char *str)
{
    constraint_handler_t prevHandler =
               set_constraint_handler_s(myConstraintHandler);
    printf_s("The argument: %s\n", str);   // Error if str
                                           // is a null pointer.
    int len = strlen(str);
    char str2[len];
    strcpy_s( str2, len, str);    // Error: str2 is one byte too short.
    // . . .
    set_constraint_handler_s(prevHandler);
}

For example, the function call func("Hi!"); produces the following output:

The argument: Hi!
A runtime constraint violation occurred:
Range error; error code: 34

Example

FILE *fp = tmpfile();
unsigned char *iobuffer = malloc( BUFSIZ );
if ( iobuffer != NULL )
{
  setbuf( fp, iobuffer );     // Make sure temporary file is buffered.
}
/* ... now write and read the temporary file as needed ... */

Example

This example shows the complete contents of two source files to illustrate how setjmp() and longjmp() allow you to escape from a function call.

#include <stdlib.h>
#include <stdio.h>
#include <setjmp.h>
#include <errno.h>

double calculate1( double x);      // Functions defined
double calculate2( double x);      // in calculate.c.

jmp_buf jmp_dest;                  // Destination for longjmp()

int main()
{
  double x = 0, y1, y2;
  int n = 0;

  puts("--- Demonstrating non-local jumps ---\n");

  switch( setjmp( jmp_dest))   // Jump to here for error handling
  {
  case 0:                      // The original setjmp() call
    break;
  case EDOM:                   // Arrived via longjmp() call with EDOM
    puts("Domain error. "
         "Negative numbers are not permitted.");
    break;
  case ERANGE:                 // Arrived via longjmp() call with ERANGE
    puts("Range error. "
         "The number you entered is too big.");
    break;
  default:                     // We should never arrive here.
    puts("Unknown error.");
    exit( EXIT_FAILURE );
  }

  printf("Enter a number: ");
  do
  {
    if ( (n = scanf("%lf", &x)) < 0)      // Read in a number.
       exit( EXIT_FAILURE );              // Read end of file.
    while ( getchar() != '\n')            // Clear the input buffer.
      ;
    if ( n == 0 )
       printf("Invalid entry. Try again: ");
  }while ( n == 0 );

  y1 = calculate1(x);
  y2 = calculate2(x);

  printf("\nResult of Calculation 1: %G\n", y1);
  printf(  "Result of Calculation 2: %G\n", y2);

  return 0;
}

// calculate.c: Perform some calculations.
// Functions: calculate1(), calculate2().
#include <math.h>
#include <setjmp.h>
#include <errno.h>

extern jmp_buf jmp_dest;             // Destination for longjmp()

double calculate1( double x)
{
  if ( x < 0)
    longjmp( jmp_dest, EDOM);        // Domain error
  else
    return sqrt(x);
}

double calculate2( double x)
{
  double y = exp(x);
  if ( y == HUGE_VAL)
    longjmp( jmp_dest, ERANGE);      // Range error
  else
    return y;
}

Example

#define MAX_STRING 80

char name[MAX_STRING];
char locale[MAX_STRING];
char *newlocale;
int i;

printf( "Who are you? " );
fgets( name, sizeof(name), stdin );

printf( "What is your locale? " );
fgets( locale, sizeof(locale), stdin );

name[ strlen(name) − 1 ] = '\0';       // Chomp off the newlines.
locale[ strlen(locale) − 1 ] = '\0';

newlocale = setlocale( LC_CTYPE, locale );
if ( newlocale == NULL )
  printf( "Sorry, couldn't change the locale to %s.\n"
          "The current locale is %s. ",
          locale, setlocale( LC_CTYPE, NULL ));
else
  printf( "The new locale is %s. ", newlocale );

name[0] = toupper( name[0] );  // Force the first letter to uppercase.

i = 1;
if ( isupper( name[i] ) )      // Is the second letter also uppercase?
  {
    while ( name[i] != '\0' )  // If so, force all the rest to lowercase.
      {
        name[i] = tolower( name[i] );
        ++i;
      }
  }
printf( "Hello there, %s!\n", name );

This program produces output like the following, if the first setlocale() call is successful:

Who are you? sÖrEn
What is your locale? de_DE
The new locale is de_DE. Hello there, Sören!

In the locale "de_DE", the isupper() function recognized the second letter of sÖrEn as uppercase, and so the Ö and E were changed to lowercase.

If the first setlocale() call fails, the output may look like this:

Who are you? FRÉDÉRIQUE
What is your locale? fr_CA
Sorry, couldn't change the locale to fr_CA.
The current locale is C. Hello there, FrÉdÉrique!

In the locale "C", the isupper() function recognized the R as uppercase, but the tolower() function was unable to convert the accented uppercase É.

Example

#define MAX_LINE 4096
FILE *fp_linewise = fopen( "output.txt", "a+" );
unsigned char *iobuffer = malloc( MAX_LINE );
if ( iobuffer != NULL )
{ // Buffer output up to each '\n'.
  if ( setvbuf( fp_linewise, iobuffer, _IOLBF, MAX_LINE ))
    fprintf( stderr, "setvbuf() failed; "
                     "unable to set line-buffering.\n" ),
    exit( -2 );
}
else
  fprintf( stderr,"malloc() failed; no point in calling setvbuf().\n"),
  exit( -1 );

Example

# include <stdio.h>
# include <stdlib.h>
# include <stdint.h>         // Defines SIG_ATOMIC_MAX
# include <signal.h>

void sigint_handler(int sig);
volatile sig_atomic_t i;     // A counter accessed by main and the
                             // handler.

int main()
{
  if ( signal( SIGINT, sigint_handler ) == SIG_ERR )
  {
    perror("Failed to install SIGINT handler");
    exit(3);
  }

   while (1)
  {
    puts( "Press Ctrl+C to interrupt me.");
    for ( i = 0 ; i < SIG_ATOMIC_MAX ; i++ )
      if ( i % 100000 == 0)
      {
        printf( "\r%d ", i / 100000 );
        fflush( stdout );
      }
    raise( SIGINT );   // Simulate a Ctrl+C in case the user didn't
                       // type it.
  }
  return 0;
}

void sigint_handler( int sig )
{
  int c = 0;

  if ( sig != SIGINT ) exit( 1 );

  signal( SIGINT, SIG_IGN );  // Ignore a second Ctrl+C

  puts( "\nThis is the function sigint_handler()."
         "\nDo you want to exit the program now? [y/n]");
  while (( c = tolower( getchar( ) )) != 'y' && c != 'n' && c != EOF )
    ;

  if ( c != 'n' )
    exit(0);
  else
    i = 0;                            // Reset timer
  signal( SIGINT, sigint_handler );   // Reinstall this handler.

  /* No return value; just fall off the end of the function. */
}

Example

double x[ ] = { -0.0,  187.234,  sqrt( -1.0 ),  1.0 / -0.0 };

for ( int i = 0 ; i < ( sizeof(x) / sizeof(double)) ; i++ )
  printf( "x[%d] equals %lF, and is%s negative.\n",
          i, x[i], signbit( x[i] ) ? "" : " not" );

The behavior of this example depends on whether the compiler supports negative zero values in floating-point constants, and whether the undefined arithmetic operations in the array initialization cause fatal exceptions. Compiled with GCC 4.9.2 and the GNU C library, this code produces the following output:

x[0] equals -0.000000, and is negative.
x[1] equals 187.234000, and is not negative.
x[2] equals NAN, and is negative.
x[3] equals -INF, and is negative.

See also the example for isunordered() in this chapter.

Example

#define DEG_PER_RAD ( 180.0 / PI )

const double PI = 4.0 * atan( 1.0 );
double a[4];

printf( "\nEnter an acute angle measure, in degrees: " );

if ( scanf( "%lf", a ) < 1 ||  ( a[0] <= 0 || a[0] >= 90 ) )
  printf( "\nThat's not an acute angle.\n" ), exit( 1 );
else
{
  a[1] = a[0] + 90 ;
  a[2] = 180 − a[0] ;
  a[3] = 225 + a[0] ;
  for ( int i = 0 ; i < 4 ; i ++ )
    printf( "The sine of %4.2lf degrees is %6.4lf.\n",
            a[i], sin( a[i] / DEG_PER_RAD ) );
}

Example

// A chain hanging from two points forms a curve called a catenary.
// A catenary is a segment of the graph of the function
// cosh(k*x)/k, for some constant k.
// The length along the catenary over a certain span, bounded by the
// two vertical lines at x=a and x=b, is equal to
// sinh(k*b)/k − sinh(k*a)/k.

double x, k;
puts("Catenary f(x) = cosh(k*x)/k\n"
     "Length along the catenary from a to b: "
     "sinh(k*b)/k − sinh(k*a)/k)\n");

puts(
"           f(-1.0)   f(0.0)   f(1.0)   f(2.0)   Length(-1.0 to 2.0)\n"
"-------------------------------------------------------------------");
for ( k = 0.5; k < 5; k *= 2)
{
  printf("k = %.1f: ", k);
  for (  x = -1.0; x < 2.1; x += 1.0)
    printf("%8.2f ", cosh(k*x)/k );

  printf("  %12.2f\n", (sinh(2*k) − sinh(−1*k))/ k);
}

This code produces the following output:

Catenary f(x) = cosh(k*x)/k
Length along the catenary from a to b:  sinh(k*b)/k − sinh(k*a)/k)

           f(-1.0)   f(0.0)   f(1.0)   f(2.0)    Length(-1.0 to 2.0)
---------------------------------------------------------------------
k = 0.5:     2.26     2.00     2.26     3.09           3.39
k = 1.0:     1.54     1.00     1.54     3.76           4.80
k = 2.0:     1.88     0.50     1.88    13.65          15.46
k = 4.0:     6.83     0.25     6.83   372.62         379.44

Tip

If the output overlaps with any argument that snprintf() or snprintf_s() copies data from, the behavior is undefined.

Example

char buffer[80];
double x = 1234.5, y = 678.9, z = -753.1, a = x * y + z;
int output_len = 0;

output_len = snprintf( buffer, 80, "For the input values %lf, %lf,"
                       " and %lf,\nthe result was %lf.\n",
                       x, y, z, a );
puts( buffer );
if ( output_len >= 80 )
  fprintf( stderr, "Output string truncated! Lost %d characters.\n",
           output_len − 79 );

This code produces the following output:

For the input values 1234.500000, 678.900000, and -753.100000,
the result was 8
Output string truncated! Lost 14 characters.

The first two lines are printed by puts() and the third by fprintf().

Example

See the example for swprintf() in this chapter.

Example

double x = 1234.5, y = 678.9, z = -753.1, a = x * y + z;
char buffer[80];
int output_len = 0;

output_len = sprintf( buffer, "For the input values %lf, %lf, and %lf,"
                       "\nthe result was %lf.\n",
                       x, y, z, a );
puts( buffer );
if ( output_len >= 80 )
  fprintf( stderr, "Output string overflowed by %d characters.\n"
                 "The variables x, y, z and a may have been corrupted:\n"
                 "x now contains %lf, y %lf, z %lf, and a %lf.\n",
                  output_len - 79, x, y, z, a );

This code produces the following output:

For the input values 1234.500000, 678.900000, and -753.100000,
the result was 837348.950000.

Output string overflowed by 14 characters.
The variables x, y, z and a may have been corrupted:
x now contains 1234.500000, y 678.900000, z -736.004971, and a 0.000000.

Example

double x[ ] = { 0.5, 0.0, -0.0, -0.5 };

for ( int i = 0; i < ( sizeof(x) / sizeof(double) ); i++)
{
  printf("The square root of %.2F equals %.4F\n", x[i], sqrt( x[i] ) );
  if ( errno )
    perror( __FILE__ );
}

This code produces the following output:

The square root of 0.50 equals 0.7071
The square root of 0.00 equals 0.0000
The square root of -0.00 equals -0.0000
The square root of -0.50 equals NAN
sqrt.c: Numerical argument out of domain

sqrt() is also used in the examples shown at erf(), feholdexcept(), frexp(), and signbit() in this chapter.

Example

See the example for rand() in this chapter.

Example

See the examples for fscanf() and strspn() in this chapter.

Example

typedef struct {
  char  lastname[32];
  char  firstname[32];
  _Bool ismale;
} Name;

char displayname[80];
Name *newName = calloc( 1, sizeof(Name) );

/* ... check for calloc failure; read in the name parts ... */

strcpy( displayname, ( newName->ismale ? "Mr. " : "Ms. " ) );
// strcat( displayname, newName->firstname );
// strcat( displayname, " " );
// strcat( displayname, newName->lastname );

// Better to use strcat_s() in case the fields in the Name
// structure are ever enlarged:
strcat_s( displayname, sizeof(displayname), newName->firstname );
strcat_s( displayname, sizeof(displayname), " " );
strcat_s( displayname, sizeof(displayname), newName->lastname );

puts( displayname );

Example

typedef struct { char  street[32];
                 char  city[32];
                 char  stateprovince[32];
                 char  zip[16];
               } Address;

char printaddr[128] = "720 S. Michigan Ave.\nChicago, IL 60605\n";
int sublength;
Address *newAddr = calloc( 1, sizeof(Address) );

if ( newAddr != NULL )
{
  sublength = strchr( printaddr, '\n' ) − printaddr;
  strncpy( newAddr->street, printaddr,
           ( sublength < 31 ? sublength : 31 ) );
  /* ... */
}

Example

int result = 0;
char word1[256], word2[256], *greaterlessequal;

while ( result < 2 )
{
  puts( "Type two words, please." );
  result = scanf( "%s%s", word1, word2 );
}
result = strcmp( word1, word2 );

if ( result < 0 )
  greaterlessequal = "less than";
else if ( result > 0 )
  greaterlessequal = "greater than";
else
  greaterlessequal = "the same as";

printf( "The word \"%s\" is %s the word \"%s\".\n",
        word1, greaterlessequal, word2 );

See also the example for qsort() in this chapter.

Example

char *samples[ ] = { "curso", "churro" };

setlocale( LC_COLLATE, "es_US.UTF-8" );

int result = strcoll( samples[0], samples[1] );

if ( result == 0 )
  printf( "The strings \"%s\" and \"%s\" are alphabetically "
          "equivalent.\n", samples[0], samples[1] );
else if ( result < 0 )
  printf( "The string \"%s\" comes before \"%s\" alphabetically.\n",
          samples[0], samples[1] );
else if ( result > 0 )
  printf( "The string \"%s\" comes after \"%s\" alphabetically.\n",
          samples[0], samples[1] );

Because the letter ch comes after the letter c in the Spanish alphabet, the preceding code prints this line in the es_US locale:

The string "curso" comes before "churro" alphabetically.

Example

struct guest {
       char name[64]; int age; _Bool male, smoking, discount; } this;
int result;

printf( "Last name: " );
result = scanf( "%[^\n]", this.name );
if ( result < 1 )
     strcpy( this.name, "[not available]" );
// or
// strcpy_s( this.name, sizeof(this.name), "[not available]" );
printf( "Name: %s\n", this.name );

Example

char *path = "/usr/local/bin:/usr/bin:/bin:/usr/bin/X11:/usr/games";
int  separator;
char *basename = "aprogram";
char fullname[1024] = "";

separator = strcspn( path, ":" );   // Obtain the index of the first
                                    // colon.

strncpy( fullname, path, separator );
fullname[separator] = '\0';         // Terminate the copied string
                                    // fragment.
strncat( fullname, "/", sizeof(fullname) − strlen(fullname) −1 );
strncat( fullname, basename, sizeof(fullname) − strlen(fullname) −1 );

puts( fullname );

The last statement prints the following string:

/usr/local/bin/aprogram

Example

FILE *fp;
char msgbuf[1024] = { '\0' };

/* Open input file: */
if (( fp = fopen( "nonexistent", "r" )) == NULL)
{
  int retval = errno;
  snprintf( msgbuf, sizeof(msgbuf),
            "%s:  file %s, function %s, line %d: error %d,\n%s.\n",
            argv[0], __FILE__, __func__, __LINE__, retval,
            strerror( retval ));
  fputs( msgbuf, stderr );
  return retval;
}

This error-handling block prints the following message:

./strerror:  file strerror.c, function main, line 17: error 2,
No such file or directory.

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
// ...
  double x = -1.0, y = 0;
// ...
  errno = 0;
  y = sqrt(x);
  if( errno == EDOM)
  {
    char msg[30] = "";
    strerror_s( msg, sizeof(msg), errno);
    fprintf( stderr, "sqrt: %s\n", msg);
  }

Possible output of the preceding statements is:

sqrt: Mathematics argument out o...

Conversion specification syntax

The conversion specifications have the following syntax:

%[modifier]specifier

The modifier, if present, instructs strftime() to use an alternative, locale-specific conversion for the specified data item, and is either E, for locale-specific calendars and clocks, or O, for locale-specific numeric symbols. The E modifier can be prefixed to the specifiers c, C, x, X, y, and Y. The O modifier can be prefixed to the specifiers d, e, H, I, m, M, S, u, U, V, w, W, and Y. All of the conversion specifiers are listed, with the struct tm members they refer to, in Table 18-12. The replacement value for the conversion specifiers depend on the LC_TIME category of the current locale, which can be changed by the setlocale() function.

Table 18-12. The strftime() conversion specifiers
Conversion specifier	Structure member(s)	Output notation
`a`	`tm_wday`	The name of the day of the week, abbreviated
`A`	`tm_wday`	The name of the day of the week, in full
`b` or `h`	`tm_mon`	The name of the month, abbreviated
`B`	`tm_mon`	The name of the month, in full
`c`	(all)	The date and time
`C`	`tm_year`	The year, divided by 100, as a decimal integer (`00` to `99`)
`d`	`tm_mday`	The day of the month, in decimal, with a leading zero on values less than 10 (`01` to `31`)
`D`	`tm_mon`, `tm_mday`, `tm_year`	Shorthand for `%m/%d/%y`
`F`	`tm_mon`, `tm_mday`, `tm_year`	Shorthand for `%Y-%m-%d`
`g`	`tm_year`, `tm_wday`, `tm_yday`	The last two digits of the year in the ISO 8601 week-based calendar (`00` to `99`)^a
`G`	`tm_year`, `tm_wday`, `tm_yday`	The four-digit year in the ISO 8601 week-based calendar
`H`	`tm_hour`	The hour of the 24-hour clock as a two-digit decimal number (`00` to `23`)
`I`	`tm_hour`	The hour of the 12-hour clock as a two-digit decimal number (`01` to `12`)
`j`	`tm_yday`	The day of the year as a three-digit decimal number (`001` to `366`)
`m`	`tm_mon`	The month as a two-digit decimal number (`01` to `12`)
`M`	`tm_min`	The minutes after the hour as a two-digit decimal number (`00` to `59`)
`n`	(none)	A newline character (`'\n'`)
`p`	`tm_hour`	The AM or PM indication used with a 12-hour clock
`r`	`tm_hour`, `tm_min`, `tm_sec`	The time of day on the 12-hour clock
`R`	`tm_hour`, `tm_min`	Shorthand for `%H:%M`
`S`	`tm_sec`	The seconds after the minute as a two-digit decimal number (`00` to `60`)
`t`	(none)	A tab character (`'\t'`)
`T`	`tm_hour`, `tm_min`, `tm_sec`	Shorthand for `%H:%M:%S`
`u`	`tm_wday`	The day of the week as a one-digit decimal number (`1` to `7`, where `1` is Monday)
`U`	`tm_year`, `tm_wday`, `tm_yday`	The week of the year as a two-digit decimal number (`00` to `53`), where week 1 begins on the first Sunday in January
`V`	`tm_year`, `tm_wday`, `tm_yday`	The week of the year in the ISO 8601 week-based calendar, as a two-digit decimal number (`01` to `53`), where week 1 begins on the last Monday that falls on or before January 4
`w`	`tm_wday`	The day of the week as a one-digit decimal number (`0` to `6`, where `0` is Sunday)
`W`	`tm_year`, `tm_wday`, `tm_yday`	The week of the year as a two-digit decimal number (`00` to `53`), where week 1 begins on the first Monday in January
`x`	(all)	The date
`X`	(all)	The time
`y`	`tm_year`	The last two digits of the year, as a decimal number (`00` to `99`)
`Y`	`tm_year`	The year as a decimal number (example: `2005`)
`z`	`tm_isdst`	The offset from Greenwich Mean Time if available; otherwise nothing (example: `+0200` for two hours and no minutes east of GMT)
`Z`	`tm_isdst`	The name or abbreviation of the time zone if available; otherwise nothing
`%`	(none)	A percent sign (`%`)
^a In this calendar, the week begins on Monday, and the first week of the year is the week that contains January 4. Up to the first three days of January may belong to week 53 of the old year, or up to the last three days of December may belong to week one of the new year.

The strftime() function returns the length of the string written to the output buffer, not counting the terminating null character. If the output is longer than the argument n allows, strftime() returns 0, and the contents of the output buffer are undetermined.

Example

time_t now;
struct tm *localnow;
char hdr_date[999] = "";

time( &now );
localnow = localtime( &now );

if ( strftime( hdr_date, 78, "Date: %a, %d %b %Y %T %z", localnow ) )
  puts( hdr_date );
else
  return -1;

This code prints a date field in RFC 2822 style, such as this one:

Date: Thu, 10 Mar 2005 13:44:18 +0100

Example

char line[1024] =
      "This string could easily be hundreds of characters long.";
char *readptr = line;
int columns = 80;

// While the text is longer than a row:
while ( strlen( readptr ) > columns )
{  // print a row with a backslash at the end:
  printf( "%.*s\\", columns-1, readptr);
  readptr += columns -1;
}
//  Then print the rest with a newline at the end:
printf( "%s\n", readptr );

Example

#define __STDC_WANT_LIB_EXT1__ 1    // For the secure functions.
#include <string.h>
#include <stdlib.h>
// ...
  char str1[]   = "hello ",     // 7 bytes
       str2[10] = "hello ",     // 7 + 3 bytes
       str3[10] = "hello ";     // 7 + 3 bytes

//  strncat( str1, "Jimi", 1);    // Severe error: buffer overflow!
//  strncat( str2, "Jimi", 3);    // OK: "hello Jim"
//  strncat( str3, "Jim", 100);   // OK.

// Or, using strncat_s(), with the variables defined above:
  int ret1, ret2, ret3;

  set_constraint_handler_s(ignore_handler_s);
  ret1 = strncat_s( str1, sizeof(str1), "Jimi", 1);  // ret1 != 0 and
                                                     // str1[0] == '\0'
  ret2 = strncat_s( str2, sizeof(str2), "Jimi", 3);  // OK: ret2 == 0
  ret3 = strncat_s( str3, sizeof(str3), "Jim", 100); // OK: ret3 == 0

Example

char *weekdays[] = { "Sunday", "Monday", "Tuesday", "Wednesday",
                     "Thursday", "Friday", "Saturday" };
char date[ ] = "Thu, 10 Mar 2005 13:44:18 +0100";
int dow;
for ( dow = 0; dow < 7; dow++ )
  if ( strncmp( date, weekdays[dow], 3 ) == 0 )
    break;

Tip

If the first n characters of src do not contain a null character, the function does not terminate the copied string fragment with a null character!

The secure function strncpy_s() also copies up to n characters from the source string src to the char array addressed by dest, but it always appends a null character. If strncpy_s() reads a null character from the source string before copying n characters, then the number of characters it copies is less than n. Otherwise, it writes a terminating null character to dest[n]. The contents of the char array dest after the string terminator character are undetermined.

The function strncpy_s() has the additional parameter destmax to specify the size of the destination array, and tests the following runtime constraints:

The pointers dest and src must not be null pointers. The values of destmax and n must not be greater than RSIZE_MAX, and destmax must be greater than zero.
Either n or the string length of src (or both) must be less than destmax.
The source and destination arrays must not overlap.

If a violation of the runtime constraints occurs, strncpy_s() writes the string terminator character to dest[0], provided dest is not a null pointer and destmax is greater than zero, but not greater than RSIZE_MAX.

The strncpy_s() function returns zero, or a nonzero value if a violation of the runtime constraints occurs.

Example

For strncpy(), see the examples for strcspn() and strpbrk() in this chapter.

The example here shows three strncpy_s() calls:

#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
// ...
   char dest[5], src[] = "okay";
   int r;
   r = strncpy_s( dest, 2, src, 2);    // r != 0, dest[0] == '\0'
   r = strncpy_s( dest, 3, src, 2);    // r == 0, dest == "ok"
   r = strncpy_s( dest, 5, src, 10);   // r == 0, dest == "okay"

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
// ...
char str[] = "hello";
size_t len = strnlen_s( str, 1000);      // len = 5
if( strnlen_s( str, 4) == 4)
{  /* str is more than 4 characters long. */ }

Example

char *story = "He shouted: \"What? I can't hear you!\"\n";
char separators[] = " \t\n.:?!\"";
char *start = story, *end = NULL;
char words[16][16];       // An array of char arrays to collect words in.
int i = 0;

while ( i < 16 && ( end = strpbrk( start, separators ) ) != NULL )
{
  if ( end != start )     // If the separator wasn't the first character,
  {                       // then save a word in an array.
    strncpy( words[i], start, end - start );
    words[i][end - start] = '\0'; // And terminate it.
    i++;
  }
  start = end + 1;                // Next strpbrk call starts with
}                                 // the character after this separator.
puts( story );
for ( int j = 0 ; j < i ; j++ )
  puts( words[j] );

This program prints each of the words it has collected on a new line:

He
shouted
What
I
can't
hear
you

Example

char *mybasename = strrchr( argv[0], '/' );       // Find end of path.
if ( mybasename != NULL )
  mybasename++;         // Point to the first character after the slash.
else
  mybasename = argv[0];
printf( "This program was invoked as %s.\n", mybasename );

Example

char wordin[256];
double val;

puts( "Enter a floating-point number, please:" );
scanf( "%s", wordin );

int index = strspn( wordin, "+-0123456789eE." );
if ( index < strlen( wordin ) )
  printf( "Sorry, but the character %c is not permitted.\n",
           wordin[index] );
else
{
  sscanf( wordin, "%lg", &val );
  printf( "You entered the value %g\n", val );
}

Example

FILE *fpTx, *fpRx, *fpLog;
char rxbuffer[1024], *found;
/* ... */
fgets( rxbuffer, 1024, fpRx );
found = strstr( rxbuffer, "assword:" );
if ( found != NULL )
{
  fputs( "Got password prompt. Sending password", fpLog );
  fputs( "topsecret", fpTx );
}

Example

char in[1024], *this = in, *next = in;
double val;
puts( "Enter some floating-point numbers, please:" );
scanf( "%[^\n]", in );

puts( "Here are the values you entered:" );
while ( 1 )
{
  val = strtod( this, &next );
  if ( next == this )     // Means no conversion was possible.
    break ;
  printf( "\t%g\n", val );
  this = next;            // Try again with the rest of the input string.
}
puts( "Done." );

Example

See the example for the analogous function strtol() in this chapter.

Example

char *command, *arg1, *arg2, *comment;
char line[ ] = "    mul eax,[ebp+4]    ; Multiply by y\n";

command = strtok(line," \t"); // First word, between spaces or tabs.
arg1 = strtok( NULL, ",");    // From there to the comma is arg1.
                              // (Trim off any spaces later.)
arg2 = strtok( NULL, ";\n");  // From there to a semicolon or line end.
comment = strtok( NULL, "\n\r\v\f" );  // From there to end of line or
                                       // page.
printf( "Command:      %s\n"
        "1st argument: %s\n"
        "2nd argument: %s\n"
        "Comment:      %s\n\n",
        command, arg1, arg2, comment );

This sample produces the following output:

Command:      mul
1st argument: eax
2nd argument: [ebp+4]
Comment:       Multiply by y

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
// ...
  char str[] = "Lennon, John: 10/9/1940";
  char *ptr;
  size_t size = sizeof(str);
  char *firstname, *lastname, *birthday;

  lastname = strtok_s( str, &size, ", ", &ptr);
  if( lastname != NULL)
    firstname = strtok_s(NULL, &size, ": ", &ptr);
  if( firstname != NULL)
    birthday = strtok_s(NULL, &size, "", &ptr);
  if(birthday != NULL)
    printf("%s %s was born on %s.\n",
           firstname, lastname, birthday);

This example would generate the following output:

John Lennon was born on 10/9/1940.

Example

char date[ ] = "10/3/2005, 13:44:18 +0100", *more = date;
long day, mo, yr, hr, min, sec, tzone;
day = strtol( more, &more, 10 );
mo  = strtol( more+1, &more, 10 );
yr  = strtol( more+1, &more, 10 );
/* ... */

Example

This for loop uses stroul() to convert an IPv4 address from a dotted-decimal string to a 32-bit integer value:

char dotted[ ] = "172.16.2.10", *ptr = dotted, *nextdot = NULL;
unsigned long dest = 0;
for ( int i = 0; i < 4; i++)
{
  dest <<= 8;
  dest += strtoul( ptr, &nextdot, 10 );
  ptr = nextdot + 1;
}

Example

See the example for the analogous function strtoul() in this chapter.

Example

typedef struct stringpair { char * original;
                            char * xformed; } Stringpair_t ;

Stringpair_t stringpairs[8] =
             { { "Chávez", NULL },        { "Carron", NULL    },
               { "Canoso", NULL },        { "Cañoso", NULL    },
               { "Carteño", NULL },       { "Cortillo", NULL  },
               { "Cortiluz S.A.", NULL }, { "Corriando", NULL } };

char xformbuffer[1024];        // Space to catch each strxfrm() result.

int stringpaircmp( const void * p1, const void *p2 );
                               // Defined externally.

setlocale( LC_COLLATE, "");   // Use the host system's locale setting.

for ( int i = 0; i < 8 ; i++ )
{
  stringpairs[i].xformed
  = malloc( strxfrm( xformbuffer, stringpairs[i].original, 1024 ) + 1);
  if ( stringpairs[i].xformed != NULL )
    strcpy(stringpairs[i].xformed, xformbuffer);
}

qsort( stringpairs, 8, sizeof(Stringpair_t), stringpaircmp );

The qsort() function invoked in the last line of this example would pass the transformed strings to a comparison function named stringpaircmp(). That function would compare the transformed strings using strcmp(), rather than comparing the originals using strcoll().

Tip

Unlike swprintf_s(), the snwprintf_s() function truncates the output string if it is longer than the destination array. In this case, the function writes the first n – 1 characters of the output string, and then the terminating null character.

Example

const wchar_t *dollar_as_wstr( long amount)
// Converts a number of cents into a wide string
// showing dollars and cents.
// For example, converts -123456 into the wide string L"-$1234.56"
{
  static wchar_t buffer[16];
  wchar_t sign[2] = L"";
  if ( amount < 0L)
    amount = -amount, sign[0] = '-';
  ldiv_t dollars_cents = ldiv( amount, 100);
  swprintf( buffer, sizeof(buffer),
          L"%ls$%ld.%2ld", sign, dollars_cents.quot, dollars_cents.rem);
  return buffer;
}

Example

double price = 0.0;
wchar_t wstr[ ] = L"Current price: $199.90";
swscanf( wstr, L"%*[^$]$%lf", &price);      // Read price from string.
price *= 0.8;                               // Apply 20% discount.
printf( "New price: $%.2lf\n", price);

This code produces the following output:

New price: $159.92

Example

if ( system( NULL ))
  system( "echo \"Shell: $SHELL; process ID: $$\"");
else
  printf( "No command processor available.\n" );

This example is not portable, but on certain systems it can produce output like this:

Shell: /usr/local/bin/bash; process ID: 21349

Example

const double pi = 4.0L * atan( 1.0 );         // Because tan(pi/4) = 1
double shadow_length = 85.5,
       angle = 36.2;          // Sun's elevation from the horizon, in
                              // degrees
double height = shadow_length *tan ( angle * pi/180);

printf("The tower is %.2f meters high.\n", height);

This code produces the following output:

The tower is 62.58 meters high.

Example

double x = -0.5, y1, y2;

y1 = tanh(x);
y2 = exp(2*x);
y2 = (y2 -1) / (y2 + 1);

printf("The tanh() function returns     %.15f.\n", y1 );
printf("Using the function exp() yields %.15f.\n", y2 );

This code produces the following output:

The tanh() function returns     -0.462117157260010.
Using the function exp() yields -0.462117157260010.

Example

int th_func(void * arg)            // The thread function.
{
    puts("Hello from th_func ...");
    ++*(int*)arg;
    return 0;
}

int main()
{
    thrd_t th;   int n = 1;

    if ( thrd_create(&th, th_func, &n) != thrd_success) {
      fprintf(stderr, "Error creating thread.\n"); return -1;
    }
    puts("Main thread here ...");

    thrd_join(th, NULL);
    printf("The value of n is %d\n", n);     // n == 2
    return 0;
}

Example

See the example for thrd_equal() in this chapter.

Example

void independent_thread(void)
{
   puts("Working independently in the background ... ");
   // . . .
   thrd_exit(0);
}

int create_independent_thread(void)
{
   thrd_t th;
   if( thrd_create(&th, (thrd_start_t)independent_thread, "")
                                                      != thrd_success)
      return -1;
   if( thrd_detach(th) != thrd_success)
      return -1;
   puts("Started independent thread.");
   return 0;
}

Example

thrd_t mainThrd;

int func(void)
{
   if( thrd_equal( thrd_current(), mainThrd) )
   {   puts("Main thread here ...");  return 0;  }
   else
   {   puts("Other thread here ..."); return 1;  }
}

int main()
{
   thrd_t th;
   mainThrd = thrd_current();
   if ( thrd_create(&th, (thrd_start_t)func, NULL) != thrd_success)
   {   fprintf(stderr, "Error creating thread.\n");  return -1; }
   func();
   thrd_join(th, NULL);
   return 0;
}

Example

See the example for thrd_detach() in this chapter.

Example

See the example for thrd_create() in this chapter.

Example

Block the calling thread for a half second (500 million nanoseconds):

struct timespec d = { .tv_nsec = 500*1E6 };
while( thrd_sleep( &d, &d) == -1)       // Sleep 500 ms.
   ;

Example

See the example on atomic_fence_op() in this chapter.

Example

time_t sec;
time(&sec);
printf("This line executed at %.24s.\n", ctime(&sec));

This code produces output like the following:

This line executed at Thu Jan 29 08:30:17 2015.

See also the examples for asctime(), ctime(), fprintf(), freopen(), gmtime(), rand(), and strftime() in this chapter.

Example

struct timespec ts;
if( timespec_get( &ts, TIME_UTC) != 0)
   printf("The exact local time:\n"
   "%.24s and %09lu nanoseconds\n", ctime(&ts.tv_sec), ts.tv_nsec);

Typical output:

The exact local time:
Sun Apr 12 11:40:43 2015 and 030395137 nanoseconds

Example

FILE *fpTmp, *fpRx;
int c;

/* ... open Rx stream ... */

// if (( fpTmp = tmpfile() ) == NULL )
// or
if( tmpfile_s( &fpTmp) != 0 )
  fputs( "Unable to open a temporary file.", stderr );
else
{
  while (( c = fgetc( fpRx )) != EOF )
    if ( fputc( c, fpTmp ) == EOF )
      break;
}
fclose( fpRx );

/* ... process the data captured in fpTmp ... */

Tip

If you use a name supplied by tmpnam() to create a file, that does not mean the file is a temporary file in the sense of tmpfile(); it will not be automatically deleted on closing.

Example

// char fname[L_tmpnam];
// or
char fname[L_tmpnam_s];
FILE *fpOut;

// if( tmpnam( fname) == NULL)
// or
if( tmpnam_s( fname, sizeof(fname)) != 0)
{
  fputs( "Error generating a temporary file name.", stderr );
  return -1;
}

fpOut = fopen( fname, "w+" );
/* ... write and edit something in the file ... */
fclose( fpOut );
printf( "The results have been saved in %s.\n", fname );

Tip

Which characters are considered uppercase, and which of those have a corresponding lowercase character, depends on the current locale setting for the localization category LC_CTYPE, which you can query or change using the setlocale() function. The uppercase characters are those for which isupper() returns true; the lowercase characters are those for which islower() returns true.

Accented characters, umlauts, and the like are considered alphabetic only in certain locales. Moreover, other locales may have characters that are alphabetic but are neither uppercase nor lowercase, or both uppercase and lowercase.

Example

See the examples for getchar() and setlocale() in this chapter.

Tip

The note concerning locales under tolower() in this chapter applies to toupper() as well.

Example

See the example for setlocale() in this chapter.

Example

wint_t before = L'\0', after = L'\0';
wctrans_t mapping;
mapping = wctrans("toupper");

while (( before = getwchar() ) != WEOF )
{
  after = towctrans( before, mapping );
  putwchar( after );
  if ( after == L'Q' )
    break;
}

Example

See the example using the analogous function towupper() under mbrtowc() in this chapter.

Example

See the example for mbrtowc() in this chapter.

Example

printf("trunc(-1.7) = %.2f   trunc(1.4) = %.2f   trunc(1.5) = %.2f\n",
        trunc(-1.7),  trunc(1.4), trunc(1.5) );

printf("round(-1.7) = %.2f   round(1.4) = %.2f   round(1.5) = %.2f\n",
        round(-1.7), round(1.4), round(1.5) );

This code produces the following output:

trunc(-1.7) = -1.00   trunc(1.4) = 1.00   trunc(1.5) = 1.00
round(-1.7) = -2.00   round(1.4) = 1.00   round(1.5) = 2.00

Example

The following example illustrates the use of tss_create() and tss_delete(). See also the example for tss_set() and the more complete code example in “Using Thread-Specific Storage”.

tss_t key;            // Global key for a TSS pointer
void destructor(void *data);               // Destructor function

int main()
{
   // Create the TSS key:
   if( tss_create(&key, destructor) != thrd_success)
     return -1;

   // Create threads and wait for them to finish.
   // . . .

   tss_delete(key);  // Free all resources of the TSS pointer.
   return 0;
}

Example

See the example for tss_create() in this chapter.

Example

See the example for tss_set() in this chapter.

Example

The following example illustrates the use of tss_set() and tss_get(). See also the example for tss_create() and the more complete code example in “Using Thread-Specific Storage”.

tss_t key;               // Global key for a TSS pointer
                         // tss_create(&key, ...) has been called.
// Process some data of some type Data_t:
int process_data(void)   // Use thread-specific storage.
{
   Data_t *ptr = (Data_t*)tss_get(key);    // Pointer to TSS
   // Process data ...
   return 0;
}

int thread_func( void* arg)
{
   size_t size = size_data( arg);   // A helper function to find the
                                    // required storage size.
   // Set thread-specific storage:
   if( tss_set(key, malloc(size)) != thrd_success)
      return -1;

   // Store and process data ...
   return process_data();            // return calls the destructor, if
}                                    // the tss_create() call set one.

Example

char file[ ]  = "input.dat";
FILE *fp;
int c;
char numstr[64];

if (( fp = fopen( file, "r" )) == NULL )
  fprintf( stderr, "Can't read the file %s\n", file), exit(1);

while ( (c = getc(fp)) != EOF )
{
  if ( isdigit(c) )     // Collect a sequence of digits.
  {
    int i = 0;
    do
    {
      numstr[i++] = (char)c;
      c = getc(fp);
    }while ( isdigit(c) && i+1 < sizeof(numstr) );

    numstr[i] = '\0';           // Terminate the numeral string.

    /* ... process the numeral string ... */

    if ( ungetc( c, fp) == EOF) // Put back the first non-digit.
      break;
    continue;
  }
  /* ... process any non-digit characters ... */
}
if ( !feof( fp))
  fprintf( stderr, "Error processing the file %s\n", file);

return 0;

Example

See the example for the corresponding byte-character function, ungetc().

va_start

The macro va_start() initializes a va_list object so that it can be used in a va_arg() call to access the first optional argument in the variable-arguments list. The va_start() macro takes as its arguments the va_list object argptr, and the identifier of the last mandatory parameter, represented in this description by last_fixed_arg. Because va_start() makes certain assumptions about the alignment of the parameters in memory, last_fixed_arg must not be declared with the register storage class specifier, and must not have a function or array type, nor an integer type that is narrower than int.

Once you have called va_start(), you can access the optional arguments in the list one by one through successive va_arg() calls. You must not call va_start() again for the same va_list object until you have passed it to the va_end() macro.

va_arg

To obtain each optional argument, call the va_arg() macro. The va_arg() macro takes as its arguments the va_list object argptr, and the type of the argument being read. Each such call to va_arg() returns one argument from the optional arguments list, and adjusts argptr so that the next call returns the next argument.

If there is no argument left to be read when you call va_arg(), the behavior is undefined. The behavior is likewise undefined if the type indicated in the va_arg() call does not match the actual argument’s type, with two exceptions: a signed integer type may match an unsigned integer type, if the value of the argument is representable in both types; and a pointer to void can match a pointer to char, signed char, or unsigned char.

Tip

The type argument to va_arg() must be in such a notation that appending an asterisk to it yields the type of a pointer to type. For example, the type argument may be char *, but not char [8], because char ** means “pointer to a pointer to char”; but char [8]* does not mean “pointer to an array of 8 char elements.” (That type’s name would be written char (*)[8].)

va_copy

The macro va_copy() copies the state of the argument list referenced by the va_list object src to the object dest. If you have already called va_arg() for the same va_list object, then the copy produced by va_copy() is set to access the same argument as the original at the time it was copied. Otherwise, the copy is initialized to access the first argument in the list. You must call va_end() both for the copy and for the original after use.

va_end

To facilitate a clean return, a function that takes a variable number of arguments must call the macro va_end() after it has finished reading its optional arguments. The va_end() macro may render argptr unusable until it is reinitialized by calling va_start().

Example

#include <stdarg.h>
#include <stdio.h>
#include <string.h>
#include <math.h>

double vproduct( int n, va_list argptr );
double vsum( int n, va_list argptr );

double vop( const char * op, int argcount, ... );
// main() calls vop() to perform calculations. vop()'s arguments are:
// (1) the name of the operation ("sum", "product",
//     "sum minus the product");
// (2) the number of operands;
// (3 through n) the operands themselves.
// Iterates through operations twice: once with three operands, once
// with six.

int main()
{
  double d1, d2, d3, d4, d5, d6;

  puts( "Enter six floating-point numbers, please:" );
  scanf( "%lf%lf%lf%lf%lf%lf", &d1, &d2, &d3, &d4, &d5, &d6 );

  char *operation[] = {"sum", "product", "product minus the sum",NULL};

  printf("\nUsing the three numbers %lf, %lf, and %lf.\n", d1, d2, d3);
  for ( int i = 0; operation[i] != NULL; i++ )
    {
      printf( "The %s of these %d numbers is %lf\n",
              operation[i], 3,
              vop( operation[i], 3, d1, d2, d3 ) );
    }

  printf( "\nUsing six numbers:"
          "\n\t%lf \t%lf \t%lf \n\t%lf \t%lf \t%lf\n",
          d1, d2, d3, d4, d5, d6 );
  for ( int i = 0; operation[i] != NULL; i++ )
    {
      printf( "The %s of these %d numbers is %lf\n",
              operation[i], 6,
              vop( operation[i], 6, d1, d2, d3, d4, d5, d6 ) );
    }
}

double vop( const char * op, int argcount, ... )
{
  va_list argptr;
  double  result;

  va_start( argptr, argcount );

  if ( strcmp( op, "sum" ) == 0 )
    result = vsum( argcount, argptr );

  else if ( strcmp( op, "product" ) == 0 )
    result = vproduct( argcount, argptr );

  else if ( strcmp( op, "product minus the sum" ) == 0 )
  {
    va_list duplicate_argptr;     // Clone the va_list in its present
                                  // state.

    va_copy( duplicate_argptr, argptr );
    result = vproduct( argcount, argptr )
             - vsum( argcount, duplicate_argptr );
    va_end( duplicate_argptr );              // Clean up the clone.
  }

  else result = NAN;

  va_end( argptr );                          // Clean up the original.
  return result;
}

double vproduct( int n, va_list argptr )
{
  double product = 1.0;

  for ( int i = 0; i < n; i ++ )
    product *= va_arg( argptr, double );

  return product;
}

double vsum( int n, va_list argptr )
{
  double sum = 0.0;

  for ( int i = 0; i < n; i ++ )
    sum += va_arg( argptr, double );

  return sum;
}

In this example, the helper functions vproduct() and vsum() take as their second argument a va_list object that has already been initialized, and also leave the cleaning up to the caller. In this respect, they are similar to the vprintf() and vscanf() function families.

See also the example for vfscanf() in this chapter.

Tip

The va_start(), va_arg(), and va_end() macros and the type va_list are declared in the header file stdarg.h.

Like the fprintf() and printf() functions, vfprintf() and vprintf() return the number of characters written to the output stream. The function vsprintf() returns the number of characters written to the string buffer, not counting the terminator character; and vsnprintf() returns the number of characters that would have been written to the string buffer if the parameter n had been sufficiently large, again not counting the terminator character.

Example

// write_log appends a line to the log file associated with the
// FILE pointer fp_log.
// The format string and optional arguments are the same as for printf().

void write_log(const char *function_name, unsigned int line_num,
               const char *format_str, ...)
{
  if ( fp_log == NULL)
    return;
  time_t timestamp = time(NULL);
  va_list argptr;
  // Set argptr to the first optional argument:
  va_start( argptr, format_str);

  // First print the timestamp, function name, and line number:
  fprintf( fp_log, "%.8s %s (line %u): ",
                   ctime(&timestamp)+11, function_name, line_num);
  // Then print the rest of the message:
  vfprintf( fp_log, format_str, argptr);

  va_end(argptr);
}

void myFunc( int param)
{
  write_log( __func__, __LINE__, "param = %d\n", param);
  /* ... */
}

Calling myFunc() in this example with the argument value 777 results in the following log file entry:

13:32:44 myFunc (line 62): param = 777

Example

See the example for vfprintf() in this chapter.

Tip

The va_start(), va_arg(), and va_end() macros and the type va_list are declared in the header file stdarg.h.

Like the fscanf(), scanf(), and sscanf() functions, vfscanf(), vscanf(), and vsscanf() return the number of input items that have been assigned to variables referenced by elements of the argument list.

Example

typedef struct {
  char lastname[20];
  char firstname[20];
  int dob_month;
  int dob_day;
  int dob_year;
} person;

person employee;

int read_person( char *lname, char *fname, ... )
// As variable arguments (...) use NULL
// or three int pointers (month, day, year).
{
  va_list args;
  int count;

  puts( "Enter the last name and first name (Example: Smith, Sally)");
  count = scanf( "%[^,], %[^\n]", lname, fname );   // Read the name.

  va_start(args, fname); // Initialize args to start with the argument
                         // that follows fname in the function call.
  if ( count == 2 && va_arg(args, int*) != NULL )
  {
    va_end( args);
    va_start( args, fname);  // Initialize args again.

    printf( "Enter the date of birth. (Example: 9/21/1962)\n");
    count += vscanf( "%d/%d/%d", args );        // Read date of birth.
  }
#ifdef DEBUG
  fprintf( stderr, "Read %d fields.\n", count);
#endif // def DEBUG

  va_end( args );
  return count;
}

int main()
{
  person *pEmployee = &employee;
  int result;

  result = read_person( pEmployee->lastname,
                        pEmployee->firstname,
                        &pEmployee->dob_month,
                        &pEmployee->dob_day,
                        &pEmployee->dob_year );

#ifdef DEBUG
  fprintf( stderr, "Fields read: %s, %s; born %d-%d-%d\n",
           pEmployee->lastname,
           pEmployee->firstname,
           pEmployee->dob_month,
           pEmployee->dob_day,
           pEmployee->dob_year );
#endif // def DEBUG
}

Example

See the example for vfscanf() in this chapter.

Example

See the example for the corresponding byte-character function vfprintf() in this chapter.

Tip

The function vsnwprintf_s() truncates its output string if the destination array s is too small. If the destination array is too small for the output of vswprintf_s(), however, a runtime constraint violation occurs.

Example

See the example for vfprintf() in this chapter.

Example

See the example for the corresponding byte-character function vfscanf() in this chapter.

Example

See the example for vfscanf() in this chapter.

Example

See the example for mbrtowc() in this chapter.

Example

   wchar_t wc = L'\u00b1';       //'±'
   char mbStr[MB_CUR_MAX];
   size_t nBytes = 0;
   mbstate_t state = {0};

   if( wcrtomb_s( &nBytes, mbStr, sizeof(mbStr), wc, &state ) != 0)
   { /* Handle the error ... */ }
   printf("Character: '%lc';  multibyte code:", wc);           // '±'
   for( unsigned i = 0; i < nBytes; ++i)
      printf(" %#04x", (unsigned char)mbStr[i]);     // 0xc2 0xb1

Example

typedef struct {
  wchar_t  lastname[32];
  wchar_t  firstname[32];
  _Bool ismale;
} Name;

Name *newName = calloc( 1, sizeof(Name) );

/* ... check for calloc failure; read in the name parts ... */

// Then display the new name
wchar_t displayname[80];
wcscpy( displayname, ( newName->ismale ? L"Mr. " : L"Ms. " ) );
wcscat( displayname, newName->firstname );
wcscat( displayname, L" " );
wcscat( displayname, newName->lastname );
wcscat( displayname, L"\n" );

// Better to use wcscat_s() in case the fields in the Name
// structure are ever enlarged:
// wcscat_s( displayname, sizeof(displayname), newName->firstname );
// wcscat_s( displayname, sizeof(displayname), L" " );
// wcscat_s( displayname, sizeof(displayname), newName->lastname );
// wcscat_s( displayname, sizeof(displayname), L"\n" );
fputws( displayname, stdout );

Example

typedef struct {
  wchar_t  street[32];
  wchar_t  city[32];
  wchar_t  stateprovince[32];
  wchar_t  zip[16];
} Address;

wchar_t printaddr[128] = L"720 S. Michigan Ave.\nChicago, IL 60605\n";
int sublength;
Address *newAddr = calloc( 1, sizeof(Address) );

if ( newAddr != NULL )
 {
  sublength = wcschr( printaddr, L'\n' ) − printaddr;
  wcsncpy( newAddr->street, printaddr,
           (sublength < 31 ? sublength : 31) );
  /* ... */
}

Example

int result = 0;
wchar_t word1[255], word2[256], *greaterlessequal;

while ( result < 2 )
{
  fputws( L"Type two words, please:  ", stdout );
  result = wscanf( L"%255ls%255ls", word1, word2 );
  if ( result == EOF )
    return EOF;
}
result = wcscmp( word1, word2 );

if ( result < 0 )
  greaterlessequal = L"less than";
else if ( result > 0 )
  greaterlessequal = L"greater than";
else
  greaterlessequal = L"the same as";

wprintf( L"The word \"%ls\" is %ls the word \"%ls\".\n", word1,
         greaterlessequal, word2 );

Example

wchar_t *samples[ ] = { L"anejo", L"añeja",};

setlocale( LC_COLLATE, "es_US.UTF-8" );

int result = wcscoll( samples[0], samples[1] );

wprintf( L"In the locale %s, ", setlocale( LC_COLLATE, NULL ));

if ( result == 0 )
  wprintf( L"the wide strings \"%ls\" and \"%ls\" are alphabetically "
           "equivalent.\n", samples[0], samples[1] );
else if ( result < 0 )
  wprintf( L"the wide string \"%ls\" precedes \"%ls\" "
           "alphabetically.\n", samples[0], samples[1] );
else if ( result > 0 )
  wprintf( L"the wide string \"%ls\" comes after \"%ls\" "
           "alphabetically.\n", samples[0], samples[1] );

Example

struct record {
  wchar_t name[64];
  int age;
  _Bool male, smoking, discount;
} this;
int results;

wprintf( L"Last name: " );
results = wscanf( L"%63l[^\n]", this.name );
if ( results < 1 )
     wcscpy( this.name,  L"[Name not available]" );
// or:
// wcscpy_s( this.name, sizeof(this.name)/sizeof(wchar_t),
//           L"[Name not available]" );
wprintf( L"%ls\n", this.name );

Example

wchar_t *path
        = L"/usr/local/bin:/usr/bin:/bin:/usr/bin/X11:/usr/games";
int  separator;

wchar_t *basename = L"aprogram";
wchar_t fullname[1024] = L"";

separator = wcscspn( path, L":" );

wcsncpy( fullname, path, separator );
fullname[separator] = '\0';
wcsncat( fullname, L"/", sizeof(fullname) − wcslen(fullname) −1 );
wcsncat( fullname, basename, sizeof(fullname) − wcslen(fullname) −1 );

fputws( fullname, stdout );

Example

#define MAX_HDR 1024

time_t now;
struct tm *localnow;
wchar_t hdr_date[MAX_HDR] = L"";

time( &now );
localnow = localtime( &now );

if( wcsftime( hdr_date, MAX_HDR, L"Date: %a, %d %b %Y %T %z", localnow))
  fputws( hdr_date, stdout );
else
  return -1;

Example

wchar_t line[1024] =
         L"This string could easily be 400 or 500 characters long. "
         L"This string could easily be 400 or 500 characters long. "
         L"\n";
wchar_t *readptr = line;
int columns = 80;
while( wcslen( readptr ) > columns) // While remaining text is too long,
{                                   // print a chunk with a final
  wprintf(L"%.*ls\\\n", columns-1, readptr);  // backslash and newline.
  readptr += columns -1;
}
wprintf( L"%ls\n", readptr);   // Print the rest, ending with a newline.

Example

See the examples for strncat() and wcscspn() in this chapter.

Example

wchar_t *months[] = { L"January", L"February", L"March", L"April",
                   L"May", L"June", L"July", L"August",
                   L"September", L"October", L"November", L"December"};

wchar_t date[ ] = L"Thu, 10 Mar 2005 13:44:18 +0100";
int mo = 0;
while (( mo < 12 ) && ( wcsncmp( date + 8, months[mo], 3 ) != 0 ))
  mo++;

Warning

If there is no null wide character in the first n wide characters of src, then the wcsncpy() function does not append a terminating null character to the copied string!

If wcsncpy() reads a null wide character from src before it has copied n wide characters, then the function writes null wide characters to dest until it has written a total of n wide characters.

Example

See the examples for wcscspn() and wcspbrk() in this chapter.

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <wchar.h>
// ...
wchar_t ws[] = L"hello";
size_t len = wcsnlen_s( ws, 100);        // len = 5
if( wcsnlen_s( ws, 4) == 4)
{ /* The string contains more than 4 wide characters. */ }

Example

wchar_t *story = L"He shouted: \"What? I can't hear you!\"\n";
wchar_t separators[ ] = L" \t\n.:?!\"";
wchar_t *start = story, *end = NULL;
wchar_t words[16][16];
int i = 0;

while ( i < 16 && ( end = wcspbrk( start, separators ) ) != NULL )
{
  if ( end != start )               // If the separator wasn't the first
  {                                 // character in the substring,
    wcsncpy( words[i], start, end − start );  // then save a word.
    words[i][end − start] = L'\0';            // And terminate it.
    i++;
  }
  start = end + 1;                  // Next wcspbrk call starts with the
}                                   // character after this separator.

fputws( story, stdout );
for ( int j = 0 ; j < i ; j++ )
{
  fputws( words[j], stdout );
  fputwc( L'\n', stdout );
}

Example

int main( int argc, char ** argv )
{
  wchar_t wmyname[256];
  size_t result = mbstowcs( wmyname, argv[0], 256 );
  if ( result == -1 )
    return -1;
  wchar_t *mybasename = wcsrchr( wmyname, L'/' );   // End of path
  if ( mybasename != NULL )
    mybasename++;
  else
    mybasename = wmyname;
  wprintf( L"This program was invoked as %ls.\n", mybasename );
}

Example

int i = 0, n = 0;
size_t result;
wchar_t wc;
char mbstring[256] = { '\0' };
wchar_t widestring[]
        = L"This is originally a string of wide characters.";
const wchar_t *wcsptr = widestring;
mbstate_t state;

printf( "The current locale is %s.\n", setlocale(LC_CTYPE, "") );

memset( &state, '\0', sizeof state );
result = wcsrtombs( mbstring, &wcsptr, 256, &state );

printf("The return value: %d\n", (int)result );
if( result > 0 && wcsptr == NULL )
   printf("The multibyte string: \"%s\"\n", mbstring);

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <wchar.h>
// ...
  wchar_t widestr[] = L"A wide-character string ...";
  const wchar_t *wcptr = widestr;      // A pointer to a wide character.
  char mbstr[100] = "";                // For the multibyte string.
  size_t mblen = 0;
  mbstate_t mbstate = {0};             // Conversion state.

  if( wcsrtombs_s( &mblen, mbstr, sizeof(mbstr),
                   &wcptr, 3, &mbstate) == 0)
  {
     printf("Multibyte length: %zu;  character codes: [", mblen);
     for( size_t i = 0; i < mblen; ++i)
        printf(" %X", (unsigned char)mbstr[i]);
     puts(" ]");
     if( wcptr != NULL)
        printf("Wide characters remaining: \"%ls\"\n", wcptr);
  }

This example produces the following output:

Multibyte length: 3;  character codes: [ 41 20 77 ]
Wide characters remaining: "ide character string ..."

Example

wchar_t wordin[256];
double val;
fputws( L"Enter a floating-point number, please: ", stdout );
wscanf( L"%ls", wordin );
int index = wcsspn( wordin, L"+-0123456789eE." );
if ( index < wcslen( wordin ) )
  wprintf ( L"Sorry, but the character %lc is not permitted.\n",
           wordin[index] );
else
{
  swscanf( wordin, L"%lg", &val );
  wprintf( L"You entered the value %g\n", val );
}

Example

This simple program prints each line in a file that contains a given keyword:

#define MAX_LINE 1024

int main( int argc, char **argv )
{
  FILE *fpIn = NULL;
  wchar_t keyword[MAX_LINE] = { L'\0' };
  wchar_t line[MAX_LINE] = { L'\0' };

  if ( argc != 3 )
  {
    wprintf( L"Syntax: %s <keyword> <filename>\n", argv[0] );
    return -1;
  }

  if (( fpIn = fopen( argv[2], "r" )) == NULL )
    return -2;
  else
    fwide( fpIn, 1 );

  if ( mbstowcs( keyword, argv[1], MAX_LINE ) == -1 )
    return -3;

  int count = 0;
  while ( fgetws( line, MAX_LINE, fpIn ) != NULL )
    if ( wcsstr( line, keyword ) != NULL )
      {
        ++count;
        fputws( line, stdout );
      }

  if ( !feof( fpIn ))
    return -4;
  else
    return count;
}

Example

wchar_t in[1024], *this = in, *next = in;
double val;
fputws( L"Enter some floating-point numbers, please:\n", stdout );
wscanf( L"%l[^\n]", in );

fputws( L"Here are the values you entered:\n", stdout );
while ( 1 )
{
  val = wcstod( this, &next );
  if ( next == this )       // Means no conversion possible.
    break ;
  this = next;
  wprintf( L"\t%g\n", val );
}
fputws( L"Done.\n", stdout );

Example

See the example for the analogous function wcstoumax() in this chapter.

Example

wchar_t *mnemonic, *arg1, *arg2, *comment, *ptr;
wchar_t line[ ] = L"    mul eax,[ebp+4]    ; Multiply by y\n";
// First word between spaces or tabs
mnemonic = wcstok( line, L" \t", &ptr );
arg1 = wcstok( NULL, L",", &ptr );   // From there to the comma is arg1.
                                     // Trim off any spaces later.
arg2 = wcstok( NULL, L";\n", &ptr ); // From there to the semicolon is
                                     // arg2.
// To line or page end is comment:
comment = wcstok( NULL, L"\n\r\v\f", &ptr );

wprintf( L"Mnemonic:     %ls\n"
         L"1st argument: %ls\n"
         L"2nd argument: %ls\n"
         L"Comment:      %ls\n\n",
         mnemonic, arg1, arg2, comment );

This code produces the following output:

Mnemonic:     mul
1st argument: eax
2nd argument: [ebp+4]
Comment:       Multiply by y

Example

See the examples for the functions wcstok() and strtok_s() in this chapter.

Example

wchar_t date[ ] = L"10/3/2005, 13:44:18 +0100", *more = date;
long day, mo, yr, hr, min, sec, tzone;
day = wcstol( more, &more, 10 );        // &more is the address of a
mo  = wcstol( more+1, &more, 10 );      // pointer
yr  = wcstol( more+1, &more, 10 );
hr  = wcstol( more+1, &more, 10 );
min = wcstol( more+1, &more, 10 );
sec = wcstol( more+1, &more, 10 );
tzone = wcstol( more+1, &more, 10 );

 wprintf( L"It's now %02ld:%02ld o'clock on %02ld-%02ld-%02ld.\n",
          hr, min, mo, day, yr % 100 );

This code produces the following output:

It's now 13:44 o'clock on 03-10-05.

Tip

The wcstombs() function terminates the resulting multibyte string with a null character ('\0') only if it has not yet written the maximum number of characters specified by the third argument! If the return value is the same as the specified limit, then the resulting string has not been terminated.

Example

wchar_t fmt_amount[128] = { L'\0' };
wchar_t prefix[32]  = L"-";
wchar_t suffix[32]  = L"€";
wchar_t number[128] = L"123.456,78";
char output_amount[256];

wcscpy( fmt_amount, prefix );
wcscat( fmt_amount, number );
wcscat( fmt_amount, suffix );

if ( -1 != wcstombs( output_amount, fmt_amount, 256 ))
  printf( "Full amount: %s\n", output_amount );

Example

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
// ...
  wchar_t widestr[] = L "A wide-character string ...";
  char mbstr[100] = "";                   // For the multibyte string.
  size_t mblen = 0;

  printf("The current locale is %s.\n",
         setlocale(LC_CTYPE, "" ));

  if( wcstombs_s( &mblen, mbstr, sizeof(mbstr), widestr, 5) == 0)
  {
    printf("Multibyte length: %u;  text: \"%s\"\n", mblen, mbstr);
  // ...
  }

This example produces the following output:

Multibyte length: 5; text: "A wid"

Example

See the example for the analogous function wcstol() in this chapter.

Example

typedef struct {
  uintmax_t packets, bytes;
  wchar_t   policy[16];
  wchar_t   protocol[6];
  /* ... */
} stats_t ;
stats_t iface_in;

wchar_t wcsstat[] =
        L"25183 1633438 ACCEPT tcp -- eth2 * 0.0.0.0/0 tcp dpts:80";
wchar_t *wcsptr = wcsstat;

iface_in.packets = wcstoumax( wcsptr, &wcsptr, 10 );
iface_in.bytes = wcstoumax( ++wcsptr, &wcsptr, 10 );
/* ... */
wprintf( L"Packets: %" PRIuMAX "; bytes: %" PRIuMAX "; policy: ...\n",
         iface_in.packets, iface_in.bytes );

This code produces the following output:

Packets: 25183; bytes: 1633438; policy: ...

Example

typedef struct stringpair { wchar_t * original;
                            wchar_t * xformed;
                          } Stringpair_t ;

int stringpaircmp( const void *p1, const void *p2 );

int main()
{
  wchar_t *originals[] = { L"Chávez", L"Carron",  L"Canoso",
                           L"Cañoso", L"Carteño", L"Corriando",
                           L"Carilo", L"Carillón", };
  wchar_t xformbuffer[1024];

  /* Make an array of structures out of the strings and their
     xformations */

  const int elementcount = sizeof(originals) / sizeof(wchar_t *);
  Stringpair_t stringpairs[elementcount];

  setlocale( LC_ALL, "es_US.UTF-8" );  // Set the locale to US Spanish
  wprintf( L"Sorting order in the locale %s:\n",
           setlocale( LC_COLLATE, NULL ));

  for ( int i = 0; i < elementcount ; i++ )
  {
    stringpairs[i].original = originals[i];
    stringpairs[i].xformed
                = malloc( wcsxfrm( xformbuffer, originals[i], 1024 ));
    if ( stringpairs[i].xformed != NULL )
      wcscpy( stringpairs[i].xformed, xformbuffer );
  }

  qsort( stringpairs, elementcount,
         sizeof(Stringpair_t), stringpaircmp );

  for ( int i = 0; i < elementcount ; i++ )
  {
    fputws( stringpairs[i].original, stdout );
    fputwc( L'\n', stdout );
  }
} // end of main()

/* A comparison function for use by qsort. Uses wcscmp() rather
 * that wcscoll(), assuming strings are paired with their wcsxfrm()
 * results in a Stringpair_t structure.
 */
int stringpaircmp( const void *p1, const void *p2 )
{
  const Stringpair_t * sp1 = (Stringpair_t *)p1;
  const Stringpair_t * sp2 = (Stringpair_t *)p2;

  return wcscmp( sp1->xformed, sp2->xformed );
}

This code produces the following output:

Sorting order in the locale es_US.UTF-8:
Canoso
Cañoso
Carilo
Carillón
Carron
Carteño
Corriando
Chávez

Example

FILE *fp_inwide;
wchar_t wc;
int bc;

/* ... open the files ... */

fwide( fp_inwide, 1 );
while (( wc = fgetwc( fp_inwide )) != WEOF )
  if (( bc = wctob( wc )) != EOF )
    fputc( c, stdout );
  else                       // If no byte-character equivalent,
    fputc( '?', stdout );    // print a question mark instead.

Example

  char mbbuffer[MB_LEN_MAX] = { '\0' };
  wchar_t wcs[] =  L"Wir stehen auf den Füßen von Riesen";
  int n = 0, i = 0;

  printf( "The current locale is %s.\n", setlocale( LC_CTYPE, "" ));
  printf( "The locale's multibyte encoding is %s.\n",
          (wctomb( NULL, L'\0' ) ? "stateful" : "stateless" ));
  do {
    n += wctomb( mbbuffer, wcs[i] );
  } while ( wcs[i++] != L'\0' );

  printf( "The wide string \"%ls\" \nis %u wide characters long.\n"
      "Its multibyte representation requires a buffer of %u bytes.\n",
       wcs, wcslen( wcs ), n );

This code produces output like this:

The current locale is en_US.UTF-8.
The locale's multibyte encoding is stateless.
The wide string "Wir stehen auf den Füßen von Riesen"
is 35 wide characters long.
Its multibyte representation requires a buffer of 38 bytes.

Example

#define __STDC_WANT_LIB_EXT1__ 1  // For wctomb_s()
#include <stdlib.h>
// ...
int main()
{
   setlocale(LC_ALL, "en_US.utf8");

   wchar_t wc = L'\u03B1';      // Greek lowercase alpha α
   char mbStr[MB_CUR_MAX];
   int nBytes = 0;

// if( (nBytes = wctomb( mbStr, wc )) < 0)
// is equivalent to
   if( wctomb_s( &nBytes, mbStr, sizeof(mbStr), wc ) != 0)
      { /* error: */ return -1; }
   printf("Wide-character code: %#06x; character: '%lc'; "
          "multibyte code:", wc, wc);
   for( int i = 0; i < nBytes; ++i)
      printf(" %#04x", (unsigned char)mbStr[i]);
   putchar('\n');
   return 0;
}

This example generates the following output:

Wide-character code: 0x03b1; character: 'α'; multibyte code: 0xce 0xb1

Example

See the example for towctrans() in this chapter.

Tip

The strings listed in the description of the iswctype() function are valid in all locales as property arguments to the wctype() function.

Example

wctype_t wct_kanji, wct_kata, wct_hira /* , ... */ ;

setlocale( LC_CTYPE, "ja_JP.UTF-8" );

if (( wct_kata = wctype( "jkata" ) ) == 0 )
  { wprintf( L"The locale doesn't support the wide-character type "
            "string \"jkata\".\n" ); return -1; }
/* ... */
wc = fgetwc( stdin );
if ( iswctype( wc, wct_kata ) )         // Mainly 0xFF66 − 0xFF9F.
  wprintf( L"%lc is a katakana character.\n", wc );

Example

See the example for wmemcpy() in this chapter.

Example

#define BUFFERSIZE 4096

wchar_t  first[BUFFERSIZE] = { L'\0' };
wchar_t second[BUFFERSIZE] = { L'\0' };

/* ... read some data into the two buffers ... */

if ( wmemcmp( first, second, BUFFERSIZE ) == 0 )
  printf( "The two buffers contain the same wide-character text.\n" );

Example

#define BUFFERSIZE 2048         // Size as a number of wchar_t elements.

wchar_t inputbuffer[BUFFERSIZE] = { L'\0' },
        *writeptr = inputbuffer;

struct block { wchar_t *text;
  struct block *next;
  struct block *prev;
} firstblock = { NULL },   // The first block is the list head.
  *tmp = NULL;

struct block *newblock( struct block *lastblock );
                                       // Creates a linked-list member.
wchar_t *storetext( struct block *listhead,
                    wchar_t *buffer,
                    size_t bufsize );
                    // Copies input buffer to a new linked-list member.

int main()
{

  while( fgetws( writeptr, BUFFERSIZE − (writeptr−inputbuffer), stdin)
          != NULL )
    {
      // Set writeptr to end of the input string:
      writeptr = wmemchr( inputbuffer, L'\0',
                          sizeof(inputbuffer) / sizeof(wchar_t) );

      if ( BUFFERSIZE − (writeptr − inputbuffer) < 80 )
                                        // If block full, or nearly so:
        {                               // copy buffer to a data block.
          writeptr = storetext( &firstblock, inputbuffer, BUFFERSIZE );
          if ( writeptr == NULL )        // Out of memory!
            abort();
        }
    }         // Here if fgetws() returns NULL.
  writeptr = storetext( &firstblock, inputbuffer, BUFFERSIZE );
  if ( writeptr == NULL )        // Out of memory!
    abort();
}
// ----------------------------
wchar_t *storetext(struct block *listhead,
                   wchar_t *buffer, size_t bufsize)
     // Copies input buffer to a new chained-list member;
     // returns pointer to input buffer, or NULL on failure.
{
  struct block *tmp = listhead;  // create new block on end of list ...
  while ( tmp->next != NULL )
    tmp = tmp->next;
  if (( tmp = newblock( tmp )) != NULL )
    wmemcpy( tmp->text, buffer, bufsize ); // ... and copy the text.
  // Or:
  // wmemcpy_s( tmp->text, BUFFERSIZE, buffer, bufsize );
  else  // Out of memory!
    return NULL;

#ifdef DEBUG
  fwprintf( stderr, L"\nStored a block with this text:\n%ls\n",
            tmp->text );
#endif

  return buffer;      // Return pointer to buffer, now ready for reuse.
}
// ----------------------------
struct block *newblock( struct block *lastblock )
     // Allocates a new block and appends it to the chained list;
     // returns pointer to new block, or NULL on failure.
{
  if (( lastblock->next = malloc( sizeof(struct block) )) != NULL
      && ( lastblock->next->text
                = malloc( BUFFERSIZE * sizeof(wchar_t) )) != NULL)
    {
      lastblock->next->prev = lastblock;
      lastblock->next->next = NULL;
      return lastblock->next;
    }
  else                            // Out of memory!
    return NULL;
}

Example

#define LINESIZE   2048     // Sizes as numbers of wchar_t elements.
FILE *fp_input, *fp_tmp;
w_char inputblock[LINESIZE*128], *writeptr;

/* ... Input some lines to the input block ... */

/* Dump most of the block to a temporary file: */
fp_tmp = tmpfile();
fwrite( inputblock, sizeof(wchar_t), LINESIZE*127, fp_tmp );

/* ... push the rest of the block to the front ... */
wmemmove( inputblock, inputblock + LINESIZE*127, LINESIZE );
// or
// wmemmove_s( inputblock, sizeof(inputblock)/sizeof(wchar_t),
//             inputblock + LINESIZE*127, LINESIZE );

/* ... and continue input: */
writeptr -= LINESIZE*127;
/* ... */

Example

#define BLOCKSIZE 2048         // Size as a number of wchar_t elements.
wchar_t *inputblock;

if (( inputblock = malloc( BLOCKSIZE * sizeof(wchar_t))) != NULL )
    wmemset( inputblock, L'~', BLOCKSIZE );
/* ... */

Example

See the examples for iswalnum() and wscanf() in this chapter.

Table 18-13. wscanf() conversion specifications that differ from scanf()
Conversion specification	Argument type	Remarks
`%c`	`char *`	Conversion as by `wcrtomb()`
`%lc`	`wchar_t *`	No conversion, no string terminator
`%s`	`char *`	Conversion as by `wcrtomb()`
`%ls`	`wchar_t *`	No conversion

Example

wchar_t perms[12];
wchar_t name[256];
unsigned int ownerid, groupid, links;
unsigned long size;
int count;

count = wscanf( L"%11l[rwxsStTld+]%u%u%u%lu%*10s%*5s%256ls",
                 perms, &links, &ownerid, &groupid, &size, name );

wprintf( L"The file %ls has a length of %lu bytes.\n", name, size );

Assume that this code is executed with the following input (produced by the Unix command ls -ln --time-style=long-iso):

-rw-r--r--  1 1001 1001 15 2005-03-01 17:23 überlänge.txt

The wscanf() function call in the example copies the string "-rw-r--r--" to the array perms, and assigns the integer values 1 to the links variable, 1,001 to ownerid and groupid, and 15 to size. Then it reads and discards the date-and-time information, and copies the rest of the input string, up to a maximum length of 256 wide characters, to the name array. The resulting output is:

The file überlänge.txt has a length of 15 bytes.

Table of Contents for C in a Nutshell, 2nd Edition

Chapter 18. Standard Library Functions

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Example

See Also

Table of Contents for
C in a Nutshell, 2nd Edition