Jens Gustedt

Modernize time.h functions v.2 It's about time

The interfaces in time.h are inconsistent, partially underspecified, subject to undetectable overflow, not thread-safe and present security issues. Along the lines of ISO 9945 (POSIX), we propose to modernize the interfaces to avoid these problems.

Changes in v2

-properly distinguish calendar time and elapsed time -the _r functions are not reentrant and may have races if the time environment is changed -avoid to use the tm buffer where it is not allowed -define offset macros for the tm structure -relate the monotonic clock to system suspension -change from pointer to array notation -better explanation why overflow of clock values is a user space problem Contents 1. INTRODUCTION

Problem description

The interfaces in time.h to manipulate time values have grown mostly unattended over the years and present several problems that could be easily avoided with more modern, redesigned interfaces. The main problems are as follows:

(1) The function clock is subject to overflows that are undetectable by its users 1 and has non-standard semantics on one of the major legacy implementations. (2) The function time does not specify the encoding that is used in the time_t type and the resolution of this time has no query interface. There is only the function difftime to obtain the relative difference between two time measurements, but there is no interface to know about the granularity that we can expect. (3) Compared to ISO (and common English) date and time enumeration, the members of the structure tm have offsets that can only be understood as historic artifacts. (4) The function timespec_get has a resolution for which there is no query interface. Its use of time_t is not necessarily consistent with the use of the same type by time.

(5) It is not specified, if the function timespec_get when called with TIME_UTC is sensible to changes of the system clock or not. (Besides that, TIME_UTC is a misnomer.) (6) The standard allows implementations to add more time bases than TIME_UTC but gives no guidance in which direction to go with such new base values. (7) The return value specification of timespec_get does not allow to dissociate different types of errors. (8) The function asctime has undefined behavior when it is called with time values that are out-of-bounds. Since the output format and length for this function is prescribed to the byte, this is an unnecessary loop hole that can easily be fixed. (9) The function ctime has implicit undefined behavior when it is called with an argument that is not presentable as local time.

1 The question whether or not the implementation might detect such overflows is not directly related to that problem. Even if an implementation would detect an overflow (which is a QoI question) the interface provides no reliable means to transmit this information to the caller.

(10) The functions asctime, ctime, gmtime and localtime refer to static state and can thus not thread-safe. In addition, giving write access to a static variable in the program state provides an exploitable attack vector for buffer overflow attacks.

Strategy

Most of these problems have already been addressed by ISO 9945 (POSIX) (after which the most recent addition of timespec_get has been modeled) so we propose a simple and straight forward solution: adopt and adapt the interfaces from there as far as possible.

We do not propose to promote interfaces of Annex K to Clause 7.27, because this would in turn introduce two new major problems:

(1) Annex K interfaces need the infrastructure of constraint handlers. We don't think that the attempt to repair time.h justifies us to force implementations to introduce new infrastructure.

(2) Because of that globally shared infrastructure, Annex K interfaces are inherently threadunsafe.

In addition, the runtime constraints that are covered for the corresponding time functions in Annex K are mostly size constraints of the arrays that are provided as arguments. Such constraints can be expressed in the syntax, and can, for many cases, be detected at compile time. Therefore, in accordance with the C2x charter, we propose to update the existing interfaces syntactically such that they are more friendly to static analysis.

Because the problems and solutions are much intertwined, we propose all these additions in this single paper. For those in WG14 that prefer to have smaller bits and pieces to swallow, we have divided the paper into sections that all have their specific questions (potential straw polls for the committee) at the end, such that WG14 may cherry-pick modifications to the standard as seems fit.

In case of adoption of any of the new functions2 or the changes to the return value of timespec_get we also propose to add a feature test macro __STDC_VERSION_TIME_H__.

Question 0. Shall a feature test macro __STDC_VERSION_TIME_H__ as proposed in N2417 be added to 7.27.1?

PUT THE BOUNDS INTO THE INTERFACES

According to the C2x charter,3 we should aim that interfaces specify the constraints on the corresponding functions as thorough as possible: 15. Application Programming Interfaces (APIs) should be selfdocumenting when possible. In particular, the order of parameters in function declarations should be arranged such that the size of an array appears before the array. The purpose is to allow Variable-Length Array (VLA) notation to be used. This not only makes the code's purpose clearer to human readers, but also makes static analysis easier. Any new APIs added to the Standard should take this into consideration.

In the case of time.h we can already apply this strategy to the existing interfaces to make them analysis friendly. E.g the function 1 time_t mktime ( struct tm * timeptr ) ; can be expressed with the equivalent prototype Modernize time.h functions v.2 N2417:3 1 time_t mktime ( struct tm timeptr [ static 1]) ; that emphasizes on the fact that the function expects a non-null pointer to at least one element as an argument. Such changes (adding static bound constraints) can be added to most of the existing functions in time.h. Since these interfaces are rewritten during compilation, such additions are always compatible with existing code. On the other hand, coding such restrictions into header files allows compilers to diagnose the most flagrant violations of the requirements. In particular, compilers can track pointers they know to be null, and may then diagnose an invalid call to a time.h function.

There is only one of the functions that should not be rewritten with a [static] parameter instead of a pointer, the time function. Here, it is specified that a null pointer is a valid argument. All these changes are straight forward and we refer to the annex for the concrete formulation of that change. Note that changing the specification within the standard for these functions will not force implementations to use exactly this specification, if they fear e.g that their headers would become incompatible for use with C++. 4 The sought effects are merely better documentation and an incentive for implementations to diagnose invalid usages of these interfaces.

Question 1. Shall we adopt [static] array parameter specifications for the time.h header as proposed in N2417?

Question 2. If yes, does WG14 want to see a proposal that changes pointer parameters of library functions to [static] array parameters?

ADD USER HELPER MACROS TO DEAL WITH THE TYPES

The types that are used to represent times have some crude historical oddities and magic constants that can easily be tamed by providing macros to our users. We propose to add two types of macros -Macros to represent the offsets that are needed for the members of the tm structure, for example TIME_TM_YEAR_OFFSET representing the value 1900. -Macros to represent the invalid values of time_t and clock_t.

The text addition for these is boringly simple and can be found in 7.27.1 p2. In addition, we propose to adjust the example in 7.27.2.3 p4 (mktime) with these new constants.

Question 3. Shall we add "offset" macros for the members of the tm structure to the time.h header as proposed in N2417?

Question 4. Shall we add "invalid" macros for the types time_t and clock_t to the time.h header as proposed in N2417?

MAKE THE UB OF CTIME EXPLICIT

In C17, the call ctime(timer) is declared to be functionally equivalent to 1 asctime ( localtime ( timer ) )

This definition has one surprising nob: localtime has conditions under which it returns a null pointer, but asctime is not allowed to receive such a pointer. Such a return happens, if timer cannot be interpreted as local time (for whatever reasons). Thus, ctime is implicitly undefined in that situation.

N2417:4

Jens Gustedt

We see two possibilities to improve that situation:

(1) Make this behavior explicitly undefined; or (2) widen the specification of asctime and impose that it should accept a null pointer and then also would return a null pointer to propagate the error return.

The second approach would only make programs that previously have been (implicitly) undefined, defined. But it would also impose implementations to change their code.

We propose to make that undefined behavior explicit by reformulating a phrase in 7.27.3.2 p2:

:::

The :::::::: calendar ::::: time :::::::: specified ::: by ::::::::: timer[0] :::: shall ::: be :::::::::: convertible ::: to :::: local ::::: time.

Question 5. Shall we add a phrase that spells out the undefined behavior of ctime as proposed in N2417? Question 6. If not, shall we change asctime such that it accepts null pointer arguments?

Avoid UB for asctime

The asctime function writes a textual representation of a broken down time in to a char buffer. Due to the exact output format, the buffer size that is needed is exactly 26. In our proposal (7.27.3.1) we use that fact in two places:

-We change the use of sprintf in the operational specification to snprintf with a second argument set to 26. -Later, we augment the syntactical specification of the newly introduced asctime_r.

The first has the advantage that we then can guarantee that the input buffer will never be accessed out-of-bounds, and that we can get rid of undefined behavior for invalid time values. We propose to replace If any of the members of the broken-down time contain values that are outside their normal ranges,the behavior of the asctime functions is undefined. Likewise, if the calculated year exceeds four digits or is less than the year 1000, the behavior is undefined. by :::

The ::::::: return ::::: value :::::: points :: to :: a :::: zero :::::::::: terminated :::::: string :: of :::::: length :: at ::::: most ::: 25 :::: and ::: no :::: write :::::::: beyond ::: the ::::: 26 th :::: byte ::::::: occurs. :: If :::: any :: of :::: the ::::::::: members :: of :::: the :::::::::::: broken-down :::: time ::::::: contain :::::: values ::::: that ::: are :::::::: outside ::::: their ::::::: normal ::::::: ranges, :: or :: if :::: the :::::::::: calculated :::: year ::::::: exceeds :::: four ::::: digits ::: or :: is :::: less :::: than :::: the :::: year ::::: 1000, :::: the :::::::: returned :::::: string :: is :::: null :::::::::: terminated :::::: within ::: the :::: first ::: 26 ::::: bytes :::: but ::: its :::::::: contents :: is ::::::::: otherwise :::::::::: unspecified. This specification allows implementations not to use the function snprintf for their implemenation if this would be considered too costly (in executable size, for example).

Question 7. Shall we change the specification of asctime to use snprintf and modify the undefined behavior to unspecified behavior as proposed in N2417?

MAKE THE RETURN OF THE CONVERSION FUNCTIONS CONST QUALIFIED

The functions asctime, ctime, gmtime and localtime return pointers to static state and can thus not be thread-safe. In addition, exposing a modifiable static variable in the program state provides an exploitable attack vector for buffer overflow attacks. The corresponding return values of the functions are not even const qualified, but they cannot not be put in a read-only section, anyhow, because their contents is subject to change with different calls.

Modernize time.h functions v.2 N2417:5 So, changing the return types of these functions will not help against malicious overflow attacks but at least it could prevent these buffers from accidental overwrites. Question 8. Shall the return types of functions asctime, ctime, gmtime and localtime be changed to pointer-to const qualified types as as proposed in N2417?

6. ADD CONVERSION FUNCTIONS THAT ARE RELATIVELY THREAD-SAFE ISO 9945 has four simple replacement functions for the conversion functionalities. They are suffixed with _r and just add a pointer to a buffer that is also returned to the parameters. Provided that any of these functions is integrated we propose to add an explicit requirement as a new first paragraph of 7.27.3: ::::::::

Functions ::::: with :: a ::: _r :::::: suffix ::::: place :::: the :::::: result ::: of ::: the :::::::::: conversion ::::: into :::: the :::::: buffer ::::::: referred ::: by :::: buf :::: and ::::::: return ::::: that :::::::: pointer. :::::: These ::::::::: functions :::: and :::: the ::::::::: function :::::::: strftime ::::: shall ::: not ::: be ::::::: subject :: to ::::: data ::::: races, :::::: unless :::: the :::: time ::: or :::::::: calendar ::::: state :: is ::::::: changed :: in :: a :::::::::::: multi-thread ::::::::: execution.

The asctime_r function

We augment the syntactical specification of the newly introduced asctime_r from ISO 9945 by an explicit requirement about the size of the buffer by using [static restrict 26]. In ISO 9945 there is already text that requires this size for the buffer, but there is not syntax to make this detectable.

Question 9. Shall we adopt asctime_r as proposed in N2417?

The localtime_r function

A localtime_r function can be specified easily. To simplify the text, we propose that the operational definition is directly given in terms of asctime_r, see 7.27.3.1.

Question 10. Shall we adopt localtime_r as proposed in N2417?

The ctime_r function

To add the ctime_r function we have to specify in addition how the chaining of localtime_r, asctime and asctime_r is to be performed. For 2.27.3.2 we propose 1 asctime ( localtime_r ( timer , ( struct tm [1]) { 0 }) ) 2 asctime_r ( localtime_r ( timer , ( struct tm

[1]) { 0 }) , buf )
That is, we propose the implicit creation of an otherwise unaccessible temporary object that is used to transfer the broken down time. This allows also to clarify the fact that the ctime functions are not expected to modify the static buffer that would be used for the return of localtime.

Question 11. Shall we adopt ctime_r as proposed in N2417? We propose to add optional macros for these time bases to the standard, such that the names, if defined, bind implementations to a particular semantic. ISO 9945 and ISO 9899 differ slightly in their interfaces, we propose to have macros were we replace a CLOCK prefix by TIME for of the four different clocks defined in ISO 9945. Since these will be generally different from the values provided by ISO 9945 (there the constants have type clockid_t) we can impose that the corresponding values are positive without invalidating components of ISO 9945.

:::::

Time ::::: bases ::::: other ::::: than ::::::::: TIME_UTC ::: are :::::::: optional; ::: all ::::: time ::::: bases :::::::: evaluate ::: to :::::: values ::::::

greater ::::: than :: 0.

Generally, since these functions now can deal with several different time concepts, we found it useful to be a bit more specific about these "times" in 7.27.1 p1.

Elapsed time

ISO 9945 has two different "clocks" for measurement of elapsed time, CLOCK_REALTIME and CLOCK_MONOTONIC. They differ eventually in the starting point of the measurement (epoch vs. boot time) and, more importantly, concerning their behavior when the system time is set:

-CLOCK_REALTIME changes when the clock is set to a new value, e.g if a background time daemon adjusts to a drift indicated by a time servers, or if calendar time is adjusted with a leap second. This is the only clock in ISO 9945 that is mandatory, and as such plays a similar role as TIME_UTC for ISO 9899. -CLOCK_MONOTONIC is guaranteed not to be affected by such changes of the system clock and to measure physical time as perceived by the platform.

Which of these two (if any) would best to model the behavior of current C implementations when using TIME_UTC could be subject to debade. We propose not to go into such discussion, but to leave such details to the implementations. The addition of the macros TIME_REALTIME and TIME_MONOTONIC is straight forward, see 7.27.1 p2. We then propose the additional text in 7.27.2.5 p3: be :::::::: affected :: by :::: any ::::::: imple :::: men :: ta ::::::::::: tion-defined :::::::: functions ::::: that ::: set :::: the :::::: system :::::: time, : if ::::: any; :: it :: is :::::: imple ::::: men :: ta :::::::::: tion-defined :: if :::: this :::: base ::::::::: accounts ::: for :::: time ::::::: during :::::: which :::

the ::::::::: execution :: of ::: the :::::: whole ::::::: system :: is :::::::::: suspended.

Question 13. Shall we adopt TIME_REALTIME as proposed in N2417?

Question 14. Shall we adopt TIME_MONOTONIC as proposed in N2417?

Question 15. Shall we relate TIME_UTC to the new optional time bases as proposed in N2417?

CPU time

In C17, CPU time of a program execution can be measured by means of the clock function.

Unfortunately this functions has several problems, the most sever being that it may overflow without notice. Another disadvantage of clock is that there is one legacy C implementation that gets this function fundamentally wrong when compared to the C standard: it accounts for elapsed (wallclock) time instead of CPU time. This repeatably leads to confusion when code is ported from or to conforming platforms. For these reasons we think that clock is best deprecated and replaced by an appropriate time base for timespec_get. ISO 9945 has two such "clocks" which we propose to adapt to the needs of the C standard. Because implementations might need to dynamically distinguish different values for these bases for concurrent program executions (processes) or threads, the specifications of the values exempts them from being compile time constants and we add in 7.25.1 p3:

:::

The :::::: value ::: of ::::::::::::::::::::::::: TIME_PROCESS_CPUTIME_ID ::::: shall ::: be ::::::::: different ::::: from :::: the ::::::: above ::: and :::::: shall :::: not :::::::: change ::::::: during :::: the :::::: same ::::::::: program ::::::::::: execution. ::::: The ::::::: macro :::::::::::::::::::::: TIME_THREAD_CPUTIME_ID ::::: shall :::: not ::: be ::::::: defined :: if :::: the :::::::::::::: implementation ::::: does :::: not ::::::: support :::::::: threads; :: its :::::: value ::::: shall :: be :::::::: different ::::: from :::: the :::::: above, ::::: shall ::: be ::: the :::::: same ::

for ::: all ::::::::::: invocations :::: from :::: the ::::: same ::::::: thread, :::: and ::: the ::::: value ::::::::: provided ::: for ::: one ::::::: thread :::: shall :::: not :: be ::::: used ::: by : a :::::::: different ::::::: thread :: as ::::: base ::::::::: argument :: of ::::::::::::: timespec_get.

For timespec_get itself the text proposal in 7.27.2.5 is then quite simple:

:::

For ::::: base :::: set :: to :::::::::::::::::::::::: TIME_PROCESS_CPUTIME_ID ::::: and ::::::::::::::::::::::: TIME_THREAD_CPUTIME_ID :::: the ::::: result :: is ::::::: similar, :::: but ::: the :::: call ::::::::: measures ::: the ::::::: amount ::: of :::::::: processor ::::: time :::::::::: associated :::: with ::: the :::::::: program ::::::::: execution ::: or ::::::: thread, ::::::::::: respectively. Calls with TIME_PROCESS_CPUTIME_ID could replace calls of clock, provided we knew the resolution of this time base. Calls with TIME_THREAD_CPUTIME_ID would implement a new feature that allows to distinguish the cost of threads individually.

Question 16. Shall we adopt TIME_PROCESS_CPUTIME_ID as proposed in N2417?

Question 17. Shall we adopt TIME_THREAD_CPUTIME_ID as proposed in N2417?

ADD AN INTERFACE TO QUERY RESOLUTION OF TIME BASES

Already for TIME_UTC, C17 has no interface that would allow to query the resolution of the resulting time. If on the long run we want to replace clock with timespec_get() we have to ensure that we also have a tool that provides a functionality similar to CLOCKS_PER_SECOND. Because of the genericity of timespec_get, the interface to query resolutions should not be a series of macros:

-User functions may have a time base as a parameter, so they cannot decided at compile time which resolution would be to query. -The resolution may not be part of the platform ABI but be dependent of a particular version of the CPU or operating system. -The resolution for a specific time base should not change during program execution. Therefore performance critical code can easily cache these values at program startup or thread startup if they need to.

ISO 9945 has a function that is capable to capture resolutions of predefined bases (which could probably be done with a macro) and also of all implementation-defined bases, the clock_getres function.

We propose to model such a function, timespec_getres, accordingly. The specification is straight forward and can be inspected in the appendix, see the new clause 7.27.2.6 (and also a crossreference for timespec_get in 7.27.2.5 p2).

Question 18. Shall we add function timespec_getres as proposed in N2417?

N2417:8 Jens Gustedt

DEFINE THE RETURN OF THE TIMESPEC_ FUNCTIONS FOR A NON-SUPPORTED BASE

As much as the resolution of a particular time base may not be part of the platform ABI, the whole support of such a base may be subject to conditions that can only be detected at runtime. The easiest way to deal with such situations is to provide well-specified error returns to functions that use time bases. ISO 9945 uses errno to distinguish different error returns, and in particular a value EINVAL for this particular error. We propose to stay with the same error codes, which implies to add EINVAL to errno.h (7.5 p2).

Question 19. Shall we add the return value -EINVAL to timespec_getres if it is called with a non-supported base as proposed in N2417?

ALLOW TIMESPEC_GET TO DIFFERENTIATE ERROR RETURNS

The timespec_get can fail for different reasons, such as an invalid time base or an overflow. Currently, such errors can only be modeled with one return value, 0. ISO 9945 also only has one explicit error return (-1) but will then distinguish different errors by changing errno. We don't think that we should follow the lead here an introduce the dependency of a complicated thread specific state. Instead we should widen the possible return values to negative values, which could encode the negative of the value that would otherwise be found in errno. Again, the specification is straight forward and can be inspected in the appendix, see the clauses 7.27.2.5 p5 and 7.26.2.6 p3.

Question 20. Shall we change the possible error returns of function timespec_get (and timespec_getres if adopted) to allow negative values as proposed in N2417?

If the answer is yes, we can to a similar addition as for timespec_getres.

Question 21. Shall we change the return of timespec_get to -EINVAL if it is called with a non-supported base as proposed in N2417?

RECOMMEND CONSISTENCY BETWEEN THE DIFFERENT TIME INTERFACES

As mentioned above there are several consistency issues between different interfaces. So we propose to add a "Recommended practice" section to timespec_get that encourages to have clock and time consistent with their respective counterparts for timespec_get. We also add a recommendation to have the global and the thread-wise CPU time consistent, such that the sum of the thread-wise times should be the same as the global CPU time. The exact wording is 7.27.2.5 p6.

Question 22. Shall we add a recommendation for consistency between the legacy interfaces and timespec_get as proposed in N2417?

Question 23. Shall we add a recommendation for consistency amoung the CPU time interfaces of timespec_get as proposed in N2417?

12. DEPRECATE CLOCK As has been observed over the last revision cycle, the clock function has a severe problem with the fact that its return value can silently overflow without giving any indication to the caller. Additionally there is still a major legacy platform that gets the semantics of it fundamentally wrong by providing elapsed time instead of CPU time. Therefore we think that clock should just be phased out. The proposed changes to 7.27.2.1 add a recommendation to use the new interface.

Question 24. Should we make clock obsolescent as proposed in N2417?

Modernize time.h functions v.2 N2417:9

DEPRECATE THE UNSAFE CONVERSION FUNCTIONS

The unsafe conversion functions are generally problematic and have to many design flaws. We propose to deprecated them:

Question 25. Should we make asctime, ctime, localtime, and gmtime obsolescent as proposed in N2417?

APPENDIX: PAGES WITH DIFFMARKS OF THE PROPOSED CHANGES

The following page numbers are from the particular snapshot and may vary once the changes are integrated.

__ DATE __

The date of translation of the preprocessing translation unit: a character string literal of the form "Mmm dd yyyy", where the names of the months are the same as those generated by the asctime function, and the first character of dd is a space character if the value is less than 10. If the date of translation is not available, an implementation-defined valid date shall be supplied.

__ FILE __

The presumed name of the current source file (a character string literal). 189)

__ LINE __ The presumed line number (within the current source file) of the current source line (an integer constant). 189)

__ STDC __ The integer constant 1, intended to indicate a conforming implementation.

__ STDC _ HOSTED __ The integer constant 1 if the implementation is a hosted implementation or the integer constant 0 if it is not.

__ STDC _ VERSION __ The integer constant yyyymmL. 190)

__ TIME __ The time of translation of the preprocessing translation unit: a character string literal of the form "hh:mm:ss" as in the time generated by the asctime function :::::::: functions. If the time of translation is not available, an implementation-defined valid time shall be supplied.

Forward references: the asctime function (?? :::::::: functions :::::::: (7.27.3.1).

Environment macros

1

The following macro names are conditionally defined by the implementation:

__ STDC _ ISO _ 10646 __ An integer constant of the form yyyymmL (for example, 199712L). If this symbol is defined, then every character in the Unicode required set, when stored in an object of type wchar _ t, has the same value as the short identifier of that character. The Unicode required set consists of all the characters that are defined by ISO/IEC 10646, along with all amendments and technical corrigenda, as of the specified year and month. If some other encoding is used, the macro shall not be defined and the actual encoding used is implementation-defined.

__ STDC _ MB _ MIGHT _ NEQ _ WC __ The integer constant 1, intended to indicate that, in the encoding for wchar _ t, a member of the basic character set need not have a code value equal to its value when used as the lone character in an integer character constant.

__ STDC _ UTF _ 16 __ The integer constant 1, intended to indicate that values of type char16 _ t are UTF-16 encoded. If some other encoding is used, the macro shall not be defined and the actual encoding used is implementation-defined.

__ STDC _ UTF _ 32 __ The integer constant 1, intended to indicate that values of type char32 _ t are UTF-32 encoded. If some other encoding is used, the macro shall not be defined and the actual encoding used is implementation-defined.

Forward references: common definitions (7.19), unicode utilities (7.28).

Conditional feature macros

1

The following macro names are conditionally defined by the implementation: These functions deal with a :::::::: different ::::::: notions :: of ::::: time: :

processor time , :::::: which :: is ::: the :::::::: amount :: of :::::::::: processing ::::::::: resources :::: that ::: are ::::::::: attributed :: to :::: the :::::::: program ::::::::: execution; :

elapsed time : , :::::: which :: is :::: the ::::: time :::: that :::::::: elapsed :: in :::: the :::::::: physical ::::::::: reference ::::::: system ::::::: during :::: the ::::::::

program ::::::::: execution; :

calendar time : , that represents the current date ( :::: and :::: time according to the Gregorian calendar) and time. Some functions deal with ; :

local time, which is the calendar time expressed for some specific time zone, ; :

-and with Daylight Saving Time, which is a temporary change in the algorithm for determining local time.

The local time zone and Daylight Saving Time are implementation-defined. not :: be :::::::: defined : if :::: the :::::::::::::: implementation ::::: does ::: not :::::::: support ::::::: threads; ::: its ::::: value ::::: shall ::: be :::::::: different :::: from :::: the ::::::

above, ::::: shall :: be :::: the ::::: same ::: for :: all ::::::::::: invocations ::::: from ::: the :::::: same :::::: thread, :::: and :::: the ::::: value ::::::::: provided ::: for :::: one ::::::

thread :::: shall :::: not :: be ::::: used ::: by : a :::::::: different ::::::: thread :: as ::::: base ::::::::: argument :: of :::::::::::::: timespec _ get. :

4

The types declared are which holds the components of a calendar time, called the broken-down time.

5

The range and precision of times representable in clock _ t and time _ t are implementation-defined.

The timespec structure shall contain at least the following members, in any order. The semantics of the members and their normal ranges are expressed in the comments. The tm structure shall contain at least the following members, in any order. The semantics of the members and their normal ranges are expressed in the comments. The value of tm _ isdst is positive if Daylight Saving Time is in effect, zero if Daylight Saving Time is not in effect, and negative if the information is not available.

Time manipulation functions

The clock function

338)

::::::::::::

Implementations ::: can ::::: define ::::::: additional :::: time :::: bases, ::: but ::: are ::: only :::::: required :: to :::::: support : a ::: real :::: time :::: clock. ::: See :::::: "future ::::: library ::::::::

directions" :::::: (7.31.16).

339) The tv _ sec member is a linear count of seconds and might not have the normal semantics of a time _ t. 340) The range [0, 60] for tm _ sec allows for a positive leap second. TIME _ PROCESS _ CPUTIME _ ID ::::::::: whenever :::: that :::::::::::: functionality :: is ::::::: defined ::: by ::: the ::::::::::::::: implementation. :

Forward references: ::: the :::::::::::::: timespec _ get :::::::: function ::::::::: (7.27.2.5). The difftime function computes the difference between two calendar times: time1 -time0.

The difftime function Synopsis

Returns

3

The difftime function returns the difference expressed in seconds as a double. 343) On successful completion, the values of the tm _ wday and tm _ yday components of the structure are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to the ranges indicated above; the final value of tm _ mday is not set until tm _ mon and tm _ year are determined.

The mktime function Synopsis

341)

::

See :::::: "future ::::: library :::::::: directions" ::::::: (7.31.16). 342) This could be due to overflow of the clock _ t type. 343) Thus, a positive or zero value for tm _ isdst causes the mktime function to presume initially that Daylight Saving Time, respectively, is or is not in effect for the specified time. A negative value causes it to attempt to determine whether Daylight Saving Time is in effect for the specified time. If base is TIME _ UTC, the tv _ sec member is set to the number of seconds since an implementation defined :::::: imple :::: men ::: ta ::::::::::: tion-defined : epoch, truncated to a whole value and the tv _ nsec member is set to the integral number of nanoseconds, rounded to the resolution of the system clock. -: If ::::: both :::: are :::::::: defined, ::: the ::::::: results ::: of :::: calls ::::: with ::::: base ::: set ::: to : TIME _ PROCESS _ CPUTIME _ ID ::: and : TIME _ THREAD _ CPUTIME _ ID : , :::: such :::: that ::: the ::::: sum :: of :: all ::::::: thread ::::::: specific ::::::::: processor ::::: times :: is :: as ::::: close ::

to ::: the ::::::::: processor :::: time ::: for :::: the ::::::::: execution :: as :::::::: possible. :

Forward references: ::: the ::::::::::::::::: timespec _ getres :::::::: function ::::::::: (7.27.2.6). Although : a :::::::::::::: struct timespec :::: object :::::::: describes :::: times :::: with ::::::::: nanosecond :::::::: resolution, ::: the ::::::: available ::::::: resolution :: is :::::: system ::::::::

The timespec _ getres function Synopsis

dependent ::: and :::: could :::: even :: be ::::: greater :::: than : 1 :::::: second. Macros that begin with either SIG and an uppercase letter or SIG _ and an uppercase letter may be added to the macros defined in the <signal.h> header.

Atomics <stdatomic.h>

1 Macros that begin with ATOMIC _ and an uppercase letter may be added to the macros defined in the <stdatomic.h> header. Typedef names that begin with either atomic _ or memory _ , and a lowercase letter may be added to the declarations in the <stdatomic.h> header. Enumeration constants that begin with memory _ order _ and a lowercase letter may be added to the definition of the memory _ order type in the <stdatomic.h> header. Function names that begin with atomic _ and a lowercase letter may be added to the declarations in the <stdatomic.h> header.

2

The macro ATOMIC _ VAR _ INIT is an obsolescent feature.

Boolean type and values <stdbool.h>

1

The ability to undefine and perhaps then redefine the macros bool, true, and false is an obsolescent feature.

Integer types <stdint.h>

1 Typedef names beginning with int or uint and ending with _ t may be added to the types defined in the <stdint.h> header. Macro names beginning with INT or UINT and ending with _ MAX, _ MIN, _ WIDTH, or _ C may be added to the macros defined in the <stdint.h> header.

Input/output <stdio.h>

1 Lowercase letters may be added to the conversion specifiers and length modifiers in fprintf and fscanf. Other characters may be used in extensions.

2

The use of ungetc on a binary stream where the file position indicator is zero prior to the call is an obsolescent feature.

General utilities <stdlib.h>

1 Function names that begin with str or wcs and a lowercase letter may be added to the declarations in the <stdlib.h> header.

2

Invoking realloc with a size argument equal to zero is an obsolescent feature.

String handling <string.h>

1 Function names that begin with str, mem, or wcs and a lowercase letter may be added to the declarations in the <string.h> header. The following 629 ::: 643 : identifiers or keywords match these patterns and have particular semantics provided by this document.

:

  If ::::: base ::: is :::::::::::::: TIME_REALTIME ::: the ::::::::: behavior :: is :::: the ::::::: similar, ::::: only ::::: that ::: the :::::: result ::: is ::::::: affected :: by ::::::: imple :::: men :: ta ::::::::::: tion-defined :::::::: functions ::::: that ::: set ::: the ::::::: system ::::: time, :: if :::: any. :: If :::::::: functions :::: that ::: set :::: the ::::::: system :::: time :::: are :::::::: provided, :: it :: is ::::::: imple :::: men :: ta ::::::::::: tion-defined :: if :::: they ::::: affect ::::: base ::::::::: TIME_UTC. :::: For :::::::::::::: TIME_MONOTONIC :::: the :::::::: reference ::::: point ::::: may :: or ::::: may ::: not ::: be :::: the ::::: same :::::: epoch ::: or :::: any ::::: other :::::: imple :::: men ::: ta ::::::::::: tion-defined :::: time :::::: point; ::::: this ::::: point :::: shall :::: not ::::::: change ::::::: during ::: the :::::::: program ::::::::: execution ::::: and ::: the :::::: result ::::: shall :::: not ::

  The :::::::: feature :::: test :::::: macro ::::::::::::::::::::::::::__ STDC _ VERSION _ TIME _ H __:::::::: expands ::: to :::: the :::::: token ::::::::: yyyymmL. :::: The :::::: other :::::: macros :::::::: defined ::: are NULL ::::::::: (described ::: in ::::: 7.19); :: ::: :::::::::::::CLOCKS _ PER _ SECwhich expands to an expression with type clock _ t (described below) that is the number per second of the value returned by the clock function; and are :: a :::::::: constant ::::::::::: expressions ::: of ::::: value ::: -1 ::::: and :::: type ::::::::: clock _ t :::: and ::::::: time _ t :::::::::: (described ::::::: below) ::::::::::: respectively; :::::: offsets ::: for :::: the ::::: fields :: of ::: the ::: tm ::::::::: structure ::::::::: (described ::::::: below) :: ::: ::::::::::::::::: TIME _ TM _ SEC _ OFFSET : ::: // :: 0 :: ::: ::::::::::::::::: TIME _ TM _ MIN _ OFFSET : ::: // :: 0 :: ::: :::::::::::::::::: TIME _ TM _ HOUR _ OFFSET ::: // :: 0 :: ::: :::::::::::::::::: TIME _ TM _ MDAY _ OFFSET ::: // :: 0 :: ::: ::::::::::::::::: TIME _ TM _ MON _ OFFSET : ::: // :: 1 :: ::: :::::::::::::::::: TIME _ TM _ YEAR _ OFFSET ::: // ::::: 1900 :: ::: :::::::::::::::::: TIME _ TM _ WDAY _ OFFSET ::: // :: 0 :: ::: :::::::::::::::::: TIME _ TM _ YDAY _ OFFSET ::: // :: 1 ::::: which :::: are :::::: integer :::::::: constant ::::::::::: expressions :::::::: suitable ::: for ::: use :: in :::: #if ::::::::::::: preprocessing ::::::::: directives ::::: with :::::: values :: of :::: type :::: int :: as :::::::::: indicated; ::: and ::::: time ::::: bases ::: for :::::::::::::: timespec _ get :::::::::::: representable :: in :::: int : which expands to an integer constant greater than 0 that designates the UTC time base. ::: are ::::::: integer ::::::: constant ::::::::::: expressions :::::::: suitable ::: for ::: use :: in :::: #if ::::::::::::: preprocessing :::::::::: directives, :::: and :: ::: :::::::::::::::::::::: TIME _ PROCESS _ CPUTIME _ ID :: ::: ::::::::::::::::::::: TIME _ THREAD _ CPUTIME _ ID working draft -September 3, 2019 ISO/IEC 9899:202x (E) ::::: which ::::: may ::: not ::: be ::::::::: constants. 338) 3 :::: Time :::::: bases ::::: other ::::: than TIME _ UTC :: are ::::::::: optional; ::: all :::: time :::::: bases :::::::: evaluate :: to ::::::: values ::::::: greater :::: than :: 0. ::: If ::::::: defined, : TIME _ REALTIME :::: and TIME _ MONOTONIC :::: have :::::::: different ::::::: values, ::: but : TIME _ UTC :::: may ::::: share :::: one :: of ::::: these ::::::: values. ::::: The ::::: value ::: of TIME _ PROCESS _ CPUTIME _ ID :::: shall ::: be :::::::: different ::::: from :::: the :::::: above :::: and :::: shall :::: not :::::: change ::::::: during ::: the :::::: same :::::::: program ::::::::: execution. ::::: The :::::: macro TIME _ THREAD _ CPUTIME _ ID :::: shall :::

  339) time _ t tv _ sec; // whole seconds --≥ 0 long tv _ nsec; // nanoseconds --[0, 999999999]

  340) int tm _ sec; // seconds after the minute --[0, 60] int tm _ min; // minutes after the hour --[0, 59] int tm _ hour; // hours since midnight --[0, 23] int tm _ mday; // day of the month --[1, 31] int tm _ mon; // months since January --[0, 11] int tm _ year; // years since 1900 int tm _ wday; // days since Sunday --[0, 6] int tm _ yday; // days since January 1 --[0, 365] int tm _ isdst; // Daylight Saving Time flag

  determines the processor time used. : It :: is ::: an ::::::::::: obsolescent ::::::: feature. 341) Returns 3 The clock function returns the implementation's best approximation to the processor time used by the program since the beginning of an implementation-defined era related only to the program invocation. To determine the time in seconds, the value returned by the clock function should be divided by the value of the macro CLOCKS _ PER _ SEC. If the processor time used is not available, the function returns the value (clock _ t)(-1) ::::::::::::::: CLOCK _ INVALID . If the value cannot be represented, the function returns an unspecified value. 342) ::::::::::::::::::::: Recommended practice 4 ::::::::: Programs ::::::: should :::::: prefer :::: the :::: use ::: of :::: the :::::::::::::: timespec _ get ::::::::: function ::::: with :: a :::::: base :::::::::: argument ::: of : :::::::::::::::::::::::::

1

  #include <time.h> time _ t mktime(struct tm * timeptr); :: ::: :::::: time _ t :::::: mktime : ( :::::: struct ::: tm ::: ts : [ :::::: static :::: 1]) : ; Description 2 The mktime function converts the broken-down time, expressed as local time, in the structure pointed to by timeptr :::::: ts[0] into a calendar time value with the same encoding as that of the values returned by the time function. The original values of the tm _ wday and tm _ yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated above.

  :::::::::: timespec _ get : ( :::::: struct ::::::::: timespec ::: ts : [ :::::: static :::: 1], ::: int ::::: base : ) : ; Description 2 The timespec _ get function sets the interval pointed to by ts ::::: ts[0] : to hold the current calendar time :::: time ::::: value : based on the specified time base. ::: For ::: all :::::::::: supported :::::: bases, ::: the :::::::::: resolution :: of :::: the :::::::: returned :::: time :::::: values :: is ::::::: imple :::: men :: ta ::::::::::: tion-defined :::: and :::: can :: be :::::::: queried :::: with ::::::::::::::::: timespec _ getres. : 3

  base :: is : TIME _ REALTIME :::the :::::::: behavior :: is :::: the ::::::: similar, ::::: only :::: that ::: the :::::: result :: is :::::::: affected :: by ::::::: imple ::::: men-::ta ::::::::::: tion-defined :::::::: functions ::::: that ::: set ::: the ::::::: system ::::: time, :: if :::: any. :: If ::::::::: functions :::: that :::: set ::: the ::::::: system :::: time :::: are :::::::::provided, :: it :: is :::::: imple :::: men :: ta ::::::::::: tion-defined :: if ::::: they ::::: affect ::::: base : TIME _ UTC : . :::: For : TIME _ MONOTONIC ::: the :::::::: reference ::::: point :::: may ::: or :::: may ::: not ::: be ::: the ::::: same :::::: epoch :: or :::: any ::::: other :::::: imple :::: men ::: ta ::::::::::: tion-defined :::: time :::::: point; ::: this ::::: point ::::: shall ::: not ::::::: change ::::::: during ::: the :::::::: program ::::::::: execution :::: and ::: the ::::: result ::::: shall ::: not ::: be ::::::: affected ::: by :::: any :::::: imple ::::: men :: ta ::::::::::: tion-defined :::::::: functions :::: that ::: set :::: the ::::::: system ::::: time, :: if :::: any; :: it :: is :::::: imple ::::: men ::: ta ::::::::::: tion-defined :: if ::: this ::::: base :::::::: accounts ::: for :::: time ::::::: during :::::: which ::: the ::::::::: execution ::: of ::: the :::::: whole :::::: system :: is ::::::::::: suspended. 345) 4 ::: For ::::: base ::: set :: to TIME _ PROCESS _ CPUTIME _ ID :::: and TIME _ THREAD _ CPUTIME _ ID ::: the :::::: result : is ::::::: similar, :::: but ::: the ::: call ::::::::: measures :::: the ::::::: amount ::: of ::::::::: processor :::: time :::::::::: associated ::::: with ::: the :::::::: program :::::::::: execution :: or ::::::: thread, ::::::::::: respectively. : Returns 5 If the timespec _ get function is successful, : it returns the nonzero ::::::: positive : value base; :: if :::: base :: is :::: not ::::::::: supported :: it ::::::: returns-EINVAL ; : otherwise, it returns zero. ::::::: another ::::: value :::: less ::::: than :: or ::::: equal ::: to :::: zero. The ::::::::: following ::::::: should ::: be ::::::::: consistent ::::::::: whenever :::::::: possible: : -::: The ::::::: results :: of :::: calls ::::: with ::::: base ::: set :: to TIME _ UTC ::: and ::: the :::::: return ::::::: values :: of ::::: time. : -: If :::::::: defined, ::: the ::::::: results :: of :::: calls ::::: with ::::: base TIME _ PROCESS _ CPUTIME _ ID ::: and ::: the :::::: return :::::: values ::: of :::::: clock. :

  ::::::::::::: timespec _ getres : ( :::::: struct ::::::::: timespec ::: ts : [ :::::: static ::: 1], :::: int ::::: base : ) : ; The : timespec _ getres function ::::: stores :::: the :::::: imple ::::: men ::: ta ::::::::::: tion-defined ::::::::: resolution :: of :::: the :::: time ::::::::: provided :: by :::: the ::::::::::::: timespec _ get :::::::: function ::: for ::::: base :: in ::::::: ts[0]. :::: For :::: each ::::: fixed :::::: value :: of ::::: base, :::: the ::::: result ::::: shall ::: be :::::::: invariant ::::::: during ::: the :::::::: program :::::::::: execution. ::::::: Returns 344) :::::::

  Thus, ::: the :::::: values ::: that ::: are ::::::: returned ::::: with ::::::: argument : TIME _ REALTIME ::are ::::::: calendar ::::: times, ::::::: whereas :::::::: differences ::: of ::::::::::measurements :::: with TIME _ MONOTONIC :::::: represent :::::: elapsed :::: time.

  with TIME _ and an uppercase letter may be added to the macros in the <time.h> header. :::The ::::::: macros ::::::::::::::: TIME _ REALTIME, :::::::::::::::: TIME _ MONOTONIC, :::::::::::::::::::::::::: TIME _ PROCESS _ CPUTIME _ ID :::: and :::::::::::::::::::::::: TIME _ THREAD _ CPUTIME _ ID :::: may ::::::: become ::::::::::: mandatory :: in :::::: future :::::::: editions :: of :::: this :::::::: standard. : 2 :::The ::::::::: functions ::::::::: asctime, :::::: ctime, :::::::: gmtime, :::: and :::::::::: localtime ::: are ::::::::::: obsolescent :::::::: features. § 7

Date and time <time.h> 7.27.1 Components of time

  The header <errno.h> defines several macros, all relating to the reporting of error conditions. ERANGE which expand to integer constant expressions with type int, distinct positive values, and which are suitable for use in #if preprocessing directives; and errno which expands to a modifiable lvalue 214) that has type int and thread local storage duration, the value of which is set to a positive error number by several library functions. If a macro definition is suppressed in order to access an actual object, or a program defines an identifier with the name errno, the behavior is undefined.

	ISO/IEC 9899:202x (E) ISO/IEC 9899:202x (E)	working draft -September 3, 2019 working draft -September 3, 2019	C2x..time-C2x n2417 C2x..time-C2x n2417
	7.5 Errors <errno.h> 7.27
	1

__ STDC _ ANALYZABLE

__

The integer constant 1, intended to indicate conformance to the specifications in Annex L (Analyzability). 2 ::: The ::::::: macros ::: are : :: ::: :::: EDOM :: ::: :::::: EILSEQ :: ::: :::::: EINVAL :: ::: ::::::

1

The header <time.h> defines several macros, and declares types and functions for manipulating time. Many :::::

  or d128 may be added to the <math.h> header. The cr prefix is intended to indicate a correctly rounded version of the function.

	n2417 C2x..time-C2x	working draft -September 3, 2019	ISO/IEC 9899:202x (E)
	cracosh	cratanh		crexp10	crlog1p	crrootn
	cracospi	cratanpi		crexp2m1	crlog2p1	crrsqrt
	cracos	cratan		crexp2	crlog2	crsinh
	crasinh	crcompoundn	crexpm1	crlogp1	crsinpi
	crasinpi	crcosh		crexp	crlog	crsin
	crasin	crcospi		crhypot	crpown	crtanh
	cratan2pi	crcos		crlog10p1	crpowr	crtanpi
	cratan2	crexp10m1	crlog10	crpow	crtan
	and the same names suffixed with f, l, d32, d64, 7.31.9 Signal handling <signal.h>
	1

_ clear atomic _ flag _ clear _ explicit ATOMIC _ FLAG _ INIT atomic _ flag _ test _ and _ set atomic _ flag _ test _ and _ set _ explicit atomic _ init atomic

	_ Alignas __ alignas _ is _ defined _ Alignof __ alignof _ is _ defined _ Atomic atomic _ bool ATOMIC _ BOOL _ LOCK _ FREE atomic _ char atomic _ char16 _ t ATOMIC _ CHAR16 _ T _ LOCK _ FREE atomic _ char32 _ t ATOMIC _ CHAR32 _ T _ LOCK _ FREE ATOMIC _ CHAR _ LOCK _ FREE atomic _ compare _ exchange _ strong atomic _ compare _ exchange _ strong _ explicit atomic _ compare _ exchange _ weak atomic _ compare _ exchange _ weak _ explicit atomic _ exchange atomic _ exchange _ explicit atomic _ fetch _ atomic _ fetch _ add atomic _ fetch _ add _ explicit atomic _ fetch _ and atomic _ fetch _ and _ explicit atomic _ fetch _ or atomic _ fetch _ or _ explicit atomic _ fetch _ sub atomic _ fetch _ sub _ explicit atomic _ fetch _ xor atomic _ fetch _ xor _ explicit atomic _ flag atomic _ load ATOMIC _ LLONG _ LOCK _ FREE atomic _ llong atomic _ is _ lock _ free atomic _ intptr _ t atomic _ intmax _ t ATOMIC _ INT _ LOCK _ FREE atomic _ int _ least8 _ t atomic _ int _ least64 _ t atomic _ int _ least32 _ t atomic _ int _ least16 _ t atomic _ int _ fast8 _ t atomic _ int _ fast64 _ t atomic _ int _ fast32 _ t atomic _ int _ fast16 _ t atomic _ flag _ int	atomic _ load _ explicit atomic _ long ATOMIC _ LONG _ LOCK _ FREE ATOMIC _ POINTER _ LOCK _ FREE atomic _ ptrdiff _ t atomic _ schar atomic _ short ATOMIC _ SHORT _ LOCK _ FREE atomic _ signal _ fence atomic _ size _ t atomic _ store atomic _ store _ explicit atomic _ thread _ fence atomic _ uchar atomic _ uint atomic _ uint _ fast16 _ t atomic _ uint _ fast32 _ t atomic _ uint _ fast64 _ t atomic _ uint _ fast8 _ t atomic _ uint _ least16 _ t atomic _ uint _ least32 _ t atomic _ uint _ least64 _ t atomic _ uint _ least8 _ t atomic _ uintmax _ t atomic _ uintptr _ t atomic _ ullong atomic _ ulong atomic _ ushort ATOMIC _ VAR _ INIT atomic _ wchar _ t ATOMIC _ WCHAR _ T _ LOCK _ FREE _ Bool __

bool _ true _ false _ are _ defined cnd _ broadcast cnd _ destroy cnd _ init cnd _ signal cnd

  The following 1188 :::: 1194 : identifiers or keywords are not covered by the above and have particular semantics provided by this document.

		n2417 C2x..time-C2x	working draft -September 3, 2019	ISO/IEC 9899:202x (E)
		totalorderf totalorderl totalordermag	UINTPTR _ WIDTH UINT _ WIDTH __ VA _ ARGS __
		totalordermagd128 totalordermagd32	wcscat wcscat _ s
		totalordermagd64	wcschr
		totalordermagf	wcscmp
		totalordermagl	wcscoll
		toupper towctrans	wcscpy wcscpy _ s
		towlower	wcscspn
	1	_ t cnd _ timedwait cnd _ wait _ Complex _ Complex _ I wcsftime wcslen wcsncat wcsncat _ s wcsncmp wcsncpy wcsncpy _ s wcsnlen _ s wcspbrk wcsrchr wcsrtombs wcsrtombs _ s wcsspn wcsstr wcsto wcstod wcstod128 wcstod32 wcstod64 wcstof wcstoimax wcstok wcstok _ s wcstol wcstold wcstoll wcstombs wcstombs _ s wcstoul wcstoull wcstoumax wcsxfrm _ WIDTH __ cplusplus __ DATE __ J.6.2 Particular identifiers or keywords towupper tss _ create tss _ delete tss _ dtor _ t tss _ get tss _ set tss _ t UINT16 _ C UINT16 _ MAX uint16 _ t UINT32 _ C UINT32 _ MAX uint32 _ t UINT64 _ C UINT64 _ MAX uint64 _ t UINT8 _ C UINT8 _ MAX uint8 _ t uint _ fast16 _ t uint _ fast32 _ t uint _ fast64 _ t uint _ fast8 _ t uint _ least16 _ t uint _ least32 _ t uint _ least64 _ t uint _ least8 _ t UINT _ MAX UINTMAX _ C UINTMAX _ MAX uintmax _ t UINTMAX _ WIDTH UINTPTR _ MAX uintptr _ t DBL _ DECIMAL _ DIG DBL _ DIG DBL _ EPSILON DBL _ HAS _ SUBNORM DBL _ MANT _ DIG abort acosd32 abort _ handler _ s acosd64 DBL _ MAX abs acosf DBL _ MAX _ 10 _ EXP acos acosh DBL _ MAX _ EXP DBL _ MIN acosd128 acoshd128	acoshd32 acoshd64 acoshf acoshl acosl
		504 § J.6.2	Portability issues Portability issues	§ J.6.1

Proposed are asctime_r, ctime_r, localtime_r, gmtime_r, and timespec_getres.

See http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2086.htm

But they could easily use conditional compilation with __cplusplus to avoid such problems.

189) The presumed source file name and line number can be changed by the #line directive. 190) See Annex M for the values in previous revisions. The intention is that this will remain an integer constant of type long int that is increased with each revision of this document.

The value of errno in the initial thread is zero at program startup (the initial value of errno in other threads is an indeterminate value), but is never set to zero by any library function.215) The value of errno may be set to nonzero by a library function call whether or not there is an error, provided the use of errno is not documented in the description of the function in this document.

Additional macro definitions, beginning with E and a digit or E and an uppercase letter, 216) may also be specified by the implementation.214) The macro errno need not be the identifier of an object. It might expand to a modifiable lvalue resulting from a function call (for example, * errno() ).215) Thus, a program that uses errno for error checking would set it to zero before a library function call, then inspect it before a subsequent library function call. Of course, a library function can save the value of errno on entry and then set it to zero, as long as the original value is restored if errno's value is still zero just before the return. 216) See "future library directions" (7.31.3).

#include <stdio.h> #include <time.h> static const char * const wday[] = { "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "-unknown-" }; struct tm time _ str; / * .. :: ::: ::::::

printf ::

(" ::: July ::: 4, :::::: 2001, :::: was :: a :: % : s : , :: % ::: dth :::: day ::: of :::: the :::: year : \ : n :: ", :: ::: :: ::: ::::

wday : [ : ts : . ::::::: tm _ wday :: ], ::: ts : . ::::::: tm _ wday :: + ::::::::::::::::::: supported :: it ::::::: returns-EINVAL ; :::::::::: otherwise, :: it ::::::: returns ::::::: another ::::: value :::: less ::::: than :: or ::::: equal ::: to :::: zero. :

Time conversion functions

1 Except for the function ::::::::: Functions :::: with :: a :: _ r :::::: suffix ::::: place ::: the :::::: result :: of ::: the ::::::::::: conversion :::: into ::: the :::::: buffer :::::::

referred ::: by :::: buf :::: and :::::: return :::: that :::::::: pointer. :::::: These ::::::::: functions :::: and ::: the :::::::: function :::::::::: strftime :::: shall :::: not ::: be ::::::

subject :: to ::::: data ::::: races, :::::: unless :::: the :::: time :: or ::::::::: calendar :::: state :: is :::::::: changed :: in :: a :::::::::::: multi-thread ::::::::: execution. 346) 2 :::::::::::

Obsolescent :::::::: functions ::::::::: asctime, ::::::: ctime, ::::::: gmtime, :::: and :::::::::: localtime :::: are ::: the ::::: same :: as ::::: their :::::::::::: counterparts :::::::

suffixed ::::: with :::

_ r. 347)

::

In ::::: place :: of :::: the :::::::::: parameter :::: buf , these functions each return ::: use : a pointer to one of two types of static objects: a : a ::::: static :::::: object :::: and ::::::: return :: it: :::: one ::: or :::: two : broken-down time structure ::::::::: structures :::: (for ::::::: gmtime :::: and ::::::::::: localtime) or an array of char :::::::::: (commonly ::::: used ::: by :::::::: asctime ::: and ::::::: ctime). Execution of any of the functions that return a pointer to one of these object types ::::: static :::::: objects : may overwrite the information in any object of the same type pointed to by the value returned from any previous call to any of them and the :::: one :: of ::::: these ::::::::: functions :::: that :::: uses :::: the ::::: same :::::: object. :::::: These functions are not ::::::::

reentrant :::: and ::: are ::: not : required to avoid data races with each other. The implementation shall behave as if no other library functions call these functions. [3] = { "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" }; static const char mon _ name [12][3] = { "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" }; static char result [ that ::: state ::: by :::::::: setlocale :: or :: by ::::: means :: of ::::: imple :::: men :: ta :::::::: tion-defined ::::::: functions :::: may ::::::: constitute ::::: races.

The asctime functions Synopsis

347)

::

See :::::: "future ::::: library :::::::: directions" The :::::: return :::::: value :::::: points :: to :: a :::: zero ::::::::::: terminated :::::: string :: of :::::: length :: at ::::: most ::: 25 :::: and ::: no ::::: write ::::::: beyond :::: the ::: 26 th ::::: byte ::::::: occurs. If any of the members of the broken-down time contain values that are outside their normal ranges, 348) the behavior of the is undefined. Likewise, :: or if the calculated year exceeds four digits or is less than the year 1000, the behavior is undefined :::::::: returned :::::: string : is :::: null ::::::::::: terminated :::::: within ::: the :::: first ::: 26 ::::: bytes ::: but ::: its :::::::: contents :: is ::::::::: otherwise ::::::::::: unspecified.

Returns 4

The asctime functions returns :::::

return : a pointer to the string. The ctime functions returns :::::: return the pointer returned by the asctime function :::::::: functions : with that broken-down time as argument.

The ctime functions Synopsis

Forward references: the localtime function (?? ::::::::: functions ::::::: (7.27.3.4). The gmtime functions returns :::::: return a pointer to the broken-down time, or a null pointer if the specified time cannot be converted to UTC. The strftime function places characters into the array pointed to by s as controlled by the string pointed to by format. The format shall be a multibyte character sequence, beginning and ending in its initial shift state. The format string consists of zero or more conversion specifiers and ordinary multibyte characters. A conversion specifier consists of a % character, possibly followed by an E or O modifier character (described below), followed by a character that determines the behavior of the conversion specifier. All ordinary multibyte characters (including the terminating null character) are copied unchanged into the array. If copying takes place between objects that overlap, the behavior is undefined. No more than maxsize characters are placed into the array.

The gmtime functions Synopsis

The localtime functions Synopsis

3

Each conversion specifier shall be replaced by appropriate characters as described in the following list. The appropriate characters shall be determined using the %C is replaced by the year divided by 100 and truncated to an integer, as a decimal number (00-99).

[tm _ year] %d is replaced by the day of the month as a decimal number (01-31). [tm _ mday]

%D is equivalent to "%m/%d/%y". [tm _ mon, tm _ mday, tm _ year] § 7.27.3.5 Library 7.31.17 Threads <threads.h> 1 Function names, type names, and enumeration constants that begin with either cnd _ , mtx _ , thrd _ , or tss _ , and a lowercase letter may be added to the declarations in the <threads.h> header.

7.31.18 Extended multibyte and wide character utilities <wchar.h> 1 Function names that begin with wcs and a lowercase letter may be added to the declarations in the <wchar.h> header.

2

Lowercase letters may be added to the conversion specifiers and length modifiers in fwprintf and fwscanf. Other characters may be used in extensions.

Wide character classification and mapping utilities <wctype.h>

1 Function names that begin with is or to and a lowercase letter may be added to the declarations in the <wctype.h> header.