Namespaces
Variants
Views
Actions

Difference between revisions of "c/chrono/asctime"

From cppreference.com
< c‎ | chrono
m (r2.7.3) (Robot: Adding de, es, fr, it, ja, pt, ru, zh)
m ('.')
 
(26 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
{{c/title| asctime}}
+
{{c/title|asctime|asctime_s}}
 
{{c/chrono/navbar}}
 
{{c/chrono/navbar}}
−
{{ddcl | header=time.h |
+
{{dcl begin}}
−
char* asctime( const tm* time_ptr );
+
{{dcl header|time.h}}
 +
{{dcl rev multi|num=1|dcl1=
 +
char*                asctime( const struct tm* time_ptr );
 +
|since2=c23|dcl2=
 +
[[deprecated]] char* asctime( const struct tm* time_ptr );
 
}}
 
}}
 +
{{dcl|num=2|since=c11|
 +
errno_t asctime_s( char* buf, rsize_t bufsz, const struct tm* time_ptr );
 +
}}
 +
{{dcl end}}
  
−
Converts given calendar time {{c|tm}} to a textual representation.
+
@1@ Converts given calendar time {{lc|tm}} to a textual representation of the following fixed 25-character form: {{c|Www Mmm dd hh:mm:ss yyyy\n}}
−
The resulting string has the following format:
+
*{{tt|Www}} - three-letter English abbreviated day of the week from {{c|time_ptr->tm_wday}}, one of {{tt|Mon}}, {{tt|Tue}}, {{tt|Wed}}, {{tt|Thu}}, {{tt|Fri}}, {{tt|Sat}}, {{tt|Sun}}.
 +
*{{tt|Mmm}} - three-letter English abbreviated month name from {{c|time_ptr->tm_mon}}, one of {{tt|Jan}}, {{tt|Feb}}, {{tt|Mar}}, {{tt|Apr}}, {{tt|May}}, {{tt|Jun}}, {{tt|Jul}}, {{tt|Aug}}, {{tt|Sep}}, {{tt|Oct}}, {{tt|Nov}}, {{tt|Dec}}.
 +
*{{tt|dd}} - 2-digit day of the month from {{c|timeptr->tm_mday}} as if printed by {{lc|sprintf}} using {{c|%2d}}.
 +
*{{tt|hh}} - 2-digit hour from {{c|timeptr->tm_hour}} as if printed by {{lc|sprintf}} using {{c|%.2d}}.
 +
*{{tt|mm}} - 2-digit minute from {{c|timeptr->tm_min}} as if printed by {{lc|sprintf}} using {{c|%.2d}}.
 +
*{{tt|ss}} - 2-digit second from {{c|timeptr->tm_sec}} as if printed by {{lc|sprintf}} using {{c|%.2d}}.
 +
*{{tt|yyyy}} - 4-digit year from {{c|timeptr->tm_year + 1900}} as if printed by {{lc|sprintf}} using {{c|%4d}}.
 +
@@ The behavior is undefined if any member of {{c|*time_ptr}} is outside its normal range.
 +
@@ The behavior is undefined if the calendar year indicated by {{c|time_ptr->tm_year}} has more than 4 digits or is less than the year 1000.
 +
@@ The function does not support localization, and the newline character cannot be removed.
 +
@@ The function modifies static storage and is not thread-safe.
  
−
{{source|Www Mmm dd hh:mm:ss yyyy}}
+
{{rrev|since=c23|
−
 
+
@@This function is deprecated and should not be used in new code.
−
*{{tt|Www}} - the day of the week (one of {{tt|Mon}}, {{tt|Tue}}, {{tt|Wed}}, {{tt|Thu}}, {{tt|Fri}}, {{tt|Sat}}, {{tt|Sun}}).
+
}}
−
*{{tt|Mmm}} - the month (one of {{tt|Jan}}, {{tt|Feb}}, {{tt|Mar}}, {{tt|Apr}}, {{tt|May}}, {{tt|Jun}}, {{tt|Jul}}, {{tt|Aug}}, {{tt|Sep}}, {{tt|Oct}}, {{tt|Nov}}, {{tt|Dec}}).
+
@2@ Same as {{v|1}}, except that the message is written into user-provided storage {{c|buf}}, which is guaranteed to be null-terminated, and the following errors are detected at runtime and call the currently installed [[c/error/set_constraint_handler_s|constraint handler]] function:
−
*{{tt|dd}} - the day of the month
+
:* {{c|buf}} or {{c|time_ptr}} is a null pointer
−
*{{tt|hh}} - hours
+
:* {{c|bufsz}} is less than 26 or greater than {{lc|RSIZE_MAX}}
−
*{{tt|mm}} - minutes
+
:* not all members of {{c|*time_ptr}} are within their normal ranges
−
*{{tt|ss}} - seconds
+
:* the year indicated by {{c|time_ptr->tm_year}} is less than 0 or greater than 9999.
−
*{{tt|yyyy}} - years
+
:{{c/ext1 availability|asctime_s}}
−
 
+
−
The function does not support localization.
+
  
 
===Parameters===
 
===Parameters===
−
{{param list begin}}
+
{{par begin}}
−
{{param list item | time_ptr | pointer to a {{c|tm}} object specifying the time to print}}
+
{{par|time_ptr|pointer to a {{lc|tm}} object specifying the time to print}}
−
{{param list end}}
+
{{par|buf|pointer to a user-supplied buffer at least 26 bytes in length}}
 +
{{par|bufsz|size of the user-supplied buffer}}
 +
{{par end}}
  
 
===Return value===
 
===Return value===
−
 
+
@1@ pointer to a static null-terminated character string holding the textual representation of date and time as described above. The string may be shared between {{tt|asctime}} and {{lc|ctime}}, and may be overwritten on each invocation of any of those functions.
−
pointer to a static null-terminated character string holding the textual representation of date and time. The string may be shared between {{tt|asctime}} and {{c|ctime}}, and may be overwritten on each invocation of any of those functions.
+
@2@ zero on success, non-zero on failure, in which case {{c|buf[0]}} is set to zero (unless {{c|buf}} is a null pointer or {{c|bufsz}} is zero or greater than {{lc|RSIZE_MAX}}).
  
 
===Notes===
 
===Notes===
−
This function returns a pointer to static data and is not thread-safe. POSIX marks this function obsolete and recommends {{c|strftime}} instead.
+
{{tt|asctime}} returns a pointer to static data and is not thread-safe. POSIX marks this function obsolete and recommends {{lc|strftime}} instead. The C standard also recommends {{lc|strftime}} instead of {{tt|asctime}} and {{tt|asctime_s}} because {{tt|strftime}} is more flexible and locale-sensitive.
  
−
The behavior is undefined if the output string would be longer than 25 characters, if {{tt|timeptr->tm_wday}} or {{tt|timeptr->tm_mon}} are not within the expected ranges, or if {{tt|timeptr->tm_year}} exceeds {{c|INT_MAX-1990}}.
+
POSIX limits undefined behaviors only to when the output string would be longer than 25 characters, when {{c|timeptr->tm_wday}} or {{c|timeptr->tm_mon}} are not within the expected ranges, or when {{c|timeptr->tm_year}} exceeds {{c|INT_MAX - 1990}}.
  
−
Some implementations handle {{c|1=timeptr->tm_mday==0}} as meaning the last day of the preceding month.
+
Some implementations handle {{c|1=timeptr->tm_mday == 0}} as meaning the last day of the preceding month.
  
 
===Example===
 
===Example===
 
{{example
 
{{example
−
|
+
|code=
−
| code=
+
#define __STDC_WANT_LIB_EXT1__ 1
−
| output=
+
#include <stdio.h>
 +
#include <time.h>
 +
 
 +
int main(void)
 +
{
 +
    struct tm tm = *localtime(&(time_t){time(NULL)});
 +
    printf("%s", asctime(&tm)); // note implicit trailing '\n'
 +
 
 +
#ifdef __STDC_LIB_EXT1__
 +
    char str[26];
 +
    asctime_s(str, sizeof str, &tm);
 +
    printf("%s", str);
 +
#endif
 +
}
 +
|p=true|output=
 +
Tue May 26 21:51:50 2015
 +
Tue May 26 21:51:50 2015
 
}}
 
}}
 +
 +
===References===
 +
<!--
 +
{{ref std c23}}
 +
{{ref std|section=7.29.3.1|title=The asctime function|p=TBD}}
 +
{{ref std|section=K.3.8.2.1|title=The asctime_s function|p=TBD}}
 +
{{ref std end}}
 +
-->
 +
{{ref std c17}}
 +
{{ref std|section=7.27.2.1|title=The asctime function|p=287}}
 +
{{ref std|section=K.3.8.2.1|title=The asctime_s function|p=453-454}}
 +
{{ref std end}}
 +
{{ref std c11}}
 +
{{ref std|section=7.27.2.1|title=The asctime function|p=392-393}}
 +
{{ref std|section=K.3.8.2.1|title=The asctime_s function|p=624-625}}
 +
{{ref std end}}
 +
{{ref std c99}}
 +
{{ref std|section=7.23.3.1|title=The asctime function|p=341-342}}
 +
{{ref std end}}
 +
{{ref std c89}}
 +
{{ref std|section=4.12.3.1|title=The asctime function}}
 +
{{ref std end}}
  
 
===See also===
 
===See also===
−
{{dcl list begin}}
+
{{dsc begin}}
−
{{dcl list template | c/chrono/dcl list ctime}}
+
{{dsc inc|c/chrono/dsc ctime}}
−
{{dcl list template | c/chrono/dcl list strftime}}
+
{{dsc inc|c/chrono/dsc strftime}}
−
{{dcl list see cpp | cpp/chrono/c/asctime}}
+
{{dsc see cpp|cpp/chrono/c/asctime}}
−
{{dcl list end}}
+
{{dsc end}}
  
−
[[de:c/chrono/asctime]]
+
{{langlinks|ar|cs|de|es|fr|it|ja|ko|pl|pt|ru|tr|zh}}
−
[[es:c/chrono/asctime]]
+
−
[[fr:c/chrono/asctime]]
+
−
[[it:c/chrono/asctime]]
+
−
[[ja:c/chrono/asctime]]
+
−
[[pt:c/chrono/asctime]]
+
−
[[ru:c/chrono/asctime]]
+
−
[[zh:c/chrono/asctime]]
+

Latest revision as of 16:57, 17 June 2024

 
C
 
Date and time utilities
Functions
Time manipulation
(C11)
(C23)
Format conversions
asctimeasctime_s
(deprecated in C23)(C11)
(deprecated in C23)(C11)
(C95)
(C23)(C11)
(C23)(C11)
Constants
Types
(C11)
 
Defined in header <time.h>
(1)
char*                asctime( const struct tm* time_ptr );
 (until C23)
[[deprecated]] char* asctime( const struct tm* time_ptr );
 (since C23)
errno_t asctime_s( char* buf, rsize_t bufsz, const struct tm* time_ptr );
 (2) (since C11)
1) Converts given calendar time tm to a textual representation of the following fixed 25-character form: Www Mmm dd hh:mm:ss yyyy\n
  • Www - three-letter English abbreviated day of the week from time_ptr->tm_wday, one of Mon, Tue, Wed, Thu, Fri, Sat, Sun.
  • Mmm - three-letter English abbreviated month name from time_ptr->tm_mon, one of Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.
  • dd - 2-digit day of the month from timeptr->tm_mday as if printed by sprintf using %2d.
  • hh - 2-digit hour from timeptr->tm_hour as if printed by sprintf using %.2d.
  • mm - 2-digit minute from timeptr->tm_min as if printed by sprintf using %.2d.
  • ss - 2-digit second from timeptr->tm_sec as if printed by sprintf using %.2d.
  • yyyy - 4-digit year from timeptr->tm_year + 1900 as if printed by sprintf using %4d.
The behavior is undefined if any member of *time_ptr is outside its normal range.
The behavior is undefined if the calendar year indicated by time_ptr->tm_year has more than 4 digits or is less than the year 1000.
The function does not support localization, and the newline character cannot be removed.
The function modifies static storage and is not thread-safe.
This function is deprecated and should not be used in new code.
 (since C23)
2) Same as (1), except that the message is written into user-provided storage buf, which is guaranteed to be null-terminated, and the following errors are detected at runtime and call the currently installed constraint handler function:
  • buf or time_ptr is a null pointer
  • bufsz is less than 26 or greater than RSIZE_MAX
  • not all members of *time_ptr are within their normal ranges
  • the year indicated by time_ptr->tm_year is less than 0 or greater than 9999.
As with all bounds-checked functions, asctime_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <time.h>.

Contents

[edit] Parameters

time_ptr - pointer to a tm object specifying the time to print
buf - pointer to a user-supplied buffer at least 26 bytes in length
bufsz - size of the user-supplied buffer

[edit] Return value

1) pointer to a static null-terminated character string holding the textual representation of date and time as described above. The string may be shared between asctime and ctime, and may be overwritten on each invocation of any of those functions.
2) zero on success, non-zero on failure, in which case buf[0] is set to zero (unless buf is a null pointer or bufsz is zero or greater than RSIZE_MAX).

[edit] Notes

asctime returns a pointer to static data and is not thread-safe. POSIX marks this function obsolete and recommends strftime instead. The C standard also recommends strftime instead of asctime and asctime_s because strftime is more flexible and locale-sensitive.

POSIX limits undefined behaviors only to when the output string would be longer than 25 characters, when timeptr->tm_wday or timeptr->tm_mon are not within the expected ranges, or when timeptr->tm_year exceeds INT_MAX - 1990.

Some implementations handle timeptr->tm_mday == 0 as meaning the last day of the preceding month.

[edit] Example

Run this code
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <time.h>
 
int main(void)
{
    struct tm tm = *localtime(&(time_t){time(NULL)});
    printf("%s", asctime(&tm)); // note implicit trailing '\n'
 
#ifdef __STDC_LIB_EXT1__
    char str[26];
    asctime_s(str, sizeof str, &tm);
    printf("%s", str);
#endif
}

Possible output: 

Tue May 26 21:51:50 2015
Tue May 26 21:51:50 2015

[edit] References

  • C17 standard (ISO/IEC 9899:2018):
  • 7.27.2.1 The asctime function (p: 287)
  • K.3.8.2.1 The asctime_s function (p: 453-454)
  • C11 standard (ISO/IEC 9899:2011):
  • 7.27.2.1 The asctime function (p: 392-393)
  • K.3.8.2.1 The asctime_s function (p: 624-625)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.23.3.1 The asctime function (p: 341-342)
  • C89/C90 standard (ISO/IEC 9899:1990):
  • 4.12.3.1 The asctime function

[edit] See also

(deprecated in C23)(C11)
 converts a time_t object to a textual representation
(function) [edit]
converts a tm object to custom textual representation
(function) [edit]
C++ documentation for asctime
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=c/chrono/asctime&oldid=172468"