asctime(), asctime64() — Convert time to character string

Standards

Standards / Extensions C or C++ Dependencies
ISO C
POSIX.1
XPG4
XPG4.2
C99
Single UNIX Specification, Version 3
Language Environment®
 both  

Format

#include <time.h>

char *asctime(const struct tm *timeptr);
#define _LARGE_TIME_API
#include <time.h>

char asctime64(const struct tm *timeptr);

General description

Converts time stored as a structure, pointed to by timeptr, to a character string. The timeptr value can be obtained from a call to gmtime() or localtime(). Both functions return a pointer to a tm structure defined in time.h — Time and date.

The string result that asctime() produces contains exactly 26 characters and has the format: 
   "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n"
The following is an example of the string returned: 
   Fri Jun 16 02:03:55 2006\n\0
Notes:
  1. The calendar time returned by a call to the time() function begins at epoch, which was at 00:00:00 Coordinated Universal Time (UTC), January 1, 1970.
  2. The asctime() function uses a 24-hour clock format.
  3. The days are abbreviated to: Sun, Mon, Tue, Wed, Thu, Fri, and Sat.
  4. The months are abbreviated to: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec.
  5. All fields have a constant width.
  6. Dates with only one digit are preceded either with a zero or a blank space.
  7. The newline character (\n) and the NULL character (\0) occupy the last two positions of the string.
  8. The asctime(), ctime(), and other time functions can use a common, statically allocated buffer for holding the return string. Each call to one of these functions may possibly destroy the result of the previous call.

The function asctime64() will behave exactly like asctime() except it will support a structured date beyond 03:14:07 UTC on January 19, 2038 with a limit of 23:59:59 UTC on December 31, 9999.

Returned value

If successful, asctime() returns a pointer to the resulting character string.

If the function is unsuccessful, it returns NULL.

Example

CELEBA06 
/* CELEBA06                                      

   This example polls the system clock and prints a message                     
   giving the current time.                                                     
                                                                                
 */                                                                             
#include <time.h>                                                               
#include <stdio.h>                                                              
                                                                                
int main(void)                                                                  
{                                                                               
    struct tm *newtime;                                                         
    time_t ltime;                                                               
                                                                                
        /* Get the time in seconds */                                           
    time(&ltime);                                                               
        /* Break it down & store it in the structure tm */                      
    newtime = localtime(&ltime);                                                
                                                                                
        /* Print the local time as a string */                                  
    printf("The current date and time are %s",                                  
             asctime(newtime));                                                 
}
Output 
The current date and time are Fri Jun 16 13:29:51 2006

Related information