Date and Time Basics in the C Computer Language
Part 33 of the Complete C Course
Foreword: Date and Time Basics in the C Computer Language
By: Chrysanthus Date Published: 22 Jun 2024
Introduction
Broken Down Time
An example of time is, "Sun Sep 16 01:03:52 1973". This time can be broken down into week-day (Sun), month (Sep), month day (16), hour (01), etc. When time is given in the form of its individual items, it is said to be Broken Down Time. The struct tm type (class) in the time library is used to hold the broken down time. The tm structure contains at least the following members (in any order). The semantics of the members and their normal ranges are expressed in the comments.
int tm_sec; //seconds after the minute -- [0, 59]
int tm_min; //minutes after the hour -- [0, 59]
int tm_hour; //hours since midnight -- [0, 23]
int tm_mday; //day of the month -- [1, 31]
int tm_mon; //months since January -- [0, 11]
int tm_year; //years since 1900
int tm_wday; // days since Sunday -- [0, 6]
int tm_yday; // days since January 1 -- [0, 365]
int tm_isdst; // Daylight Saving Time flag
Note:
- The value of tm_isdst is positive if Daylight Saving Time is in effect, zero if Daylight Saving Time is not in effect, and negative if the information is not available. Daylight Saving Time is applicable to countries in the Northern Hemisphere.
- The possible numbers for the day (tm_mday) in the month, begins from 1 to 31, and not 0 to 30.
- The number for the month (tm_mon), begins from 0 to 11, and not 1 to 12.
- The value for tm_year is an int, not the four-digit year. It is an int resulting from the subtraction of the year 1900, from the four-digit year, at the time of interest.
In the following program, the items of the time, "Sun Sep 16 01:03:52 1973" are assigned to the member identifiers of a struct tm object. Read and test it.
#include <stdio.h>
#include <time.h>
int main(int argc, char *argv[])
{
struct tm timeItems;
timeItems.tm_sec = 52;
timeItems.tm_min = 03;
timeItems.tm_hour = 01;
timeItems.tm_mday = 16;
timeItems.tm_mon = 8;
timeItems.tm_year = 1973 - 1900;
timeItems.tm_wday = 0;
timeItems.tm_isdst = 0;
printf("%i ", timeItems.tm_wday); printf("%i ", timeItems.tm_mon);
printf("%i ", timeItems.tm_mday); printf("%i:", timeItems.tm_hour);
printf("%i:", timeItems.tm_min); printf("%i ", timeItems.tm_sec);
printf("%i ", timeItems.tm_year); printf("%i\n", timeItems.tm_isdst);
return 0;
}
The output is, "0 8 16 1:3:52 73 0" and correct.
Converting struct tm Object to String
#include <time.h>
char * asctime(const struct tm *timeptr);
The asctime() function converts the broken-down time in the structure pointed to by timeptr, into a string in the form,
"Sun Sep 16 01:03:52 1973\n\0"
where '\n' sends the cursor to the next line below, at the output, and using the following tables:
| 0 | Sun |
| 1 | Mon |
| 2 | Tue |
| 3 | Wed |
| 4 | Thu |
| 5 | Fri |
| 6 | Sat |
| 0 | Jan |
| 1 | Feb |
| 2 | Mar |
| 3 | Apr |
| 4 | May |
| 5 | Jun |
| 6 | Jul |
| 7 | Aug |
| 8 | Sep |
| 9 | Oct |
| 10 | Nov |
| 11 | Dec |
The asctime() function returns a pointer to the string. Read and test the following code:
#include <stdio.h>
#include <time.h>
int main(int argc, char *argv[])
{
struct tm timeItems;
timeItems.tm_sec = 52;
timeItems.tm_min = 03;
timeItems.tm_hour = 01;
timeItems.tm_mday = 16;
timeItems.tm_mon = 8;
timeItems.tm_year = 1973 - 1900;
timeItems.tm_wday = 0;
timeItems.tm_isdst = 0;
struct tm *timeItemsPtr = &timeItems;
char *const strPtr = asctime(timeItemsPtr);
printf("%s", strPtr);
return 0;
}
The output is,
"Sun Sep 16 01:03:52 1973"
without the quotes. It is better to use the predefined asctime() function to convert the tm struct members to one string, than to attempt to do it manually, with possible errors, as was attempted in the previous program. Note the two lines around the bottom of the code above, that are essential for the conversion.
The time_t object type and the mktime() Function
#include <time.h>
time_t mktime(struct tm *timeptr);
It takes a pointer to a struct tm object as argument, and not the identifier of the struct tm object. So in the code, the pointer has to be obtain before it can be used as argument in this function call. The programmer does not really need to know the nature of the time_t object.
Another useful function in the library is the ctime() function. Its synopsis is:
#include <time.h>
char * ctime(const time_t *timer);
The ctime() function converts the calendar time pointed to by timer, to local time in the form of a string. The ctime function returns a pointer to the string. Read and test the following program that makes use of the mktime() and ctime() predefined functions:
#include <stdio.h>
#include <time.h>
int main(int argc, char *argv[])
{
struct tm timeItems;
timeItems.tm_sec = 52;
timeItems.tm_min = 03;
timeItems.tm_hour = 01;
timeItems.tm_mday = 16;
timeItems.tm_mon = 8;
timeItems.tm_year = 1973 - 1900;
timeItems.tm_wday = 0;
timeItems.tm_isdst = 0;
struct tm *timeItemsPtr = &timeItems;
time_t timeTObj = mktime(timeItemsPtr);
time_t *timeTObjPtr = &timeTObj;
char * const strPtr = ctime(timeTObjPtr);
printf("%s", strPtr);
return 0;
}
The output is, "Sun Sep 16 01:03:52 1973" as expected.
Format of String Output
Sun Sep 16 01:03:52 1973
The format begins with the day of the week in three letters. This is followed by a space and then the month in three letters. This is followed by a space and the integer day of the month in two digits. This is followed by a space and then the hour in two digits. This is followed by a colon and then the minutes in two digits. This is followed by a colon and then the seconds in two digits. This is followed by a space and then the year in four digits.
Current Computer Date and Time
#include <time.h>
time_t time(time_t *timer);
The time function determines the current calendar time. The time function returns the implementation's best approximation to the current calendar time, as a time_t object. Read and test the following program that uses the time() and ctime() functions to obtain the current date and time, as a string:
#include <stdio.h>
#include <time.h>
int main(int argc, char *argv[])
{
time_t currTime = time(NULL);
time_t *currTimePtr = &currTime;
char * const curStrPtr = ctime(currTimePtr);
printf("%s", curStrPtr);
return 0;
}
The output should be something like:
Sat Jun 10 15:21:47 2025
Note that the argument to the time() function, for the current time, is "NULL". This date/time is read from the computer internal clock.