time : Index | Toc |
Time requests | |
TAllocTimeRequest | Allocate a time request |
TFreeTimeRequest | Free a time request |
Time queries | |
TQueryTime | Query system time |
TGetDate | Query system date (and timezone) |
Waiting | |
TDelay | Wait an amount of time |
TWaitTime | Wait an amount of time, with signals |
TWaitDate | Wait for an explicit date, with signals |
Utilities | |
TSubTime | Subtract one time from another |
TAddTime | Add a time to another |
TCmpTime | Compare times |
TIsLeapYear | Check if year is a leap year |
TIsValidDate | Check if a day, month, year is a valid date |
Regular date | |
TPackDate | Pack a datebox structure to a date |
TUnpackDate | Unpack a date to a datebox structure |
TMakeDate | Initialize a date |
TAddDate | Add days and/or time to a date |
TSubDate | Substract days and/or a time from a date |
TDiffDate | Calculate days/time difference between dates |
Date conversion | |
TYDayToDM | Convert a year and yearday to a day and month |
TDMYToYDay | Convert day, month, year to a yearday |
TGetWeekDay | Get the weekday number of a day, month, year |
TGetWeekNumber | Get the week number of a day, month, year |
Julian date | |
TDateToJulian | Get a Julian day from a date |
TJulianToDate | Get a date from a Julian day |
TMYToJulian | Convert month, year to a Julian day |
TJulianToDMY | Convert a Julian day to day, month, year |
time : TSubTime | Toc |
TSubTime - Subtract time
TTimeSubTime(TTimeBase, a, b) TAPTR TTIME* TTIME* TSubTime(a, b) TTIME* TTIME*
Subtract time b from time a, leaving the result in time a.
a Pointer to a time structure to subtract from b Pointer to a time structure to be subtracted
time : TAddTime | Toc |
TAddTime - Add time
TTimeAddTime(TTimeBase, a, b) TAPTR TTIME* TTIME* TAddTime(a, b) TTIME* TTIME*
Add time b to time a, leaving the result in time a.
a Pointer to a time structure to add to b Pointer to a time structure to be added
time : TCmpTime | Toc |
TCmpTime - Compare times
res = TTimeCmpTime(TTimeBase, a, b) TINT TAPTR TTIME* TTIME* res = TTimeCmp(a, b) TINT TTIME* TTIME*
Compare time a with time b. The result will be
1 if time a refers to a later point in time than time b -1 if time a refers to a earlier point in time than time b 0 if time a is equal to time b.
a Pointer to a time structure, first operand b Pointer to a time structure, second operand
res result of comparison, -1, 0 or 1
time : TAllocTimeRequest | Toc |
TAllocTimeRequest - allocate a time request
timereq = TTimeAllocTimeRequest(TTimeBase, tags) TAPTR TAPTR TTAGITEM* timereq = TAllocTimeRequest(tags) TAPTR TTAGITEM*
This function opens the timer.device and returns a pointer to a time request, which is readily initialized to be used by functions such as TWaitTime and TQueryTime.Each time request allocated by this function must be freed using TFreeTimeRequest.
tags Pointer to an array of tag items
None defined yet
timereq Pointer to a time request, or TNULL if the device open failed
- A single time request cannot be used by multiple tasks at the same time. If required, allocate one request per task.
time : TFreeTimeRequest | Toc |
TFreeTimeRequest - free a time request
TTimeFreeTimeRequest(TTimeBase, timereq) TAPTR TAPTR TFreeTimeRequest(timereq) TAPTR
This function frees a time request that was allocated with TAllocTimeRequest.
timereq Pointer to a time request
time : TQueryTime | Toc |
TQueryTime - Query relative system time
TTimeQueryTime(TTimeBase, timereq, timep) TAPTR TAPTR TTIME* TQueryTime(timereq, timep) TAPTR TTIME*
This function queries a (relative) system time and inserts it into the time structure being pointed to by timep. The time request is a timer.device instance and usually obtained with a call to TAllocTimeRequest.
timereq Pointer to a time request timep Pointer to a time structure to be filled
- It is important to note that a TEKlib TTIME is a relative entity. It might appear as if the fields filled in by this function could in some way reflect an absolute time or date, but this would be entirely misleading as the base for a TTIME structure can differ among different hosts. For getting an absolute date and time use the more expensive function TGetDate.
time : TGetDate | Toc |
TGetDate - Get absolute system time and date
error = TTimeGetDate(TTimeBase, timereq, datep, tzsecp) TINT TAPTR TAPTR TDATE* TINT* error = TGetDate(timereq, datep, tzsecp) TINT TAPTR TDATE* TINT*
This function queries the system's absolute time and date and inserts it into the structure being pointed to by datep, and optionally the number of seconds West of GMT into the variable being pointed to by tzsecp. The time request argument is a pointer to a timer.device instance, which is usually obtained with a call to TAllocTimeRequest.If tzsecp is TNULL then *datep will be set to the system's local time. If tzsecp points to a variable then *datep will be set to Universal Time (UT).
timereq Pointer to a time request datep Pointer to a date structure receiving the date tzsecp Pointer to an integer receiving the seconds west of GMT
error Error value, indicating -1 for invalid arguments 0 for success 1 for no date resource available 2 for no timezone information available
- The inner layout of the date structure is private and may differ among different hosts. Use functions like TUnpackDate to access it, and functions like TAddDate to perform calculations on it.
- For measuring a relative time it can be sufficient to use a TTIME structure, which is better accessible to applications and requires less complex internal calculations. See TQueryTime and TSubTime for details.
time : TWaitTime | Toc |
TWaitTime - Wait for signals with a relative timeout
signals = TTimeWaitTime(TTimeBase, timereq, timeout, sigmask) TUINT TAPTR TAPTR TTIME* TUINT signals = TWaitTime(timereq, timeout, sigmask) TUINT TAPTR TTIME* TUINT
Suspend the current task to wait for a set of signals or for a timeout. Any signals causing this function to return will be returned to the caller and cleared from the task's signal state. If a timeout causes the return then the return value is 0. If timeout is TNULL then this function is equivalent to exec:TWait.
timereq Pointer to a time request timeout Pointer to a TTIME structure sigmask Set of signals to wait for
signals Signals that caused returning, or 0 if a timeout occured
time : TWaitDate | Toc |
TWaitDate - Wait for signals, with an absolute timeout
signals = TTimeWaitDate(TTimeBase, timereq, datep, sigmask) TUINT TAPTR TAPTR TDATE* TUINT signals = TWaitDate(timereq, datep, sigmask) TUINT TAPTR TDATE* TUINT
Suspend the current task to wait for a set of signals or for an absolute date. Any signals causing this function to return will be returned to the caller and cleared from the task's signal state. If an expiring date causes the return then this function returns 0. If datep is TNULL then this function is equivalent to exec:TWait.
timereq Pointer to a time request absdate Pointer to a TDATE structure sigmask Set of signals to wait for
signals Signals that caused returning, or 0 if a timeout occured
- The absdate timeout is expected to be a system local date.
time : TDateToJulian | Toc |
TDateToJulian - Get a Julian day from a date
jd = TTimeDateToJulian(TTimeBase, date) TDOUBLE TAPTR TDATE* jd = TDateToJulian(date) TDOUBLE TDATE*
Calculate the Julian day from a date structure. The Julian date counts the days since January 1st 4713 B.C. A Julian day starts at 12h universal time (UT). A specific point in time is given as a day number and the time of the day as its fraction.The Julian date is often used for astronomical calculations.
date ptr to a TDATE structure
jd Julian day
- The Julian date conversion involves expensive calculations. Preferrably use functions like TMakeDate, TAddDate, TDiffDate, etc. for working with the TDATE type.
- The Julian date knows about the date reformations that took place in the Christian world in the year 1582. The 5th to 14th October 1582 never existed in this system, as they were eliminated in order to correct derivations from the astronomical year that accumulated over the previous centuries. Leap years were introduced to alleviate the problem.
time : TJulianToDate | Toc |
TJulianToDate - Get a date from a Julian day
TTimeJulianToDate(TTimeBase, julian, tdate) TAPTR TDOUBLE TDATE* TJulianToDate(julian, tdate) TDOUBLE TDATE*
Calculate a TDATE from a Julian day.
julian Julian day tdate Ptr to a TDATE structure
time : TIsLeapYear | Toc |
TIsLeapYear - Check if a year is a leap year
isleapyear = TTimeIsLeapYear(TTimeBase, year) TBOOL TAPTR TINT isleapyear = TIsLeapYear(year) TBOOL TINT
Check if year is a leap year.
year Year to check
isleapyear TTRUE if leap year, TFALSE otherweise
- Leap years were introduced in the Christian world in the year 1582. This is taken into account by this function. See also TDateToJulian for further details.
time : TIsValidDate | Toc |
TIsValidDate - Check if a date is valid
valid = TTimeIsValidDate(TTimeBase, day, month, year) TBOOL TAPTR TINT TINT TINT valid = TIsValidDate(day, month, year) TBOOL TINT TINT TINT
Check if the given combination from day, month, year is a valid date, e.g. 29, 2, 2003 would be an invalid date, and this function would return TFALSE.
day, month, year Date
valid Boolean
time : TMYToJulian | Toc |
TMYToJulian - Get a Julian day from a month and year
julian = TTimeMYToJulian(TTimeBase, month, year) TDOUBLE TAPTR TINT TINT julian = TMYToJulian(month, year) TDOUBLE TINT TINT
Calculate the Julian day from the given month and year.
month Month to convert year Year to convert
julian Julian day
To convert a full date to a Julian date, add the month's day number to the result:julian = TMYToJulian(month, year); julian += day;Or, to get from a year and year's day to a Julian day:julian = TMYToJulian(1, year); julian += yearday;
time : TJulianToDMY | Toc |
TJulianToDMY - Convert a Julian to day, month, year
dayfract = TTimeJulianToDMY(TTimeBase, julian, pday, pmonth, pyear) TDOUBLE TAPTR TDOUBLE TINT* TINT* TINT* dayfract = TJulianToDMY(julian, pday, pmonth, pyear) TDOUBLE TDOUBLE TINT* TINT* TINT*
Convert a Julian day to a combination of day, month, year. The remaining fraction of the day will be returned to the caller.
julian Julian day pday Pointer to an integer for day (may be TNULL) pmonth Pointer to an integer for month (may be TNULL) pyear Pointer to an integer for year (may be TNULL)
dayfract Remaining fraction of the day
- Multiply the resulting fraction of the day
etc.
- by 24 to get the number of hours,
- by 1440 to get the number of minutes,
- by 86400 to get the number of seconds,
- A more convenient way to decompose a Julian day can be the use of a combination of TJulianToDate and TUnpackDate.
time : TYDayToDM | Toc |
TYDayToDM - Convert a year and yearday to a day and month
TTimeYDayToDM(TTimeBase, yearday, year, pday, pmonth) TAPTR TINT TINT TINT* TINT* TYDayToDM(yearday, year, pday, pmonth) TINT TINT TINT* TINT*
Convert a year and yearday to a month's day and month of the given year.
yearday Daynumber in the respective year year The year pday Pointer to an integer receiving the day (may be TNULL) pmonth Pointer to an integer receiving the month (may be TNULL)
time : TDMYToYDay | Toc |
TDMYToYDay - Convert day, month, year to a yearday
yday = TTimeDMYToYDay(TTimeBase, day, month, year) TINT TAPTR TINT TINT TINT yday = TDMYToYDay(day, month, year) TINT TINT TINT TINT
Convert a date in the format day, month, year to yearday of the given year.
day, month, year Date
yday Day of the year
time : TUnpackDate | Toc |
TUnpackDate - Unpack a date to a datebox structure
TTimeUnpackDate(TTimeBase, tdate, datebox, fields) TAPTR TDATE* struct TDateBox* TUINT16 TUnpackDate(tdate, datebox, fields) TDATE* struct TDateBox* TUINT16
Convert a date to a datebox structure. At least the fields flagged in the fields argument will be inserted to the resulting datebox structure.Specific combinations of date fields may be sufficient for your purpose, like TDB_DAY|TDB_MONTH|TDB_YEAR or TDB_YDAY|TDB_YEAR|TDB_SEC. If you want to receive all fields, pass TDB_ALL in the fields argument. The fields actually being inserted by this function (which can be more than requested) will be flagged as correponding bits in datebox->tdb_Fields.
tdate pointer to a source date datebox pointer to a TDateBox structure to be filled in fields Fields to be inserted into the datebox structure Valid field flags:
Flag Description corresponds to TDB_YEAR year datebox->tdb_Year TDB_YDAY day of year datebox->tdb_YDay TDB_MONTH month of year datebox->tdb_Month TDB_WEEK week of year datebox->tdb_Week TDB_WDAY day of week datebox->tdb_WDay TDB_DAY day of month datebox->tdb_Day TDB_HOUR hour of day datebox->tdb_Hour TDB_MINUTE minute of hour datebox->tdb_Minute TDB_SEC second of minute datebox->tdb_Sec TDB_USEC 1/1000000th sec datebox->tdb_USec TDB_ALL all of the above all of the above
time : TPackDate | Toc |
TPackDate - Pack fields in a datebox structure to a date
success = TTimePackDate(TTimeBase, datebox, tdate) TBOOL TAPTR struct TDateBox* TDATE* success = TPackDate(datebox, tdate) TBOOL struct TDateBox* TDATE*
Convert a datebox structure to a date. All fields with a corresponding bit in datebox->tdb_Fields will be possibly taken into account. Fields required are TDB_YEAR and either TDB_MONTH, TDB_DAY or TDTB_YDAY. More fields like TDB_HOUR, TDB_MINUTE etc. will be incorporated to the resulting date as well, if they are present. If not enough relevant fields are provided then this function returns TFALSE.See TUnpackDate for a description of the flags in datebox->tdb_Fields.
datebox Pointer to a source datebox structure tdate Pointer to a destination TDATE
success TTRUE if conversion succeeded
- See TMakeDate for annotations regarding the precision of dates and times.
time : TGetWeekDay | Toc |
TGetWeekDay - Get weekday number from day, month, year
daynum = TTimeGetWeekDay(TTimeBase, day, month, year) TINT TAPTR TINT TINT TINT daynum = TGetWeekDay(day, month, year) TINT TINT TINT TINT
Get a weekday number from date. The number is defined as 0 (TDT_SUNDAY) to 6 (TDT_SATURDAY). See the defines in tek/mod/time.h.
day, month, year Date
daynum Week's day number (0...6)
- An alternative way to get to a weekday number would be the use of TUnpackDate and the field TDB_WDAY.
time : TGetWeekNumber | Toc |
TGetWeekNumber - Get week number in a year from a date
weeknum = TTimeGetWeekNumber(TTimeBase, day, month, year) TINT TAPTR TINT TINT TINT weeknum = TGetWeekNumber(day, month, year) TINT TINT TINT TINT
Calculate the week number from a date.
day, month, year Date
weeknum Year's week number
- It is possible that a day at the end of the year is in the first week of the following year. For example, the 29th December 2003 is in week 1 of the year 2004 already. Be prepared for this.
- An alternative way to get a week number may be the use of TUnpackDate and the field TDB_WEEK.
time : TMakeDate | Toc |
TMakeDate - Initialize a date structure with date and time
valid = TTimeMakeDate(TTimeBase, tdate, day, month, year, time) TBOOL TAPTR TDATE* TINT TINT TINT TTIME* valid = TMakeDate(tdate, day, month, year, time) TBOOL TDATE* TINT TINT TINT TTIME*
Initialize a date structure from a day, month, year, and optionally from a time structure. If day, month, year form an invalid date, this function return TFALSE.
tdate Date structure to be filled day, month, year Date time Pointer to a TTIME structure. May be TNULL.
valid Boolean. TTRUE if the date is valid
- When a time specification is incorporated into the resulting date, then it is not guaranteed to be taken into account with a precision higher than 1/1000th of a second.
time : TAddDate | Toc |
TAddDate - Add a number of days and a time to a date
TTimeAddDate(TTimeBase, date, ndays, time) TAPTR TDATE* TINT TTIME* TAddDate(date, ndays, time) TDATE* TINT TTIME*
Add a number of days and optionally a time to a date.
tdate Date structure ndays Number of days to add. Can be 0. time Pointer to a TTIME structure. Can be TNULL.
time : TSubDate | Toc |
TSubDate - Substract a number of days and a time from a date
TTimeSubDate(TTimeBase, date, ndays, time) TAPTR TDATE* TINT TTIME* TSubDate(date, ndays, time) TDATE* TINT TTIME*
Subtract a number of days and optionally a time from a date.
tdate Date structure ndays Number of days to subtract. Can be 0. time Pointer to a TTIME structure. Can be TNULL.
time : TDiffDate | Toc |
TDiffDate - Get the difference between dates
days = TTimeDiffDate(TTimeBase, date1, date2, timep) TINT TAPTR TDATE* TDATE* TTIME* days = TDiffDate(date1, date2, timep) TINT TDATE* TDATE* TTIME*
This function returns the difference in number of days between tdate1 and tdate2. The difference in time will be inserted, optionally, into the time structure being pointed to by timep.Note that if tdate1 is before tdate2 then the resulting number of days will be negative, but the time difference (in seconds and microseconds) will always be inserted as positive numbers.
tdate1, tdate2 Pointers to TDATE structures timep Pointer to a TTIME structure receiving a time difference, or TNULL
days Number of days difference
- See TMakeDate for annotations about the precision of dates and times.
time : TDelay | Toc |
TDelay - Suspend for some time
TTimeDelay(TTimeBase, timereq, timeout) TAPTR TAPTR TTIME* TDelay(timereq, timeout) TAPTR TTIME*
This function suspends the current task for the specified time. The time request is a timer.device instance and usually obtained with a call to TAllocTimeRequest.
timereq Pointer to a time request timeout Pointer to a TTIME structure containing the time to wait
time : ABOUT | Toc |
$Id: time.html,v 1.7 2005/09/07 01:19:38 tmueller Exp $
$Log: time.html,v $ Revision 1.7 2005/09/07 01:19:38 tmueller added inline function equivalents to synopsis Revision 1.2 2005/06/29 21:41:02 tmueller minor fixesRevision 1.1 2005/06/19 20:42:21 tmueller addedRevision 1.4 2004/01/21 14:31:59 tmueller Bugfixes and better wordingRevision 1.3 2003/12/19 18:15:01 tmueller Improved precision for notes on TAllocTimeRequest and TQueryTimeRevision 1.2 2003/12/14 01:40:48 tmueller Better wording, fixes, changes to TQueryTime, addition of TDelayRevision 1.1.1.1 2003/12/11 07:17:27 tmueller Krypton import
time : Table of contents |
- ABOUT
- Index
- TAddDate
- TAddTime
- TAllocTimeRequest
- TCmpTime
- TDMYToYDay
- TDateToJulian
- TDelay
- TDiffDate
- TFreeTimeRequest
- TGetDate
- TGetWeekDay
- TGetWeekNumber
- TIsLeapYear
- TIsValidDate
- TJulianToDMY
- TJulianToDate
- TMYToJulian
- TMakeDate
- TPackDate
- TQueryTime
- TSubDate
- TSubTime
- TUnpackDate
- TWaitDate
- TWaitTime
- TYDayToDM
Generated Wed Sep 7 02:18:02 2005 from time.doc