/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

[11] Fix | Delete

#ifndef ISC_TIME_H

[12] Fix | Delete

#define ISC_TIME_H 1

[13] Fix | Delete

[14] Fix | Delete

/*! \file */

[15] Fix | Delete

[16] Fix | Delete

#include <inttypes.h>

[17] Fix | Delete

#include <stdbool.h>

[18] Fix | Delete

[19] Fix | Delete

#include <isc/lang.h>

[20] Fix | Delete

#include <isc/types.h>

[21] Fix | Delete

[22] Fix | Delete

/***

[23] Fix | Delete

*** Intervals

[24] Fix | Delete

***/

[25] Fix | Delete

[26] Fix | Delete

/*!

[27] Fix | Delete

* \brief

[28] Fix | Delete

* The contents of this structure are private, and MUST NOT be accessed

[29] Fix | Delete

* directly by callers.

[30] Fix | Delete

*

[31] Fix | Delete

* The contents are exposed only to allow callers to avoid dynamic allocation.

[32] Fix | Delete

*/

[33] Fix | Delete

struct isc_interval {

[34] Fix | Delete

unsigned int seconds;

[35] Fix | Delete

unsigned int nanoseconds;

[36] Fix | Delete

};

[37] Fix | Delete

[38] Fix | Delete

extern const isc_interval_t * const isc_interval_zero;

[39] Fix | Delete

[40] Fix | Delete

/*

[41] Fix | Delete

* ISC_FORMATHTTPTIMESTAMP_SIZE needs to be 30 in C locale and potentially

[42] Fix | Delete

* more for other locales to handle longer national abbreviations when

[43] Fix | Delete

* expanding strftime's %a and %b.

[44] Fix | Delete

*/

[45] Fix | Delete

#define ISC_FORMATHTTPTIMESTAMP_SIZE 50

[46] Fix | Delete

[47] Fix | Delete

ISC_LANG_BEGINDECLS

[48] Fix | Delete

[49] Fix | Delete

void

[50] Fix | Delete

isc_interval_set(isc_interval_t *i,

[51] Fix | Delete

unsigned int seconds, unsigned int nanoseconds);

[52] Fix | Delete

/*%<

[53] Fix | Delete

* Set 'i' to a value representing an interval of 'seconds' seconds and

[54] Fix | Delete

* 'nanoseconds' nanoseconds, suitable for use in isc_time_add() and

[55] Fix | Delete

* isc_time_subtract().

[56] Fix | Delete

*

[57] Fix | Delete

* Requires:

[58] Fix | Delete

*

[59] Fix | Delete

*\li 't' is a valid pointer.

[60] Fix | Delete

*\li nanoseconds < 1000000000.

[61] Fix | Delete

*/

[62] Fix | Delete

[63] Fix | Delete

bool

[64] Fix | Delete

isc_interval_iszero(const isc_interval_t *i);

[65] Fix | Delete

/*%<

[66] Fix | Delete

* Returns true iff. 'i' is the zero interval.

[67] Fix | Delete

*

[68] Fix | Delete

* Requires:

[69] Fix | Delete

*

[70] Fix | Delete

*\li 'i' is a valid pointer.

[71] Fix | Delete

*/

[72] Fix | Delete

[73] Fix | Delete

/***

[74] Fix | Delete

*** Absolute Times

[75] Fix | Delete

***/

[76] Fix | Delete

[77] Fix | Delete

/*%

[78] Fix | Delete

* The contents of this structure are private, and MUST NOT be accessed

[79] Fix | Delete

* directly by callers.

[80] Fix | Delete

*

[81] Fix | Delete

* The contents are exposed only to allow callers to avoid dynamic allocation.

[82] Fix | Delete

*/

[83] Fix | Delete

[84] Fix | Delete

struct isc_time {

[85] Fix | Delete

unsigned int seconds;

[86] Fix | Delete

unsigned int nanoseconds;

[87] Fix | Delete

};

[88] Fix | Delete

[89] Fix | Delete

extern const isc_time_t * const isc_time_epoch;

[90] Fix | Delete

[91] Fix | Delete

void

[92] Fix | Delete

isc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds);

[93] Fix | Delete

/*%<

[94] Fix | Delete

* Set 't' to a value which represents the given number of seconds and

[95] Fix | Delete

* nanoseconds since 00:00:00 January 1, 1970, UTC.

[96] Fix | Delete

*

[97] Fix | Delete

* Notes:

[98] Fix | Delete

*\li The Unix version of this call is equivalent to:

[99] Fix | Delete

*\code

[100] Fix | Delete

* isc_time_settoepoch(t);

[101] Fix | Delete

* isc_interval_set(i, seconds, nanoseconds);

[102] Fix | Delete

* isc_time_add(t, i, t);

[103] Fix | Delete

*\endcode

[104] Fix | Delete

*

[105] Fix | Delete

* Requires:

[106] Fix | Delete

*\li 't' is a valid pointer.

[107] Fix | Delete

*\li nanoseconds < 1000000000.

[108] Fix | Delete

*/

[109] Fix | Delete

[110] Fix | Delete

void

[111] Fix | Delete

isc_time_settoepoch(isc_time_t *t);

[112] Fix | Delete

/*%<

[113] Fix | Delete

* Set 't' to the time of the epoch.

[114] Fix | Delete

*

[115] Fix | Delete

* Notes:

[116] Fix | Delete

*\li The date of the epoch is platform-dependent.

[117] Fix | Delete

*

[118] Fix | Delete

* Requires:

[119] Fix | Delete

*

[120] Fix | Delete

*\li 't' is a valid pointer.

[121] Fix | Delete

*/

[122] Fix | Delete

[123] Fix | Delete

bool

[124] Fix | Delete

isc_time_isepoch(const isc_time_t *t);

[125] Fix | Delete

/*%<

[126] Fix | Delete

* Returns true iff. 't' is the epoch ("time zero").

[127] Fix | Delete

*

[128] Fix | Delete

* Requires:

[129] Fix | Delete

*

[130] Fix | Delete

*\li 't' is a valid pointer.

[131] Fix | Delete

*/

[132] Fix | Delete

[133] Fix | Delete

#ifdef CLOCK_BOOTTIME

[134] Fix | Delete

isc_result_t

[135] Fix | Delete

isc_time_boottime(isc_time_t *t);

[136] Fix | Delete

/*%<

[137] Fix | Delete

* Set 't' to monotonic time from previous boot

[138] Fix | Delete

* it's not affected by system time change. It also

[139] Fix | Delete

* includes the time system was suspended

[140] Fix | Delete

*

[141] Fix | Delete

* Requires:

[142] Fix | Delete

*\li 't' is a valid pointer.

[143] Fix | Delete

*

[144] Fix | Delete

* Returns:

[145] Fix | Delete

*

[146] Fix | Delete

*\li Success

[147] Fix | Delete

*\li Unexpected error

[148] Fix | Delete

* Getting the time from the system failed.

[149] Fix | Delete

*/

[150] Fix | Delete

#endif /* CLOCK_BOOTTIME */

[151] Fix | Delete

[152] Fix | Delete

[153] Fix | Delete

isc_result_t

[154] Fix | Delete

isc_time_now(isc_time_t *t);

[155] Fix | Delete

/*%<

[156] Fix | Delete

* Set 't' to the current absolute time.

[157] Fix | Delete

*

[158] Fix | Delete

* Requires:

[159] Fix | Delete

*

[160] Fix | Delete

*\li 't' is a valid pointer.

[161] Fix | Delete

*

[162] Fix | Delete

* Returns:

[163] Fix | Delete

*

[164] Fix | Delete

*\li Success

[165] Fix | Delete

*\li Unexpected error

[166] Fix | Delete

* Getting the time from the system failed.

[167] Fix | Delete

*\li Out of range

[168] Fix | Delete

* The time from the system is too large to be represented

[169] Fix | Delete

* in the current definition of isc_time_t.

[170] Fix | Delete

*/

[171] Fix | Delete

[172] Fix | Delete

isc_result_t

[173] Fix | Delete

isc_time_nowplusinterval(isc_time_t *t, const isc_interval_t *i);

[174] Fix | Delete

/*%<

[175] Fix | Delete

* Set *t to the current absolute time + i.

[176] Fix | Delete

*

[177] Fix | Delete

* Note:

[178] Fix | Delete

*\li This call is equivalent to:

[179] Fix | Delete

*

[180] Fix | Delete

*\code

[181] Fix | Delete

* isc_time_now(t);

[182] Fix | Delete

* isc_time_add(t, i, t);

[183] Fix | Delete

*\endcode

[184] Fix | Delete

*

[185] Fix | Delete

* Requires:

[186] Fix | Delete

*

[187] Fix | Delete

*\li 't' and 'i' are valid pointers.

[188] Fix | Delete

*

[189] Fix | Delete

* Returns:

[190] Fix | Delete

*

[191] Fix | Delete

*\li Success

[192] Fix | Delete

*\li Unexpected error

[193] Fix | Delete

* Getting the time from the system failed.

[194] Fix | Delete

*\li Out of range

[195] Fix | Delete

* The interval added to the time from the system is too large to

[196] Fix | Delete

* be represented in the current definition of isc_time_t.

[197] Fix | Delete

*/

[198] Fix | Delete

[199] Fix | Delete

int

[200] Fix | Delete

isc_time_compare(const isc_time_t *t1, const isc_time_t *t2);

[201] Fix | Delete

/*%<

[202] Fix | Delete

* Compare the times referenced by 't1' and 't2'

[203] Fix | Delete

*

[204] Fix | Delete

* Requires:

[205] Fix | Delete

*

[206] Fix | Delete

*\li 't1' and 't2' are valid pointers.

[207] Fix | Delete

*

[208] Fix | Delete

* Returns:

[209] Fix | Delete

*

[210] Fix | Delete

*\li -1 t1 < t2 (comparing times, not pointers)

[211] Fix | Delete

*\li 0 t1 = t2

[212] Fix | Delete

*\li 1 t1 > t2

[213] Fix | Delete

*/

[214] Fix | Delete

[215] Fix | Delete

isc_result_t

[216] Fix | Delete

isc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result);

[217] Fix | Delete

/*%<

[218] Fix | Delete

* Add 'i' to 't', storing the result in 'result'.

[219] Fix | Delete

*

[220] Fix | Delete

* Requires:

[221] Fix | Delete

*

[222] Fix | Delete

*\li 't', 'i', and 'result' are valid pointers.

[223] Fix | Delete

*

[224] Fix | Delete

* Returns:

[225] Fix | Delete

*\li Success

[226] Fix | Delete

*\li Out of range

[227] Fix | Delete

* The interval added to the time is too large to

[228] Fix | Delete

* be represented in the current definition of isc_time_t.

[229] Fix | Delete

*/

[230] Fix | Delete

[231] Fix | Delete

isc_result_t

[232] Fix | Delete

isc_time_subtract(const isc_time_t *t, const isc_interval_t *i,

[233] Fix | Delete

isc_time_t *result);

[234] Fix | Delete

/*%<

[235] Fix | Delete

* Subtract 'i' from 't', storing the result in 'result'.

[236] Fix | Delete

*

[237] Fix | Delete

* Requires:

[238] Fix | Delete

*

[239] Fix | Delete

*\li 't', 'i', and 'result' are valid pointers.

[240] Fix | Delete

*

[241] Fix | Delete

* Returns:

[242] Fix | Delete

*\li Success

[243] Fix | Delete

*\li Out of range

[244] Fix | Delete

* The interval is larger than the time since the epoch.

[245] Fix | Delete

*/

[246] Fix | Delete

[247] Fix | Delete

uint64_t

[248] Fix | Delete

isc_time_microdiff(const isc_time_t *t1, const isc_time_t *t2);

[249] Fix | Delete

/*%<

[250] Fix | Delete

* Find the difference in microseconds between time t1 and time t2.

[251] Fix | Delete

* t2 is the subtrahend of t1; ie, difference = t1 - t2.

[252] Fix | Delete

*

[253] Fix | Delete

* Requires:

[254] Fix | Delete

*

[255] Fix | Delete

*\li 't1' and 't2' are valid pointers.

[256] Fix | Delete

*

[257] Fix | Delete

* Returns:

[258] Fix | Delete

*\li The difference of t1 - t2, or 0 if t1 <= t2.

[259] Fix | Delete

*/

[260] Fix | Delete

[261] Fix | Delete

uint32_t

[262] Fix | Delete

isc_time_seconds(const isc_time_t *t);

[263] Fix | Delete

/*%<

[264] Fix | Delete

* Return the number of seconds since the epoch stored in a time structure.

[265] Fix | Delete

*

[266] Fix | Delete

* Requires:

[267] Fix | Delete

*

[268] Fix | Delete

*\li 't' is a valid pointer.

[269] Fix | Delete

*/

[270] Fix | Delete

[271] Fix | Delete

isc_result_t

[272] Fix | Delete

isc_time_secondsastimet(const isc_time_t *t, time_t *secondsp);

[273] Fix | Delete

/*%<

[274] Fix | Delete

* Ensure the number of seconds in an isc_time_t is representable by a time_t.

[275] Fix | Delete

*

[276] Fix | Delete

* Notes:

[277] Fix | Delete

*\li The number of seconds stored in an isc_time_t might be larger

[278] Fix | Delete

* than the number of seconds a time_t is able to handle. Since

[279] Fix | Delete

* time_t is mostly opaque according to the ANSI/ISO standard

[280] Fix | Delete

* (essentially, all you can be sure of is that it is an arithmetic type,

[281] Fix | Delete

* not even necessarily integral), it can be tricky to ensure that

[282] Fix | Delete

* the isc_time_t is in the range a time_t can handle. Use this

[283] Fix | Delete

* function in place of isc_time_seconds() any time you need to set a

[284] Fix | Delete

* time_t from an isc_time_t.

[285] Fix | Delete

*

[286] Fix | Delete

* Requires:

[287] Fix | Delete

*\li 't' is a valid pointer.

[288] Fix | Delete

*

[289] Fix | Delete

* Returns:

[290] Fix | Delete

*\li Success

[291] Fix | Delete

*\li Out of range

[292] Fix | Delete

*/

[293] Fix | Delete

[294] Fix | Delete

uint32_t

[295] Fix | Delete

isc_time_nanoseconds(const isc_time_t *t);

[296] Fix | Delete

/*%<

[297] Fix | Delete

* Return the number of nanoseconds stored in a time structure.

[298] Fix | Delete

*

[299] Fix | Delete

* Notes:

[300] Fix | Delete

*\li This is the number of nanoseconds in excess of the number

[301] Fix | Delete

* of seconds since the epoch; it will always be less than one

[302] Fix | Delete

* full second.

[303] Fix | Delete

*

[304] Fix | Delete

* Requires:

[305] Fix | Delete

*\li 't' is a valid pointer.

[306] Fix | Delete

*

[307] Fix | Delete

* Ensures:

[308] Fix | Delete

*\li The returned value is less than 1*10^9.

[309] Fix | Delete

*/

[310] Fix | Delete

[311] Fix | Delete

void

[312] Fix | Delete

isc_time_formattimestamp(const isc_time_t *t, char *buf, unsigned int len);

[313] Fix | Delete

/*%<

[314] Fix | Delete

* Format the time 't' into the buffer 'buf' of length 'len',

[315] Fix | Delete

* using a format like "30-Aug-2000 04:06:47.997" and the local time zone.

[316] Fix | Delete

* If the text does not fit in the buffer, the result is indeterminate,

[317] Fix | Delete

* but is always guaranteed to be null terminated.

[318] Fix | Delete

*

[319] Fix | Delete

* Requires:

[320] Fix | Delete

*\li 'len' > 0

[321] Fix | Delete

*\li 'buf' points to an array of at least len chars

[322] Fix | Delete

*

[323] Fix | Delete

*/

[324] Fix | Delete

[325] Fix | Delete

void

[326] Fix | Delete

isc_time_formathttptimestamp(const isc_time_t *t, char *buf, unsigned int len);

[327] Fix | Delete

/*%<

[328] Fix | Delete

* Format the time 't' into the buffer 'buf' of length 'len',

[329] Fix | Delete

* using a format like "Mon, 30 Aug 2000 04:06:47 GMT"

[330] Fix | Delete

* If the text does not fit in the buffer, the result is indeterminate,

[331] Fix | Delete

* but is always guaranteed to be null terminated.

[332] Fix | Delete

*

[333] Fix | Delete

* Requires:

[334] Fix | Delete

*\li 'len' > 0

[335] Fix | Delete

*\li 'buf' points to an array of at least len chars

[336] Fix | Delete

*

[337] Fix | Delete

*/

[338] Fix | Delete

[339] Fix | Delete

isc_result_t

[340] Fix | Delete

isc_time_parsehttptimestamp(char *input, isc_time_t *t);

[341] Fix | Delete

/*%<

[342] Fix | Delete

* Parse the time in 'input' into the isc_time_t pointed to by 't',

[343] Fix | Delete

* expecting a format like "Mon, 30 Aug 2000 04:06:47 GMT"

[344] Fix | Delete

*

[345] Fix | Delete

* Requires:

[346] Fix | Delete

*\li 'buf' and 't' are not NULL.

[347] Fix | Delete

*/

[348] Fix | Delete

[349] Fix | Delete

void

[350] Fix | Delete

isc_time_formatISO8601(const isc_time_t *t, char *buf, unsigned int len);

[351] Fix | Delete

/*%<

[352] Fix | Delete

* Format the time 't' into the buffer 'buf' of length 'len',

[353] Fix | Delete

* using the ISO8601 format: "yyyy-mm-ddThh:mm:ssZ"

[354] Fix | Delete

* If the text does not fit in the buffer, the result is indeterminate,

[355] Fix | Delete

* but is always guaranteed to be null terminated.

[356] Fix | Delete

*

[357] Fix | Delete

* Requires:

[358] Fix | Delete

*\li 'len' > 0

[359] Fix | Delete

*\li 'buf' points to an array of at least len chars

[360] Fix | Delete

*

[361] Fix | Delete

*/

[362] Fix | Delete

[363] Fix | Delete

void

[364] Fix | Delete

isc_time_formatISO8601ms(const isc_time_t *t, char *buf, unsigned int len);

[365] Fix | Delete

/*%<

[366] Fix | Delete

* Format the time 't' into the buffer 'buf' of length 'len',

[367] Fix | Delete

* using the ISO8601 format: "yyyy-mm-ddThh:mm:ss.sssZ"

[368] Fix | Delete

* If the text does not fit in the buffer, the result is indeterminate,

[369] Fix | Delete

* but is always guaranteed to be null terminated.

[370] Fix | Delete

*

[371] Fix | Delete

* Requires:

[372] Fix | Delete

*\li 'len' > 0

[373] Fix | Delete

*\li 'buf' points to an array of at least len chars

[374] Fix | Delete

*

[375] Fix | Delete

*/

[376] Fix | Delete

[377] Fix | Delete

ISC_LANG_ENDDECLS

[378] Fix | Delete

[379] Fix | Delete

#endif /* ISC_TIME_H */

[380] Fix | Delete

[381] Fix | Delete