// -*- c -*-

// @@PLEAC@@_NAME
// @@SKIP@@ C/Posix/GNU


// @@PLEAC@@_WEB
// @@SKIP@@ http://www.gnu.org/software/libc/libc.html


// @@PLEAC@@_2.7
//------------------------------------------------------------------
#include <stdlib.h> // rand() srand()

...

/*
    rand() function is not guaranted to produce random values
*/

int random;
  
// the same value between 0 and RAND_MAX
// for every run
random = rand();

...

//------------------------------------------------------------------
...

float random;

// the same value between 0 and 1.0
// for every run
random = (float) rand() / RAND_MAX;

...

//------------------------------------------------------------------
...

#define N 42

...

int random;

// the same value between 0 and N -1
// for every run
random = (int)( N * (double)rand() / (RAND_MAX + 1.0) );

...

// @@PLEAC@@_2.8
//------------------------------------------------------------------
#include <stdlib.h> // rand() srand()
#include <time.h> // time()

...

int random;

// seeds a new sequence of random number
srand(time(NULL));

// a different value between 0 and RAND_MAX
// for every run
random = rand();

...

// @@PLEAC@@_2.9
//------------------------------------------------------------------
/*
    under Linux /dev/random or /dev/urandom
*/

#include <stdio.h> // FILE *, fopen(), fread(), fclose()

...

FILE * fp;

unsigned int random;

if ((fp = fopen("/dev/random","r")) == NULL) {
  perror("fopen");
  exit(1);
}

fread(&random, sizeof(random), 1, fp);
printf("random number %u from /dev/random\n", random);

fclose(fp);

...

//------------------------------------------------------------------

// @@PLEAC@@_3.0
// NOTE: In order to keep the size / verbosity of code examples to a minimum, library function
// calls will generally not include error checking and handling. Example:
//
//     p = malloc(...);                if ((p = malloc(...)) == NULL)
//                                     {
//                                       ... handle error ...
//                                     }
//
// However, any necessary, application-specific error-related code, will still be used. Code
// examples will endeavour, wherever possible, to make use of:
//
// * C99 Features e.g. variable-length arrays, non-const aggregate initialisers
// * GNU Extensions e.g. nested functions, statement expressions
//
// The aim of doing so is to reduce redundancy [i.e. copious examples of older / standard C
// already exist] as well as enhance the information value of each PLEAC example.
//
// Another item worthy of note is the use of writeable 'static local storage' in many custom
// functions. Whilst a commonly-used technique that makes functions self-contained, and easier
// to use [which is precisely why it is used here], it is not viable in multi-threaded code;
// examples need to be suitably modified to work in such code. The section, 'Printing a Date',
// in Chapter 3: Dates and Times, discusses this issue, and provides illustrative examples.
//
// The GNU C Library provides extensive, if somewhat low-level, date / time functionality. The
// relevant section of the manual may be found at:
//
//     http://www.gnu.org/software/libc/manual/html_mono/libc.html#Date%20and%20Time
//
// Outline of some of the more important concepts:
//
// * Calendar time represented in three forms:
//   - Simple time [a.k.a. Epoch Seconds, seconds since Jan 1, 1970]; represented by the
//    'time_t' type [generally implemented as a 32 bit integer]
//   - Broken-down time; represented by 'struct tm', having a field for each time component
//   - Formatted string; certain string formats are printable and parseable as valid calendar
//     times
//
// * Date manipulations are ordinarily performed using broken-down time form, and are converted
//   to / from this form as the need arises:
//   - Input
//     + simple -> broken-down: 'localtime' / 'gmtime'
//     + string -> broken-down: 'strptime' / 'getdate'
//   - Arithmetic
//     + broken-down -> simple: 'mktime'
//   - Output
//     + broken-down -> string: 'strftime', 'asctime'
//   
//   The above list shows that a date / time value might be either be read in as a string [then
//   parsed, and converted], or converted from a simple-time value [e.g. the 'time' and
//   'gettimeofday' routines return the current date / time as a simple-time value]. Date
//   arithmetic can, of course, be performed using the component fields of a broken-time value,
//   but would, more commonly, be first converted to a simple-time value [via 'mktime'], the
//   relevant operations performed, and converted back. Date / time output is ordinarily in
//   string form, the conversion most likely performed using 'strftime' routine, but use of the
//   'printf' family is also possible
//
// * Despite a few exceptions, the date / time library routines are well standardised [just
//   include the <time.h> header], so are available across platforms. The widely-implemented,
//   though *NIX-specific, routines include:
//   - 'gettimeofday', essentially a higher resolution [microseconds, possibly nanoseconds]
//      version of 'time'
//   - 'strptime' and 'getdate', both routines similar in functionlity to 'sscanf' but using
//     format specifications specialised for date / time handling
//
// Implementations of general purpose date routines [which are generally used in several
// sections] appear here. Protoypes appear in each section in which they are used. To
// successfully compile examples ensure the relevant code from this section is copied into
// the example source file.

struct tm mk_tm(int year, int month, int day, int hour, int minute, int second)
{
  struct tm tmv =
  {
    .tm_hour = hour, .tm_min = minute, .tm_sec = second,
    .tm_year = year - 1900, .tm_mon = month - 1, .tm_mday = day,
    .tm_isdst = -1
  };

  mktime(&tmv);

  return tmv;
}

struct tm mk_tm_unfilled(void)
{
  // -1 value used to indicate 'unfilled' since zero is a legitimate value in some fields
  return ((struct tm) { -1, -1, -1, -1, -1, -1, -1, -1, -1 });
}

struct tm mk_tm_zero(void)
{
  return ((struct tm) { 0, 0, 0, 0, 0, 0, -1, -1, -1 });
}

void show_tm(const struct tm* tmvptr)
{
  int year = tmvptr->tm_year > -1 ? tmvptr->tm_year + 1900 : tmvptr->tm_year;
  int month = tmvptr->tm_mon > -1 ? tmvptr->tm_mon + 1 : tmvptr->tm_mon;

  printf("Y/M/D H:M:S -> %04d/%02d/%02d %02d:%02d:%02d\n",
    year, month, tmvptr->tm_mday,
    tmvptr->tm_hour, tmvptr->tm_min, tmvptr->tm_sec);

  printf("DOW: %02d\nDOY: %02d\nDaylight Saving: %02d\n",
    tmvptr->tm_wday, tmvptr->tm_yday, tmvptr->tm_isdst);

  fflush(stdout);
}

// Note: Equivalent of 'timegm' function implemented on *NIX platforms [code may be 'unpacked'
// for compilers not supporting nested functions] using the more portable technique of changing,
// temporarily, the TZ value
time_t mktime_utc(struct tm* tmvptr)
{
  const char NUL = '\0'; char tzold[32] = {NUL}, tznew[32] = {NUL};

  void save_tz(void)
  {
    char* tz = getenv("TZ"); if (tz != NULL) strcpy(tzold, tz);
  }

  void restore_tz(void)
  {
    char* tz = (tzold[0] != NUL) ? strcat(strcpy(tznew, "TZ="), tzold) : "TZ";
    putenv(tz);
  }

  save_tz();
  putenv("TZ=UTC");
  time_t utc = mktime(tmvptr);
  restore_tz();

  return utc;
}

// ----

// The following helper functions are loosely based on the implementations found in the
// corresponding section(s) of PLEAC-PHP. The 'mk_date_interval' function is notable for
// several reasons:
// * Heavy use of pointer manipulation to search and tokenise string contents; illustrative
//   of a faster, more lightweight, though considerably more complex, approach to this task
//   when compared with use of library functions like 'strtok', 'strstr' and 'strchr'
// * Comprehensive example of both variable-argument handling, and of sensible nested function
//   use
// * The 'parse_entry' nested function illustrates an approach that can be used for mimicing
//   named function parameters
// * Use of a delimited string as a lookup table in the 'getvalue' nested function is mainly
//   illustrative. Better performance can be obtained by other means; if still opting for a
//   string-based lookup table approach, a 'perfect hash'-based technique would be ideal,
//   though would require much more code to implement 
//
// This function, together with 'to_epoch' and 'from_epoch', make use of string parameters
// to represent a keyword. In C this approach wouldn't ordinarily be used because such
// information can most often be encode in integer form e.g. integer constants or enumerations,
// and the processing of integers is dramatically faster and far more efficient than string
// operations such as linear searching and comparision. However, the reason for adopting this
// string-based approach is to mimic the beahviour of the PLEAC-PHP implementations, as well
// as illustrate various C techniques such as pointer manipulation and variable argument
// handling.
// 
// As an aside, error checking is minimal in most of these functions, and could certainly be
// improved.

time_t mk_date_interval(const char* arg1, ...)
{
  static const char EQ = '=', COMMA = ',', NUL = '\0';
  static char buffer[16]; 

  // ----

  char* parse_entry(const char* entry, int* value)
  {
    char* p = (char*) entry; // Assumes: "key=value" form

    // Extract, and convert 'value'
    while (*p++ != EQ) if (*p == NUL) return NULL; 
    *value = atoi(p);

    // Extract 'key', copy to buffer for return
    p = buffer;
    while (*entry != EQ) *p++ = *entry++;
    *p = NUL;

    return buffer;
  }

  // ----

  int getvalue(const char* key)
  {
    // Lookup table implemented as a delimited string
    static const char* const TBL = "sec=1,min=60,hou=3600,day=86400,wee=604800";

    // Perform table lookup [via linear search (slow) of string]
    char* p = (char*) strcasestr(TBL, key);
    if (!p) return 0;

    // Extract table value. Since table is in delimited string form, use pointer
    // manipulation to mark start and end locations of required substring [value for key].
    // Since locations are in a string constant, NUL-termination cannot be performed
    // in-place, so substring is copied to a buffer for subsequent processing
    while (*p++ != EQ) ; 
    char* q = p;
    while (*q != NUL) if (*q == COMMA) break; else ++q; 
    memcpy(buffer, p, q - p);
    *(buffer + (q - p)) = NUL;

    return atoi(buffer);
  }

  // ----

  int interval = 0, value; const char* key;

  // Extract values from 1st argument
  if (!(key = parse_entry(arg1, &value))) return 0;
  interval += value * getvalue(key);

  // Setup for variable argument handling, and extract values from each of these
  const char* arg; va_list ap;

  va_start(ap, arg1);

  while ((arg = va_arg(ap, const char*)) != NULL)
  {
    if (!(key = parse_entry(arg, &value))) return 0;
    interval += value * getvalue(key);
  }

  va_end(ap);

  return interval;
}  

time_t to_epoch(const char* intvltype, double multiple)
{
  return (time_t) floor(multiple * get_date_interval_value(intvltype));
}

double from_epoch(const char* intvltype, time_t tv)
{
  double interval = get_date_interval_value(intvltype);
  return (interval > 0.0) ? tv / interval : 0.0;
}

double get_date_interval_value(const char* intvltype)
{
  double interval = 0.0;

  // What, no lookup table ;) ?
  switch (*intvltype)
  {
    case 'd' : interval = strncasecmp(intvltype, "day", 3) == 0 ? 86400.0 : 0.0; break;
    case 'h' : interval = strncasecmp(intvltype, "hou", 3) == 0 ? 3600.0 : 0.0; break;
    case 'm' : interval = strncasecmp(intvltype, "min", 3) == 0 ? 60.0 : 0.0; break;
    case 's' : interval = strncasecmp(intvltype, "sec", 3) == 0 ? 1.0 : 0.0; break;
    case 'w' : interval = strncasecmp(intvltype, "wee", 3) == 0 ? 604800.0 : 0.0; break;
  }

  return interval;
}

// ----

int doy(int year, int month, int day)
{
  const int BASE = -1; // Zero base [i.e. 1st day is zero] assumed
  static const int cumdays[] = { 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334, 365 };

  if (month < 1 || month > 12) return -1;
  return BASE + cumdays[month - 1] + day + (is_leap_year(year) && month > 2 ? 1 : 0);
}

const char* dayname(int day)
{
  static const char* dnams[] = { "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" };
  if (day < 0 || day > 6) return NULL;
  return dnams[day];
}

// ----

bool is_parseable_date(const char* date, const char* fmt, struct tm* tmvptr)
{
  static char datebuf[128];

  // Date / time string is parsed according to format specification; if it fails it can
  // be assumed a format or type error occurred
  if (strptime(date, fmt, tmvptr) != 0)
  {
    datebuf[0] = '\1';
    // Attempt to generate a date / time string using the previously created broken-time
    // value; if it succeeds it can be assumed the broken-down value is sound, but further
    // validation is needed to ensure the value is truly 'valid'
    return !(strftime(datebuf, sizeof(datebuf), fmt, tmvptr) == 0 && datebuf[0] != '\0');
  }

  return false;   
}

bool is_leap_year(int year)
{
  return year % 4 == 0 && (year % 100 != 0 || year % 400 == 0);
}

bool is_valid_hms(int hour, int minute, int second)
{
  // Purely arbitrary choice; allows 24:00:00, but may be omitted
  if (hour == 24 && minute == 0 && second == 0)
    return true;

  if (hour > -1 && hour < 24)
    if (minute > -1 && minute < 60)
      if (second > -1 && second < 60)
        return true;

  return false;
}

bool is_valid_ymd(int year, int month, int day)
{
  static const int mtbl[] = { -1, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };

  // Purely arbitrary choice; may be modified or omitted
  if (year < 1970 || year > 2038) return false;

  if (month > 0 && month < 13 && day > 0 && day <= mtbl[month]) return true;
  if (day == 29 && month == 2 && is_leap_year(year)) return true;

  return false;
}

bool is_valid_tm(struct tm* tmvptr)
{
  return
    is_valid_hms(tmvptr->tm_hour, tmvptr->tm_min, tmvptr->tm_sec) &&
    is_valid_ymd(tmvptr->tm_year + 1900, tmvptr->tm_mon + 1, tmvptr->tm_mday) &&
    mktime(tmvptr) != -1;
}

// ----

const char* mk_fmt_date(const char* fmt, const struct tm* tmvptr)
{
  static char datebuf[64];
  return (strftime(datebuf, sizeof(datebuf), fmt, tmvptr) == 0) ? NULL : datebuf;
}

// ----

double hms_to_frac(int hour, int min, int sec)
{
  return (hour * 3600 + min * 60 + sec) / 86400.;
}

void frac_to_hms(double frac, int* hour, int* min, int* sec)
{
  int seconds = floor(frac * 86400.);

  *hour = seconds / 3600;
  *min = (seconds - *hour * 3600) / 60;
  *sec = (seconds - (*hour * 3600 + *min * 60));
}

// @@PLEAC@@_3.1
// The current date may be obtained by two means:
// * 'time' library function call; this is the standard, cross-platform approach, which
//   returns a value in Epoch Seconds [elapsed seconds since Jan 1, 1970] 
// * 'gettimeofday' library function; *NIX-specific approach which is similar to 'time'
//   function, but also allows values retrieveable to microsecond resolution
//
// Once an epoch second value is so obtained it is usual to convert it to a broken-down time
// representation for subsequent manipulation, particularly conversion to string form for 
// output. If however, date arithmetic is to be performed, it is more common to see it done
// directly in epoch second form 

#include <time.h>

int main(void)
{
  // Current time: epoch seconds
  time_t curtime = time(NULL);

  // Current time: broken-down time
  struct tm* locptr = localtime(&curtime);
}

// ------------

#include <time.h>
#include <sys/time.h>

int main(void)
{
  // Current time: epoch seconds
  time_t curtime = ({ struct timeval timev; gettimeofday(&timev, NULL); timev.tv_sec; });

  // Current time: broken-down time
  struct tm* locptr = localtime(&curtime);
}

// ----------------------------

#include <stdio.h>
#include <time.h>

int main(void)
{
  time_t curtime = time(NULL);

  // Print standard format date string generated from a simple-time value
  printf("today is %s", ctime(&curtime)); fflush(stdout);

  struct tm* locptr = localtime(&curtime);
  
  // Print standard format date string generated from a broken-time value
  printf("today is %s", asctime(locptr)); fflush(stdout);

  // Use 'strftime' and date format specification to generate date string
  char datebuf[32];
  strftime(datebuf, sizeof(datebuf), "%Y-%m-%d", locptr);

  printf("today is %s\n", datebuf); fflush(stdout);  

  // Extract broken-down time components, and format string using 'printf'
  printf("today is %04d-%02d-%02d\n",
    locptr->tm_year + 1900,
    locptr->tm_mon + 1,
    locptr->tm_mday);
  fflush(stdout);  
}

// @@PLEAC@@_3.2
// The 'mktime' library function fulfils this role by converting a broken-down time value to
// the required epoch seconds. By default the generated value is local time based; a custom
// function is provided for UTC-based time

#include <time.h>
#include <stdlib.h>
#include <string.h>

struct tm mk_tm(int year, int month, int day, int hour, int minute, int second);
time_t mktime_utc(struct tm* tmvptr);

// ----

int main(void)
{
  // Create a broken-down time value from arbitrary component values [Y,M,D,H,M,S]
  struct tm tmv = mk_tm(2007, 5, 2, 0, 0, 0);
  
  // Convert a broken-down time value to epoch seconds [local time assumed]
  time_t epoch_seconds_local = mktime(&tmv);

  // Convert a broken-down time value to epoch seconds [UTC time]
  time_t epoch_seconds_utc = mktime_utc(&tmv);
}

// @@PLEAC@@_3.3
// Two library functions fulfil this role:
// * 'localtime', generates a local time-based value
// * 'gmtime', as above, except generated value is UTC-based

#include <time.h>
#include <stdio.h>

int main(void)
{
  // Current time: epoch seconds
  time_t curtime = time(NULL);

  // Current time: broken-down time [local time-based]
  struct tm* locptr = localtime(&curtime);

  // Current time: broken-down time [UTC-based]
  struct tm* utcptr = gmtime(&curtime);

  printf("Dateline: %02d:%02d:%02d-%04d/%02d/%02d\n",
    locptr->tm_hour, locptr->tm_min, locptr->tm_sec,
    locptr->tm_year + 1900, locptr->tm_mon + 1, locptr->tm_mday);

  struct tm loct = *locptr;

  printf("Dateline: %02d:%02d:%02d-%04d/%02d/%02d\n",
    loct.tm_hour, loct.tm_min, loct.tm_sec,
    loct.tm_year + 1900, loct.tm_mon + 1, loct.tm_mday);

  fflush(stdout);
}

// @@PLEAC@@_3.4
// This task entails the conversion of all dates to be so treated to epoch seconds, which can
// then be arithmetically manipulated. A number of helper functions are included:
// * 'to_epoch', 'from_epoch'; convert a time interval e.g. day, week etc to / from epoch second
//   intervals
// * 'mk_date_interval', creates an epoch second interval from a set of disparate time intervals
// * 'frac_to_hms' and 'hms_to_frac' convert fractional days to / from H:M:S values
//
// In general, arithmetic manipulation of 'time_t' values is safe, but on platforms where it
// may not be implemented as an 'int' or related type, the 'difftime' library function should
// used

#include <stdio.h>
#include <stdarg.h>
#include <string.h>
#include <math.h>
#include <time.h>

time_t mk_date_interval(const char* arg1, ...);
double get_date_interval_value(const char* intvltype);

time_t to_epoch(const char* intvltype, double multiple);
double from_epoch(const char* intvltype, time_t tv);

const char* mk_fmt_date(const char* fmt, const struct tm* tmvptr);
struct tm mk_tm(int year, int month, int day, int hour, int minute, int second);

// ----

int main(void)
{
  time_t now, difference; 

  time_t when = now + difference;     // 'difference' epoch seconds in the future
  time_t then = now - difference;     // 'difference' epoch seconds in the past

  // ------------

  now = time(NULL);

  time_t diff1 = to_epoch("day", 2),
         diff2 = to_epoch("week", 2);

  printf("Today is:                  %s", ctime(&now));
  printf("Two days in the future is: %s", ({ time_t tv = now + diff1; ctime(&tv); }));
  printf("Two weeks in the past is:  %s", ({ time_t tv = now - diff2; ctime(&tv); }));
  printf("\n"); fflush(stdout);

  printf("Today is:                  %s\n", mk_fmt_date("%Y-%m-%d", localtime(&now)));
  printf("Two days in the future is: %s\n",
    ({ time_t tv = now + diff1; mk_fmt_date("%Y-%m-%d", localtime(&tv)); }));
  printf("Two weeks in the past is:  %s\n",
    ({ time_t tv = now - diff2; mk_fmt_date("%Y-%m-%d", localtime(&tv)); }));
  printf("\n"); fflush(stdout);

  // ------------

  time_t birthtime = 96176750;                  // 18/Jan/1973, 3:45:50 am

  time_t interval = 5 +                         // 5 seconds
                    17 * 60 +                   // 17 minutes
                    2  * 60 * 60 +              // 2 hours
                    55 * 60 * 60 * 24;          // and 55 days

  then = birthtime + interval;

  // Then is Wed Mar 14 06:02:55 1973
  printf("Then is %s", ctime(&then)); fflush(stdout);

  // ------------

  birthtime = ({ struct tm tmv = mk_tm(1973, 1, 18, 3, 45, 50); mktime(&tmv); });

  interval = mk_date_interval("day=55", "hou=2", "min=17", "sec=5", NULL);

  then = birthtime + interval;

  printf("To be precise: %s\n", mk_fmt_date("%H:%M:%S, %Y-%m-%d", localtime(&then)));
  fflush(stdout);
}

// @@PLEAC@@_3.5
// Refer to explanation in previous section

#include <stdio.h>
#include <string.h>
#include <math.h>
#include <time.h>

double get_date_interval_value(const char* intvltype);

time_t to_epoch(const char* intvltype, double multiple);
double from_epoch(const char* intvltype, time_t tv);

double hms_to_frac(int hour, int min, int sec);
void frac_to_hms(double frac, int* hour, int* min, int* sec);

struct tm mk_tm(int year, int month, int day, int hour, int minute, int second);

// ----

int main(void)
{
  time_t recent, earlier; 

  time_t seconds = recent - earlier;  // 'seconds' is epoch seconds interval

  // ------------

  struct tm tmv1 = mk_tm(1982, 4, 12, 12, 0, 0),
            tmv2 = mk_tm(1981, 4, 12, 6, 0, 0);

  time_t interval = mktime(&tmv1) - mktime(&tmv2);

  double days = from_epoch("day", interval);

  printf("An interval of %d epoch seconds is %.3f days\n", interval, days);

  // ------------

  time_t bree = 361535725;            // 16 Jun 1981, 4:35:25 [actually: 20:35:25]
  time_t nat = 96201950;              // 18 Jan 1973, 3:45:50 [actually: 21:45:50]

  time_t difference = bree - nat;     // Or do: difference = difftime(bree, nat);

  printf("There were %d seconds between Nat and Bree\n", difference); fflush(stdout);

  // ----

  // Or do following to ensure correctly adjusted intervals are generated:
  bree = ({ struct tm tmv = mk_tm(1981, 6, 16, 20, 35, 25); mktime(&tmv); });
  nat = ({ struct tm tmv = mk_tm(1973, 1, 18, 21, 45, 50); mktime(&tmv); });

  difference = bree - nat;

  printf("There were %d seconds between Nat and Bree\n", difference); fflush(stdout);

  // ------------

  printf("There were %.3f seconds between Nat and Bree\n", from_epoch("sec", difference));
  printf("There were %.3f minutes between Nat and Bree\n", from_epoch("min", difference));
  printf("There were %.3f hours between Nat and Bree\n", from_epoch("hour", difference));
  printf("There were %.3f days between Nat and Bree\n", from_epoch("day", difference));
  printf("There were %.3f weeks between Nat and Bree\n", from_epoch("week", difference));
  fflush(stdout);

  // ------------

  double frac = ({ double days = from_epoch("day", difference); days - floor(days); });
  int hour, min, sec;

  frac_to_hms(frac, &hour, &min, &sec);

  printf("Bree came %d days, %d:%d:%d after Nat\n",
    (int) from_epoch("day", difference),
    hour, min, sec);
  fflush(stdout);
}

// @@PLEAC@@_3.6
// These are obtainable by generating a broken-down time value, and either:
// * Computing the required item using data from the relevant 'tm_' fields
// * Calling the 'strftime' library function with the broken-down time value, and 
//   appropriate format specification. Examples use 'mk_fmt_date' which makes use of
//   'strftime'
// It should be noted that each item may have several possible values, so care is needed
// in interpreting results

#include <stdbool.h>
#include <time.h>
#include <stdio.h>

const char* mk_fmt_date(const char* fmt, const struct tm* tmvptr);

struct tm mk_tm(int year, int month, int day, int hour, int minute, int second);
bool is_leap_year(int year);

int doy(int year, int month, int day);
const char* dayname(int day);

// ----

int main(void)
{
  // Current time in broken-down time form
  struct tm* locptr = ({ time_t curtime = time(NULL); localtime(&curtime); });

  int day_of_week, day_of_year, week_of_year;

  day_of_week = atoi(mk_fmt_date("%w", locptr));   // 1st DOW: sun=0 -> sat=6

  day_of_week = atoi(mk_fmt_date("%u", locptr));   // 1st DOW: mon=1 -> sun=7
  day_of_week = locptr->tm_wday;                   // "   "    "       

  day_of_year = atoi(mk_fmt_date("%j", locptr));   // 1 -> 366
  day_of_year = locptr->tm_yday;                   // 0 -> 365
  day_of_year = doy(2007, 5, 12);                  // " -> "

  week_of_year = atoi(mk_fmt_date("%U", locptr));  // 0 -> 53; sun 1st day of week 1;
                                                   //          preceding days week 0
  week_of_year = atoi(mk_fmt_date("%V", locptr));  // 1 -> 53; ISO
  week_of_year = atoi(mk_fmt_date("%W", locptr));  // 0 -> 53; mon 1st day of week 1;
                                                   //          preceding days week 0

  // ------------

  int year = 1981, month = 6, day = 16;

  struct tm tmv = mk_tm(year, month, day, 0, 0, 0);

  printf("%d/%d/%d was a %s in week %s\n",
    month, day, year, dayname(tmv.tm_wday), mk_fmt_date("%V", &tmv));
}

// @@PLEAC@@_3.7
// Parsing date / time values from strings generally sees:
// * Use of the 'strptime' / 'getdate' functions on *NIX platforms
// * Use of 'sscanf'
// * Custom routines [e.g. strtok'-based, regex-based, raw pointer manipulations]
//
// to extract date / time components and create broken-down time values from them. The first
// approach is probably the simplest, but is not possible on all platforms. It is also
// interesting that it includes only minimal validation capability, that is, while format and
// type violations are readily detected [e.g. supplying either 2007-12-12, or aaaa/bb/cc, when
// something like 2007/12/12 is expected], date validity is only minimally checked [e.g.
// invalid day-month combinations are allowed, as are unrepresentable years (like 1111)], so
// must be manually implemented. A small set of validation and helper functions is implemented
// below.
//
// Note: 'getdate' is a high-level function built using top of 'strptime'. It will not be
// discussed here, so refer to GNU C Library documentation for details.

// 1. 'strptime' Example [conventional use of 'strptime']

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

int main(void)
{
  const char* date = "1998-06-03";

  const char* FMT = "%Y-%m-%d";

  if (strptime(date, FMT, &tmv) == 0)
  {
    fputs("Date parse error ...\n", stderr);
    return EXIT_FAILURE;
  }

  struct tm tmv = { 0, 0, 0, 0, 0, 0, -1, -1, -1 };

  time_t epoch_seconds = mktime(&tmv);
}

// ------------

// 2. 'sscanf' Example [conventional use of 'sscanf']

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

int main(void)
{
  const char* date = "1998-06-03";

  const char* FMT = "%04d-%02d-%02d";

  int year, month, day;
  int result = sscanf(date, FMT, &year, &month, &day);

  if (result == 0 || result == EOF) 
  {
    fputs("Date parse error ...\n", stderr);
    return EXIT_FAILURE;
  }

  struct tm tmv = { 0, 0, 0, day, month - 1, year - 1900, -1, -1, -1 };

  time_t epoch_seconds = mktime(&tmv);
}

// ------------

// 3. 'strtok' Example [hardcoded, minimal error checking, assumes date string will not be used
//    elsewhere, hence may have its contents altered] 

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

#include <string.h>

int main(void)
{
  char date[] = "1998-06-03";

  const char* SEP = "-";
  int ymd[3]; int i = 0;

  char* p = strtok(date, SEP);

  while (p)
  {
    if (i > 2) 
    {
      fputs("Date parse error ...\n", stderr);
      return EXIT_FAILURE;
    }

    ymd[i++] = atoi(p);

    p = strtok(NULL, SEP);
  }

  struct tm tmv = { 0, 0, 0, ymd[2], ymd[1] - 1, ymd[0] - 1900, -1, -1, -1 };

  time_t epoch_seconds = mktime(&tmv);
}

// ------------

// 4. Regex Example [hardcoded, minimal error checking. Assumes date string will not be used
//    elsewhere, hence may have its contents altered] 

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

#include <regex.h>

int main(void)
{
  char date[] = "1998-06-03";

  // Setup regex pattern, and compile; bail out if problem detected
  const char* PATTERN = "([[:digit:]]{4})-([[:digit:]]{1,2})-([[:digit:]]{1,2})";
  regex_t rx;

  if (regcomp(&rx, PATTERN, REG_EXTENDED) != 0)
  {
    fputs("Date parse error [regex compilation failure] ...\n", stderr);
    return EXIT_FAILURE;
  }

  // Hardcoded for 3 [subexpreesion] matches. Match buffer needs to be one larger to
  // accomodate whole-expression match]
  const size_t nmatch = 4;
  regmatch_t match[nmatch];

  // Perform regex match
  int match_result = regexec(&rx, date, nmatch, match, 0);

  // Regex resources no longer required [only match buffer results required], so free them
  regfree(&rx);

  // In the current case, a mismatch indicates an ill-formatted date string was supplied,
  // so bail out 
  if (match_result != 0)
  {
    fputs("Date parse error [regex mismatch] ...\n", stderr);
    return EXIT_FAILURE;
  }

  // NUL-terminate subexpression match areas for easy extraction
  const char NUL = '\0';

  date[match[1].rm_eo] = NUL;
  date[match[2].rm_eo] = NUL;
  date[match[3].rm_eo] = NUL;

  // Convert each subexpression match to required value
  int year = atoi((char*) date + match[1].rm_so);
  int month = atoi((char*) date + match[2].rm_so);
  int day = atoi((char*) date + match[3].rm_so);

  struct tm tmv = { 0, 0, 0, day, month - 1, year - 1900, -1, -1, -1 };

  time_t epoch_seconds = mktime(&tmv);
}

// ------------

// 5. Raw Pointer Example [hardcoded, no error checking, assumes date string is in the
//    correct format, and that it will not be used elsewhere, hence may have its contents
//    altered] 

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

int main(void)
{
  char date[] = "1998-06-03";

  const char NUL = '\0', SEP = '-';
  char *p = date, *q = date;

  int year, month, day;

  // Traverse date buffer, NUL-terminating each required substring in turn for easy conversion
  while (*p++ != SEP) ; *p = NUL; year = atoi(q); q = ++p;
  while (*p++ != SEP) ; *p = NUL; month = atoi(q); q = ++p;
  while (*p++ != NUL) ; day = atoi(q);

  struct tm tmv = { 0, 0, 0, day, month - 1, year - 1900, -1, -1, -1 };

  time_t epoch_seconds = mktime(&tmv);
}

// ----------------------------

#include <stdbool.h>
#include <stdio.h>
#include <string.h>
#include <time.h>

struct tm mk_tm(int year, int month, int day, int hour, int minute, int second);
struct tm mk_tm_unfilled(void);
struct tm mk_tm_zero(void);
void show_tm(const struct tm* tmvptr);

bool is_parseable_date(const char* date, const char* fmt, struct tm* tmvptr);

bool is_leap_year(int year);
bool is_valid_hms(int hour, int minute, int second);
bool is_valid_ymd(int year, int month, int day);
bool is_valid_tm(struct tm* tmvptr);

// ----

int main(void)
{
  // Format specification
  const char* FMT = "%Y/%m/%d";

  // Initialise 'struct tm' object
  struct tm tmv = mk_tm_zero();

  // Use a generously-sized input buffer
  char datebuf[128];

  do
  {
    // Prompt and get a date string from the user 
    fputs("Enter a date in YYYY/MM/DD form: ", stdout); fflush(stdout);
    fgets(datebuf, sizeof(datebuf), stdin);

    // Two stage validation:
    // * Check that input at least matches 'date' form / structure
    // * Ensure generated date / time components comprise a 'sensible' value
    if (is_parseable_date(datebuf, FMT, &tmv) && is_valid_tm(&tmv))
      break;

    // Oops !
    fputs("Bad date string - try again\n\n", stdout); fflush(stdout);

  } while (true);

  // Let's look at the generated date / time components
  show_tm(&tmv);
}

// @@PLEAC@@_3.8
// Printing a date usually sees a broken-down time object either supplied or generated, then
// date components extracted and formatted. This may be accomplished:
// * Manually; extracting broken-down time components and formatting via a 'printf' family
//   function
// * Via 'strftime' library function, a 'printf'-like function that uses a host of date / time
//   specific format specifications
//
// 'ctime' and 'asctime' library functions are available where only a default string
// representation is needed.
//
// In the final part of this section is a self-contained example illustarting, and discussing
// in detail, several implementations of a custom function, 'mk_fmt_date', which makes use of
// 'strftime' to generate a formatted date string

#include <stdio.h>
#include <time.h>

int main(void)
{
  time_t curtime = time(NULL);

  // 'ctime' accepts a 'time_t' pointer, and creates a date string in the form:
  //     "Fri May  4 10:38:03 2007\n"
  printf("%s", ctime(&curtime)); fflush(stdout);
}

// ------------

#include <stdio.h>
#include <time.h>

int main(void)
{
  struct tm* curtmptr = ({ time_t curtime = time(NULL); localtime(&curtime); });

  // 'asctime' accepts a 'struct tm' pointer and creates a date string in the form:
  // "Fri May  4 10:38:03 2007\n"
  printf("%s", asctime(curtmptr)); fflush(stdout);
}

// ------------

#include <stdio.h>
#include <time.h>

struct tm mk_tm(int year, int month, int day, int hour, int minute, int second);

// ----

int main(void)
{
  struct tm* curtmptr = ({ time_t curtime = time(NULL); localtime(&curtime); });
  const char* fmt = "%Y/%m/%d"; // format: YYYY/MM/DD

  // 'strftime' accepts a 'struct tm' pointer and creates a date string in the form specified
  // by a format string, one which is similar to that used by the 'printf' function family,
  // but specialised for date / time formatting. Example below assumes the generated string
  // will fit within a 32 byte buffer. It is possible to determine the actual buffer size
  // needed to accomodate the generated string by making an initial call to 'strftime', as
  // follows:
  //
  //    #include <limits.h>
  //    ...
  //    int DATESIZE = strftime(NULL, _POSIX_SSIZE_MAX, fmt, curtmptr);
  //    ...
  //    char datebuf[DATESIZE + 1];
  //    ...
  //    strftime(datebuf, DATESIZE + 1, fmt, curtmptr);
  //
  char datebuf[32];

  strftime(datebuf, sizeof(datebuf), fmt, curtmptr);
  printf("%s\n", datebuf); fflush(stdout);

  // As above, except that a custom helper function is used to create a 'struct tm' object
  struct tm curtm = mk_tm(2007, 5, 4, 0, 0, 0);

  strftime(datebuf, sizeof(datebuf), fmt, &curtm);
  printf("%s\n", datebuf); fflush(stdout);

  // As above, except that 'printf' is used to perform date string formatting
  printf("%04d/%02d/%02d\n", curtmptr->tm_year + 1900, curtmptr->tm_mon + 1, curtmptr->tm_mday);
  fflush(stdout);
}

// ----------------------------

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

const char* mk_fmt_date(const char* fmt, const struct tm* tmvptr);
const char* mk_fmt_date_r(const char* fmt, const struct tm* tmvptr, char* datebuf, size_t bufsize);
const char* mk_fmt_date_a(const char* fmt, const struct tm* tmvptr);

// ----

int main(void)
{
  struct tm* locptr = ({ time_t curtime = time(NULL); localtime(&curtime); });

  // 1. Return pointer to static local storage
  printf("%s\n", mk_fmt_date("%Y/%m/%d", locptr)); fflush(stdout);

  // 2. Return pointer to supplied buffer
  const size_t BUFSIZE = 32; char buffer[BUFSIZE];
  printf("%s\n", mk_fmt_date_r("%Y/%m/%d", locptr, buffer, BUFSIZE)); fflush(stdout);

  // 3. Return dynamically allocated memory pointer

  // a) Typical use where pointer is captured, used, and finally freed
  const char* bptr = mk_fmt_date_a("%Y/%m/%d", locptr);
  printf("%s\n", bptr); fflush(stdout);
  free(bptr); bptr = NULL;

  // b) Or, for a slightly more compact solution, use the comma operator
  const char* bptrf;
  free(((bptrf = mk_fmt_date_a("%Y/%m/%d", locptr)), printf("%s\n", bptrf), fflush(stdout), bptrf));
  bptrf = NULL;

  // c) Or, for the most compact solution, use a statement expression
  ({ const char* bptr = mk_fmt_date_a("%Y/%m/%d", locptr); printf("%s\n", bptr); fflush(stdout); free(bptr); });
}

// ----

const char* mk_fmt_date(const char* fmt, const struct tm* tmvptr)
{
  // Use of static local storage makes the function self-contained, and keeps the interface
  // uncluttered; an approach adopted, incidentally, in many of the string-handling library
  // functions. However, since each invocation of the function updates the same buffer, it is
  // possible, for example, to inadvertantly use a value generated by a call of this function
  // in another thread, which is why the use of static local storage is not considered 'thread
  // safe' [even use of 'buffer locking' code cannot prevent this type of problem] 
  static char datebuf[64];
  return (strftime(datebuf, sizeof(datebuf), fmt, tmvptr) == 0) ? NULL : datebuf;
}

const char* mk_fmt_date_r(const char* fmt, const struct tm* tmvptr, char* datebuf, size_t bufsize)
{
  // The canonical C approach: supply the function a buffer, and associated buffer size
  // information, and return the buffer's address. This approach clutters the function interface,
  // as well as making function calls more 'noisy' since storage for the call needs to be 
  // supplied / allocated, and size information obtained. Its advantage, though, is that thread
  // safety is assured since each call of the function updates a different memory area
  return (strftime(datebuf, bufsize, fmt, tmvptr) == 0) ? NULL : datebuf;
}

const char* mk_fmt_date_a(const char* fmt, const struct tm* tmvptr)
{
  // Read-only static local storage is, by definition, thread safe
  static const size_t MAXBUFSIZE = 256;

  // Function interface is again uncluttered when using dynamic memory, and the function is 
  // also thread safe. However, the function is no longer self-contained in that the returned
  // buffer address *must* be captured [usually by assignment to a variable], and the allocated
  // memory later explicitly deallocated
  size_t bufsize = strftime(NULL, MAXBUFSIZE, fmt, tmvptr) + 1;
  char* datebuf = (bufsize == 0) ? NULL : (char*) malloc(bufsize);
  return (datebuf != NULL && (strftime(datebuf, bufsize, fmt, tmvptr) > 0)) ? datebuf : NULL;
}

// @@PLEAC@@_3.9
// On single-tasking platforms it can be assumed that elapsed time [i.e. the length of an interval
// between two calendar times] equals processor time [i.e the total amount of time a process has
// used the CPU]. Not so on multi-tasking platforms where a process relinquishes the CPU [e.g.
// the scheduler gives the CPU to another process, process blocks waiting for I/O, or voluntarily
// 'goes to sleep']. It is therefore important to be mindful of the difference, and care taken
// to use / measure the appropriate one.
//
// Elapsed time can portably be measured by performing simple arithmetic using 'time_t' values
// obtained via the 'time' function. However, the resolution is quite low, being second-based.
// Higher resolution timing is possible via platform-specific functionality; in the case of
// *NIX / GNU platforms, the 'gettimeofday' function together with the 'timeval' structure,
// allows for microsecond-level resolution.
//
// Should there be a need to measure processor time, the - portable - 'clock_t' type with 'clock'
// function is available, while on *NIX / GNU platforms there is 'struct tms' together with
// the 'times' function.

#include <stdio.h>
#include <time.h>

int main(void)
{
  time_t start = time(NULL);

  // ... do work here ...

  time_t finish = time(NULL);

  printf("Elapsed time %.9f seconds\n", difftime(finish, start)); fflush(stdout);
}

// ------------

#include <stdio.h>
#include <sys/time.h>

int main(void)
{
  struct timeval start, finish;

  gettimeofday(&start, NULL);

  // ... do work here ...

  gettimeofday(&finish, NULL);  

  double elapsed = finish.tv_sec - start.tv_sec + (finish.tv_usec - start.tv_usec) / 1.e6;

  printf("Elapsed time %.9f seconds\n", elapsed); fflush(stdout);
}

// ------------

#include <stdio.h>
#include <time.h>

int main(void)
{
  clock_t start = clock();

  // ... do work here ...

  clock_t finish = clock();

  double proctime = ((double) (finish - start)) / CLOCKS_PER_SEC;

  printf("Processor time %.9f seconds\n", proctime); fflush(stdout);
}

// ------------

#include <stdio.h>
#include <unistd.h>
#include <time.h>
#include <sys/times.h>

int main(void)
{
  const long CLOCK_TICKS = sysconf(_SC_CLK_TCK);

  struct tms st_cpu, en_cpu;

  clock_t st_time = times(&st_cpu);

  // ... do work here ...

  clock_t en_time = times(&en_cpu);

  printf("Processor Time (seconds):\n\tReal Time: %.9f, User Time %.9f, System Time %.9f\n",
    difftime(en_time, st_time) / CLOCK_TICKS,
    difftime(en_cpu.tms_utime, st_cpu.tms_utime) / CLOCK_TICKS,
    difftime(en_cpu.tms_stime, st_cpu.tms_stime) / CLOCK_TICKS);
  fflush(stdout);
}

// ----------------------------

#include <stdio.h>
#include <sys/time.h>

int main(void)
{
  struct timeval start, finish;

  // Start timing 
  gettimeofday(&start, NULL);

  // ... do work here ...
  printf("Type in some text, press ENTER when done: "); fflush(stdout);

  char line[80];
  fgets(line, sizeof(line), stdin);

  // End timing 
  gettimeofday(&finish, NULL);  

  // Compute and print elapsed [not processor] time
  double elapsed = finish.tv_sec - start.tv_sec + (finish.tv_usec - start.tv_usec) / 1.e6;
  printf("You took %.9f seconds\n", elapsed); fflush(stdout);
}

// ------------

#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <sys/time.h>

void sort(double array[], int size);

// ----

int main(void)
{
  struct timeval start, finish;
  double elapsed = 0.0;

  const int SIZE = 500, NUMBER = 100;
  double array[SIZE];

  srand(time(NULL));

  for (int i = 0; i < NUMBER; ++i)
  {
    for (int j = 0; j < SIZE; ++j) array[j] = rand();

    gettimeofday(&start, NULL);

    sort(array, SIZE);

    gettimeofday(&finish, NULL);  
    elapsed = elapsed + (finish.tv_sec - start.tv_sec + (finish.tv_usec - start.tv_usec) / 1.e6);
  }

  // Compute and print average elapsed [not processor] time
  printf("On average, sorting %d random numbers took %.9f seconds\n", SIZE, elapsed / NUMBER);
  fflush(stdout);
}

// ----

void sort(double array[], int size)
{
  int cmp(const void* lp, const void* rp)
  {
    const double* lpv = (const double*) lp;
    const double* rpv = (const double*) rp;
    return (*lpv > *rpv) - (*lpv < *rpv);
  }

  qsort(array, size, sizeof(array[0]), cmp);
}

// @@PLEAC@@_3.10
// Pausing a process for a designated time period may be accomplished several ways. Only one
// approach is portable across platforms, but is a 'busy waiting'-based approach which, while
// it allows for sub-second pause periods, has the disadvantage of wasting CPU cycles for the
// entire pause period.

#include <time.h>

void busywait(double seconds);

// ----

int main(void)
{
  busywait(0.25);
}

// ----

void busywait(double seconds)
{
  double elapsed;
  clock_t start = clock();

  do { elapsed = ((double) (clock() - start)) / CLOCKS_PER_SEC; } while (elapsed < seconds);
}

// ----------------------------

// Approaches where a process is 'put to sleep' i.e. suspended, with its share of the CPU
// allocated to other processes, are inherently platform-specific. Under *NIX / GNU, several
// library functions may be used:
// * Combination of either 'alarm' or 'setitimer', and 'pause', together with appropriate
//   signal trapping and handling to avoid problems like potential race conditions. Note:
//   code below is a simplistic, purely illustrative example, and does not do this [need to
//   use 'sigprocmask', 'sigaction' et al]
// * Either 'sleep' [second-resolution] or 'nanosleep' [up to nanosecond-resolution if
//   supported by the platform]; will terminate before pause period if process receives a
//   signal
// * Either 'select', or 'poll', to implement microsecond-resolution pause not interrupted by
//   signal

#include <signal.h>
#include <unistd.h>

void alarmSec(long sec);

// ----

int main(void)
{
  // Low-resolution: sleep time specified in seconds
  alarmSec(1);
}

// ----

void alarmSec(long sec)
{
  static void sig_alrm(int signo) {}

  if (signal(SIGALRM, sig_alrm) == SIG_ERR) return;
  alarm(sec);
  pause();
  alarm(0);
}

// ------------

#include <unistd.h>
#include <sys/time.h>

void sleepSec(long sec);
void sleepMicroSec(long usec);
void sleepNanoSec(long nsec);

// ----

int main(void)
{
  // Low-resolution: sleep time specified in seconds
  sleepSec(1);
  sleep(1);

  // High-resolution: sleep time specified in microseconds
  sleepMicroSec(250000);

  // Very high resolution. However, actual resolution is hardware / platform
  // dependant, and will be rounded up to level actually supported
  sleepNanoSec(250000);
}

// ----

void sleepSec(long sec)
{
  nanosleep(&((const struct timespec) { sec, 0 }), NULL);
}

void sleepMicroSec(long usec)
{
  nanosleep(&((const struct timespec) { usec / 1000000L, usec % 1000000L * 1000000L }), NULL);
}

void sleepNanoSec(long nsec)
{
  nanosleep(&((const struct timespec) { 0, nsec }), NULL);
}

// ------------

#include <unistd.h>
#include <sys/time.h>

void sleepAbsSec(long sec);
void sleepAbsMicroSec(long usec);

// ----

int main(void)
{
  // Low-resolution: sleep time specified in seconds
  sleepAbsSec(1);

  // High-resolution: sleep time specified in microseconds
  sleepAbsMicroSec(250000);
}

// ----
     
void sleepAbsSec(long sec)
{
  select(0, NULL, NULL, NULL, &((struct timeval) { sec, 0 }));
}

void sleepAbsMicroSec(long usec)
{
  select(0, NULL, NULL, NULL, &((struct timeval) { usec / 1000000L, usec % 1000000L }));
}

// @@PLEAC@@_3.11
// @@INCOMPLETE@@
// @@INCOMPLETE@@

// @@PLEAC@@_5.0
//------------------------------------------------------------------
#define _GNU_SOURCE

#include <search.h> // hcreate_r() hdestroy_r() struct hsearch_data
#include <string.h>// memset()
#include <stdio.h>// perror()
#include <stdlib.h> //exit()

#define TAB 4

...

struct hsearch_data hash;
size_t max_element = 42; // of elements in search table

...

char * food[] = { "Apple",
                  "Banana",
                  "Lemon",
                  "Carrot"
};
char * color[] = { "red",
                   "yellow",
                   "yellow",
                   "orange"
};

// we create the hash
memset( &hash, 0, sizeof(hash) );
if( hcreate_r(max_element, &hash) == 0 ) {
  perror("hcreate_r");
  exit(1);
}

/*
  adding some elements
*/
  
// we destroy the hash
hdestroy_r( &hash );
  
...

// @@PLEAC@@_5.1
//------------------------------------------------------------------

...

void hash_add_element(char * elmt_key,
                      char * elmt_data,
                      struct hsearch_data * table) {

  ENTRY item;
  ENTRY * ret;
    
  item.key = strdup(elmt_key);
  item.data = strdup(elmt_data);

  if( hsearch_r(item, ENTER, &ret, table) == 0 ) {
    perror("hsearch_r");
    exit(1);
  }
  
  return;
}

...

ENTRY entry;
ENTRY * found;
 
int i;

/*
  hash creation
*/

hash_add_element(food[0], color[0], &hash);
hash_add_element(food[1], color[1], &hash);
hash_add_element(food[2], color[2], &hash);
hash_add_element(food[3], color[3], &hash);

fprintf(stdout, "Known foods:\n");
for( i = 0; i < TAB; i++ ) {
  entry.key = food[i];
  hsearch_r( entry, FIND, &found, &hash );
  fprintf(stdout, "%s\n", found->key);

  // It is the responsibility of the program code
  // to free the elements contained in the hashing table
  free(found->key);
  free(found->data);
}

/*
  hash destruction
*/

...

# Known foods:
# Apple
# Banana
# Lemon
# Carrot

// @@PLEAC@@_5.2
//------------------------------------------------------------------

...

entry.key = "Martini";

if( hsearch_r( entry, FIND, &found, &hash ) != 0 )
  // Martini exists
else
  // it doesn't

...

// @@PLEAC@@_5.3
//------------------------------------------------------------------

// we can't delete an element with the hashing table
// provided by the GNU C library


// @@PLEAC@@_7.4
//------------------------------------------------------------------
#include <stdio.h>
#include <string.h> // strerror()
#include <errno.h> // errno

...

FILE * fp;

if( (fp = fopen(filename, mode)) == NULL )
  fprintf( stderr, "Couldn't open %s for reading : %s\n",
           filename,
           strerror(errno) );

...

// @@PLEAC@@_7.5
//------------------------------------------------------------------
#include <stdio.h> // tmpfile()

...

FILE * file;

// /!\ the temporary filename isn't accessible
file = tmpfile(); 

...

//------------------------------------------------------------------
#include <stdio.h> // remove()
#include <stdlib.h> // mkstemp()

...

int fd;
char template[20];

strcpy( template, "tmp/XXXXXX" );
fd = mkstemp( template );

if( fd < 0 ) {
  perror( mkstemp );
  exit( 1 );
}

remove( template );

// now go on to use the file ...

...

//------------------------------------------------------------------
#include <stdio.h> // tempnam()
#include <stdlib.h>
#include <unistd.h> // unlink()
#include <fcntl.h> // open()
#include <sys/stat.h> 
#include <sys/types.h>

...

char * tmpname = NULL;
int fd;

while(1) {
  tmpname = tempnam( NULL, NULL );
  if( tmpname == NULL ) {
    perror( "tempname" );
    exit(1);
  }

  // is another process creating a temporary file at the same moment?
  // we don't know.
  // => we have to ensure an exclusive open
  fd = open( tmpname, O_CREAT | O_EXCL | O_RDWR, 0600 );

  // temporary file will be destroy on close() call
  unlink( tmpname );

  free( tmpname );
  if( fd < 0 )
    perror( "open" );
  else
    break;
}

// now go on to use the file ...

...


// @@PLEAC@@_8.2
//------------------------------------------------------------------
/*
  using external program : wc -l
*/
#include <stdio.h>
#include <stdlib.h> // system(), exit(); malloc(), free()
#include <string.h> // strlen()
#include <errno.h> // errno

...

char file[100] = argv[1]; // a pathname
char * command;

// we format the shell command
command = malloc( (strlen("wc -l ") + 1) + (strlen(file) + 1) );
sprintf(command, "%s %s", "wc -l", argv[1]);

// bad solution

system(command);

// good solution : using popen() instead of system()

FILE * message;
if( (message = popen(command, "r")) == NULL ) {
  fprintf(stderr, "error popen %d\n", errno);
  exit(1);
}

char wc_output[100];
fgets(wc_output, sizeof wc_output, message);
fprintf(stdout, "%s", wc_output);

pclose(message);
  
free(command);

...

//------------------------------------------------------------------
/*
    using standard C library
*/
#include <stdio.h>

...

char file[100] = argv[1]; // a pathname
FILE * fp;

if( (fp = fopen( file, "r" )) == NULL ) {
  perror("fopen");
  exit(1);
}

int line = 0;
char ch;

while ( (ch = getc(fp)) != EOF )
 if (ch == '\n')
   line++;

fprintf(stdout, "number of lines : %d\n", line );
fclose(fp);

...

//------------------------------------------------------------------
/*
    using system calls
    /!\ fast implementation, the whole file is in memory
*/
#include <stdio.h>
#include <stdlib.h>

#include <fcntl.h> // open()
#include <sys/stat.h> 
#include <sys/types.h>
#include <unistd.h> // lseek(), close()

...

char file[100] = argv[1]; // a pathname
int fd;

fd = open(file, O_RDONLY);

size_t size;

size = lseek(fd, 0, SEEK_END ); // size of the buffer
  
char * buffer;
buffer = malloc(size);
  
lseek(fd, 0, SEEK_SET); // back to the beginning of the file

if( (read(fd, buffer, size)) != size ) {
  perror("read");
  exit(1);
}
  
close(fd);

int line = 0;

int i;
for( i = 0; i < size; i++ ) {
  if(buffer[i] == '\n')
    line++;
}

free(buffer);
  
fprintf(stdout, "number of lines : %d\n", line );

...


// @@PLEAC@@_9.0
//------------------------------------------------------------------
#include <stdio.h> // perror(), fprintf()
#include <unistd.h> // stat(), fstat(), lstat()
#include <sys/stat.h> // struct stat

...

struct stat entry;
if( stat("/usr/bin/vi", &entry) < 0 )
  perror("");
if( S_ISREG(entry.st_mode) )
  fprintf( stderr, "file\n" );

...

//------------------------------------------------------------------
#include <stdio.h> // perror(), fprintf()
#include <unistd.h> // stat(), fstat(), lstat()
#include <sys/stat.h> // struct stat

...

struct stat entry;
if( stat("/usr/bin", &entry) < 0 )
  perror("");
if( S_ISDIR( entry.st_mode) )
  fprintf( stderr, "directory\n" );

...

//------------------------------------------------------------------
// we can't access the inode of a file with a stream as parameter
// we need to pass a file descriptor parameter to fstat
#include <stdio.h> // perror(), fprintf()
#include <unistd.h> // stat(), fstat(), lstat()
#include <sys/stat.h> // struct stat
#include <fcntl.h> //open()

...

struct stat entry;
int fd; // file descriptor
FILE * fp;  // stream

if((fd = open("/etc/group", O_RDONLY)) < 0)
  perror("");

if( fstat(fd, &entry) < 0 )
  perror("");
  
if((fp = fdopen(fd, "r" )) == NULL ) // we attach the file descriptor to a stream
  perror("");

...

//------------------------------------------------------------------
#include <stdio.h> // perror()
#include <unistd.h> // stat(), fstat(), lstat()
#include <sys/stat.h> // struct stat
#include <sys/types.h> // off_t

...
  
struct stat entry;

time_t ctime;
off_t size;

if( stat("/usr/bin/vi", &entry) < 0 )
  perror("");

ctime = entry.st_ctime;
size = entry.st_size;
//fprintf( stdout, "ctime: %ld\nsize: %ld\n", ctime, size );
  
...  

//------------------------------------------------------------------
// No equivalent in C ANSI/POSIX/GNU for -T (file is a text file)?
/*
# -s for filesize (test if nonzero)
unless (-s F && -T _) {
  die "$filename doesn't have text in it.\n";
}
*/

//------------------------------------------------------------------
#include <stdio.h>
#include <dirent.h> // struct dirent, opendir(), readdir(), closedir()
#include <sys/types.h> // DIR type

...

DIR * dir;
struct dirent * entry;

dir = opendir("/usr/bin");
if( dir == NULL )
  perror("");
while((entry = readdir(dir)) != NULL)
  fprintf(stdout, "Inside /usr/bin is something called %s\n", entry->d_name);
fprintf(stdout, "\n");
closedir(dir);

...


// @@PLEAC@@_9.10
//------------------------------------------------------------------

//  we use the XPG version of basename which overrides
//  the GNU version (not portable) if libgen.h is included
//  /!\ do not call basename or dirname with a static string (bugs in glibc)

#include <stdio.h> // fprintf()
#include <stdlib.h> // free()
#include <string.h>  // strdup(), strrchr()
#include <libgen.h>  // basename(), dirname()

...
 char * dir, * file, * ext;
char * tmp_dirname, * tmp_file;
char * path = "/usr/lib/libc.a";

tmp_dirname = strdup(path);
tmp_file = strdup(path);
   dir = dirname(tmp_dirname);
file = basename(tmp_file);
ext = strrchr(path, '.'); // extension as everything after the last '.'

fprintf(stdout, "dir is %s, file is %s, ext is %s\n", dir, file, ext);
// dir is /usr/lib, file is libc.a, ext is .a
 free(tmp_file);
free(tmp_dirname);

...

//------------------------------------------------------------------
#include <stdio.h> // fprintf()
#include <stdlib.h> // free()
#include <string.h>  // strdup()
#include <libgen.h>  // basename(), dirname()

...

char * file, * dir, * tmp_file, * tmp_dirname;
char * path = "/usr/lib/libc.a";

tmp_file = strdup( path );
tmp_dirname = strdup( path );
dir = dirname( tmp_dirname );
file = basename( tmp_file );

fprintf( stdout, "dir is %s, file is %s\n", dir, file );
// dir is /usr/lib, file is libc.a
free(tmp_dirname);
free(tmp_file);
 ...

//------------------------------------------------------------------
// no equivalent in C for fileparse() but we can
//  implement a (very basic) similar function

#include <stdio.h> // fprintf()
#include <stdlib.h> // free()
#include <string.h>  // strdup(), strrchr(), strlen()

typedef struct Pathname_ {
  char * dirname;
  char * filename;
  char * extension;
}Pathname;

void fileparse( const char * path, Pathname * split_path) {
  char * tmp_path, * ptr, * extension;

  tmp_path = strdup(path);
 ptr= strrchr( tmp_path, '/');
  *ptr = '\0';
  ptr++;

  // dirname
  split_path->dirname = strdup(tmp_path);
  // filename
  split_path->filename = malloc(strlen(ptr) + 1);
  strcpy(split_path->filename, ptr);

  // extension
  extension = strrchr(path, '.'); // extension as everything
after the last '.'
  split_path->extension = strdup(extension);

  free(tmp_path);
 return;
}

int main( int argc, char * argv[] ) {

  Pathname fparsed;
  char * path = "/usr/lib/libc.a";
 fileparse(path, &fparsed);
 fprintf(stdout, "dir is %s, file is %s, ext is %s\n",
      fparsed.dirname,
      fparsed.filename,
      fparsed.extension);
  // dir is /usr/lib, file is libc.a, ext is .a
 free(fparsed.dirname);
  free(fparsed.filename);
  free(fparsed.extension);

  return 0;
}

//------------------------------------------------------------------
//  we are Unix centric so no equivalent for fileparse_set_fstype("MacOS");

//------------------------------------------------------------------
char * extension(const char * path){
  char * ext;
  ext = strrchr(path, '.');
  if(ext == NULL)
    return NULL;

  return ext;
}

// fprintf(stdout, "ext is %s\n", extension(path));
// ext is .a

// @@PLEAC@@_10.0
// NOTE: In order to keep the size / verbosity of code examples to a minimum, library function
// calls will generally not include error checking and handling. Example:
//
//     p = malloc(...);                if ((p = malloc(...)) == NULL)
//                                     {
//                                       ... handle error ...
//                                     }
//
// However, any necessary, application-specific error-related code, will still be used. Code
// examples will endeavour, wherever possible, to make use of:
//
// * C99 Features e.g. variable-length arrays, non-const aggregate initialisers
// * GNU Extensions e.g. nested functions, statement expressions
//
// The aim of doing so is to reduce redundancy [i.e. copious examples of older / standard C
// already exist] as well as enhance the information value of each PLEAC example.
//
// Another item worthy of note is the use of writeable 'static local storage' in many custom
// functions. Whilst a commonly-used technique that makes functions self-contained, and easier
// to use [which is precisely why it is used here], it is not viable in multi-threaded code;
// examples need to be suitably modified to work in such code. The section, 'Printing a Date',
// in Chapter 3: Dates and Times, discusses this issue, and provides illustrative examples.

#include <stdio.h>

// Declaring the variable as 'static' ensures it has 'file scope', that is:
// * It may be considered globally accessable within the current source file
// * Is not visible to code defined outside the current file
static int greeted = 0;

int howManyGreetings(void);
void hello(void);

// ------------

int main(void)
{
  hello();

  int greetings = howManyGreetings();

  printf("bye there!, there have been %d greetings so far\n", greetings);
}

// ------------

int howManyGreetings(void)
{
  return greeted;
}

void hello(void)
{
  printf("high there!, this function has been called %d times\n", ++greeted);
}

// @@PLEAC@@_10.1
// Standard C requires that a function be prototyped, hence the name and type of parameters
// must be specified, and the argumemt list in any calls to that function must match the
// parameter list, as illustrated here. 

#include <math.h>

double hypotenuse(double side1, double side2);

// ----

int main(void)
{
  double diag = hypotenuse(3.0, 4.0);
}

// ----

double hypotenuse(double side1, double side2)
{
  return sqrt(pow(side1, 2.0) + pow(side2, 2.0));
}

// ----------------------------

// Standard C does not support the dynamic packaging / unpackaging of arguments, thus it is
// *not* possible to call a function which has, for example, been declared to expect two
// parameters, with a single argument, to to pass it its arguments packed as elements in
// a single array and expect those elements to be 'unpacked' from the array. If the function
// is to be passed an array when called, then it must be declared to expect an array. Put
// simply, the function call must conform to the function declaration and definition

#include <math.h>

double hypotenuse(double sidearr[]);

// ----

int main(void)
{
  double sidearr[] = {3.0, 4.0};
  double diag = hypotenuse(sidearr);
}

// ----

double hypotenuse(double sidearr[])
{
  return sqrt(pow(sidearr[0], 2.0) + pow(sidearr[1], 2.0));
}

// ----------------------------

// Scope doe