Namespaces
Variants
Views
Actions

Difference between revisions of "c/chrono/ctime"

From cppreference.com
< c‎ | chrono
(templatization)
m (fix numbering)
 
(7 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
{{dcl begin}}
 
{{dcl begin}}
 
{{dcl header|time.h}}
 
{{dcl header|time.h}}
−
{{dcl|num=1| char* ctime( const time_t* time ); }}
+
{{dcl rev multi|num=1|dcl1=
−
{{dcl|num=2|notes={{mark since c11}}|
+
char*               ctime( const time_t* timer );
−
errno_t ctime_s(char *buffer, rsize_t bufsz, const time_t *time);
+
|since2=c23|dcl2=
 +
[[deprecated]] char* ctime( const time_t* timer );
 +
}}
 +
{{dcl|num=2| since=c11 |
 +
errno_t ctime_s( char *buf, rsize_t bufsz, const time_t* timer );
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
−
@1@ Converts given time since epoch to a calendar local time and then to a textual representation, as if by calling {{c|asctime(localtime(time))}}.
+
@1@ Converts given time since epoch to a calendar local time and then to a textual representation, as if by calling {{c|asctime(localtime(timer))}}{{rev inl|since=c23| or {{c|asctime(localtime_r(timer, &(struct tm){0}))}}}}. {{rev inl|since=c23|This function is deprecated and should not be used in new code.}}
−
@2@ Same as {{v|1}}, except that the function is equivalent to {{c|asctime_s(buffer, bufsz, localtime_s(time, &(struct tm){0}))}}, and the following errors are detected at runtime and call the currently installed [[c/error/set_constraint_handler_s|constraint handler]] function:
+
@2@ Same as {{v|1}}, except that the function is equivalent to {{c|asctime_s(buf, bufsz, localtime_s(timer, &(struct tm){0}))}}, and the following errors are detected at runtime and call the currently installed [[c/error/set_constraint_handler_s|constraint handler]] function:
−
:* {{tt|buffer}} or {{tt|time}} is a null pointer
+
:* {{tt|buf}} or {{tt|timer}} is a null pointer
 
:* {{tt|bufsz}} is less than {{c|26}} or greater than {{lc|RSIZE_MAX}}
 
:* {{tt|bufsz}} is less than {{c|26}} or greater than {{lc|RSIZE_MAX}}
 
:{{c/ext1 availability|ctime_s}}
 
:{{c/ext1 availability|ctime_s}}
Line 30: Line 34:
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | time | pointer to a {{lc|time_t}} object specifying the time to print}}
+
{{par | timer | pointer to a {{lc|time_t}} object specifying the time to print}}
−
{{par | buffer | pointer to an element of a char array of size at least {{tt|bufsz}} }}
+
{{par | buf | pointer to the first element of a char array of size at least {{tt|bufsz}} }}
−
{{par | bufsz | max number of bytes to output, typically the size of the buffer pointed to by {{tt|buffer}} }}
+
{{par | bufsz | max number of bytes to output, typically the size of the buffer pointed to by {{tt|buf}} }}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
@1@ 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 {{lc|ctime}}, and may be overwritten on each invocation of any of those functions.
+
@1@ pointer to a static null-terminated character string holding the textual representation of date and time. The string may be shared between {{lc|asctime}} and {{tt|ctime}}, and may be overwritten on each invocation of any of those functions.
−
@2@ zero on success (in which case the string representation of time has been written out to the array pointed to by {{tt|buffer}}), or non-zero on failure (in which case, the terminating null character is always written to {{c|buffer[0]}} unless {{tt|buffer}} is a null pointer or {{tt|bufsz}} is zero or greater than RSIZE_MAX.
+
@2@ zero on success (in which case the string representation of time has been written out to the array pointed to by {{tt|buf}}), or non-zero on failure (in which case, the terminating null character is always written to {{c|buf[0]}} unless {{tt|buf}} is a null pointer or {{tt|bufsz}} is zero or greater than {{lc|RSIZE_MAX}}.
  
 
===Notes===
 
===Notes===
 
{{tt|ctime}} returns a pointer to static data and is not thread-safe. In addition, it modifies the static {{lc|tm}} object which may be shared with {{lc|gmtime}} and {{lc|localtime}}. POSIX marks this function obsolete and recommends {{lc|strftime}} instead. The C standard also recommends {{lc|strftime}} instead of {{tt|ctime}} and {{tt|ctime_s}} because {{tt|strftime}} is more flexible and locale-sensitive.
 
{{tt|ctime}} returns a pointer to static data and is not thread-safe. In addition, it modifies the static {{lc|tm}} object which may be shared with {{lc|gmtime}} and {{lc|localtime}}. POSIX marks this function obsolete and recommends {{lc|strftime}} instead. The C standard also recommends {{lc|strftime}} instead of {{tt|ctime}} and {{tt|ctime_s}} because {{tt|strftime}} is more flexible and locale-sensitive.
  
−
The behavior of {{tt|ctime}} may be undefined for the values of time_t that result in the string longer than 25 characters (e.g. year 10000).
+
The behavior of {{tt|ctime}} is undefined for the values of {{lc|time_t}} that result in the string longer than 25 characters (e.g. year 10000).
  
 
===Example===
 
===Example===
Line 63: Line 67:
 
#endif
 
#endif
 
}
 
}
 +
| p=true
 
  | output=
 
  | output=
 
Tue May 26 21:51:03 2015
 
Tue May 26 21:51:03 2015
Line 69: Line 74:
  
 
===References===
 
===References===
 +
<!--
 +
{{ref std c23}}
 +
{{ref std | section=7.29.3.2  | title=The ctime function | p=TBD}}
 +
{{ref std | section=K.3.8.2.2 | title=The ctime_s function | p=TBD}}
 +
{{ref std end}}
 +
-->
 +
{{ref std c17}}
 +
{{ref std | section=7.27.3.2  | title=The ctime function | p=287-288}}
 +
{{ref std | section=K.3.8.2.2 | title=The ctime_s function | p=454}}
 +
{{ref std end}}
 
{{ref std c11}}
 
{{ref std c11}}
 
{{ref std | section=7.27.3.2  | title=The ctime function | p=393}}
 
{{ref std | section=7.27.3.2  | title=The ctime function | p=393}}
 
{{ref std | section=K.3.8.2.2 | title=The ctime_s function | p=626}}
 
{{ref std | section=K.3.8.2.2 | title=The ctime_s function | p=626}}
 +
{{ref std end}}
 
{{ref std c99}}
 
{{ref std c99}}
 
{{ref std | section=7.23.3.2  | title=The ctime function | p=342}}
 
{{ref std | section=7.23.3.2  | title=The ctime function | p=342}}
 +
{{ref std end}}
 
{{ref std c89}}
 
{{ref std c89}}
 
{{ref std | section=4.12.3.2  | title=The ctime function}}
 
{{ref std | section=4.12.3.2  | title=The ctime function}}
Line 85: Line 102:
 
{{dsc end}}
 
{{dsc end}}
  
−
[[ar:c/chrono/ctime]]
+
{{langlinks|ar|cs|de|es|fr|it|ja|ko|pl|pt|ru|tr|zh}}
−
[[cs:c/chrono/ctime]]
+
−
[[de:c/chrono/ctime]]
+
−
[[es:c/chrono/ctime]]
+
−
[[fr:c/chrono/ctime]]
+
−
[[it:c/chrono/ctime]]
+
−
[[ja:c/chrono/ctime]]
+
−
[[ko:c/chrono/ctime]]
+
−
[[pl:c/chrono/ctime]]
+
−
[[pt:c/chrono/ctime]]
+
−
[[ru:c/chrono/ctime]]
+
−
[[tr:c/chrono/ctime]]
+
−
[[zh:c/chrono/ctime]]
+

Latest revision as of 22:04, 3 September 2022

 
C
 
Date and time utilities
Functions
Time manipulation
(C11)
(C23)
Format conversions
(deprecated in C23)(C11)
ctimectime_s
(deprecated in C23)(C11)
(C95)
(C23)(C11)
(C23)(C11)
Constants
Types
(C11)
 
Defined in header <time.h>
(1)
char*                ctime( const time_t* timer );
 (until C23)
[[deprecated]] char* ctime( const time_t* timer );
 (since C23)
errno_t ctime_s( char *buf, rsize_t bufsz, const time_t* timer );
 (2) (since C11)
1) Converts given time since epoch to a calendar local time and then to a textual representation, as if by calling asctime(localtime(timer)) or asctime(localtime_r(timer, &(struct tm){0}))(since C23). This function is deprecated and should not be used in new code.(since C23)
2) Same as (1), except that the function is equivalent to asctime_s(buf, bufsz, localtime_s(timer, &(struct tm){0})), and the following errors are detected at runtime and call the currently installed constraint handler function:
  • buf or timer is a null pointer
  • bufsz is less than 26 or greater than RSIZE_MAX
As with all bounds-checked functions, ctime_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>.

The resulting string has the following format: 

Www Mmm dd hh:mm:ss yyyy\n
  • Www - the day of the week (one of Mon, Tue, Wed, Thu, Fri, Sat, Sun).
  • Mmm - the month (one of Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec).
  • dd - the day of the month
  • hh - hours
  • mm - minutes
  • ss - seconds
  • yyyy - years

The function does not support localization.

Contents

[edit] Parameters

timer - pointer to a time_t object specifying the time to print
buf - pointer to the first element of a char array of size at least bufsz
bufsz - max number of bytes to output, typically the size of the buffer pointed to by buf

[edit] Return value

1) pointer to a static null-terminated character string holding the textual representation of date and time. 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 (in which case the string representation of time has been written out to the array pointed to by buf), or non-zero on failure (in which case, the terminating null character is always written to buf[0] unless buf is a null pointer or bufsz is zero or greater than RSIZE_MAX.

[edit] Notes

ctime returns a pointer to static data and is not thread-safe. In addition, it modifies the static tm object which may be shared with gmtime and localtime. POSIX marks this function obsolete and recommends strftime instead. The C standard also recommends strftime instead of ctime and ctime_s because strftime is more flexible and locale-sensitive.

The behavior of ctime is undefined for the values of time_t that result in the string longer than 25 characters (e.g. year 10000).

[edit] Example

Run this code
#define __STDC_WANT_LIB_EXT1__ 1
#include <time.h>
#include <stdio.h>
 
int main(void)
{
    time_t result = time(NULL);
    printf("%s", ctime(&result));
 
#ifdef __STDC_LIB_EXT1__
    char str[26];
    ctime_s(str,sizeof str,&result);
    printf("%s", str);
#endif
}

Possible output: 

Tue May 26 21:51:03 2015
Tue May 26 21:51:03 2015

[edit] References

  • C17 standard (ISO/IEC 9899:2018):
  • 7.27.3.2 The ctime function (p: 287-288)
  • K.3.8.2.2 The ctime_s function (p: 454)
  • C11 standard (ISO/IEC 9899:2011):
  • 7.27.3.2 The ctime function (p: 393)
  • K.3.8.2.2 The ctime_s function (p: 626)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.23.3.2 The ctime function (p: 342)
  • C89/C90 standard (ISO/IEC 9899:1990):
  • 4.12.3.2 The ctime function

[edit] See also

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