FCL/sf/os/ossrv: comparison genericopenlibs/openenvcore/include/time.dosc

equal deleted inserted replaced

--1:000000000000
+:e4d67989cc36
+/** @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
+*/