1ASCTIME(3P)                POSIX Programmer's Manual               ASCTIME(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       asctime, asctime_r — convert date and time to a string
13

SYNOPSIS

15       #include <time.h>
16
17       char *asctime(const struct tm *timeptr);
18       char *asctime_r(const struct tm *restrict tm, char *restrict buf);
19

DESCRIPTION

21       For asctime(): The functionality described on this  reference  page  is
22       aligned  with the ISO C standard. Any conflict between the requirements
23       described here and the ISO C standard is unintentional. This volume  of
24       POSIX.1‐2017 defers to the ISO C standard.
25
26       The asctime() function shall convert the broken-down time in the struc‐
27       ture pointed to by timeptr into a string in the form:
28
29
30           Sun Sep 16 01:03:52 1973\n\0
31
32       using the equivalent of the following algorithm:
33
34
35           char *asctime(const struct tm *timeptr)
36           {
37               static char wday_name[7][3] = {
38                   "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
39               };
40               static char mon_name[12][3] = {
41                   "Jan", "Feb", "Mar", "Apr", "May", "Jun",
42                   "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
43               };
44               static char result[26];
45
46               sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n",
47                   wday_name[timeptr->tm_wday],
48                   mon_name[timeptr->tm_mon],
49                   timeptr->tm_mday, timeptr->tm_hour,
50                   timeptr->tm_min, timeptr->tm_sec,
51                   1900 + timeptr->tm_year);
52               return result;
53           }
54
55       However,   the   behavior   is   undefined   if   timeptr->tm_wday   or
56       timeptr->tm_mon  are  not  within  the  normal  ranges  as  defined  in
57       <time.h>, or if timeptr->tm_year  exceeds  {INT_MAX}-1990,  or  if  the
58       above  algorithm would attempt to generate more than 26 bytes of output
59       (including the terminating null).
60
61       The tm structure is defined in the <time.h> header.
62
63       The asctime(),  ctime(),  gmtime(),  and  localtime()  functions  shall
64       return  values  in one of two static objects: a broken-down time struc‐
65       ture and an array of type char.  Execution of any of the functions  may
66       overwrite the information returned in either of these objects by any of
67       the other functions.
68
69       The asctime() function need not be thread-safe.
70
71       The asctime_r() function shall convert  the  broken-down  time  in  the
72       structure  pointed  to  by  tm  into a string (of the same form as that
73       returned by asctime(), and with the same undefined behavior when  input
74       or  output  is out of range) that is placed in the user-supplied buffer
75       pointed to by buf (which shall contain at  least  26  bytes)  and  then
76       return buf.
77

RETURN VALUE

79       Upon  successful  completion,  asctime()  shall return a pointer to the
80       string.  If the function is unsuccessful, it shall return NULL.
81
82       Upon successful completion, asctime_r() shall return  a  pointer  to  a
83       character  string  containing the date and time. This string is pointed
84       to by the argument buf.  If the  function  is  unsuccessful,  it  shall
85       return NULL.
86

ERRORS

88       No errors are defined.
89
90       The following sections are informative.
91

EXAMPLES

93       None.
94

APPLICATION USAGE

96       These  functions  are included only for compatibility with older imple‐
97       mentations. They have undefined behavior if the resulting string  would
98       be  too  long,  so the use of these functions should be discouraged. On
99       implementations that do not detect output string length overflow, it is
100       possible  to  overflow  the  output  buffers  in such a way as to cause
101       applications to fail, or possible  system  security  violations.  Also,
102       these  functions  do  not  support  localized date and time formats. To
103       avoid these problems, applications should use  strftime()  to  generate
104       strings from broken-down times.
105
106       Values  for  the  broken-down time structure can be obtained by calling
107       gmtime() or localtime().
108
109       The asctime_r() function is thread-safe and shall return  values  in  a
110       user-supplied  buffer instead of possibly using a static data area that
111       may be overwritten by each call.
112

RATIONALE

114       The standard developers decided to mark the asctime()  and  asctime_r()
115       functions  obsolescent  even  though asctime() is in the ISO C standard
116       due to the possibility of buffer overflow. The ISO C standard also pro‐
117       vides  the  strftime()  function which can be used to avoid these prob‐
118       lems.
119

FUTURE DIRECTIONS

121       These functions may be removed in a future version.
122

SEE ALSO

124       clock(), ctime(), difftime(), gmtime(),  localtime(),  mktime(),  strf‐
125       time(), strptime(), time(), utime()
126
127       The Base Definitions volume of POSIX.1‐2017, <time.h>
128
130       Portions  of  this text are reprinted and reproduced in electronic form
131       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
132       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
133       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
134       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
135       event of any discrepancy between this version and the original IEEE and
136       The  Open Group Standard, the original IEEE and The Open Group Standard
137       is the referee document. The original Standard can be  obtained  online
138       at http://www.opengroup.org/unix/online.html .
139
140       Any  typographical  or  formatting  errors that appear in this page are
141       most likely to have been introduced during the conversion of the source
142       files  to  man page format. To report such errors, see https://www.ker
143       nel.org/doc/man-pages/reporting_bugs.html .
144
145
146
147IEEE/The Open Group                  2017                          ASCTIME(3P)
Impressum