diff -r 000000000000 -r e4d67989cc36 genericopenlibs/openenvcore/include/time.dosc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/genericopenlibs/openenvcore/include/time.dosc Tue Feb 02 02:01:42 2010 +0200 @@ -0,0 +1,1153 @@ +/** @file ../include/time.h +@internalComponent +*/ + +/** @fn asctime(const struct tm *tm) +@param tm + +Refer to ctime() for the documentation +@see gettimeofday() +@see getenv() +@see time() +@see tzset() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn clock(void) +@return clock is just for build support and hence returns 0. + + + + + The clock function +determines the amount of processor time used since the invocation of the +calling process, measured in CLOCKS_PER_SEC s of a second. + + Note: the clock system call eventually calls Symbian OS call user::GetCpuTime(), + which is not supported from version 8.0b, hence this api is included for build + support only. + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn ctime(const time_t *clock) +@param clock + +Note: This description also covers the following functions - + difftime() asctime() localtime() gmtime() mktime() ctime_r() localtime_r() gmtime_r() asctime_r() + +@return Each of these functions returns the value described, NULL, or -1 in the case of mktime if an error was detected. + + The functions ctime, gmtime and localtime all take as an argument a time value representing the time +in seconds since the Epoch (00:00:00 UTC, January 1, 1970); see time + + The function localtime converts the time value pointed at by clock and returns a pointer to a " struct tm " (described below) which contains the broken down time information + for the value after adjusting for the current time zone (and any other factors + such as Daylight Saving Time). Time zone adjustments are performed as specified + by the TZ environment variable (see the tzset function). localtime uses tzset to initialize time conversion information + if tzset has not already been called by the process. + + After filling in the tm structure, localtime sets the tm_isdst's Nth element of tzname to a pointer to a ASCII string that is the time zone abbreviation to be +used with localtime's (return, value.); + + The function gmtime similarly converts the time value without any time zone adjustment + and returns a pointer to a tm structure (described below). + + The ctime function adjusts the time value for the current time zone, in + the same manner as localtime, and returns a pointer to a 26-character string of the form: Thu Nov 24 18:22:48 1986 +\\0 + + All the fields have constant width. + + The ctime_r function provides the same functionality as ctime except the caller must provide the output buffer buf to store the result, which must be at least 26 characters long. + + The localtime_r and gmtime_r functions provide the same functionality as localtime and gmtime respectively, except the caller must provide the output buffer result. + + The asctime function +converts the broken down time in the structure tm pointed at by *tm to the form +shown in the example above. + + The asctime_r function provides the same functionality as asctime except the caller provides the output buffer buf to store the result, which must be at least 26 characters long. + + The functions mktime converts the broken-down time in the structure pointed to by + tm into a time value with the same encoding as that of the values returned by + the time function (that is, seconds from the Epoch, UTC). The mktime function interprets the input structure according to the current + timezone setting (see tzset ). + + 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 their normal ranges and will be + normalized if needed. For example, October 40 is changed into November 9, a tm_hour of -1 means 1 hour before midnight, tm_mday of 0 means the day preceding the current month, and tm_mon of -2 means 2 months before January of tm_year. + + A positive or zero value for tm_isdst causes mktime to presume initially that summer time (for example, Daylight + Saving Time) is or is not in effect for the specified time.. A negative value + for tm_isdst causes the mktime function to attempt to define whether summer time is in effect + for the specified time. The tm_isdst and tm_gmtoff members are forced to zero by timegm. + + 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 their normal ranges: The final value of tm_mday is not set until tm_mon and tm_year are determined. + + The mktime function returns the specified calendar time. If the calendar + time cannot be represented, it returns -1. + + The difftime function +returns the difference between two calendar times, ( time1 - time0), expressed in seconds. + + External declarations as well as the tm structure definition are in the +@code + #include include file. The tm structure includes +@endcode + at least the following fields: + +@code + +int tm_sec; // seconds (0 - 60) +int tm_min; // minutes (0 - 59) +int tm_hour; // hours (0 - 23) +int tm_mday; // day of month (1 - 31) +int tm_mon; // month of year (0 - 11) +int tm_year; // year - 1900 +int tm_wday; // day of week (Sunday = 0) +int tm_yday; // day of year (0 - 365) +int tm_isdst; // is summer time in effect? +char *tm_zone; // abbreviation of timezone name +long tm_gmtoff; // offset from UTC in seconds + +@endcode + + The +field tm_isdst is non-zero if summer time is in effect. + + The field tm_gmtoff is the offset (in seconds) of the time represented from UTC, with positive +values indicating east of the Prime Meridian. + +Examples: +@code +//Example usage of asctime,localtime and gmtime: +#include +#include +int main(){ + time_t t; + struct tm *timeptr; + char* asc_time; + t = time (NULL); //Get current time in seconds from Epoc + //Fill tm struct w.r.t localtime using localtime + timeptr = localtime (&t;); + //Use this to convert it to a string indicating time w.r.t localtime + asc_time = asctime (timeptr); + printf ("Time from asctime w.r.t localtime : %s", asc_time); + //Fill tm struct w.r.t GMT using gmtime + timeptr = gmtime (&t;); + //Use this to convert it to a string indicating time w.r.t GMT + asc_time = asctime (timeptr); + printf ("Time from asctime w.r.t gmtime : %s", asc_time); + return 0; +} + +@endcode + Output +@code +Time from asctime w.r.t localtime : Thu Jun 22 10:42:27 2006 +Time from asctime w.r.t gmtime : Thu Jun 22 05:12:27 2006 + +@endcode +@code +//Example usage of ctime,mktime: +#include +#include +int main(){ + time_t t; + struct tm timeptr; + char* c_time; + //Fill the tm struct with values + timeptr.tm_year = 2001; + timeptr.tm_mon = 6; + timeptr.tm_mday = 4; + timeptr.tm_hour = 0; + timeptr.tm_min = 0; + timeptr.tm_sec = 1; + timeptr.tm_isdst = -1; + t = mktime (&timeptr;); //Call mktime to make time in seconds w.r.t epoc + //Convert this to a string indicating time using ctime + c_time = ctime (&t;); + printf ("Time from ctime : %s", c_time); + return 0; +} + +@endcode + Output +@code +Time from ctime : Thu Jan 1 05:29:59 1970 + +@endcode +@code +//Example usage of difftime: +#include +#include +#include +int main(){ + time_t t0,t1,t2; + //Set initial and final values + t0 = 10; + t1 = 20; + t2 = difftime (t1, t0); //Find the time difference using difftime + printf ("Result of difftime = %d", t2); + return 0; +} + +@endcode + Output +@code +Result of difftime = 10 + +@endcode +@see gettimeofday() +@see getenv() +@see time() +@see tzset() + + +Bugs: + + Except for difftime, mktime, and the _r variants of the other functions, +these functions leaves their result in an internal static object and return +a pointer to that object. +Subsequent calls to these +function will modify the same object. + +The C Standard provides no mechanism for a program to modify its current +local timezone setting, and the POSIX -standard method is not reentrant. +(However, thread-safe implementations are provided +in the POSIX threaded environment.) + +The tm_zone field of a returned tm +structure points to a static array of characters, +which will also be overwritten by any subsequent calls (as well as by +subsequent call to tzset ) + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn difftime(time_t time1, time_t time0) +@param time1 +@param time0 + +Refer to ctime() for the documentation +@see gettimeofday() +@see getenv() +@see time() +@see tzset() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn gmtime(const time_t *clock) +@param clock + +Refer to ctime() for the documentation +@see gettimeofday() +@see getenv() +@see time() +@see tzset() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn localtime(const time_t *clock) +@param clock + +Refer to ctime() for the documentation +@see gettimeofday() +@see getenv() +@see time() +@see tzset() + + +The localtime() is not guaranteed to be thread safe. + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn mktime(struct tm *tm) +@param tm + +Refer to ctime() for the documentation +@see gettimeofday() +@see getenv() +@see time() +@see tzset() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn strftime(char * s, size_t maxsize, const char * format, const struct tm * t) +@param s +@param maxsize +@param format +@param t + +The strftime function formats the information from t into the buffer s according to the string pointed to by format . +The format string consists of zero or more conversion specifications and +ordinary characters. +All ordinary characters are copied directly into the buffer. +A conversion specification consists of a percent sign "\%" +and one other character. + +No more than maxsize characters will be placed into the array. If the total number of resulting characters, including the terminating NULL character, is not more +than maxsize , strftime returns the number of characters in the array, not counting +the terminating NULL. Otherwise, zero is returned and the buffer contents are +indeterminate. + +@code +The conversion specifications are copied to the buffer after expansion as follows:- +%A is replaced by national representation of the full weekday name. +%a is replaced by national representation of the abbreviated weekday name. +%B is replaced by national representation of the full month name. +%b is replaced by national representation of the abbreviated month name. +%C is replaced by (year / 100) as decimal number; single digits are preceded by a zero. +%c is replaced by national representation of time and date. +%D is equivalent to "%m/%d/%y". +%d is replaced by the day of the month as a decimal number (01-31). +%E* %O* + POSIX locale extensions. The sequences %Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy are supposed to provide alternate representations. +Additionally %OB implemented to represent alternative months names (used standalone, without day mentioned). + +%e is replaced by the day of month as a decimal number (1-31); single digits are preceded by a blank. +%F is equivalent to "%Y-%m-%d". +%G is replaced by a year as a decimal number with century. This year is the one that contains the greater part of the week (Monday as the first day of the week). +%g is replaced by the same year as in "%G", but as a decimal number without century (00-99). +%H is replaced by the hour (24-hour clock) as a decimal number (00-23). +%h the same as %b. +%I is replaced by the hour (12-hour clock) as a decimal number (01-12). +%j is replaced by the day of the year as a decimal number (001-366). +%k is replaced by the hour (24-hour clock) as a decimal number (0-23); single digits are preceded by a blank. +%l is replaced by the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank. +%M is replaced by the minute as a decimal number (00-59). +%m is replaced by the month as a decimal number (01-12). +%n is replaced by a newline. +%O* the same as %E*. +%p is replaced by national representation of either "ante meridiem" or "post meridiem" as appropriate. +%R is equivalent to "%H:%M". +%r is equivalent to "%I:%M:%S %p". +%S is replaced by the second as a decimal number (00-60). +%s is replaced by the number of seconds since the Epoch, UTC (see mktime). +%T is equivalent to "%H:%M:%S". +%t is replaced by a tab. +%U is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number (00-53). +%u is replaced by the weekday (Monday as the first day of the week) as a decimal number (1-7). +%V is replaced by the week number of the year (Monday as the first day of the week) as a decimal number (01-53). If the week containing January 1 has four or more days in the new year, then it is week 1; otherwise it is the last week of the previous year, and the next week is week 1. +%v is equivalent to "%e-%b-%Y". +%W is replaced by the week number of the year (Monday as the first day of the week) as a decimal number (00-53). +%w is replaced by the weekday (Sunday as the first day of the week) as a decimal number (0-6). +%X is replaced by national representation of the time. +%x is replaced by national representation of the date. +%Y is replaced by the year with century as a decimal number. +%y is replaced by the year without century as a decimal number (00-99). +%Z is replaced by the time zone name. +%z is replaced by the time zone offset from UTC; a leading plus sign stands for east of UTC, a minus sign for west of UTC, hours and minutes follow with two digits each and no delimiter between them (common form for RFC 822 date headers). +%+ is replaced by national representation of the date and time (the format is similar to that produced by 'date( )' function ). +%-* GNU libc extension. Do not do any padding when performing numerical outputs. +%_* GNU libc extension. Explicitly specify space for padding. +%0* GNU libc extension. Explicitly specify zero for padding. +%% is replaced by ‘%’. +@endcode + +Examples: +@code +#include +#include +#include +#include +int main() +{ + struct tm tm; + char buf[255]; + char *locale; + locale = setlocale(LC_TIME,"en_GB.ISO-8859-1"); + if( locale != NULL) + { + strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm;); + printf("sec = %d min = %d hours = %d +Year = %d Month = %d day = %d +",\ + tm.tm_sec,tm.tm_min,tm.tm_hour,tm.tm_year,tm.tm_mon,tm.tm_mday); + strftime(buf, sizeof(buf), "%d %B %Y %H:%M:%S", &tm;); + puts(buf); + strptime("Mon","%a", &tm;); + strftime(buf, sizeof(buf), "%a", &tm;); + puts(buf); + } + else + printf("Failed to set locale +"); +} + +@endcode + Output +@code +sec = 1 min = 31 hours = 18 +Year = 101 Month = 10 day = 12 +12 November 2001 18:31:01 +Mon + +@endcode +@see printf() +@see ctime() +@see strptime() +@see wcsftime() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn time(time_t *p) +@param p +@return On success the value of time in seconds since the Epoch is returned. On error +(time_t)(-1) is returned and errno is set appropriately. + + The time function returns the value of time in seconds since 0 hours, 0 +minutes, 0 seconds, January 1, 1970, Coordinated Universal Time. If an error occurs, time returns the value ( time_t)(-1) . + + The return value is also stored in * p , +provided that p is non-null. + +Examples: +@code +/* + * Detailed description : sample usage of time system call + */ +#include +int main() +{ + time_t Time ; + if(time(&Time;) < 0 ) + { + printf("Time system call failed +") ; + return -1 ; + } + printf("Time value is %u +" , Time) ; + return 0 ; +} + +@endcode + Output +@code + +Time value is 1176916948 + +@endcode +@see gettimeofday() +@see ctime() + + +Bugs: + + Neither -isoC-99 nor -p1003.1-2001 requires time to set errno on failure; thus, it is impossible for an application to distinguish +the valid time value -1 (representing the last UTC second of 1969) +from the error return value. + +Systems conforming to earlier versions of the C and POSIX standards (including older versions of ) +did not set * p in the error case. + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn tzset(void) + + The tzset function +initializes time conversion information used by the library routine localtime . +The environment variable TZ specifies how this is done. + + If TZ does not appear in the environment, the best available approximation + to local wall clock time is used. + + If TZ appears in the environment but its value is a null string, Coordinated +Universal Time ( UTC ) +is used (without leap second correction). + + + +Examples: +@code +#include +#include +int main(){ + time_t t; + char* c_time; + tzset(); //Call tzset + c_time = ctime (&t;); //Get time-string using ctime for Epoc time + printf ("Time from ctime after tzset: %s", c_time); + return 0; +} + +@endcode + Output +@code +Time from ctime after tzset: Sun Apr 7 02:24:08 1974 + +@endcode +@see gettimeofday() +@see ctime() +@see getenv() +@see time() + + +@see gettimeofday() +@see ctime() +@see getenv() +@see time() +@see gettimeofday() +@see ctime() +@see getenv() +@see time() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn clock_getres(clockid_t clock_id, struct timespec *res) +@param clock_id +@param res + +Refer to clock_gettime() for the documentation +@see adjtime() +@see ctime() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn clock_gettime(clockid_t clock_id, struct timespec *tp) +@param clock_id +@param tp + +Note: This description also covers the following functions - + clock_settime() clock_getres() clock_getcpuclockid() + +@return All the above APIs return 0 on success and -1 on failure. + +@code + #include < sys/time.h > as: +@endcode + The clock_gettime and clock_settime allow the calling process to retrieve or set the value used by a clock +which is specified by clock_id. + + The clock_id argument can be one of four values: CLOCK_REALTIME for time + that increments as a wall clock should, CLOCK_MONOTONIC which increments in + SI seconds, CLOCK_VIRTUAL for time that increments only when the CPU is running + in user mode on behalf of the calling process, or CLOCK_PROF for time that increments + when the CPU is running in user or kernel mode. + + As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME + is supported for all the clock-based APIs. + + The structure pointed to by tp is defined in +@code + #include as: +@endcode + +@code +struct timespec { +time_ttv_sec;/* seconds */ +longtv_nsec;/* and nanoseconds */ +}; +@endcode + + The resolution (granularity) of a clock is returned by the clock_getres system call. +This value is placed in a (non-NULL) *tp. + + The clock_getcpuclockid system call returns ( in *clock_id ) the clock ID of the CPU-time clock of the process specified + by pid. If pid is zero, the clock ID of the CPU-time clock of the process making + the call is returned. + +Examples: +@code +#include +#include +int clock_user() +{ + struct timespec tp; + int retval; + clockid_t clockid; + clock_getres (CLOCK_REALTIME, &tp;); // Call clock_getres + printf ("Real time-clock resolution is %d seconds and %d nanoseconds +", tp.tv_sec, tp.tv_nsec); + clock_getcpuclockid (0 ,&clockid;); // Call clock_getcpuclockid with pid = 0 + printf ("The clock id for the current process is %d +", clockid); + tp.tv_sec = 0; + tp.tv_nsec = 100; + retval = clock_settime (CLOCK_REALTIME, &tp;); // Call clock_settime with 100ns + printf ("clock_settime returned %d +", retval); + clock_gettime (CLOCK_REALTIME, &tp;); // Call clock_gettime to fill tp + printf ("Time from real time-clock is %d seconds and %d nanoseconds +", tp.tv_sec, tp.tv_nsec); + return 0; +} + +@endcode + Output +@code +Real time-clock resolution is 0 seconds and 1000000 nanoseconds +The clock id for the current process is 0 +clock_settime returned 0 +Time from real time-clock is 0 seconds and 70663000 nanoseconds + +@endcode +@see adjtime() +@see ctime() + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn clock_settime(clockid_t clock_id, const struct timespec *tp) +@param clock_id +@param tp + +Refer to clock_gettime() for the documentation + +@see adjtime() +@see ctime() + +@capability Deferred @ref User::SetUTCTime(const TTime &aUTCTime) + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn nanosleep(const struct timespec *req, struct timespec *rem) +@param req +@param rem +@return If the nanosleep system call returns because the requested time has elapsed, the value +returned will be zero. If rem is non- NULL, the timespec structure it references is updated to contain the +unslept amount (the request time minus the time actually slept). + + The nanosleep system call +causes the process to sleep for the specified time. +Currently only microsecond sleep resolution can be obtained. + + + +Examples: +@code +/* + * Detailed description: Sample usage of nanosleep system call. + */ +#include +#include +int main() +{ + struct timespec tim, tim2; + tim.tv_sec = 1; + tim.tv_nsec = 500; + if(nanosleep(&tim; , &tim2;) < 0 ) { + printf("Nano sleep system call failed +"); + return -1; + } + printf("Nano sleep successfull +"); + return 0; +} + +@endcode + Output +@code +Nano sleep successfull + +@endcode +@see sleep() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn clock_getcpuclockid(pid_t pid, clockid_t* clock_id) +@param pid +@param clock_id + +Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME + is supported for all the clock-based APIs. Any value for pid except "0" is considered as invalid + and for "0" the supported 'clock_id' i.e, CLOCK_REALTIME is returned. + +Refer to clock_gettime() for the documentation +@see adjtime() +@see ctime() + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn clock_nanosleep (clockid_t clock_id, int flags, + const struct timespec *rqtp, struct timespec *rmtp) +@param clock_id +@param flags +@param rqtp +@param rmtp + +For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/clock_nanosleep.html + +Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME + is supported for all the clock-based APIs. + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn asctime_r(const struct tm *tm, char *buf) +@param tm +@param buf + +Refer to ctime() for the documentation +@see gettimeofday() +@see getenv() +@see time() +@see tzset() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn ctime_r(const time_t *clock, char *buf) +@param clock +@param buf + +Refer to ctime() for the documentation +@see gettimeofday() +@see getenv() +@see time() +@see tzset() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn gmtime_r(const time_t *clock, struct tm *result) +@param clock +@param result + +Refer to ctime() for the documentation +@see gettimeofday() +@see getenv() +@see time() +@see tzset() + + + + +@publishedAll +@externallyDefinedApi +*/ + + +/** @fn localtime_r(const time_t *clock, struct tm *result) +@param clock +@param result + +Refer to ctime() for the documentation +@see gettimeofday() +@see getenv() +@see time() +@see tzset() + + + + +@publishedAll +@externallyDefinedApi +*/ + + +/** @fn strptime(const char * buf, const char * fmt, struct tm * tm) +@param buf +@param fmt +@param tm +@return Upon successful completion, strptime returns the pointer to the first character in buf that has not been required to satisfy the specified conversions in fmt . +It returns NULL if one of the conversions failed. + + The strptime function parses the string in the buffer buf according to the string pointed to by fmt , +and fills in the elements of the structure pointed to by tm . +The resulting values will be relative to the local time zone. +Thus, it can be considered the reverse operation of strftime . + + The fmt string consists of zero or more conversion specifications and +ordinary characters. +All ordinary characters are matched exactly with the buffer, where +white space in the fmt string will match any amount of white space +in the buffer. +All conversion specifications are identical to those described in strftime . + + Two-digit year values, including formats \%y and \%D , +are now interpreted as beginning at 1969 per POSIX requirements. +Years 69-00 are interpreted in the 20th century (1969-2000), years +01-68 in the 21st century (2001-2068). + + If the fmt string does not contain enough conversion specifications to completely +specify the resulting struct tm , +the unspecified members of tm are left untouched. +For example, if format is "\%H:\%M:\%S", +only tm_hour , tm_sec and tm_min will be modified. +If time relative to today is desired, initialize the tm structure with today's date before passing it to strptime . + +Examples: +@code +#include +#include +#include +#include +int main() +{ + struct tm tm; + char buf[255]; + char *locale; + locale = setlocale(LC_TIME,"en_GB.ISO-8859-1"); + if( locale != NULL) + { + strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm;); + printf("sec = %d min = %d hours = %d +Year = %d Month = %d day = %d +", + tm.tm_sec,tm.tm_min,tm.tm_hour,tm.tm_year,tm.tm_mon,tm.tm_mday); + strftime(buf, sizeof(buf), "%d %B %Y %H:%M:%S", &tm;); + puts(buf); + strptime("Mon","%a", &tm;); + strftime(buf, sizeof(buf), "%a", &tm;); + puts(buf); + } + else + printf("Failed to set locale"); +} + +@endcode + Output +@code +sec = 1 min = 31 hours = 18 +Year = 101 Month = 10 day = 12 +12 November 2001 18:31:01 +Mon + +@endcode +@see scanf() +@see strftime() + + +Bugs: + + Both the \%e and \%l format specifiers may incorrectly scan one too many digits +if the intended values comprise only a single digit +and that digit is followed immediately by another digit. +Both specifiers accept zero-padded values, +even though they are both defined as taking unpadded values. + +The \%p format specifier has no effect unless it is parsed after hour-related specifiers. +Specifying \%l without \%p will produce undefined results. +Note that 12AM +(ante meridiem) +is taken as midnight +and 12PM +(post meridiem) +is taken as noon. + +The \%U and \%W format specifiers accept any value within the range 00 to 53 +without validating against other values supplied (like month +or day of the year, for example). + +The \%Z format specifier only accepts time zone abbreviations of the local time zone, +or the value "GMT". +This limitation is because of ambiguity due to of the over loading of time +zone abbreviations. +One such example is EST which is both Eastern Standard Time and Eastern Australia Summer Time. + +The strptime function does not correctly handle multibyte characters in the fmt argument. + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn timer_create (clockid_t __clock_id, + struct sigevent *__restrict __evp, + timer_t *__restrict __timerid) +@param __clock_id +@param __evp +@param __timerid + +For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/timer_create.html + +Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME + is supported for all the clock-based APIs. + +@see timer_settime() +@see timer_delete() + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn timer_delete (timer_t __timerid) +@param __timerid + +For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/timer_delete.html + +@see timer_create() +@see timer_settime() + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn timer_settime(timer_t __timerid, int __flags, + const struct itimerspec *__restrict __value, + struct itimerspec *__restrict __ovalue) +@param __timerid +@param __flags +@param __value +@param __ovalue + +For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/timer_settime.html + +Note: This description also covers the timer_gettime() and timer_getoverrun() functions. + +Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME + is supported for all the clock-based APIs. At the user level, Symbian OS supports upto a + maximum of 1 ms resolution timer (RTimer::HighRes ()) upon which the timer emulation solution is based. + As the re-registrations for a periodic timer happen in the user mode, the timer expirations + might show up a possible unspecified latency. + +Examples: +@code +/* + * Detailed description: + */ +#include +#include +#include +#include +#include + +void sighler (union sigval val) + { + printf("In the handler with val:%d\n", val.sival_int); + } + +int main() + { + timer_t timerid; + struct sigevent sig; + + pthread_attr_t attr; + pthread_attr_init( &attr ); + + sig.sigev_notify = SIGEV_THREAD; + sig.sigev_notify_function = sighler; + sig.sigev_value.sival_int =20; + sig.sigev_notify_attributes = &attr; + + if(0 == timer_create(CLOCK_REALTIME, &sig, &timerid)) + { + struct itimerspec in, out; + + in.it_value.tv_sec = 1; + in.it_value.tv_nsec = 0; + + in.it_interval.tv_sec = 0; + in.it_interval.tv_nsec = 0; + + if(0 == timer_settime(timerid, 0, &in, &out)) + { + sleep(3); //wait for the timer expirations... + } + else + { + printf("timer_settime () failed with err:%d\n", errno); + } + + timer_delete(timerid); + } + else + { + printf("timer_create () failed with err:%d\n", errno); + } + + return 0; + } + +@endcode + Output +@code +In the handler with val:20 + +@endcode +@see timer_create() +@see timer_delete() +@see clock_gettime() + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn timer_gettime (timer_t __timerid, struct itimerspec *__value) +@param __timerid +@param __value + +For documentation refer to timer_settime(). + +@see timer_create() +@see timer_delete() + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn timer_getoverrun (timer_t __timerid) +@param __timerid + +For documentation refer to timer_settime(). + +@see timer_create() +@see timer_delete() + +@publishedAll +@externallyDefinedApi +*/ + +/** @def CLOCK_REALTIME + +This clock represents the realtime clock for the system. + +@publishedAll +@externallyDefinedApi +*/ + +/** @def CLOCK_VIRTUAL + +This clock represents the amount of time (in seconds and nanoseconds) that the calling process has spent executing code in the user's context. It is a per-process clock. It cannot be set by the user. + +@publishedAll +@externallyDefinedApi +*/ + +/** @def TIMER_ABSTIME + +absolute timer + +@publishedAll +@externallyDefinedApi +*/ + +/** @struct tm + +Contains the following members, + +@publishedAll +@externallyDefinedApi +*/ + +/** @var tm::tm_sec +seconds after the minute +*/ + +/** @var tm::tm_min +minutes after the hour +*/ + +/** @var tm::tm_hour +hours since midnight +*/ + +/** @var tm::tm_mday +day of the month +*/ + +/** @var tm::tm_mon +months since January +*/ + +/** @var tm::tm_year +years since 1900 +*/ + +/** @var tm::tm_wday +days since Sunday +*/ + +/** @var tm::tm_yday +days since January 1 +*/ + +/** @var tm::tm_isdst +Daylight Savings Time flag +*/ + +/** @var tm::tm_gmtoff +offset from UTC in seconds +*/ + +/** @var tm::tm_zone +timezone abbreviation +*/ + + +/** @fn time_t timegm(struct tm *tmp) + +@param tmp + +Description: +This function is inverses for gmtime. +Converts struct tm to time_t, assuming the data in tm is UTC rather than local timezone. + +@see gmtime() +@see localtime() +@see mktime() +@see tzset() + +@publishedAll +@externallyDefinedApi +*/