--- /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 <time.h> 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 <time.h>
+#include <stdio.h>
+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 <time.h>
+#include <stdio.h>
+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 <time.h>
+#include <unistd.h>
+#include <stdio.h>
+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 <string.h>
+#include <stdio.h>
+#include <time.h>
+#include <locale.h>
+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 <time.h>
+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 <time.h>
+#include <stdio.h>
+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 <sys/time.h> 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 <time.h>
+#include <stdio.h>
+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 <stdio.h>
+#include <time.h>
+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 <string.h>
+#include <stdio.h>
+#include <time.h>
+#include <locale.h>
+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 <time.h>
+#include <stdio.h>
+#include <signal.h>
+#include <pthread.h>
+#include <unistd.h>
+
+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
+*/