C Programming

Asctime() Function in C Language

Time data are calculated from seconds since 00:00:00 UTC on January 1, 1970 GMT or UNIX time. To use this data in a human readable format, you must convert the UNIX time to a time date and then to a string.

In this Linux Hint article, we will explain how to use asctime() to retrieve the time data from the system calendar and convert it to a string. We will explore the theoretical description of the structure of this data tm, the syntax of the function, and its input and output arguments along with the data types that each of them supports. We will then implement the use of this function with practical examples using code snippets and images.

Asctime() Function Syntax in C Language

char * str asctime ( const struct tm* tm_ptr );

Description of the Asctime() Function in the C language

The asctime() function retrieves the information from struct tm which is pointed to by the *tm_ptr pointer, converts it to a string, and returns its pointer in *str.

The format which is returned by this function in the output string is as follows:

"Www Mmm dd hh:mm:ss yyyy \n\0"

Both days and months are represented by the first three letters of their names. The dates are represented by two digits for the days and months and four digits for the year. The string corresponding to str contains a special character \n\0 at the end.

The asctime() function and its variables are defined in the “time.h” header. To use them, we have to include them in our “.c” or “.h” file as follows:

#include <time.h>

How to Get the Local Time in String Format with the Asctime() Function in the C Language

In this example, we will show you step-by-step on how to use the asctime() function to get the Unix time and local time data in the tm structure and then convert it to a string of human-readable characters.

As we explained in the introduction, the system time is calculated from the Unix time. Therefore, we have to get this time first with the time() function in time_t.

In the following snippet, time() gets the Unix time in U_time and prints it to the command console:

#include <stdio.h>

#include <time.h>

void main()
   {
time_tU_time;
U_time = time(NULL);
printf ("UNIX Time: %ld\n", U_time);
   }

The following image displays the UNIX time which is returned in U_time.

Once we obtain the time from UNIX, we need to convert this data to a local or gmt time and store it in the integer structure, tm.

Each integer in this structure represents seconds, minutes, hours, days, etc. Later, we will give a more detailed description of the variables contained in this structure and how you can access each of them.

The data of the tm structure can be the local time in which you get with localtime() or the GMT time with gmtime().

Both functions have the Unix time obtained with U_time as input argument and return the pointer tm_ptr of tm, which we must define beforehand as shown in the following:

#include <stdio.h>

#include <time.h>

void main()
   {
    …
struct tm *tm_ptr;    //Define tm_ptr as a pointer to tm
          …
        }

It is important to note that both the UNIX time in U_time and the tm data are updated each time one of the functions that retrieve this data is called. Otherwise, the data from the last call remains stored in their variables.

In the following code snippet, we see how to retrieve the local time data in the tm structure using the localtime() function. When you call this function, you must pass the time from UNIX as the input argument and the pointer to tm as the output argument.

tm_ptr = localtime ( &U_time );

In this way, we already converted the time from UNIX to the local time and stored it in the tm struct. We only need to convert this data to a string with asctime().

In the following snippet, we see the code to get the time from UNIX. Calculate this data and store it in tm struct. Then, we use asctime() to convert the integers of the struct which is pointed to by *tm_ptr to strings.

This function returns the string which is pointed to by *str_ptr in its output argument.

Finally, we output the obtained string to the command console using printf().

#include <stdio.h>

#include <time.h>

void main()
   {
time_tU_time;        //Define U_time as output of time()
  const char*str_ptr;  //Define the pointer of the string  
struct tm *tm_ptr;    //Define tm_ptr as a pointer to tm

U_time = time( NULL ); //We get the UTC time in U_time

tm_ptr = localtime ( &U_time ); //We get the local time in tm
str_ptr = asctime ( tm_ptr );       //convert tm to string
printf ( "Local time is: %s\n", str_ptr );
   }

The following image shows the result of this code:

 

The Tm Struct

The tm structure and the time_t and clock_t variables are predefined structures and data types in the “time.h” header and are used to store the results that are returned by some of the defined functions there.

Let us now look at the structure of the tm integer and the names of the individual variables that make it up:

structtm {
inttm_sec; // Seconds (0-61)
inttm_min; // Minutes (0-59)
inttm_hour; // Hours (0-23)
inttm_mday; // Day (1-31)
inttm_mon; // Month (0-11)
inttm_year; // Years since 1970
inttm_wday; // Weekday (0-6; Sunday = 0)
inttm_yday; // Day of the year (0-365)
inttm_isdst; // Summer time 1=Yes; 0=No; -1=Undefined
          };

Conclusion

In this Linux Hint article, we explained how to get the Unix system time and convert it to a calendar string with asctime() step by step. We also briefly explained the additional functions that are needed to process and retrieve this data, as well as how to handle the tm and time data. We hope that you found this article useful. For more Linux Hint articles on the C language, use the search engine on our website.

About the author

Julio Cesar

Julio Cesar is a 42 years old programmer with 8 years of experience in embedded systems development, 6 years developing firmware for user interfaces in C and C++. Additionally he has 2 years of experience developing scripts for network devices and 3 years as developer of high frequency PCB (Printed Circuit Board).